Disciplines · Decisions (ADRs)

ADR-0018: OSHUN Studio Component Primitives and Composition Contracts

Studio now has accepted governance for IA (ADR-0013), design language (ADR-0014), typography (ADR-0015), color (ADR-0016), and spacing/layout (ADR-0017).

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

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

Context and Problem Statement#

Studio now has accepted governance for IA (ADR-0013), design language (ADR-0014), typography (ADR-0015), color (ADR-0016), and spacing/layout (ADR-0017). The next failure point is component-level drift: teams can still assemble controls, cards, command bars, and data surfaces with inconsistent state semantics and accessibility patterns.

Without explicit component-primitive governance, Studio risks:

  • inconsistent interaction states and affordances
  • divergence in keyboard/focus/assistive behavior across domains
  • repeated bespoke implementations for common primitives
  • regression-prone composition across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian

Decision Drivers#

  • Ergonomic consistency: shared interaction contracts across core controls.
  • Accessibility reliability: deterministic keyboard, focus, and semantics.
  • Composability: primitives that support advanced workflows without forked implementations.
  • Token alignment: primitives must consume approved type/color/spacing contracts.
  • Operational governance: component changes require auditable promotion.

Considered Options#

Option 1: Domain-Owned Component Libraries#

Each domain maintains its own primitive set.

Pros:

  • High local autonomy.

Cons:

  • Significant UX and accessibility drift.
  • Duplicate maintenance and testing cost.

Option 2: Shared Primitive Set Without Governance Workflow#

Provide common components but no release-policy enforcement.

Pros:

  • Faster initial adoption.

Cons:

  • Weak quality gates for critical regressions.
  • Inconsistent cross-domain composition semantics.

Option 3: Unified Studio Primitive System with Governed Composition Flows (Chosen)#

Adopt one canonical component-primitive system with role-gated release, policy/audit/telemetry requirements, and composition validity checks.

Pros:

  • Consistent, accessible interaction behavior across all domains.
  • Lower duplication and stronger runtime predictability.
  • Traceable promotion process for primitive changes.

Cons:

  • Added governance and rollout discipline for primitive evolution.

Decision Outcome#

Chosen option: Option 3.

Studio component-primitives requirements:

  1. Canonical primitive catalog: button, field, input, select, tabs, panel, table, toast, modal/sheet, and command primitives with documented states.
  2. Composition contracts: predictable assembly rules for dense workflows (list/detail, command bars, side panels, approval flows).
  3. A11y guarantees: focus order, keyboard interaction, labels, and state announcements are deterministic.
  4. Governed release flow: draft -> validate -> approve -> publish with rollback reference.
  5. Observability: component-governance flows emit telemetry and audit evidence.

Normative Rules#

Primitive Contract#

  • Governed Studio routes must compose UI from approved primitives.
  • Primitive variants and states (idle, loading, error, disabled, success) must be standardized.
  • New primitives require contract documentation before promotion.

Composition Contract#

  • Multi-panel and command-heavy surfaces must use approved layout/composition templates.
  • Ad hoc composition patterns are prohibited in governed Studio workflows without architecture approval.

Accessibility Contract#

  • Primitive interactions must support keyboard and screen-reader semantics.
  • Focus and aria patterns must remain stable across variants and themes.
  • Critical workflows must remain operable under reduced-motion and zoomed text settings.

Release Validity Contract#

A component-primitives release is valid only when all are true:

  • primitive/state contract checks pass
  • composition-policy checks pass
  • accessibility validation passes
  • role-authorized approval is recorded
  • telemetry/audit records are complete
  • rollback reference is defined

Architecture Implications#

  • libs/oshun/ui is the canonical component-primitives package for Studio surfaces.
  • apps/oshun/web/src/design-system remains the web implementation boundary for primitive composition and token wiring.
  • Studio component-governance workflows are implemented under apps/oshun/web Studio routes with policy and observability instrumentation.

Acceptance Criteria (OST-00041)#

OST-00041 is complete only when:

  1. ADR exists at docs/adr/ADR-0024-oshun-studio-component-primitives-and-composition-contracts.md.
  2. ADR defines options, trade-offs, and selected strategy.
  3. ADR defines primitive, composition, accessibility, and release-validity contracts.
  4. ADR aligns with ADR-0007 through ADR-0017.
  5. ADR aligns with docs/releases/v1/design/ux-principles.md, docs/releases/v1/design/ergonomics-requirements.md, libs/oshun/ui, and libs/oshun/design-tokens.
  6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

Consequences#

Positive#

  • Consistent interaction quality and accessibility across domains.
  • Lower maintenance through canonical primitive reuse.
  • Stronger release safety for component-level changes.

Negative#

  • Additional governance overhead for primitive updates.
  • Requires cross-domain coordination for contract evolution.
  • 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

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