# ADR-0015: OSHUN Studio Typography System and Readability 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 design language governance is now defined (`ADR-0014`), but
typography requires an explicit decision because Studio workloads combine
high-density operational dashboards, long-form narrative content, technical
logs, and review/approval evidence.

Typography drift across these surfaces can cause:

- reduced readability in dense production views
- hierarchy ambiguity in safety-critical operations
- inconsistent text scaling behavior under accessibility settings
- cross-domain UX fragmentation between Yemaya, Isis, Hathor, Aja, Bellona, and
  Project Obsidian

## Decision Drivers

- **Readability under density**: preserve scannability and comprehension in
  dashboard-heavy flows.
- **Hierarchy consistency**: enforce deterministic heading/body/metadata
  semantics.
- **Accessibility compliance**: meet AA contrast and dynamic text scaling
  expectations.
- **Token parity**: keep typography implementations tied to canonical token
  contracts.
- **Cross-domain continuity**: one Studio typographic grammar with domain-aware
  context cues.

## Considered Options

### Option 1: Domain-Specific Typography Systems

Each domain optimizes typography independently.

**Pros**:

- Local optimization per workload.
- Faster domain-specific iteration.

**Cons**:

- Breaks Studio coherence.
- Increases cognitive load during cross-domain workflows.
- Weakens accessibility governance consistency.

### Option 2: Minimal Shared Text Styles Only

Use a small shared type scale but no operational governance workflow.

**Pros**:

- Fast to implement.
- Lower governance overhead.

**Cons**:

- Insufficient for high-density production contexts.
- No objective release quality gates for readability regressions.

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

Adopt a single Studio typography system with role-gated publication, readability
validation, and auditable release evidence.

**Pros**:

- Consistent information hierarchy across all Studio surfaces.
- Strong accessibility and readability protections.
- Traceable token-to-UI typography releases.

**Cons**:

- Requires stricter governance and release process discipline.

## Decision Outcome

**Chosen option**: Option 3.

Studio typography system requirements:

1. **Tokenized scale**: canonical families, weights, sizes, and line-heights.
2. **Readability profiles**: dense operations, narrative review, and technical
   mono/data contexts.
3. **Dynamic scale support**: accessible scaling without clipping critical UI.
4. **Release governance**: draft -> validate -> approve -> publish workflow.
5. **Auditability**: every publish operation emits telemetry and audit evidence.

## Normative Rules

### Typographic Hierarchy Contract

- Each Studio screen must include one explicit L0 orientation anchor.
- L1/L2/L3 hierarchy must remain visually distinguishable in size/weight and
  contrast.
- Metadata text must never compete with primary decision text.

### Readability Contract

- Body defaults must align to `16px` baseline minimum on key operational
  surfaces.
- Long-form narrative and approval evidence views must use line lengths and
  line-height ranges aligned with readability standards.
- Mono styles are required for technical IDs, trace IDs, and diagnostics.

### Accessibility Contract

- Typography changes must preserve contrast compliance across theme variants.
- Reduced-motion and dynamic text settings must not hide critical actions.
- Large-text scaling must preserve action reachability and avoid horizontal
  scrolling for critical content.

### Release Validity Contract

A typography release is valid only when all are true:

- token schema and compatibility checks pass
- readability validation profile checks pass
- accessibility checks pass
- role-authorized approver signs off
- audit and telemetry records are complete
- rollback version is defined

## Architecture Implications

- `libs/oshun/design-tokens` remains the source of truth for type primitives.
- `apps/oshun/web/src/design-system/tokens.ts` remains the web-implementation
  layer for typography consumption.
- Studio typography governance workflows are implemented in `apps/oshun/web`
  under Studio routes.
- Typography release decisions are program-governed for Project Obsidian.

## Acceptance Criteria (OST-00017)

`OST-00017` is complete only when:

1. ADR is published at `docs/adr/ADR-0021-oshun-studio-typography-system.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines normative hierarchy, readability, accessibility, and release
   validity contracts.
4. ADR aligns with `ADR-0007` through `ADR-0014`.
5. ADR aligns with `docs/releases/v1/design/readability-standards.md` and
   `libs/oshun/design-tokens/src/tokens.ts`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Stable typographic experience across Studio workflows.
- Better readability and lower operator fatigue in dense views.
- Measurable and auditable typography release quality.

### Negative

- Additional governance overhead for typography changes.
- Requires cross-team coordination for type-scale updates.

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

## References

- `docs/releases/v1/design/readability-standards.md`
- `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`