Eve library

OSHUN Studio Design Language 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-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.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
  • docs/releases/v1/design/ux-principles.md
  • docs/releases/v1/design/motion-language.md
  • libs/oshun/design-tokens/src/tokens.ts
  • apps/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, and workspaceId.
  • 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:

  1. This dependency and contract map exists.
  2. Dependencies across all five Studio domains plus Project Obsidian are explicitly mapped.
  3. Contract shapes exist for token bundles, domain identity, accessibility certification, release packaging, and audit events.
  4. Ownership boundaries are explicit and reviewable.
  5. Validation rules for release gating are documented.