UI overhaul: labels instead of essays, and a deck you can read

[MyNamesEMurray]

Summary

A full pass over all four pages for distribution polish, driven by screenshots of the running app rather than by reading markup. The theme was already coherent; what was wrong was density, hierarchy, and a handful of things that were simply broken at sizes nobody had looked at.

Changes

Shared components first (theme.css, DESIGN.md). Each page had grown its own copy of the same patterns, so the pass starts by settling them: .setting + .why (a short label with its explanation folded into a disclosure), .section, .card-head, .seg, .empty-state, .toolbar, .kbd. DESIGN.md gains the two principles these encode — labels, not essays (depth on demand, not depth by default) and nothing in the app is only a colour.

Settings: documentation turned back into a UI. Most controls carried their whole explanation inside the <label>, five to seven lines each, four stacked in a row on the Voice tab. All 16 paragraph-labels became a short label, a one-line hint, and the control, with the prose kept verbatim behind 24 "why?" disclosures — nothing deleted, just not shouted while a stream is live. Tabs became sections with real headings; Voice went from one five-part scroll to Where speech comes from → How the cast handles what you say → Accuracy → Second channel. The Simple/Advanced split was also wrong in a way that mattered: the Twitch channel name was Advanced-only while "pull game + title from Twitch" was Simple, so a Simple setting depended on a field you could not see.

The deck: a conversation instead of a wall. The column is contained and centred instead of spanning the monitor, consecutive messages group under one header, and the cast rail dropped the four-times-repeated "watching" and the ring around every tile. The 🤖 AI badge deliberately does not group — it moved onto the bubble, trailing the text, so every cast message still carries it.

The wizard got a map. Six anonymous dashes became a named rail with ticks and a step counter; "Next" says where it goes; choice cards became real radios with a check mark (they were previously selected by a faint tint alone); and errors became callouts that say what to do instead of showing raw provider JSON like connect ECONNREFUSED 127.0.0.1:4455.

Real defects fixed along the way: the settings save bar was fixed-position over the content and hid the bottom of long tabs; the deck's status orbs dropped their labels below 1180px, leaving four unreadable coloured dots; "Say something" wrapped onto two lines; cost printed three decimals and rounded anything under a cent to $0.00; and the overlay's compact theme was genuinely illegible over a bright scene (white text, two soft shadows, white video) and now has a proper halo.

Verification

• Full CI reproduced locally: node --check over every JS file, config.example.json parse, npm test (161 pass, 0 fail, 1 pre-existing Windows-only SAPI skip), npm run smoke → SMOKE OK.
• Everything was judged from screenshots of the app running headless with a seeded four-ghost session, at 1440 / 1000 / 900 and at the 1.25 font scale, before and after. Roughly 100 screenshots across the pass; every wizard step was walked, not just the first.
• Settings: data-path set is byte-identical to the previous revision, every pre-existing id still resolves, and a save round-trip was verified for one control per tab.
• Deck: automated check that every cast message carries .badge-ai (11/11 and 9/9 in two runs), plus 3× zooms proving the badge is legible against all four ghost colours at both font scales. Send, energy drag, room switch, pause/resume and the command palette all still work.
• Overlay: rendered over bright, pure-white, dark and busy backdrops in both themes. A regression was caught mid-pass — the new halo bled into the AI badge and filled in its letters — and fixed by having the badge opt out; 3× zoom over a bright scene proves badge and watermark intact.
• Only console message on any page is a pre-existing GET /favicon.ico 404.

Risk & rollout

• Presentation only. No server, config, protocol or API change; no new config keys; nothing to migrate. src/ is untouched by this PR.
• The ethics guarantees were the thing to watch, and they are intact. The AI badge is the same .badge-ai component at the same size and contrast on every surface — it moved position on the deck and opted out of the overlay's new text halo, both so it stays more legible, never less. The "simulated viewers, not real people" watermark was strengthened only: full white on a bordered plate that can never be squeezed, same size, same position, same copy, still unconditional.
• Settings binding is the main review risk — a control that silently stops saving would be invisible. Hence the byte-identical data-path check and the per-tab round-trip, but a second pair of eyes on that file is worth it.
• The overlay renders on air, so its diff was kept deliberately small: the card theme was fine over every backdrop tested and was left alone.
• Two things noticed and deliberately not fixed here, both server-side: /favicon.ico 404s on every page load, and /api/config serves stale in-memory config after a non-hot save under npm run serve (the Electron host relaunches, so this only bites headless).

Checklist

• npm run smoke passes locally (or CI is green)
• Follows the design language in DESIGN.md (if UI changed)
• AI-labeling / "simulated viewers" guarantees intact (if bot output or overlay changed)
• Docs updated (README / config reference) if behavior or config changed
• Targets main

🤖 Generated with Claude Code

https://claude.ai/code/session_01LWa54BF5RjHWC5GFaENZMM

---

Generated by Claude Code