# Design patterns

Which design source, kit and agent skill each surface uses, and the rules that keep a rebrand cheap.

The template's visual identity lives in tokens (`packages/ui/src/styles/globals.css`), and every surface composes from owned source in `packages/ui`. `apps/web/PRODUCT.md` holds the principles and anti-references; read it before any UI work. This page says which tool each job uses, so a project built from the template keeps one design language as it grows.

## Three registers [#three-registers]

| Register       | Surfaces                                | Authority                                                                    | Agent skills                                                                 |
| -------------- | --------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| Operate        | dashboard, todos, files, settings, auth | shadcn primitives and tokens; `apps/web/PRODUCT.md`                          | `ui-catalog`, `ui-sdk`, `web-design-guidelines`; `craft` when designing      |
| Persuade       | landing, marketing, pricing             | `docs/landing.md`; the same tokens through `landing.css` aliases             | `design-taste-frontend`, `redesign-existing-projects`, `stageshow`, `ui-sdk` |
| Developer docs | `/docs`                                 | Fumadocs headless (`fumadocs-core` + `fumadocs-mdx`) with our own components | `docs-and-changelog`                                                         |

An agent picks the register first (`ui-catalog` step 1), then loads only that register's skills. Taste guidance never reaches an Operate screen. Every interactive control, on any register, is built the way [Build a screen with ui-sdk](#build-a-screen-with-ui-sdk) says.

## Sources by job [#sources-by-job]

| Job                                       | Source                                                                                                          | Skill                                                     |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Primitive, form, overlay, empty, toast    | [ui-sdk](https://ui-sdk.dev) behind the [shadcn/ui](https://ui.shadcn.com) API in `packages/ui/src/components`  | `ui-sdk`, `ui-catalog`, `shadcn`                          |
| Free composites (tree, timeline, pickers) | [ReUI](https://reui.io) free registry (`@reui`); Pro blocks stay out                                            | `ui-catalog`                                              |
| Chat, streaming, tool cards               | the installed AI/chat set, then [AI Elements](https://elements.ai-sdk.dev)                                      | `ai-assistant`                                            |
| Charts, sparklines, KPI cards             | [Bklit UI](https://bklit.com), the `@bklit` shadcn registry (MIT, source copied into the app)                   | `bklit-ui`, `bklit-ui-design`, `bklit-ui-migrate`         |
| Product illustrations (faux UI)           | [Stageshow](https://benji.org/stageshow), kit vendored in `apps/web/src/platform/stageshow/`                    | `stageshow`                                               |
| Loading states (skeletons)                | [skullet](https://skullet.lochie.me) through `MeasuredSkeleton` (`apps/web/src/platform/skeleton/`) and samples | `ui-catalog`                                              |
| Motion on an existing control             | [transitions.dev](https://transitions.dev) recipes                                                              | `transitions-dev`, `emil-design-eng`, `review-animations` |
| Native (Expo)                             | SwiftUI / Jetpack Compose through `@expo/ui`                                                                    | `expo-ui`, `expo-native-ui`                               |

## Four rules with no alternative [#four-rules-with-no-alternative]

- **Controls come from ui-sdk, through `packages/ui`.** Every control on a web screen is a `packages/ui` wrapper over a ui-sdk component, chosen and tested with the `ui-sdk` skill as [Build a screen with ui-sdk](#build-a-screen-with-ui-sdk) adapts it. `apps/web` never imports `@ui-sdk/*` or lists it in its `package.json`, and never hand-rolls a widget with `role=`; a component ui-sdk has and `packages/ui` lacks gets a wrapper there first. `scripts/web-ui-sdk.test.mjs` checks the imports and the dependency.
- **Charts come from Bklit UI only.** Every chart, sparkline and KPI or stat card on the web is a Bklit component, installed with `pnpm dlx shadcn@latest add @bklit/<item>` in `packages/ui`. No other chart library (Recharts, Chart.js, Nivo, Victory, visx, ECharts, ApexCharts, Highcharts, Tremor and the like) is imported in `apps/web/src` or `packages/ui/src` or listed in their `package.json`; `scripts/web-chart-library.test.mjs` fails if one is. d3 stays allowed, because Bklit components call it. An existing chart moves over with `bklit-ui-migrate`.
- **Product illustrations are built with Stageshow only.** Faux product UI on landing, marketing and docs pages (stills, feature cards, cursor demos, bento grids) starts from a Stageshow gold example, uses the kit in `apps/web/src/platform/stageshow/` (copy more parts from `.agents/skills/stageshow/kit` when a scene needs them) and ships only after its loop passes `film.mjs --gate`. A chart inside a scene is a Bklit chart placed on the stage, since Stageshow takes the app's own components. Review holds this rule.
- **Loading skeletons are skullet, through `MeasuredSkeleton` only.** Every loading skeleton in the web app is `MeasuredSkeleton` from `@/platform/skeleton/measured-skeleton`: pass `data` and a `sample` of the same shape from the feature's `<feature>.samples.ts` and render from the argument of `children`, or pass `loading` over content already on screen (a refetch). The wrapper adds the translated label; the provider in the signed-in layout sets the reveal and the theme, and the colours are the `--skullet-*` tokens. Only `apps/web/src/platform/skeleton/` imports `skullet`. No hand-made `animate-pulse` boxes, no shadcn `Skeleton` or `SidebarMenuSkeleton`, and no other skeleton library (react-loading-skeleton, react-content-loader, MUI, Chakra and the like) in `apps/web/src` or `packages/ui/src` or their `package.json`. Skeletons render only behind sign-in, so the skullet chunk stays off public pages ([W15](/docs/development/web-conventions)): a public page renders its data from the route loader, or a `Spinner` for a pending action. `scripts/web-skeletons.test.mjs` checks all of this, including that no route outside `routes/_auth/` reaches the wrapper through its imports.

Bklit draws DOM and SVG for React on the web and has no React Native build, so the chart rule stops at `apps/web` and `packages/ui`. A chart in the Expo app uses [`victory-native`](https://commerce.nearform.com/open-source/victory-native), which draws with Skia, Reanimated and Gesture Handler, all already in `apps/mobile`; add it with `expo install` with the first mobile chart (it needs a newer Skia than the app pins today). An iOS-only screen may use `Chart` from `@expo/ui/swift-ui` (Swift Charts) instead.

Skullet measures the DOM and ships React, Vue, Svelte and web-component builds, but none for React Native, so the skeleton rule stops at the web too. A loading list in the Expo app uses `SkeletonRows` from `apps/mobile/src/design` (a still placeholder with the metrics of a `SettingRow` group and a spoken label).

The shadcn `skeleton.tsx` stays in `packages/ui` because the vendored shadcn sidebar (`SidebarMenuSkeleton`) and the ReUI emoji picker draw their own loading state with it; app code does not import either. The wrapper covers skullet's `Skeleton` only: a Suspense fallback (`SkeletonSuspense`) or a placeholder box (`SkeletonBox`) gets its own wrapper in `platform/skeleton/` when a screen first needs one, never a direct import. Passing `id` keeps a skeleton's shape in `localStorage`; the change that first does so also calls `forgetShapes()` on sign-out.

Two surfaces predate these rules: the dashboard KPI cards (`dashboard.stat-card.tsx`, plain number cards) and the hand-built fragments of the landing feature board (`landing.feature-*.tsx`). Do not copy them as patterns; move them to Bklit and Stageshow when you rework them.

## Build a screen with ui-sdk [#build-a-screen-with-ui-sdk]

`packages/ui` runs on [ui-sdk](https://ui-sdk.dev) (`@ui-sdk/react`), which ships an agent skill for building interfaces with it. `.agents/skills/ui-sdk` (and its `.claude/skills` mirror) links to that skill inside the installed `@ui-sdk/core`, so every agent loads `$ui-sdk` at the version `packages/ui` pins; `scripts/web-ui-sdk.test.mjs` checks the link and the version. A new or reworked `apps/web` screen follows the skill: path 1 (`references/build-interface.md`) for the screen, path 2 (`references/create-component.md`) for a part ui-sdk does not ship, then `references/agent-ready.md` and `references/testing.md`. Component pages are in `packages/ui/node_modules/@ui-sdk/react/docs/` (start at `llms.txt`); the installed `.d.ts` wins over them.

The skill is written for an app that imports `@ui-sdk/*` itself. Here it applies with these changes:

- **Import the wrappers.** App code imports `@template-cloudflare/ui/components/<name>`, the shadcn API; only `packages/ui` imports `@ui-sdk/*`. Read the skill's examples as the ui-sdk parts behind each wrapper: the same composition under shadcn names (`SelectTrigger`, `DialogContent`). The migration notes for wrappers are in `AGENTS.md` (UI SDK and craft).
- **Choose from the skill's table.** "The person needs to → Use" in `build-interface.md` decides the component. When it names one `packages/ui` does not wrap yet (Listbox, Toolbar, Segmented Control, Meter, Password, Date or Time Input, Date Picker, File Input, Color Picker, Trigger Menu, Token Input, Command pages), the screen first adds a wrapper on that entry in `packages/ui/src/components/<name>.tsx`, built like the existing ones: shadcn part names and classes, semantic tokens, `cn`, `withSlot` (`packages/ui/src/lib/with-slot.ts`) to keep the shadcn slot name, and state styled from `data-*` attributes. Behaviour ui-sdk does not ship is path 2, also in `packages/ui`. A `div` with `role="listbox"`, `"menu"`, `"dialog"`, `"tablist"`, `"switch"`, `"slider"`, `"radiogroup"`, `"toolbar"` or `"tree"` in `apps/web` is a bug.
- **Know which wrappers are not on ui-sdk.** `reui/color-picker` (its area, sliders and swatches are plain elements with `role=`), `native-select` (a bare `<select>`) and the ReUI composites that draw their own roles (`time-picker`, `emoji-picker`, `signature-pad`, `stepper`, and the cascader's items and footer) are not on a ui-sdk control. People can use them, but the agent bridge cannot see those parts; a screen that needs one as a control an agent fills ports it to its ui-sdk entry first (`color-picker`, `select`, `time-input`, `listbox`). The ported wrappers keep their old props: `command` takes cmdk's (`shouldFilter`, `CommandInput`'s `value`/`onValueChange`, `heading`, `onSelect(value)`), `calendar` react-day-picker's (`Date` values, `mode`/`selected`/`onSelect`, `disabled` and `modifiers` matchers, whose disabled days stay focusable), `carousel` embla's `opts` and `setApi`, `resizable` react-resizable-panels v4's sizes and layouts, and `reui/tree` a headless-tree `tree`. Name a resizable group, a carousel, a calendar and a rating with `aria-label`.
- **Style with our tokens.** `apps/web/PRODUCT.md` and the tokens in `packages/ui/src/styles/globals.css` set the look. Never import `@ui-sdk/core/web.css`, so skip `references/styles.md`, which documents it. The skill's "declare the ui-sdk layer" rule is already met: `globals.css` starts with `@layer ui-sdk;` and `apps/web/src/index.css` imports it first, so the CSS ui-sdk adds at runtime (hidden parts, a reset of the browser's popover box, the toast region) stays below Tailwind's layers wherever it lands. Do not repeat the line in `index.css`. Check colour contrast in a real browser, in both themes.
- **The rest applies as written.** Name every control (`FieldLabel`, `DialogTitle`, or `aria-label` without visible text), and take every visible label from the i18n catalogs; `defaultValue` to start, or `value` with `onValueChange` to control; key lists by value or id, never by index; no direction provider for right to left; mark delete, pay and send with `data-agent-confirm` and secrets with `data-agent-secret`; comments are rare, as the repository's `no-comments` skill also says. The skill's typecheck step is `pnpm check-types`.
- **Test the screen.** Wiring tests with Testing Library in jsdom: Space on every switch and checkbox the screen places, every button in every dialog, each required field submitted empty, focus back where it belongs when a dialog or menu closes, and button names read from the page's own markup. `apps/web/src/test-setup.ts` holds the skill's jsdom stubs and turns on its strict mode, so a ui-sdk development warning fails the test. Then the agent test from `agent-ready.md`: `createAgent` from `@template-cloudflare/ui/lib/agent`, one bridge per test file, every snapshot entry named, every control the task names in the label check and one `act` step for each. The example is [`settings.agent.test.tsx`](https://github.com/CarlosZiegler/template-cloudflare/blob/main/apps/web/src/features/settings/settings.agent.test.tsx). A bug the test finds in code you were only asked to test becomes an `it.fails` with its reason. `checkPattern`, `mount` and the break-it-on-purpose pass are for a new component in `packages/ui` (its jsdom tests start with `// @vitest-environment jsdom`), not for a screen made of ours.
- **One agent at runtime.** Besides tests, only `apps/web/src/platform/agent/live-agent.tsx` imports `lib/agent` (`scripts/web-ui-sdk.test.mjs`). A screen never creates its own bridge: it marks its controls, and the [agent on the live page](#agent-on-the-live-page) does the rest.

Repository rules win over the skill where they disagree: the [client/server boundary](/docs/architecture/client-server-boundary) (ADR-0002), the [web feature shape](/docs/development/web-conventions) (ADR-0012), i18n, and `PRODUCT.md` for the look. The skill wins over generic design skills (`craft`, `design-taste-frontend`, `web-design-guidelines`, `shadcn`) on which component to use, how its parts compose, behaviour, accessibility and tests.

### Agent on the live page [#agent-on-the-live-page]

The signed-in app runs one agent bridge, from `apps/web/src/platform/agent/live-agent.tsx`. `AppShell` mounts `AppLiveAgent` (`features/app-shell/app-shell.live-agent.tsx`), which renders `LiveAgent` with the `ui.webmcp` flag.

- **One bridge.** `liveAgent()` calls `createAgent({ allow })` the first time the shell mounts in the browser and returns that bridge from then on; ui-sdk's bridge has no `destroy`, so it is never created per render or per route. Nothing runs on the server.
- **A person confirms.** `allow` lets every step through except one on a `data-agent-confirm` control. That step waits for our `AlertDialog`: the title and hint come from the `LIVE_AGENT_*` keys, the description is the mark's own sentence, and Cancel ("Don't allow") is the first Close part, so it has the focus. Cancel, Escape, the bridge's five-minute timeout and the shell unmounting all refuse the step, and the press never runs. The dialog itself carries `data-agent-hidden`, so an agent can neither read nor press Allow. There is never a `window.confirm`.
- **Marks.** Each delete, pay and send action puts `data-agent-confirm={t("<FEATURE>_AGENT_CONFIRM_…")}` on the button that confirms (the `AlertDialogAction`, the submit, the menu item that acts), never on the trigger that only opens a dialog. The sentence names what happens, from app state: "Removes Grace Hopper from this organization." Password and one-time-code inputs carry `data-agent-secret`; a one-time secret on screen (2FA setup, backup codes, a new webhook secret) sits in `data-agent-hidden`. `scripts/web-ui-sdk.test.mjs` fails when an `AlertDialogAction` or a button whose handler deletes, removes, revokes, rotates, purges, bans, sends or impersonates has no mark, when a known mark or its sentence goes missing, and when a password input has no `data-agent-secret`.
- **WebMCP behind `ui.webmcp`.** With the flag on (off by default, set at `/admin/flags`) and a browser that has `document.modelContext`, `registerTools(agent, { allow: () => true })` gives the browser's own agent `snapshot`, `act` and `query`. Its `allow` answers yes because the bridge's `allow` has already asked the person; a marked step still opens our dialog, once. Turning the flag off or leaving the app unregisters the tools. Without `document.modelContext` nothing is registered.
- **Not yet.** The in-app assistant ([ADR-0007](/docs/adr/0007-ai-assistant-and-tool-catalog)) does not call `snapshot`, `act` or `query` as tools; that is an owner decision.

Tests: `platform/agent/live-agent.test.tsx` (our dialog opens, Cancel and Escape refuse, Allow runs the action, the agent cannot see the dialog, unmounting refuses) and `features/app-shell/app-shell.live-agent.test.tsx` (no tools with the flag off or without `document.modelContext`, registered when on, removed when off or unmounted, a marked WebMCP step asks once).

## Rules that keep it consistent [#rules-that-keep-it-consistent]

- **Tokens, not values.** A component reads `--primary`, `--card`, `--radius` and the rest; a registry's own colors and fonts are mapped onto them, never copied. A kit with its own token layer (Stageshow's `--ss-*`, Bklit's chart colors) is aliased to ours in one place.
- **Owned source.** Registry items are copied into `packages/ui` (or a feature's `platform/` folder) and exported one subpath at a time. Diff before accepting an overwrite: local files carry React Compiler and test edits.
- **Every state ships.** Loading, empty and error are part of the screen, because developers copy what the template shows.
- **A skeleton is drawn from the real component.** A loading state is measured from a sample of the component it stands in for (`<feature>.samples.ts`), never hand-built from boxes, so nothing moves when the data lands.
- **Honest illustrations.** Faux UI on landing, marketing and docs pages uses the product's own strings from the locale catalogs, shows only features the template has, and is labelled as an illustration. A Stageshow scene passes `film.mjs --gate` before it ships.
- **Motion respects the reader.** Every animation has a reduced-motion state, pauses off screen, and starts when it can be seen.
- **Weight is measured.** A new kit or registry item records its gzip delta on the route it lands in, in `docs/measurements/`.

## Key files [#key-files]

- [`apps/web/PRODUCT.md`](https://github.com/CarlosZiegler/template-cloudflare/blob/main/apps/web/PRODUCT.md)
- [`docs/landing.md`](https://github.com/CarlosZiegler/template-cloudflare/blob/main/docs/landing.md)
- [`packages/ui/components.json`](https://github.com/CarlosZiegler/template-cloudflare/blob/main/packages/ui/components.json)
- [`scripts/web-ui-sdk.test.mjs`](https://github.com/CarlosZiegler/template-cloudflare/blob/main/scripts/web-ui-sdk.test.mjs)
- [`apps/web/src/features/settings/settings.agent.test.tsx`](https://github.com/CarlosZiegler/template-cloudflare/blob/main/apps/web/src/features/settings/settings.agent.test.tsx)
- [`apps/web/src/platform/agent/live-agent.tsx`](https://github.com/CarlosZiegler/template-cloudflare/blob/main/apps/web/src/platform/agent/live-agent.tsx)
- [`.agents/skills/ui-catalog/SKILL.md`](https://github.com/CarlosZiegler/template-cloudflare/blob/main/.agents/skills/ui-catalog/SKILL.md)
- [`scripts/web-chart-library.test.mjs`](https://github.com/CarlosZiegler/template-cloudflare/blob/main/scripts/web-chart-library.test.mjs)
- [`apps/web/src/platform/skeleton/measured-skeleton.tsx`](https://github.com/CarlosZiegler/template-cloudflare/blob/main/apps/web/src/platform/skeleton/measured-skeleton.tsx)
- [`scripts/web-skeletons.test.mjs`](https://github.com/CarlosZiegler/template-cloudflare/blob/main/scripts/web-skeletons.test.mjs)
