Design

---
name: design
description: Design a site built on agentic-cms, from the wireframe to a look of its own or from one look to the next - tokens first, then the chrome, then the sections - one element at a time through candidates the owner picks from, a build on the dev server the owner looks at, and a pixel proof before anything merges. Use when asked to design, restyle, theme, brand, redesign or "make it look like" anything on the site, or to start designing a site from scratch.
argument-hint: [what to design: the whole site, a section, the chrome, the tokens]
---

# Design

The repo is the current directory: a site on `agentic-cms`, its design in
`STANDARD.md` (the tokens, the type, the markup rules, the section anatomy,
the motion, the register of decisions that look like bugs) and in
`src/components/`; the engine, the content and the SEO are not the design
and do not change here. The owner decides what it looks like; this skill's
job is to make each decision cheap to take and impossible to lose.

## Read first

`STANDARD.md` in full (what exists, and §8, the decisions that must not be
"fixed"); `src/components/README.md` (the catalogue: one implementation per
shared element, cards per section); `src/app/globals.css` (the `@theme
static` block, the only place a token lives) and `src/styles/base.css`;
`AGENTS.md` § Styling; `docs/design.md` of the kit
(`node_modules/agentic-cms/docs/design.md` on a site that installs it).
Then look, not guess: `pnpm build` and `pnpm kit shot / --width 1440`,
`--width 390`, one shot per page the job touches (`.parity/shots/`).

## The copy first

A design is drawn around the site's own words, so the copy comes before
any round. `pnpm content:lint` says whether it is there: a `placeholder`
line is the starter's copy (a site from `agentic-cms init` starts with its
home page, its blog index and the tagline in `src/config/site.ts` marked
`(placeholder)`), an `example-brand` line is the kit example's brand (its
name, its domain, its author). Get the copy first — from the owner, or
`/editorial:new-page`, which writes a page's real copy and removes the
marker — and never design around a placeholder, the example's brand or its
sample content. `pnpm kit demo new` says so too, naming the fields, before
it writes a round on such a page: stop there and get the copy. <!-- required -->

## The order

Design lands in this order, each step its own branch, its own look on the
dev server and its own commit; never all at once.

1. **Tokens.** Colours (in each scheme the profile names — `schemes` in
   `src/config/harness.ts`; a `light-dark()` pair on a site with two),
   the fonts (self-hosted or system; the build fetches nothing), the type
   scale, the spacing rhythm, and — re-enabled as tokens, not utilities —
   radius, shadow, blur, easing. A colour becomes a token at its second use.
   The wireframe's four colours are the seed; a design has more, named for
   what they are for (`paper`, `ink`, `accent`), never for their hue. Where
   the site has role tokens (`panel`, `line`, `on-ink`, the radius and
   shadow roles, the headings' letter-spacing and `--tracking-label`: a
   site from `init` since 0.8.0 starts with them at the wireframe's values,
   an older one has them once it added them), the design gives the roles
   their values first: every component that asks for a role follows.
2. **The chrome.** The navbar, the footer, the buttons, the title block:
   shared once in `src/components/ui/`, never pasted into a page. Every
   state (hover, focus, current page, open menu) is part of it.
3. **The sections**, one at a time, in the order a visitor meets them. Each
   section's card content is its own, inside the site's card frame where
   it has one (`ui/Panel` on a site that has the example's), and a card is
   not a generic component.
4. **Motion**, last, in the layer the site has (its `STANDARD.md` §7): a
   motion folder of the site's own while it keeps one, otherwise
   `agentic-cms/ix`. Where the layout renders `motionScript()`, the
   play-once layer (`Reveal`, `RevealGroup`, `Sequence`, `part()`) is the
   default, timed by the `--ease-*` / `--motion-*` tokens, and `Fx` and
   `OnView` serve only where a replay on re-entry is wanted. A site that
   moves with `Fx` and `OnView` and renders no `motionScript()` keeps them
   — `data-ix` targets, every animated component honouring
   `useReducedMotionPref()` — and takes the play-once layer only on the
   owner's word (`docs/migrating-to-0.8.0.md` § 3.5 of the kit). A site
   with no motion yet starts with the play-once layer: `motionScript()`
   and the layer's block of `motion.css` first, as that section says.
   Start states and keyframes live in `src/styles/motion.css`; a sequence
   longer than two seconds declares `data-settle` on its section (`settle`
   on a `Sequence`).

## The loop, per element

1. **Candidates.** Two to four, never one: the `design-options` skill —
   static candidates (marks, chips, palettes) on a sheet (`pnpm kit sheet`),
   live ones (a footer, a menu, a hover) on a throwaway demo route the owner
   opens on the dev server. Rendered at the real size, on the real
   background, the current version last for comparison.
2. **The pick.** The owner names a row ("B", "the alternate", "A with B's
   icons"). A pick from a sheet is a direction; the owner's look at the
   built thing on the dev server is the decision. One preview round, one
   build; a question in the chat beats another round of candidates.
3. **Build it** on the branch: tokens in `globals.css`, utilities in the
   component, a `<Name>.module.css` only for what utilities cannot say,
   decorative elements as real `aria-hidden` elements, icons as SVG. One
   instance means the class: a look the owner chose for one card is applied
   to every card of its kind in the same job (`pnpm kit probe` and `grep`
   find them all first).
4. **Prove it**: the `design-proof` skill. A change that must not move a
   pixel elsewhere shows it (`visual-parity` clean outside the changed
   section, the `SIZE` verdict `shift` where a section grew); a design
   change is its own commit and says so in the message.
5. **Record it.** Anything that looks like a bug on purpose (an element at
   `opacity: 0` until JavaScript runs, the outer cards hidden at a width, a
   glow only above 1440 px) goes into `STANDARD.md` §8 with the reason and
   the date; a new token, family or rule goes into the section it belongs
   to; a new shared component into `src/components/README.md`.

## Rules that survive every look

- Utilities for layout, spacing, type, colour, visibility, hover and focus;
  tokens only in `@theme static`; one colour utility per property per
  element; never `text-base` / `text-sm` — the type scale is the site's.
- Images stay `<img>` with `width`, `height` and `alt`; above the fold in a
  server component `EagerImage`; below it `loading="lazy"`.
- Nothing hides until JavaScript runs unless a reveal owns it, and then the
  HTML a crawler receives is complete.
- A demo route never merges (it has no `seo` block; the build fails on it,
  on purpose). The design's throwaway files go with the branch.
- Public URLs never change for a look.
- A round starts from the page's content file and never writes copy into
  a candidate: the candidates take the page's copy from its file (`demo
  new --section` reads it on every render), and copy the page lacks goes
  into the page file and its schema first; `agentic-cms/copy` fails copy
  in code, a round's route and its candidates included. <!-- required -->

## Verify

End the procedure with `pnpm lint`, 0 failures, after the last edit: it
holds the engines in every file (copy, head, forms, tags, e-mail) and the
library's placement, and a failure is fixed at its source, never by
loosening a rule. <!-- required -->

```bash
pnpm lint && pnpm test && pnpm content:lint && pnpm build    # 0 failures
pnpm kit visual-parity capture before --ref develop && pnpm kit visual-parity capture after && pnpm kit visual-parity compare before after --json
pnpm kit serve                                                # the owner's look: hand over the URLs it printed; Ctrl-C stops it
```

## Stop for the user

The copy, when a page still holds placeholders (§ The copy first); every
pick (step 2); the dev-server look before a merge; any change to a public
URL, to the content or to the SEO fields — those are not design.