Eve library

OSHUN Studio Typography Runbook

Runbook

Revision 1

On this page

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#

text
[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#

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

Incident Resolved#

text
[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.