logaritmisk/biggus-dickus

Fork 0

Files

T

logaritmisk 5d63f06863 docs(specs): dark-mode theme toggle — tri-state, icon segmented, FOUC-safe (#59 )

2026-06-07 15:19:29 +02:00

8.5 KiB

Raw Blame History

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)

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.
Icon segmented control: three icon buttons (lucide Sun/Moon/Monitor), active one highlighted, mirroring LangSwitch styling, mounted in the header next to LangSwitch.
FOUC prevention: a synchronous pre-React init applies the class before first paint.
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 <html> 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) ──▶ <html class="dark"?> ──▶ 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 <script> in <head>, before the module script, that synchronously sets the class so a dark reload never flashes light:

<script>
  try {
    var t = localStorage.getItem("theme") || "system";
    var dark = t === "dark" || (t === "system" &&
      window.matchMedia("(prefers-color-scheme: dark)").matches);
    document.documentElement.classList.toggle("dark", dark);
  } catch (e) {}
</script>

(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 <button>s in a row (flex gap-1), one per Theme, each with a lucide icon (Sun → light, Moon → dark, Monitor → system), sized size-4/h-4 w-4.
Active button highlighted; inactive text-muted-foreground (mirror LangSwitch). Each carries aria-pressed={theme === value} and aria-label={t("theme.<value>")}.
onClick → setTheme(value).
No raw color utilities (token classes only — passes check:colors).

Mount — `web/src/shell/app-shell.tsx`

Insert <ThemeSwitch /> in the header immediately before <LangSwitch />:

<header className="flex items-center gap-4 border-b px-4 py-2">
  <div className="flex-1" />
  <ThemeSwitch />
  <LangSwitch />
  <Button variant="ghost" size="sm" onClick={onSignOut}>{t("auth.signOut")}</Button>
</header>

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 <html> 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

A tri-state theme toggle (Light/Dark/System) appears in the header; default is System.
Choosing Dark applies .dark to <html> and persists; Light removes it; System follows the OS and live-updates via prefers-color-scheme until the user pins a value.
No light flash on a dark reload (synchronous pre-React init).
Dark --primary button-label contrast ≥ 4.5:1 (--ring kept in sync); light unchanged.
en/sv parity for theme.*; aria-pressed + aria-label on the controls.
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).

8.5 KiB Raw Blame History