# 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 */
```