--- path: /studio/component-primitives surface: studio domain: design auth: signed-in + studio entitlement source: apps/oshun/web/src/app/studio/component-primitives/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/validate, auth/schema gates, error states, issue/no-issue results, quick actions, and mobile no-overflow.' --- # Studio · Component Primitives ## Purpose Validate a component-primitive composition tree with the real design-system composition + accessibility contract validator: the Composition Validation Lane flags unknown primitives, missing required props, missing accessible names, illegal children, and nested interactive content. It is a live admin console wired to `/v1/admin/studio/component-primitives`, not an in-page simulation. ## Entry points - **Direct URL / bookmark** — `/studio/component-primitives` (signed-in + studio entitlement; admin scope required to validate) - **Sibling Studio routes** — reached via the quick-action panel on color-system, spacing-layout, complex-interactions, and other design/governance pages ## Layout regions `page.tsx` mounts `` and renders `` followed by a single `panel` of quick-action links. - **Shell**: `ShellLayout` chrome with the Studio tab active - **Workspace heading**: `WorkspaceHeading` renders the page `

` "Studio Component Primitives", followed by the `data-component-primitives-summary` paragraph - **Composition Validation Lane**: an `

` `data-cp-lane-heading` ("Composition Validation Lane") section with the load states and, when ready, the validate form and result - **Quick-actions panel**: 17 sibling `quickAction` `Link`s — 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, Complex Interactions, "Back to Spacing/Layout workspace", "Back to Color System workspace", "Back to Typography workspace", and "Back to Design Language workspace". No self-link and no Route Map panel. ## States - [x] **Loading** — `data-cp-loading` ("Loading composition validator…") - [x] **Unauthorized** — `data-cp-unauthorized` ("Access restricted.") on 401/403 - [x] **Error** — `data-cp-error` ("Could not load the composition validator.") - [x] **Ready / form** — `data-cp-enums` ("N primitives · M interactive · K issue codes") plus the `data-cp-form` validate form - [x] **Result** — `data-cp-result` headline (`data-cp-headline` with `data-valid`) plus either the `data-cp-issues` list of `data-cp-issue-row` items (`data-issue-code`, `data-issue-path`) or `data-cp-no-issues` ("No contract violations found.") - [x] **Validate error** — `data-cp-validate-error` for invalid JSON or a non-200 response ## Interactions - [x] **Composition (JSON)** — `textarea` `data-cp-payload`, `aria-label="composition json"`, seeded with `{ composition: { type, props, accessibleName?, children[] } }` - [x] **Validate composition** — `button` `data-cp-submit` (`type="submit"`); POSTs `{ composition }` to `/v1/admin/studio/component-primitives/validate`, setting `data-cp-result` on a 200 with a valid `result`, or `data-cp-validate-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/component-primitives` through the live catalog, malformed-JSON client guard, real BFF 400 validation detail, invalid-composition issue rows, valid-composition no-issues result, 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/component-primitives` on mount — returns the catalog (`primitiveTypes[]`, `interactiveTypes[]`, `issueCodes[]`) - **Writes**: `POST /v1/admin/studio/component-primitives/validate` — body `{ composition }`, returns `{ result: { valid, errorCount, nodeCount, interactiveCount, issues[] } }` - **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-color-system.md`](./studio-color-system.md), [`studio-typography.md`](./studio-typography.md), [`studio-spacing-layout.md`](./studio-spacing-layout.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/StudioComponentPrimitivesWorkspace.tsx` - BFF store: `apps/oshun/bff/src/studio/component-composition-store.ts` behind `/v1/admin/studio/component-primitives` ## 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 canonical primitive catalog is currently the BFF contract in `component-composition-store.ts` (`Stack`, `Card`, `Text`, `Icon`, `Button`, `Link`, `Input`) and is read back through the live catalog before validation.