# Theme Settings System — 2026-05-30

## Editable Theme Values

| Setting | Variable | Default | Storage Key |
|---------|----------|---------|-------------|
| Primary color | `--crm-primary` | `#16a34a` | `crm-primary-color` |
| Dark/Light mode | `crm-theme-dark` / `crm-theme-light` class on `<html>` | `dark` | `crm-theme` |

Derived automatically from primary color (updated by JS, not stored separately):
- `--crm-primary-hover` — 15% darkened version of primary
- `--crm-primary-soft` — primary with 0.12 alpha (rgba)
- `--crm-accent`, `--crm-accent-hover`, `--crm-accent-soft` — aliases kept for backward compat
- `--wa`, `--wa-dark`, `--wa-soft` — dashboard chat workspace accent (auto-derived via CSS `var()`)

## Storage Method

`localStorage` with keys:
- `crm-primary-color` — hex color string (e.g. `#16a34a`)
- `crm-theme` — `dark` or `light`

Data is stored in the user's browser. Works on all admin pages. No database writes required.

## How Theme is Applied Globally

### On every page load (zero flash)
An inline `<script>` in `<head>` (injected by `AdminPanelProvider` renderHook) runs before CSS:
```js
var t = localStorage.getItem('crm-theme') || 'dark';
document.documentElement.classList.add('crm-theme-' + t);
if (t === 'dark') document.documentElement.classList.add('dark');
var p = localStorage.getItem('crm-primary-color');
if (p) { document.documentElement.style.setProperty('--crm-primary', p); }
```

### After DOM loads
`public/js/crm-theme.js` (loaded in BODY_END) runs and:
1. Re-applies the stored theme (dark/light class)
2. Calls `applyPrimaryToDOM(getPrimary())` — sets `--crm-primary`, `--crm-primary-hover`, `--crm-primary-soft`, and accent aliases on `document.documentElement`

### CSS cascade
- `html.crm-theme-dark { --crm-accent: var(--crm-primary) }` — all Filament page styles reference `--crm-accent` which now derives from `--crm-primary`
- `html.crm-theme-light { --crm-accent: var(--crm-primary) }` — same for light mode
- `chat-workspace.css :root { --wa: var(--crm-primary) }` — dashboard uses the same primary

## Where Color Can Be Changed

### Dashboard (`/admin`)
- Color picker input (`<input type="color" id="primaryColorPicker">`) in the topbar
- Changes apply immediately on `input` event
- Saved to localStorage on `change` event
- Reset button restores `#16a34a`

### Settings page (`/admin/settings`) — Section 7: Theme Settings
- Color picker + hex text input (synced)
- Dark/Light mode toggle buttons
- Reset All button (resets to green + dark mode)

## How to Reset Theme

```js
window.crmTheme.resetPrimary();  // resets color to #16a34a, removes from localStorage
window.crmTheme.setTheme('dark'); // resets mode to dark
```

Or use the "Reset All" button in Settings → Section 7.

## window.crmTheme API

```js
window.crmTheme.getTheme()          // → 'dark' | 'light'
window.crmTheme.setTheme('light')   // set mode + persist
window.crmTheme.toggle()            // toggle mode
window.crmTheme.getPrimary()        // → hex string e.g. '#16a34a'
window.crmTheme.setPrimary('#3b82f6', true)  // set primary + persist
window.crmTheme.resetPrimary()      // reset to default green
window.crmTheme.DEFAULT_PRIMARY     // '#16a34a'
```
