# OSHUN Studio Typography Runbook

Status: Active  
Owner: OSHUN Studio Design Systems + OSHUN Web  
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`
- `docs/releases/v1/specs/studio-typography-user-journeys-and-edge-cases.md`
- `apps/oshun/web/src/components/studio/StudioTypographyWorkspace.tsx`

## Purpose

Define operational ownership, SLOs, playbooks, and escalation paths for Studio
Typography governance workflows.

This document is the execution artifact for `OST-00024`.

## 1. Ownership Model

| Surface                      | Primary Owner    | Backup Owner          | Dependencies                |
| ---------------------------- | ---------------- | --------------------- | --------------------------- |
| Typography workspace route   | OSHUN Web        | Platform Web          | token contracts + analytics |
| Typography token governance  | Design Systems   | Platform Architecture | `libs/oshun/design-tokens`  |
| Readability validation       | Accessibility QA | Design Systems        | profile validators          |
| Role-policy enforcement      | Security + Web   | Platform Identity     | auth/session payloads       |
| Telemetry and audit pipeline | Data Platform    | SRE                   | event ingestion and sinks   |

## 2. Core SLOs

| Metric                                | Target             | Alert Threshold      |
| ------------------------------------- | ------------------ | -------------------- |
| Typography flow success rate          | >= 99.0%           | < 98.0% over 15 min  |
| Readability validation pass integrity | 100% deterministic | any false pass       |
| Domain parity sync success rate       | >= 99.5%           | < 99.0% over 15 min  |
| Typography flow p95 latency           | <= 2200ms          | > 3200ms over 15 min |
| Typography audit completeness         | >= 99.5%           | < 99.0% over 15 min  |

## 3. Operational Playbooks

### 3.1 Token Publish Failures

Trigger: repeated `TOKEN_SCHEMA_INVALID` failures.

Actions:

1. Validate token schema diff and compatibility checks.
2. Confirm bundle version uniqueness and release metadata.
3. Run dry-run publish in preview.
4. Roll back to last certified bundle if needed.

### 3.2 Readability Validation Failures

Trigger: repeated `READABILITY_PROFILE_FAILED` outcomes.

Actions:

1. Inspect profile-specific violations (`dense_ops`, `narrative_review`,
   `technical_logs`).
2. Apply token adjustments for size/line-height/measure.
3. Re-run validation and confirm pass status.
4. Block production promotion until pass.

### 3.3 Domain Parity Drift

Trigger: `DOMAIN_TYPOGRAPHY_DRIFT` or parity mismatch reports.

Actions:

1. Identify stale bundle references by domain/surface.
2. Re-apply canonical bundle mapping.
3. Re-run parity sync and verification.
4. Freeze releases until parity is restored.

### 3.4 Policy Denial Spike

Trigger: unexpected increase in `ROLE_POLICY_DENIED` events.

Actions:

1. Compare UI policy map against entitlement contracts.
2. Verify auth payload changes in upstream identity services.
3. Apply policy map hotfix or revert entitlement drift.

### 3.5 Telemetry and Audit Degradation

Trigger: missing typography telemetry/audit events.

Actions:

1. Validate sink health and retry queue depth.
2. Enable degraded observability banner in workspace if needed.
3. Reconcile missed events from buffered logs.
4. Confirm post-recovery event completeness.

## 4. Release Checklist

- [ ] Validate `/studio/typography` renders and executes all required flows.
- [ ] Validate optimistic, error, and retry behavior for each flow.
- [ ] Validate role-policy allow/deny paths.
- [ ] Validate telemetry/audit emissions and SLO panel behavior.
- [ ] Validate test and smoke evidence paths.

## 5. Incident Communication Templates

### Incident Start

```
[P{severity}] Studio Typography Incident
Detected: {timestamp}
Impact: {publish/validation/parity impact}
Suspected cause: {schema error | readability regression | parity drift | policy drift}
Owner: {on-call}
```

### Incident Update

```
[P{severity}] Studio Typography Update
Time: {timestamp}
Mitigation: {rollback | hotfix | degraded mode}
Affected flows: {scaleBundlePublish | readabilityProfileValidation | domainParitySync}
ETA: {time}
```

### Incident Resolved

```
[P{severity}] Studio Typography Incident Resolved
Resolved: {timestamp}
Root cause: {description}
Fix: {release/hotfix id}
Validation: {tests + telemetry checks}
Postmortem: {link}
```

## 6. Escalation Paths

| Area                        | Primary Channel         | Escalate To                            |
| --------------------------- | ----------------------- | -------------------------------------- |
| Web runtime and workspace   | `#oshun-web`            | Platform on-call                       |
| Typography token governance | `#oshun-design-systems` | Architecture council                   |
| Policy and permissions      | `#oshun-security`       | Security lead                          |
| Program-level operations    | `#project-obsidian-ops` | Executive producer + program tech lead |

## 7. Acceptance Criteria (OST-00024)

`OST-00024` is complete only when:

1. Ownership and decision authority are documented.
2. Typography SLOs and alert thresholds are documented.
3. At least five playbooks exist for major failure modes.
4. Release checklist, communication templates, and escalation paths exist.
