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.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/readability-standards.mddocs/releases/v1/design/brand-system.mdlibs/oshun/design-tokens/src/tokens.tsapps/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
TypographyAuditEventrecords.
5. Acceptance Criteria (OST-00018)#
OST-00018 is complete only when:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Canonical contract shapes for bundle, readability, parity, release, and audit are documented.
- Ownership boundaries and validation rules are explicit.