# OSHUN Studio Design Language Runbook

Status: Active  
Owner: OSHUN Studio Design Systems + OSHUN Web  
Last Updated: 2026-02-23  
Related:

- `docs/adr/ADR-0014-oshun-studio-design-language-and-visual-identity.md`
- `docs/releases/v1/specs/studio-design-language-dependency-and-data-contract-map.md`
- `docs/releases/v1/specs/studio-design-language-user-journeys-and-edge-cases.md`
- `apps/oshun/web/src/components/studio/StudioDesignLanguageWorkspace.tsx`

## Purpose

Define operational ownership, playbooks, SLOs, and escalation paths for Studio
Design Language workflows.

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

## 1. Ownership Model

| Surface                         | Primary Owner  | Backup Owner          | Dependencies                  |
| ------------------------------- | -------------- | --------------------- | ----------------------------- |
| Design Language workspace route | OSHUN Web      | Platform Web          | Token + analytics services    |
| Token contract governance       | Design Systems | Platform Architecture | `libs/oshun/design-tokens`    |
| Role-policy enforcement         | Security + Web | Platform Identity     | Session/entitlement payloads  |
| Telemetry and audit pipelines   | Data Platform  | SRE                   | Analytics sinks, event ingest |
| Release approval operations     | Program Ops    | Design leadership     | Governance workflows          |

## 2. Core SLOs

| Metric                                     | Target             | Alert Threshold      |
| ------------------------------------------ | ------------------ | -------------------- |
| Token publish success rate                 | >= 99.0%           | < 98.0% over 15 min  |
| Domain sync success rate                   | >= 99.5%           | < 99.0% over 15 min  |
| Accessibility certification pass integrity | 100% deterministic | any false pass       |
| p95 flow latency                           | <= 2200ms          | > 3200ms over 15 min |
| Audit event completeness                   | >= 99.5%           | < 99.0% over 15 min  |

## 3. Playbooks

### 3.1 Publish Failure Spike

Trigger: repeated token publish errors.

Actions:

1. Confirm token schema and version collision checks.
2. Inspect latest publish trace IDs and failure codes.
3. Validate preview channel write path.
4. Roll forward hotfix or rollback to last certified bundle.

### 3.2 Unauthorized Action Spike

Trigger: sudden increase in policy denials.

Actions:

1. Validate UI role-policy map against entitlement contracts.
2. Verify identity payload changes in auth/bff.
3. Patch misconfigured policy map or revert entitlement drift.

### 3.3 Accessibility Certification Regression

Trigger: certification unexpectedly failing for known-good bundle.

Actions:

1. Compare checker version and token inputs.
2. Re-run on pinned reference snapshots.
3. If checker regression confirmed, freeze production promotion and issue patch.

### 3.4 Domain Identity Drift

Trigger: mismatch across domain identity surfaces.

Actions:

1. Run parity report for Yemaya/Isis/Hathor/Aja/Bellona.
2. Re-sync with last approved `DomainIdentitySpec`.
3. Block further releases until parity restored.

### 3.5 Telemetry/Audit Degradation

Trigger: audit events not arriving within SLA.

Actions:

1. Check sink health and retry queue depth.
2. Enable degraded-mode warning in workspace UI.
3. Reconcile missing events from local buffered records.

## 4. Release Checklist

- [ ] Validate all design flows render and execute (`publish`, `sync`,
      `certify`).
- [ ] Validate optimistic, error, and retry states for each flow.
- [ ] Validate policy allow/deny behavior for configured roles.
- [ ] Validate telemetry and audit event emission.
- [ ] Validate SLO panel updates after executions.
- [ ] Validate test suite and smoke spec evidence links.

## 5. Incident Communication Templates

### Incident Start

```
[P{severity}] Studio Design Language Incident
Detected: {timestamp}
Impact: {publish/sync/certification impact}
Suspected cause: {policy drift | token schema error | sink failure}
Owner: {on-call}
```

### Incident Update

```
[P{severity}] Studio Design Language Update
Time: {timestamp}
Mitigation: {rollback | hotfix | degraded mode}
Affected flows: {tokenBundlePublish | domainIdentitySync | accessibilityCertification}
ETA: {time}
```

### Incident Resolved

```
[P{severity}] Studio Design Language 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                | `#oshun-web`            | Platform on-call                       |
| Token contract issues      | `#oshun-design-systems` | Architecture council                   |
| Security/policy            | `#oshun-security`       | Security lead                          |
| Program release operations | `#project-obsidian-ops` | Executive producer + program tech lead |

## 7. Acceptance Criteria (OST-00016)

`OST-00016` is complete only when:

1. Ownership model and decision authority are documented.
2. SLOs and alert thresholds are documented.
3. At least five operational playbooks exist.
4. Release checklist exists.
5. Incident communication templates and escalation paths exist.
