V1 Web PWA · Surface walkthrough

Studio · Color System

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/color-system · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/color-system/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 colour palettes with the real harmony generator: the Color Harmony Lane rotates a base colour's hue by the canonical harmony offsets (complementary, analogous, triadic, split-complementary, tetradic) to derive a swatch set. It is a live admin console wired to /v1/admin/studio/color-harmony, not an in-page simulation.

Entry points#

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

Layout regions#

page.tsx mounts <ShellLayout active="studio"> and renders <StudioColorSystemWorkspace /> 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 Color System", followed by the data-color-system-summary paragraph
  • Color Harmony Lane: an <h2> data-ch-lane-heading ("Color Harmony Lane") section containing the load states and, when ready, the generate form and result
  • Quick-actions panel: 17 sibling quickAction Links — 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 Typography workspace", "Back to Design Language workspace", and "Back to Studio IA workspace" (/studio). There is no self-link and no Route Map panel.

States#

  • Loading — data-ch-loading ("Loading harmony generator…") while the mount-time GET is in flight
  • Unauthorized — data-ch-unauthorized ("Access restricted.") on a 401/403 from the catalog fetch (admin scope missing)
  • Error — data-ch-error ("Could not load the harmony generator.") on a non-OK or malformed catalog response
  • Ready / form — data-ch-enums ("N harmonies") plus the data-ch-form generate form
  • Result — data-ch-result headline (data-ch-headline with data-ch-base-hsl) and the data-ch-swatches grid of data-ch-swatch tiles (data-ch-swatch-hex)
  • Generate error — data-ch-generate-error for invalid JSON or a non-200 generate response

Interactions#

  • Palette (JSON) — textarea data-ch-payload, aria-label="palette json", seeded with { baseColor, harmony }; updates local payload state
  • Generate palette — button data-ch-submit (type="submit"); on submit POSTs the parsed JSON to /v1/admin/studio/color-harmony/generate, setting data-ch-result on a 200 with a valid result, or data-ch-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/color-system through the live harmony catalog, malformed-JSON client guard, real BFF 400 validation detail, triadic palette generation from #ff0000, exact swatch hues/hexes, 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/color-harmony on mount — returns the harmony catalog (harmonies[])
  • Writes: POST /v1/admin/studio/color-harmony/generate — body { baseColor, harmony }, returns { result: { harmony, baseHsl, swatches[] } }
  • Realtime: none
  • Caching: client fetch with cache: 'no-store'; buildBffAuthHeaders() attaches the bearer token
  • Auth/role check: admin-scoped fail-closed — the BFF route requires admin:* or admin:studio and replies 401 (missing auth) / 403 (admin scope missing) 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 produces deterministic harmony swatches only. Publishing palettes into future production domain theme catalogs is outside this route's current contract.