Eve library

OSHUN Studio Typography 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-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.