# OSHUN Studio Typography Journeys and Edge Cases

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.
