# ADR-0014: OSHUN Studio Design Language and Visual Identity 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 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.

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

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