# ADR-0020: OSHUN Studio Navigation and Command Surfaces

**Status**: Accepted  
**Date**: 2026-02-23  
**Authors**: OSHUN Studio Product Design, OSHUN Web Engineering  
**Reviewers**: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project
Obsidian Program Design

## Context and Problem Statement

Studio now governs visual and interaction foundations, but users still traverse
many advanced workflows across domains. Without explicit navigation and command
surface governance, command discoverability and route consistency can degrade in
high-complexity production contexts.

Unmanaged navigation/command surfaces cause:

- inconsistent global/local command behavior
- unclear back-stack and context restoration paths
- fragmented cross-domain navigation semantics
- elevated operator error risk in high-pressure workflows

## Decision Drivers

- **Command discoverability**: key actions must be reachable quickly.
- **Navigation determinism**: stable route, context, and back-stack behavior.
- **Cross-domain continuity**: one navigation grammar across all domains.
- **Accessibility reliability**: keyboard and screen-reader command parity.
- **Operational safety**: auditable command invocation and policy enforcement.

## Considered Options

### Option 1: Domain-Owned Navigation and Command Models

Each domain defines independent command palettes and navigation patterns.

**Pros**:

- Local autonomy.

**Cons**:

- Inconsistent user mental model and high switching cost.
- Weak shared governance for high-risk actions.

### Option 2: Shared Routes, Ungoverned Command Surfaces

Unify route contracts but allow ad hoc command surfaces.

**Pros**:

- Faster incremental implementation.

**Cons**:

- Inconsistent command semantics and weak policy guarantees.

### Option 3: Unified Navigation and Command Surface System with Governance (Chosen)

Adopt shared command-surface patterns with governed invocation policy, context
preservation, and auditable release controls.

**Pros**:

- Predictable navigation and command behavior across domains.
- Better operator efficiency and lower invocation errors.
- Strong governance and observability for critical actions.

**Cons**:

- Added governance overhead and stricter rollout discipline.

## Decision Outcome

**Chosen option**: Option 3.

Navigation/command requirements:

1. **Canonical route contracts** with context-preserving parameters.
2. **Unified command surfaces** for global/local actions with deterministic
   scopes.
3. **Policy-aware command execution** for sensitive actions.
4. **A11y command parity** for keyboard and assistive technologies.
5. **Release governance** with telemetry/audit and rollback readiness.

## Normative Rules

### Navigation Contract

- Governed Studio routes must preserve workspace context and back-stack state.
- Cross-domain transitions must expose deterministic return paths.

### Command Surface Contract

- Command actions must declare scope (`global`, `workspace`, `domain`).
- High-impact commands require explicit confirmation and policy checks.

### Accessibility Contract

- All commands must remain keyboard reachable and screen-reader interpretable.
- Command-surface focus management must be stable across open/close transitions.

### Release Validity Contract

A navigation/command release is valid only when all are true:

- route and context-preservation checks pass
- command-scope and policy checks pass
- accessibility checks pass
- role-authorized approval exists
- telemetry/audit records are complete
- rollback strategy is defined

## Architecture Implications

- Route contracts remain in `libs/oshun/navigation` and
  `apps/oshun/web/src/navigation`.
- Command surfaces are implemented in `apps/oshun/web` using shared UI and
  policy contracts.
- Navigation/command observability remains centralized in
  `libs/oshun/analytics`.

## Acceptance Criteria (OST-00057)

`OST-00057` is complete only when:

1. ADR exists at
   `docs/adr/ADR-0026-oshun-studio-navigation-and-command-surfaces.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines navigation, command-surface, accessibility, and release-validity
   contracts.
4. ADR aligns with `ADR-0007` through `ADR-0019`.
5. ADR aligns with `docs/releases/v1/design/ux-principles.md`,
   `docs/releases/v1/design/ergonomics-requirements.md`, and
   `libs/oshun/navigation`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Faster, safer command execution across domains.
- Improved navigation predictability in complex Studio workflows.
- Better governance and auditability for critical command usage.

### Negative

- Added implementation and governance complexity for command surfaces.
- Requires ongoing policy maintenance across domains.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0014-oshun-web-and-pwa-strategy.md`
- `docs/adr/ADR-0015-deep-linking-and-cross-domain-routing.md`
- `docs/adr/ADR-0016-shared-identity-and-cross-domain-session-model.md`
- `docs/adr/ADR-0017-offline-caching-and-sync-strategy.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0019-oshun-studio-information-architecture.md`
- `docs/adr/ADR-0020-oshun-studio-design-language-and-visual-identity.md`
- `docs/adr/ADR-0021-oshun-studio-typography-system.md`
- `docs/adr/ADR-0022-oshun-studio-color-system-and-token-governance.md`
- `docs/adr/ADR-0023-oshun-studio-spacing-and-layout-grid.md`
- `docs/adr/ADR-0024-oshun-studio-component-primitives-and-composition-contracts.md`
- `docs/adr/ADR-0025-oshun-studio-complex-interaction-patterns-and-state-orchestration.md`

## References

- `docs/releases/v1/design/ux-principles.md`
- `docs/releases/v1/design/ergonomics-requirements.md`
- `docs/domains/yemaya/features.md`
- `docs/domains/isis/features.md`
- `docs/domains/hathor/features.md`
- `docs/domains/aja/features.md`
- `docs/domains/bellona/features.md`
- `libs/oshun/navigation`
- `apps/oshun/web/src/navigation/routes.ts`