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

# Studio · Design Language

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

- [x] **Loading** — `data-dt-loading` ("Loading token resolver…")
- [x] **Unauthorized** — `data-dt-unauthorized` ("Access restricted.") on
      401/403
- [x] **Error** — `data-dt-error` ("Could not load the token resolver.")
- [x] **Ready / form** — `data-dt-enums` ("N token issue codes") plus the
      `data-dt-form` resolve form
- [x] **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`)
- [x] **Resolve error** — `data-dt-resolve-error` for invalid JSON or a non-200
      response

## Interactions

- [x] **Tokens (JSON)** — `textarea` `data-dt-payload`,
      `aria-label="design     tokens json"`, seeded with
      `{ tokens[{ tokenId, value: string | { alias } }]     }`
- [x] **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
- [x] **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

- Parent: [`../studio-overview.md`](../studio-overview.md)
- Sibling: [`studio-typography.md`](./studio-typography.md),
  [`studio-color-system.md`](./studio-color-system.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)
- Component source:
  `apps/oshun/web/src/components/studio/StudioDesignLanguageWorkspace.tsx`
- Design-system primitives live under the `design-system/lilith/` directory (no
  single `design-system/lilith.ts` file)
- BFF store: `apps/oshun/bff/src/studio/` design-token resolver behind
  `/v1/admin/studio/design-tokens`

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