Status: Active
Owner: OSHUN Studio Product Design + Web Engineering
Last Updated: 2026-02-23
Related:
docs/adr/ADR-0015-oshun-studio-typography-system.mddocs/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#
- Typography changes must be reviewable and reversible.
- Readability checks must be explicit before promotion.
- Dense operations and long-form narrative contexts must both be validated.
- Every action must preserve
programId,projectId, andworkspaceId.
1. Primary Journeys#
J1. Typography Scale Draft and Publish#
Goal: Publish a new typography token bundle into preview.
Entry: Studio -> Typography -> Token Pipeline
Steps:
- Clone current typography bundle to draft.
- Adjust scale and line-height tokens.
- Run schema and compatibility validation.
- Publish to preview channel.
- 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:
- Select bundle version and validation profiles.
- Execute automated readability checks.
- Inspect violations and recommended remediations.
- Apply fixes and re-run validation.
- 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:
- Generate current drift report across domains.
- Resolve bundle mismatches per domain surface.
- Sync canonical bundle references.
- Re-run parity scan.
- 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:
- Open typography release package.
- Verify readability and parity evidence.
- Validate role-policy and compliance checklist.
- Approve or reject with rationale.
- 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:
- Identify failing bundle and impacted surfaces.
- Trigger rollback to last certified version.
- Verify readability and clipping recovery.
- Lock problematic bundle.
- 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.startedtypography.journey.step.completedtypography.journey.blockedtypography.journey.recoveredtypography.journey.completed
Required dimensions:
programId,projectId,workspaceIdjourneyId,stepId,bundleVersionactorRole,outcome,latencyMs,errorCode
5. Acceptance Criteria (OST-00019)#
OST-00019 is complete only when:
- At least five typography journeys are documented.
- At least ten typography edge cases are documented with deterministic behavior.
- Journey-to-surface mapping is explicit.
- Instrumentation requirements with required dimensions are documented.