Disciplines · Decisions (ADRs)

ADR-0017: OSHUN Studio Spacing and Layout Grid Governance

Studio workflows operate with high information density and multi-panel layouts.

Accepted · 2026-02-23
10sections3 minread
Markdown source
On this page

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.
  • 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