# ADR-0018: OSHUN Studio Component Primitives and Composition Contracts

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

## 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`

## 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`