# OSHUN Studio Color System Runbook

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

```
[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

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

### Incident Resolved

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