Status: Active
Owner: OSHUN Studio Design Systems + OSHUN Web
Last Updated: 2026-02-23
Related: docs/adr/ADR-0018-oshun-studio-component-primitives-and-composition-contracts.md
Purpose#
Define dependencies and canonical contracts required to govern Studio component primitives across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.
This document is the execution artifact for OST-00042.
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/ux-principles.mddocs/releases/v1/design/ergonomics-requirements.mdlibs/oshun/uilibs/oshun/design-tokens/src/tokens.tsapps/oshun/web/src/design-system/tokens.ts
1. Dependency Overview#
1.1 Control Surfaces#
- Primitive source of truth:
libs/oshun/ui - Web composition layer:
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#
Component Primitive Governance -> Yemaya: project and collaboration surfaces require consistent card, table, and action-strip primitives.Component Primitive Governance -> Isis: workflow builders and job logs rely on deterministic field, modal, and status-pattern primitives.Component Primitive Governance -> Hathor: long-form authoring and review flows require reliable text-input, panel, and approval primitives.Component Primitive Governance -> Aja: timeline and motion pipeline tooling requires stable command, scrubber, and diagnostics primitives.Component Primitive Governance -> Bellona: build/runtime orchestration needs high-density operational controls with consistent error/disabled states.Project Obsidian -> all: program-level compliance for primitive contracts and release evidence.
2. Ownership and Contract Matrix#
| Area | Owner | Consumers | Artifact | Contract |
|---|---|---|---|---|
| Primitive catalog spec | Design Systems + Web Platform | Studio surfaces | Primitive bundle | PrimitiveCatalogBundle |
| Composition templates | Design Systems + UX Architecture | Domain teams | Composition spec | PrimitiveCompositionSpec |
| Accessibility/state validation | Accessibility QA + Web | Release managers | Validation report | PrimitiveValidationReport |
| Domain primitive parity | Domain adapters + QA | Product + Ops | Parity report | DomainPrimitiveParityReport |
| Audit/telemetry stream | Data Platform | SRE + Governance | Event stream | PrimitiveAuditEvent |
3. Canonical Contracts#
3.1 PrimitiveCatalogBundle#
ts
export interface PrimitiveCatalogBundle {
bundleId: string;
version: string;
scope: 'studio-component-primitives';
generatedAt: string;
generatedBy: string;
primitives: Array<{
primitiveId: string;
category:
| 'input'
| 'navigation'
| 'feedback'
| 'overlay'
| 'data'
| 'layout';
variants: string[];
states: Array<'idle' | 'loading' | 'error' | 'disabled' | 'success'>;
tokenDependencies: string[];
accessibilityContractId: string;
}>;
}
3.2 PrimitiveCompositionSpec#
ts
export interface PrimitiveCompositionSpec {
specId: string;
bundleVersion: string;
templates: Array<{
templateId: string;
name: string;
useCase:
| 'list_detail'
| 'command_bar'
| 'approval_workspace'
| 'dashboard_panel_grid'
| 'diagnostics_console';
requiredPrimitives: string[];
forbiddenPatterns: string[];
interactionContracts: string[];
}>;
}
3.3 PrimitiveValidationReport#
ts
export interface PrimitiveValidationReport {
reportId: string;
bundleVersion: string;
checkedAt: string;
checkedBy: string;
checks: {
keyboardContractPass: boolean;
focusOrderPass: boolean;
ariaStateSemanticsPass: boolean;
compositionTemplatePass: boolean;
tokenContractParityPass: boolean;
};
violations: Array<{
primitiveId: string;
issue: string;
severity: 'low' | 'medium' | 'high' | 'critical';
}>;
status: 'pass' | 'fail';
}
3.4 DomainPrimitiveParityReport#
ts
export interface DomainPrimitiveParityReport {
reportId: string;
bundleVersion: string;
domains: Array<'yemaya' | 'isis' | 'hathor' | 'aja' | 'bellona'>;
generatedAt: string;
driftFindings: Array<{
domain: string;
surface: string;
primitiveId: string;
expectedVersion: string;
actualVersion: string;
}>;
parityStatus: 'pass' | 'fail';
}
3.5 PrimitiveAuditEvent#
ts
export interface PrimitiveAuditEvent {
eventId: string;
action:
| 'primitives.bundle.publish.requested'
| 'primitives.bundle.publish.completed'
| 'primitives.validation.requested'
| 'primitives.validation.completed'
| 'primitives.parity.sync.requested'
| 'primitives.parity.sync.completed'
| 'primitives.permission.denied';
outcome: 'allowed' | 'denied' | 'success' | 'error';
programId: string;
projectId: string;
workspaceId: string;
role: string;
traceId: string;
occurredAt: string;
reason?: string;
}
4. Validation Rules#
- Production promotion is blocked unless
PrimitiveValidationReport.status = 'pass'. - Production promotion is blocked unless
DomainPrimitiveParityReport.parityStatus = 'pass'. - All publish/validate/sync flows require complete context and policy authorization.
- All allow/deny outcomes must emit
PrimitiveAuditEventrecords.
5. Acceptance Criteria (OST-00042)#
OST-00042 is complete only when:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for primitive catalog, composition templates, validation, parity, and audit streams are documented.
- Ownership boundaries and validation rules are explicit.