diff --git a/README.md b/README.md
index fc64336..dc2477c 100644
--- a/README.md
+++ b/README.md
@@ -74,8 +74,52 @@ This is **Identity System v1** — see [Brand assets](#brand-assets):
   `next/font/google`.
 - **Dark theme** — a token-level flip in `globals.css`. It follows
   `prefers-color-scheme` by default; a stored preference stamps `data-theme` on
-  `<html>` and wins in both directions (`ThemeToggle` in the navbar, with a
-  no-FOUC script in the layout).
+  `<html>` and wins in both directions. Theme state is owned by
+  `<ThemeProvider>` (`src/components/theme/`) via the `useTheme` hook — the
+  per-user choice is persisted to localStorage, the OS preference is followed
+  live until a choice is made, and a no-FOUC script in the layout paints the
+  initial theme before React hydrates (`ThemeToggle` in the navbar).
+
+#### Theme usage (light & dark mode)
+
+`src/lib/theme.ts` is the single source of truth for theme logic: the `Theme`
+type, the `THEME_STORAGE_KEY` constant, storage get/set, system-preference
+resolution and listening, and the shared no-FOUC `themeScript`. Components read
+`resolvedTheme` and call `setTheme` / `toggleTheme` through the `useTheme()`
+hook from `src/components/theme/`.
+
+Two wiring steps are required in the root layout
+(`src/app/layout.tsx`) — both are already in place; keep them if you ever
+rewrite the layout:
+
+1. **Paint before React hydrates (no flash).** Insert the exported inline
+   script in `<head>` via React's safe `<script dangerouslySetInnerHTML>`
+   API. It stamps `<html data-theme>` + `color-scheme` from the stored
+   choice, falling back to the OS preference:
+
+   ```tsx
+   import { themeScript } from "@/lib/theme";
+
+   // inside <head>:
+   <script dangerouslySetInnerHTML={{ __html: themeScript }} />
+   ```
+
+2. **Wrap the whole app in `<ThemeProvider>`** so every theme-aware
+   component reads a consistent `resolvedTheme` (and re-renders on change)
+   from its very first render:
+
+   ```tsx
+   <ThemeProvider>
+     {/* Navbar (with <ThemeToggle />), main, footer, toasts … */}
+   </ThemeProvider>
+   ```
+
+The per-user choice is persisted to localStorage under `THEME_STORAGE_KEY`
+and wins over the OS preference; until a choice is made the app follows
+`prefers-color-scheme` live. The navy/gold/terracotta **color tokens** and
+their dark-mode overrides live in `src/app/globals.css` (the `@theme inline`
+block plus `data-theme` overrides) — update them there if the brand palette
+ever changes.
 
 ## Brand assets
 
@@ -242,10 +286,12 @@ npx eslint .        # lint
 npx next build      # production build, also runs a TypeScript check
 ```
 
-There's no dedicated unit/integration test suite yet — verification today is
-type-checking, linting, a production build, and Playwright-driven smoke
-testing of every route (checking for console errors, layout overflow, and
-broken images) done ad hoc during review rather than committed as a CI suite.
+Unit tests live in `src/lib/test/` (theme system, timezone, slot locking,
+escrow funding, identity verification) and run with `npm test`. Verification
+today is `npm test`, type-checking, linting, a production build, and
+Playwright-driven smoke testing of every route (checking for console errors,
+layout overflow, and broken images) done ad hoc during review rather than
+committed as a CI suite.
 
 ## Deployment
 
diff --git a/TODO.md b/TODO.md
index c82092f..0e5bf56 100644
--- a/TODO.md
+++ b/TODO.md
@@ -1,16 +1,57 @@
-# Transaction Notification Center — Implementation Checklist ✓
+# Design-System Theme Provider (navy/gold/terracotta) — Implementation Checklist ✓
+
+## Objective
+Codify the navy/gold/terracotta identity system into a theme provider with
+accessible light and dark modes persisted per user (issue #30).
 
 ## Files to Create
-- [x] `src/lib/notifications.ts` — Types, interfaces, and helper functions
-- [x] `src/components/notifications/useNotifications.tsx` — React Context, Provider, and hook
-- [x] `src/components/notifications/NotificationToast.tsx` — Floating toast component
-- [x] `src/components/notifications/NotificationCenter.tsx` — Dropdown panel with notification list
+- [x] `src/lib/theme.ts` — Theme system single source of truth: `Theme` type,
+      `THEME_STORAGE_KEY`, storage get/set, `getSystemTheme`, `applyTheme`,
+      `listenForSystemTheme`, `resolveTheme`, and the shared no-FOUC
+      `themeScript`.
+- [x] `src/components/theme/ThemeProvider.tsx` — React Context provider +
+      `useTheme` hook (stored choice wins, OS preference followed live until
+      the user picks).
+- [x] `src/components/theme/index.ts` — Barrel export (matches
+      `notifications/index.ts`).
+- [x] `src/lib/test/theme.test.ts` — Unit tests (storage, resolution,
+      application, system listening, script).
 
 ## Files to Edit
-- [x] `src/app/layout.tsx` — Wrap with NotificationProvider
-- [x] `src/components/Navbar.tsx` — Add bell icon with unread count badge
+- [x] `src/components/ThemeToggle.tsx` — Consume `useTheme`; added
+      `aria-pressed`; visuals unchanged.
+- [x] `src/app/layout.tsx` — Wrap app in `<ThemeProvider>`; inline no-FOUC
+      script now imported from `@/lib/theme` (single source of truth).
+
+## Architectural Decisions
+- **No new dependencies.** Uses React Context (existing pattern from
+  `NotificationProvider`), `react-icons` (already a dep), and the existing
+  Tailwind v4 token setup.
+- **Tokens stay in CSS.** The navy/gold/terracotta tokens and their dark-mode
+  overrides live in `src/app/globals.css` via `@theme inline` + `data-theme`
+  (this was already in place). `src/lib/theme.ts` owns the *logic* around
+  those tokens.
+- **Persistence is per-user via localStorage** (key `theme`) — the same
+  mechanism the previous standalone toggle used, so existing stored choices
+  keep working. No auth/session exists yet, so browser-local is the right
+  scope; a per-account key can be layered on later.
+- **Dark mode is a first-class, accessible mode:** `color-scheme` is set so
+  native controls adapt, focus rings use `outline-gold`, and the toggle
+  exposes `aria-label` + `aria-pressed`.
+- **No flash of wrong theme (FOUC):** the root layout's inline
+  `themeScript` (now imported from `@/lib/theme`) paints the correct theme
+  before React hydrates; the provider only keeps React state in sync.
+- **OS-follow by default:** until the user makes an explicit choice the
+  provider follows `prefers-color-scheme` live; choosing persists and stops
+  following.
 
 ## Verification
 - [x] `npm run lint` — No linting errors
-- [x] `npm run build` — Production build succeeds (17 routes)
+- [x] `npm run typecheck` — No TypeScript errors
+- [x] `npm test` — All tests pass (incl. `theme.test.ts`)
+- [x] `npm run build` — Production build succeeds
 
+## CI Note
+The issue's "add caching for npm dependencies in CI" task was already
+satisfied: `.github/workflows/ci.yml` uses `actions/setup-node` with
+`cache: npm`.
diff --git a/src/app/layout.tsx b/src/app/layout.tsx
index 05a0b4e..e3661a2 100644
--- a/src/app/layout.tsx
+++ b/src/app/layout.tsx
@@ -4,18 +4,16 @@ import "leaflet/dist/leaflet.css";
 import "./globals.css";
 import Navbar from "@/components/Navbar";
 import Footer from "@/components/Footer";
+import { ThemeProvider } from "@/components/theme";
 import { NotificationProvider } from "@/components/notifications/useNotifications";
 import NotificationToast from "@/components/notifications/NotificationToast";
+import { themeScript } from "@/lib/theme";
 
 const inter = Inter({
   variable: "--font-inter",
   subsets: ["latin"],
 });
 
-// Runs before paint so the correct theme is applied with no flash: honour a
-// stored preference, otherwise fall back to the OS setting (handled in CSS).
-const themeScript = `(function(){try{var t=localStorage.getItem('theme');var r=document.documentElement;if(t==='light'||t==='dark'){r.setAttribute('data-theme',t);r.style.colorScheme=t;}else{r.style.colorScheme=window.matchMedia('(prefers-color-scheme: dark)').matches?'dark':'light';}}catch(e){}})();`;
-
 export const metadata: Metadata = {
   title: "GuildWorkman — Book trusted local pros",
   description:
@@ -30,15 +28,25 @@ export default function RootLayout({
   return (
     <html lang="en" suppressHydrationWarning className={`${inter.variable} h-full antialiased`}>
       <head>
+        {/*
+         * No-FOUC theme script: paints <html data-theme> + color-scheme
+         * before React hydrates. dangerouslySetInnerHTML is React's
+         * sanctioned way to emit an inline script; `themeScript` is an
+         * immutable, minified const whose only interpolations are
+         * compile-time constants (never user input), so there's no XSS
+         * surface here.
+         */}
         <script dangerouslySetInnerHTML={{ __html: themeScript }} />
       </head>
       <body className="min-h-full flex flex-col bg-sand text-ink">
-        <NotificationProvider>
-          <Navbar />
-          <main className="flex-1">{children}</main>
-          <Footer />
-          <NotificationToast />
-        </NotificationProvider>
+        <ThemeProvider>
+          <NotificationProvider>
+            <Navbar />
+            <main className="flex-1">{children}</main>
+            <Footer />
+            <NotificationToast />
+          </NotificationProvider>
+        </ThemeProvider>
       </body>
     </html>
   );
diff --git a/src/components/ThemeToggle.tsx b/src/components/ThemeToggle.tsx
index 8db74b9..5603789 100644
--- a/src/components/ThemeToggle.tsx
+++ b/src/components/ThemeToggle.tsx
@@ -1,48 +1,31 @@
 "use client";
 
-import { useEffect, useState } from "react";
 import { FaSun, FaMoon } from "react-icons/fa6";
+import { useTheme } from "./theme";
 
-type Theme = "light" | "dark";
-
-/** Light/dark toggle. Defaults to the system preference; once toggled,
-    the choice is stamped on <html data-theme> and persisted. The initial
-    paint is handled by the inline script in the root layout (no FOUC). */
+/** Light/dark toggle. State is owned by <ThemeProvider> (per-user choice
+    persisted to localStorage; OS preference followed until a choice is
+    made). The initial paint is handled by the inline script in the root
+    layout, so there is no flash of the wrong theme. */
 export default function ThemeToggle() {
-  const [theme, setTheme] = useState<Theme | null>(null);
-
-  useEffect(() => {
-    const stored = localStorage.getItem("theme");
-    if (stored === "light" || stored === "dark") {
-      setTheme(stored);
-    } else {
-      setTheme(window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
-    }
-  }, []);
-
-  const toggle = () => {
-    const next: Theme = theme === "dark" ? "light" : "dark";
-    setTheme(next);
-    const root = document.documentElement;
-    root.setAttribute("data-theme", next);
-    root.style.colorScheme = next;
-    localStorage.setItem("theme", next);
-  };
+  const { resolvedTheme, toggleTheme } = useTheme();
+  const isDark = resolvedTheme === "dark";
 
   return (
     <button
       type="button"
-      onClick={toggle}
-      aria-label={theme === "dark" ? "Switch to light theme" : "Switch to dark theme"}
+      onClick={toggleTheme}
+      aria-label="Toggle color theme"
+      aria-pressed={isDark}
       className="flex h-9 w-9 items-center justify-center rounded-xl border border-line text-muted transition hover:border-navy-2 hover:text-ink focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-gold"
     >
       {/* Render nothing until mounted to avoid a mismatched icon flash */}
-      {theme === "dark" ? (
+      {resolvedTheme === null ? (
+        <span className="h-[0.95rem] w-[0.95rem]" />
+      ) : isDark ? (
         <FaSun aria-hidden className="text-[0.95rem]" />
-      ) : theme === "light" ? (
-        <FaMoon aria-hidden className="text-[0.95rem]" />
       ) : (
-        <span className="h-[0.95rem] w-[0.95rem]" />
+        <FaMoon aria-hidden className="text-[0.95rem]" />
       )}
     </button>
   );
diff --git a/src/components/theme/ThemeProvider.tsx b/src/components/theme/ThemeProvider.tsx
new file mode 100644
index 0000000..b7728d9
--- /dev/null
+++ b/src/components/theme/ThemeProvider.tsx
@@ -0,0 +1,109 @@
+"use client";
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from "react";
+import {
+  applyTheme,
+  getStoredTheme,
+  getSystemTheme,
+  listenForSystemTheme,
+  setStoredTheme,
+  type Theme,
+} from "@/lib/theme";
+
+// ── Context shape ──────────────────────────────────────────────────────
+interface ThemeContextValue {
+  /** The user's explicit choice, or `null` while following the OS. */
+  theme: Theme | null;
+  /**
+   * The effective theme — the user's explicit choice once made, otherwise
+   * the OS preference. `null` only for the single render before the
+   * initialisation effect runs (render nothing theme-dependent then).
+   */
+  resolvedTheme: Theme | null;
+  /** Persist and apply an explicit choice. */
+  setTheme: (theme: Theme) => void;
+  /** Flip between light and dark, persisting the choice. */
+  toggleTheme: () => void;
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+// ── Provider ───────────────────────────────────────────────────────────
+/**
+ * Owns the navy/gold/terracotta light & dark modes. A stored per-user
+ * choice wins; otherwise the OS preference is followed live until the user
+ * picks. The root layout's inline script paints the initial theme before
+ * React hydrates, so this provider only keeps React state + <html> in sync
+ * — never a visible flash.
+ */
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const [theme, setThemeState] = useState<Theme | null>(null);
+  const [systemTheme, setSystemTheme] = useState<Theme | null>(null);
+
+  // Initialise once: honour a stored choice, else resolve the OS
+  // preference. The no-FOUC script in the layout has already painted the
+  // correct theme by now, so this is pure state synchronisation.
+  useEffect(() => {
+    const stored = getStoredTheme();
+    if (stored) {
+      setThemeState(stored);
+      return;
+    }
+    setSystemTheme(getSystemTheme());
+  }, []);
+
+  // Apply changes to <html> and keep following the OS live, but only while
+  // the user has not made an explicit choice. When `theme` becomes non-null
+  // this effect returns early without subscribing — and because React runs
+  // the previous effect's cleanup first, the OS listener is unsubscribed the
+  // moment an explicit choice is made (and again on unmount). So the promise
+  // holds: "stored per-user choice wins; otherwise OS preference followed
+  // live until the user chooses."
+  useEffect(() => {
+    const resolved = theme ?? systemTheme;
+    if (resolved) applyTheme(resolved);
+    if (theme) return;
+    return listenForSystemTheme(setSystemTheme);
+  }, [theme, systemTheme]);
+
+  const setTheme = useCallback((next: Theme) => {
+    setThemeState(next);
+    setStoredTheme(next);
+  }, []);
+
+  const toggleTheme = useCallback(() => {
+    // resolvedTheme may still be null for a single pre-effect render;
+    // fall back to the OS preference so the first click is always right.
+    const resolved = theme ?? systemTheme ?? getSystemTheme();
+    setTheme(resolved === "dark" ? "light" : "dark");
+  }, [theme, systemTheme, setTheme]);
+
+  const value = useMemo<ThemeContextValue>(
+    () => ({
+      theme,
+      resolvedTheme: theme ?? systemTheme,
+      setTheme,
+      toggleTheme,
+    }),
+    [theme, systemTheme, setTheme, toggleTheme]
+  );
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}
+
+// ── Hook ───────────────────────────────────────────────────────────────
+export function useTheme(): ThemeContextValue {
+  const ctx = useContext(ThemeContext);
+  if (!ctx) {
+    throw new Error("useTheme must be used within a <ThemeProvider>");
+  }
+  return ctx;
+}
diff --git a/src/components/theme/index.ts b/src/components/theme/index.ts
new file mode 100644
index 0000000..81bd8a0
--- /dev/null
+++ b/src/components/theme/index.ts
@@ -0,0 +1,4 @@
+// Barrel for the theme system (same pattern as notifications/index.ts).
+// ThemeProvider only imports from "@/lib/theme" — nothing here imports back
+// through this barrel — so re-exporting creates no circular-import risk.
+export { ThemeProvider, useTheme } from "./ThemeProvider";
diff --git a/src/lib/test/setup.ts b/src/lib/test/setup.ts
new file mode 100644
index 0000000..41d663f
--- /dev/null
+++ b/src/lib/test/setup.ts
@@ -0,0 +1,4 @@
+// React 19 requires this flag so `act(...)` runs in the dedicated
+// "act environment" mode instead of warning that the environment isn't
+// configured for it. Vitest loads this file before every test file.
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
diff --git a/src/lib/test/theme.test.ts b/src/lib/test/theme.test.ts
new file mode 100644
index 0000000..9724dee
--- /dev/null
+++ b/src/lib/test/theme.test.ts
@@ -0,0 +1,206 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  THEME_STORAGE_KEY,
+  applyTheme,
+  getStoredTheme,
+  getSystemTheme,
+  isTheme,
+  listenForSystemTheme,
+  resolveTheme,
+  setStoredTheme,
+  themeScript,
+} from "../theme";
+
+const SYSTEM_DARK_QUERY = "(prefers-color-scheme: dark)";
+
+/** jsdom has no matchMedia — stub it with a controllable mock. */
+function stubMatchMedia(matches: boolean) {
+  const listeners = new Set<(event: MediaQueryListEvent) => void>();
+  const mql = {
+    matches,
+    media: SYSTEM_DARK_QUERY,
+    addEventListener: vi.fn((_: string, cb: () => void) => listeners.add(cb)),
+    removeEventListener: vi.fn((_: string, cb: () => void) => listeners.delete(cb)),
+  };
+  window.matchMedia = vi.fn().mockReturnValue(mql) as unknown as typeof window.matchMedia;
+  return { mql, listeners };
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+  document.documentElement.removeAttribute("data-theme");
+  document.documentElement.style.colorScheme = "";
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("isTheme", () => {
+  it("accepts only the two supported themes", () => {
+    expect(isTheme("light")).toBe(true);
+    expect(isTheme("dark")).toBe(true);
+    expect(isTheme("system")).toBe(false);
+    expect(isTheme("")).toBe(false);
+    expect(isTheme(null)).toBe(false);
+    expect(isTheme(undefined)).toBe(false);
+  });
+});
+
+describe("getStoredTheme / setStoredTheme", () => {
+  it("returns null when nothing has been stored", () => {
+    expect(getStoredTheme()).toBeNull();
+  });
+
+  it("round-trips a stored choice", () => {
+    setStoredTheme("dark");
+    expect(window.localStorage.getItem(THEME_STORAGE_KEY)).toBe("dark");
+    expect(getStoredTheme()).toBe("dark");
+  });
+
+  it("treats an invalid stored value as no preference", () => {
+    window.localStorage.setItem(THEME_STORAGE_KEY, "neon");
+    expect(getStoredTheme()).toBeNull();
+  });
+
+  it("recovers gracefully when localStorage is unavailable", () => {
+    vi.spyOn(Storage.prototype, "getItem").mockImplementation(() => {
+      throw new Error("blocked");
+    });
+    expect(getStoredTheme()).toBeNull();
+
+    vi.spyOn(Storage.prototype, "setItem").mockImplementation(() => {
+      throw new Error("blocked");
+    });
+    expect(() => setStoredTheme("light")).not.toThrow();
+  });
+
+  it("is a safe no-op when window is unavailable (SSR)", () => {
+    vi.stubGlobal("window", undefined);
+    try {
+      expect(getStoredTheme()).toBeNull();
+      expect(() => setStoredTheme("dark")).not.toThrow();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+});
+
+describe("getSystemTheme", () => {
+  it("falls back to light when matchMedia is unavailable", () => {
+    // jsdom ships no matchMedia, so this is the un-stubbed path.
+    expect(getSystemTheme()).toBe("light");
+  });
+
+  it("reports dark when the OS prefers dark", () => {
+    stubMatchMedia(true);
+    expect(getSystemTheme()).toBe("dark");
+  });
+
+  it("reports light when the OS prefers light", () => {
+    stubMatchMedia(false);
+    expect(getSystemTheme()).toBe("light");
+  });
+
+  it("falls back to light when window is unavailable (SSR)", () => {
+    vi.stubGlobal("window", undefined);
+    try {
+      expect(getSystemTheme()).toBe("light");
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+});
+
+describe("resolveTheme", () => {
+  it("lets a stored choice win over the OS preference", () => {
+    expect(resolveTheme("light", "dark")).toBe("light");
+    expect(resolveTheme("dark", "light")).toBe("dark");
+  });
+
+  it("falls back to the OS preference when nothing is stored", () => {
+    expect(resolveTheme(null, "dark")).toBe("dark");
+    expect(resolveTheme(null, "light")).toBe("light");
+  });
+});
+
+describe("applyTheme", () => {
+  it("stamps <html data-theme> and color-scheme", () => {
+    applyTheme("dark");
+    expect(document.documentElement.getAttribute("data-theme")).toBe("dark");
+    expect(document.documentElement.style.colorScheme).toBe("dark");
+
+    applyTheme("light");
+    expect(document.documentElement.getAttribute("data-theme")).toBe("light");
+    expect(document.documentElement.style.colorScheme).toBe("light");
+  });
+});
+
+describe("listenForSystemTheme", () => {
+  it("notifies on OS preference changes and unsubscribes", () => {
+    const { listeners } = stubMatchMedia(false);
+    const onChange = vi.fn();
+
+    const unsubscribe = listenForSystemTheme(onChange);
+    expect(window.matchMedia).toHaveBeenCalledWith(SYSTEM_DARK_QUERY);
+
+    // Simulate the OS switching to dark.
+    listeners.forEach((cb) => cb({ matches: true } as MediaQueryListEvent));
+    expect(onChange).toHaveBeenCalledWith("dark");
+
+    unsubscribe();
+    listeners.forEach((cb) => cb({ matches: false } as MediaQueryListEvent));
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("is a no-op without matchMedia", () => {
+    expect(() => listenForSystemTheme(vi.fn())).not.toThrow();
+  });
+
+  it("is a no-op when window is unavailable (SSR)", () => {
+    vi.stubGlobal("window", undefined);
+    try {
+      const unsubscribe = listenForSystemTheme(vi.fn());
+      expect(() => unsubscribe()).not.toThrow();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it("falls back to legacy addListener/removeListener when addEventListener is absent", () => {
+    const listeners = new Set<(event: MediaQueryListEvent) => void>();
+    const mql = {
+      matches: false,
+      media: SYSTEM_DARK_QUERY,
+      addListener: vi.fn((cb: (event: MediaQueryListEvent) => void) => listeners.add(cb)),
+      removeListener: vi.fn((cb: (event: MediaQueryListEvent) => void) => listeners.delete(cb)),
+    } as unknown as MediaQueryList;
+    window.matchMedia = vi.fn().mockReturnValue(mql) as unknown as typeof window.matchMedia;
+
+    const onChange = vi.fn();
+    const unsubscribe = listenForSystemTheme(onChange);
+
+    // The modern API is absent, so the legacy path is used.
+    expect(mql.addEventListener).toBeUndefined();
+    expect(mql.addListener).toHaveBeenCalledTimes(1);
+
+    // Simulate the OS switching to dark via the legacy callback.
+    listeners.forEach((cb) => cb({ matches: true } as MediaQueryListEvent));
+    expect(onChange).toHaveBeenCalledWith("dark");
+
+    unsubscribe();
+    expect(mql.removeListener).toHaveBeenCalledTimes(1);
+    listeners.forEach((cb) => cb({ matches: false } as MediaQueryListEvent));
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("themeScript", () => {
+  it("is a self-contained script that reads the shared storage key", () => {
+    expect(themeScript).toContain(THEME_STORAGE_KEY);
+    expect(themeScript).toContain("data-theme");
+    expect(themeScript).toContain("prefers-color-scheme");
+    // Must be an IIFE guarding against storage errors, not rely on imports.
+    expect(themeScript.startsWith("(function(){try{")).toBe(true);
+  });
+});
diff --git a/src/lib/test/themeProvider.test.tsx b/src/lib/test/themeProvider.test.tsx
new file mode 100644
index 0000000..25776e6
--- /dev/null
+++ b/src/lib/test/themeProvider.test.tsx
@@ -0,0 +1,134 @@
+import { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ThemeProvider, useTheme } from "../../components/theme";
+import { THEME_STORAGE_KEY } from "../theme";
+
+const SYSTEM_DARK_QUERY = "(prefers-color-scheme: dark)";
+
+/** jsdom has no matchMedia — stub it with a controllable mock. */
+function stubMatchMedia(matches: boolean) {
+  const listeners = new Set<(event: MediaQueryListEvent) => void>();
+  const mql = {
+    matches,
+    media: SYSTEM_DARK_QUERY,
+    addEventListener: vi.fn((_: string, cb: (event: MediaQueryListEvent) => void) => listeners.add(cb)),
+    removeEventListener: vi.fn((_: string, cb: (event: MediaQueryListEvent) => void) => listeners.delete(cb)),
+  };
+  window.matchMedia = vi.fn().mockReturnValue(mql) as unknown as typeof window.matchMedia;
+  return { mql, listeners };
+}
+
+/** Minimal consumer exposing the hook's values through DOM nodes. */
+function ThemeConsumer() {
+  const { resolvedTheme, setTheme, toggleTheme } = useTheme();
+  return (
+    <div>
+      <span data-testid="resolved">{resolvedTheme ?? "none"}</span>
+      <button data-testid="set-light" onClick={() => setTheme("light")}>
+        light
+      </button>
+      <button data-testid="set-dark" onClick={() => setTheme("dark")}>
+        dark
+      </button>
+      <button data-testid="toggle" onClick={toggleTheme}>
+        toggle
+      </button>
+    </div>
+  );
+}
+
+let container: HTMLDivElement;
+let root: Root;
+
+beforeEach(() => {
+  window.localStorage.clear();
+  document.documentElement.removeAttribute("data-theme");
+  document.documentElement.style.colorScheme = "";
+  container = document.createElement("div");
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+  vi.restoreAllMocks();
+});
+
+function render() {
+  act(() => {
+    root.render(
+      <ThemeProvider>
+        <ThemeConsumer />
+      </ThemeProvider>
+    );
+  });
+}
+
+function resolvedThemeText() {
+  return container.querySelector('[data-testid="resolved"]')!.textContent;
+}
+
+function click(testid: string) {
+  act(() => {
+    container
+      .querySelector(`[data-testid="${testid}"]`)!
+      .dispatchEvent(new MouseEvent("click", { bubbles: true }));
+  });
+}
+
+describe("ThemeProvider", () => {
+  it("follows the OS preference live until an explicit choice, then stops listening", () => {
+    const { listeners } = stubMatchMedia(false);
+    render();
+
+    // The init effect resolves from the OS preference and subscribes.
+    expect(resolvedThemeText()).toBe("light");
+    expect(listeners.size).toBe(1);
+
+    // OS flips to dark while the user hasn't chosen -> followed live.
+    act(() => {
+      listeners.forEach((cb) => cb({ matches: true } as MediaQueryListEvent));
+    });
+    expect(resolvedThemeText()).toBe("dark");
+    expect(document.documentElement.getAttribute("data-theme")).toBe("dark");
+
+    // Explicit choice -> persisted, applied, and the listener removed.
+    click("set-dark");
+    expect(window.localStorage.getItem(THEME_STORAGE_KEY)).toBe("dark");
+    expect(listeners.size).toBe(0);
+    expect(resolvedThemeText()).toBe("dark");
+
+    // OS flips again -> ignored now that the user has chosen.
+    act(() => {
+      listeners.forEach((cb) => cb({ matches: false } as MediaQueryListEvent));
+    });
+    expect(resolvedThemeText()).toBe("dark");
+  });
+
+  it("lets a stored choice win and never listens to the OS", () => {
+    const { listeners } = stubMatchMedia(true);
+    window.localStorage.setItem(THEME_STORAGE_KEY, "light");
+    render();
+
+    expect(resolvedThemeText()).toBe("light");
+    expect(document.documentElement.getAttribute("data-theme")).toBe("light");
+    expect(listeners.size).toBe(0);
+  });
+
+  it("persists and applies toggle flips", () => {
+    stubMatchMedia(false);
+    render();
+
+    click("toggle"); // light -> dark
+    expect(window.localStorage.getItem(THEME_STORAGE_KEY)).toBe("dark");
+    expect(resolvedThemeText()).toBe("dark");
+    expect(document.documentElement.getAttribute("data-theme")).toBe("dark");
+
+    click("toggle"); // dark -> light
+    expect(window.localStorage.getItem(THEME_STORAGE_KEY)).toBe("light");
+    expect(resolvedThemeText()).toBe("light");
+    expect(document.documentElement.getAttribute("data-theme")).toBe("light");
+  });
+});
diff --git a/src/lib/theme.ts b/src/lib/theme.ts
new file mode 100644
index 0000000..3f8db38
--- /dev/null
+++ b/src/lib/theme.ts
@@ -0,0 +1,114 @@
+/**
+ * Theme system — codifies the GuildWorkman identity (trust navy / guild gold /
+ * terracotta) into a single source of truth for light & dark mode.
+ *
+ * The colour *tokens* live in `src/app/globals.css` (Tailwind v4 `@theme
+ * inline` + `data-theme` overrides). This module owns everything else:
+ *
+ *   - the persisted per-user choice (localStorage, key `theme`)
+ *   - resolving the effective theme (stored choice, else OS preference)
+ *   - applying a theme to <html data-theme> + `color-scheme`
+ *   - live OS-preference listening (until the user makes an explicit choice)
+ *   - the inline paint-time script used by the root layout (no flash)
+ *
+ * Everything here is pure / DOM-safe so it can be unit-tested in jsdom.
+ */
+
+export type Theme = "light" | "dark";
+
+/** localStorage key used to persist the per-user theme choice. */
+export const THEME_STORAGE_KEY = "theme";
+
+const SYSTEM_DARK_QUERY = "(prefers-color-scheme: dark)";
+
+/** Type guard for untrusted values (localStorage, inline script input). */
+export function isTheme(value: unknown): value is Theme {
+  return value === "light" || value === "dark";
+}
+
+/** Read the persisted per-user choice; `null` when unset, corrupted, or in a
+    non-browser environment (SSR — no `window`/localStorage). Never throws:
+    localStorage access is guarded by a `typeof window` check and a try/catch
+    (private mode, storage disabled). */
+export function getStoredTheme(): Theme | null {
+  if (typeof window === "undefined") return null;
+  try {
+    const raw = window.localStorage.getItem(THEME_STORAGE_KEY);
+    return isTheme(raw) ? raw : null;
+  } catch {
+    // localStorage can throw (private mode, storage disabled) — fall back.
+    return null;
+  }
+}
+
+/** Persist the per-user theme choice. Never throws. */
+export function setStoredTheme(theme: Theme): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(THEME_STORAGE_KEY, theme);
+  } catch {
+    // Non-fatal: the theme still applies for this session.
+  }
+}
+
+/** The OS preference; falls back to light when matchMedia is unavailable. */
+export function getSystemTheme(): Theme {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return "light";
+  }
+  return window.matchMedia(SYSTEM_DARK_QUERY).matches ? "dark" : "light";
+}
+
+/** Stamp a theme on <html data-theme> and set color-scheme so native
+    controls (scrollbars, selects, date pickers) match. */
+export function applyTheme(theme: Theme): void {
+  const root = document.documentElement;
+  root.setAttribute("data-theme", theme);
+  root.style.colorScheme = theme;
+}
+
+/** Subscribe to OS preference changes. Returns an unsubscribe function.
+    Safe to call in environments without matchMedia (returns a no-op).
+    Prefers the modern `addEventListener` API and falls back to the legacy
+    `addListener`/`removeListener` pair for older browsers (e.g. Safari < 14). */
+export function listenForSystemTheme(onChange: (theme: Theme) => void): () => void {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") {
+    return () => {};
+  }
+  const mql = window.matchMedia(SYSTEM_DARK_QUERY);
+  const handler = (event: MediaQueryListEvent): void => {
+    onChange(event.matches ? "dark" : "light");
+  };
+  // Modern engines expose addEventListener; older ones only addListener.
+  if (typeof mql.addEventListener === "function") {
+    mql.addEventListener("change", handler);
+    return () => mql.removeEventListener("change", handler);
+  }
+  mql.addListener(handler);
+  return () => mql.removeListener(handler);
+}
+
+/** Resolve the effective theme from a stored choice and the OS preference:
+    the stored choice wins, otherwise the OS preference. */
+export function resolveTheme(
+  stored: Theme | null,
+  system: Theme
+): Theme {
+  return stored ?? system;
+}
+
+/**
+ * Inline script injected in <head> by the root layout. Runs before first
+ * paint so the correct theme is applied with no flash: honour a stored
+ * preference, otherwise fall back to the OS setting (the CSS `@media
+ * (prefers-color-scheme: dark)` rule handles the no-script case).
+ * Kept here — next to the rest of the theme system — as the single source
+ * of truth shared with the ThemeProvider.
+ *
+ * Safety: the string is exported as an immutable `const` and rendered via
+ * React's sanctioned `<script dangerouslySetInnerHTML>` API in the layout.
+ * The only interpolations are the compile-time constants `THEME_STORAGE_KEY`
+ * and `SYSTEM_DARK_QUERY` — never user input — and the body is a single
+ * minified line, so there is no XSS surface to introduce at render time.
+ */
+export const themeScript = `(function(){try{var t=localStorage.getItem('${THEME_STORAGE_KEY}');var r=document.documentElement;if(t==='light'||t==='dark'){r.setAttribute('data-theme',t);r.style.colorScheme=t;}else{r.style.colorScheme=window.matchMedia('${SYSTEM_DARK_QUERY}').matches?'dark':'light';}}catch(e){}})();`;
diff --git a/vitest.config.ts b/vitest.config.ts
index 50a6d0c..7b73c2b 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -1,9 +1,16 @@
+import { fileURLToPath } from "node:url";
 import { defineConfig } from "vitest/config";
- 
+
 export default defineConfig({
+  resolve: {
+    alias: {
+      "@": fileURLToPath(new URL("./src", import.meta.url)),
+    },
+  },
   test: {
     environment: "jsdom",
-    include: ["src/**/*.test.ts"],
+    include: ["src/**/*.test.{ts,tsx}"],
+    setupFiles: ["src/lib/test/setup.ts"],
     globals: false,
   },
-});
\ No newline at end of file
+});
