feat(ux): theming foundation + dark mode + visual polish

[SoundMindsAI]

Fifth and final UX-audit fix PR. Scope: visual consistency, theming, and dark mode. The audit's key insight was that ~4 primitive edits fix most of the drift — this does those plus makes dark mode functional.

Changes

• Root-cause primitive migration — Card was bg-white text-gray-900 (a permanently-light surface propagating to 50+ consumers); now bg-card text-card-foreground border-border. Badge keeps its semantic color families but gains dark: variants so status chips read on a dark surface. empty-state, chat bubbles, and metric-delta migrated to tokens too.
• New Alert primitive (info/warning/destructive, token-driven + dark-safe) replaces the hand-rolled border-*-200 bg-*-50 callouts (proposal error, chat secrets warning, chat stream error) — consistent padding/weight, no longer light-only.
• Dark mode is now reachable and functional — new ThemeToggle (light/dark/system) in the nav wires the already-configured next-themes. Verified live with Playwright: the nav flips white→near-black and cards/text/borders theme correctly (screenshot in the session).
• Top nav → tokens + mobile: bg-background border-border, active pill uses the primary token, and the 9-item row is overflow-x-auto so it stays usable on narrow screens (was a fixed non-wrapping row).
• metric-delta gains tabular-nums (digit alignment on the densest screens) + dark: green/red delta colors.
• Chart a11y — the LLM-vs-UBI convergence overlay distinguished series by color alone; the UBI line is now dashed (deuteranopia-safe).

Deferred (tracked follow-up — noted honestly)

The long-tail hardcoded-color sweep (~49 text-blue-600 links + remaining bg-*-50 boxes), full chart theme-color migration + axis labels/units, and a centralized date formatter. The primary surfaces are dark-correct (verified), but a human dark-mode QA pass across every surface is recommended before declaring dark mode 100% done — the token migration is correct-by-construction but the long-tail isn't swept yet.

Testing

Alert + ThemeToggle tests; the migration reuses the exact tokens the audit confirmed already work in dark mode on Input/Table/Select/Dialog, so existing tests (which assert substring/attribute) stay green. Full suite 1330; tsc + eslint + prettier clean; pnpm build passes; dark mode Playwright-verified.

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a reusable Alert component, adds a ThemeToggle component for light/dark/system theme switching, and updates several components (such as Card, EmptyState, and TopNav) to support dark mode using Tailwind tokens. Feedback on these changes highlights a potential hydration mismatch in the chat detail page due to reading sessionStorage during initial render, a UX improvement for the theme toggle to prevent non-visual state transitions, and a bug in the metric delta calculation when handling negative baselines.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

The warningDismissed state is initialized by reading from sessionStorage directly during the initial render:

const [warningDismissed, setWarningDismissed] = useState(() => {
  if (typeof window === 'undefined') return false;
  return sessionStorage.getItem(SECRETS_WARNING_KEY) === '1';
});

Because this component is rendered on the server (where typeof window === 'undefined' is true), warningDismissed will always initialize to false on the server. If a user has previously dismissed the warning, the client will initialize it to true on the initial render. This mismatch between the server-rendered HTML (which includes the Alert banner) and the client-rendered HTML (which does not) will cause a hydration mismatch error in Next.js.

Recommended Fix

Initialize the state to false and read from sessionStorage inside a useEffect hook after the component has mounted:

const [warningDismissed, setWarningDismissed] = useState(false);

useEffect(() => {
  if (typeof window !== 'undefined') {
    setWarningDismissed(sessionStorage.getItem(SECRETS_WARNING_KEY) === '1');
  }
}, []);

[gemini-code-assist]

Cycling blindly through ['light', 'dark', 'system'] can lead to a frustrating UX papercut where clicking the toggle results in no visual change. For example, if the user's system preference is light, the active theme is system (resolving to light). Clicking the toggle will switch the theme to light, which keeps the page light and makes the button feel broken on the first click.

To provide a seamless UX, we can toggle directly between light and dark based on the active resolvedTheme from next-themes. This guarantees a visual change on every click while still respecting the user's system preference initially.

Suggested change

	const { theme, setTheme } = useTheme();
	const [mounted, setMounted] = useState(false);
	// Canonical next-themes hydration guard: the resolved theme is only known
	// client-side, so render a stable placeholder until mount. The synchronous
	// set-on-mount is intentional (one-shot, empty deps).
	// eslint-disable-next-line react-hooks/set-state-in-effect
	useEffect(() => setMounted(true), []);
	const order = ['light', 'dark', 'system'] as const;
	const current = (theme ?? 'system') as (typeof order)[number];
	const next = order[(order.indexOf(current) + 1) % order.length]!;
	const Icon = current === 'dark' ? Moon : current === 'light' ? Sun : Monitor;
	const { theme, setTheme, resolvedTheme } = useTheme();
	const [mounted, setMounted] = useState(false);
	// Canonical next-themes hydration guard: the resolved theme is only known
	// client-side, so render a stable placeholder until mount. The synchronous
	// set-on-mount is intentional (one-shot, empty deps).
	// eslint-disable-next-line react-hooks/set-state-in-effect
	useEffect(() => setMounted(true), []);
	const current = theme ?? 'system';
	const next = resolvedTheme === 'dark' ? 'light' : 'dark';
	const Icon = resolvedTheme === 'dark' ? Moon : Sun;

[gemini-code-assist]

The deltaPct calculation (on line 32) does not handle negative baselines correctly:

const deltaPct = ((achieved - baseline) / baseline) * 100;

If baseline is negative, a positive change (e.g., from -10 to -5) will result in a negative percentage, and a negative change (e.g., from -10 to -15) will result in a positive percentage. This will cause the wrong color class (text-green-700 vs text-red-700) to be applied here.

Recommended Fix

Update the deltaPct calculation to use Math.abs(baseline):

const deltaPct = ((achieved - baseline) / Math.abs(baseline)) * 100;

[SoundMindsAI]

Review adjudication

Gemini — 2 findings, both accepted + fixed in dc57f3b5:

Finding	Verdict	Action
theme-toggle.tsx — blind light→dark→system cycle can no-op on the first click (system already resolves to the landed theme)	Accept	Toggle off resolvedTheme (light↔dark) so every click is a visible change.
chat/[id]/page.tsx — warningDismissed read sessionStorage in the initial state → SSR (false) vs client (true) hydration mismatch	Accept	Initialize to false; read sessionStorage in a mount effect. (Pre-existing latent bug adjacent to the Alert change; fixed inline.)

Only remaining red is the pre-existing backend (contract+integration) UBI test (#610). Dark mode was Playwright-verified before shipping the toggle.