# ADR-0016: OSHUN Studio Color System and Token Governance

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

OSHUN Studio now has accepted IA (`ADR-0013`), visual identity (`ADR-0014`), and
typography (`ADR-0015`) decisions. A dedicated color-system decision is required
because Studio workloads rely heavily on color semantics for status, risk,
readiness, and cross-domain context.

Without explicit color governance, Studio risks:

- inconsistent semantic status signaling across domains
- domain accent overuse that harms usability and trust
- contrast regressions in high-density operational views
- drift between token definitions and runtime color usage

## Decision Drivers

- **Semantic clarity**: status colors must be deterministic and consistent.
- **Cross-domain cohesion**: domain accents should provide context, not override
  shared shell semantics.
- **Accessibility compliance**: color decisions must preserve AA contrast.
- **Token governance**: every color used in Studio should map to token
  contracts.
- **Operational safety**: critical states (error/warning/success/info) must
  remain immediately distinguishable.

## Considered Options

### Option 1: Domain-Owned Color Systems

Each domain controls its own color semantics and accents.

**Pros**:

- Local autonomy and domain expressiveness.

**Cons**:

- Inconsistent semantics and high cognitive switching cost.
- Elevated risk of accessibility drift.

### Option 2: Shared Base Palette, Ungoverned Runtime Usage

Provide shared tokens but allow unrestricted runtime color use.

**Pros**:

- Faster implementation.

**Cons**:

- No enforceable guarantees for semantic consistency.
- Drift between token definitions and UI usage.

### Option 3: Unified Studio Color System with Governed Release Flow (Chosen)

Use one Studio color model with semantic priority, domain accent constraints,
contrast validation, and auditable release governance.

**Pros**:

- Predictable status signaling across all domains.
- Enforceable accessibility and token parity.
- Controlled and auditable release path for color changes.

**Cons**:

- Requires governance overhead and stricter release process.

## Decision Outcome

**Chosen option**: Option 3.

Studio color-system requirements:

1. **Semantic-first model**: text/surface/accent/status semantics are primary.
2. **Domain accent constraints**: domain accents are contextual and secondary to
   semantic status colors.
3. **Contrast certification**: color bundles must pass contrast checks before
   production promotion.
4. **Token-only usage policy**: Studio color usage must map to approved tokens.
5. **Release governance**: draft -> validate -> approve -> publish with
   rollback.

## Normative Rules

### Semantic Priority Contract

- Semantic status colors (`success`, `warning`, `danger`, `info`) are
  authoritative for state communication.
- Domain accents must not replace semantic status colors in critical states.
- Surface and text contrast roles must remain stable across theme variants.

### Domain Accent Contract

- Domain accent application is limited to contextual indicators, non-critical
  highlights, and identity cues.
- Full-surface domain tints are prohibited for dense data and critical controls
  unless explicitly approved.

### Accessibility Contract

- Color changes must pass AA contrast for normal and large text contexts.
- High-contrast variants must preserve semantic meaning and legibility.

### Release Validity Contract

A color release is valid only when all are true:

- token schema and semantic mapping checks pass
- contrast validation checks pass
- role-authorized approval exists
- telemetry/audit records are complete
- rollback reference is present

## Architecture Implications

- `libs/oshun/design-tokens` remains canonical source for color primitives and
  semantics.
- `apps/oshun/web/src/design-system/tokens.ts` remains web-layer color
  implementation.
- Studio color governance workflows are implemented in `apps/oshun/web` and
  integrated with audit/telemetry.

## Acceptance Criteria (OST-00025)

`OST-00025` is complete only when:

1. ADR exists at
   `docs/adr/ADR-0022-oshun-studio-color-system-and-token-governance.md`.
2. ADR defines options, trade-offs, and chosen strategy.
3. ADR defines semantic priority, domain accent, accessibility, and release
   validity contracts.
4. ADR aligns with `ADR-0007` through `ADR-0015`.
5. ADR aligns with `docs/releases/v1/design/brand-system.md` and
   `libs/oshun/design-tokens/src/tokens.ts`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Consistent cross-domain state semantics.
- Lower risk of accessibility and color-drift regressions.
- Stronger operator trust in visual state communication.

### Negative

- Added governance and release ceremony for color changes.
- Requires strict adherence to tokenized usage.

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

## References

- `docs/releases/v1/design/brand-system.md`
- `docs/releases/v1/design/ux-principles.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/design-tokens/src/tokens.ts`
- `apps/oshun/web/src/design-system/tokens.ts`