Disciplines · Decisions (ADRs)

ADR-0014: OSHUN Studio Design Language and Visual Identity Governance

OSHUN Studio now has an accepted IA contract (ADR-0013) for exposing advanced cross-domain workflows, but Studio lacks a formal design-language governance decision for high-density production use cases.

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 an accepted IA contract (ADR-0013) for exposing advanced cross-domain workflows, but Studio lacks a formal design-language governance decision for high-density production use cases.

Without a studio-specific visual identity contract, teams risk:

  • fragmented visual patterns between domain capabilities
  • inconsistent readability in dense operational views
  • drift between token libraries and actual UI behavior
  • inaccessible color/typography/motion decisions in high-stakes workflows

Studio must support expert users building AAA games, films, and transmedia projects across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

Decision Drivers#

  • Capability clarity: advanced domain workflows must remain scannable under high information density.
  • Cross-domain cohesion: shared Studio grammar with domain-specific accents, not domain-specific UI silos.
  • Accessibility by default: contrast, typography, and motion must remain compliant in operational and degraded states.
  • Token source of truth: visual behavior must be traceable to design token contracts and auditable changes.
  • Operational ergonomics: decisions must optimize keyboard-first, review-heavy, and multi-hour production sessions.

Considered Options#

Option 1: Domain-Owned Visual Systems#

Each domain maintains its own visual identity and component grammar.

Pros:

  • Fast local iteration per domain.
  • Lower central governance overhead.

Cons:

  • Breaks one-studio mental model.
  • Increases user cognitive switching costs.
  • High risk of accessibility and token drift.

Option 2: Minimal Shared Theme Tokens Only#

Use shared color and typography tokens but no Studio-specific visual governance.

Pros:

  • Simpler rollout.
  • Lower short-term coordination effort.

Cons:

  • Incomplete control over interaction patterns and quality bars.
  • Weak guidance for dense, mission-critical workflows.

Option 3: Unified Studio Design Language with Visual Governance Flows (Chosen)#

Adopt a comprehensive Studio design language with governance workflows, role-based approvals, telemetry, and audit evidence.

Pros:

  • Consistent expert ergonomics across all domain capabilities.
  • Enforceable token-to-UI parity and accessibility standards.
  • Strong release governance for visual changes.

Cons:

  • Requires disciplined token and release management.
  • Higher up-front investment in governance flows.

Decision Outcome#

Chosen option: Option 3.

Studio will implement a governed design language that includes:

  1. Foundational token contract: color, typography, spacing, radii, motion, elevation, and focus indicators.
  2. Studio domain visual accents: Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian context accents over a shared shell grammar.
  3. Operational preview surfaces: typography/readability preview, contrast-status preview, motion/reduced-motion preview.
  4. Governed publication flow: draft -> review -> certification -> release.
  5. Policy and audit requirements: role-based publication controls, immutable audit events, and release evidence bundle.

Normative Rules#

Visual Identity Contract#

  • Shared shell grammar remains authoritative for layout, spacing, interaction, and status semantics.
  • Domain accents may signal context but must not replace shared semantic status colors.
  • Typography scale must preserve readability in dense data views and long-form narrative views.
  • Reduced-motion paths are mandatory and equivalent in functional clarity.

Release Governance Contract#

A visual release is valid only when all are true:

  • token bundle version created and immutable
  • contrast and accessibility checks pass
  • role-authorized approver signs off
  • telemetry and audit evidence attached
  • rollback artifact available

Scope Alignment#

This ADR applies to Studio surfaces in apps/oshun/web, including all cross-domain workflows mapped in ADR-0013.

Architecture Implications#

  • libs/oshun/design-tokens remains canonical source of shared tokens.
  • apps/oshun/web/src/design-system remains the web implementation layer.
  • Studio-specific visual governance flows are implemented in apps/oshun/web and must emit telemetry/audit events for publish actions.
  • Domain adapters must provide metadata required for domain accent rendering and identity labeling.

Acceptance Criteria (OST-00009)#

OST-00009 is complete only when:

  1. ADR exists at docs/adr/ADR-0020-oshun-studio-design-language-and-visual-identity.md.
  2. ADR defines explicit options and chosen strategy with trade-offs.
  3. ADR defines normative visual identity and governance rules.
  4. ADR aligns with ADR-0007 through ADR-0013, plus docs/releases/v1/design/brand-system.md, docs/releases/v1/design/ux-principles.md, and docs/releases/v1/design/motion-language.md.
  5. ADR names Studio production scope domains: Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.
  6. ADR defines objective release-validity conditions.

Consequences#

Positive#

  • Predictable expert UX across complex production workflows.
  • Better readability and reduced decision friction under high density.
  • Auditable release discipline for all visual changes.

Negative#

  • More governance steps before visual releases.
  • Requires cross-functional coordination between design, web, and platform.
  • 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

References#

  • 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
  • docs/domains/yemaya/service-catalog.md
  • docs/domains/isis/service-catalog.md
  • docs/domains/hathor/service-catalog.md
  • docs/domains/aja/service-catalog.md
  • docs/domains/bellona/service-catalog.md
  • libs/oshun/design-tokens/src/tokens.ts
  • apps/oshun/web/src/design-system/tokens.ts