xianyu-hunter-hermes-skill/skill/xianyu-hunter-monitor/references/web-theme-toggle-visual-polish-2026-05.md

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

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.