@@ -12,9 +12,10 @@ in `out/` is served by any static host (GitHub Pages, GitLab Pages, Bitbucket).
 - Search over curated repository listing (`repositories.txt`)
 - Dark mode, 100% CSS switching (`components/theme-toggle.jsx` +
   `plans/css-only-dark-mode.md`): three radios (light/dark/system) on a
-  right-aligned `.theme-bar` sub-row under the menu bar (the right-edge
-  mirror of the breadcrumbs' left-edge alignment), palettes selected in
-  `app/globals.css` via `:root:has(#rf-theme-…:checked)` +
+  right-aligned `.theme-bar` row below the header, rendered by
+  `app/layout.jsx` between `<SiteHeader>` and the persistence script (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
 
@@ -685,27 +685,28 @@ pre {
 }
 
 /* ---- Color theme toggle (three radio modes, pure-CSS switching) ---- */
-/* Sub-row under the menu bar: the same alignment formula .breadcrumbs use
-   (--width-content column, 0.8rem horizontal padding, border-box) keeps the
-   toggle's right edge flush with the menu bar's right content edge at every
-   viewport — the right-edge mirror of the breadcrumb trail's left-edge
-   alignment. #top-menu is capped by mvp.css at --width-content, so the row
-   and the menu bar can never drift apart. */
+/* Row below the site header (rendered by app/layout.jsx): the same alignment
+   formula .breadcrumbs use (--width-content column, 0.8rem horizontal
+   padding, border-box) keeps the toggle's right edge flush with the menu
+   bar's right content edge at every viewport — the right-edge mirror of the
+   breadcrumb trail's left-edge alignment. #top-menu is capped by mvp.css at
+   --width-content, so the row and the menu bar can never drift apart. */
 .theme-bar {
   display: flex;
   justify-content: flex-end;
   max-width: var(--width-content);
   box-sizing: border-box;
   margin: 0 auto;
-  padding: 0.2rem 0.8rem 0.45rem;
+  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. */
+   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;
@@ -714,7 +715,7 @@ pre {
   padding: 0.15rem;
   border: 1px solid var(--input-border);
   border-radius: var(--radius);
-  background: var(--bg-color);
+  background: var(--surface-color);
 }
 
 .theme-option {
@@ -728,7 +729,7 @@ pre {
 }
 
 .theme-option:hover {
-  background: var(--surface-color);
+  background: var(--btn-hover-bg);
 }
 
 .theme-option-input {
 
@@ -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';
 
@@ -48,13 +49,25 @@ export default function RootLayout({ children }) {
       </head>
       <body>
         <SiteHeader repositories={repositories} />
+        {/* Color theme toggle on a row below the header: .theme-bar reuses
+            the breadcrumbs' alignment formula (--width-content column,
+            0.8rem horizontal padding, border-box) so the toggle's right
+            edge sits flush with the menu bar's right content edge,
+            mirroring how the breadcrumb trail aligns with the bar's left
+            edge (plans/css-only-dark-mode.md). */}
+        <div className="theme-bar">
+          <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 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. */}
+            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:
 
@@ -1,12 +1,11 @@
 import Link from 'next/link';
 import MenuToggle from './menu-toggle';
 import MenuSearch from './menu-search';
-import ThemeToggle from './theme-toggle';
 import { withBasePath } from '../lib/base-path';
 
 // Site header: brand logo, hamburger toggle, main navigation links and the
-// type-ahead menu search in the top bar, plus the three-mode color theme
-// toggle on a right-aligned sub-row below 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 (
     <>
@@ -35,15 +34,6 @@ export default function SiteHeader({ repositories = [] }) {
           </ul>
           <MenuSearch repositories={repositories} />
         </nav>
-        {/* Theme sub-row below the menu bar: .theme-bar reuses the
-            breadcrumbs' alignment formula (--width-content column, 0.8rem
-            horizontal padding, border-box) so the toggle's right edge sits
-            flush with the menu bar's right content edge, mirroring how the
-            breadcrumb trail aligns with the bar's left edge
-            (plans/css-only-dark-mode.md). */}
-        <div className="theme-bar">
-          <ThemeToggle />
-        </div>
       </header>
     </>
   );
 
@@ -3,7 +3,7 @@
 ## Goals
 
 1. Three-mode theme control — **light / dark / system** — with small images
-   (icons) for each mode, on a sub-row below the top menu bar.
+   (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).
@@ -19,8 +19,9 @@
 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` sub-row under `.menu-bar`**, inside `#top-menu`, right-aligned
-with the menu bar's content edge.
+**`.theme-bar` row below `#top-menu`**, rendered by `app/layout.jsx` right
+after `<SiteHeader />` (and before the persistence shim, which needs the
+radios parsed), right-aligned with the menu bar's 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.
@@ -122,15 +123,16 @@ practices" and "only CSS" conflict here, so the plan resolves it as:
 
 ### Alignment with the menu
 
-The toggle lives on a `.theme-bar` sub-row inside `#top-menu`, right after
-`.menu-bar`, and pinned right via `justify-content: flex-end`. The row
-reuses the breadcrumbs' exact alignment formula — `max-width:
-var(--width-content)`, `box-sizing: border-box`, `margin: 0 auto`,
-`padding: 0.2rem 0.8rem 0.45rem` (see `tests/unit/layout-styles.test.js` for
-the breadcrumb invariant this mirrors) — so its right content edge is the
-menu bar's right content edge at every viewport, with no positioning tricks
-or magic numbers; the formula works identically at mobile widths, where the
-sub-row simply follows the wrapped menu bar.
+The toggle lives on a `.theme-bar` row rendered by `app/layout.jsx` right
+after `<SiteHeader />`, below the header block, pinned right via
+`justify-content: flex-end`. The row reuses the breadcrumbs' exact alignment
+formula — `max-width: var(--width-content)`, `box-sizing: border-box`,
+`margin: 0 auto`, `padding: 0.4rem 0.8rem 0.45rem` (see
+`tests/unit/layout-styles.test.js` for the breadcrumb invariant this mirrors)
+— so its right content edge is the menu bar's right content edge at every
+viewport, with 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
 
@@ -191,8 +193,9 @@ mustache-rendered).
 ## Implementation steps
 
 1. Write the failing unit/integration tests (above).
-2. `components/theme-toggle.jsx` + render it in `components/site-header.jsx`
-   on a `.theme-bar` sub-row after `.menu-bar`.
+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.
@@ -254,7 +257,7 @@ mustache-rendered).
    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` sub-row
+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
 
@@ -31,34 +31,38 @@ test('the toggle right edge aligns with the top menu content edge', async ({ pag
   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 sub-row padding insets the toggle).
-      barContentRight: bar.right - parseFloat(style.paddingRight)
+      // 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 menu bar, right-aligned, at mobile widths', async ({ page }) => {
+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),
-      belowBar: toggle.top >= bar.bottom
+      belowHeader: toggle.top >= header.bottom
     };
   });
   expect(Math.abs(edges.toggleRight - edges.barContentRight)).toBeLessThanOrEqual(1);
-  expect(edges.belowBar).toBe(true);
+  expect(edges.belowHeader).toBe(true);
 });
 
 test('light OS preference renders light by default', async ({ page }) => {
 
@@ -1,7 +1,8 @@
-// Dark mode toggle under the top menu: three radio modes (light / dark /
+// 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 sub-row below the menu bar whose right edge aligns
-// with the menu's content edge (plans/css-only-dark-mode.md).
+// the whole control on a right-aligned .theme-bar row under the header whose
+// right edge aligns with the menu bar's content edge
+// (plans/css-only-dark-mode.md).
 import { describe, test, expect } from 'bun:test';
 import { mock } from 'bun:test';
 
@@ -14,8 +15,9 @@ mock.module('next/navigation', () => sharedNextNavigationMock({
 
 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 SiteHeader from '../../components/site-header';
+import RootLayout from '../../app/layout';
 
 installRtlDom();
 
@@ -59,21 +61,25 @@ describe('ThemeToggle', () => {
   });
 });
 
-describe('SiteHeader placement', () => {
-  test('the toggle sits on a sub-row below the menu bar, inside the header', () => {
-    render(_jsx(SiteHeader, { repositories: [] }));
-    const header = document.getElementById('top-menu');
-    const bar = document.querySelector('.menu-bar');
-    const themeBar = header.querySelector('.theme-bar');
-    const toggle = themeBar.querySelector('.theme-toggle');
-    expect(themeBar).toBeTruthy();
-    expect(toggle).toBeTruthy();
-    // The sub-row comes after the menu bar and holds only the toggle.
-    const children = [...header.children];
-    expect(children[children.length - 1]).toBe(themeBar);
-    expect(children.indexOf(themeBar)).toBeGreaterThan(children.indexOf(bar));
-    expect(themeBar.children.length).toBe(1);
-    expect(themeBar.contains(toggle)).toBe(true);
-    expect(bar.contains(toggle)).toBe(false);
+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);
   });
 });