Status: Active
Owner: OSHUN Studio Design Systems + OSHUN Web
Last Updated: 2026-02-23
Related: docs/adr/ADR-0017-oshun-studio-spacing-and-layout-grid.md
Purpose#
Define dependencies and contracts required to govern Studio spacing and layout grid behavior across Yemaya, Isis, Hathor, Aja, Bellona, and Project Obsidian.
This document is the execution artifact for OST-00034.
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/brand-system.mddocs/releases/v1/design/ergonomics-requirements.mdlibs/oshun/design-tokens/src/tokens.tsapps/oshun/web/src/design-system/tokens.tsapps/oshun/web/src/design-system/globals-v2.css
1. Dependency Overview#
1.1 Control Surfaces#
- Token source of truth:
libs/oshun/design-tokens - Layout implementation layer:
apps/oshun/web/src/design-system/tokens.tsandapps/oshun/web/src/design-system/globals-v2.css - Studio governance UX:
apps/oshun/web/src/components/studio - Telemetry and audit:
libs/oshun/analytics+ Studio event sinks
1.2 Domain Dependency Graph#
Spacing/Grid Governance -> Yemaya: project/asset table density and collaboration layout structure.Spacing/Grid Governance -> Isis: workflow/run dashboards and job-monitoring card grids.Spacing/Grid Governance -> Hathor: narrative + worldbuilding surface readability and panel layout balance.Spacing/Grid Governance -> Aja: motion pipeline diagnostics with compact action rows and technical side-panels.Spacing/Grid Governance -> Bellona: build/runtime and bridge dashboards with high-density operational controls.Project Obsidian -> all: program-level release governance for layout-system changes.
2. Ownership and Contract Matrix#
| Area | Owner | Consumers | Artifact | Contract |
|---|---|---|---|---|
| Spacing token schema | Design Systems | Web UI + shared components | Token bundle | SpacingTokenBundle |
| Grid breakpoint conventions | Web Platform | Studio surfaces | Grid profile | GridProfileSpec |
| Density profile validation | UX QA + Accessibility | Release managers | Validation report | LayoutDensityValidationReport |
| Domain layout parity | Domain adapters + QA | Product + Ops | Parity report | DomainLayoutParityReport |
| Audit/telemetry stream | Data Platform | SRE + Governance | Event stream | LayoutAuditEvent |
3. Canonical Contracts#
3.1 SpacingTokenBundle#
ts
export interface SpacingTokenBundle {
bundleId: string;
version: string;
scope: 'studio-spacing-layout';
generatedAt: string;
generatedBy: string;
spacing: Record<string, number>;
radii: Record<string, number>;
metadata: {
baseUnitPx: number;
allowedRawSpacingValues: number[];
};
}
3.2 GridProfileSpec#
ts
export interface GridProfileSpec {
profileId: string;
bundleVersion: string;
breakpoints: Array<{
name: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
minWidthPx: number;
columns: number;
gutterPx: number;
containerPaddingPx: number;
}>;
densityModes: Array<'compact' | 'standard' | 'spacious'>;
}
3.3 LayoutDensityValidationReport#
ts
export interface LayoutDensityValidationReport {
reportId: string;
bundleVersion: string;
checkedAt: string;
checkedBy: string;
checks: {
tokenizedSpacingUsagePass: boolean;
minTouchTargetSpacingPass: boolean;
responsiveGridIntegrityPass: boolean;
overflowAndClippingPass: boolean;
};
violations: Array<{
surface: string;
issue: string;
severity: 'low' | 'medium' | 'high' | 'critical';
}>;
status: 'pass' | 'fail';
}
3.4 DomainLayoutParityReport#
ts
export interface DomainLayoutParityReport {
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.5 LayoutAuditEvent#
ts
export interface LayoutAuditEvent {
eventId: string;
action:
| 'layout.bundle.publish.requested'
| 'layout.bundle.publish.completed'
| 'layout.density.validate.requested'
| 'layout.density.validate.completed'
| 'layout.parity.sync.requested'
| 'layout.parity.sync.completed'
| 'layout.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 release blocked unless
LayoutDensityValidationReport.status = 'pass'. - Production release blocked unless
DomainLayoutParityReport.parityStatus = 'pass'. - All publish/validate/sync actions require complete context and policy authorization.
- All allow/deny outcomes must emit
LayoutAuditEventrecords.
5. Acceptance Criteria (OST-00034)#
OST-00034 is complete only when:
- This dependency and contract map exists.
- Dependencies for all five Studio domains plus Project Obsidian are mapped.
- Contracts for spacing bundle, grid profiles, density validation, parity reporting, and audit are documented.
- Ownership boundaries and validation rules are explicit.