diff --git a/CLAUDE.md b/CLAUDE.md
index be599577..78622cbe 100644
--- a/CLAUDE.md
+++ b/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)
diff --git a/docs/web-ui.md b/docs/web-ui.md
index b251c5a1..058d41f7 100644
--- a/docs/web-ui.md
+++ b/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).
diff --git a/docs/css-vars.md b/docs/web-ui/css-vars.md
similarity index 100%
rename from docs/css-vars.md
rename to docs/web-ui/css-vars.md