Eve library

OSHUN Studio Color System 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-0016-oshun-studio-color-system-and-token-governance.md
  • docs/releases/v1/specs/studio-color-system-dependency-and-data-contract-map.md
  • docs/releases/v1/specs/studio-color-system-user-journeys-and-edge-cases.md
  • apps/oshun/web/src/components/studio/StudioColorSystemWorkspace.tsx

Purpose#

Define ownership, SLOs, incident playbooks, and escalation paths for Studio color-system governance workflows.

This document is the execution artifact for OST-00032.

1. Ownership Model#

Surface Primary Owner Backup Owner Dependencies
Color-system workspace route OSHUN Web Platform Web token contracts + analytics
Color token governance Design Systems Platform Architecture libs/oshun/design-tokens
Contrast validation Accessibility QA Design Systems contrast validator stack
Policy enforcement Security + Web Platform Identity entitlement/session contracts
Telemetry and audit Data Platform SRE event sinks and ingestion pipelines

2. Core SLOs#

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

3. Operational Playbooks#

3.1 Bundle Publish Failures#

Trigger: repeated semantic mapping/publish failures.

Actions:

  1. Validate token schema and semantic map compatibility.
  2. Confirm unique version metadata.
  3. Re-run preview publish checks.
  4. Roll back to last certified bundle when needed.

3.2 Contrast Validation Failures#

Trigger: CONTRAST_VALIDATION_FAILED outcomes.

Actions:

  1. Identify failing token pairs and required ratios.
  2. Adjust token values preserving semantic priority.
  3. Re-run contrast validation.
  4. Block promotion until pass.

3.3 Domain Color Drift#

Trigger: DOMAIN_COLOR_DRIFT findings.

Actions:

  1. Identify drifted domain surfaces.
  2. Re-apply canonical token mappings.
  3. Re-run parity checks.
  4. Freeze release until parity pass.

3.4 Policy Denial Spike#

Trigger: unexpected increase in ROLE_POLICY_DENIED outcomes.

Actions:

  1. Compare UI policy map with entitlement contracts.
  2. Verify identity payload/version changes.
  3. Apply hotfix or rollback policy drift.

3.5 Telemetry and Audit Degradation#

Trigger: missing or delayed color telemetry/audit events.

Actions:

  1. Validate sink health and retry queue depth.
  2. Enable degraded observability warning in UI.
  3. Reconcile missed events from buffered traces.
  4. Confirm event completeness restoration.

4. Release Checklist#

  • Validate /studio/color-system renders and executes all required flows.
  • Validate optimistic, error, and retry behavior.
  • Validate role-policy allow/deny behavior.
  • Validate telemetry/audit event emission and SLO panel updates.
  • Validate integration/e2e/accessibility evidence artifacts.

5. Incident Communication Templates#

Incident Start#

text
[P{severity}] Studio Color-System Incident
Detected: {timestamp}
Impact: {publish/contrast/parity impact}
Suspected cause: {semantic map issue | contrast regression | parity drift | policy drift}
Owner: {on-call}

Incident Update#

text
[P{severity}] Studio Color-System Update
Time: {timestamp}
Mitigation: {rollback | hotfix | degraded mode}
Affected flows: {colorBundlePublish | contrastValidation | domainColorParitySync}
ETA: {time}

Incident Resolved#

text
[P{severity}] Studio Color-System 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
Color token governance #oshun-design-systems Architecture council
Security/policy #oshun-security Security lead
Program operations #project-obsidian-ops Executive producer + program tech lead

7. Acceptance Criteria (OST-00032)#

OST-00032 is complete only when:

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