# Web Theme Toggle + Visual Polish — 2026-05

Session learning from BOSS's xianyu-hunter dashboard refinement request: when asked to make the UI more polished, at minimum provide explicit dark/light theme switching and make the result visible in the Web UI immediately.

## Implemented pattern

Files in `/Users/chick/.Hermes/workspace/research/xianyu-hunter`:

- `public/index.html`
  - Add a header button before existing settings/login/create actions:
    - `id="theme-toggle"`
    - `onclick="toggleTheme()"`
    - child spans `theme-icon` and `theme-label`
  - Bump static asset query versions, e.g. `style.css?v=14`, `app.js?v=14`, to avoid stale browser cache.
- `public/app.js`
  - Add `THEME_STORAGE_KEY = 'xianyu-hunter-theme'`.
  - Add `getPreferredTheme()`:
    - prefer saved `localStorage` value if `light`/`dark`.
    - otherwise follow `window.matchMedia('(prefers-color-scheme: light)')`.
  - Add `applyTheme(theme)`:
    - sets `document.documentElement.dataset.theme`.
    - updates `theme-icon` and `theme-label` when DOM elements exist.
  - Add `toggleTheme()`:
    - toggles `light`/`dark`, persists to `localStorage`, reapplies.
  - Call `applyTheme(getPreferredTheme())` early so theme applies before app data rendering.
- `public/style.css`
  - Use `:root` as default dark theme and `:root[data-theme="light"]` for light variables.
  - Expand variables beyond the older basic palette: `--surface`, `--surface-strong`, `--border-strong`, `--muted`, `--accent3`, `--shadow`, `--shadow-soft`, `--glow`.
  - Prefer real light-theme variables rather than simple inversion.
  - Polish high-visibility surfaces: header, sidebar, content shell, task cards, buttons, pipeline, tabs, stat cards, product table wrapper, modal, log blocks.
  - Use cache-safe CSS constructs with existing browser target: gradients, `backdrop-filter`, CSS variables, and `color-mix()`.

## Verification commands

```bash
cd /Users/chick/.Hermes/workspace/research/xianyu-hunter
node --check public/app.js
node --check server.mjs
python3 - <<'PY'
from pathlib import Path
html=Path('public/index.html').read_text()
css=Path('public/style.css').read_text()
js=Path('public/app.js').read_text()
for needle in ['style.css?v=', 'app.js?v=', 'theme-toggle']:
    print(needle, needle in html)
print('light theme vars', ':root[data-theme="light"]' in css)
print('toggleTheme', 'function toggleTheme()' in js)
PY
node tools/xianyu_ops.mjs stop || true
node tools/xianyu_ops.mjs start --port 3000
node tools/xianyu_ops.mjs status --port 3000
python3 - <<'PY'
import urllib.request
html=urllib.request.urlopen('http://127.0.0.1:3000/', timeout=10).read().decode('utf-8')
print('theme button', 'theme-toggle' in html)
print('css v', 'style.css?v=' in html)
print('app v', 'app.js?v=' in html)
PY
```

## Pitfalls

- Do not stop after backend/CSS edits only; BOSS expects visible product UI changes and live verification.
- If CSS/JS filenames use query-string cache busting, bump both versions in `index.html`; otherwise the browser may keep the previous UI.
- `applyTheme()` may run before the header DOM exists, so DOM updates must guard missing `theme-icon`/`theme-label` elements.
- Preserve existing login/notification/task controls while adding the theme toggle; do not regress the simplified login UX.