---
path: /studio/spacing-layout
surface: studio
domain: design
auth: signed-in + studio entitlement
source: apps/oshun/web/src/app/studio/spacing-layout/page.tsx
status: walked + e2e-covered
last_walked:
  '2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data
  (2xx), console/page-errors, expected content, screenshot verified; live
  screen-reader, touch, offline, and telemetry-delivery checks pending a manual
  AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md; body
  re-derived 2026-06-03 from current source (lane-console architecture);
  2026-07-02 studio-design-lane-consoles Playwright pass covers live BFF
  catalog/generate, auth/schema gates, error states, quick actions, and mobile
  no-overflow.'
---

# Studio · Spacing and Layout

## Purpose

Generate spacing tokens with the real generator: the Spacing Scale Lane computes
`px = base × multiplier`, converts to rem against the root font size, and flags
each token's alignment to the layout grid. It is a live admin console wired to
`/v1/admin/studio/spacing-scale`, not an in-page simulation.

## Entry points

- **Direct URL / bookmark** — `/studio/spacing-layout` (signed-in + studio
  entitlement; admin scope required to generate)
- **Sibling Studio routes** — reached via the quick-action panel on
  color-system, typography, component-primitives, and other design/governance
  pages

## Layout regions

`page.tsx` mounts `<ShellLayout active="studio">` and renders
`<StudioSpacingLayoutWorkspace />` followed by a single `panel` of quick-action
links.

- **Shell**: `ShellLayout` chrome with the Studio tab active
- **Workspace heading**: `WorkspaceHeading` renders the page `<h1>` "Studio
  Spacing & Layout", followed by the `data-spacing-layout-summary` paragraph
- **Spacing Scale Lane**: an `<h2>` `data-ss-lane-heading` ("Spacing Scale
  Lane") section with the load states and, when ready, the generate form and
  result table
- **Quick-actions panel**: 16 sibling `quickAction` `Link`s — Component
  Primitives, Complex Interactions, Search/Discovery, Cross-Domain Entity Model,
  Workspace Context Switching, Multi-Project Operations, Authentication
  Architecture, Session and Device Management, RBAC and Permission Policy UX,
  Enterprise Tenant Isolation, Audit and Compliance Surfaces, Notification
  Center, Activity and Change Feeds, "Back to Color System workspace", "Back to
  Typography workspace", and "Back to Design Language workspace". No self-link
  and no Route Map panel.

## States

- [x] **Loading** — `data-ss-loading` ("Loading spacing generator…")
- [x] **Unauthorized** — `data-ss-unauthorized` ("Access restricted.") on
      401/403
- [x] **Error** — `data-ss-error` ("Could not load the spacing generator.")
- [x] **Ready / form** — `data-ss-enums` ("N common grids · M token fields")
      plus the `data-ss-form` generate form
- [x] **Result** — `data-ss-result` headline (`data-ss-headline` with
      `data-ss-aligned-count`) and the `data-ss-tokens` table of
      `data-ss-token-row` rows (`data-ss-px`, `data-ss-rem`, `data-aligned`)
- [x] **Generate error** — `data-ss-generate-error` for invalid JSON or a
      non-200 response

## Interactions

- [x] **Spacing (JSON)** — `textarea` `data-ss-payload`,
      `aria-label="spacing     json"`, seeded with
      `{ baseUnitPx, multipliers[], gridPx, rootFontSizePx }`
- [x] **Generate spacing** — `button` `data-ss-submit` (`type="submit"`); POSTs
      the parsed JSON to `/v1/admin/studio/spacing-scale/generate`, setting
      `data-ss-result` on a 200 with a valid `result`, or
      `data-ss-generate-error` otherwise
- [x] **Quick-action links** — each `quickAction` `Link` navigates to its
      sibling Studio route (see Layout regions for the 16 targets)

## E2E coverage

**Coverage depth**: deep.

- `studio-lane-console-spacing.spec.ts` covers the original live generator happy
  path and off-grid token branch.
- `studio-design-lane-consoles.spec.ts` adds malformed-JSON client guard, real
  BFF 400 validation detail, exact quick-action href list, loading /
  unauthorized / malformed-catalog fail-closed states, mobile no-overflow, and
  direct BFF 401 / 403 / 400 gates for `/v1/admin/studio/spacing-scale`.

## Data & contracts

- **Reads**: `GET /v1/admin/studio/spacing-scale` on mount — returns the catalog
  (`commonGrids[]`, `tokenFields[]`)
- **Writes**: `POST /v1/admin/studio/spacing-scale/generate` — returns
  `{ result: { tokens[], summary{ tokenCount, alignedCount, misalignedCount } } }`
- **Realtime**: none
- **Caching**: client `fetch` with `cache: 'no-store'`; `buildBffAuthHeaders()`
  attaches the bearer token
- **Auth/role check**: admin-scoped fail-closed — `admin:*` or `admin:studio`,
  401/403 under the studio workspace gate

## Cross-references

- Parent: [`../studio-overview.md`](../studio-overview.md)
- Sibling: [`studio-color-system.md`](./studio-color-system.md),
  [`studio-typography.md`](./studio-typography.md),
  [`studio-component-primitives.md`](./studio-component-primitives.md),
  [`studio-complex-interactions.md`](./studio-complex-interactions.md),
  [`studio-design-language.md`](./studio-design-language.md)
- Component source:
  `apps/oshun/web/src/components/studio/StudioSpacingLayoutWorkspace.tsx`
- BFF store: `apps/oshun/bff/src/studio/` spacing-scale generator behind
  `/v1/admin/studio/spacing-scale`

## Known downstream boundaries

- Current source intentionally uses the flat quick-action panel and no Route Map
  panel; the 2026-07-02 browser spec asserts the exact target list.
- The generator validates alignment against the caller-provided `gridPx`;
  feeding those tokens into a future live theming grid is outside this route's
  current contract.