> ## Documentation Index
> Fetch the complete documentation index at: https://docs.claw.boo/llms.txt
> Use this file to discover all available pages before exploring further.
# Theming
> Switch Clawboo between light, dark, and system theme, and how the preference is resolved, persisted, and applied without a flash.
Use this page when you want to switch the dashboard between **light**, **dark**, and **system** (follow-the-OS) themes, or when you need to understand where the preference is stored and why fresh installs open in light mode.
The toggle lives in the bottom-left of the sidebar. There is no API behind it; theming is entirely client-side: a single class on the `` element flips the CSS-variable palette, so switching is instant with no rebuild and no page reload.
## Prerequisites
Theming needs nothing connected. The toggle works on the very first screen, before you connect a [runtime](/appendices/glossary) or deploy a team, because the preference lives in the browser, not on the server.
* A browser with `localStorage` (every modern browser). The preference is stored per origin, so two ports, for example a dev server on `:5173` and the bundled server on its API port, keep independent theme settings.
## Steps
### 1. Find the theme toggle
Open the dashboard. The toggle (`ThemeToggle`) sits at the bottom of the left sidebar (`AgentListColumn`), below a divider, under the navigation buttons. It renders a Lucide icon, the current preference label, and, when you are on **System**, the resolved theme in small uppercase to its right.
| Current preference | Icon | Label | Right-side hint |
| ------------------ | ------- | -------- | ----------------------------------------------- |
| Light | Sun | `Light` | n/a |
| Dark | Moon | `Dark` | n/a |
| System | Monitor | `System` | `light` or `dark` (whatever the OS resolves to) |
### 2. Click to cycle
The toggle is a single button that cycles through the three preferences in a fixed order on each click:
```
light → dark → system → light → …
```
The button's tooltip (and `aria-label`) always names what the next click will do: for example *"Theme: Light. Click for Dark."*, or on System *"Theme: System (dark). Click for Light."*. There is no separate menu; one button, one cycle.
### 3. (Optional) Let it follow your OS
Pick **System** to track your operating-system color scheme. While in system mode, Clawboo subscribes to the `prefers-color-scheme: dark` media query and flips the resolved theme live when you change your OS appearance, no click required. Picking **Light** or **Dark** explicitly unsubscribes from that media query and pins the theme.
## How it resolves and persists
Two concepts are kept distinct:
* **Preference** (`theme`): the raw choice you made: `system`, `light`, or `dark`.
* **Resolved theme** (`resolvedTheme`): the concrete palette currently rendered: `light` or `dark`, never `system`. In system mode it is derived from the OS media query; otherwise it equals the preference.
```mermaid theme={"theme":{"light":"github-dark","dark":"github-dark"}}
flowchart LR
Pref["preference\n(system | light | dark)"] --> Resolve{resolve}
Resolve -->|system| OS["prefers-color-scheme"]
Resolve -->|light/dark| Direct["use as-is"]
OS --> Resolved["resolvedTheme\n(light | dark)"]
Direct --> Resolved
Resolved -->|dark| AddClass["add .dark to <html>"]
Resolved -->|light| RemoveClass["remove .dark from <html>"]
```
**Persistence.** When you change the preference, it is written to `localStorage` under the key `clawboo.theme`. On the next load, `ThemeProvider` reads that key:
* A stored value of `light`, `dark`, or `system` is honored.
* Any other state, including a fresh install with **no stored value**, defaults to **light**, so onboarding always happens in light mode.
**Applying the class.** The resolved theme maps to exactly one DOM change: `dark` adds the `.dark` class to `document.documentElement` (``); `light` removes it. Everything visual follows from that class.
## No flash on load (FOUC prevention)
If theming only ran inside React, a dark-mode user would briefly see the light default before the bundle mounted and applied the class. To prevent that flash, an **inline `