V1 Web PWA · Surface walkthrough

Studio · Spacing and Layout

A per-surface walkthrough of the V1 Web PWA studio surface: layout, states, interactions, data, and cross-references.

walked + e2e-covered
9sections3 minread
Markdown source
On this page

Context. surface studio · domain design · route /studio/spacing-layout · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/spacing-layout/page.tsx

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.

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 Links — 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#

  • Loading — data-ss-loading ("Loading spacing generator…")
  • Unauthorized — data-ss-unauthorized ("Access restricted.") on 401/403
  • Error — data-ss-error ("Could not load the spacing generator.")
  • Ready / form — data-ss-enums ("N common grids · M token fields") plus the data-ss-form generate form
  • 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)
  • Generate error — data-ss-generate-error for invalid JSON or a non-200 response

Interactions#

  • Spacing (JSON) — textarea data-ss-payload, aria-label="spacing json", seeded with { baseUnitPx, multipliers[], gridPx, rootFontSizePx }
  • 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
  • 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#

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.