# Dark-Mode Theme Toggle — Design **Date:** 2026-06-07 **Status:** Approved (brainstorming) — ready for implementation planning. **Issue:** #59. ## Context `web/src/index.css` defines a complete `.dark` token set (24 tokens — background/foreground, card, popover, primary, secondary, muted, accent, destructive, success, warning, highlight, border, input, ring + their `-foreground` variants), and the `ui/*` components carry `dark:` variants. After #49, the feature screens route through the semantic tokens, so the app now *adapts* to `.dark`. But nothing ever applies the `.dark` class and there is **no theme toggle**, so dark mode can't activate. This milestone ships the toggle (the issue's "ship it" path). Theme is **client-only**, mirroring the locale mechanism: `localStorage` persistence, read at startup, applied to the DOM. `/api/config` (`ConfigView`) carries no theme field; a per-instance server default is out of scope (could add `default_theme` later, like `default_language`). ### Decisions (from brainstorming) 1. **Tri-state model:** `"light" | "dark" | "system"`. Default (unset) is `"system"` — follows the OS via `prefers-color-scheme` and keeps re-tracking live until the user pins light or dark. 2. **Icon segmented control:** three icon buttons (lucide `Sun`/`Moon`/`Monitor`), active one highlighted, mirroring `LangSwitch` styling, mounted in the header next to `LangSwitch`. 3. **FOUC prevention:** a synchronous pre-React init applies the class before first paint. 4. **Dark `--primary` contrast tweak** (parked from #49) folded in here. ## Architecture Plain client-side theming over CSS custom properties (no `next-themes` dependency). The `.dark` class on `` activates the existing dark token block; Tailwind utilities reference the tokens, so no per-component work is needed beyond what #49 already did. ``` localStorage["theme"] ──read──▶ resolve(theme) ──▶ ──▶ tokens ──▶ UI ▲ ▲ setTheme() (toggle) matchMedia listener (when theme === "system") ``` ## Components ### `web/src/theme/theme.ts` (new) — core, framework-free - `export const THEME_KEY = "theme";` - `export type Theme = "light" | "dark" | "system";` - `export function resolveTheme(theme: Theme): "light" | "dark"` — returns `theme` unless `"system"`, in which case `matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"`. Guards `typeof window`/`matchMedia` for non-DOM (test/SSR) safety → falls back to `"light"`. - `export function readTheme(): Theme` — reads `localStorage[THEME_KEY]`; returns `"system"` if absent/invalid. Guards `typeof localStorage`. - `export function applyTheme(theme: Theme): void` — `document.documentElement.classList.toggle("dark", resolveTheme(theme) === "dark")`. Guards `typeof document`. ### `web/src/theme/use-theme.ts` (new) — React hook (sibling of `i18n/use-locale.ts`) - `useTheme(): { theme: Theme; setTheme: (t: Theme) => void }`. - Holds `theme` in `useState(readTheme)`. - `setTheme(t)`: `localStorage.setItem(THEME_KEY, t)`, `setThemeState(t)`, `applyTheme(t)`. - `useEffect`: when `theme === "system"`, subscribe to `matchMedia("(prefers-color-scheme: dark)")` `change` → `applyTheme("system")`; clean up on change/unmount. (No-op subscription when pinned.) - On mount it also calls `applyTheme(theme)` once (covers the case where the hook mounts without the pre-React init, e.g. tests) — idempotent with the inline script. ### Pre-React init (FOUC prevention) — `web/index.html` A tiny inline ` ``` (Kept inline + defensive; it must run before paint, so it cannot be a module import.) ### `web/src/shell/theme-switch.tsx` (new) — the UI - Renders three ` ``` ### i18n — `web/src/i18n/{en,sv}.json` Add a `theme` namespace (en/sv parity): - en: `{ "light": "Light", "dark": "Dark", "system": "System" }` - sv: `{ "light": "Ljust", "dark": "Mörkt", "system": "System" }` ### Dark `--primary` contrast tweak — `web/src/index.css` Current dark `--primary: oklch(0.673 0.182 276.935)` with near-black `--primary-foreground: oklch(0.205 0 0)` yields ~3.21:1 for button-label text. Lower the dark `--primary` lightness so the near-black foreground reaches **≥4.5:1** (e.g. around `oklch(0.62 0.20 277)` — implementer computes the exact value with a WCAG contrast check against `--primary-foreground`, keeping it a recognizable indigo and `--ring` in sync). Light mode is unchanged (already 8.3:1). ## Data flow First load: inline script applies class from `localStorage`/system before paint → React mounts → `useTheme` seeds from `localStorage` and (when `system`) attaches the media listener. Toggle click → `setTheme` persists + re-applies. OS theme change while in `system` → listener re-applies. Other tabs are not synced (out of scope; a `storage` listener could be a later nicety). ## Error handling / edges - `localStorage`/`matchMedia`/`document` all guarded → safe in tests/SSR (fall back to light, no throw). - Invalid stored value → treated as `"system"`. - The inline script is wrapped in `try/catch` so a storage exception never blocks render. - Pinning light/dark removes the system listener so it stops following the OS. ## Testing - **`web/src/theme/theme.test.ts`** (unit): `resolveTheme` maps light/dark verbatim and resolves `system` via a mocked `matchMedia`; `readTheme` returns `system` when unset and the stored value otherwise; `applyTheme` toggles the `dark` class on `documentElement`. - **`web/src/shell/theme-switch.test.tsx`** (renderApp): clicking **Dark** adds `.dark` to `document.documentElement` and sets `localStorage.theme === "dark"`; clicking **Light** removes it; clicking **System** with `matchMedia` mocked dark → class present, `localStorage.theme === "system"`; `aria-pressed` reflects the active mode. (Mock `window.matchMedia` in the test as jsdom lacks it.) - **Storybook:** `theme-switch.stories.tsx` rendering the three-state control (a play test asserting the three buttons + aria-pressed). Note: toggling theme in a story mutates `` globally — keep the story render-only or reset the class in `play`/`beforeEach`. - Gate: `pnpm typecheck && lint && test && build && check:size && check:colors`. en/sv parity; no codename. `check:size` within 250 KB gz (three small lucide icons; `Sun`/`Moon`/`Monitor` — negligible, but confirm). ## Acceptance criteria 1. A tri-state theme toggle (Light/Dark/System) appears in the header; default is System. 2. Choosing Dark applies `.dark` to `` and persists; Light removes it; System follows the OS and live-updates via `prefers-color-scheme` until the user pins a value. 3. No light flash on a dark reload (synchronous pre-React init). 4. Dark `--primary` button-label contrast ≥ 4.5:1 (`--ring` kept in sync); light unchanged. 5. en/sv parity for `theme.*`; `aria-pressed` + `aria-label` on the controls. 6. `typecheck`/`lint`/`test`/`build`/`check:size`/`check:colors` green; no codename; no new npm dep. ## Out of scope → follow-ups - Per-account / server-synced theme preference (add `default_theme` to `ConfigView` later, mirroring `default_language`). - Cross-tab sync via a `storage` event listener. - Header redesign / wayfinding (#54); a full dark-mode visual QA pass across every screen (the tokens make it adapt, but a dedicated screenshot review is a separate effort).