Disciplines · Decisions (ADRs)

ADR-0015: OSHUN Studio Typography System and Readability Governance

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

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