V1 Web PWA · Surface walkthrough

Studio · Typography

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/typography · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/typography/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 a modular type scale with the real generator: the Type Scale Lane computes font size = base × ratio^step and snaps each line height up to the baseline grid for vertical rhythm. It is a live admin console wired to /v1/admin/studio/type-scale, not an in-page simulation.

Entry points#

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

Layout regions#

page.tsx mounts <ShellLayout active="studio"> and renders <StudioTypographyWorkspace /> 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 Typography", followed by the data-typography-summary paragraph
  • Type Scale Lane: an <h2> data-ts-lane-heading ("Type Scale Lane") section with the load states and, when ready, the generate form and result table
  • Quick-actions panel: 17 sibling quickAction Links — Color System, Spacing/Layout, 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 Design Language workspace", and "Back to Studio IA workspace" (/studio). No self-link and no Route Map panel.

States#

  • Loading — data-ts-loading ("Loading type-scale generator…")
  • Unauthorized — data-ts-unauthorized ("Access restricted.") on 401/403
  • Error — data-ts-error ("Could not load the type-scale generator.")
  • Ready / form — data-ts-enums ("N common ratios") plus the data-ts-form generate form
  • Result — data-ts-result headline (data-ts-headline with data-ts-range) and the data-ts-scale table of data-ts-step-row rows (data-ts-font, data-ts-line-height)
  • Generate error — data-ts-generate-error for invalid JSON or a non-200 response

Interactions#

  • Scale (JSON) — textarea data-ts-payload, aria-label="type scale json", seeded with { baseSizePx, ratio, steps[], lineHeightMultiplier, baselineGridPx }
  • Generate scale — button data-ts-submit (type="submit"); POSTs the parsed JSON to /v1/admin/studio/type-scale/generate, setting data-ts-result on a 200 with a valid result, or data-ts-generate-error otherwise
  • Quick-action links — each quickAction Link navigates to its sibling Studio route (see Layout regions for the 17 targets)

E2E coverage#

Coverage depth: deep.

  • studio-design-lane-consoles.spec.ts drives /studio/typography through the live catalog, malformed-JSON client guard, real BFF 400 validation detail, successful modular-scale generation, 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/type-scale on mount — returns the catalog (commonRatios{})
  • Writes: POST /v1/admin/studio/type-scale/generate — returns { result: { scale[], summary{ stepCount, minFontSizePx, maxFontSizePx } } }
  • 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 snaps to the caller-provided baselineGridPx; feeding the scale into a future live theming pipeline is outside this route's current contract.