merge: dark-mode theme toggle — tri-state Light/Dark/System, FOUC-safe (#59)

2026-06-07 16:45:55 +02:00
parent d0e3772c34 eead013ccd
commit 9323c608ee
13 changed files with 915 additions and 2 deletions
@@ -0,0 +1,520 @@
 # Dark-Mode Theme Toggle Implementation Plan
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
 **Goal:** Ship a tri-state (Light/Dark/System) theme toggle that activates the existing `.dark` token set, persists to `localStorage`, defaults to System (live-tracking the OS), and never flashes on reload.
 **Architecture:** Client-only theming over CSS custom properties — no new dependency. A framework-free core (`theme.ts`) resolves/reads/applies the theme; a `useTheme` hook mirrors `use-locale`; a synchronous inline script in `index.html` applies the class before first paint; an icon segmented `ThemeSwitch` lives in the header next to `LangSwitch`. The `.dark` class on `<html>` activates the dark tokens migrated in #49.
 **Tech Stack:** React 19 + TS + pnpm, Tailwind v4 (OKLCH tokens in `index.css`), lucide-react (already a dep), Vitest + RTL + MSW + Storybook. Test runner: `pnpm test` (vitest, single pass).
 **Conventions:** pnpm; **no `any`/`eslint-disable`/`@ts-ignore`**; no codename; en/sv parity; source double-quote/semicolon, stories single-quote/no-semicolon; token classes only (no raw colors — `check:colors` must pass); guard DOM globals (`window`/`localStorage`/`matchMedia`/`document`) for jsdom/test safety.
 **Spec:** `docs/superpowers/specs/2026-06-07-dark-mode-theme-toggle-design.md`
 **File structure:**
 - `web/src/theme/theme.ts` (new) — `THEME_KEY`, `Theme`, `resolveTheme`, `readTheme`, `applyTheme`.
 - `web/src/theme/theme.test.ts` (new) — unit tests for the core.
 - `web/src/theme/use-theme.ts` (new) — `useTheme()` hook.
 - `web/src/shell/theme-switch.tsx` (new) — the icon segmented control.
 - `web/src/shell/theme-switch.test.tsx` (new) — interaction tests.
 - `web/src/shell/theme-switch.stories.tsx` (new) — Storybook story.
 - `web/src/shell/app-shell.tsx` (modify) — mount `<ThemeSwitch />`.
 - `web/src/i18n/en.json`, `web/src/i18n/sv.json` (modify) — `theme.*` keys.
 - `web/index.html` (modify) — inline FOUC-prevention script.
 - `web/src/index.css` (modify) — dark `--primary`/`--ring` contrast tweak.
 ---
 # Task 1: Theme core (`theme.ts`) + unit tests
 **Files:**
 - Create: `web/src/theme/theme.ts`
 - Create: `web/src/theme/theme.test.ts`
 - [ ] **Step 1: Write the failing tests** — `web/src/theme/theme.test.ts`:
 ```ts
 import { afterEach, expect, test, vi } from "vitest";
 import { applyTheme, readTheme, resolveTheme, THEME_KEY } from "./theme";
 function mockMatchMedia(matches: boolean) {
  vi.stubGlobal("matchMedia", (query: string) => ({
    matches,
    media: query,
    onchange: null,
    addEventListener: vi.fn(),
    removeEventListener: vi.fn(),
    addListener: vi.fn(),
    removeListener: vi.fn(),
    dispatchEvent: vi.fn(),
  }));
 }
 afterEach(() => {
  vi.unstubAllGlobals();
  localStorage.clear();
  document.documentElement.classList.remove("dark");
 });
 test("resolveTheme returns explicit values verbatim", () => {
  expect(resolveTheme("light")).toBe("light");
  expect(resolveTheme("dark")).toBe("dark");
 });
 test("resolveTheme maps system via prefers-color-scheme", () => {
  mockMatchMedia(true);
  expect(resolveTheme("system")).toBe("dark");
  mockMatchMedia(false);
  expect(resolveTheme("system")).toBe("light");
 });
 test("readTheme defaults to system when unset or invalid", () => {
  expect(readTheme()).toBe("system");
  localStorage.setItem(THEME_KEY, "bogus");
  expect(readTheme()).toBe("system");
  localStorage.setItem(THEME_KEY, "dark");
  expect(readTheme()).toBe("dark");
 });
 test("applyTheme toggles the dark class on documentElement", () => {
  mockMatchMedia(false);
  applyTheme("dark");
  expect(document.documentElement.classList.contains("dark")).toBe(true);
  applyTheme("light");
  expect(document.documentElement.classList.contains("dark")).toBe(false);
  mockMatchMedia(true);
  applyTheme("system");
  expect(document.documentElement.classList.contains("dark")).toBe(true);
 });
 ```
 - [ ] **Step 2: Run to verify it fails**
 Run: `cd web && pnpm vitest run src/theme/theme.test.ts`
 Expected: FAIL — cannot import from `./theme` (module not found).
 - [ ] **Step 3: Implement** — `web/src/theme/theme.ts`:
 ```ts
 export const THEME_KEY = "theme";
 export type Theme = "light" | "dark" | "system";
 const THEMES: readonly Theme[] = ["light", "dark", "system"];
 function prefersDark(): boolean {
  return (
    typeof window !== "undefined" &&
    typeof window.matchMedia === "function" &&
    window.matchMedia("(prefers-color-scheme: dark)").matches
  );
 }
 export function resolveTheme(theme: Theme): "light" | "dark" {
  if (theme === "light" || theme === "dark") return theme;
  return prefersDark() ? "dark" : "light";
 }
 export function readTheme(): Theme {
  if (typeof localStorage === "undefined") return "system";
  const stored = localStorage.getItem(THEME_KEY);
  return THEMES.includes(stored as Theme) ? (stored as Theme) : "system";
 }
 export function applyTheme(theme: Theme): void {
  if (typeof document === "undefined") return;
  document.documentElement.classList.toggle("dark", resolveTheme(theme) === "dark");
 }
 ```
 - [ ] **Step 4: Run to verify it passes**
 Run: `cd web && pnpm vitest run src/theme/theme.test.ts`
 Expected: PASS (4 tests).
 - [ ] **Step 5: Commit**
 ```bash
 git add web/src/theme/theme.ts web/src/theme/theme.test.ts
 git commit -m "feat(web): theme core — resolve/read/apply tri-state theme (#59)"
 ```
 ---
 # Task 2: `useTheme` hook
 **Files:**
 - Create: `web/src/theme/use-theme.ts`
 (No standalone unit test — the hook is exercised by `theme-switch.test.tsx` in Task 3, which drives it through real UI per the project's testing style. `theme.ts` carries the logic and is unit-tested in Task 1.)
 - [ ] **Step 1: Implement** — `web/src/theme/use-theme.ts`:
 ```ts
 import { useEffect, useState } from "react";
 import { applyTheme, readTheme, type Theme } from "./theme";
 export function useTheme(): { theme: Theme; setTheme: (theme: Theme) => void } {
  const [theme, setThemeState] = useState<Theme>(readTheme);
  const setTheme = (next: Theme) => {
    if (typeof localStorage !== "undefined") localStorage.setItem("theme", next);
    setThemeState(next);
    applyTheme(next);
  };
  useEffect(() => {
    applyTheme(theme);
    if (theme !== "system") return;
    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
    const mql = window.matchMedia("(prefers-color-scheme: dark)");
    const onChange = () => applyTheme("system");
    mql.addEventListener("change", onChange);
    return () => mql.removeEventListener("change", onChange);
  }, [theme]);
  return { theme, setTheme };
 }
 ```
 Note: import `THEME_KEY` from `./theme` and use it instead of the literal `"theme"` for the
 `localStorage.setItem` key (DRY with the core). Update the import line to
 `import { applyTheme, readTheme, THEME_KEY, type Theme } from "./theme";` and use
 `localStorage.setItem(THEME_KEY, next)`.
 - [ ] **Step 2: Typecheck**
 Run: `cd web && pnpm typecheck`
 Expected: PASS (no errors).
 - [ ] **Step 3: Commit**
 ```bash
 git add web/src/theme/use-theme.ts
 git commit -m "feat(web): useTheme hook with live system tracking (#59)"
 ```
 ---
 # Task 3: `ThemeSwitch` UI + i18n + tests + story
 **Files:**
 - Create: `web/src/shell/theme-switch.tsx`
 - Create: `web/src/shell/theme-switch.test.tsx`
 - Create: `web/src/shell/theme-switch.stories.tsx`
 - Modify: `web/src/i18n/en.json`, `web/src/i18n/sv.json`
 - [ ] **Step 1: Add i18n keys.** In `web/src/i18n/en.json`, add a top-level `theme` namespace (place after the `labels` entry):
 ```json
  "theme": { "light": "Light", "dark": "Dark", "system": "System" },
 ```
 In `web/src/i18n/sv.json`, the matching entry:
 ```json
  "theme": { "light": "Ljust", "dark": "Mörkt", "system": "System" },
 ```
 - [ ] **Step 2: Write the failing test** — `web/src/shell/theme-switch.test.tsx`:
 ```tsx
 import { afterEach, beforeEach, expect, test, vi } from "vitest";
 import { screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { renderApp } from "../test/render";
 import { ThemeSwitch } from "./theme-switch";
 beforeEach(() => {
  vi.stubGlobal("matchMedia", (query: string) => ({
    matches: false,
    media: query,
    onchange: null,
    addEventListener: vi.fn(),
    removeEventListener: vi.fn(),
    addListener: vi.fn(),
    removeListener: vi.fn(),
    dispatchEvent: vi.fn(),
  }));
 });
 afterEach(() => {
  vi.unstubAllGlobals();
  localStorage.clear();
  document.documentElement.classList.remove("dark");
 });
 test("selecting Dark applies the dark class and persists", async () => {
  renderApp(<ThemeSwitch />);
  await userEvent.click(screen.getByRole("button", { name: /dark/i }));
  expect(document.documentElement.classList.contains("dark")).toBe(true);
  expect(localStorage.getItem("theme")).toBe("dark");
  expect(screen.getByRole("button", { name: /dark/i })).toHaveAttribute(
    "aria-pressed",
    "true",
  );
 });
 test("selecting Light removes the dark class and persists", async () => {
  localStorage.setItem("theme", "dark");
  renderApp(<ThemeSwitch />);
  await userEvent.click(screen.getByRole("button", { name: /light/i }));
  expect(document.documentElement.classList.contains("dark")).toBe(false);
  expect(localStorage.getItem("theme")).toBe("light");
 });
 test("selecting System resolves via prefers-color-scheme", async () => {
  vi.stubGlobal("matchMedia", (query: string) => ({
    matches: true,
    media: query,
    onchange: null,
    addEventListener: vi.fn(),
    removeEventListener: vi.fn(),
    addListener: vi.fn(),
    removeListener: vi.fn(),
    dispatchEvent: vi.fn(),
  }));
  renderApp(<ThemeSwitch />);
  await userEvent.click(screen.getByRole("button", { name: /system/i }));
  expect(localStorage.getItem("theme")).toBe("system");
  expect(document.documentElement.classList.contains("dark")).toBe(true);
 });
 ```
 - [ ] **Step 3: Run to verify it fails**
 Run: `cd web && pnpm vitest run src/shell/theme-switch.test.tsx`
 Expected: FAIL — cannot import `ThemeSwitch`.
 - [ ] **Step 4: Implement** — `web/src/shell/theme-switch.tsx`:
 ```tsx
 import { Monitor, Moon, Sun } from "lucide-react";
 import { useTranslation } from "react-i18next";
 import { useTheme } from "../theme/use-theme";
 import type { Theme } from "../theme/theme";
 import { cn } from "@/lib/utils";
 const OPTIONS: { value: Theme; Icon: typeof Sun }[] = [
  { value: "light", Icon: Sun },
  { value: "dark", Icon: Moon },
  { value: "system", Icon: Monitor },
 ];
 export function ThemeSwitch() {
  const { t } = useTranslation();
  const { theme, setTheme } = useTheme();
  return (
    <div className="flex gap-1">
      {OPTIONS.map(({ value, Icon }) => {
        const active = theme === value;
        return (
          <button
            key={value}
            type="button"
            onClick={() => setTheme(value)}
            aria-pressed={active}
            aria-label={t(`theme.${value}`)}
            title={t(`theme.${value}`)}
            className={cn(
              "rounded-md p-1 transition-colors",
              active
                ? "bg-accent text-foreground"
                : "text-muted-foreground hover:text-foreground",
            )}
          >
            <Icon className="h-4 w-4" aria-hidden />
          </button>
        );
      })}
    </div>
  );
 }
 ```
 (Verify the `cn` import path matches the project — other `ui/*` files import `cn` from `@/lib/utils`. If `lib/utils` is absent, mirror whatever `button.tsx` uses.)
 - [ ] **Step 5: Run to verify it passes**
 Run: `cd web && pnpm vitest run src/shell/theme-switch.test.tsx`
 Expected: PASS (3 tests).
 - [ ] **Step 6: Write the Storybook story** — `web/src/shell/theme-switch.stories.tsx`:
 ```tsx
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { expect } from 'storybook/test'
 import { ThemeSwitch } from './theme-switch'
 const meta = {
  component: ThemeSwitch,
  tags: ['ai-generated'],
 } satisfies Meta<typeof ThemeSwitch>
 export default meta
 type Story = StoryObj<typeof meta>
 export const Default: Story = {
  play: async ({ canvas }) => {
    await expect(canvas.getByRole('button', { name: /light/i })).toBeInTheDocument()
    await expect(canvas.getByRole('button', { name: /dark/i })).toBeInTheDocument()
    await expect(canvas.getByRole('button', { name: /system/i })).toBeInTheDocument()
  },
 }
 ```
 (Note: the story exercises rendering only — it does not click options, to avoid mutating `<html>`
 globally across the browser-mode test run.)
 - [ ] **Step 7: Run the story as a test + lint**
 Run: `cd web && pnpm vitest run src/shell/theme-switch.stories.tsx && pnpm lint`
 Expected: PASS.
 - [ ] **Step 8: Commit**
 ```bash
 git add web/src/shell/theme-switch.tsx web/src/shell/theme-switch.test.tsx web/src/shell/theme-switch.stories.tsx web/src/i18n/en.json web/src/i18n/sv.json
 git commit -m "feat(web): ThemeSwitch icon segmented control + theme.* i18n (#59)"
 ```
 ---
 # Task 4: Mount in the header + FOUC inline script
 **Files:**
 - Modify: `web/src/shell/app-shell.tsx`
 - Modify: `web/index.html`
 - [ ] **Step 1: Mount `ThemeSwitch`.** In `web/src/shell/app-shell.tsx`, add the import:
 ```tsx
 import { ThemeSwitch } from "./theme-switch";
 ```
 and render it in the header immediately before `<LangSwitch />`:
 ```tsx
        <div className="flex-1" />
        <ThemeSwitch />
        <LangSwitch />
 ```
 (Match the existing header's exact JSX; only insert the one line. Do not change other markup.)
 - [ ] **Step 2: Add the FOUC-prevention inline script.** In `web/index.html`, inside `<head>`
  BEFORE the `<script type="module" src="/src/main.tsx">` tag, add:
 ```html
    <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>
 ```
 - [ ] **Step 3: Verify the app-shell test still passes** (the header now has an extra control):
 Run: `cd web && pnpm vitest run src/shell/app-shell.test.tsx`
 Expected: PASS (the existing "language switch" test is unaffected — ThemeSwitch buttons have distinct accessible names).
 - [ ] **Step 4: Build to verify `index.html` is valid**
 Run: `cd web && pnpm build`
 Expected: built successfully (Vite processes the inline script).
 - [ ] **Step 5: Commit**
 ```bash
 git add web/src/shell/app-shell.tsx web/index.html
 git commit -m "feat(web): mount ThemeSwitch in header + pre-paint theme init (#59)"
 ```
 ---
 # Task 5: Dark `--primary` contrast tweak + final verification
 **Files:**
 - Modify: `web/src/index.css`
 - [ ] **Step 1: Compute the new dark `--primary`.** The dark button label uses `--primary-foreground:
  oklch(0.205 0 0)` (near-black) on `--primary: oklch(0.673 0.182 276.935)` (~3.21:1). Lower the
  lightness (and keep it a recognizable indigo) until WCAG contrast vs `oklch(0.205 0 0)` is **≥4.5:1**.
  A good starting point is `oklch(0.62 0.20 277)`; compute the exact value with a contrast check
  (convert both to sRGB relative luminance, `(L1+0.05)/(L2+0.05) ≥ 4.5`). In the `.dark` block of
  `web/src/index.css`, update BOTH `--primary` and `--ring` (they must match) to the chosen value:
 ```css
  --primary: oklch(<chosen-L> <chosen-C> 277);
  ...
  --ring: oklch(<chosen-L> <chosen-C> 277);
 ```
 Leave `--primary-foreground: oklch(0.205 0 0)` and the entire `:root` (light) block unchanged.
 - [ ] **Step 2: Verify the contrast.** State the computed ratio in the commit body (must be ≥4.5:1).
  Sanity-check the value is still visibly indigo (hue ~277, chroma not flattened to gray).
 - [ ] **Step 3: Full gate (single test pass).**
 Run:
 ```bash
 cd web && pnpm typecheck && pnpm lint && pnpm test && pnpm build && pnpm check:size && pnpm check:colors
 ```
 Expected: all green. `check:colors` passes (icons are not color utilities). `check:size` within 250 KB
 gz (three lucide icons are negligible). Tests run exactly ONCE (no concurrent runs).
 - [ ] **Step 4: Codename + status checks.**
 ```bash
 git grep -in 'biggus\|dickus' -- web/src web/index.html; echo "codename-exit=$?"
 git status --short
 ```
 Expected: no codename matches; working tree shows only intended changes.
 - [ ] **Step 5: Manual smoke (recommended).** `pnpm dev`, toggle Light/Dark/System; confirm the app
  switches, a dark reload doesn't flash light, primary buttons are legible in dark, and switching the
  OS theme while in System updates the app live.
 - [ ] **Step 6: Commit**
 ```bash
 git add web/src/index.css
 git commit -m "fix(web): raise dark --primary contrast to AA for button labels (#59)"
 ```
 ---
 ## Self-Review (completed)
 **Spec coverage:** tri-state model + System default (T1 `resolveTheme`/`readTheme`, T3 UI); persisted
 to localStorage (T2 `setTheme`, T3 tests); `.dark` on `<html>` (T1 `applyTheme`); live system tracking
 (T2 `useEffect` matchMedia listener); FOUC prevention (T4 inline script); icon segmented control next
 to LangSwitch (T3 + T4 mount); en/sv `theme.*` (T3); aria-pressed/aria-label (T3); dark `--primary`
 contrast ≥4.5:1 + `--ring` sync (T5); gate incl. check:colors/check:size + no codename + no new dep
 (T5). All acceptance criteria 1–6 mapped. ✓
 **Placeholder scan:** the only "computed" value is the exact dark `--primary` OKLCH — a genuine WCAG
 measurement step with a concrete starting point and an explicit acceptance threshold (≥4.5:1), not a
 TODO. All code blocks are complete. ✓
 **Type consistency:** `Theme` type defined in `theme.ts` (T1), imported by `use-theme.ts` (T2) and
 `theme-switch.tsx` (T3); `THEME_KEY` from `theme.ts` used in T2's setter; `resolveTheme`/`readTheme`/
 `applyTheme` signatures consistent across tasks; i18n keys `theme.light/dark/system` defined in T3 and
 referenced by `t(\`theme.${value}\`)` in T3's component. ✓
 ## Notes
 - No new dependency (lucide-react already present; `.dark` tokens already exist from #49).
 - The inline FOUC script is intentionally plain ES5-ish + try/catch — it runs before the bundle and
  must never throw.
 - Cross-tab sync and per-account/server theme default are explicit follow-ups (not in this plan).
@@ -0,0 +1,149 @@
 # 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 `<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:
 ```html
 <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 />`:
 ```tsx
 <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
 1. A tri-state theme toggle (Light/Dark/System) appears in the header; default is System.
 2. 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.
 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).
@@ -4,6 +4,16 @@
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Collection</title>
    <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>
  </head>
  <body>
    <div id="root"></div>
@@ -9,6 +9,7 @@
  "form": { "selectPlaceholder": "— select —", "create": "Create object", "save": "Save", "cancel": "Cancel", "visibility": "Visibility", "draft": "Draft", "internal": "Internal", "required": "This field is required", "rejected": "The server rejected the changes — check required and referenced fields", "fieldRejected": "The field \"{{field}}\" was rejected — check its value", "flexibleHeading": "Catalogue fields" },
  "actions": { "edit": "Edit", "delete": "Delete", "rename": "Rename", "save": "Save", "closeDetail": "Close detail", "confirmDelete": "Delete this object? This cannot be undone.", "confirmDeleteTerm": "Delete this term? This cannot be undone.", "confirmDeleteAuthority": "Delete this authority? This cannot be undone.", "confirmDeleteField": "Delete this field definition? This cannot be undone.", "confirmDeleteVocabulary": "Delete this vocabulary? This cannot be undone.", "inUse": "Can't delete — used by {{count}} object(s). Clear those fields first." },
  "labels": { "label": "Label", "externalUri": "External URI (optional)", "otherLanguages": "This entry also has labels in other languages, which are kept." },
  "theme": { "light": "Light", "dark": "Dark", "system": "System" },
  "vocab": {
    "newVocabulary": "New vocabulary", "key": "Key",
    "create": "Create", "selectPrompt": "Select a vocabulary to manage its terms",
@@ -9,6 +9,7 @@
  "form": { "selectPlaceholder": "— välj —", "create": "Skapa föremål", "save": "Spara", "cancel": "Avbryt", "visibility": "Synlighet", "draft": "Utkast", "internal": "Intern", "required": "Fältet är obligatoriskt", "rejected": "Servern avvisade ändringarna — kontrollera obligatoriska och refererade fält", "fieldRejected": "Fältet \"{{field}}\" avvisades — kontrollera värdet", "flexibleHeading": "Katalogfält" },
  "actions": { "edit": "Redigera", "delete": "Ta bort", "rename": "Byt namn", "save": "Spara", "closeDetail": "Stäng detalj", "confirmDelete": "Ta bort detta föremål? Detta kan inte ångras.", "confirmDeleteTerm": "Ta bort denna term? Detta kan inte ångras.", "confirmDeleteAuthority": "Ta bort denna auktoritet? Detta kan inte ångras.", "confirmDeleteField": "Ta bort denna fältdefinition? Detta kan inte ångras.", "confirmDeleteVocabulary": "Ta bort denna vokabulär? Detta kan inte ångras.", "inUse": "Kan inte ta bort — används av {{count}} föremål. Rensa de fälten först." },
  "labels": { "label": "Etikett", "externalUri": "Extern URI (valfritt)", "otherLanguages": "Denna post har även etiketter på andra språk, som behålls." },
  "theme": { "light": "Ljust", "dark": "Mörkt", "system": "System" },
  "vocab": {
    "newVocabulary": "Ny vokabulär", "key": "Nyckel",
    "create": "Skapa", "selectPrompt": "Välj en vokabulär för att hantera dess termer",
@@ -69,7 +69,7 @@
  --card-foreground: oklch(0.985 0 0);
  --popover: oklch(0.205 0 0);
  --popover-foreground: oklch(0.985 0 0);
-  --primary: oklch(0.673 0.182 276.935);
+  --primary: oklch(0.72 0.18 277);
  --primary-foreground: oklch(0.205 0 0);
  --secondary: oklch(0.269 0 0);
  --secondary-foreground: oklch(0.985 0 0);
@@ -86,7 +86,7 @@
  --highlight-foreground: oklch(0.205 0 0);
  --border: oklch(1 0 0 / 10%);
  --input: oklch(1 0 0 / 15%);
-  --ring: oklch(0.673 0.182 276.935);
+  --ring: oklch(0.72 0.18 277);
 }
@layer base {
@@ -4,6 +4,7 @@ import { useTranslation } from "react-i18next";
 import { useLogout } from "../api/queries";
 import { Button } from "@/components/ui/button";
 import { LangSwitch } from "./lang-switch";
 import { ThemeSwitch } from "./theme-switch";
 import { Sidebar } from "./sidebar";
 export function AppShell() {
@@ -22,6 +23,7 @@ export function AppShell() {
      <div className="flex flex-1 flex-col">
        <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")}
@@ -0,0 +1,20 @@
 import type { Meta, StoryObj } from '@storybook/react-vite'
 import { expect } from 'storybook/test'
 import { ThemeSwitch } from './theme-switch'
 const meta = {
  component: ThemeSwitch,
  tags: ['ai-generated'],
 } satisfies Meta<typeof ThemeSwitch>
 export default meta
 type Story = StoryObj<typeof meta>
 export const Default: Story = {
  play: async ({ canvas }) => {
    await expect(canvas.getByRole('button', { name: /light/i })).toBeInTheDocument()
    await expect(canvas.getByRole('button', { name: /dark/i })).toBeInTheDocument()
    await expect(canvas.getByRole('button', { name: /system/i })).toBeInTheDocument()
  },
 }
@@ -0,0 +1,57 @@
 import { afterEach, beforeEach, expect, test, vi } from "vitest";
 import { screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { renderApp } from "../test/render";
 import { ThemeSwitch } from "./theme-switch";
 beforeEach(() => {
  vi.stubGlobal("matchMedia", (query: string) => ({
    matches: false,
    media: query,
    onchange: null,
    addEventListener: vi.fn(),
    removeEventListener: vi.fn(),
    addListener: vi.fn(),
    removeListener: vi.fn(),
    dispatchEvent: vi.fn(),
  }));
 });
 afterEach(() => {
  vi.unstubAllGlobals();
  localStorage.clear();
  document.documentElement.classList.remove("dark");
 });
 test("selecting Dark applies the dark class and persists", async () => {
  renderApp(<ThemeSwitch />);
  await userEvent.click(screen.getByRole("button", { name: /dark/i }));
  expect(document.documentElement.classList.contains("dark")).toBe(true);
  expect(localStorage.getItem("theme")).toBe("dark");
  expect(screen.getByRole("button", { name: /dark/i })).toHaveAttribute("aria-pressed", "true");
 });
 test("selecting Light removes the dark class and persists", async () => {
  localStorage.setItem("theme", "dark");
  renderApp(<ThemeSwitch />);
  await userEvent.click(screen.getByRole("button", { name: /light/i }));
  expect(document.documentElement.classList.contains("dark")).toBe(false);
  expect(localStorage.getItem("theme")).toBe("light");
 });
 test("selecting System resolves via prefers-color-scheme", async () => {
  vi.stubGlobal("matchMedia", (query: string) => ({
    matches: true,
    media: query,
    onchange: null,
    addEventListener: vi.fn(),
    removeEventListener: vi.fn(),
    addListener: vi.fn(),
    removeListener: vi.fn(),
    dispatchEvent: vi.fn(),
  }));
  renderApp(<ThemeSwitch />);
  await userEvent.click(screen.getByRole("button", { name: /system/i }));
  expect(localStorage.getItem("theme")).toBe("system");
  expect(document.documentElement.classList.contains("dark")).toBe(true);
 });
@@ -0,0 +1,43 @@
 import { Monitor, Moon, Sun } from "lucide-react";
 import { useTranslation } from "react-i18next";
 import { useTheme } from "../theme/use-theme";
 import type { Theme } from "../theme/theme";
 import { cn } from "@/lib/utils";
 const OPTIONS: { value: Theme; Icon: typeof Sun }[] = [
  { value: "light", Icon: Sun },
  { value: "dark", Icon: Moon },
  { value: "system", Icon: Monitor },
 ];
 export function ThemeSwitch() {
  const { t } = useTranslation();
  const { theme, setTheme } = useTheme();
  return (
    <div className="flex gap-1">
      {OPTIONS.map(({ value, Icon }) => {
        const active = theme === value;
        return (
          <button
            key={value}
            type="button"
            onClick={() => setTheme(value)}
            aria-pressed={active}
            aria-label={t(`theme.${value}`)}
            title={t(`theme.${value}`)}
            className={cn(
              "rounded-md p-1 transition-colors",
              active
                ? "bg-accent text-foreground"
                : "text-muted-foreground hover:text-foreground",
            )}
          >
            <Icon className="h-4 w-4" aria-hidden />
          </button>
        );
      })}
    </div>
  );
 }
@@ -0,0 +1,52 @@
 import { afterEach, expect, test, vi } from "vitest";
 import { applyTheme, readTheme, resolveTheme, THEME_KEY } from "./theme";
 function mockMatchMedia(matches: boolean) {
  vi.stubGlobal("matchMedia", (query: string) => ({
    matches,
    media: query,
    onchange: null,
    addEventListener: vi.fn(),
    removeEventListener: vi.fn(),
    addListener: vi.fn(),
    removeListener: vi.fn(),
    dispatchEvent: vi.fn(),
  }));
 }
 afterEach(() => {
  vi.unstubAllGlobals();
  localStorage.clear();
  document.documentElement.classList.remove("dark");
 });
 test("resolveTheme returns explicit values verbatim", () => {
  expect(resolveTheme("light")).toBe("light");
  expect(resolveTheme("dark")).toBe("dark");
 });
 test("resolveTheme maps system via prefers-color-scheme", () => {
  mockMatchMedia(true);
  expect(resolveTheme("system")).toBe("dark");
  mockMatchMedia(false);
  expect(resolveTheme("system")).toBe("light");
 });
 test("readTheme defaults to system when unset or invalid", () => {
  expect(readTheme()).toBe("system");
  localStorage.setItem(THEME_KEY, "bogus");
  expect(readTheme()).toBe("system");
  localStorage.setItem(THEME_KEY, "dark");
  expect(readTheme()).toBe("dark");
 });
 test("applyTheme toggles the dark class on documentElement", () => {
  mockMatchMedia(false);
  applyTheme("dark");
  expect(document.documentElement.classList.contains("dark")).toBe(true);
  applyTheme("light");
  expect(document.documentElement.classList.contains("dark")).toBe(false);
  mockMatchMedia(true);
  applyTheme("system");
  expect(document.documentElement.classList.contains("dark")).toBe(true);
 });
@@ -0,0 +1,33 @@
 export const THEME_KEY = "theme";
 export type Theme = "light" | "dark" | "system";
 const THEMES: readonly Theme[] = ["light", "dark", "system"];
 function prefersDark(): boolean {
  return (
    typeof window !== "undefined" &&
    typeof window.matchMedia === "function" &&
    window.matchMedia("(prefers-color-scheme: dark)").matches
  );
 }
 export function resolveTheme(theme: Theme): "light" | "dark" {
  if (theme === "light" || theme === "dark") return theme;
  return prefersDark() ? "dark" : "light";
 }
 export function readTheme(): Theme {
  if (typeof localStorage === "undefined") return "system";
  const stored = localStorage.getItem(THEME_KEY);
  return THEMES.includes(stored as Theme) ? (stored as Theme) : "system";
 }
 export function applyTheme(theme: Theme): void {
  if (typeof document === "undefined") return;
  document.documentElement.classList.toggle("dark", resolveTheme(theme) === "dark");
 }
@@ -0,0 +1,25 @@
 import { useEffect, useState } from "react";
 import { applyTheme, readTheme, THEME_KEY, type Theme } from "./theme";
 export function useTheme(): { theme: Theme; setTheme: (theme: Theme) => void } {
  const [theme, setThemeState] = useState<Theme>(readTheme);
  const setTheme = (next: Theme) => {
    if (typeof localStorage !== "undefined") localStorage.setItem(THEME_KEY, next);
    setThemeState(next);
    applyTheme(next);
  };
  useEffect(() => {
    applyTheme(theme);
    if (theme !== "system") return;
    if (typeof window === "undefined" || typeof window.matchMedia !== "function") return;
    const mql = window.matchMedia("(prefers-color-scheme: dark)");
    const onChange = () => applyTheme("system");
    mql.addEventListener("change", onChange);
    return () => mql.removeEventListener("change", onChange);
  }, [theme]);
  return { theme, setTheme };
 }