# OSHUN Studio Color System Dependency and Data Contract Map

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`

## Purpose

Define dependencies and contracts for Studio color-system and token governance
across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.

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

## Sources Used

- `docs/domains/yemaya/features.md`
- `docs/domains/isis/features.md`
- `docs/domains/hathor/features.md`
- `docs/domains/aja/features.md`
- `docs/domains/bellona/features.md`
- `docs/domains/yemaya/service-catalog.md`
- `docs/domains/isis/service-catalog.md`
- `docs/domains/hathor/service-catalog.md`
- `docs/domains/aja/service-catalog.md`
- `docs/domains/bellona/service-catalog.md`
- `docs/releases/v1/design/brand-system.md`
- `libs/oshun/design-tokens/src/tokens.ts`
- `apps/oshun/web/src/design-system/tokens.ts`

## 1. Dependency Overview

### 1.1 Control Surfaces

- **Token source of truth**: `libs/oshun/design-tokens`
- **Web color implementation**: `apps/oshun/web/src/design-system/tokens.ts`
- **Studio governance UI**: `apps/oshun/web/src/components/studio`
- **Telemetry and audit**: `libs/oshun/analytics` + studio sinks

### 1.2 Domain Dependency Graph

- `Color Governance -> Yemaya`: project and asset-status surfaces require stable
  semantic status colors.
- `Color Governance -> Isis`: generation job states and risk indicators rely on
  deterministic status mapping.
- `Color Governance -> Hathor`: world/narrative review needs high readability in
  long-form and dense graph states.
- `Color Governance -> Aja`: motion quality and pipeline diagnostics require
  unambiguous warning/error signaling.
- `Color Governance -> Bellona`: build/export/runtime operations require clear
  operational severity semantics.
- `Project Obsidian -> all`: release and compliance governance for color
  changes.

## 2. Ownership and Contract Matrix

| Area                   | Owner                    | Consumers              | Artifact          | Contract                        |
| ---------------------- | ------------------------ | ---------------------- | ----------------- | ------------------------------- |
| Color token schema     | Design Systems           | Web UI, shared UI libs | Token bundle      | `ColorTokenBundle`              |
| Semantic mapping rules | Design Systems + Product | Domain surfaces        | Mapping matrix    | `SemanticColorMapping`          |
| Contrast validation    | Accessibility QA         | Release managers       | Validation report | `ColorContrastValidationReport` |
| Domain accent parity   | Domain adapters          | QA + Ops               | Parity report     | `DomainColorParityReport`       |
| Audit telemetry stream | Data Platform            | SRE + Governance       | Event stream      | `ColorAuditEvent`               |

## 3. Canonical Contracts

### 3.1 ColorTokenBundle

```ts
export interface ColorTokenBundle {
  bundleId: string;
  version: string;
  scope: 'studio-color-system';
  generatedAt: string;
  generatedBy: string;
  primitives: {
    neutral: Record<string, string>;
    brand: Record<string, string>;
    status: Record<string, string>;
    domain: Record<string, string>;
  };
  semantic: {
    text: Record<string, string>;
    surface: Record<string, string>;
    accent: Record<string, string>;
    status: Record<'success' | 'warning' | 'danger' | 'info', string>;
  };
}
```

### 3.2 SemanticColorMapping

```ts
export interface SemanticColorMapping {
  mappingId: string;
  bundleVersion: string;
  states: Array<{
    state:
      | 'idle'
      | 'in_progress'
      | 'blocked'
      | 'warning'
      | 'error'
      | 'success'
      | 'needs_review';
    semanticTokenPath: string;
    approvedBy: string;
    approvedAt: string;
  }>;
}
```

### 3.3 ColorContrastValidationReport

```ts
export interface ColorContrastValidationReport {
  reportId: string;
  bundleVersion: string;
  checkedAt: string;
  checkedBy: string;
  checks: {
    normalTextAAPass: boolean;
    largeTextAAPass: boolean;
    highContrastVariantPass: boolean;
    semanticStatusDifferentiationPass: boolean;
  };
  violations: Array<{
    tokenPair: string;
    ratio: number;
    required: number;
    severity: 'low' | 'medium' | 'high' | 'critical';
  }>;
  status: 'pass' | 'fail';
}
```

### 3.4 DomainColorParityReport

```ts
export interface DomainColorParityReport {
  reportId: string;
  bundleVersion: string;
  domains: Array<'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona'>;
  generatedAt: string;
  driftFindings: Array<{
    domain: string;
    surface: string;
    tokenPath: string;
    expected: string;
    actual: string;
  }>;
  parityStatus: 'pass' | 'fail';
}
```

### 3.5 ColorAuditEvent

```ts
export interface ColorAuditEvent {
  eventId: string;
  action:
    | 'color.bundle.publish.requested'
    | 'color.bundle.publish.completed'
    | 'color.contrast.validate.requested'
    | 'color.contrast.validate.completed'
    | 'color.parity.sync.requested'
    | 'color.parity.sync.completed'
    | 'color.permission.denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  programId: string;
  projectId: string;
  workspaceId: string;
  role: string;
  traceId: string;
  occurredAt: string;
  reason?: string;
}
```

## 4. Validation Rules

- Production release blocked unless
  `ColorContrastValidationReport.status = 'pass'`.
- Production release blocked unless
  `DomainColorParityReport.parityStatus = 'pass'`.
- All publish/validate/sync actions require complete context and role
  authorization.
- All allow/deny outcomes must emit `ColorAuditEvent` records.

## 5. Acceptance Criteria (OST-00026)

`OST-00026` is complete only when:

1. This dependency and contract map exists.
2. Dependencies for all five Studio domains plus Project Obsidian are mapped.
3. Contract shapes for color bundle, semantic mapping, contrast validation,
   parity reporting, and audit events are documented.
4. Ownership boundaries and validation rules are explicit.
