# OSHUN Studio Design Language Dependency and Data Contract Map

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.
