Eve library

OSHUN Studio Spacing and Layout Grid 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-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.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/brand-system.md
  • docs/releases/v1/design/ergonomics-requirements.md
  • libs/oshun/design-tokens/src/tokens.ts
  • apps/oshun/web/src/design-system/tokens.ts
  • apps/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.ts and apps/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 LayoutAuditEvent records.

5. Acceptance Criteria (OST-00034)#

OST-00034 is complete only when:

  1. This dependency and contract map exists.
  2. Dependencies for all five Studio domains plus Project Obsidian are mapped.
  3. Contracts for spacing bundle, grid profiles, density validation, parity reporting, and audit are documented.
  4. Ownership boundaries and validation rules are explicit.