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.mddocs/domains/isis/features.mddocs/domains/hathor/features.mddocs/domains/aja/features.mddocs/domains/bellona/features.mddocs/domains/yemaya/service-catalog.mddocs/domains/isis/service-catalog.mddocs/domains/hathor/service-catalog.mddocs/domains/aja/service-catalog.mddocs/domains/bellona/service-catalog.mddocs/releases/v1/design/brand-system.mdlibs/oshun/design-tokens/src/tokens.tsapps/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
ColorAuditEventrecords.
5. Acceptance Criteria (OST-00026)#
OST-00026 is complete only when:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contract shapes for color bundle, semantic mapping, contrast validation, parity reporting, and audit events are documented.
- Ownership boundaries and validation rules are explicit.