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
| 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 says.
Sources by job
| Job | Source | Skill |
|---|---|---|
| Primitive, form, overlay, empty, toast | ui-sdk behind the shadcn/ui API in packages/ui/src/components | ui-sdk, ui-catalog, shadcn |
| Free composites (tree, timeline, pickers) | ReUI free registry (@reui); Pro blocks stay out | ui-catalog |
| Chat, streaming, tool cards | the installed AI/chat set, then AI Elements | ai-assistant |
| Charts, sparklines, KPI cards | Bklit UI, the @bklit shadcn registry (MIT, source copied into the app) | bklit-ui, bklit-ui-design, bklit-ui-migrate |
| Product illustrations (faux UI) | Stageshow, kit vendored in apps/web/src/platform/stageshow/ | stageshow |
| Loading states (skeletons) | skullet through MeasuredSkeleton (apps/web/src/platform/skeleton/) and samples | ui-catalog |
| Motion on an existing control | 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
- Controls come from ui-sdk, through
packages/ui. Every control on a web screen is apackages/uiwrapper over a ui-sdk component, chosen and tested with theui-sdkskill as Build a screen with ui-sdk adapts it.apps/webnever imports@ui-sdk/*or lists it in itspackage.json, and never hand-rolls a widget withrole=; a component ui-sdk has andpackages/uilacks gets a wrapper there first.scripts/web-ui-sdk.test.mjschecks 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>inpackages/ui. No other chart library (Recharts, Chart.js, Nivo, Victory, visx, ECharts, ApexCharts, Highcharts, Tremor and the like) is imported inapps/web/srcorpackages/ui/srcor listed in theirpackage.json;scripts/web-chart-library.test.mjsfails if one is. d3 stays allowed, because Bklit components call it. An existing chart moves over withbklit-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/kitwhen a scene needs them) and ships only after its loop passesfilm.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
MeasuredSkeletononly. Every loading skeleton in the web app isMeasuredSkeletonfrom@/platform/skeleton/measured-skeleton: passdataand asampleof the same shape from the feature's<feature>.samples.tsand render from the argument ofchildren, or passloadingover 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. Onlyapps/web/src/platform/skeleton/importsskullet. No hand-madeanimate-pulseboxes, no shadcnSkeletonorSidebarMenuSkeleton, and no other skeleton library (react-loading-skeleton, react-content-loader, MUI, Chakra and the like) inapps/web/srcorpackages/ui/srcor theirpackage.json. Skeletons render only behind sign-in, so the skullet chunk stays off public pages (W15): a public page renders its data from the route loader, or aSpinnerfor a pending action.scripts/web-skeletons.test.mjschecks all of this, including that no route outsideroutes/_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, 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
packages/ui runs on ui-sdk (@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; onlypackages/uiimports@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 inAGENTS.md(UI SDK and craft). - Choose from the skill's table. "The person needs to → Use" in
build-interface.mddecides the component. When it names onepackages/uidoes 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 inpackages/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 fromdata-*attributes. Behaviour ui-sdk does not ship is path 2, also inpackages/ui. Adivwithrole="listbox","menu","dialog","tablist","switch","slider","radiogroup","toolbar"or"tree"inapps/webis a bug. - Know which wrappers are not on ui-sdk.
reui/color-picker(its area, sliders and swatches are plain elements withrole=),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:commandtakes cmdk's (shouldFilter,CommandInput'svalue/onValueChange,heading,onSelect(value)),calendarreact-day-picker's (Datevalues,mode/selected/onSelect,disabledandmodifiersmatchers, whose disabled days stay focusable),carouselembla'soptsandsetApi,resizablereact-resizable-panels v4's sizes and layouts, andreui/treea headless-treetree. Name a resizable group, a carousel, a calendar and a rating witharia-label. - Style with our tokens.
apps/web/PRODUCT.mdand the tokens inpackages/ui/src/styles/globals.cssset the look. Never import@ui-sdk/core/web.css, so skipreferences/styles.md, which documents it. The skill's "declare the ui-sdk layer" rule is already met:globals.cssstarts with@layer ui-sdk;andapps/web/src/index.cssimports 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 inindex.css. Check colour contrast in a real browser, in both themes. - The rest applies as written. Name every control (
FieldLabel,DialogTitle, oraria-labelwithout visible text), and take every visible label from the i18n catalogs;defaultValueto start, orvaluewithonValueChangeto control; key lists by value or id, never by index; no direction provider for right to left; mark delete, pay and send withdata-agent-confirmand secrets withdata-agent-secret; comments are rare, as the repository'sno-commentsskill also says. The skill's typecheck step ispnpm 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.tsholds the skill's jsdom stubs and turns on its strict mode, so a ui-sdk development warning fails the test. Then the agent test fromagent-ready.md:createAgentfrom@template-cloudflare/ui/lib/agent, one bridge per test file, every snapshot entry named, every control the task names in the label check and oneactstep for each. The example issettings.agent.test.tsx. A bug the test finds in code you were only asked to test becomes anit.failswith its reason.checkPattern,mountand the break-it-on-purpose pass are for a new component inpackages/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.tsximportslib/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 does the rest.
Repository rules win over the skill where they disagree: the client/server boundary (ADR-0002), the web feature shape (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
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()callscreateAgent({ allow })the first time the shell mounts in the browser and returns that bridge from then on; ui-sdk's bridge has nodestroy, so it is never created per render or per route. Nothing runs on the server. - A person confirms.
allowlets every step through except one on adata-agent-confirmcontrol. That step waits for ourAlertDialog: the title and hint come from theLIVE_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 carriesdata-agent-hidden, so an agent can neither read nor press Allow. There is never awindow.confirm. - Marks. Each delete, pay and send action puts
data-agent-confirm={t("<FEATURE>_AGENT_CONFIRM_…")}on the button that confirms (theAlertDialogAction, 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 carrydata-agent-secret; a one-time secret on screen (2FA setup, backup codes, a new webhook secret) sits indata-agent-hidden.scripts/web-ui-sdk.test.mjsfails when anAlertDialogActionor 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 nodata-agent-secret. - WebMCP behind
ui.webmcp. With the flag on (off by default, set at/admin/flags) and a browser that hasdocument.modelContext,registerTools(agent, { allow: () => true })gives the browser's own agentsnapshot,actandquery. Itsallowanswers yes because the bridge'sallowhas already asked the person; a marked step still opens our dialog, once. Turning the flag off or leaving the app unregisters the tools. Withoutdocument.modelContextnothing is registered. - Not yet. The in-app assistant (ADR-0007) does not call
snapshot,actorqueryas 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
- Tokens, not values. A component reads
--primary,--card,--radiusand 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'splatform/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 --gatebefore 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
apps/web/PRODUCT.mddocs/landing.mdpackages/ui/components.jsonscripts/web-ui-sdk.test.mjsapps/web/src/features/settings/settings.agent.test.tsxapps/web/src/platform/agent/live-agent.tsx.agents/skills/ui-catalog/SKILL.mdscripts/web-chart-library.test.mjsapps/web/src/platform/skeleton/measured-skeleton.tsxscripts/web-skeletons.test.mjs