V1 Web PWA · Surface walkthrough

Studio · Design Language

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/design-language · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/design-language/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/resolve, auth/schema gates, error states, quick actions, and mobile no-overflow.

Purpose#

Resolve design-token aliases with the real resolver: the Token Resolution Lane follows each token's alias chain to its final literal value, reports the alias depth, and flags missing and circular references. It is a live admin console wired to /v1/admin/studio/design-tokens, not an in-page simulation.

Entry points#

  • Direct URL / bookmark — /studio/design-language (signed-in + studio entitlement; admin scope required to resolve)
  • 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 <StudioDesignLanguageWorkspace /> 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 Design Language", followed by the data-design-language-summary paragraph
  • Token Resolution Lane: an <h2> data-dt-lane-heading ("Token Resolution Lane") section with the load states and, when ready, the resolve form and result table
  • Quick-actions panel: 19 sibling quickAction Links — Typography, Color System, Spacing/Layout, Component Primitives, Complex Interactions, Navigation/Commands, 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 Studio IA workspace" (/studio), and "Back to Explore" (/explore). No self-link and no Route Map panel.

States#

  • Loading — data-dt-loading ("Loading token resolver…")
  • Unauthorized — data-dt-unauthorized ("Access restricted.") on 401/403
  • Error — data-dt-error ("Could not load the token resolver.")
  • Ready / form — data-dt-enums ("N token issue codes") plus the data-dt-form resolve form
  • Result — data-dt-result headline (data-dt-headline with data-dt-resolved-count, data-dt-circular-count) and the data-dt-tokens table of data-dt-token-row rows (data-dt-resolved-value, data-dt-depth, data-dt-issue)
  • Resolve error — data-dt-resolve-error for invalid JSON or a non-200 response

Interactions#

  • Tokens (JSON) — textarea data-dt-payload, aria-label="design tokens json", seeded with { tokens[{ tokenId, value: string | { alias } }] }
  • Resolve tokens — button data-dt-submit (type="submit"); POSTs the parsed JSON to /v1/admin/studio/design-tokens/resolve, setting data-dt-result on a 200 with a valid result, or data-dt-resolve-error otherwise
  • Quick-action links — each quickAction Link navigates to its sibling Studio route or back to Explore (see Layout regions for the 19 targets)

E2E coverage#

Coverage depth: deep.

  • studio-design-lane-consoles.spec.ts drives /studio/design-language through the live token-issue catalog, malformed-JSON client guard, real BFF 400 duplicate-token validation detail, successful alias-chain resolution, missing alias and circular alias rows, exact quick-action href list, loading / unauthorized / malformed-catalog fail-closed states, mobile no-overflow, and direct BFF 401 / 403 / 400 gates.

Data & contracts#

  • Reads: GET /v1/admin/studio/design-tokens on mount — returns the catalog (tokenIssues[])
  • Writes: POST /v1/admin/studio/design-tokens/resolve — returns { result: { tokens[], summary{ tokenCount, resolvedCount, missingCount, circularCount } } }
  • 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 current route resolves arbitrary caller-provided token graphs. Validating against a future production theme catalog is outside this route's current contract.