# OSHUN Studio Spacing and Layout Grid Dependency and Data Contract Map

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.
