# 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`, `web-design-guidelines`                              |
| Persuade       | landing, marketing, pricing             | `docs/landing.md`; the same tokens through `landing.css` aliases             | `design-taste-frontend`, `redesign-existing-projects`, `stageshow` |
| 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.

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

| Job                                       | Source                                                                                                          | Skill                                                     |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| Primitive, form, overlay, empty, toast    | [shadcn/ui](https://ui.shadcn.com), installed in `packages/ui/src/components`                                   | `shadcn`, `ui-catalog`                                    |
| 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`         |
| Faux product UI on the landing            | [Stageshow](https://github.com/benjitaylor/skills), kit vendored in `apps/web/src/platform/stageshow/`          | `stageshow`                                               |
| Loading states (skeletons)                | [skullet](https://skullet.lochie.me), wrapped in `apps/web/src/platform/skeleton/` with sample data per feature | —                                                         |
| 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`, `building-native-ui`                           |

No screen draws a chart yet. The shadcn `chart` wrapper (Recharts) is installed but unused; a new chart comes from `@bklit`, and `bklit-ui-migrate` moves a Recharts chart over.

## 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 the landing 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)
- [`.agents/skills/ui-catalog/SKILL.md`](https://github.com/CarlosZiegler/template-cloudflare/blob/main/.agents/skills/ui-catalog/SKILL.md)