Disciplines · Decisions (ADRs)

ADR-0016: OSHUN Studio Color System and Token Governance

OSHUN Studio now has accepted IA (ADR-0013), visual identity (ADR-0014), and typography (ADR-0015) decisions.

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#

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