docs(web-ui): move css-vars.md into web-ui/

The CSS theme-variable reference documents the dashboard/agent web-UI
stylesheets, so it belongs under docs/web-ui/ alongside shape/dashboard/
agent. Wire it into the web-ui.md index (split list + reading path) and
the CLAUDE.md file map. Closes #1405.

CLAUDE.md

@@ -363,7 +363,8 @@ docs/
                        contents, container row, topology, selection bar,
                        approval card, endpoints + event channel),
                        web-ui/agent.md (header, terminal, composer,
-                       inbox, live view, per-agent endpoints, stats)
+                       inbox, live view, per-agent endpoints, stats),
+                       web-ui/css-vars.md (Catppuccin theme variables)
   turn-loop.md         claude invocation, wake prompt, MCP tool surface
   tools/               per-group tool docs (bash.md, lifecycle.md,
                          scheduling.md, matrix.md, forge.md)

docs/web-ui.md

@@ -19,6 +19,9 @@ This doc has been split for readability. Pick the section you need:
 - **[Per-agent page](web-ui/agent.md)** — header, main terminal,
   composer, side panel + inbox, live view, slash commands,
   per-agent endpoints, stats page.
+- **[CSS theme variables](web-ui/css-vars.md)** — the Catppuccin
+  Mocha custom properties declared once in `base.css` and the rule
+  that per-page stylesheets reference (never redeclare) them.
 
 ## Reading paths
 
@@ -37,3 +40,6 @@ This doc has been split for readability. Pick the section you need:
   [`web-ui/agent.md`](web-ui/agent.md) (Terminal-embedded prompt).
 - **"What are the per-agent HTTP endpoints?"** →
   [`web-ui/agent.md`](web-ui/agent.md) (Per-agent endpoints).
+- **"Which CSS variable do I use / where are colours defined?"** →
+  [`web-ui/css-vars.md`](web-ui/css-vars.md) (Palette, single-source
+  `base.css` rule).

docs/web-ui/css-vars.md

@@ -0,0 +1,72 @@
+# CSS custom properties (theme variables)
+
+All colour variables are declared **once** in
+`frontend/packages/shared/src/base.css` under `:root`.
+Per-page stylesheets (`common.css`, `dashboard.css`, `flow.css`, `logs.css`, `agent.css`) must reference these
+names and must **not** redeclare them.
+
+## Palette (`base.css`)
+
+| Variable | Hex | Catppuccin Mocha | Use |
+|---|---|---|---|
+| `--bg` | `#1e1e2e` | base | page background |
+| `--bg-elev` | `#181825` | mantle | elevated surfaces: floating dropdowns, popovers |
+| `--crust` | `#11111b` | crust | terminal / code block background |
+| `--fg` | `#cdd6f4` | text | primary text colour |
+| `--muted` | `#7f849c` | overlay1 | secondary / dimmed text |
+| `--purple` | `#cba6f7` | mauve | accent — active tabs, links, highlights |
+| `--purple-dim` | `#45475a` | surface1 | subtle borders, terminal chrome, badge backgrounds |
+| `--cyan` | `#89dceb` | sky | tool-use events, info accents |
+| `--blue` | `#89b4fa` | blue | links, interactive accent (distinct from sky) |
+| `--pink` | `#f5c2e7` | pink | thinking events |
+| `--amber` | `#fab387` | peach | warnings, pending / running state |
+| `--yellow` | `#f9e2af` | yellow | flash messages, mild warnings |
+| `--green` | `#a6e3a1` | green | success, ok state |
+| `--red` | `#f38ba8` | red | errors, fail state |
+| `--border` | `#313244` | surface0 | general borders, hover/active backgrounds |
+| `--subtext0` | `#a6adc8` | subtext0 | secondary toolbar/status text; dimmer than `--fg`, lighter than `--muted` |
+
+## Common mistakes
+
+The Catppuccin colour names do **not** map 1:1 to the variable names.
+Variables to avoid (undefined — they will silently resolve to transparent / inherited):
+
+| Wrong | Correct |
+|---|---|
+| `--text` | `--fg` |
+| `--mauve` | `--purple` |
+| `--surface0` | `--bg-elev` (float bg) or `--border` (border/hover) |
+| `--surface1` | `--border` |
+| `--surface2` | `--purple-dim` |
+| `--overlay0`, `--overlay1` | `--muted` |
+| `--base`, `--mantle` | `--bg`, `--bg-elev` |
+
+## Usage guide
+
+**Floating menus and dropdowns** (e.g. agent context menu, tabbar overflow):
+```css
+background: var(--bg-elev);
+border: 1px solid var(--purple-dim);
+```
+
+**Hover / active state backgrounds**:
+```css
+background: var(--border);
+```
+
+**Active tab text / accent elements**:
+```css
+color: var(--purple);
+```
+
+**Muted / meta text**:
+```css
+color: var(--muted);
+```
+
+**Error / warning / success badges**:
+```css
+color: var(--red);    /* error */
+color: var(--amber);  /* warning / running */
+color: var(--green);  /* ok */
+```