Skip to content
Docs
Changelog

Design patterns

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

Markdown

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

RegisterSurfacesAuthorityAgent skills
Operatedashboard, todos, files, settings, authshadcn primitives and tokens; apps/web/PRODUCT.mdui-catalog, ui-sdk, web-design-guidelines; craft when designing
Persuadelanding, marketing, pricingdocs/landing.md; the same tokens through landing.css aliasesdesign-taste-frontend, redesign-existing-projects, stageshow, ui-sdk
Developer docs/docsFumadocs headless (fumadocs-core + fumadocs-mdx) with our own componentsdocs-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

JobSourceSkill
Primitive, form, overlay, empty, toastui-sdk behind the shadcn/ui API in packages/ui/src/componentsui-sdk, ui-catalog, shadcn
Free composites (tree, timeline, pickers)ReUI free registry (@reui); Pro blocks stay outui-catalog
Chat, streaming, tool cardsthe installed AI/chat set, then AI Elementsai-assistant
Charts, sparklines, KPI cardsBklit 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 samplesui-catalog
Motion on an existing controltransitions.dev recipestransitions-dev, emil-design-eng, review-animations
Native (Expo)SwiftUI / Jetpack Compose through @expo/uiexpo-ui, expo-native-ui

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 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): 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, 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; 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. 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 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() 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) 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

  • 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

Edit on GitHubDocumentation is in English.
Cookie settings
We use essential cookies to make our app work. With your consent, we also use optional cookies to improve your experience.

Read our Cookie Policy and Privacy Policy.