# ADR-0017: OSHUN Studio Spacing and Layout Grid Governance

**Status**: Accepted  
**Date**: 2026-02-23  
**Authors**: OSHUN Studio Design Systems, OSHUN Web Engineering  
**Reviewers**: Domain Leads (Yemaya, Isis, Hathor, Aja, Bellona), Project
Obsidian Program Design

## Context and Problem Statement

Studio workflows operate with high information density and multi-panel layouts.
Without an explicit spacing and layout-grid decision, domains may diverge in
rhythm, scannability, and interaction ergonomics.

Lack of governed spacing/grid rules causes:

- inconsistent panel density and hierarchy spacing
- unpredictable alignment across cross-domain surfaces
- degraded mobile/desktop responsiveness
- token drift via ad hoc layout constants

## Decision Drivers

- **Ergonomics consistency**: predictable spacing rhythm for rapid scanning.
- **Cross-domain alignment**: one layout grammar across domain modules.
- **Responsive reliability**: deterministic behavior from narrow to wide
  viewports.
- **Token parity**: spacing and radii usage must be tokenized and auditable.
- **Operational clarity**: dense data layouts must preserve clarity and action
  reachability.

## Considered Options

### Option 1: Domain-Specific Layout Grids

Each domain defines independent spacing and grid rules.

**Pros**:

- Local flexibility.

**Cons**:

- High visual and cognitive drift.
- Difficult cross-domain consistency.

### Option 2: Shared Token Scale, Ungoverned Layout Usage

Use shared spacing tokens but allow ungoverned composition.

**Pros**:

- Faster initial implementation.

**Cons**:

- Weak guarantees for layout consistency and ergonomics.

### Option 3: Unified Studio Spacing and Grid Governance (Chosen)

Adopt a shared spacing scale + governed layout-grid conventions with release
checks and auditability.

**Pros**:

- Consistent layout rhythm and panel ergonomics.
- Better responsiveness and readability in dense surfaces.
- Enforceable token usage and predictable release governance.

**Cons**:

- Requires stronger governance discipline for layout changes.

## Decision Outcome

**Chosen option**: Option 3.

Studio spacing/layout requirements:

1. **Tokenized spacing scale** for all spacing/padding/gap usage.
2. **Layout grid conventions** for panel columns, gutters, and breakpoints.
3. **Density profiles** for operational, review, and executive surfaces.
4. **Validation gates** for spacing-token parity and responsive integrity.
5. **Release governance** with approvals, telemetry/audit, and rollback.

## Normative Rules

### Spacing Contract

- Layout gaps, paddings, and margins must use approved spacing tokens.
- Ad hoc numeric spacing values in governed Studio surfaces are prohibited.

### Grid Contract

- Studio surfaces must align to shared responsive breakpoints and grid columns.
- Gutter and container spacing rules must remain deterministic per breakpoint.

### Density Contract

- Dense operational surfaces must preserve minimum interaction spacing.
- Review and narrative surfaces may use expanded spacing presets.

### Release Validity Contract

A spacing/layout release is valid only when all are true:

- token usage parity checks pass
- responsive grid checks pass
- role-authorized approval exists
- telemetry/audit records are complete
- rollback reference is defined

## Architecture Implications

- `libs/oshun/design-tokens` remains authoritative for spacing primitives.
- `apps/oshun/web/src/design-system/tokens.ts` and global system CSS remain web
  implementation surfaces.
- Studio spacing/layout governance workflows are implemented under
  `apps/oshun/web` Studio routes.

## Acceptance Criteria (OST-00033)

`OST-00033` is complete only when:

1. ADR exists at `docs/adr/ADR-0023-oshun-studio-spacing-and-layout-grid.md`.
2. ADR defines options, trade-offs, and selected strategy.
3. ADR defines spacing, grid, density, and release validity contracts.
4. ADR aligns with `ADR-0007` through `ADR-0016`.
5. ADR aligns with `docs/releases/v1/design/brand-system.md`,
   `docs/releases/v1/design/ergonomics-requirements.md`, and
   `libs/oshun/design-tokens/src/tokens.ts`.
6. ADR explicitly covers Yemaya, Isis, Hathor, Aja, Bellona, and Project
   Obsidian.

## Consequences

### Positive

- Stable layout rhythm and cross-domain alignment.
- Fewer responsive regressions in dense Studio interfaces.
- Stronger governance and traceability for layout-system changes.

### Negative

- Added governance overhead for layout adjustments.
- Requires token-discipline in all Studio contributions.

## Related Decisions

- `docs/adr/ADR-0013-oshun-shell-architecture-and-domain-adapters.md`
- `docs/adr/ADR-0014-oshun-web-and-pwa-strategy.md`
- `docs/adr/ADR-0015-deep-linking-and-cross-domain-routing.md`
- `docs/adr/ADR-0016-shared-identity-and-cross-domain-session-model.md`
- `docs/adr/ADR-0017-offline-caching-and-sync-strategy.md`
- `docs/adr/ADR-0018-analytics-taxonomy-and-event-naming.md`
- `docs/adr/ADR-0019-oshun-studio-information-architecture.md`
- `docs/adr/ADR-0020-oshun-studio-design-language-and-visual-identity.md`
- `docs/adr/ADR-0021-oshun-studio-typography-system.md`
- `docs/adr/ADR-0022-oshun-studio-color-system-and-token-governance.md`

## References

- `docs/releases/v1/design/brand-system.md`
- `docs/releases/v1/design/ergonomics-requirements.md`
- `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`
- `libs/oshun/design-tokens/src/tokens.ts`
- `apps/oshun/web/src/design-system/tokens.ts`
- `apps/oshun/web/src/design-system/globals-v2.css`