docs(demo): regenerate the demo reel on the four-theme UI [DO NOT MERGE — stacked]

.changeset/design-system-foundation.md

@@ -0,0 +1,34 @@
+---
+"@paddock/web": minor
+---
+
+Design system foundation: Tailwind v4, semantic OKLCH tokens, and an enforced contrast floor.
+
+The UI had no design document and no token layer — colour was addressed by
+palette step in 1017 places, with 722 hand-written `dark:` pairs and 200
+arbitrary `text-[Npx]` values. One ramp had been tuned against a dark canvas and
+reused unchanged against a light one, so light mode failed WCAG AA at its
+most-used tokens.
+
+- **Light mode now passes AA.** Help text and field labels went 3.75:1 → 6.71:1,
+  muted text and placeholders 2.81:1 → 4.90:1, and the primary button's white
+  label 4.17:1 → 5.53:1. Light and dark ramps are now derived separately in
+  OKLCH; the mid-steps lose the high-chroma tan cast that made light mode read
+  muddy.
+- **Contrast is enforced, not asserted.** A new test parses the real stylesheet
+  and fails the build if any text-on-surface pair drops below 4.5:1 (3:1 for
+  control boundaries) in either mode, or if a colour falls outside the sRGB
+  gamut.
+- **Shared UI primitives** (`Button`, `Card`, `Section`, `EmptyState`, `Field`,
+  `Input`, `Toggle`, `Chip`, `Callout`, `Dialog`, `Menu`). Dialogs now trap and
+  restore focus, and menus support arrow-key navigation — neither worked before.
+- Chat messages no longer animate in (a 250 ms fade-with-translate on a
+  100+/day event), and `prefers-reduced-motion` is honoured throughout.
+- Config no longer reflows while you type: a field's width was recomputed from
+  its live value on every keystroke, so crossing 38 characters jumped it to full
+  width and re-packed every field after it.
+- Per-instance branding (`PADDOCK_BRAND_ACCENT`) is unchanged and covered by a
+  test.
+
+`docs/DESIGN.md` documents the system, and Tailwind is configured in CSS —
+`tailwind.config.js` and `postcss.config.js` are gone.

.changeset/runtime-themes-and-accent-picker.md

@@ -0,0 +1,43 @@
+---
+"@paddock/web": minor
+---
+
+Four runtime themes and a colour picker, in Config → Appearance.
+
+The design system shipped one palette. This adds a theme switcher and three
+further themes on top of the neutral base, plus an accent picker — all
+per-browser, applied instantly, no save and no restart.
+
+- **Four themes.** `foundation` (the neutral base), `parchment` (a 90s RPG menu
+  — wine chrome, brass fittings, corner brackets, an old-style serif),
+  `terminal` (green phosphor and ANSI in the dark; greenbar and ribbon ink in
+  the light) and `scifi` (deep-space ground and luminous cyan). Both light and
+  dark are designed for each, not inverted from one another.
+- **Pick any colour for the accent.** The picker takes a colour and nothing
+  else: the theme supplies its own saturation and a target contrast, and the
+  *lightness is solved* to hit it. An unreadable accent is therefore
+  inexpressible rather than merely warned about — it is not possible to choose
+  one that fails AA in either mode. Optionally the same colour can tint the
+  page ground (None / A little / More). No colour theory is exposed anywhere in
+  the UI.
+- **Per-instance branding still composes.** With no colour picked, the solver
+  reads the hue of whatever `PADDOCK_BRAND_ACCENT` produced, so an operator's
+  brand colour is re-solved against the active theme instead of being used at
+  whatever lightness it happened to have.
+- **Every theme is contrast-guarded.** The build-time guard previously read only
+  the base palette, so a theme could ship uncertified. It now walks the theme
+  registry and applies the full contract to each one in both modes, and fails
+  both ways — a theme registered with no stylesheet, or a stylesheet no one
+  registered.
+
+**Fixed: hovering the primary button made its label harder to read.** In dark
+mode the fill lightened on hover, taking its white label from 5.53:1 to
+**4.17:1** — below AA, on hover, on the most-clicked control in the app. Hover
+now raises contrast in both modes. The guard had never paired a foreground with
+a hover fill, which is why this was invisible; that pairing is now asserted, and
+adding it immediately caught a second instance in `parchment` (6.31:1 → 5.20:1)
+where the correct direction is the opposite one, because its fill carries dark
+ink rather than white.
+
+The "Appearance" entry in the sidebar is gone — it was a second door onto the
+Config section that already holds these settings.

CLAUDE.md

@@ -92,6 +92,39 @@ derived, not read); nothing may ever log or serialise a declared server's values
 puts the whole `mcp_servers` record in one `--mcp-config` argv element, so an `env`
 value or an `Authorization` header is visible in `/proc/<pid>/cmdline` to the same user.
 
+## UI conventions
+
+**Read [`docs/DESIGN.md`](docs/DESIGN.md) before touching anything visual.** It is
+the repo's only document about how Paddock *looks* (every other `DESIGN-*.md` is
+architecture, and unlike the rest of `docs/` it is current, not the stale fork).
+It covers the token architecture, the type/space/radius/elevation/motion scales,
+the shared primitives, and — aimed squarely at a coding agent — a "Reject this"
+section and a step-by-step "How to add a direction".
+
+The five rules it exists to protect, all enforced by
+`packages/web/src/styles/tokens.test.ts`, which fails the build:
+
+- **Colour lives only in `packages/web/src/styles/tokens.css`**, as semantic
+  tokens (`--surface-raised`, `--text-muted`, `--danger-soft`) declared twice —
+  `:root` for light, `.dark` for dark, ramps derived **separately** in OKLCH.
+- **Never a literal hex, `rgb()` or raw palette step in component code.** Write
+  `text-fg-muted`, not `text-paddock-500` or `text-[#8f7c54]`. The one exception
+  is `src/lib/brand.ts`.
+- **Never a `dark:` variant for a colour** — the token swaps itself. Never an
+  arbitrary `text-[Npx]` — use a rung (`text-3xs` … `text-3xl`). Never a bare
+  `outline` focus ring (use `box-shadow`), never `transition-all`.
+- **Reach for a primitive** from `packages/web/src/components/ui/` (`Button`,
+  `Card`, `Section`, `EmptyState`, `Field`, `Input`, `Toggle`, `Chip`,
+  `Callout`, `Dialog`, `Menu`) before hand-rolling markup. Structural changes go
+  in the primitive, where one edit reaches every call site.
+- **`--accent` / `--accent-600` / `--accent-700` are the branding seam** (#34):
+  space-separated sRGB channels a running server overwrites for
+  `PADDOCK_BRAND_ACCENT`. Keep that format and keep every other accent token
+  derived from them.
+
+Styling is **Tailwind v4** — configuration is CSS (`packages/web/src/index.css`),
+there is no `tailwind.config.js` and no PostCSS config; do not reintroduce them.
+
 ## Dev conventions
 
 Full guide: [`CONTRIBUTING.md`](CONTRIBUTING.md); run modes: [`DEV.md`](DEV.md).