From 81607aca26110a316fcd84a96926ac45e70cf12b Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Mon, 1 Jun 2026 19:55:01 +0200
Subject: [PATCH] docs: add CSS custom properties reference (docs/css-vars.md)

Lists all variables declared in base.css with their hex values,
Catppuccin Mocha names, and intended use. Includes a common-mistakes
table mapping the wrong names (--text, --mauve, --surface0/1/2, etc.)
to the correct ones, plus a usage guide for the most common patterns
(dropdowns, hover states, active tabs, badges).
---
 docs/css-vars.md | 69 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 docs/css-vars.md

diff --git a/docs/css-vars.md b/docs/css-vars.md
new file mode 100644
index 00000000..7bf56e7b
--- /dev/null
+++ b/docs/css-vars.md
@@ -0,0 +1,69 @@
+# CSS custom properties (theme variables)
+
+All colour variables are declared **once** in
+`frontend/packages/shared/src/base.css` under `:root`.
+Per-page stylesheets (`dashboard.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 |
+| `--pink` | `#f5c2e7` | pink | thinking events |
+| `--amber` | `#fab387` | peach | warnings, pending / running state |
+| `--green` | `#a6e3a1` | green | success, ok state |
+| `--red` | `#f38ba8` | red | errors, fail state |
+| `--border` | `#313244` | surface0 | general borders, hover/active backgrounds |
+
+## 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 */
+```