Eve library

OSHUN Studio Typography Journeys and Edge Cases

Spec

Revision 1

On this page

Status: Active
Owner: OSHUN Studio Product Design + Web Engineering
Last Updated: 2026-02-23
Related:

  • docs/adr/ADR-0015-oshun-studio-typography-system.md
  • docs/releases/v1/specs/studio-typography-dependency-and-data-contract-map.md

Purpose#

Define primary journeys and edge-case behavior for typography system governance in OSHUN Studio.

This document is the execution artifact for OST-00019.

Personas#

  • Design System Lead
  • Accessibility Lead
  • Narrative UX Lead
  • Technical Director
  • Program Reviewer

Journey Principles#

  1. Typography changes must be reviewable and reversible.
  2. Readability checks must be explicit before promotion.
  3. Dense operations and long-form narrative contexts must both be validated.
  4. Every action must preserve programId, projectId, and workspaceId.

1. Primary Journeys#

J1. Typography Scale Draft and Publish#

Goal: Publish a new typography token bundle into preview.

Entry: Studio -> Typography -> Token Pipeline

Steps:

  1. Clone current typography bundle to draft.
  2. Adjust scale and line-height tokens.
  3. Run schema and compatibility validation.
  4. Publish to preview channel.
  5. Record telemetry/audit and rollback target.

Success State:

  • Immutable bundle version is published.
  • Preview surfaces render updated typography.

J2. Readability Profile Validation#

Goal: Validate typography against dense, narrative, and technical profiles.

Entry: Studio -> Typography -> Readability Validation

Steps:

  1. Select bundle version and validation profiles.
  2. Execute automated readability checks.
  3. Inspect violations and recommended remediations.
  4. Apply fixes and re-run validation.
  5. Mark report pass/fail and attach evidence.

Success State:

  • Validation report status is pass.
  • Evidence references are attached.

J3. Domain Typography Parity Sync#

Goal: Ensure domain surfaces consume same canonical typography bundle.

Entry: Studio -> Typography -> Domain Parity

Steps:

  1. Generate current drift report across domains.
  2. Resolve bundle mismatches per domain surface.
  3. Sync canonical bundle references.
  4. Re-run parity scan.
  5. Confirm parity pass state.

Success State:

  • All target domains report no typography drift.

J4. Accessibility and Program Review Approval#

Goal: Approve typography release for production.

Entry: Review & Approvals

Steps:

  1. Open typography release package.
  2. Verify readability and parity evidence.
  3. Validate role-policy and compliance checklist.
  4. Approve or reject with rationale.
  5. If approved, promote to production.

Success State:

  • Approved release promoted with full evidence chain.

J5. Typography Incident Rollback#

Goal: Recover from typography regression in production.

Entry: Observability alert or user escalation.

Steps:

  1. Identify failing bundle and impacted surfaces.
  2. Trigger rollback to last certified version.
  3. Verify readability and clipping recovery.
  4. Lock problematic bundle.
  5. Publish post-incident analysis.

Success State:

  • Stable typography restored with incident evidence logged.

2. Critical Edge Cases#

E1. Incomplete Context#

  • Trigger: missing program/project/workspace IDs.
  • Required behavior: block action, request context repair, emit audit error.

E2. Unauthorized Bundle Publish#

  • Trigger: role lacks publish permission.
  • Required behavior: deny with explicit reason and escalation path.

E3. Token Schema Invalid#

  • Trigger: invalid type token shape.
  • Required behavior: fail fast with token-level diagnostics.

E4. Readability Profile Failure#

  • Trigger: body minimum or measure check fails.
  • Required behavior: block release until remediation.

E5. Clipping Regression at Large Text#

  • Trigger: dynamic scale causes clipping on key surfaces.
  • Required behavior: block publish and require fix.

E6. Domain Drift Persisting After Sync#

  • Trigger: parity check still fails post sync.
  • Required behavior: report mismatched surfaces and keep release blocked.

E7. Telemetry Sink Failure#

  • Trigger: telemetry emit failure during publish.
  • Required behavior: retry with degradation notice and deferred reconciliation.

E8. Approval Deadlock#

  • Trigger: approver conflict/unavailability.
  • Required behavior: delegated approval flow and SLA escalation.

E9. Missing Rollback Artifact#

  • Trigger: release package lacks fallback bundle.
  • Required behavior: block production promotion.

E10. Excessive Publish Latency#

  • Trigger: publish flow exceeds SLO.
  • Required behavior: alert operators and capture diagnostics.

3. Journey-to-Surface Mapping#

Journey Primary Surface Supporting Surfaces
J1 Typography Scale Draft and Publish Typography Observability
J2 Readability Profile Validation Typography Governance
J3 Domain Typography Parity Sync Typography Programs, Projects
J4 Accessibility and Program Review Approval Review & Approvals Governance
J5 Typography Incident Rollback Observability Typography, Governance

4. Instrumentation Requirements#

Required events:

  • typography.journey.started
  • typography.journey.step.completed
  • typography.journey.blocked
  • typography.journey.recovered
  • typography.journey.completed

Required dimensions:

  • programId, projectId, workspaceId
  • journeyId, stepId, bundleVersion
  • actorRole, outcome, latencyMs, errorCode

5. Acceptance Criteria (OST-00019)#

OST-00019 is complete only when:

  1. At least five typography journeys are documented.
  2. At least ten typography edge cases are documented with deterministic behavior.
  3. Journey-to-surface mapping is explicit.
  4. Instrumentation requirements with required dimensions are documented.