---
path: /studio/color-system
surface: studio
domain: design
auth: signed-in + studio entitlement
source: apps/oshun/web/src/app/studio/color-system/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 · Color System

## 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` `Link`s — 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

- [x] **Loading** — `data-ch-loading` ("Loading harmony generator…") while the
      mount-time GET is in flight
- [x] **Unauthorized** — `data-ch-unauthorized` ("Access restricted.") on a
      401/403 from the catalog fetch (admin scope missing)
- [x] **Error** — `data-ch-error` ("Could not load the harmony generator.") on a
      non-OK or malformed catalog response
- [x] **Ready / form** — `data-ch-enums` ("N harmonies") plus the `data-ch-form`
      generate form
- [x] **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`)
- [x] **Generate error** — `data-ch-generate-error` for invalid JSON or a
      non-200 generate response

## Interactions

- [x] **Palette (JSON)** — `textarea` `data-ch-payload`,
      `aria-label="palette     json"`, seeded with `{ baseColor, harmony }`;
      updates local payload state
- [x] **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
- [x] **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

- Parent: [`../studio-overview.md`](../studio-overview.md)
- Sibling: [`studio-typography.md`](./studio-typography.md),
  [`studio-spacing-layout.md`](./studio-spacing-layout.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/StudioColorSystemWorkspace.tsx`
- BFF route: `apps/oshun/bff/src/routes/admin-studio-color-harmony.ts` (store:
  `apps/oshun/bff/src/studio/color-harmony-store.ts`)

## 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.