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
Purpose#
Define dependencies and data contracts required to operationalize Studio design language and visual identity governance across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.
This document is the execution artifact for OST-00010.
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.mddocs/releases/v1/design/ux-principles.mddocs/releases/v1/design/motion-language.mdlibs/oshun/design-tokens/src/tokens.tsapps/oshun/web/src/design-system/tokens.ts
1. Dependency Overview#
1.1 Control Surfaces#
- Token authority:
libs/oshun/design-tokens - Web implementation:
apps/oshun/web/src/design-system - Studio orchestration/UI:
apps/oshun/web/src/components/studio - Analytics and audit emission:
libs/oshun/analytics+ web sink adapters
1.2 Studio Domain Dependency Graph#
Design Language Governance -> Yemaya: collaboration, review workflow, publication orchestration metadata.Design Language Governance -> Isis: preview generation for rich assets, model-based visual QA artifacts.Design Language Governance -> Hathor: narrative typography/readability validation contexts.Design Language Governance -> Aja: motion accessibility and animation smoothness constraints for motion-heavy surfaces.Design Language Governance -> Bellona: runtime/export UI clarity for build, bridge, and diagnostics surfaces.Project Obsidian -> all: release governance and evidence bundling.
2. Ownership and Contract Matrix#
| Area | Owner | Consumers | Produced Artifact | Required Contract |
|---|---|---|---|---|
| Token definitions | Design Systems | Web, Mobile, Domain UIs | Token bundle | DesignTokenBundle |
| Visual identity mapping | Studio Design | Domain adapters | Domain accent matrix | DomainIdentitySpec |
| Accessibility certification | Accessibility team | Release managers | WCAG evidence report | AccessibilityCertification |
| Visual release governance | Program operations | Engineering + Design | Signed release package | VisualReleasePackage |
| Telemetry and audit | Platform analytics | SRE + Governance | Event stream + audit logs | VisualAuditEvent |
3. Canonical Contracts#
3.1 DesignTokenBundle#
ts
export interface DesignTokenBundle {
bundleId: string;
version: string;
scope: 'studio';
mode: 'light' | 'dark' | 'highContrastLight' | 'highContrastDark';
generatedAt: string;
generatedBy: string;
tokens: {
semantic: Record<string, string>;
typography: Record<string, string | number>;
spacing: Record<string, number>;
radii: Record<string, number>;
motion: Record<string, string | number>;
};
}
3.2 DomainIdentitySpec#
ts
export interface DomainIdentitySpec {
programId: string;
domain: 'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona' | 'project-obsidian';
accentHex: string;
textOnAccentHex: string;
emphasisRules: {
allowFullSurfaceTint: boolean;
maxTintOpacityPercent: number;
navIconTintAllowed: boolean;
};
approvedBy: string;
approvedAt: string;
}
3.3 AccessibilityCertification#
ts
export interface AccessibilityCertification {
certificationId: string;
bundleVersion: string;
checkedAt: string;
checkedBy: string;
wcagLevel: 'AA' | 'AAA';
contrastViolations: Array<{
tokenPath: string;
ratio: number;
required: number;
}>;
reducedMotionCompliance: boolean;
keyboardOperabilityCompliance: boolean;
status: 'pass' | 'fail';
}
3.4 VisualReleasePackage#
ts
export interface VisualReleasePackage {
releaseId: string;
programId: string;
bundleVersion: string;
releaseChannel: 'preview' | 'staging' | 'production';
approvers: Array<{
actorId: string;
role: string;
decision: 'approved' | 'rejected';
decidedAt: string;
}>;
certificationIds: string[];
rollbackBundleVersion: string;
evidenceLinks: string[];
}
3.5 VisualAuditEvent#
ts
export interface VisualAuditEvent {
eventId: string;
action:
| 'token.bundle.publish.requested'
| 'token.bundle.publish.completed'
| 'domain.identity.sync.requested'
| 'domain.identity.sync.completed'
| 'accessibility.certification.requested'
| 'accessibility.certification.completed'
| 'permission.denied';
outcome: 'allowed' | 'denied' | 'success' | 'error';
programId: string;
projectId: string;
workspaceId: string;
role: string;
traceId: string;
occurredAt: string;
reason?: string;
}
4. Validation Rules#
- All visual release actions must include
programId,projectId, andworkspaceId. - No token bundle can move to production without passing
AccessibilityCertification.status === 'pass'. - Domain identity sync requires role authorization and audit emission.
- Telemetry and audit records must capture both allow/deny outcomes.
5. Acceptance Criteria (OST-00010)#
OST-00010 is complete only when:
- This dependency and contract map exists.
- Dependencies across all five Studio domains plus Project Obsidian are explicitly mapped.
- Contract shapes exist for token bundles, domain identity, accessibility certification, release packaging, and audit events.
- Ownership boundaries are explicit and reviewable.
- Validation rules for release gating are documented.