Disciplines · Decisions (ADRs)

ADR-0019: OSHUN Studio Complex Interaction Patterns and State Orchestration

Studio now governs IA, design language, typography, color, spacing, and component primitives.

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 IA, design language, typography, color, spacing, and component primitives. However, advanced workflows still rely on complex interactions: multi-step wizards, command stacks, parallel validation pipelines, drag/reorder operations, and long-running async orchestration.

Without an explicit decision for complex interaction patterns, Studio risks:

  • inconsistent async-state behavior across advanced workflows
  • brittle user recovery paths in failure and partial-completion states
  • accessibility regressions in high-density command surfaces
  • drift in interaction semantics across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian

Decision Drivers#

  • Interaction determinism: predictable state transitions for advanced flows.
  • Recovery ergonomics: robust retry, rollback, and resume behavior.
  • Accessibility safety: keyboard, focus, and screen-reader continuity through complex transitions.
  • Cross-domain consistency: shared interaction grammar for advanced Studio capabilities.
  • Operational governance: auditable release checks for high-risk patterns.

Considered Options#

Option 1: Domain-Specific Interaction Models#

Each domain defines its own advanced interaction patterns and state models.

Pros:

  • Local optimization for domain-specific tooling.

Cons:

  • High cognitive/context-switching costs.
  • Increased regressions and duplicated maintenance.

Option 2: Shared Base Components, Ungoverned Interaction Logic#

Use shared primitives while allowing ad hoc orchestration logic.

Pros:

  • Faster short-term implementation velocity.

Cons:

  • No enforceable guarantees for state and recovery semantics.
  • Harder incident triage across workflows.

Option 3: Unified Complex Interaction Pattern System with Governed State Orchestration (Chosen)#

Adopt a shared complex-interaction model with explicit state machines, recovery contracts, and auditable promotion gates.

Pros:

  • Deterministic user experience in high-risk workflows.
  • Stronger resilience under async failure conditions.
  • Better cross-domain maintainability and observability.

Cons:

  • Added design/engineering governance overhead.

Decision Outcome#

Chosen option: Option 3.

Complex-interaction requirements:

  1. Canonical orchestration states: idle -> pending -> success | error with optional resumable checkpoints.
  2. Recovery contract: every advanced flow defines retry, rollback, and degraded-mode behavior.
  3. Concurrency contract: parallel task groups have deterministic completion and cancellation semantics.
  4. Accessibility contract: complex transitions preserve focus context and interaction reachability.
  5. Release governance: draft -> validate -> approve -> publish with full telemetry/audit evidence.

Normative Rules#

State-Orchestration Contract#

  • Advanced Studio flows must declare explicit transition states and terminal outcomes.
  • Partial completion states must include deterministic user guidance.

Recovery Contract#

  • Every complex flow must support retry and reset actions.
  • High-impact failures must include rollback references or safe degraded mode.

Concurrency Contract#

  • Parallel tasks must expose aggregate status and per-task diagnostics.
  • Cancellation and timeout behavior must be deterministic and auditable.

Accessibility Contract#

  • Focus management must remain stable throughout async transitions.
  • Complex controls must be keyboard-operable and semantically announced.

Release Validity Contract#

A complex interaction release is valid only when all are true:

  • state-transition validations pass
  • recovery and timeout paths pass
  • accessibility checks pass
  • role-authorized approval exists
  • telemetry/audit records are complete
  • rollback or degraded-mode strategy is documented

Architecture Implications#

  • libs/oshun/ui and apps/oshun/web/src/design-system remain shared interaction implementation layers.
  • Studio complex-interaction governance flows are implemented under apps/oshun/web Studio routes.
  • Observability contracts remain centralized in libs/oshun/analytics.

Acceptance Criteria (OST-00049)#

OST-00049 is complete only when:

  1. ADR exists at docs/adr/ADR-0025-oshun-studio-complex-interaction-patterns-and-state-orchestration.md.
  2. ADR defines options, trade-offs, and selected strategy.
  3. ADR defines state-orchestration, recovery, concurrency, accessibility, and release-validity contracts.
  4. ADR aligns with ADR-0007 through ADR-0018.
  5. ADR aligns with docs/releases/v1/design/ux-principles.md, docs/releases/v1/design/ergonomics-requirements.md, and libs/oshun/ui.
  6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

Consequences#

Positive#

  • Predictable advanced workflow behavior across domains.
  • Lower incident severity through stronger recovery semantics.
  • Better operator trust in Studio orchestration controls.

Negative#

  • Increased governance and validation effort.
  • Higher up-front design rigor for interaction-state modeling.
  • 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

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/ui
  • apps/oshun/web/src/design-system/tokens.ts