Disciplines · Decisions (ADRs)

ADR-0020: OSHUN Studio Navigation and Command Surfaces

Studio now governs visual and interaction foundations, but users still traverse many advanced workflows across domains.

Accepted · 2026-02-23
10sections4 minread
Markdown source
On this page

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#

  • 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.
  • 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