Eve library

OSHUN Studio Color System Dependency and Data Contract Map

Spec

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

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.