diff --git a/AGENTS.md b/AGENTS.md
index 162b1d8..303480d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,8 +10,21 @@ in `out/` is served by any static host (GitHub Pages, GitLab Pages, Bitbucket).
 
 **Key Features:**
 - Search over curated repository listing (`repositories.txt`)
-- Breadcrumb trail under the menu (`components/breadcrumbs.jsx` +
-  `lib/breadcrumbs.js`): mirrors `/user/repo/branch` with linked ancestors;
+- Dark mode, 100% CSS switching (`components/theme-toggle.jsx` +
+  `plans/css-only-dark-mode.md`): three radios (light/dark/system) on the
+  right side of the `.theme-bar` row below the header, rendered by
+  `app/layout.jsx` — the breadcrumb trail shares the row on report routes
+  (crumbs left, toggle right, vertically centered; the right-edge mirror
+  of the breadcrumbs' left-edge alignment) — palettes selected in
+  `app/globals.css` via `:root:has(#rf-theme-…:checked)` +
+  `prefers-color-scheme`; an inline pre-paint script in `app/layout.jsx`
+  only restores/persists the choice (CSP-hashed by the build). Guards:
+  `tests/unit/theme-css.test.js` (the two dark blocks must stay
+  byte-identical; all hex colors live in the palette blocks; dark palette
+  passes the same WCAG AA math as `tests/unit/css-a11y.test.js`)
+- Breadcrumb trail on the theme bar row under the menu
+  (`components/breadcrumbs.jsx` + `lib/breadcrumbs.js`): mirrors
+  `/user/repo/branch` with linked ancestors;
   the repo crumb never self-links, and ReportView announces the resolved
   branch (`rf:branch-resolved` event) so the label matches the loaded report
   (`main` 404 → `master` fallback)
@@ -130,6 +143,14 @@ coverage there when introducing new markup patterns.
 - **Environment config:** meta tags in `app/layout.jsx` (`submission-target`,
   `sentry-dsn`, `platform-base-url`) plus `NEXT_PUBLIC_HOSTING_ENVIRONMENT`
   / `NEXT_PUBLIC_BASE_PATH` at build time.
+- **Theming:** see the dark-mode bullet above — the radios in
+  `components/theme-toggle.jsx` are the single source of truth; never add
+  JS-driven styling. All colors must be custom properties declared only in
+  the four palette blocks (`:root`, `html:root` mvp overrides, and the two
+  identical dark blocks) in `app/globals.css`; mvp.css light overrides must
+  stay on `html:root` (mvp loads after the bundle). Report-template
+  widgets that hardcode light colors are re-driven from `main#app …`
+  rules there (the mustache stays byte-identical).
 
 ## Report Tables (Enhanced)
 
@@ -178,7 +199,7 @@ coverage there when introducing new markup patterns.
 
 ## Current Test Count
 
-~543 unit/integration + ~202 E2E (~198 across three browsers + 4 basePath leg).
+~584 unit/integration + ~229 E2E (~202 across three browsers + 4 basePath leg + 27 dark mode).
 
 WCAG 2.2 AA / HTML5 guards live in tests/unit/html5-attributes.test.js,
 tests/unit/report-template-wcag.test.js, tests/unit/css-a11y.test.js and
diff --git a/app/globals.css b/app/globals.css
index 1d84ad2..69edd5f 100644
--- a/app/globals.css
+++ b/app/globals.css
@@ -1,17 +1,43 @@
 /* Main stylesheet: CSS custom properties, base layout, footer. */
 
+/* ---- Color palettes (dark mode: plans/css-only-dark-mode.md) ---- */
+/* The theme is selected purely in CSS: the three radios in
+ * components/theme-toggle.jsx are the single source of truth.
+ *  - explicit "dark" radio  -> :root:has(#rf-theme-dark:checked) below;
+ *  - "system" radio + dark OS -> the prefers-color-scheme block below;
+ *  - anything else           -> this light :root palette.
+ * :has() blocks (1,2,0) beat mvp.css's later :root (0,1,0); the light mvp
+ * overrides therefore need html:root (0,1,1) to survive the load order. */
+
 :root {
+  color-scheme: light;
   --brand-color: #2a6f97;
   /* Darker accent: white text on it passes WCAG 2.2 AA contrast (1.4.3) and
      it serves as the visible focus indicator (2.4.11, >= 3:1 against the
      white page background). */
   --brand-accent: #1f5273;
+  /* --brand-color is an accent *background* (white text sits on it, in both
+     palettes). Accent *text* (links, wordmark) needs its own role: #2a6f97
+     as text fails AA on the dark page background. */
+  --link-color: #2a6f97;
+  --on-accent-color: #ffffff;
   --text-color: #1f2d3d;
   --muted-color: #5c6b7a;
   --bg-color: #ffffff;
   --surface-color: #f5f8fa;
+  --card-bg: #ffffff;
+  --border-color: #dde4ea;
+  --input-border: #c6d2dc;
   --error-color: #c0392b;
   --success-color: #1e8449;
+  --error-bg: #fdf6f5;
+  --error-border: #f0c6c0;
+  --btn-hover-bg: #e8f0f6;
+  --btn-disabled-bg: #f3f4f6;
+  --btn-disabled-text: #6b7280;
+  --popup-border: #cccccc;
+  --toast-bg: #1f2933;
+  --toast-text: #ffffff;
   --menu-max-height: 140px;
   --menu-height: 48px;
   --radius: 6px;
@@ -22,6 +48,106 @@
   --width-content: min(3840px, 95vw);
 }
 
+/* mvp.css re-declares its variables on :root AFTER this bundle loads, so
+   same-specificity overrides lose the cascade. html:root (0,1,1) wins over
+   mvp's :root (0,1,0) and themes every mvp-styled element (inputs, quotes,
+   table headers, zebra rows, scrollbars) via mvp's own variable plumbing. */
+html:root {
+  --color-bg: var(--bg-color);
+  --color-text: var(--text-color);
+  --color-bg-secondary: var(--surface-color);
+  --color-text-secondary: var(--muted-color);
+  --color-link: var(--link-color);
+  --color-secondary: var(--brand-accent);
+  --color-secondary-accent: rgba(42, 111, 151, 0.08);
+  --color-accent: rgba(42, 111, 151, 0.08);
+  --color-shadow: rgba(0, 0, 0, 0.12);
+  --color-table: var(--brand-color);
+  --color-scrollbar: var(--input-border);
+}
+
+/* Dark palette. The two blocks below MUST stay identical: one applies the
+   explicit dark radio at any OS setting, the other applies the system radio
+   only when the OS prefers dark. tests/unit/theme-css.test.js guards the
+   duplication byte-for-byte. */
+:root:has(#rf-theme-dark:checked) {
+  color-scheme: dark;
+  --brand-color: #2a6f97;
+  /* Focus indicator / hover accent on the dark page: >= 3:1 against both
+     --bg-color (3.8:1) and --surface-color (3.3:1), and 4.8:1 against white,
+     so the light-mode guards keep passing under their last-occurrence
+     variable resolution (tests/unit/css-a11y.test.js). */
+  --brand-accent: #3178a6;
+  --link-color: #6fb1d9;
+  --on-accent-color: #ffffff;
+  --text-color: #e6edf3;
+  --muted-color: #9fb0c0;
+  --bg-color: #10161d;
+  --surface-color: #1a2330;
+  --card-bg: #1a2330;
+  --border-color: #2c3a4d;
+  --input-border: #5b7396;
+  --error-color: #f0928c;
+  --success-color: #5bbd8b;
+  --error-bg: #2b1d1f;
+  --error-border: #7a4a48;
+  --btn-hover-bg: #243244;
+  --btn-disabled-bg: #232a35;
+  --btn-disabled-text: #8a97a8;
+  --popup-border: #3a4b61;
+  --toast-bg: #1f2933;
+  --toast-text: #ffffff;
+  --color-bg: var(--bg-color);
+  --color-text: var(--text-color);
+  --color-bg-secondary: var(--surface-color);
+  --color-text-secondary: var(--muted-color);
+  --color-link: var(--link-color);
+  --color-secondary: var(--link-color);
+  --color-secondary-accent: rgba(111, 177, 217, 0.12);
+  --color-accent: rgba(111, 177, 217, 0.1);
+  --color-shadow: rgba(0, 0, 0, 0.33);
+  --color-table: var(--link-color);
+  --color-scrollbar: #566d8f;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:has(#rf-theme-system:checked) {
+    color-scheme: dark;
+    --brand-color: #2a6f97;
+    --brand-accent: #3178a6;
+    --link-color: #6fb1d9;
+    --on-accent-color: #ffffff;
+    --text-color: #e6edf3;
+    --muted-color: #9fb0c0;
+    --bg-color: #10161d;
+    --surface-color: #1a2330;
+    --card-bg: #1a2330;
+    --border-color: #2c3a4d;
+    --input-border: #5b7396;
+    --error-color: #f0928c;
+    --success-color: #5bbd8b;
+    --error-bg: #2b1d1f;
+    --error-border: #7a4a48;
+    --btn-hover-bg: #243244;
+    --btn-disabled-bg: #232a35;
+    --btn-disabled-text: #8a97a8;
+    --popup-border: #3a4b61;
+    --toast-bg: #1f2933;
+    --toast-text: #ffffff;
+    --color-bg: var(--bg-color);
+    --color-text: var(--text-color);
+    --color-bg-secondary: var(--surface-color);
+    --color-text-secondary: var(--muted-color);
+    --color-link: var(--link-color);
+    --color-secondary: var(--link-color);
+    --color-secondary-accent: rgba(111, 177, 217, 0.12);
+    --color-accent: rgba(111, 177, 217, 0.1);
+    --color-shadow: rgba(0, 0, 0, 0.33);
+    --color-table: var(--link-color);
+    --color-scrollbar: #566d8f;
+  }
+}
+
 body {
   margin: 0;
   color: var(--text-color);
@@ -33,7 +159,7 @@ body {
   left: -9999px;
   top: 0;
   background: var(--brand-color);
-  color: #fff;
+  color: var(--on-accent-color);
   padding: 0.5rem 1rem;
   z-index: 100;
 }
@@ -89,7 +215,7 @@ main section {
 }
 
 .hero h1 {
-  color: var(--brand-color);
+  color: var(--link-color);
   margin-bottom: 0.25rem;
 }
 
@@ -108,7 +234,7 @@ main section {
 }
 
 a {
-  color: var(--brand-color);
+  color: var(--link-color);
 }
 
 code {
@@ -133,7 +259,7 @@ pre {
 /* ---- Top navigation (max 140px, mobile hamburger) ---- */
 #top-menu {
   background: var(--surface-color);
-  border-bottom: 1px solid #dde4ea;
+  border-bottom: 1px solid var(--border-color);
   /* mvp.css adds generous header padding; reset it so max-height bounds the
      whole rendered box (padding contributes outside max-height). */
   padding: 0;
@@ -157,7 +283,7 @@ pre {
   align-items: center;
   gap: 0.4rem;
   font-weight: bold;
-  color: var(--brand-color);
+  color: var(--link-color);
   text-decoration: none;
   white-space: nowrap;
   font-size: 0.9rem;
@@ -176,14 +302,14 @@ pre {
 .menu-search input {
   width: 100%;
   padding: 0.35rem 0.6rem;
-  border: 1px solid #c6d2dc;
+  border: 1px solid var(--input-border);
   border-radius: var(--radius);
 }
 
 .menu-toggle {
   display: none;
   background: none;
-  border: 1px solid #c6d2dc;
+  border: 1px solid var(--input-border);
   border-radius: var(--radius);
   font-size: 1.1rem;
   padding: 0.25rem 0.6rem;
@@ -221,25 +347,25 @@ pre {
 .menu-links a:hover,
 .menu-links a:focus-visible {
   background: var(--brand-color);
-  color: #fff;
+  color: var(--on-accent-color);
 }
 
 /* ---- Breadcrumbs (user/report trail under the top menu) ---- */
 .breadcrumbs {
-  /* Same column as the top menu: #top-menu is capped by mvp.css at
-     --width-content, so reuse the variable — the two can never drift apart.
-     border-box (not mvp's default content-box) so the horizontal padding
-     insets crumbs exactly like .menu-bar's padding insets the brand; with
-     content-box, symmetric padding on a centered block never moves the
-     content edge. */
-  max-width: var(--width-content);
-  box-sizing: border-box;
+  /* Lives on the .theme-bar row (rendered by app/layout.jsx), sharing the
+     line with the color theme toggle: the row owns the menu-column
+     alignment formula (max-width: var(--width-content) + 0.8rem horizontal
+     padding, see .theme-bar above), so the trail must add no box-model
+     offsets of its own — flex-grow fills the row's left side, keeping the
+     first crumb's glyph at the menu bar's left content edge while the
+     toggle pins to the right edge, both vertically centered. */
+  flex: 1 1 auto;
+  min-width: 0;
   /* mvp.css gives bare nav a 7rem bottom margin, bold text and a spaced flex
-     row — reset all three so the trail hugs the menu like a sub-bar. */
-  margin: 0 auto;
+     row — reset all three so the trail sits inline like a sub-bar. */
+  margin: 0;
   font-weight: normal;
   display: block;
-  padding: 0 0.8rem;
   font-size: 0.85rem;
 }
 
@@ -283,8 +409,8 @@ pre {
   margin: 0.15rem 0 0;
   padding: 0;
   list-style: none;
-  background: #fff;
-  border: 1px solid #c6d2dc;
+  background: var(--card-bg);
+  border: 1px solid var(--input-border);
   border-radius: var(--radius);
   box-shadow: var(--shadow);
   max-height: 16rem;
@@ -299,7 +425,7 @@ pre {
 .search-results li.active,
 .search-results li:hover {
   background: var(--brand-color);
-  color: #fff;
+  color: var(--on-accent-color);
 }
 
 .hero-search {
@@ -316,7 +442,7 @@ pre {
   width: 100%;
   box-sizing: border-box;
   padding: 0.35rem 0.6rem;
-  border: 1px solid #c6d2dc;
+  border: 1px solid var(--input-border);
   border-radius: var(--radius);
 }
 
@@ -336,18 +462,18 @@ pre {
 .repo-card {
   display: block;
   padding: 0.85rem 1rem;
-  border: 1px solid #dde4ea;
+  border: 1px solid var(--border-color);
   border-radius: var(--radius);
   text-decoration: none;
   color: var(--text-color);
-  background: #fff;
+  background: var(--card-bg);
   box-shadow: var(--shadow);
 }
 
 .repo-card:hover,
 .repo-card:focus-visible {
   border-color: var(--brand-color);
-  color: var(--brand-color);
+  color: var(--link-color);
 }
 
 /* ---- Pagination ---- */
@@ -360,7 +486,7 @@ pre {
 
 .pagination .page {
   padding: 0.35rem 0.65rem;
-  border: 1px solid #c6d2dc;
+  border: 1px solid var(--input-border);
   border-radius: var(--radius);
   text-decoration: none;
 }
@@ -368,7 +494,7 @@ pre {
 .pagination .page.current {
   background: var(--brand-color);
   border-color: var(--brand-color);
-  color: #fff;
+  color: var(--on-accent-color);
 }
 
 /* ---- User listing (/user) ---- */
@@ -412,7 +538,7 @@ pre {
 .cta {
   display: inline-block;
   background: var(--brand-color);
-  color: #fff;
+  color: var(--on-accent-color);
   padding: 0.6rem 1.2rem;
   border-radius: var(--radius);
   border: none;
@@ -423,7 +549,7 @@ pre {
 
 .cta:hover {
   background: var(--brand-accent);
-  color: #fff;
+  color: var(--on-accent-color);
 }
 
 /* ---- Error pages ---- */
@@ -432,9 +558,9 @@ pre {
   margin: 3rem auto;
   text-align: center;
   padding: 2rem;
-  border: 1px solid #f0c6c0;
+  border: 1px solid var(--error-border);
   border-radius: var(--radius);
-  background: #fdf6f5;
+  background: var(--error-bg);
 }
 
 .error-page h1 {
@@ -455,7 +581,7 @@ pre {
 
 .error-actions .retry {
   background: var(--brand-color);
-  color: #fff;
+  color: var(--on-accent-color);
   border: none;
   border-radius: var(--radius);
   padding: 0.5rem 1rem;
@@ -533,8 +659,8 @@ pre {
   gap: 0.75rem;
   padding: 0.6rem 0.9rem;
   border-radius: var(--radius);
-  background: #1f2933;
-  color: #fff;
+  background: var(--toast-bg);
+  color: var(--toast-text);
   box-shadow: var(--shadow);
   pointer-events: auto;
 }
@@ -546,7 +672,7 @@ pre {
 .rf-toast-dismiss {
   background: none;
   border: none;
-  color: #fff;
+  color: var(--toast-text);
   font-size: 1.1rem;
   line-height: 1;
   cursor: pointer;
@@ -557,3 +683,121 @@ pre {
   outline: 2px solid var(--brand-color);
   outline-offset: 2px;
 }
+
+/* ---- Color theme toggle (three radio modes, pure-CSS switching) ---- */
+/* Row below the site header (rendered by app/layout.jsx): the breadcrumb
+   trail (when the route has one) on the left and the toggle on the right,
+   vertically centered on one line. The alignment formula .breadcrumbs used
+   to carry lives here now: --width-content column, 0.8rem horizontal
+   padding, border-box — keeping the first crumb's glyph at the menu bar's
+   left content edge and the toggle at its right content edge at every
+   viewport, the two edges mirroring each other. #top-menu is capped by
+   mvp.css at --width-content, so the row and the menu bar can never drift
+   apart. Crumb routes grow the trail (flex: 1 1 auto); crumb-less routes
+   leave only the toggle, pinned right by flex-end. */
+.theme-bar {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  max-width: var(--width-content);
+  box-sizing: border-box;
+  margin: 0 auto;
+  padding: 0.4rem 0.8rem 0.45rem;
+}
+
+/* The radios in components/theme-toggle.jsx are the theme's single source of
+   truth (see the palette blocks at the top of this file). Each input is
+   visually replaced by its icon pill (appearance: none, absolute, fills the
+   28px label) but stays keyboard-focusable — the global :focus-visible rule
+   draws the indicator — and the checked pill doubles as the selected state,
+   so no JS is involved in switching. The control renders as a surface chip
+   so it stands out from the page background. */
+.theme-toggle {
+  display: flex;
+  align-items: center;
+  gap: 0.15rem;
+  flex: 0 0 auto;
+  padding: 0.15rem;
+  border: 1px solid var(--input-border);
+  border-radius: var(--radius);
+  background: var(--surface-color);
+}
+
+.theme-option {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1.75rem; /* 28px >= 24px minimum target size (SC 2.5.8) */
+  height: 1.75rem;
+  border-radius: 5px;
+}
+
+.theme-option:hover {
+  background: var(--btn-hover-bg);
+}
+
+.theme-option-input {
+  appearance: none;
+  position: absolute;
+  inset: 0;
+  margin: 0;
+  border-radius: 5px;
+  cursor: pointer;
+}
+
+.theme-option-input:checked {
+  background: var(--brand-color);
+}
+
+.theme-option-icon {
+  /* Relative so the glyph paints above the checked input's pill. */
+  position: relative;
+  width: 1.15rem;
+  height: 1.15rem;
+  color: var(--text-color);
+  pointer-events: none;
+}
+
+.theme-option-input:checked + .theme-option-icon {
+  color: var(--on-accent-color);
+}
+
+/* ---- Report template theme overrides ---- */
+/* The bundled mustache template (public/assets/refactor-first-report.mustache)
+   hardcodes light values for a few report widgets; it stays byte-identical,
+   so these main#app rules (1,1,1) beat its injected <style> (0,1,0). They are
+   palette-driven with light values equal to the template's current colors,
+   so the same rule serves both palettes with no duplication. */
+main#app .popup {
+  background-color: var(--card-bg);
+  border-color: var(--popup-border);
+}
+
+main#app .rf-page-btn {
+  background: var(--card-bg);
+  border: 1px solid var(--brand-color);
+  color: var(--text-color);
+}
+
+main#app .rf-page-btn:hover:not([disabled]) {
+  background: var(--btn-hover-bg);
+}
+
+main#app .rf-page-btn[disabled] {
+  background: var(--btn-disabled-bg);
+  border-color: var(--input-border);
+  color: var(--btn-disabled-text);
+}
+
+main#app .rf-export-btn:focus-visible,
+main#app .rf-page-btn:focus-visible {
+  outline-color: var(--brand-accent);
+}
+
+main#app .rf-data-table td[data-rf-copy]:focus-visible {
+  /* --brand-accent (the focus-indicator role), not --brand-color (the
+     accent-background role): #2a6f97 is only 2.9:1 against the dark
+     --surface-color, below the 3:1 of SC 2.4.11. */
+  outline-color: var(--brand-accent);
+}
diff --git a/app/layout.jsx b/app/layout.jsx
index 604e404..e1f2f6a 100644
--- a/app/layout.jsx
+++ b/app/layout.jsx
@@ -3,6 +3,7 @@ import SiteHeader from '../components/site-header';
 import SiteFooter from '../components/site-footer';
 import Breadcrumbs from '../components/breadcrumbs';
 import SentryProvider from '../components/sentry-provider';
+import ThemeToggle from '../components/theme-toggle';
 import { loadListedRepositories } from '../lib/repositories.js';
 import './globals.css';
 
@@ -37,6 +38,10 @@ export default function RootLayout({ children }) {
         <meta name="referrer" content="strict-origin-when-cross-origin" />
         <meta name="submission-target" content="refactorfirst/refactorfirst.github.io" />
         <meta name="sentry-dsn" content="" />
+        {/* Both palettes are supported; declaring it pre-stylesheet keeps
+            native UI (scrollbars, form controls, the pre-CSS canvas) from
+            flashing light for dark-mode users. */}
+        <meta name="color-scheme" content="light dark" />
         <link
           rel="stylesheet"
           href="https://cdn.jsdelivr.net/npm/mvp.css@1.15.0/mvp.css"
@@ -44,12 +49,38 @@ export default function RootLayout({ children }) {
       </head>
       <body>
         <SiteHeader repositories={repositories} />
-        {/* Breadcrumb trail under the menu (report/user routes only). Suspense
-            is required because useSearchParams deopts otherwise (static
-            export; the fallback keeps prerendered HTML crumb-free). */}
-        <Suspense fallback={null}>
-          <Breadcrumbs />
-        </Suspense>
+        {/* Theme bar row below the header: the breadcrumb trail (report/user
+            routes only) on the left and the color theme toggle on the right,
+            vertically centered on one line. The row reuses the breadcrumbs'
+            alignment formula (--width-content column, 0.8rem horizontal
+            padding, border-box), so the first crumb's glyph sits at the menu
+            bar's left content edge and the toggle at its right content edge
+            — the two edges mirror each other (plans/css-only-dark-mode.md).
+            Suspense is required for useSearchParams (static export; the
+            fallback keeps prerendered HTML crumb-free and the toggle still
+            renders — an empty flex slot). */}
+        <div className="theme-bar">
+          <Suspense fallback={null}>
+            <Breadcrumbs />
+          </Suspense>
+          <ThemeToggle />
+        </div>
+        {/* Theme persistence shim (plans/css-only-dark-mode.md): switching
+            itself is pure CSS (radio + :has() in globals.css); this inline
+            script only restores the saved choice into the radios before
+            first paint and records changes. It must stay AFTER the
+            .theme-bar markup (the radios have to be parsed before it can
+            check them) and before any meaningful page content. It sets the
+            checked *property* (never the attribute), so React hydration
+            never sees a mismatch. scripts/fix-csp-hashes.mjs hashes it into
+            the CSP at build time; with JS disabled the toggle still works
+            per page view. */}
+        <script
+          dangerouslySetInnerHTML={{
+            __html:
+              "(function(){var r;try{r=localStorage.getItem('rf-theme')}catch(e){}if(r==='light'||r==='dark'){var i=document.getElementById('rf-theme-'+r);if(i)i.checked=true}document.addEventListener('change',function(e){var t=e.target;if(t&&t.name==='rf-theme'){try{localStorage.setItem('rf-theme',t.value)}catch(_){}}})})();"
+          }}
+        />
         <main id="app" tabIndex={-1}>{children}</main>
         <SiteFooter />
         <SentryProvider />
diff --git a/components/site-header.jsx b/components/site-header.jsx
index 7d7af01..f8b8ddd 100644
--- a/components/site-header.jsx
+++ b/components/site-header.jsx
@@ -4,7 +4,8 @@ import MenuSearch from './menu-search';
 import { withBasePath } from '../lib/base-path';
 
 // Site header: brand logo, hamburger toggle, main navigation links and the
-// type-ahead menu search pinned to the right side of the bar.
+// type-ahead menu search. The color theme toggle lives below the header in
+// app/layout.jsx (.theme-bar row).
 export default function SiteHeader({ repositories = [] }) {
   return (
     <>
diff --git a/components/theme-toggle.jsx b/components/theme-toggle.jsx
new file mode 100644
index 0000000..28b0527
--- /dev/null
+++ b/components/theme-toggle.jsx
@@ -0,0 +1,73 @@
+// Dark mode toggle for the top menu bar: three radio modes (light, dark,
+// system) rendered as icon pills. Deliberately a Server Component with no
+// state and no handlers — the radios ARE the state, and app/globals.css
+// selects the palette via :has(#rf-theme-…:checked) plus
+// prefers-color-scheme, so switching themes is pure CSS. A tiny inline
+// bootstrap script in app/layout.jsx (progressive enhancement) restores and
+// persists the checked radio across hard page loads.
+const MODES = [
+  {
+    value: 'light',
+    label: 'Light theme',
+    icon: (
+      <>
+        <circle cx="12" cy="12" r="4" />
+        <path d="M12 2v2m0 16v2M4.9 4.9l1.4 1.4m11.4 11.4 1.4 1.4M2 12h2m16 0h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4" />
+      </>
+    )
+  },
+  {
+    value: 'dark',
+    label: 'Dark theme',
+    icon: <path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z" />
+  },
+  {
+    value: 'system',
+    label: 'System preference',
+    icon: (
+      <>
+        <rect x="2" y="3" width="20" height="14" rx="2" />
+        <path d="M8 21h8m-4-4v4" />
+      </>
+    )
+  }
+];
+
+/**
+ * Renders the three-mode color theme radio group pinned to the menu bar's
+ * right edge (last flex child of .menu-bar, mirroring the breadcrumbs'
+ * left-edge alignment with the menu).
+ *
+ * @returns {import('react').ReactElement} The theme toggle radiogroup.
+ */
+export default function ThemeToggle() {
+  return (
+    <div className="theme-toggle" role="radiogroup" aria-label="Color theme">
+      {MODES.map(mode => (
+        <label key={mode.value} className="theme-option">
+          <input
+            type="radio"
+            name="rf-theme"
+            id={`rf-theme-${mode.value}`}
+            value={mode.value}
+            aria-label={mode.label}
+            className="theme-option-input"
+            defaultChecked={mode.value === 'system'}
+          />
+          <svg
+            className="theme-option-icon"
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="2"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            aria-hidden="true"
+          >
+            {mode.icon}
+          </svg>
+        </label>
+      ))}
+    </div>
+  );
+}
diff --git a/plans/css-only-dark-mode.md b/plans/css-only-dark-mode.md
new file mode 100644
index 0000000..cabb83a
--- /dev/null
+++ b/plans/css-only-dark-mode.md
@@ -0,0 +1,272 @@
+# CSS-Only Dark Mode — Implementation Plan
+
+## Goals
+
+1. Three-mode theme control — **light / dark / system** — with small images
+   (icons) for each mode, on a row below the site header.
+2. The control's right edge aligns with the menu bar's right content edge at
+   every viewport (mirroring how the breadcrumb trail aligns with the menu's
+   left edge).
+3. All *theming* is pure CSS: custom properties + `prefers-color-scheme` +
+   `:has()`. No JS adds classes, styles, or colors.
+4. WCAG 2.2 AA in **both** palettes, enforced by the existing guard suite.
+
+## Architecture
+
+### Single source of truth: three radio inputs
+
+`components/theme-toggle.jsx` (a Server Component — no state, no handlers)
+renders three radios named `rf-theme` (`rf-theme-light`, `rf-theme-dark`,
+`rf-theme-system`, with `system` `defaultChecked`), each wrapped in a labelled
+icon pill (inline SVG: sun / moon / monitor). The toggle sits on the
+**`.theme-bar` row below `#top-menu`**, rendered by `app/layout.jsx` right
+after `<SiteHeader />` (and before the persistence shim, which needs the
+radios parsed); on report routes the breadcrumb trail shares the row, to the
+toggle's left, both vertically centered, the toggle pinned to the menu bar's
+right content edge.
+
+Why radios: "one of three modes" is exactly a radio group, the checked state
+is queryable from CSS (`:has(#id:checked)`), and switching requires zero JS.
+Buttons + `aria-pressed` would need a script to do anything.
+
+### Cascade design (app/globals.css)
+
+```css
+:root        { color-scheme: light;  /* light palette */ }
+html:root    { /* mvp.css --color-* overrides, light */ }
+:root:has(#rf-theme-dark:checked)      { color-scheme: dark; /* dark palette */ }
+@media (prefers-color-scheme: dark) {
+  :root:has(#rf-theme-system:checked)  { color-scheme: dark; /* same dark palette */ }
+}
+```
+
+- **system + OS dark** → the media block applies (specificity (1,2,0) beats the
+  base `:root` (0,1,0) regardless of load order — required because mvp.css is
+  linked after the bundle).
+- **explicit dark** → the `:has()` block applies at any OS setting.
+- **explicit light** → neither dark block matches (the system radio is
+  unchecked), so the base light palette wins even when the OS is dark.
+- **OS theme flips while "system" is selected** → CSS re-evaluates live; no JS
+  listener is ever needed. This is the key payoff of the radio + `:has()`
+  design.
+
+The dark declaration block is necessarily duplicated (one copy inside the
+media query, one without — plain CSS has no mixins). A unit test compares the
+two blocks byte-for-byte to prevent drift.
+
+### mvp.css integration
+
+mvp.css 1.15 is fully variable-driven (`--color-bg/-text/-bg-secondary/
+-text-secondary/-link/-accent/-secondary-accent/-shadow/-table/-scrollbar`),
+and its own dark support requires `:root[color-mode="user"]`, which we never
+set. Both palettes therefore *redeclare mvp's variables*:
+
+- Light redeclarations must survive mvp.css loading after the bundle, so they
+  live on `html:root` (specificity (0,1,1) > mvp's `:root` (0,1,0)).
+- Dark redeclarations live inside the (1,2,0) `:has()` blocks, which beat
+  everything.
+
+Inputs, blockquotes, `mark`, table headers, scrollbars etc. then follow the
+theme with no per-element rules.
+
+### Color roles (the one real refactor)
+
+Today `--brand-color` serves two incompatible roles. Dark mode forces the
+split because #2a6f97 as *text* on a dark page fails AA (3.3:1), while as a
+*background* for white text it passes in both modes (5.5:1):
+
+| Variable | Role | Light | Dark | Dark-mode check |
+|---|---|---|---|---|
+| `--brand-color` | accent **backgrounds** (CTA, hover fills) | #2a6f97 | #2a6f97 | white text 5.5:1 |
+| `--link-color` (new) | accent **text** (links, wordmark, hero h1) | #2a6f97 | #6fb1d9 | 7.7:1 on dark bg |
+| `--brand-accent` | hover bg + focus indicator | #1f5273 | #3178a6 | 3.8:1 on dark bg, 3.3:1 vs surface, 4.8:1 vs white |
+| `--bg-color` / `--surface-color` | page / panels | #ffffff / #f5f8fa | #10161d / #1a2330 | — |
+| `--text-color` / `--muted-color` | text | #1f2d3d / #5c6b7a | #e6edf3 / #9fb0c0 | 13:1 / 8:1 |
+| `--border-color`, `--input-border`, `--card-bg` | chrome (was #dde4ea / #c6d2dc / #fff hardcoded) | as today | #2c3a4d / #5b7396 / #1a2330 | input border ≥3:1 vs surface |
+| `--error-color` / `--success-color` | status text | #c0392b / #1e8449 | #f0928c / #5bbd8b | ~8:1 on dark bg |
+| `--error-bg` / `--error-border` | error page panel | #fdf6f5 / #f0c6c0 | #2b1d1f / #7a4a48 | — |
+
+All remaining hardcoded colors in globals.css (#dde4ea, #c6d2dc, #fff
+surfaces, error-page pastels) are swept into these variables. The toast is
+already dark-on-light and works unchanged in both modes.
+
+### Report template (mustache) — untouched
+
+`public/assets/refactor-first-report.mustache` stays **byte-identical**
+(`tests/unit/report-template.test.js` asserts the served copy matches the
+source, and the WCAG template guard asserts its literal hex colors). Its
+light-only rules (popup `#fff` background, `.rf-page-btn` white buttons,
+`.rf-page-btn:focus-visible` outline #1f5273) are restyled from globals.css
+with `main#app`-prefixed selectors — specificity (1,1,1) beats the template's
+injected `<style>` (0,1,0) regardless of load order — driven by theme
+variables whose **light values equal the template's current hexes**, so a
+single rule serves both modes with no duplication. Its brand-colored bits
+(`thead` #2a6f97 + white text, table borders via `currentColor`) already work
+on dark. Both copies (`assets/` + `public/assets/`) remain in sync trivially
+since neither changes.
+
+### Persistence — the one, flagged deviation
+
+CSS cannot read `localStorage`; a strictly-CSS site loses an explicit choice
+on every hard load (Next's client-side navigation preserves it — the layout
+never remounts — but refresh/new tab resets). "Follow dark mode best
+practices" and "only CSS" conflict here, so the plan resolves it as:
+
+- **Switching, system-following and all colors: 100% CSS.** With JS disabled
+  the toggle still works per page view and the OS preference still themes the
+  site.
+- **An ~8-line inline script** right after the header in `app/layout.jsx`
+  restores `localStorage['rf-theme']` into the radios (parser-blocking, i.e.
+  before first paint in practice) and saves the value on a delegated
+  `change` listener. It sets the radio `checked` *property* (never the
+  attribute), so React hydration is unaffected.
+- `scripts/fix-csp-hashes.mjs` already hashes every inline script in the
+  export, so the strict CSP keeps working with zero pipeline changes.
+
+### Alignment with the menu
+
+The toggle lives on a `.theme-bar` row rendered by `app/layout.jsx` right
+after `<SiteHeader />`, below the header block. The row owns the alignment
+formula the standalone breadcrumb bar used to carry — `max-width:
+var(--width-content)`, `box-sizing: border-box`, `margin: 0 auto`,
+`padding: 0.4rem 0.8rem 0.45rem` — with `align-items: center` so the
+breadcrumb trail (report/user routes; `flex: 1 1 auto`, no box-model offsets
+of its own) sits on the line's left at the menu bar's left content edge,
+vertically centered against the toggle pinned to the right content edge
+(`justify-content: flex-end` keeps the toggle right on crumb-less pages).
+No positioning tricks or magic numbers; the formula works identically at
+mobile widths, where the row simply follows the wrapped menu bar.
+
+### Toggle UI / a11y
+
+- Container: `<div role="radiogroup" aria-label="Color theme">` — three
+  labelled, native radios (`aria-label` "Light theme" / "Dark theme" /
+  "System preference"), each visually replaced by its icon pill via
+  `appearance: none; position: absolute; inset: 0` (still keyboard-focusable;
+  the checked input itself renders the brand pill).
+- Each pill: 28×28px label (≥ 24px, SC 2.5.8), inline `stroke="currentColor"`
+  SVG icon (`aria-hidden="true"` — the radio label carries the name).
+- Selected state: `:checked` background on the input plus
+  `:checked + svg` icon recolor. Focus: the global `:focus-visible` rule
+  outlines the input (SC 2.4.7/2.4.11).
+- `color-scheme` per palette + `<meta name="color-scheme" content="light dark">`
+  for native controls, scrollbars and the pre-CSS canvas.
+- No color-transition animation (instant switch; nothing for
+  `prefers-reduced-motion` to suppress).
+
+### Known limitation (documented, out of scope)
+
+Chart.js / WASM canvases draw their own palettes into canvas bitmaps; CSS
+cannot restyle them. Charts keep their existing colors (future work: read
+CSS variables in `lib/report-view.js` at render time).
+
+## Tests (TDD — written first, must fail before implementation)
+
+1. `tests/integration/theme-toggle.test.jsx` — renders three `rf-theme`
+   radios with system checked by default, labelled inputs, decorative icons,
+   `radiogroup` with accessible name; header renders the toggle after the
+   search box (alignment precondition).
+2. `tests/unit/theme-css.test.js` — structural guards on globals.css:
+   base light `:root` (+ `color-scheme: light`), dark `:has()` block
+   (+ `color-scheme: dark`), media-wrapped system block, the two dark blocks
+   **byte-identical**, `html:root` mvp overrides, no hardcoded light hex left
+   in component rules; dark palette contrast pairs computed the same way
+   `css-a11y.test.js` does (bg/text, muted, link, focus ≥3:1, brand bg vs
+   white ≥4.5:1).
+3. `tests/unit/css-a11y.test.js` — extend the resolver to be palette-aware
+   (light values from the base block, dark values from the dark blocks) and
+   assert the existing light guarantees **and** their dark equivalents. The
+    palette values are chosen so the file's last-occurrence resolution (used
+    by the unchanged light tests) still passes: dark `--brand-accent`
+    (#3178a6) must keep ≥3:1 vs white as well as vs the dark background.
+4. `tests/e2e/dark-mode.spec.js` (against the built export, as always):
+   - toggle right edge == `.menu-bar` content right edge (±1px, incl. mobile);
+   - three options render with icons, system preselected;
+   - clicking "dark" flips `body` background; reload → still dark
+     (persistence); selecting "system" follows the emulated OS scheme
+     (`colorScheme: 'dark'` → dark without any click);
+   - default light rendering under `colorScheme: 'light'` is unchanged.
+
+Existing guards that must stay green untouched: `layout-styles`,
+`report-template*`, `report-template-wcag`, `html5-attributes`, `page-titles`,
+`zz-style-check`, plus the full integration suite (the renderer forbids
+`<input>` — irrelevant here since the toggle is React-rendered, not
+mustache-rendered).
+
+## Implementation steps
+
+1. Write the failing unit/integration tests (above).
+2. `components/theme-toggle.jsx` + render it in `app/layout.jsx` on a
+   `.theme-bar` row right after `<SiteHeader />`, before the persistence
+   shim.
+3. globals.css: split color roles, sweep hardcoded colors into variables, add
+   the three cascade blocks + mvp variable overrides + dark overrides for the
+   report template's light-only rules + `.theme-bar`/toggle styles.
+4. `app/layout.jsx`: inline persistence script after `<SiteHeader />` +
+   `color-scheme` meta.
+5. Unit/integration green; `npx eslint` clean.
+6. E2E: new spec + the header-adjacent specs (`layout`, `user-journeys`,
+   `mobile-responsiveness`, `breadcrumbs`) against a fresh `bun run build`.
+7. Update `AGENTS.md` (feature bullet + theming notes).
+
+## Critical review (self-review of this plan)
+
+1. **"Only CSS" is not literally achievable end-to-end** — persistence needs
+   ~8 lines of JS. This is called out rather than hidden: every *visual* aspect
+   (switching, system-following, palettes, no-FOUC for the system default)
+   remains pure CSS; the script only remembers the choice. A strictly-CSS
+   alternative (no persistence) was rejected: losing the theme on every
+   refresh fails the "best practices" requirement, which the user also
+   stated. Best-practice guides (web.dev, MDN) list persistence as
+   fundamental.
+2. **FOUC audit** — with the system default there is *zero* flash (media
+   query applies at first style resolution). With an explicit saved choice the
+   inline script runs before the parser yields (it sits immediately after the
+   header markup), so no content is painted before it executes; the residual
+   worst case is a single light frame of the 48px menu bar. A `<head>`-set
+   `data-theme` attribute would remove even that but was rejected: it makes
+   the attribute a *second source of truth* and breaks "radios work without
+   JS".
+3. **`:has()` support** — Baseline since Dec 2023 (Chromium 105+, Firefox
+   121+, Safari 15.4+). In browsers without it the toggle is inert but the
+   system preference still themes the site via the plain media query —
+   graceful degradation, matching the site's evergreen toolchain (Next 15,
+   WASM widgets).
+4. **Hydration safety** — the restore script sets the `checked` DOM property
+   only (never the attribute), so React sees no hydration mismatch, and
+   uncontrolled radios are never re-managed by React afterwards. Verified
+   pattern for static-export + hydration.
+5. **Cascade order verified against the naive test parsers** —
+   `css-a11y.test.js`/`layout-styles.test.js` parse globals.css with a
+   flat regex; the plan deliberately keeps single-level `@media` nesting and
+   chooses dark values that also satisfy the light assertions under the
+    parser's last-occurrence variable resolution (e.g. dark `--brand-accent`
+    #3178a6 is ≥3:1 vs white). The new `theme-css.test.js` then adds a
+   palette-aware resolver so this fragile coincidence becomes an enforced
+   property instead of luck.
+6. **Duplication risk** — the dark block exists twice (media + explicit).
+   Unavoidable in plain CSS; mitigated by the byte-identical test, which turns
+   the duplication into an invariant.
+7. **mvp.css beat strategy re-checked** — light overrides need `html:root`
+   because mvp's `:root` declarations load later; dark blocks win on
+   specificity (1,2,0). Confirmed against mvp.css 1.15.0's actual source
+   (fetched and inspected), not assumption.
+8. **Report scope contained** — the mustache template stays untouched
+   (guarded byte-for-byte by an existing test), so ~200 E2E report assertions
+   are structurally unaffected; dark overrides live in globals.css where the
+   new unit tests cover them.
+9. **Contrast choices are computed, not eyeballed** — every dark palette pair
+   is asserted in tests using the same WCAG math as the existing suite; values
+   were pre-verified (dark bg/text ≈13:1, muted ≈8:1, links ≈7.7:1, focus
+    indicator 3.8:1 on the page bg (3.3:1 on surfaces), brand-bg+white 5.5:1,
+    error/success ≈8:1).
+10. **Alignment is structural, not geometric** — the `.theme-bar` row
+    reuses the breadcrumbs' `--width-content` column + 0.8rem padding formula,
+    so the toggle's right edge is the menu bar's right content edge at every
+    viewport with zero positioning code; the E2E test pins it with a
+    bounding-box comparison, at desktop and mobile widths.
+
+Verdict: the design is sound. The only genuine trade-offs — the persistence
+shim (flagged deviation) and the duplicated dark block (test-guarded) — are
+the standard costs of doing three-mode theming in pure CSS, and both are
+consciously mitigated rather than accidental.
diff --git a/tests/e2e/dark-mode.spec.js b/tests/e2e/dark-mode.spec.js
new file mode 100644
index 0000000..5390dc0
--- /dev/null
+++ b/tests/e2e/dark-mode.spec.js
@@ -0,0 +1,164 @@
+// Dark mode E2E (plans/css-only-dark-mode.md): the three-mode toggle sits
+// flush with the top menu's right content edge, switching is pure CSS
+// (radio :has() + prefers-color-scheme), and the inline bootstrap script
+// persists the choice across hard loads.
+import { test, expect } from '@playwright/test';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const SAMPLE_REPORT = readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)), '../fixtures/junit4-report.json'),
+  'utf8'
+);
+
+const LIGHT_BG = 'rgb(255, 255, 255)';
+const DARK_BG = 'rgb(16, 22, 29)';
+
+async function bodyBackground(page) {
+  return page.evaluate(
+    () => getComputedStyle(document.body).backgroundColor
+  );
+}
+
+test('the toggle renders three labelled icon modes with system preselected', async ({ page }) => {
+  await page.goto('/');
+  const group = page.locator('.theme-toggle[role="radiogroup"]');
+  await expect(group).toBeVisible();
+  await expect(group).toHaveAttribute('aria-label', 'Color theme');
+  await expect(group.locator('input[type="radio"]')).toHaveCount(3);
+  await expect(page.locator('#rf-theme-system')).toBeChecked();
+  for (const value of ['light', 'dark', 'system']) {
+    await expect(page.locator(`#rf-theme-${value}`)).toHaveAttribute('name', 'rf-theme');
+    await expect(page.locator(`#rf-theme-${value} + .theme-option-icon`)).toBeVisible();
+  }
+});
+
+test('the toggle right edge aligns with the top menu content edge', async ({ page }) => {
+  test.skip(test.info().project.name !== 'chromium', 'geometry check runs once');
+  await page.setViewportSize({ width: 1280, height: 900 });
+  await page.goto('/');
+  const edges = await page.evaluate(() => {
+    const header = document.getElementById('top-menu').getBoundingClientRect();
+    const bar = document.querySelector('.menu-bar').getBoundingClientRect();
+    const toggle = document.querySelector('.theme-toggle').getBoundingClientRect();
+    const style = getComputedStyle(document.querySelector('.menu-bar'));
+    return {
+      toggleRight: toggle.right,
+      // The menu bar's right *content* edge (its 0.8rem padding insets the
+      // search input exactly like the row padding insets the toggle).
+      barContentRight: bar.right - parseFloat(style.paddingRight),
+      belowHeader: toggle.top >= header.bottom
+    };
+  });
+  expect(Math.abs(edges.toggleRight - edges.barContentRight)).toBeLessThanOrEqual(1);
+  expect(edges.belowHeader).toBe(true);
+});
+
+test('the toggle sits below the header, right-aligned, at mobile widths', async ({ page }) => {
+  test.skip(test.info().project.name !== 'chromium', 'geometry check runs once');
+  await page.setViewportSize({ width: 375, height: 800 });
+  await page.goto('/');
+  const edges = await page.evaluate(() => {
+    const header = document.getElementById('top-menu').getBoundingClientRect();
+    const bar = document.querySelector('.menu-bar').getBoundingClientRect();
+    const toggle = document.querySelector('.theme-toggle').getBoundingClientRect();
+    return {
+      toggleRight: toggle.right,
+      barContentRight: bar.right - parseFloat(getComputedStyle(document.querySelector('.menu-bar')).paddingRight),
+      belowHeader: toggle.top >= header.bottom
+    };
+  });
+  expect(Math.abs(edges.toggleRight - edges.barContentRight)).toBeLessThanOrEqual(1);
+  expect(edges.belowHeader).toBe(true);
+});
+
+test('light OS preference renders light by default', async ({ page }) => {
+  await page.emulateMedia({ colorScheme: 'light' });
+  await page.goto('/');
+  expect(await bodyBackground(page)).toBe(LIGHT_BG);
+});
+
+test('dark OS preference themes the site without any click', async ({ page }) => {
+  await page.emulateMedia({ colorScheme: 'dark' });
+  await page.goto('/');
+  expect(await bodyBackground(page)).toBe(DARK_BG);
+  // The system radio stays checked; the palette came from prefers-color-scheme.
+  await expect(page.locator('#rf-theme-system')).toBeChecked();
+});
+
+test('the dark radio overrides a light OS preference and persists across reloads', async ({ page }) => {
+  await page.emulateMedia({ colorScheme: 'light' });
+  await page.goto('/');
+  await page.locator('#rf-theme-dark').check();
+  expect(await bodyBackground(page)).toBe(DARK_BG);
+
+  await page.reload();
+  expect(await bodyBackground(page)).toBe(DARK_BG);
+  await expect(page.locator('#rf-theme-dark')).toBeChecked();
+  expect(await page.evaluate(() => localStorage.getItem('rf-theme'))).toBe('dark');
+});
+
+test('the light radio overrides a dark OS preference and persists across reloads', async ({ page }) => {
+  await page.emulateMedia({ colorScheme: 'dark' });
+  await page.goto('/');
+  await page.locator('#rf-theme-light').check();
+  expect(await bodyBackground(page)).toBe(LIGHT_BG);
+
+  await page.reload();
+  expect(await bodyBackground(page)).toBe(LIGHT_BG);
+  expect(await page.evaluate(() => localStorage.getItem('rf-theme'))).toBe('light');
+});
+
+test('switching back to system follows the OS preference again', async ({ page }) => {
+  await page.emulateMedia({ colorScheme: 'dark' });
+  await page.goto('/');
+  await page.locator('#rf-theme-light').check();
+  expect(await bodyBackground(page)).toBe(LIGHT_BG);
+  await page.locator('#rf-theme-system').check();
+  expect(await bodyBackground(page)).toBe(DARK_BG);
+  expect(await page.evaluate(() => localStorage.getItem('rf-theme'))).toBe('system');
+});
+
+test('dark mode keeps rendering dark on report pages after navigation', async ({ page }) => {
+  await page.goto('/');
+  await page.locator('#rf-theme-dark').check();
+  await page.goto('/about/');
+  expect(await bodyBackground(page)).toBe(DARK_BG);
+  expect(await page.evaluate(() => localStorage.getItem('rf-theme'))).toBe('dark');
+});
+
+test('breadcrumbs and the toggle share one vertically centered row on report pages', async ({ page }) => {
+  test.skip(test.info().project.name !== 'chromium', 'geometry check runs once');
+  // Mock GitHub raw content so the report page never hits the network.
+  await page.route('**/raw.githubusercontent.com/**', route => {
+    if (route.request().url().endsWith('refactor-first.json')) {
+      route.fulfill({ status: 200, contentType: 'application/json', body: SAMPLE_REPORT });
+    } else {
+      route.continue();
+    }
+  });
+  await page.goto('/refactorfirst/refactorfirst/master/');
+  await page.waitForLoadState('networkidle');
+  const edges = await page.evaluate(() => {
+    const crumb = document.querySelector('nav[aria-label="Breadcrumb"] ol li a');
+    const crumbBox = crumb.getBoundingClientRect();
+    const toggle = document.querySelector('.theme-toggle').getBoundingClientRect();
+    const bar = document.querySelector('.menu-bar').getBoundingClientRect();
+    return {
+      crumbGlyphLeft: crumbBox.left + parseFloat(getComputedStyle(crumb).paddingLeft),
+      brandLeft: document.querySelector('.brand').getBoundingClientRect().left,
+      sameRow: crumbBox.top < toggle.bottom && toggle.top < crumbBox.bottom,
+      centerDelta: Math.abs((crumbBox.top + crumbBox.bottom) / 2 - (toggle.top + toggle.bottom) / 2),
+      toggleRight: toggle.right,
+      barContentRight: bar.right - parseFloat(getComputedStyle(document.querySelector('.menu-bar')).paddingRight)
+    };
+  });
+  // The first crumb's glyph keeps the menu column's left content edge…
+  expect(Math.abs(edges.crumbGlyphLeft - edges.brandLeft)).toBeLessThanOrEqual(1);
+  // …the toggle keeps the right content edge…
+  expect(Math.abs(edges.toggleRight - edges.barContentRight)).toBeLessThanOrEqual(1);
+  // …and the two share one vertically centered line.
+  expect(edges.sameRow).toBe(true);
+  expect(edges.centerDelta).toBeLessThanOrEqual(1);
+});
diff --git a/tests/integration/theme-toggle.test.jsx b/tests/integration/theme-toggle.test.jsx
new file mode 100644
index 0000000..81577a1
--- /dev/null
+++ b/tests/integration/theme-toggle.test.jsx
@@ -0,0 +1,111 @@
+// Dark mode toggle below the site header: three radio modes (light / dark /
+// system) rendered as icon pills, with the system preference preselected and
+// the whole control on a right-aligned .theme-bar row under the header —
+// the row the breadcrumb trail shares on report routes (crumbs left, toggle
+// right), aligned with the menu bar's content edges
+// (plans/css-only-dark-mode.md).
+import { describe, test, expect } from 'bun:test';
+import { mock } from 'bun:test';
+
+import { sharedNextNavigationMock } from './next-navigation-stub';
+
+let currentPath = '/';
+let currentSearch = '';
+mock.module('next/navigation', () => sharedNextNavigationMock({
+  usePathname: () => currentPath,
+  useSearchParams: () => new URLSearchParams(currentSearch)
+}));
+
+import { render, installRtlDom, within } from './rtl';
+import { jsx as _jsx } from 'react/jsx-runtime';
+import { renderToStaticMarkup } from 'react-dom/server';
+import ThemeToggle from '../../components/theme-toggle';
+import RootLayout from '../../app/layout';
+
+installRtlDom();
+
+describe('ThemeToggle', () => {
+  test('renders a radiogroup with three labelled modes', () => {
+    render(_jsx(ThemeToggle, {}));
+    const group = document.querySelector('[role="radiogroup"]');
+    expect(group).toBeTruthy();
+    expect(group.getAttribute('aria-label')).toBe('Color theme');
+
+    const inputs = within(group).getAllByRole('radio');
+    expect(inputs.length).toBe(3);
+    const described = inputs.map(input => input.getAttribute('aria-label'));
+    expect(described).toContain('Light theme');
+    expect(described).toContain('Dark theme');
+    expect(described).toContain('System preference');
+  });
+
+  test('the system preference is preselected and all inputs share one group', () => {
+    render(_jsx(ThemeToggle, {}));
+    const system = document.getElementById('rf-theme-system');
+    expect(system.checked).toBe(true);
+    const names = [...document.querySelectorAll('input[type="radio"]')]
+      .map(input => input.getAttribute('name'));
+    expect(new Set(names).size).toBe(1);
+    expect(names[0]).toBe('rf-theme');
+  });
+
+  test('each mode carries a decorative icon (small image) inside its label', () => {
+    render(_jsx(ThemeToggle, {}));
+    const labels = [...document.querySelectorAll('.theme-option')];
+    expect(labels.length).toBe(3);
+    labels.forEach(label => {
+      const icon = label.querySelector('svg');
+      expect(icon).toBeTruthy();
+      expect(icon.getAttribute('aria-hidden')).toBe('true');
+      expect(icon.classList.contains('theme-option-icon')).toBe(true);
+      // The icon is a sibling of the radio so :checked styling can reach it.
+      expect(icon.previousElementSibling.tagName).toBe('INPUT');
+    });
+  });
+});
+
+describe('Root layout placement', () => {
+  test('the toggle row sits below the header, before main, holding the radios', () => {
+    const html = renderToStaticMarkup(_jsx(RootLayout, { children: null }));
+    const headerStart = html.indexOf('<header');
+    const headerEnd = html.indexOf('</header>');
+    const themeBar = html.indexOf('class="theme-bar"');
+    const main = html.indexOf('<main');
+    expect(themeBar).toBeGreaterThan(headerEnd);
+    expect(themeBar).toBeLessThan(main);
+    // The header itself no longer contains the toggle row.
+    expect(html.slice(headerStart, headerEnd)).not.toContain('theme-bar');
+    // The row holds all three radios (and nothing but the toggle).
+    const rowHtml = html.slice(themeBar, main);
+    expect(rowHtml).toContain('rf-theme-light');
+    expect(rowHtml).toContain('rf-theme-dark');
+    expect(rowHtml).toContain('rf-theme-system');
+    // The persistence bootstrap must come after the radios to restore the
+    // saved choice pre-paint.
+    const shim = html.indexOf("localStorage.getItem('rf-theme')");
+    expect(shim).toBeGreaterThan(themeBar);
+  });
+
+  test('on report routes the breadcrumb trail shares the toggle row, to its left', () => {
+    currentPath = '/alice/some-repo/master';
+    currentSearch = '';
+    try {
+      const html = renderToStaticMarkup(_jsx(RootLayout, { children: null }));
+      const themeBar = html.indexOf('class="theme-bar"');
+      const main = html.indexOf('<main');
+      const rowHtml = html.slice(themeBar, main);
+      const crumbs = rowHtml.indexOf('aria-label="Breadcrumb"');
+      const toggle = rowHtml.indexOf('rf-theme-light');
+      expect(crumbs, 'breadcrumb nav missing from the theme bar').toBeGreaterThan(-1);
+      expect(toggle).toBeGreaterThan(-1);
+      // DOM order mirrors the flex row: crumbs first (left), toggle last
+      // (right); the row's flex-grow keeps them on one line.
+      expect(crumbs).toBeLessThan(toggle);
+      // The trail no longer renders outside the row.
+      expect(html.slice(0, themeBar)).not.toContain('aria-label="Breadcrumb"');
+      expect(html.slice(main)).not.toContain('aria-label="Breadcrumb"');
+    } finally {
+      currentPath = '/';
+    }
+  });
+});
diff --git a/tests/unit/layout-styles.test.js b/tests/unit/layout-styles.test.js
index 8d78e58..540ed9a 100644
--- a/tests/unit/layout-styles.test.js
+++ b/tests/unit/layout-styles.test.js
@@ -56,17 +56,18 @@ describe('layout styles (mvp.css section-flex reset)', () => {
     expect(body).toMatch(/margin:\s*0\s+auto\s*;/);
   });
 
-  test('the breadcrumb bar shares the top menu column (#top-menu caps)', () => {
-    // #top-menu is capped by mvp.css at --width-content; reusing the variable
-    // keeps the breadcrumb column and the menu column aligned forever. The
-    // bar must be border-box so its horizontal padding insets crumbs exactly
-    // like .menu-bar's padding insets the brand: with content-box, symmetric
-    // padding on a centered block never moves the content edge.
+  test('the breadcrumb trail stretches inside the theme bar row (menu column)', () => {
+    // The trail now shares the .theme-bar row with the color theme toggle:
+    // the row carries the alignment formula (max-width: var(--width-content)
+    // + 0.8rem horizontal padding, guarded in tests/unit/theme-css.test.js),
+    // so .breadcrumbs must not add its own box-model offsets — it grows to
+    // fill the row's left side, keeping the first crumb's glyph at the menu
+    // column's left content edge while the toggle pins to the right edge.
     const body = rules.get('.breadcrumbs');
     expect(body).toBeTruthy();
-    expect(body).toMatch(/max-width:\s*var\(--width-content\)/);
-    expect(body).toMatch(/box-sizing:\s*border-box\s*;/);
-    expect(body).toMatch(/padding:\s*0\s+0\.8rem\s*;/); // matches .menu-bar
+    expect(body).toMatch(/flex:\s*1\s+1\s+auto/);
+    expect(body).not.toMatch(/max-width/);
+    expect(body).not.toMatch(/padding:\s*0\s+0\.8rem/);
   });
 
   test('crumb links carry no left padding (glyph edge aligns with the brand)', () => {
diff --git a/tests/unit/theme-css.test.js b/tests/unit/theme-css.test.js
new file mode 100644
index 0000000..f500a2f
--- /dev/null
+++ b/tests/unit/theme-css.test.js
@@ -0,0 +1,299 @@
+// Dark mode cascade guards (plans/css-only-dark-mode.md): the light palette
+// lives on :root, the dark palette is selected purely in CSS via
+// :has(#rf-theme-…:checked) radio state plus prefers-color-scheme, the two
+// dark blocks never drift apart, every hardcoded color stays inside the
+// palette blocks, and the dark palette passes the same WCAG 2.2 AA math the
+// css-a11y.test.js guards apply to the light palette.
+import { describe, it, expect } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const css = readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)), '../../app/globals.css'),
+  'utf-8'
+);
+const layoutSource = readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)), '../../app/layout.jsx'),
+  'utf-8'
+);
+
+const DARK_RADIO = ':root:has(#rf-theme-dark:checked)';
+const DARK_SYSTEM = ':root:has(#rf-theme-system:checked)';
+const PALETTE_SELECTORS = new Set([':root', 'html:root', DARK_RADIO, DARK_SYSTEM]);
+
+const noComments = css.replace(/\/\*[\s\S]*?\*\//g, '');
+
+/**
+ * Indexes CSS declaration blocks by selector (same parser as css-a11y).
+ *
+ * @param {string} source - Stylesheet source.
+ * @returns {Map<string, string>} Declaration blocks keyed by selector.
+ */
+function ruleMap(source) {
+  const rules = new Map();
+  const ruleRe = /([^{}]+)\{([^{}]*)\}/g;
+  let match;
+  while ((match = ruleRe.exec(source)) !== null) {
+    for (const selector of match[1].split(',')) {
+      rules.set(selector.trim(), match[2]);
+    }
+  }
+  return rules;
+}
+
+/**
+ * Collects custom property declarations from a declaration block.
+ *
+ * @param {string} body - Declarations of one CSS rule.
+ * @returns {Map<string, string>} Values keyed by custom property name.
+ */
+function cssVarsOf(body) {
+  const vars = new Map();
+  const varRe = /(--[\w-]+)\s*:\s*([^;]+);/g;
+  let match;
+  while ((match = varRe.exec(body)) !== null) {
+    vars.set(match[1], match[2].trim());
+  }
+  return vars;
+}
+
+const rules = ruleMap(noComments);
+
+/**
+ * Resolves a value against a palette, following one var() indirection.
+ *
+ * @param {string} value - CSS value to resolve.
+ * @param {Map<string, string>} palette - Palette values.
+ * @returns {string} The resolved value.
+ */
+function resolveIn(value, palette) {
+  const m = String(value).match(/var\((--[\w-]+)\)/);
+  return m ? palette.get(m[1]) : value;
+}
+
+/**
+ * Converts a hex color to normalized RGB channels.
+ *
+ * @param {string} hex - Hexadecimal CSS color.
+ * @returns {number[]} Red, green, and blue channels from 0 to 1.
+ */
+function hexToRgb(hex) {
+  const match = hex.trim().match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i);
+  if (!match) throw new Error(`not a hex color: ${hex}`);
+  let h = match[1];
+  if (h.length === 3) h = h.split('').map(c => c + c).join('');
+  return [0, 2, 4].map(i => parseInt(h.slice(i, i + 2), 16) / 255);
+}
+
+/**
+ * Calculates a color's WCAG relative luminance.
+ *
+ * @param {string} hex - Hexadecimal CSS color.
+ * @returns {number} Relative luminance from 0 to 1.
+ */
+function relativeLuminance(hex) {
+  const [r, g, b] = hexToRgb(hex).map(channel =>
+    channel <= 0.03928 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4
+  );
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/**
+ * Calculates the WCAG contrast ratio between two colors.
+ *
+ * @param {string} colorA - First hexadecimal CSS color.
+ * @param {string} colorB - Second hexadecimal CSS color.
+ * @returns {number} Contrast ratio from 1 to 21.
+ */
+function contrastRatio(colorA, colorB) {
+  const [la, lb] = [relativeLuminance(colorA), relativeLuminance(colorB)];
+  const [light, dark] = la >= lb ? [la, lb] : [lb, la];
+  return (light + 0.05) / (dark + 0.05);
+}
+
+// Light palette = base :root plus the html:root mvp.css overrides.
+const lightPalette = new Map([
+  ...cssVarsOf(rules.get(':root') || ''),
+  ...cssVarsOf(rules.get('html:root') || '')
+]);
+const darkBody = rules.get(DARK_RADIO) || '';
+const darkPalette = cssVarsOf(darkBody);
+
+/**
+ * Reads a contrast ratio between two palette entries.
+ *
+ * @param {Map<string, string>} palette - Palette to resolve against.
+ * @param {string} nameA - First custom property name.
+ * @param {string} nameB - Second custom property name.
+ * @returns {number} WCAG contrast ratio of the two resolved colors.
+ */
+function contrastOf(palette, nameA, nameB) {
+  return contrastRatio(resolveIn(palette.get(nameA), palette), resolveIn(palette.get(nameB), palette));
+}
+
+describe('dark mode cascade structure', () => {
+  it('the light palette declares color-scheme: light on :root', () => {
+    const base = rules.get(':root');
+    expect(base).toBeTruthy();
+    expect(base).toMatch(/color-scheme:\s*light/);
+    expect(lightPalette.get('--bg-color')).toBe('#ffffff');
+  });
+
+  it('mvp.css variables are overridden for the light theme on html:root', () => {
+    // mvp.css loads after the bundle, so same-specificity :root overrides
+    // would lose the cascade; html:root (0,1,1) beats mvp's :root (0,1,0).
+    const mvp = rules.get('html:root');
+    expect(mvp).toBeTruthy();
+    expect(mvp).toMatch(/--color-bg:\s*var\(--bg-color\)/);
+    expect(mvp).toMatch(/--color-link:\s*var\(--link-color\)/);
+  });
+
+  it('an explicit dark radio selects the dark palette at any OS setting', () => {
+    expect(darkBody).toBeTruthy();
+    expect(darkBody).toMatch(/color-scheme:\s*dark/);
+    expect(darkPalette.get('--bg-color')).toBeTruthy();
+    expect(darkPalette.get('--bg-color')).not.toBe('#ffffff');
+  });
+
+  it('the system radio follows the OS preference via prefers-color-scheme', () => {
+    const mediaSection = noComments.match(
+      /@media \(prefers-color-scheme: dark\)\s*\{([\s\S]*?)\n\}/
+    );
+    expect(mediaSection).toBeTruthy();
+    expect(mediaSection[1]).toContain(DARK_SYSTEM);
+    expect(rules.get(DARK_SYSTEM)).toBeTruthy();
+    expect(rules.get(DARK_SYSTEM)).toMatch(/color-scheme:\s*dark/);
+  });
+
+  it('the two dark blocks are identical so the palettes cannot drift', () => {
+    const normalize = body => body.replace(/\s+/g, ' ').trim();
+    expect(normalize(rules.get(DARK_SYSTEM))).toBe(normalize(darkBody));
+  });
+
+  it('no hardcoded colors survive outside the palette blocks', () => {
+    const ruleRe = /([^{}]+)\{([^{}]*)\}/g;
+    let match;
+    while ((match = ruleRe.exec(noComments)) !== null) {
+      const selector = match[1].trim();
+      if (PALETTE_SELECTORS.has(selector)) continue;
+      expect(match[2]).not.toMatch(/#[0-9a-fA-F]{3,6}\b/);
+      expect(match[2]).not.toMatch(/rgba?\(/);
+    }
+  });
+
+  it('report-template light-only rules are re-driven from theme variables', () => {
+    const pageBtn = rules.get('main#app .rf-page-btn');
+    expect(pageBtn).toBeTruthy();
+    expect(pageBtn).toMatch(/background:\s*var\(--card-bg\)/);
+    expect(pageBtn).toMatch(/color:\s*var\(--text-color\)/);
+
+    const popup = rules.get('main#app .popup');
+    expect(popup).toBeTruthy();
+    expect(popup).toMatch(/background-color:\s*var\(--card-bg\)/);
+
+    // The template hardcodes a #1f5273 focus ring that disappears on dark
+    // backgrounds; the override must come from the palette.
+    const focus = rules.get('main#app .rf-page-btn:focus-visible');
+    expect(focus).toMatch(/outline-color:\s*var\(--brand-accent\)/);
+
+    // The cell-copy focus ring must use the focus-indicator role too:
+    // --brand-color (the accent *background*) is only 2.9:1 against the
+    // dark --surface-color, below the 3:1 of SC 2.4.11.
+    const cellCopy = rules.get('main#app .rf-data-table td[data-rf-copy]:focus-visible');
+    expect(cellCopy).toMatch(/outline-color:\s*var\(--brand-accent\)/);
+  });
+});
+
+describe('toggle styles', () => {
+  it('the toggle renders icon pills over appearance-none radios', () => {
+    expect(rules.get('.theme-toggle')).toMatch(/display:\s*flex/);
+    expect(rules.get('.theme-option-input')).toMatch(/appearance:\s*none/);
+    expect(rules.get('.theme-option-input')).toMatch(/position:\s*absolute/);
+    expect(rules.get('.theme-option-input:checked')).toMatch(/background:\s*var\(--brand-color\)/);
+    expect(rules.get('.theme-option-input:checked + .theme-option-icon'))
+      .toMatch(/color:\s*var\(--on-accent-color\)/);
+  });
+
+  it('each toggle option meets the 24px minimum target size (SC 2.5.8)', () => {
+    const option = rules.get('.theme-option');
+    expect(option).toBeTruthy();
+    const width = Number(option.match(/width:\s*([\d.]+)rem/)[1]);
+    const height = Number(option.match(/height:\s*([\d.]+)rem/)[1]);
+    expect(width).toBeGreaterThanOrEqual(1.5);
+    expect(height).toBeGreaterThanOrEqual(1.5);
+  });
+
+  it('the row below the header mirrors the breadcrumb alignment formula', () => {
+    // Same invariant layout-styles.test.js pinned for the standalone
+    // .breadcrumbs bar: the row shares #top-menu's --width-content column
+    // and the 0.8rem horizontal padding insets its children to the menu
+    // bar's content edges at every viewport — the toggle on the right, the
+    // breadcrumb trail on the left (flex-grow), vertically centered.
+    const row = rules.get('.theme-bar');
+    expect(row).toBeTruthy();
+    expect(row).toMatch(/display:\s*flex/);
+    expect(row).toMatch(/justify-content:\s*flex-end/);
+    expect(row).toMatch(/align-items:\s*center/);
+    expect(row).toMatch(/max-width:\s*var\(--width-content\)/);
+    expect(row).toMatch(/box-sizing:\s*border-box/);
+    expect(row).toMatch(/margin:\s*0\s+auto/);
+    expect(row).toMatch(/padding:\s*[^;]*0\.8rem[^;]*;/);
+  });
+});
+
+describe('dark palette WCAG 2.2 AA', () => {
+  it('body text keeps AA contrast (>= 4.5:1)', () => {
+    expect(contrastOf(darkPalette, '--bg-color', '--text-color')).toBeGreaterThanOrEqual(4.5);
+  });
+
+  it('muted text keeps AA contrast (>= 4.5:1)', () => {
+    expect(contrastOf(darkPalette, '--bg-color', '--muted-color')).toBeGreaterThanOrEqual(4.5);
+  });
+
+  it('link text keeps AA contrast (>= 4.5:1)', () => {
+    expect(contrastOf(darkPalette, '--bg-color', '--link-color')).toBeGreaterThanOrEqual(4.5);
+  });
+
+  it('text on surface panels keeps AA contrast (>= 4.5:1)', () => {
+    expect(contrastOf(darkPalette, '--surface-color', '--text-color')).toBeGreaterThanOrEqual(4.5);
+  });
+
+  it('the keyboard focus indicator has non-text contrast >= 3:1 (SC 2.4.11)', () => {
+    expect(contrastOf(darkPalette, '--bg-color', '--brand-accent')).toBeGreaterThanOrEqual(3);
+    expect(contrastOf(darkPalette, '--surface-color', '--brand-accent')).toBeGreaterThanOrEqual(3);
+  });
+
+  it('accent backgrounds keep AA contrast with their foreground (>= 4.5:1)', () => {
+    expect(contrastOf(darkPalette, '--brand-color', '--on-accent-color')).toBeGreaterThanOrEqual(4.5);
+  });
+
+  it('input boundaries are perceivable on surfaces (SC 1.4.11, >= 3:1)', () => {
+    expect(contrastOf(darkPalette, '--surface-color', '--input-border')).toBeGreaterThanOrEqual(3);
+  });
+
+  it('status colors keep AA contrast on the page background (>= 4.5:1)', () => {
+    expect(contrastOf(darkPalette, '--bg-color', '--error-color')).toBeGreaterThanOrEqual(4.5);
+    expect(contrastOf(darkPalette, '--bg-color', '--success-color')).toBeGreaterThanOrEqual(4.5);
+  });
+
+  it('the dark accent also passes the light guards\' vs-white check', () => {
+    // css-a11y.test.js resolves custom properties by last occurrence in the
+    // file (the dark palette). Its assertions check contrast against white,
+    // so the dark --brand-accent must stay >= 3:1 against white too.
+    const accent = resolveIn(darkPalette.get('--brand-accent'), darkPalette);
+    expect(contrastRatio(accent, '#ffffff')).toBeGreaterThanOrEqual(3);
+  });
+});
+
+describe('theme persistence bootstrap', () => {
+  it('layout restores the saved choice pre-paint and saves changes', () => {
+    expect(layoutSource).toContain("localStorage.getItem('rf-theme')");
+    expect(layoutSource).toContain("localStorage.setItem('rf-theme'");
+    expect(layoutSource).toContain('rf-theme-');
+  });
+
+  it('layout advertises both color schemes before stylesheets load', () => {
+    expect(layoutSource).toMatch(/<meta\s+name="color-scheme"\s+content="light dark"\s*\/>/);
+  });
+});