# OSHUN Studio Typography Dependency and Data Contract Map

Status: Active  
Owner: OSHUN Studio Design Systems + OSHUN Web  
Last Updated: 2026-02-23  
Related: `docs/adr/ADR-0015-oshun-studio-typography-system.md`

## Purpose

Define dependencies and contracts required to ship and govern the Studio
typography system across Yemaya, Isis, Hathor, Aja, Bellona, and Project
Obsidian.

This document is the execution artifact for `OST-00018`.

## 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/readability-standards.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 typography implementation**: `apps/oshun/web/src/design-system`
- **Studio governance UX**: `apps/oshun/web/src/components/studio`
- **Telemetry and audit**: `libs/oshun/analytics` + Studio event sinks

### 1.2 Domain Dependency Graph

- `Typography Governance -> Yemaya`: project dashboards, collaboration threads,
  asset tables require dense and legible hierarchy.
- `Typography Governance -> Isis`: generation logs, workflow metadata, and
  cost/latency diagnostics require mono/data readability.
- `Typography Governance -> Hathor`: narrative and lore authoring needs
  long-form readability profiles.
- `Typography Governance -> Aja`: motion pipeline status boards require clear
  technical labels and compact metadata hierarchy.
- `Typography Governance -> Bellona`: build/runtime diagnostics need
  scan-friendly technical text and error prominence.
- `Project Obsidian -> all`: program-level release standards and evidence
  requirements for typography changes.

## 2. Ownership and Contract Matrix

| Area                        | Owner                     | Consumers              | Artifact          | Contract                       |
| --------------------------- | ------------------------- | ---------------------- | ----------------- | ------------------------------ |
| Typography token schema     | Design Systems            | Web UI, shared UI libs | Token bundle      | `TypographyTokenBundle`        |
| Readability validation      | Accessibility + Design QA | Release managers       | Validation report | `ReadabilityValidationReport`  |
| Typography release approval | Program operations        | Engineering + Design   | Signed package    | `TypographyReleasePackage`     |
| Domain typography parity    | Studio domain adapters    | Product + QA           | Parity report     | `DomainTypographyParityReport` |
| Audit/telemetry traces      | Data Platform             | SRE + Governance       | Event stream      | `TypographyAuditEvent`         |

## 3. Canonical Contracts

### 3.1 TypographyTokenBundle

```ts
export interface TypographyTokenBundle {
  bundleId: string;
  version: string;
  scope: 'studio-typography';
  generatedAt: string;
  generatedBy: string;
  typography: {
    families: {
      display: string;
      body: string;
      mono: string;
    };
    weights: Record<'regular' | 'medium' | 'semibold' | 'bold', number>;
    scale: Record<
      string,
      {
        sizePx: number;
        lineHeightPx: number;
        weight: number;
        letterSpacing?: string;
      }
    >;
  };
}
```

### 3.2 ReadabilityValidationReport

```ts
export interface ReadabilityValidationReport {
  reportId: string;
  bundleVersion: string;
  checkedAt: string;
  checkedBy: string;
  profiles: Array<'dense_ops' | 'narrative_review' | 'technical_logs'>;
  checks: {
    minBodySizePass: boolean;
    lineHeightRangePass: boolean;
    longFormMeasurePass: boolean;
    dynamicScalePass: boolean;
    clippingRegressionPass: boolean;
  };
  violations: Array<{
    tokenPath: string;
    issue: string;
    severity: 'low' | 'medium' | 'high' | 'critical';
  }>;
  status: 'pass' | 'fail';
}
```

### 3.3 DomainTypographyParityReport

```ts
export interface DomainTypographyParityReport {
  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.4 TypographyReleasePackage

```ts
export interface TypographyReleasePackage {
  releaseId: string;
  programId: string;
  bundleVersion: string;
  releaseChannel: 'preview' | 'staging' | 'production';
  readabilityReportId: string;
  parityReportId: string;
  approvers: Array<{
    actorId: string;
    role: string;
    decision: 'approved' | 'rejected';
    decidedAt: string;
  }>;
  rollbackBundleVersion: string;
  evidenceLinks: string[];
}
```

### 3.5 TypographyAuditEvent

```ts
export interface TypographyAuditEvent {
  eventId: string;
  action:
    | 'typography.bundle.publish.requested'
    | 'typography.bundle.publish.completed'
    | 'typography.readability.validate.requested'
    | 'typography.readability.validate.completed'
    | 'typography.parity.sync.requested'
    | 'typography.parity.sync.completed'
    | 'typography.permission.denied';
  outcome: 'allowed' | 'denied' | 'success' | 'error';
  programId: string;
  projectId: string;
  workspaceId: string;
  role: string;
  traceId: string;
  occurredAt: string;
  reason?: string;
}
```

## 4. Validation Rules

- No production typography release without
  `ReadabilityValidationReport.status = 'pass'`.
- No production typography release without
  `DomainTypographyParityReport.parityStatus = 'pass'`.
- All publish and validation actions require role authorization and complete
  context (`programId`, `projectId`, `workspaceId`).
- All allow/deny outcomes must emit `TypographyAuditEvent` records.

## 5. Acceptance Criteria (OST-00018)

`OST-00018` is complete only when:

1. This dependency and contract map exists.
2. Dependencies for all five Studio domains plus Project Obsidian are mapped.
3. Canonical contract shapes for bundle, readability, parity, release, and audit
   are documented.
4. Ownership boundaries and validation rules are explicit.
