From 2aa0600b6fb96054274eb846cd83a7f27eac6620 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Fri, 29 May 2026 15:49:37 +0200
Subject: [PATCH 01/31] feat: color datatype

Adds a color datatype to Verso, as the basis for a theme feature.
---
 src/tests/TestMain.lean                       |  31 +++++
 src/tests/Tests.lean                          |   1 +
 src/tests/Tests/Color.lean                    |  56 +++++++++
 src/verso/Verso.lean                          |   1 +
 src/verso/Verso/Color.lean                    |  11 ++
 src/verso/Verso/Color/Basic.lean              |  94 ++++++++++++++
 src/verso/Verso/Color/Syntax.lean             |  92 ++++++++++++++
 src/verso/Verso/Color/Types.lean              |  19 +++
 src/verso/Verso/Color/Widget.lean             |  34 +++++
 src/verso/Verso/Color/color-swatch.js         |  25 ++++
 .../literate-config/lake-manifest.json        | 119 ++++++++----------
 .../literate-multi-root/lake-manifest.json    | 119 ++++++++----------
 12 files changed, 470 insertions(+), 132 deletions(-)
 create mode 100644 src/tests/Tests/Color.lean
 create mode 100644 src/verso/Verso/Color.lean
 create mode 100644 src/verso/Verso/Color/Basic.lean
 create mode 100644 src/verso/Verso/Color/Syntax.lean
 create mode 100644 src/verso/Verso/Color/Types.lean
 create mode 100644 src/verso/Verso/Color/Widget.lean
 create mode 100644 src/verso/Verso/Color/color-swatch.js

diff --git a/src/tests/TestMain.lean b/src/tests/TestMain.lean
index f77fde9bc..56f73455b 100644
--- a/src/tests/TestMain.lean
+++ b/src/tests/TestMain.lean
@@ -349,9 +349,40 @@ def testBuildLog (_ : Config) : IO Unit := do
     throw <| IO.userError "redirected logging should still accumulate into the logger's buffers"
   IO.println "  All build-log tests passed."
 
+open Verso in
+def testColor (_ : Config) : IO Unit := do
+  IO.println "Running color tests..."
+  let check (name got expected : String) : IO Unit :=
+    unless got == expected do
+      throw <| IO.userError s!"{name}: got \"{got}\", expected \"{expected}\""
+  -- Opaque colors render as lowercase `#rrggbb`.
+  check "black.css" Color.black.css "#000000"
+  check "white.css" Color.white.css "#ffffff"
+  check "gray.css" Color.gray.css "#808080"
+  check "red.css" Color.red.css "#ff0000"
+  check "green.css" Color.green.css "#008000"
+  check "blue.css" Color.blue.css "#0000ff"
+  check "transparent.css" Color.transparent.css "#00000000"
+  check "6-digit literal css" (color%#4777ff).css "#4777ff"
+  -- A 3-digit literal doubles each digit.
+  check "3-digit literal css" (color%#fff).css "#ffffff"
+  -- A color with alpha renders as `rgba(...)` with the alpha in [0, 1].
+  check "alpha literal css" (color%#aabbcc80).css "#aabbcc80"
+  -- TeX rendering is six uppercase hex digits with no alpha.
+  check "red.tex" Color.red.tex "FF0000"
+  check "literal tex" (color%#4777ff).tex "4777FF"
+  check "alpha literal tex" (color%#aabbcc80).tex "AABBCC"
+  -- The literal parses to the expected channels.
+  unless (color%#4777ff) = Color.rgba 0x47 0x77 0xff 255 do
+    throw <| IO.userError "6-digit literal parsed to the wrong channels"
+  unless (color%#fff) = Color.rgba 255 255 255 255 do
+    throw <| IO.userError "3-digit literal parsed to the wrong channels"
+  IO.println "  All color tests passed."
+
 open Verso.Integration in
 def tests := [
   testBuildLog,
+  testColor,
   testSerialization,
   testSearchJs,
   testBlog,
diff --git a/src/tests/Tests.lean b/src/tests/Tests.lean
index 9b25d3df0..f28bc799c 100644
--- a/src/tests/Tests.lean
+++ b/src/tests/Tests.lean
@@ -4,6 +4,7 @@ Released under Apache 2.0 license as described in the file LICENSE.
 Author: David Thrane Christiansen
 -/
 import Tests.Basic
+import Tests.Color
 import Tests.Elab
 import Tests.GenericCode
 import Tests.Golden
diff --git a/src/tests/Tests/Color.lean b/src/tests/Tests/Color.lean
new file mode 100644
index 000000000..9e892cee0
--- /dev/null
+++ b/src/tests/Tests/Color.lean
@@ -0,0 +1,56 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+import Verso.Color
+import Lean.Elab.Command
+
+/-!
+Compile-time tests for the `color%` literal: the three accepted hex lengths elaborate, and other
+lengths are rejected with a clear error. Value-level `css`/`tex` checks live in the runtime suite
+(`testColor` in `TestMain`).
+-/
+
+open Verso
+
+-- The three accepted lengths elaborate and render as expected (a 3-digit literal doubles each
+-- digit; 8 digits keep the alpha byte).
+/-- info: #ffffff -/
+#guard_msgs in
+#eval IO.println (color%#fff).css
+
+/-- info: #4777ff -/
+#guard_msgs in
+#eval IO.println (color%#4777ff).css
+
+/-- info: #aabbcc80 -/
+#guard_msgs in
+#eval IO.println (color%#aabbcc80).css
+
+/-- error: expected 3, 6, or 8 hex digits, got 0 -/
+#guard_msgs in
+example : Color := color%#
+
+/-- error: expected 3, 6, or 8 hex digits, got 4 -/
+#guard_msgs in
+example : Color := color%#1234
+
+/-- error: expected 3, 6, or 8 hex digits, got 5 -/
+#guard_msgs in
+example : Color := color%#12345
+
+/-- error: expected 3, 6, or 8 hex digits, got 7 -/
+#guard_msgs in
+example : Color := color%#1234567
+
+-- The parser registers trailing whitespace on the hex token, so the original source (including the
+-- spaces after the literal) can be reconstructed from the parse tree by `Syntax.reprint`.
+open Lean Parser in
+/-- info: round-trips: true -/
+#guard_msgs in
+#eval show Lean.Elab.Command.CommandElabM Unit from do
+  let input := "color%#abc   "
+  match runParserCategory (← getEnv) `term input with
+  | .ok stx => IO.println s!"round-trips: {stx.reprint == some input}"
+  | .error e => throwError e
diff --git a/src/verso/Verso.lean b/src/verso/Verso.lean
index 328400a72..29c24bf84 100644
--- a/src/verso/Verso.lean
+++ b/src/verso/Verso.lean
@@ -8,6 +8,7 @@ module
 -- Import modules here that should be built as part of the library.
 public import Verso.CLI
 public import Verso.Code
+public import Verso.Color
 public import Verso.Doc
 public import Verso.Doc.ArgParse
 public import Verso.Doc.Concrete
diff --git a/src/verso/Verso/Color.lean b/src/verso/Verso/Color.lean
new file mode 100644
index 000000000..434913b12
--- /dev/null
+++ b/src/verso/Verso/Color.lean
@@ -0,0 +1,11 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+public import Verso.Color.Types
+public import Verso.Color.Basic
+public import Verso.Color.Widget
+public import Verso.Color.Syntax
diff --git a/src/verso/Verso/Color/Basic.lean b/src/verso/Verso/Color/Basic.lean
new file mode 100644
index 000000000..ca3df7b4c
--- /dev/null
+++ b/src/verso/Verso/Color/Basic.lean
@@ -0,0 +1,94 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+public import Verso.Color.Types
+
+set_option linter.missingDocs true
+set_option doc.verso true
+
+/-!
+The pure Lean API for {name (full := Verso.Color)}`Color`: a small set of named colors, CSS and TeX
+rendering, and parsing of hex color strings.
+-/
+
+namespace Verso.Color
+
+/--
+Constructs an opaque color.
+-/
+public def rgb (red green blue : UInt8) : Color := .rgba red green blue 255
+
+/-- Opaque black. -/
+public def black : Color := .rgb 0 0 0
+/-- Opaque white. -/
+public def white : Color := .rgb 255 255 255
+/-- A medium gray, matching the CSS {lit}`gray` keyword ({lit}`#808080`). -/
+public def gray : Color := .rgb 128 128 128
+/-- Opaque red, matching the CSS {lit}`red` keyword ({lit}`#ff0000`). -/
+public def red : Color := .rgb 255 0 0
+/-- Opaque green, matching the CSS {lit}`green` keyword ({lit}`#008000`, not full-intensity {lit}`#00ff00`). -/
+public def green : Color := .rgb 0 128 0
+/-- Opaque blue, matching the CSS {lit}`blue` keyword ({lit}`#0000ff`). -/
+public def blue : Color := .rgb 0 0 255
+/-- Fully transparent (zero alpha). -/
+public def transparent : Color := .rgba 0 0 0 0
+
+private def hexDigit (upper : Bool) (n : Nat) : Char :=
+  if n < 10 then Char.ofNat ('0'.toNat + n)
+  else Char.ofNat ((if upper then 'A' else 'a').toNat + (n - 10))
+
+private def hexByte (upper : Bool) (b : UInt8) : String :=
+  let n := b.toNat
+  String.ofList [hexDigit upper (n / 16), hexDigit upper (n % 16)]
+
+/--
+Renders a color for CSS as lowercase hex: `#rrggbb` when fully opaque, otherwise `#rrggbbaa`. Using
+hex for both keeps one format and maps the alpha byte exactly, with no decimal rounding.
+-/
+public def css : Color → String
+  | .rgba r g b a =>
+    let rgb := "#" ++ hexByte false r ++ hexByte false g ++ hexByte false b
+    if a == 255 then rgb else rgb ++ hexByte false a
+
+/--
+Renders a color for TeX as six uppercase hex digits {lit}`RRGGBB`, suitable for xcolor's
+{lit}`\definecolor{…}{HTML}{…}`. The alpha channel is dropped, since {lit}`xcolor`'s {lit}`HTML`
+model is opaque RGB.
+-/
+public def tex : Color → String
+  | .rgba r g b _ => hexByte true r ++ hexByte true g ++ hexByte true b
+
+end Color
+
+private def hexValue (c : Char) : Option Nat :=
+  if c.isDigit then some (c.toNat - '0'.toNat)
+  else if 'a' ≤ c ∧ c ≤ 'f' then some (c.toNat - 'a'.toNat + 10)
+  else if 'A' ≤ c ∧ c ≤ 'F' then some (c.toNat - 'A'.toNat + 10)
+  else none
+
+/--
+Parses the hex digits of a color (no leading `#`) into RGBA byte channels. Accepts 3 digits
+({lit}`rgb`, each digit doubled, opaque), 6 digits ({lit}`rrggbb`, opaque), or 8 digits
+({lit}`rrggbbaa`).
+-/
+public def fromHexString (hex : String) : Except String (UInt8 × UInt8 × UInt8 × UInt8) := do
+  let digit (c : Char) : Except String Nat :=
+    match hexValue c with
+    | some v => pure v
+    | none => throw s!"'{c}' is not a hex digit"
+  let byte (hi lo : Char) : Except String UInt8 := do
+    return UInt8.ofNat ((← digit hi) * 16 + (← digit lo))
+  match hex.toList with
+  | [r, g, b] =>
+    -- Each digit is doubled: `c` becomes `0xcc`, i.e. `c * 17`.
+    return (UInt8.ofNat ((← digit r) * 17), UInt8.ofNat ((← digit g) * 17),
+            UInt8.ofNat ((← digit b) * 17), 255)
+  | [r1, r2, g1, g2, b1, b2] =>
+    return (← byte r1 r2, ← byte g1 g2, ← byte b1 b2, 255)
+  | [r1, r2, g1, g2, b1, b2, a1, a2] =>
+    return (← byte r1 r2, ← byte g1 g2, ← byte b1 b2, ← byte a1 a2)
+  | ds => throw s!"expected 3, 6, or 8 hex digits, got {ds.length}"
diff --git a/src/verso/Verso/Color/Syntax.lean b/src/verso/Verso/Color/Syntax.lean
new file mode 100644
index 000000000..eec0946d1
--- /dev/null
+++ b/src/verso/Verso/Color/Syntax.lean
@@ -0,0 +1,92 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+meta import Lean.Parser
+meta import Lean.Parser.Types
+public import Lean.Parser.Types
+public meta import Lean.Parser.Basic
+public import Lean.PrettyPrinter.Parenthesizer
+public import Lean.PrettyPrinter.Formatter
+public import Lean.Elab.Term
+meta import Lean.PrettyPrinter
+meta import Lean.Elab.Term
+public meta import Verso.Color.Basic
+public meta import Verso.Color.Widget
+
+namespace Verso
+
+public section
+
+open Lean Parser PrettyPrinter
+
+/-- The syntax node kind produced by the `colorHex` parser. -/
+meta def colorHexKind : SyntaxNodeKind := `Verso.colorHex
+
+private meta def isHexDigit (c : Char) : Bool :=
+  if c.isDigit then true
+  else if 'a' ≤ c ∧ c ≤ 'f' then true
+  else if 'A' ≤ c ∧ c ≤ 'F' then true
+  else false
+
+/--
+Parses a hexadecimal color: a `#` followed by the maximal run of hex digits (upper- or lowercase),
+terminated by the first non-hex character or end of input. The run length is checked by the
+elaborator, not the parser, in order to provide better error messages.
+-/
+private meta def colorHexFn : ParserFn := fun c s =>
+  let initStackSz := s.stackSize
+  let iniPos := s.pos
+  let curr := c.get iniPos
+  if curr != '#' then
+    s.mkErrorAt "'#' to begin a color literal" iniPos initStackSz
+  else
+    let s := s.next c iniPos
+    let s := takeWhileFn isHexDigit c s
+    mkNodeToken colorHexKind iniPos true c s
+
+/-- A parser for the `#`-prefixed hexadecimal section of a `color%` literal. -/
+meta def colorHex : Parser :=
+  withAntiquot (mkAntiquot "colorHex" colorHexKind) {
+    fn := colorHexFn
+    info := mkAtomicInfo "colorHex"
+  }
+
+@[combinator_parenthesizer colorHex]
+meta def colorHex.parenthesizer : Parenthesizer := Parenthesizer.visitToken
+@[combinator_formatter colorHex]
+meta def colorHex.formatter : Formatter := Formatter.visitAtom colorHexKind
+
+meta initialize register_parser_alias colorHex
+
+/-- The hex digits of a `colorHex` syntax, without the leading `#`. -/
+private meta def asHexString (stx : TSyntax colorHexKind) : String :=
+  let val := (stx.raw.ifNode (·.getArg 0) (fun _ => stx.raw)).getAtomVal
+  match val.toList with
+  | '#' :: rest => String.ofList rest
+  | cs => String.ofList cs
+
+/--
+A color literal: `color%#rgb`, `color%#rrggbb`, or `color%#rrggbbaa` (case-insensitive hex, no space
+before the `#`). It is an ordinary term, usable anywhere a `Color` is expected, including in
+structure-field defaults.
+-/
+syntax (name := colorLit) "color%" noWs colorHex : term
+
+open Elab Term in
+@[term_elab colorLit]
+meta def elabColorLit : TermElab := fun stx expectedType? => do
+  let hexStx := stx.getArg 1
+  let hex := asHexString ⟨hexStx⟩
+  let (r, g, b, a) ←
+    match fromHexString hex with
+    | .ok v => pure v
+    | .error msg => throwErrorAt hexStx msg
+  saveColorWidget (.rgba r g b a) stx
+  let lit (n : UInt8) : Term := ⟨Syntax.mkNumLit (toString n.toNat)⟩
+  elabTerm (← `(Verso.Color.rgba $(lit r) $(lit g) $(lit b) $(lit a))) expectedType?
+
+end
diff --git a/src/verso/Verso/Color/Types.lean b/src/verso/Verso/Color/Types.lean
new file mode 100644
index 000000000..80d8fed72
--- /dev/null
+++ b/src/verso/Verso/Color/Types.lean
@@ -0,0 +1,19 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+namespace Verso
+
+-- This is an inductive with a single `rgba` constructor rather than a structure so that other color
+-- models (such as wide-gamut `oklch`) can be added later. The byte channels give a canonical
+-- `DecidableEq`, so colors round-trip through hex exactly and themes, fonts, and assets deduplicate
+-- by value.
+/--
+A color in sRGB with an alpha channel, each channel a byte.
+-/
+public inductive Color where
+  | rgba (red green blue alpha : UInt8)
+deriving DecidableEq, Repr, Inhabited
diff --git a/src/verso/Verso/Color/Widget.lean b/src/verso/Verso/Color/Widget.lean
new file mode 100644
index 000000000..5931d3536
--- /dev/null
+++ b/src/verso/Verso/Color/Widget.lean
@@ -0,0 +1,34 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+public meta import Lean.Widget.UserWidget
+public meta import Verso.Color.Basic
+
+set_option linter.missingDocs true
+set_option doc.verso true
+
+/-!
+The InfoView preview widget for colors. The CSS form is computed in Lean and handed to the widget,
+so the JavaScript only has to draw the swatch.
+-/
+
+namespace Verso
+
+public section
+
+open Lean Widget
+
+/-- A read-only InfoView swatch that previews a color. -/
+@[widget_module]
+meta def colorWidget : Lean.Widget.Module where
+  javascript := include_str "color-swatch.js"
+
+/--
+Attaches the color-preview widget to {name}`stx`, rendering {name}`color` as CSS.
+-/
+meta def saveColorWidget (color : Color) (stx : Syntax) : CoreM Unit :=
+  savePanelWidgetInfo colorWidget.javascriptHash (pure (Json.mkObj [("css", .str color.css)])) stx
diff --git a/src/verso/Verso/Color/color-swatch.js b/src/verso/Verso/Color/color-swatch.js
new file mode 100644
index 000000000..e242c0a55
--- /dev/null
+++ b/src/verso/Verso/Color/color-swatch.js
@@ -0,0 +1,25 @@
+import * as React from "react";
+
+const e = React.createElement;
+
+// A read-only preview of a `color%` literal: a swatch filled with the color next to its CSS
+// rendering. The pre-rendered CSS string is supplied as `props.css` by the `colorLit` elaborator.
+export default function (props) {
+  const swatch = e("span", {
+    style: {
+      display: "inline-block",
+      width: "1.4em",
+      height: "1.4em",
+      borderRadius: "3px",
+      border: "1px solid rgba(0, 0, 0, 0.25)",
+      backgroundColor: props.css,
+      verticalAlign: "middle",
+    },
+  });
+  const label = e(
+    "code",
+    { style: { marginLeft: "0.5em", verticalAlign: "middle" } },
+    props.css,
+  );
+  return e("div", { style: { padding: "0.4em" } }, swatch, label);
+}
diff --git a/test-projects/literate-config/lake-manifest.json b/test-projects/literate-config/lake-manifest.json
index d03c6ee10..8ccd52764 100644
--- a/test-projects/literate-config/lake-manifest.json
+++ b/test-projects/literate-config/lake-manifest.json
@@ -1,66 +1,53 @@
-{
-  "version": "1.2.0",
-  "packagesDir": ".lake/packages",
-  "packages": [
-    {
-      "type": "path",
-      "scope": "",
-      "name": "verso",
-      "manifestFile": "lake-manifest.json",
-      "inherited": false,
-      "dir": "../..",
-      "configFile": "lakefile.lean"
-    },
-    {
-      "url": "https://github.com/leanprover/illuminate",
-      "type": "git",
-      "subDir": null,
-      "scope": "",
-      "rev": "99ada816d9929a51132d5b5dc4f43c51f16d67d8",
-      "name": "illuminate",
-      "manifestFile": "lake-manifest.json",
-      "inputRev": "main",
-      "inherited": true,
-      "configFile": "lakefile.lean"
-    },
-    {
-      "url": "https://github.com/leanprover-community/plausible",
-      "type": "git",
-      "subDir": null,
-      "scope": "",
-      "rev": "86210d4ad1b08b086d0bd638637a75246523dbb8",
-      "name": "plausible",
-      "manifestFile": "lake-manifest.json",
-      "inputRev": "main",
-      "inherited": true,
-      "configFile": "lakefile.toml"
-    },
-    {
-      "url": "https://github.com/acmepjz/md4lean",
-      "type": "git",
-      "subDir": null,
-      "scope": "",
-      "rev": "6a3fb240133bcb7e1a066fdc784b3fdc304e3fc5",
-      "name": "MD4Lean",
-      "manifestFile": "lake-manifest.json",
-      "inputRev": "main",
-      "inherited": true,
-      "configFile": "lakefile.lean"
-    },
-    {
-      "url": "https://github.com/leanprover/subverso",
-      "type": "git",
-      "subDir": null,
-      "scope": "",
-      "rev": "ce893b9042128037e2d3c0158b9567fab9fae268",
-      "name": "subverso",
-      "manifestFile": "lake-manifest.json",
-      "inputRev": "main",
-      "inherited": true,
-      "configFile": "lakefile.lean"
-    }
-  ],
-  "name": "«literate-config-test»",
-  "lakeDir": ".lake",
-  "fixedToolchain": false
-}
+{"version": "1.2.0",
+ "packagesDir": ".lake/packages",
+ "packages":
+ [{"type": "path",
+   "scope": "",
+   "name": "verso",
+   "manifestFile": "lake-manifest.json",
+   "inherited": false,
+   "dir": "../..",
+   "configFile": "lakefile.lean"},
+  {"url": "https://github.com/leanprover/illuminate",
+   "type": "git",
+   "subDir": null,
+   "scope": "",
+   "rev": "99ada816d9929a51132d5b5dc4f43c51f16d67d8",
+   "name": "illuminate",
+   "manifestFile": "lake-manifest.json",
+   "inputRev": "main",
+   "inherited": true,
+   "configFile": "lakefile.lean"},
+  {"url": "https://github.com/leanprover-community/plausible",
+   "type": "git",
+   "subDir": null,
+   "scope": "",
+   "rev": "a456461b368b71d2accd95234832cd9c174b5437",
+   "name": "plausible",
+   "manifestFile": "lake-manifest.json",
+   "inputRev": "main",
+   "inherited": true,
+   "configFile": "lakefile.toml"},
+  {"url": "https://github.com/acmepjz/md4lean",
+   "type": "git",
+   "subDir": null,
+   "scope": "",
+   "rev": "6a3fb240133bcb7e1a066fdc784b3fdc304e3fc5",
+   "name": "MD4Lean",
+   "manifestFile": "lake-manifest.json",
+   "inputRev": "main",
+   "inherited": true,
+   "configFile": "lakefile.lean"},
+  {"url": "https://github.com/leanprover/subverso",
+   "type": "git",
+   "subDir": null,
+   "scope": "",
+   "rev": "ce893b9042128037e2d3c0158b9567fab9fae268",
+   "name": "subverso",
+   "manifestFile": "lake-manifest.json",
+   "inputRev": "main",
+   "inherited": true,
+   "configFile": "lakefile.lean"}],
+ "name": "«literate-config-test»",
+ "lakeDir": ".lake",
+ "fixedToolchain": false}
diff --git a/test-projects/literate-multi-root/lake-manifest.json b/test-projects/literate-multi-root/lake-manifest.json
index 9c84043e5..f67a53e6a 100644
--- a/test-projects/literate-multi-root/lake-manifest.json
+++ b/test-projects/literate-multi-root/lake-manifest.json
@@ -1,66 +1,53 @@
-{
-  "version": "1.2.0",
-  "packagesDir": ".lake/packages",
-  "packages": [
-    {
-      "type": "path",
-      "scope": "",
-      "name": "verso",
-      "manifestFile": "lake-manifest.json",
-      "inherited": false,
-      "dir": "../..",
-      "configFile": "lakefile.lean"
-    },
-    {
-      "url": "https://github.com/leanprover/illuminate",
-      "type": "git",
-      "subDir": null,
-      "scope": "",
-      "rev": "99ada816d9929a51132d5b5dc4f43c51f16d67d8",
-      "name": "illuminate",
-      "manifestFile": "lake-manifest.json",
-      "inputRev": "main",
-      "inherited": true,
-      "configFile": "lakefile.lean"
-    },
-    {
-      "url": "https://github.com/leanprover-community/plausible",
-      "type": "git",
-      "subDir": null,
-      "scope": "",
-      "rev": "86210d4ad1b08b086d0bd638637a75246523dbb8",
-      "name": "plausible",
-      "manifestFile": "lake-manifest.json",
-      "inputRev": "main",
-      "inherited": true,
-      "configFile": "lakefile.toml"
-    },
-    {
-      "url": "https://github.com/acmepjz/md4lean",
-      "type": "git",
-      "subDir": null,
-      "scope": "",
-      "rev": "6a3fb240133bcb7e1a066fdc784b3fdc304e3fc5",
-      "name": "MD4Lean",
-      "manifestFile": "lake-manifest.json",
-      "inputRev": "main",
-      "inherited": true,
-      "configFile": "lakefile.lean"
-    },
-    {
-      "url": "https://github.com/leanprover/subverso",
-      "type": "git",
-      "subDir": null,
-      "scope": "",
-      "rev": "ce893b9042128037e2d3c0158b9567fab9fae268",
-      "name": "subverso",
-      "manifestFile": "lake-manifest.json",
-      "inputRev": "main",
-      "inherited": true,
-      "configFile": "lakefile.lean"
-    }
-  ],
-  "name": "«literate-multi-root-test»",
-  "lakeDir": ".lake",
-  "fixedToolchain": false
-}
+{"version": "1.2.0",
+ "packagesDir": ".lake/packages",
+ "packages":
+ [{"type": "path",
+   "scope": "",
+   "name": "verso",
+   "manifestFile": "lake-manifest.json",
+   "inherited": false,
+   "dir": "../..",
+   "configFile": "lakefile.lean"},
+  {"url": "https://github.com/leanprover/illuminate",
+   "type": "git",
+   "subDir": null,
+   "scope": "",
+   "rev": "99ada816d9929a51132d5b5dc4f43c51f16d67d8",
+   "name": "illuminate",
+   "manifestFile": "lake-manifest.json",
+   "inputRev": "main",
+   "inherited": true,
+   "configFile": "lakefile.lean"},
+  {"url": "https://github.com/leanprover-community/plausible",
+   "type": "git",
+   "subDir": null,
+   "scope": "",
+   "rev": "a456461b368b71d2accd95234832cd9c174b5437",
+   "name": "plausible",
+   "manifestFile": "lake-manifest.json",
+   "inputRev": "main",
+   "inherited": true,
+   "configFile": "lakefile.toml"},
+  {"url": "https://github.com/acmepjz/md4lean",
+   "type": "git",
+   "subDir": null,
+   "scope": "",
+   "rev": "6a3fb240133bcb7e1a066fdc784b3fdc304e3fc5",
+   "name": "MD4Lean",
+   "manifestFile": "lake-manifest.json",
+   "inputRev": "main",
+   "inherited": true,
+   "configFile": "lakefile.lean"},
+  {"url": "https://github.com/leanprover/subverso",
+   "type": "git",
+   "subDir": null,
+   "scope": "",
+   "rev": "ce893b9042128037e2d3c0158b9567fab9fae268",
+   "name": "subverso",
+   "manifestFile": "lake-manifest.json",
+   "inputRev": "main",
+   "inherited": true,
+   "configFile": "lakefile.lean"}],
+ "name": "«literate-multi-root-test»",
+ "lakeDir": ".lake",
+ "fixedToolchain": false}

From 147d1343d7e45783e8370062a4234d62ede3f889 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Fri, 29 May 2026 16:00:02 +0200
Subject: [PATCH 02/31] prettier

---
 src/verso/Verso/Color/color-swatch.js | 30 ++++++++++++---------------
 1 file changed, 13 insertions(+), 17 deletions(-)

diff --git a/src/verso/Verso/Color/color-swatch.js b/src/verso/Verso/Color/color-swatch.js
index e242c0a55..d14b307ce 100644
--- a/src/verso/Verso/Color/color-swatch.js
+++ b/src/verso/Verso/Color/color-swatch.js
@@ -5,21 +5,17 @@ const e = React.createElement;
 // A read-only preview of a `color%` literal: a swatch filled with the color next to its CSS
 // rendering. The pre-rendered CSS string is supplied as `props.css` by the `colorLit` elaborator.
 export default function (props) {
-  const swatch = e("span", {
-    style: {
-      display: "inline-block",
-      width: "1.4em",
-      height: "1.4em",
-      borderRadius: "3px",
-      border: "1px solid rgba(0, 0, 0, 0.25)",
-      backgroundColor: props.css,
-      verticalAlign: "middle",
-    },
-  });
-  const label = e(
-    "code",
-    { style: { marginLeft: "0.5em", verticalAlign: "middle" } },
-    props.css,
-  );
-  return e("div", { style: { padding: "0.4em" } }, swatch, label);
+    const swatch = e("span", {
+        style: {
+            display: "inline-block",
+            width: "1.4em",
+            height: "1.4em",
+            borderRadius: "3px",
+            border: "1px solid rgba(0, 0, 0, 0.25)",
+            backgroundColor: props.css,
+            verticalAlign: "middle",
+        },
+    });
+    const label = e("code", { style: { marginLeft: "0.5em", verticalAlign: "middle" } }, props.css);
+    return e("div", { style: { padding: "0.4em" } }, swatch, label);
 }

From 88336f85144823d161596516ea5ddab14d4e4c9d Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Fri, 29 May 2026 17:13:18 +0200
Subject: [PATCH 03/31] feat: accessibility checking color math

Implements the color mathematics needed for automatic color theme
accessibility checking (in particular, contrast and difference under
colorlindness simulation).
---
 src/tests/TestMain.lean               |   7 +
 src/tests/Tests.lean                  |   1 +
 src/tests/Tests/Arbitrary.lean        |  16 ++
 src/tests/Tests/ColorMath.lean        | 313 ++++++++++++++++++++++++++
 src/verso/Verso/Color.lean            |   1 +
 src/verso/Verso/Color/Math.lean       | 230 +++++++++++++++++++
 src/verso/Verso/Color/Syntax.lean     |  15 +-
 src/verso/Verso/Color/Types.lean      |   3 +
 src/verso/Verso/Color/Widget.lean     |  11 +-
 src/verso/Verso/Color/color-swatch.js |  54 ++++-
 10 files changed, 636 insertions(+), 15 deletions(-)
 create mode 100644 src/tests/Tests/ColorMath.lean
 create mode 100644 src/verso/Verso/Color/Math.lean

diff --git a/src/tests/TestMain.lean b/src/tests/TestMain.lean
index 56f73455b..118879c02 100644
--- a/src/tests/TestMain.lean
+++ b/src/tests/TestMain.lean
@@ -149,6 +149,12 @@ def testSerialization (_ : Config) : IO Unit := do
   if fails > 0 then
     throw <| IO.userError s!"{fails} serialization tests failed"
 
+def testColorMath (_ : Config) : IO Unit := do
+  IO.println "Running color math tests..."
+  let fails ← runColorMathTests
+  if fails > 0 then
+    throw <| IO.userError s!"{fails} color math tests failed"
+
 def testSearchJs (_ : Config) : IO Unit := do
   IO.println "Running search JS wire-format tests..."
   let fails ← Verso.Tests.SearchJs.runSearchJsTests
@@ -383,6 +389,7 @@ open Verso.Integration in
 def tests := [
   testBuildLog,
   testColor,
+  testColorMath,
   testSerialization,
   testSearchJs,
   testBlog,
diff --git a/src/tests/Tests.lean b/src/tests/Tests.lean
index f28bc799c..d41c95fd1 100644
--- a/src/tests/Tests.lean
+++ b/src/tests/Tests.lean
@@ -5,6 +5,7 @@ Author: David Thrane Christiansen
 -/
 import Tests.Basic
 import Tests.Color
+import Tests.ColorMath
 import Tests.Elab
 import Tests.GenericCode
 import Tests.Golden
diff --git a/src/tests/Tests/Arbitrary.lean b/src/tests/Tests/Arbitrary.lean
index bfe69e9a8..8e526decc 100644
--- a/src/tests/Tests/Arbitrary.lean
+++ b/src/tests/Tests/Arbitrary.lean
@@ -18,6 +18,7 @@ public meta import VersoManual.LicenseInfo
 public meta import VersoSearch
 public meta import VersoSearch.DomainSearch
 public meta import Verso.Output.Html
+public meta import Verso.Color.Types
 public meta import MultiVerso.Manifest
 public meta import VersoManual.Basic
 import all VersoManual.Basic
@@ -437,3 +438,18 @@ instance : Shrinkable System.FilePath where
     if let some parent := path.parent then
       parent :: (path.fileName.toList.flatMap shrink |>.map path.withFileName)
     else []
+
+instance : Arbitrary Verso.Color where
+  arbitrary := do
+    -- Bias the alpha channel: fully opaque (the common case) 60% of the time, fully transparent 5%,
+    -- and uniformly random the rest. A uniform alpha would almost never be exactly opaque.
+    let a ← frequency (pure 255) [(60, pure 255), (5, pure 0), (35, arbitrary)]
+    return .rgba (← arbitrary) (← arbitrary) (← arbitrary) a
+
+instance : Shrinkable Verso.Color where
+  shrink
+    | .rgba r g b a =>
+      (shrink r |>.map (Verso.Color.rgba · g b a)) ++
+      (shrink g |>.map (Verso.Color.rgba r · b a)) ++
+      (shrink b |>.map (Verso.Color.rgba r g · a)) ++
+      (shrink a |>.map (Verso.Color.rgba r g b ·))
diff --git a/src/tests/Tests/ColorMath.lean b/src/tests/Tests/ColorMath.lean
new file mode 100644
index 000000000..55c29afe1
--- /dev/null
+++ b/src/tests/Tests/ColorMath.lean
@@ -0,0 +1,313 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+public import Plausible
+public meta import Verso.Color
+import all Verso.Color.Math
+public meta import Tests.Arbitrary
+
+/-!
+Unit and property tests for the color math in `Verso.Color.Math`.
+-/
+
+open Plausible Gen Arbitrary Shrinkable
+open Verso Verso.Color
+
+meta section
+
+/-- Approximate float equality to a tolerance. -/
+def approx (tol a b : Float) : Bool := (a - b).abs ≤ tol
+
+/-- Whether two colors' channels are all within `tol` of each other. -/
+def channelsClose (tol : Nat) : Color → Color → Bool
+  | .rgba r1 g1 b1 a1, .rgba r2 g2 b2 a2 =>
+    let near (x y : UInt8) : Bool := (Int.ofNat x.toNat - Int.ofNat y.toNat).natAbs ≤ tol
+    near r1 r2 && near g1 g2 && near b1 b2 && near a1 a2
+
+instance : Arbitrary CVD where
+  arbitrary := Gen.elements [.protanopia, .deuteranopia, .tritanopia] (by simp)
+
+instance : Shrinkable CVD where
+  shrink _ := []
+
+/-! ## Unit tests on reference values -/
+
+-- Relative luminance of black is 0 and of white is 1, so their contrast ratio is the maximal 21.
+/-- info: (0.000000, 1.000000, 21.000000) -/
+#guard_msgs in
+#eval (relativeLuminance .black, relativeLuminance .white, contrastRatio .black .white)
+
+-- ΔE is zero for equal colors and large for black vs. white.
+/-- info: (0.000000, 100.000004) -/
+#guard_msgs in
+#eval (deltaE .black .black, deltaE .white .black)
+
+-- Dichromacy simulation leaves the gray axis unchanged.
+/-- info: (Verso.Color.rgba 128 128 128 255, Verso.Color.rgba 128 128 128 255, Verso.Color.rgba 128 128 128 255) -/
+#guard_msgs in
+#eval (dichromacy .protanopia .gray, dichromacy .deuteranopia .gray, dichromacy .tritanopia .gray)
+
+-- Red and green, far apart normally, collapse closer together under deuteranopia.
+/-- info: true -/
+#guard_msgs in
+#eval decide (deltaE (dichromacy .deuteranopia .red) (dichromacy .deuteranopia .green) < deltaE .red .green)
+
+/-! ## Property tests -/
+
+open scoped Plausible.Decorations in
+def testProp
+    (p : Prop) (cfg : Configuration := {})
+    (p' : Decorations.DecorationsOf p := by mk_decorations) [Testable p'] :
+    IO (TestResult p') :=
+  Testable.checkIO p' (cfg := cfg)
+
+/-- Relative luminance lies in [0, 1]. -/
+def testLuminanceRange := testProp <| ∀ (c : Color),
+  0.0 ≤ relativeLuminance c ∧ relativeLuminance c ≤ 1.000000001
+
+/-- Raises a channel by `d`, saturating at 255. -/
+private def raise (x d : UInt8) : UInt8 := UInt8.ofNat (Nat.min 255 (x.toNat + d.toNat))
+
+/-- Raising any channel never lowers the relative luminance. -/
+def testLuminanceMonotone := testProp <| ∀ (r g b d0 d1 d2 : UInt8),
+  relativeLuminance (.rgba r g b 255)
+    ≤ relativeLuminance (.rgba (raise r d0) (raise g d1) (raise b d2) 255) + 0.000000001
+
+/-- Contrast ratio is symmetric. -/
+def testContrastSymmetric := testProp <| ∀ (c d : Color),
+  approx 0.000000001 (contrastRatio c d) (contrastRatio d c)
+
+/-- Contrast ratio lies in [1, 21]. -/
+def testContrastRange := testProp <| ∀ (c d : Color),
+  0.999999999 ≤ contrastRatio c d ∧ contrastRatio c d ≤ 21.000000001
+
+/-- A color has contrast ratio 1 with itself. -/
+def testContrastSelf := testProp <| ∀ (c : Color),
+  approx 0.000000001 (contrastRatio c c) 1.0
+
+/-- ΔE is non-negative. -/
+def testDeltaENonneg := testProp <| ∀ (c d : Color), deltaE c d ≥ 0.0
+
+/-- ΔE is symmetric. -/
+def testDeltaESymmetric := testProp <| ∀ (c d : Color),
+  approx 0.0001 (deltaE c d) (deltaE d c)
+
+/-- ΔE is zero for equal colors. -/
+def testDeltaEZero := testProp <| ∀ (c : Color), approx 0.000001 (deltaE c c) 0.0
+
+/-- Dichromacy maps the gray axis to itself (within one quantization step). -/
+def testDichromacyGray := testProp <| ∀ (cvd : CVD) (v : UInt8),
+  channelsClose 1 (dichromacy cvd (.rgba v v v 255)) (.rgba v v v 255)
+
+/-- The alpha channel of a color. -/
+private def alphaOf : Color → UInt8
+  | .rgba _ _ _ a => a
+
+/--
+Dichromacy preserves the alpha channel.
+
+It is *not* idempotent on the quantized, gamut-clamped `Color`: clipping a channel to 0 or 255
+discards the exact projected point, so a second pass can drift. Idempotence holds only for the
+continuous linear-light projection.
+-/
+def testDichromacyAlphaPreserved := testProp <| ∀ (cvd : CVD) (c : Color),
+  alphaOf (dichromacy cvd c) == alphaOf c
+
+/-- Relative luminance ignores the alpha channel. -/
+def testLuminanceIgnoresAlpha := testProp <| ∀ (r g b a : UInt8),
+  relativeLuminance (.rgba r g b a) == relativeLuminance (.rgba r g b 255)
+
+/-- Contrast ratio ignores the alpha channel. -/
+def testContrastIgnoresAlpha := testProp <| ∀ (r1 g1 b1 a1 r2 g2 b2 a2 : UInt8),
+  contrastRatio (.rgba r1 g1 b1 a1) (.rgba r2 g2 b2 a2)
+    == contrastRatio (.rgba r1 g1 b1 255) (.rgba r2 g2 b2 255)
+
+/-- ΔE ignores the alpha channel. -/
+def testDeltaEIgnoresAlpha := testProp <| ∀ (r1 g1 b1 a1 r2 g2 b2 a2 : UInt8),
+  deltaE (.rgba r1 g1 b1 a1) (.rgba r2 g2 b2 a2)
+    == deltaE (.rgba r1 g1 b1 255) (.rgba r2 g2 b2 255)
+
+open Lean (Name)
+
+def colorMathTests : List (Name × (Σ p, IO <| TestResult p)) := [
+  (`testLuminanceRange, ⟨_, testLuminanceRange⟩),
+  (`testLuminanceMonotone, ⟨_, testLuminanceMonotone⟩),
+  (`testContrastSymmetric, ⟨_, testContrastSymmetric⟩),
+  (`testContrastRange, ⟨_, testContrastRange⟩),
+  (`testContrastSelf, ⟨_, testContrastSelf⟩),
+  (`testDeltaENonneg, ⟨_, testDeltaENonneg⟩),
+  (`testDeltaESymmetric, ⟨_, testDeltaESymmetric⟩),
+  (`testDeltaEZero, ⟨_, testDeltaEZero⟩),
+  (`testDichromacyGray, ⟨_, testDichromacyGray⟩),
+  (`testDichromacyAlphaPreserved, ⟨_, testDichromacyAlphaPreserved⟩),
+  (`testLuminanceIgnoresAlpha, ⟨_, testLuminanceIgnoresAlpha⟩),
+  (`testContrastIgnoresAlpha, ⟨_, testContrastIgnoresAlpha⟩),
+  (`testDeltaEIgnoresAlpha, ⟨_, testDeltaEIgnoresAlpha⟩),
+]
+
+public def runColorMathTests : IO Nat := do
+  let mut failures := 0
+  for (name, test) in colorMathTests do
+    IO.print s!"{name}: "
+    let res ← test.2
+    IO.println res
+    unless res matches .success .. do
+      failures := failures + 1
+  return failures
+
+/-!
+## Source-backed simulation cases
+
+`cvdReferenceVectors` are outputs of DaltonLens-Python's `Simulator_Brettel1997` (severity 1.0), the
+reference implementation that libDaltonLens is validated against. Each row is
+`(input, protanopia, deuteranopia, tritanopia)`. `dichromacy` is expected to match each within a
+couple of byte units: the small difference comes from libDaltonLens's matrix coefficients being
+rounded to five decimals, not from a different method. A large deviation would mean a transposed
+matrix, wrong half-plane sign, wrong gamma direction, or swapped channels.
+-/
+
+def cvdReferenceVectors : List (Color × Color × Color × Color) := [
+  (.rgba 0 0 0 255, .rgba 0 0 0 255, .rgba 0 0 0 255, .rgba 0 0 0 255),
+  (.rgba 255 255 255 255, .rgba 254 254 254 255, .rgba 254 254 254 255, .rgba 254 254 254 255),
+  (.rgba 128 128 128 255, .rgba 128 128 128 255, .rgba 128 128 128 255, .rgba 128 128 128 255),
+  (.rgba 255 0 0 255, .rgba 106 90 13 255, .rgba 163 138 0 255, .rgba 254 0 78 255),
+  (.rgba 0 128 0 255, .rgba 139 118 0 255, .rgba 120 103 17 255, .rgba 58 117 135 255),
+  (.rgba 0 0 255 255, .rgba 0 54 254 255, .rgba 0 86 254 255, .rgba 0 95 134 255),
+  (.rgba 255 255 0 255, .rgba 254 250 0 255, .rgba 254 242 21 255, .rgba 254 239 242 255),
+  (.rgba 0 255 255 255, .rgba 238 242 254 255, .rgba 209 223 254 255, .rgba 73 248 254 255),
+  (.rgba 255 0 255 255, .rgba 0 105 254 255, .rgba 101 160 251 255, .rgba 238 98 120 255),
+  (.rgba 29 3 65 255, .rgba 0 13 65 255, .rgba 0 23 64 255, .rgba 14 21 23 255),
+  (.rgba 220 20 60 255, .rgba 87 81 62 255, .rgba 139 121 49 255, .rgba 220 12 72 255),
+  (.rgba 0 128 255 255, .rgba 0 129 254 255, .rgba 0 132 254 255, .rgba 0 147 185 255),
+  (.rgba 217 163 130 255, .rgba 181 168 130 255, .rgba 191 176 128 255, .rgba 220 158 164 255),
+  (.rgba 69 78 10 255, .rgba 88 75 9 255, .rgba 84 71 12 255, .rgba 75 72 73 255),
+  (.rgba 19 4 44 255, .rgba 0 8 44 255, .rgba 0 15 43 255, .rgba 9 13 15 255),
+  (.rgba 208 166 233 255, .rgba 144 174 233 255, .rgba 164 185 231 255, .rgba 198 176 178 255),
+  (.rgba 128 155 248 255, .rgba 98 157 248 255, .rgba 107 160 247 255, .rgba 105 168 190 255),
+  (.rgba 186 161 139 255, .rgba 171 163 139 255, .rgba 175 165 138 255, .rgba 188 157 160 255),
+  (.rgba 143 239 71 255, .rgba 254 226 68 255, .rgba 237 207 80 255, .rgba 173 222 242 255),
+  (.rgba 208 171 0 255, .rgba 200 172 0 255, .rgba 202 173 0 255, .rgba 217 159 165 255),
+  (.rgba 100 219 141 255, .rgba 228 207 140 255, .rgba 204 189 144 255, .rgba 130 206 233 255),
+  (.rgba 8 195 186 255, .rgba 185 185 185 255, .rgba 162 169 187 255, .rgba 60 188 223 255),
+  (.rgba 216 44 22 255, .rgba 99 86 26 255, .rgba 142 121 0 255, .rgba 217 32 77 255),
+  (.rgba 220 5 138 255, .rgba 43 82 138 255, .rgba 124 126 133 255, .rgba 215 46 82 255),
+  (.rgba 20 76 123 255, .rgba 43 74 122 255, .rgba 38 73 123 255, .rgba 0 81 99 255),
+  (.rgba 108 103 7 255, .rgba 118 101 6 255, .rgba 116 99 9 255, .rgba 114 96 97 255),
+  (.rgba 1 31 2 255, .rgba 34 28 1 255, .rgba 28 23 3 255, .rgba 9 27 33 255),
+  (.rgba 171 134 165 255, .rgba 129 139 165 255, .rgba 141 147 164 255, .rgba 167 138 141 255),
+  (.rgba 65 157 195 255, .rgba 132 152 194 255, .rgba 119 144 195 255, .rgba 59 158 186 255),
+  (.rgba 98 117 255 255, .rgba 0 124 254 255, .rgba 0 134 254 255, .rgba 34 141 169 255),
+  (.rgba 206 251 97 255, .rgba 254 242 95 255, .rgba 254 229 102 255, .rgba 225 236 242 255),
+  (.rgba 175 243 166 255, .rgba 254 234 165 255, .rgba 237 220 168 255, .rgba 192 232 249 255),
+  (.rgba 215 176 180 255, .rgba 180 180 180 255, .rgba 190 187 179 255, .rgba 214 176 179 255),
+  (.rgba 99 224 34 255, .rgba 244 210 28 255, .rgba 218 189 51 255, .rgba 140 207 231 255),
+  (.rgba 148 184 216 255, .rgba 167 182 215 255, .rgba 162 179 216 255, .rgba 144 186 203 255),
+  (.rgba 134 96 79 255, .rgba 107 100 79 255, .rgba 115 106 77 255, .rgba 135 93 97 255),
+  (.rgba 108 124 184 255, .rgba 92 125 184 255, .rgba 96 127 183 255, .rgba 95 132 146 255),
+  (.rgba 227 18 239 255, .rgba 0 96 239 255, .rgba 82 145 236 255, .rgba 210 94 111 255),
+  (.rgba 136 91 172 255, .rgba 47 101 172 255, .rgba 82 114 171 255, .rgba 123 106 107 255),
+  (.rgba 146 65 82 255, .rgba 78 79 82 255, .rgba 101 95 79 255, .rgba 145 65 77 255),
+  (.rgba 184 152 129 255, .rgba 163 154 129 255, .rgba 169 159 128 255, .rgba 186 148 152 255),
+  (.rgba 86 194 100 255, .rgba 206 183 99 255, .rgba 184 166 104 255, .rgba 116 181 204 255),
+  (.rgba 84 227 67 255, .rgba 245 213 64 255, .rgba 217 190 77 255, .rgba 131 210 237 255),
+  (.rgba 58 182 159 255, .rgba 178 173 158 255, .rgba 157 158 160 255, .rgba 83 175 203 255),
+  (.rgba 12 21 96 255, .rgba 0 27 96 255, .rgba 0 34 95 255, .rgba 0 38 52 255),
+  (.rgba 213 102 201 255, .rgba 74 125 201 255, .rgba 129 152 198 255, .rgba 203 120 130 255),
+  (.rgba 81 61 202 255, .rgba 0 75 202 255, .rgba 0 92 201 255, .rgba 20 94 112 255),
+  (.rgba 224 20 14 255, .rgba 95 81 21 255, .rgba 144 122 0 255, .rgba 225 0 71 255),
+  (.rgba 171 86 146 255, .rgba 78 102 146 255, .rgba 112 121 144 255, .rgba 165 95 104 255),
+  (.rgba 38 220 115 255, .rgba 231 206 113 255, .rgba 202 184 120 255, .rgba 103 205 237 255),
+]
+
+/-- The largest per-channel difference between two colors (ignoring alpha). -/
+private def chanMaxDiff : Color → Color → Nat
+  | .rgba r1 g1 b1 _, .rgba r2 g2 b2 _ =>
+    let d (x y : UInt8) : Nat := (Int.ofNat x.toNat - Int.ofNat y.toNat).natAbs
+    Nat.max (d r1 r2) (Nat.max (d g1 g2) (d b1 b2))
+
+/--
+The greatest per-channel deviation of `dichromacy` from the DaltonLens reference, over all vectors
+and all three deficiencies. Pinned so a regression (or a larger deviation than the matrix rounding
+explains) fails the test.
+-/
+def cvdReferenceMaxDeviation : Nat :=
+  cvdReferenceVectors.foldl (init := 0) fun acc (c, p, de, t) =>
+    Nat.max acc <|
+      Nat.max (chanMaxDiff (dichromacy .protanopia c) p) <|
+        Nat.max (chanMaxDiff (dichromacy .deuteranopia c) de) (chanMaxDiff (dichromacy .tritanopia c) t)
+
+-- `dichromacy` matches the DaltonLens reference across all 50 vectors and all three deficiencies. The
+-- largest per-channel deviation is 7, for one tritanopia color (`rgba 81 61 202`) that sits near the
+-- half-plane boundary, where the hard plane switch and the 5-decimal-rounded matrices interact; the
+-- rest are within about 3. A transposed matrix, flipped half-plane sign, or wrong gamma direction
+-- would push this far higher.
+/-- info: 7 -/
+#guard_msgs in
+#eval cvdReferenceMaxDeviation
+
+/-! ## CIEDE2000 against Sharma's published Lab vectors
+
+`deltaE2000` (the CIELAB core of `deltaE`, reached via `import all`) is validated against the 34
+test pairs from Sharma, Wu & Dalal (2005), Table 1, the canonical data for checking a CIEDE2000
+implementation. These pairs deliberately exercise the hue-rotation and near-zero-chroma cases that
+catch transcription errors the broad invariants miss. Values via the reference implementation at
+https://github.com/gfiumara/CIEDE2000.
+-/
+
+def sharmaDeltaEVectors : List ((Float × Float × Float) × (Float × Float × Float) × Float) := [
+  ((50.0, 2.6772, -79.7751), (50.0, 0.0, -82.7485), 2.0425),
+  ((50.0, 3.1571, -77.2803), (50.0, 0.0, -82.7485), 2.8615),
+  ((50.0, 2.8361, -74.0200), (50.0, 0.0, -82.7485), 3.4412),
+  ((50.0, -1.3802, -84.2814), (50.0, 0.0, -82.7485), 1.0000),
+  ((50.0, -1.1848, -84.8006), (50.0, 0.0, -82.7485), 1.0000),
+  ((50.0, -0.9009, -85.5211), (50.0, 0.0, -82.7485), 1.0000),
+  ((50.0, 0.0, 0.0), (50.0, -1.0, 2.0), 2.3669),
+  ((50.0, -1.0, 2.0), (50.0, 0.0, 0.0), 2.3669),
+  ((50.0, 2.4900, -0.0010), (50.0, -2.4900, 0.0009), 7.1792),
+  ((50.0, 2.4900, -0.0010), (50.0, -2.4900, 0.0010), 7.1792),
+  ((50.0, 2.4900, -0.0010), (50.0, -2.4900, 0.0011), 7.2195),
+  ((50.0, 2.4900, -0.0010), (50.0, -2.4900, 0.0012), 7.2195),
+  ((50.0, -0.0010, 2.4900), (50.0, 0.0009, -2.4900), 4.8045),
+  ((50.0, -0.0010, 2.4900), (50.0, 0.0010, -2.4900), 4.8045),
+  ((50.0, -0.0010, 2.4900), (50.0, 0.0011, -2.4900), 4.7461),
+  ((50.0, 2.5000, 0.0), (50.0, 0.0, -2.5000), 4.3065),
+  ((50.0, 2.5000, 0.0), (73.0, 25.0, -18.0), 27.1492),
+  ((50.0, 2.5000, 0.0), (61.0, -5.0, 29.0), 22.8977),
+  ((50.0, 2.5000, 0.0), (56.0, -27.0, -3.0), 31.9030),
+  ((50.0, 2.5000, 0.0), (58.0, 24.0, 15.0), 19.4535),
+  ((50.0, 2.5000, 0.0), (50.0, 3.1736, 0.5854), 1.0000),
+  ((50.0, 2.5000, 0.0), (50.0, 3.2972, 0.0), 1.0000),
+  ((50.0, 2.5000, 0.0), (50.0, 1.8634, 0.5757), 1.0000),
+  ((50.0, 2.5000, 0.0), (50.0, 3.2592, 0.3350), 1.0000),
+  ((60.2574, -34.0099, 36.2677), (60.4626, -34.1751, 39.4387), 1.2644),
+  ((63.0109, -31.0961, -5.8663), (62.8187, -29.7946, -4.0864), 1.2630),
+  ((61.2901, 3.7196, -5.3901), (61.4292, 2.2480, -4.9620), 1.8731),
+  ((35.0831, -44.1164, 3.7933), (35.0232, -40.0716, 1.5901), 1.8645),
+  ((22.7233, 20.0904, -46.6940), (23.0331, 14.9730, -42.5619), 2.0373),
+  ((36.4612, 47.8580, 18.3852), (36.2715, 50.5065, 21.2231), 1.4146),
+  ((90.8027, -2.0831, 1.4410), (91.1528, -1.6435, 0.0447), 1.4441),
+  ((90.9257, -0.5406, -0.9208), (88.6381, -0.8985, -0.7239), 1.5381),
+  ((6.7747, -0.2908, -2.4247), (5.8714, -0.0985, -2.2286), 0.6377),
+  ((2.0776, 0.0795, -1.1350), (0.9033, -0.0636, -0.5514), 0.9082),
+]
+
+/--
+The greatest absolute deviation of `deltaE2000` from Sharma's published ΔE₀₀, over all 34 vectors.
+Sharma publishes four decimal places, so a correct implementation lands within rounding.
+-/
+def sharmaMaxDeviation : Float :=
+  sharmaDeltaEVectors.foldl (init := 0.0) fun acc (lab1, lab2, exp) =>
+    let (l1, a1, b1) := lab1
+    let (l2, a2, b2) := lab2
+    let d := (deltaE2000 l1 a1 b1 l2 a2 b2 - exp).abs
+    if acc < d then d else acc
+
+-- `deltaE2000` reproduces every Sharma reference value to within their published precision (four
+-- decimals), confirming the CIEDE2000 formula is transcribed correctly (including the tricky
+-- hue-rotation and near-zero-chroma cases).
+/-- info: true -/
+#guard_msgs in
+#eval decide (sharmaMaxDeviation < 0.0001)
diff --git a/src/verso/Verso/Color.lean b/src/verso/Verso/Color.lean
index 434913b12..17dd7a0f6 100644
--- a/src/verso/Verso/Color.lean
+++ b/src/verso/Verso/Color.lean
@@ -7,5 +7,6 @@ module
 
 public import Verso.Color.Types
 public import Verso.Color.Basic
+public import Verso.Color.Math
 public import Verso.Color.Widget
 public import Verso.Color.Syntax
diff --git a/src/verso/Verso/Color/Math.lean b/src/verso/Verso/Color/Math.lean
new file mode 100644
index 000000000..c25f6fe03
--- /dev/null
+++ b/src/verso/Verso/Color/Math.lean
@@ -0,0 +1,230 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+public import Verso.Color.Types
+
+set_option linter.missingDocs true
+set_option doc.verso true
+
+/-!
+Color math for accessibility checking, using the following:
+
+* Relative luminance and contrast ratio, from WCAG 2.1 ([relative
+  luminance](https://www.w3.org/TR/WCAG21/#dfn-relative-luminance), [contrast
+  ratio](https://www.w3.org/TR/WCAG21/#dfn-contrast-ratio)). A theme has to keep text readable
+  against its background, and the WCAG contrast ratio is the accepted way to measure that.
+
+* Color-vision-deficiency simulation, using the Brettel, Viénot & Mollon (1997) dichromacy method as
+  reproduced by [libDaltonLens](https://github.com/DaltonLens/libDaltonLens). Brettel 1997 is used
+  for all three dichromacies because the simpler Viénot 1999 single-matrix variant is inaccurate for
+  tritanopia. Simulating how a palette looks to a color-blind reader lets the checker catch colors
+  that collapse together and stop carrying meaning.
+
+* Color difference, using CIEDE2000 (Sharma, Wu & Dalal 2005, "The CIEDE2000 color-difference
+  formula"; [reference implementation and test
+  data](https://hajim.rochester.edu/ece/sites/gsharma/ciede2000/)). It is a perceptually uniform
+  measure of how distinct two colors look, used to decide whether two theme colors stay far enough
+  apart, including under the simulations above.
+
+All channels convert to {name}`Float` at the boundary (`/255`) and the math runs in {name}`Float`;
+the {name (full := Verso.Color)}`Color` type itself stays byte-exact.
+-/
+
+namespace Verso
+
+namespace Color
+
+private def pi : Float := 3.141592653589793
+
+private def fmin (a b : Float) : Float := if a < b then a else b
+private def fmax (a b : Float) : Float := if a > b then a else b
+private def clamp01 (v : Float) : Float := fmax 0.0 (fmin 1.0 v)
+
+private def channelToFloat (x : UInt8) : Float := x.toNat.toFloat / 255.0
+
+/-- Quantizes a {lit}`[0, 1]` channel back to a byte, rounding to nearest and clamping. -/
+private def floatToChannel (v : Float) : UInt8 :=
+  (Nat.min 255 ((clamp01 v * 255.0 + 0.5).toUInt64.toNat)).toUInt8
+
+/--
+The sRGB electro-optical transfer function: decodes a gamma-encoded {lit}`[0, 1]` channel to
+linear-light. WCAG 2.1 and the sRGB standard use the {lit}`0.04045` threshold and the
+{lit}`((c + 0.055) / 1.055) ^ 2.4` curve.
+-/
+private def srgbToLinear (c : Float) : Float :=
+  if c < 0.04045 then c / 12.92
+  else Float.pow ((c + 0.055) / 1.055) 2.4
+
+/--
+The inverse of {name}`srgbToLinear`: encodes a linear-light value back to a gamma-encoded
+{lit}`[0, 1]` channel (clamping out-of-gamut values).
+-/
+private def linearToSrgb (v : Float) : Float :=
+  if v ≤ 0.0 then 0.0
+  else if v ≥ 1.0 then 1.0
+  else if v < 0.0031308 then v * 12.92
+  else Float.pow v (1.0 / 2.4) * 1.055 - 0.055
+
+/--
+The WCAG 2.1 relative luminance of a color, in {lit}`[0, 1]`. The alpha channel is ignored;
+luminance is defined for opaque colors. Coefficients are the sRGB/Rec.709 luminance weights.
+-/
+public def relativeLuminance : Color → Float
+  | .rgba r g b _ =>
+    let rl := srgbToLinear (channelToFloat r)
+    let gl := srgbToLinear (channelToFloat g)
+    let bl := srgbToLinear (channelToFloat b)
+    0.2126 * rl + 0.7152 * gl + 0.0722 * bl
+
+/--
+The WCAG 2.1 contrast ratio between two colors, in {lit}`[1, 21]`. The luminances are ordered by
+max/min, so the ratio is symmetric in its arguments.
+-/
+public def contrastRatio (c1 c2 : Color) : Float :=
+  let l1 := relativeLuminance c1
+  let l2 := relativeLuminance c2
+  (fmax l1 l2 + 0.05) / (fmin l1 l2 + 0.05)
+
+/-- A type of color vision deficiency (dichromacy). -/
+public inductive CVD where
+  | protanopia
+  | deuteranopia
+  | tritanopia
+deriving DecidableEq, Repr
+
+/-- A row-major 3x3 matrix in linear RGB. -/
+private abbrev Mat3 := Float × Float × Float × Float × Float × Float × Float × Float × Float
+
+private def applyMat3 (m : Mat3) (r g b : Float) : Float × Float × Float :=
+  let (m00, m01, m02, m10, m11, m12, m20, m21, m22) := m
+  (m00 * r + m01 * g + m02 * b, m10 * r + m11 * g + m12 * b, m20 * r + m21 * g + m22 * b)
+
+/--
+The Brettel, Viénot & Mollon (1997) simulation parameters for a dichromacy: two linear-RGB matrices,
+one per half-plane of the dichromat's reduced gamut, and the separation plane normal (also in linear
+RGB) that selects between them. Each matrix's rows sum to one, so the gray axis is preserved. Values
+from libDaltonLens (https://github.com/DaltonLens/libDaltonLens).
+-/
+private def brettelParams : CVD → Mat3 × Mat3 × (Float × Float × Float)
+  | .protanopia =>
+    ((0.14980, 1.19548, -0.34528, 0.10764, 0.84864, 0.04372, 0.00384, -0.00540, 1.00156),
+     (0.14570, 1.16172, -0.30742, 0.10816, 0.85291, 0.03892, 0.00386, -0.00524, 1.00139),
+     (0.00048, 0.00393, -0.00441))
+  | .deuteranopia =>
+    ((0.36477, 0.86381, -0.22858, 0.26294, 0.64245, 0.09462, -0.02006, 0.02728, 0.99278),
+     (0.37298, 0.88166, -0.25464, 0.25954, 0.63506, 0.10540, -0.01980, 0.02784, 0.99196),
+     (-0.00281, -0.00611, 0.00892))
+  | .tritanopia =>
+    ((1.01277, 0.13548, -0.14826, -0.01243, 0.86812, 0.14431, 0.07589, 0.80500, 0.11911),
+     (0.93678, 0.18979, -0.12657, 0.06154, 0.81526, 0.12320, -0.37562, 1.12767, 0.24796),
+     (0.03901, -0.02788, -0.01113))
+
+/--
+Simulates how a color appears to someone with the given color vision deficiency, using the Brettel
+1997 method: decode sRGB to linear light, pick the half-plane matrix whose side of the separation
+plane the color is on, apply it, then re-encode and quantize.
+-/
+public def dichromacy (cvd : CVD) : Color → Color
+  | .rgba r g b a =>
+    let rl := srgbToLinear (channelToFloat r)
+    let gl := srgbToLinear (channelToFloat g)
+    let bl := srgbToLinear (channelToFloat b)
+    let (plane1, plane2, n0, n1, n2) := brettelParams cvd
+    let m := if rl * n0 + gl * n1 + bl * n2 ≥ 0.0 then plane1 else plane2
+    let (rl', gl', bl') := applyMat3 m rl gl bl
+    .rgba (floatToChannel (linearToSrgb rl')) (floatToChannel (linearToSrgb gl'))
+      (floatToChannel (linearToSrgb bl')) a
+
+/-! # CIELAB color difference (CIEDE2000) -/
+
+/--
+Converts a color to CIELAB ({lit}`L*`, {lit}`a*`, {lit}`b*`) under the D65 white point, ignoring
+alpha.
+-/
+private def toLab : Color → Float × Float × Float
+  | .rgba r g b _ =>
+    -- sRGB → linear → CIE XYZ (D65), the standard sRGB matrix.
+    let rl := srgbToLinear (channelToFloat r)
+    let gl := srgbToLinear (channelToFloat g)
+    let bl := srgbToLinear (channelToFloat b)
+    let x := 0.4124564 * rl + 0.3575761 * gl + 0.1804375 * bl
+    let y := 0.2126729 * rl + 0.7151522 * gl + 0.0721750 * bl
+    let z := 0.0193339 * rl + 0.1191920 * gl + 0.9503041 * bl
+    -- XYZ → L*a*b* with the D65 reference white.
+    let f := fun t =>
+      if t > 0.008856451679035631 then Float.pow t (1.0 / 3.0)
+      else 7.787037037037035 * t + 16.0 / 116.0
+    let fx := f (x / 0.95047)
+    let fy := f (y / 1.00000)
+    let fz := f (z / 1.08883)
+    (116.0 * fy - 16.0, 500.0 * (fx - fy), 200.0 * (fy - fz))
+
+/--
+The CIEDE2000 color difference ΔE₀₀ between two CIELAB colors, each given as {lit}`L*`, {lit}`a*`,
+{lit}`b*`. Non-negative, symmetric, and zero for equal inputs. Implements the formulation of Sharma,
+Wu & Dalal (2005), "The CIEDE2000 color-difference formula", with `kL = kC = kH = 1`. Factored out
+of the color-level difference so it can be validated directly against Sharma's published Lab test
+vectors (the test suite reaches it through `import all`).
+-/
+private def deltaE2000 (l1 a1 b1 l2 a2 b2 : Float) : Float := Id.run do
+  let rad := fun d => d * pi / 180.0
+  let deg := fun r => r * 180.0 / pi
+  -- atan2 in degrees, in [0, 360).
+  let atan2deg := fun y x =>
+    let a := deg (Float.atan2 y x)
+    if a < 0.0 then a + 360.0 else a
+  let cosd := fun d => Float.cos (rad d)
+  let sind := fun d => Float.sin (rad d)
+  let pow7 := fun (t : Float) => Float.pow t 7.0
+  let c25_7 := pow7 25.0
+  let cstar1 := Float.sqrt (a1 * a1 + b1 * b1)
+  let cstar2 := Float.sqrt (a2 * a2 + b2 * b2)
+  let cbar := (cstar1 + cstar2) / 2.0
+  let g := 0.5 * (1.0 - Float.sqrt (pow7 cbar / (pow7 cbar + c25_7)))
+  let a1' := (1.0 + g) * a1
+  let a2' := (1.0 + g) * a2
+  let c1' := Float.sqrt (a1' * a1' + b1 * b1)
+  let c2' := Float.sqrt (a2' * a2' + b2 * b2)
+  let h1' := if a1' == 0.0 && b1 == 0.0 then 0.0 else atan2deg b1 a1'
+  let h2' := if a2' == 0.0 && b2 == 0.0 then 0.0 else atan2deg b2 a2'
+  let dL' := l2 - l1
+  let dC' := c2' - c1'
+  let dh' :=
+    if c1' * c2' == 0.0 then 0.0
+    else if (h2' - h1') > 180.0 then h2' - h1' - 360.0
+    else if (h2' - h1') < -180.0 then h2' - h1' + 360.0
+    else h2' - h1'
+  let dH' := 2.0 * Float.sqrt (c1' * c2') * sind (dh' / 2.0)
+  let lbar' := (l1 + l2) / 2.0
+  let cbar' := (c1' + c2') / 2.0
+  let hbar' :=
+    if c1' * c2' == 0.0 then h1' + h2'
+    else if (fmax h1' h2' - fmin h1' h2') ≤ 180.0 then (h1' + h2') / 2.0
+    else if (h1' + h2') < 360.0 then (h1' + h2' + 360.0) / 2.0
+    else (h1' + h2' - 360.0) / 2.0
+  let t := 1.0 - 0.17 * cosd (hbar' - 30.0) + 0.24 * cosd (2.0 * hbar')
+    + 0.32 * cosd (3.0 * hbar' + 6.0) - 0.20 * cosd (4.0 * hbar' - 63.0)
+  let dtheta := 30.0 * Float.exp (-(((hbar' - 275.0) / 25.0) * ((hbar' - 275.0) / 25.0)))
+  let rc := 2.0 * Float.sqrt (pow7 cbar' / (pow7 cbar' + c25_7))
+  let sl := 1.0 + (0.015 * (lbar' - 50.0) * (lbar' - 50.0))
+    / Float.sqrt (20.0 + (lbar' - 50.0) * (lbar' - 50.0))
+  let sc := 1.0 + 0.045 * cbar'
+  let sh := 1.0 + 0.015 * cbar' * t
+  let rt := -(sind (2.0 * dtheta)) * rc
+  let termL := dL' / sl
+  let termC := dC' / sc
+  let termH := dH' / sh
+  return Float.sqrt (fmax 0.0 (termL * termL + termC * termC + termH * termH + rt * termC * termH))
+
+/--
+The CIEDE2000 color difference ΔE₀₀ between two colors, each first converted to CIELAB under the D65
+white point. Non-negative, symmetric, and zero for equal colors.
+-/
+public def deltaE (c1 c2 : Color) : Float :=
+  let (l1, a1, b1) := toLab c1
+  let (l2, a2, b2) := toLab c2
+  deltaE2000 l1 a1 b1 l2 a2 b2
diff --git a/src/verso/Verso/Color/Syntax.lean b/src/verso/Verso/Color/Syntax.lean
index eec0946d1..713c71af6 100644
--- a/src/verso/Verso/Color/Syntax.lean
+++ b/src/verso/Verso/Color/Syntax.lean
@@ -17,13 +17,16 @@ meta import Lean.Elab.Term
 public meta import Verso.Color.Basic
 public meta import Verso.Color.Widget
 
+set_option linter.missingDocs true
+set_option doc.verso true
+
 namespace Verso
 
 public section
 
 open Lean Parser PrettyPrinter
 
-/-- The syntax node kind produced by the `colorHex` parser. -/
+/-- The syntax node kind for the hexadecimal body of a `color%` literal. -/
 meta def colorHexKind : SyntaxNodeKind := `Verso.colorHex
 
 private meta def isHexDigit (c : Char) : Bool :=
@@ -55,14 +58,16 @@ meta def colorHex : Parser :=
     info := mkAtomicInfo "colorHex"
   }
 
+/-- Parenthesizer for {name}`colorHex`, which prints as a single token. -/
 @[combinator_parenthesizer colorHex]
 meta def colorHex.parenthesizer : Parenthesizer := Parenthesizer.visitToken
+/-- Formatter for {name}`colorHex`, which prints as a single token. -/
 @[combinator_formatter colorHex]
 meta def colorHex.formatter : Formatter := Formatter.visitAtom colorHexKind
 
 meta initialize register_parser_alias colorHex
 
-/-- The hex digits of a `colorHex` syntax, without the leading `#`. -/
+/-- The hex digits of a {name}`colorHex` syntax, without the leading `#`. -/
 private meta def asHexString (stx : TSyntax colorHexKind) : String :=
   let val := (stx.raw.ifNode (·.getArg 0) (fun _ => stx.raw)).getAtomVal
   match val.toList with
@@ -71,12 +76,14 @@ private meta def asHexString (stx : TSyntax colorHexKind) : String :=
 
 /--
 A color literal: `color%#rgb`, `color%#rrggbb`, or `color%#rrggbbaa` (case-insensitive hex, no space
-before the `#`). It is an ordinary term, usable anywhere a `Color` is expected, including in
-structure-field defaults.
+before the `#`). It is an ordinary term, usable anywhere a {name (full := Verso.Color)}`Color` is
+expected, including in structure-field defaults.
 -/
 syntax (name := colorLit) "color%" noWs colorHex : term
 
 open Elab Term in
+/-- Elaborates a {lit}`color%` literal to a {name (full := Verso.Color)}`Color` and attaches the
+preview widget. -/
 @[term_elab colorLit]
 meta def elabColorLit : TermElab := fun stx expectedType? => do
   let hexStx := stx.getArg 1
diff --git a/src/verso/Verso/Color/Types.lean b/src/verso/Verso/Color/Types.lean
index 80d8fed72..10ae38417 100644
--- a/src/verso/Verso/Color/Types.lean
+++ b/src/verso/Verso/Color/Types.lean
@@ -5,6 +5,9 @@ Author: David Thrane Christiansen
 -/
 module
 
+set_option linter.missingDocs true
+set_option doc.verso true
+
 namespace Verso
 
 -- This is an inductive with a single `rgba` constructor rather than a structure so that other color
diff --git a/src/verso/Verso/Color/Widget.lean b/src/verso/Verso/Color/Widget.lean
index 5931d3536..28c880903 100644
--- a/src/verso/Verso/Color/Widget.lean
+++ b/src/verso/Verso/Color/Widget.lean
@@ -7,6 +7,7 @@ module
 
 public meta import Lean.Widget.UserWidget
 public meta import Verso.Color.Basic
+public meta import Verso.Color.Math
 
 set_option linter.missingDocs true
 set_option doc.verso true
@@ -28,7 +29,13 @@ meta def colorWidget : Lean.Widget.Module where
   javascript := include_str "color-swatch.js"
 
 /--
-Attaches the color-preview widget to {name}`stx`, rendering {name}`color` as CSS.
+Attaches the color-preview widget to {name}`stx`. The widget shows {name}`color` together with how
+it appears under each of the three dichromacies, all rendered to CSS in Lean.
 -/
 meta def saveColorWidget (color : Color) (stx : Syntax) : CoreM Unit :=
-  savePanelWidgetInfo colorWidget.javascriptHash (pure (Json.mkObj [("css", .str color.css)])) stx
+  let props := Json.mkObj [
+    ("css", .str color.css),
+    ("protanopia", .str (Color.dichromacy .protanopia color).css),
+    ("deuteranopia", .str (Color.dichromacy .deuteranopia color).css),
+    ("tritanopia", .str (Color.dichromacy .tritanopia color).css)]
+  savePanelWidgetInfo colorWidget.javascriptHash (pure props) stx
diff --git a/src/verso/Verso/Color/color-swatch.js b/src/verso/Verso/Color/color-swatch.js
index d14b307ce..ef9928ad2 100644
--- a/src/verso/Verso/Color/color-swatch.js
+++ b/src/verso/Verso/Color/color-swatch.js
@@ -2,20 +2,56 @@ import * as React from "react";
 
 const e = React.createElement;
 
-// A read-only preview of a `color%` literal: a swatch filled with the color next to its CSS
-// rendering. The pre-rendered CSS string is supplied as `props.css` by the `colorLit` elaborator.
-export default function (props) {
-    const swatch = e("span", {
+function swatch(css, size) {
+    return e("span", {
         style: {
             display: "inline-block",
-            width: "1.4em",
-            height: "1.4em",
+            width: size,
+            height: size,
             borderRadius: "3px",
             border: "1px solid rgba(0, 0, 0, 0.25)",
-            backgroundColor: props.css,
+            backgroundColor: css,
             verticalAlign: "middle",
         },
     });
-    const label = e("code", { style: { marginLeft: "0.5em", verticalAlign: "middle" } }, props.css);
-    return e("div", { style: { padding: "0.4em" } }, swatch, label);
+}
+
+function cvdRow(label, css) {
+    return e(
+        "div",
+        { style: { display: "flex", alignItems: "center", gap: "0.4em", padding: "0.1em 0.4em" } },
+        swatch(css, "1em"),
+        e("span", { style: { fontSize: "0.85em" } }, label),
+        e("code", { style: { fontSize: "0.8em", opacity: 0.7 } }, css),
+    );
+}
+
+// A read-only preview of a `color%` literal: the color itself, plus how it looks under each of the
+// three dichromacies. All CSS strings are pre-rendered by the `colorLit` elaborator.
+export default function (props) {
+    const main = e(
+        "div",
+        { style: { padding: "0.4em" } },
+        swatch(props.css, "1.4em"),
+        e("code", { style: { marginLeft: "0.5em", verticalAlign: "middle" } }, props.css),
+    );
+    const cvd = e(
+        "div",
+        {
+            style: {
+                borderTop: "1px solid rgba(0, 0, 0, 0.1)",
+                marginTop: "0.3em",
+                paddingTop: "0.2em",
+            },
+        },
+        e(
+            "div",
+            { style: { fontSize: "0.75em", opacity: 0.6, padding: "0 0.4em 0.1em" } },
+            "Color vision deficiency",
+        ),
+        cvdRow("Protanopia", props.protanopia),
+        cvdRow("Deuteranopia", props.deuteranopia),
+        cvdRow("Tritanopia", props.tritanopia),
+    );
+    return e("div", {}, main, cvd);
 }

From aef96d772b094b472b895e4439dbe2bd5b9adb71 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Fri, 29 May 2026 20:32:58 +0200
Subject: [PATCH 04/31] feat: accessibility test core logic

Adds the core logic for accessibility calculations.
---
 src/tests/TestMain.lean                  |   7 ++
 src/tests/Tests.lean                     |   1 +
 src/tests/Tests/ColorAccessibility.lean  | 106 +++++++++++++++++++
 src/verso/Verso/Color.lean               |   1 +
 src/verso/Verso/Color/Accessibility.lean | 127 +++++++++++++++++++++++
 5 files changed, 242 insertions(+)
 create mode 100644 src/tests/Tests/ColorAccessibility.lean
 create mode 100644 src/verso/Verso/Color/Accessibility.lean

diff --git a/src/tests/TestMain.lean b/src/tests/TestMain.lean
index 118879c02..42452a3dd 100644
--- a/src/tests/TestMain.lean
+++ b/src/tests/TestMain.lean
@@ -155,6 +155,12 @@ def testColorMath (_ : Config) : IO Unit := do
   if fails > 0 then
     throw <| IO.userError s!"{fails} color math tests failed"
 
+def testColorAccessibility (_ : Config) : IO Unit := do
+  IO.println "Running color accessibility tests..."
+  let fails ← runColorAccessibilityTests
+  if fails > 0 then
+    throw <| IO.userError s!"{fails} color accessibility tests failed"
+
 def testSearchJs (_ : Config) : IO Unit := do
   IO.println "Running search JS wire-format tests..."
   let fails ← Verso.Tests.SearchJs.runSearchJsTests
@@ -390,6 +396,7 @@ def tests := [
   testBuildLog,
   testColor,
   testColorMath,
+  testColorAccessibility,
   testSerialization,
   testSearchJs,
   testBlog,
diff --git a/src/tests/Tests.lean b/src/tests/Tests.lean
index d41c95fd1..5fadb14d4 100644
--- a/src/tests/Tests.lean
+++ b/src/tests/Tests.lean
@@ -5,6 +5,7 @@ Author: David Thrane Christiansen
 -/
 import Tests.Basic
 import Tests.Color
+import Tests.ColorAccessibility
 import Tests.ColorMath
 import Tests.Elab
 import Tests.GenericCode
diff --git a/src/tests/Tests/ColorAccessibility.lean b/src/tests/Tests/ColorAccessibility.lean
new file mode 100644
index 000000000..62c5ebc1a
--- /dev/null
+++ b/src/tests/Tests/ColorAccessibility.lean
@@ -0,0 +1,106 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+public import Plausible
+public meta import Verso.Color
+public meta import Tests.Arbitrary
+
+/-!
+Unit and property tests for the accessibility predicates and checks in `Verso.Color.Accessibility`.
+-/
+
+open Plausible Gen Arbitrary Shrinkable
+open Verso Verso.Color
+
+meta section
+
+/-- The Okabe-Ito colorblind-safe palette, used to validate the distinguishability threshold. -/
+def okabeIto : Array (String × Color) := #[
+  ("black", color%#000000),
+  ("orange", color%#e69f00),
+  ("sky blue", color%#56b4e9),
+  ("bluish green", color%#009e73),
+  ("yellow", color%#f0e442),
+  ("blue", color%#0072b2),
+  ("vermillion", color%#d55e00),
+  ("reddish purple", color%#cc79a7),
+]
+
+/-! ## Unit tests on curated palettes -/
+
+-- A high-contrast pair (black on white) passes the text contrast check.
+/-- info: true -/
+#guard_msgs in
+#eval (contrastIssues textContrastThreshold "black on white" .black .white).isEmpty
+
+-- A low-contrast pair (gray on white, ratio ≈ 3.95) fails the text contrast check.
+/-- info: false -/
+#guard_msgs in
+#eval (contrastIssues textContrastThreshold "gray on white" .gray .white).isEmpty
+
+-- A nearly-opaque (99%) black composited over white is essentially black, so it passes easily.
+/-- info: true -/
+#guard_msgs in
+#eval (contrastIssues textContrastThreshold "99% black on white" (color%#000000fc) .white).isEmpty
+
+-- A half-transparent black over white composites to mid-gray, which fails the text threshold.
+/-- info: false -/
+#guard_msgs in
+#eval (contrastIssues textContrastThreshold "50% black on white" (color%#00000080) .white).isEmpty
+
+-- A translucent background cannot be contrast-checked: the effective backdrop is unknown.
+/-- info: false -/
+#guard_msgs in
+#eval (contrastIssues textContrastThreshold "black on translucent" .black (color%#ffffff80)).isEmpty
+
+-- A red and a green of matched lightness collapse together under deuteranopia (ΔE ≈ 2.1).
+/-- info: false -/
+#guard_msgs in
+#eval (colorblindIssues distinguishableThreshold #[("red", color%#e60000), ("green", color%#00a000)]).isEmpty
+
+-- Okabe-Ito blue and orange stay distinct under every dichromacy.
+/-- info: true -/
+#guard_msgs in
+#eval (colorblindIssues distinguishableThreshold #[("blue", color%#0072b2), ("orange", color%#e69f00)]).isEmpty
+
+-- The whole colorblind-safe Okabe-Ito palette passes the distinguishability check.
+/-- info: true -/
+#guard_msgs in
+#eval (colorblindIssues distinguishableThreshold okabeIto).isEmpty
+
+/-! ## Property tests -/
+
+open scoped Plausible.Decorations in
+def testProp
+    (p : Prop) (cfg : Configuration := {})
+    (p' : Decorations.DecorationsOf p := by mk_decorations) [Testable p'] :
+    IO (TestResult p') :=
+  Testable.checkIO p' (cfg := cfg)
+
+/-- Contrast is monotone in the threshold: passing at 4.5 implies passing at 3.0. -/
+def testContrastMonotone := testProp <| ∀ (fg bg : Color),
+  !meetsContrast 4.5 fg bg || meetsContrast 3.0 fg bg
+
+/-- When the contrast check reports no problem, the composited foreground meets the contrast. -/
+def testNoContrastIssueMeansMeets := testProp <| ∀ (fg bg : Color),
+  !(contrastIssues 4.5 "pair" fg bg).isEmpty || meetsContrast 4.5 (over fg bg) bg
+
+open Lean (Name)
+
+def colorAccessibilityTests : List (Name × (Σ p, IO <| TestResult p)) := [
+  (`testContrastMonotone, ⟨_, testContrastMonotone⟩),
+  (`testNoContrastIssueMeansMeets, ⟨_, testNoContrastIssueMeansMeets⟩),
+]
+
+public def runColorAccessibilityTests : IO Nat := do
+  let mut failures := 0
+  for (name, test) in colorAccessibilityTests do
+    IO.print s!"{name}: "
+    let res ← test.2
+    IO.println res
+    unless res matches .success .. do
+      failures := failures + 1
+  return failures
diff --git a/src/verso/Verso/Color.lean b/src/verso/Verso/Color.lean
index 17dd7a0f6..0b3dfe7b5 100644
--- a/src/verso/Verso/Color.lean
+++ b/src/verso/Verso/Color.lean
@@ -8,5 +8,6 @@ module
 public import Verso.Color.Types
 public import Verso.Color.Basic
 public import Verso.Color.Math
+public import Verso.Color.Accessibility
 public import Verso.Color.Widget
 public import Verso.Color.Syntax
diff --git a/src/verso/Verso/Color/Accessibility.lean b/src/verso/Verso/Color/Accessibility.lean
new file mode 100644
index 000000000..70fa21000
--- /dev/null
+++ b/src/verso/Verso/Color/Accessibility.lean
@@ -0,0 +1,127 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+public import Verso.Color.Types
+public import Verso.Color.Math
+
+set_option linter.missingDocs true
+set_option doc.verso true
+
+/-!
+This module contains genre-neutral accessibility predicates and checks built on the color math:
+
+ * WCAG contrast
+
+ * CIEDE2000 distinguishability (including under simulated color vision deficiency)
+
+-/
+
+namespace Verso
+
+namespace Color
+
+/-- The kind of accessibility problem found, so a caller can route each to its own severity. -/
+public inductive IssueKind where
+  | contrast
+  | colorblind
+deriving DecidableEq, Repr
+
+/--
+An accessibility problem found while checking a set of colors. It carries no severity; the caller
+maps {name}`IssueKind` to a severity. {lit}`offending` lists the colors involved, for error
+messages.
+-/
+public structure Issue where
+  /-- Whether this is a contrast or a color-vision-deficiency problem. -/
+  kind : IssueKind
+  /-- A human-readable description of the problem. -/
+  message : String
+  /-- The colors involved, for inclusion in error messages. -/
+  offending : Array Color := #[]
+
+/-- The WCAG AA contrast threshold for normal-size text. -/
+public def textContrastThreshold : Float := 4.5
+
+/-- The WCAG AA contrast threshold for large text and user-interface components. -/
+public def largeContrastThreshold : Float := 3.0
+
+/--
+The CIEDE2000 ΔE above which two colors count as distinguishable. Set in the "clearly perceptible"
+range: high enough to be a real difference, low enough not to flag the colorblind-safe Okabe-Ito
+palette (which stays above it under all three dichromacies).
+-/
+public def distinguishableThreshold : Float := 5.0
+
+/-- Whether {lit}`fg` on {lit}`bg` meets the given WCAG contrast ratio. -/
+public def meetsContrast (threshold : Float) (fg bg : Color) : Bool :=
+  contrastRatio fg bg ≥ threshold
+
+/-- Whether two colors differ by at least {lit}`threshold` in CIEDE2000 ΔE. -/
+public def distinguishable? (threshold : Float) (c1 c2 : Color) : Bool :=
+  deltaE c1 c2 ≥ threshold
+
+/-- Whether a color is fully opaque. Contrast can only be judged for opaque colors. -/
+public def isOpaque : Color → Bool
+  | .rgba _ _ _ a => a == 255
+
+/--
+Composites {lit}`fg` over {lit}`bg` using {lit}`fg`'s alpha (straight alpha in sRGB, matching how a
+browser paints translucent content on a solid background). The result is opaque; the background's
+own alpha is ignored.
+-/
+public def over (fg bg : Color) : Color :=
+  match fg, bg with
+  | .rgba rf gf bf af, .rgba rb gb bb _ =>
+    let a := af.toNat.toFloat / 255.0
+    let mix (f b : UInt8) : UInt8 :=
+      .ofNat (Nat.min 255 ((a * f.toNat.toFloat + (1.0 - a) * b.toNat.toFloat + 0.5).toUInt64.toNat))
+    .rgba (mix rf rb) (mix gf gb) (mix bf bb) 255
+
+private def cvdName : CVD → String
+  | .protanopia => "protanopia"
+  | .deuteranopia => "deuteranopia"
+  | .tritanopia => "tritanopia"
+
+/--
+Checks that {name}`fg` has enough contrast against {name}`bg` for {name}`threshold`. A translucent
+{name}`fg` is first composited over {name}`bg` (with {name}`over`), since that is the color actually
+seen. The background must be opaque, though: contrast against a translucent background depends on an
+unknown backdrop, so a non-opaque {name}`bg` is itself reported as a problem. {name}`description`
+names the pair in any issue.
+-/
+public def contrastIssues (threshold : Float) (description : String) (fg bg : Color) : Array Issue :=
+  if !isOpaque bg then
+    #[{ kind := .contrast,
+        message := s!"{description}: contrast cannot be judged because the background is not opaque",
+        offending := #[bg] }]
+  else
+    let seen := over fg bg
+    if meetsContrast threshold seen bg then
+      #[]
+    else
+      #[{ kind := .contrast,
+          message := s!"{description}: contrast ratio {contrastRatio seen bg} is below {threshold}",
+          offending := #[fg, bg] }]
+
+/--
+Checks that the given named colors stay mutually distinguishable under each of the three
+dichromacies. Reports a {name (full := IssueKind.colorblind)}`colorblind` issue for any pair that
+collapses (ΔE below {name}`threshold`) under some simulation.
+-/
+public def colorblindIssues (threshold : Float) (colors : Array (String × Color)) : Array Issue := Id.run do
+  let mut out := #[]
+  for i in [0:colors.size] do
+    for j in [i + 1:colors.size] do
+      let (n1, c1) := colors[i]!
+      let (n2, c2) := colors[j]!
+      for cvd in [CVD.protanopia, CVD.deuteranopia, CVD.tritanopia] do
+        unless distinguishable? threshold (dichromacy cvd c1) (dichromacy cvd c2) do
+          out := out.push
+            { kind := .colorblind,
+              message := s!"{n1} and {n2} are indistinguishable under {cvdName cvd}",
+              offending := #[c1, c2] }
+  return out

From f7adb2fb28109e3c4f7b0ff37f402ecaf148bc78 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Fri, 29 May 2026 22:07:24 +0200
Subject: [PATCH 05/31] feat: data model and syntax for fonts as Lean values

Adds a representation of fonts for use in themes.
---
 src/tests/Tests.lean                    |   1 +
 src/tests/Tests/Font.lean               |  70 +++++++++
 src/verso-manual/VersoManual/Basic.lean |  13 +-
 src/verso/Verso.lean                    |   1 +
 src/verso/Verso/Font.lean               | 194 ++++++++++++++++++++++++
 5 files changed, 269 insertions(+), 10 deletions(-)
 create mode 100644 src/tests/Tests/Font.lean
 create mode 100644 src/verso/Verso/Font.lean

diff --git a/src/tests/Tests.lean b/src/tests/Tests.lean
index 5fadb14d4..136521bd2 100644
--- a/src/tests/Tests.lean
+++ b/src/tests/Tests.lean
@@ -8,6 +8,7 @@ import Tests.Color
 import Tests.ColorAccessibility
 import Tests.ColorMath
 import Tests.Elab
+import Tests.Font
 import Tests.GenericCode
 import Tests.Golden
 import Tests.CommentSkipping
diff --git a/src/tests/Tests/Font.lean b/src/tests/Tests/Font.lean
new file mode 100644
index 000000000..b311d70cf
--- /dev/null
+++ b/src/tests/Tests/Font.lean
@@ -0,0 +1,70 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+import Verso.Font
+
+/-!
+Compile-time tests for `Verso.Font`: the `define_font_face` command embeds file bytes, `Weight`
+literals clamp into range, and `Typeface.cssFamily` renders (and escapes) as expected. There is no
+general font file to bundle yet, so an existing KaTeX font stands in for the embedding test.
+-/
+
+open Verso
+
+-- `define_font_face` embeds the file's bytes at compile time.
+define_font_face katexMono where
+  format := .woff2
+  file := "../../../vendored-js/katex/fonts/KaTeX_Typewriter-Regular.woff2"
+
+/-- info: true -/
+#guard_msgs in #eval decide (katexMono.bytes.size > 1000)
+/-- info: Verso.FontFormat.woff2 -/
+#guard_msgs in #eval katexMono.format
+/-- info: Verso.FontStyle.normal -/
+#guard_msgs in #eval katexMono.style
+
+-- `weight :=` is sugar for `weights := .fixed _`; `style` and the file format are honored.
+define_font_face boldItalicFace where
+  weight := .bold
+  style := .italic
+  format := .ttf
+  file := "../../../vendored-js/katex/fonts/KaTeX_Typewriter-Regular.ttf"
+
+/-- info: some 700 -/
+#guard_msgs in
+#eval match boldItalicFace.weights with
+  | .fixed w => some w.val
+  | _ => none
+/-- info: true -/
+#guard_msgs in #eval boldItalicFace.style = .italic
+
+-- Named weights and the clamping `OfNat`.
+/-- info: 400 -/
+#guard_msgs in #eval Weight.regular.val
+/-- info: 600 -/
+#guard_msgs in #eval Weight.semibold.val
+/-- info: 1000 -/
+#guard_msgs in #eval (1500 : Weight).val
+/-- info: 1 -/
+#guard_msgs in #eval (0 : Weight).val
+
+-- Default typefaces expand to system stacks; a custom family is quoted and escaped.
+/-- info: "ui-sans-serif, system-ui, sans-serif" -/
+#guard_msgs in #eval Typeface.sans.cssFamily
+/-- info: "\"Fancy\"" -/
+#guard_msgs in #eval (Typeface.files "Fancy" #[]).cssFamily
+/-- info: "\"a\\\"b\"" -/
+#guard_msgs in #eval (Typeface.files "a\"b" #[]).cssFamily
+
+-- A missing required field is an error.
+/-- error: `define_font_face` requires a `format` field -/
+#guard_msgs in
+define_font_face noFormat where
+  file := "x.woff2"
+
+/-- error: `define_font_face` requires a `file` field -/
+#guard_msgs in
+define_font_face noFile where
+  format := .ttf
diff --git a/src/verso-manual/VersoManual/Basic.lean b/src/verso-manual/VersoManual/Basic.lean
index f40cf1f54..cb31d5f40 100644
--- a/src/verso-manual/VersoManual/Basic.lean
+++ b/src/verso-manual/VersoManual/Basic.lean
@@ -7,6 +7,7 @@ module
 import Std.Data.HashSet
 import Std.Data.TreeSet
 import Verso.Doc
+public import Verso.Font
 public import Verso.Instances
 public import Verso.Doc.Html
 public import Verso.Doc.TeX
@@ -83,16 +84,8 @@ def toCss (family : FontFamily) : String := s!"font-family: var({family.toCssVar
 
 end FontFamily
 
-inductive FontStyle where
-  | normal
-  | italic
-deriving DecidableEq, Repr, Hashable
-
-def FontStyle.toCss (s : FontStyle) : String :=
-  "font-style: " ++
-  match s with
-  | .normal => "normal;"
-  | .italic => "italic;"
+-- `FontStyle` was previously defined here; it is re-exported here for backwards compatibility
+export Verso (FontStyle)
 
 inductive FontWeight where
   | lighter
diff --git a/src/verso/Verso.lean b/src/verso/Verso.lean
index 29c24bf84..5b19f8209 100644
--- a/src/verso/Verso.lean
+++ b/src/verso/Verso.lean
@@ -21,6 +21,7 @@ public import Verso.Doc.Lsp
 public import Verso.Doc.Suggestion
 public import Verso.Doc.TeX
 public import Verso.ExpectString
+public import Verso.Font
 public import Verso.Hover
 public import Verso.Instances
 public import Verso.Linters
diff --git a/src/verso/Verso/Font.lean b/src/verso/Verso/Font.lean
new file mode 100644
index 000000000..4998ab6b9
--- /dev/null
+++ b/src/verso/Verso/Font.lean
@@ -0,0 +1,194 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+public meta import Lean.Elab.Command
+public import VersoUtil.BinFiles
+
+set_option linter.missingDocs true
+set_option doc.verso true
+
+namespace Verso
+
+/-- Whether a font is upright or italic. -/
+public inductive FontStyle where
+  | normal
+  | italic
+deriving DecidableEq, Repr, Hashable
+
+/-- The CSS {lit}`font-style` declaration for a style. -/
+public def FontStyle.toCss (s : FontStyle) : String :=
+  "font-style: " ++
+  match s with
+  | .normal => "normal;"
+  | .italic => "italic;"
+
+/--
+A font weight in the CSS range 1–1000 (e.g. 400 for regular, 700 for bold).
+-/
+public structure Weight where
+  /-- The numeric weight, between 1 and 1000 inclusive. -/
+  val : Nat
+  /-- The weight is at least 1. -/
+  lo : 1 ≤ val := by grind
+  /-- The weight is at most 1000. -/
+  hi : val ≤ 1000 := by grind
+
+/--
+Numeric literals can be use for weights.
+
+They are clamped into the valid 1–1000 range, so a weight can be written as a plain number with no
+proof at the call site.
+-/
+public instance (n : Nat) : OfNat Weight n where
+  ofNat.val := max 1 (min 1000 n)
+
+namespace Weight
+
+/-- Thin (100). -/
+public abbrev thin : Weight := 100
+/-- Extra light (200). -/
+public abbrev extraLight : Weight := 200
+/-- Light (300). -/
+public abbrev light : Weight := 300
+/-- Regular (400). -/
+public abbrev regular : Weight := 400
+/-- Medium (500). -/
+public abbrev medium : Weight := 500
+/-- Semibold (600). -/
+public abbrev semibold : Weight := 600
+/-- Bold (700). -/
+public abbrev bold : Weight := 700
+/-- Extra bold (800). -/
+public abbrev extraBold : Weight := 800
+/-- Black (900). -/
+public abbrev black : Weight := 900
+
+end Weight
+
+/-- A font file format. -/
+public inductive FontFormat where
+  | woff2
+  | woff
+  | otf
+  | ttf
+deriving DecidableEq, Repr
+
+/--
+The format hint for this file kind: the string written inside CSS {lit}`format("...")` in the
+{lit}`src` entry of a {lit}`@font-face` rule (for example, {lit}`"woff2"` or {lit}`"opentype"`).
+-/
+public def FontFormat.css : FontFormat → String
+  | .woff2 => "woff2"
+  | .woff => "woff"
+  | .otf => "opentype"
+  | .ttf => "truetype"
+
+/--
+The weight or weights provided by a single font file: one fixed weight, or a variable-font range
+carrying a proof that the low weight does not exceed the high weight.
+-/
+public inductive FaceWeights where
+  | fixed (weight : Weight)
+  | variable (lo hi : Weight) (le : lo.val ≤ hi.val := by grind)
+
+/-- One font file: the weights and style it provides, its format, and its embedded bytes. -/
+public structure FontFace where
+  /-- The weight or weight range this file provides. -/
+  weights : FaceWeights := .fixed .regular
+  /-- The style (upright or italic) this file provides. -/
+  style : FontStyle := .normal
+  /-- The file's format. -/
+  format : FontFormat
+  /-- The file's contents, embedded at compile time. -/
+  bytes : ByteArray
+
+/--
+{open Typeface}
+
+A concrete font for theme text. The {name}`sans`, {name}`serif`, and {name}`mono` constructors refer
+to some arbitrary built-in family that may vary from system to system, while {name}`files` is used
+to refer to specific files.
+-/
+public inductive Typeface where
+  /-- Some sans-serif font -/
+  | sans
+  /-- Some serif font -/
+  | serif
+  /-- Some monospace font -/
+  | mono
+  /-- A specific font, provided as files -/
+  | files (family : String) (faces : Array FontFace)
+
+/-- Quotes a CSS string, escaping backslashes and double quotes so the name cannot break out. -/
+private def cssQuote (s : String) : String :=
+  "\"" ++ (s.replace "\\" "\\\\" |>.replace "\"" "\\\"") ++ "\""
+
+/--
+The CSS {lit}`font-family` value for a typeface.
+-/
+public def Typeface.cssFamily : Typeface → String
+  | .sans => "ui-sans-serif, system-ui, sans-serif"
+  | .serif => "ui-serif, Georgia, Cambria, serif"
+  | .mono => "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
+  | .files family _ => cssQuote family
+
+/-! # Defining font faces -/
+
+/--
+Defines a {name}`FontFace` whose {name}`FontFace.bytes` are embedded from a file at compile time.
+
+The fields, in any order: {lit}`format` (required), {lit}`file` (required, a string literal path
+relative to the current source file), {lit}`weights` (defaults to {lit}`.fixed .regular`),
+{lit}`weight` (sugar: {lit}`weight := w` means {lit}`weights := .fixed w`), and {lit}`style`
+(defaults to {lit}`.normal`). For example:
+
+```
+define_font_face sourceSansVariable where
+  weights := .variable .thin .black
+  format := .ttf
+  file := "fonts/SourceSans3-VF.ttf"
+```
+-/
+syntax (name := defineFontFace) "define_font_face " ident " where" manyIndent(group(withPosition(ident " := " colGt term))) : command
+
+open Lean Elab Command in
+/-- Elaborates a {lit}`define_font_face` command into a {name}`FontFace` definition. -/
+@[command_elab defineFontFace]
+public meta def elabDefineFontFace : CommandElab := fun stx => do
+  let nameIdent := stx[1]
+  let mut weights? : Option Term := none
+  let mut style? : Option Term := none
+  let mut format? : Option Term := none
+  let mut file? : Option (TSyntax `str) := none
+  for f in stx[3].getArgs do
+    let key := f[0].getId
+    let val : Term := ⟨f[2]⟩
+    match key with
+    | `weights => weights? := some val
+    | `weight => weights? := some (← `(Verso.FaceWeights.fixed $val))
+    | `style => style? := some val
+    | `format => format? := some val
+    | `file =>
+      if f[2].isStrLit?.isSome then file? := some ⟨f[2]⟩
+      else throwErrorAt f[2] "the `file` field must be a string literal"
+    | other => throwErrorAt f[0] s!"unknown field `{other}`; expected weights, weight, style, format, or file"
+  let some format := format?
+    | throwError "`define_font_face` requires a `format` field"
+  let some file := file?
+    | throwError "`define_font_face` requires a `file` field"
+  let weights ←
+    match weights? with
+    | some w => pure w
+    | none => ``(Verso.FaceWeights.fixed Verso.Weight.regular)
+  let style ←
+    match style? with
+    | some s => pure s
+    | none => ``(Verso.FontStyle.normal)
+  let name : Ident := ⟨nameIdent⟩
+  elabCommand <| ←
+    `(public def $name : Verso.FontFace :=
+        { weights := $weights, style := $style, format := $format, bytes := include_bin $file })

From aa9ed3ad722389e50f214604d6a802adf787ff02 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Sat, 30 May 2026 03:19:15 +0200
Subject: [PATCH 06/31] feat: code themes

Adds a first-class Lean representation of themes for rendered Lean code.
---
 .github/workflows/ci.yml                      |   8 +
 browser-tests/theme-customization/__init__.py |   0
 .../test_theme_customization.py               | 149 ++++
 lakefile.lean                                 |   9 +
 src/tests/TestMain.lean                       |  28 +-
 src/tests/Tests/Arbitrary.lean                |  14 +-
 src/tests/Tests/Color.lean                    |   2 +-
 src/tests/Tests/ColorAccessibility.lean       |   6 +-
 src/tests/Tests/ColorMath.lean                |  10 +-
 src/tests/ThemeTestDoc.lean                   |  40 +
 src/tests/ThemeTestMain.lean                  |  57 ++
 src/tests/golden/.gitignore                   |   1 +
 src/tests/golden/theme-css/default.expected   | 693 ++++++++++++++++++
 src/tests/golden/theme-css/default.input      |   1 +
 src/verso-manual/VersoManual.lean             |  45 ++
 src/verso-manual/VersoManual/Html.lean        |   1 +
 src/verso-search/VersoSearch.lean             |   2 +-
 src/verso/Verso.lean                          |   4 +-
 src/verso/Verso/Code/Highlighted.lean         | 103 ++-
 src/verso/Verso/Color.lean                    |  13 -
 src/verso/Verso/Font.lean                     |  10 +-
 src/verso/Verso/Theme/Code.lean               | 445 +++++++++++
 src/verso/Verso/Theme/Code/Defaults.lean      |  27 +
 src/verso/Verso/Theme/Code/Ext.lean           |  28 +
 src/verso/Verso/Theme/Color.lean              |  13 +
 .../{ => Theme}/Color/Accessibility.lean      |  19 +-
 src/verso/Verso/{ => Theme}/Color/Basic.lean  |   6 +-
 src/verso/Verso/{ => Theme}/Color/Math.lean   |   6 +-
 src/verso/Verso/{ => Theme}/Color/Syntax.lean |  12 +-
 src/verso/Verso/{ => Theme}/Color/Types.lean  |   2 +-
 src/verso/Verso/{ => Theme}/Color/Widget.lean |   6 +-
 .../Verso/{ => Theme}/Color/color-swatch.js   |   0
 32 files changed, 1643 insertions(+), 117 deletions(-)
 create mode 100644 browser-tests/theme-customization/__init__.py
 create mode 100644 browser-tests/theme-customization/test_theme_customization.py
 create mode 100644 src/tests/ThemeTestDoc.lean
 create mode 100644 src/tests/ThemeTestMain.lean
 create mode 100644 src/tests/golden/.gitignore
 create mode 100644 src/tests/golden/theme-css/default.expected
 create mode 100644 src/tests/golden/theme-css/default.input
 delete mode 100644 src/verso/Verso/Color.lean
 create mode 100644 src/verso/Verso/Theme/Code.lean
 create mode 100644 src/verso/Verso/Theme/Code/Defaults.lean
 create mode 100644 src/verso/Verso/Theme/Code/Ext.lean
 create mode 100644 src/verso/Verso/Theme/Color.lean
 rename src/verso/Verso/{ => Theme}/Color/Accessibility.lean (88%)
 rename src/verso/Verso/{ => Theme}/Color/Basic.lean (95%)
 rename src/verso/Verso/{ => Theme}/Color/Math.lean (98%)
 rename src/verso/Verso/{ => Theme}/Color/Syntax.lean (91%)
 rename src/verso/Verso/{ => Theme}/Color/Types.lean (97%)
 rename src/verso/Verso/{ => Theme}/Color/Widget.lean (91%)
 rename src/verso/Verso/{ => Theme}/Color/color-swatch.js (100%)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2d4e8b25c..363616b03 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -191,6 +191,14 @@ jobs:
                     browser-tests/test_redirect.py \
                     browser-tests/test_katex.py -v
 
+            - name: Run theme customization browser test
+              run: |
+                  lake build theme-test-site
+                  rm -rf _out/theme-test
+                  lake exe theme-test-site --output _out/theme-test
+                  uv run --project browser-tests --extra test pytest \
+                    browser-tests/theme-customization -v
+
             - name: Build the VersoHtml site for browser tests
               run: |
                   # The verso-html genre renders literate JSON into a standalone HTML site.
diff --git a/browser-tests/theme-customization/__init__.py b/browser-tests/theme-customization/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/browser-tests/theme-customization/test_theme_customization.py b/browser-tests/theme-customization/test_theme_customization.py
new file mode 100644
index 000000000..6fe98da99
--- /dev/null
+++ b/browser-tests/theme-customization/test_theme_customization.py
@@ -0,0 +1,149 @@
+"""
+Browser test that pins a representative subset of themed CSS variables to their rendered DOM
+values. The test currently exercises the four token color fields (keyword, const, var, fallback)
+plus the error indicator border. Other themed fields are emitted to `verso-themes.css` but are
+not all asserted here; expanding coverage is straightforward as more rendered features land in
+the small test document.
+
+Workflow:
+
+1. Build the `theme-test-site` Lean exe, which renders a small Manual document with a
+   customized `CodeTheme` whose every color field holds a distinct sentinel value.
+2. Serve the resulting `_out/theme-test/html-multi` directory.
+3. For each themed element in the generated HTML, read its computed style and assert it
+   matches the sentinel hex value the Lean theme set for that field.
+
+If the rendered color drifts from the Lean theme value, the theme pipeline
+(`CodeTheme.cssVariables` -> generated `verso-themes.css` -> `highlightingStyle`
+`var(--verso-*)` lookups) is broken end-to-end.
+"""
+
+import socket
+import subprocess
+import time
+from pathlib import Path
+
+import pytest
+from playwright.sync_api import sync_playwright
+
+
+HERE = Path(__file__).parent
+REPO_ROOT = HERE.parent.parent
+SITE_DIR = REPO_ROOT / "_out" / "theme-test" / "html-multi"
+
+
+def _hex_to_rgb(h: str) -> str:
+    h = h.lstrip("#")
+    if len(h) == 3:
+        h = "".join(c * 2 for c in h)
+    r, g, b = (int(h[i : i + 2], 16) for i in (0, 2, 4))
+    return f"rgb({r}, {g}, {b})"
+
+
+# Sentinel colors mirroring `src/tests/ThemeTestMain.lean`.
+THEME = {
+    "background": "#000101",
+    "codeBlockBackground": "#000202",
+    "textColor": "#000303",
+    "codeColor": "#000404",
+    "selectedColor": "#000606",
+    "infoIndicatorColor": "#000808",
+    "warningIndicatorColor": "#000a0a",
+    "errorIndicatorColor": "#000c0c",
+    "hoverBackground": "#000d0d",
+    "constColor": "#001717",
+    "keywordColor": "#001818",
+    "varColor": "#001919",
+}
+
+
+def _find_free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+@pytest.fixture(scope="module")
+def built_site():
+    """Rebuilds the customized-theme test site under `_out/theme-test`."""
+    subprocess.check_call(
+        ["lake", "build", "theme-test-site"],
+        cwd=REPO_ROOT,
+    )
+    if SITE_DIR.exists():
+        # Wipe so a stale build can't pass a renamed/deleted assertion.
+        subprocess.check_call(["rm", "-rf", str(SITE_DIR.parent)], cwd=REPO_ROOT)
+    subprocess.check_call(
+        ["lake", "exe", "theme-test-site", "--output", "_out/theme-test"],
+        cwd=REPO_ROOT,
+    )
+    assert SITE_DIR.exists(), f"Manual build did not produce {SITE_DIR}"
+    return SITE_DIR
+
+
+@pytest.fixture(scope="module")
+def server(built_site):
+    port = _find_free_port()
+    proc = subprocess.Popen(
+        ["python", "-m", "http.server", str(port), "--bind", "127.0.0.1"],
+        cwd=built_site,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    time.sleep(0.5)
+    try:
+        yield f"http://127.0.0.1:{port}"
+    finally:
+        proc.terminate()
+        proc.wait()
+
+
+@pytest.fixture(scope="module")
+def playwright_instance():
+    with sync_playwright() as p:
+        yield p
+
+
+@pytest.fixture(scope="module", params=["chromium", "firefox"])
+def page(request, playwright_instance, server):
+    browser = getattr(playwright_instance, request.param).launch()
+    page = browser.new_page()
+    page.goto(server + "/Code-samples/")
+    yield page
+    browser.close()
+
+
+def _color(page, selector: str, prop: str = "color") -> str:
+    return page.evaluate(
+        "([sel, p]) => getComputedStyle(document.querySelector(sel)).getPropertyValue(p)",
+        [selector, prop],
+    ).strip()
+
+
+def _expect(actual: str, hex_value: str, description: str) -> None:
+    expected = _hex_to_rgb(hex_value)
+    assert actual == expected, f"{description}: expected {expected} ({hex_value}), got {actual}"
+
+
+def test_token_colors(page):
+    # The first `.keyword` in the only code block is `def`.
+    _expect(_color(page, "code.hl.lean .keyword"), THEME["keywordColor"], "keyword color")
+    # `.const` on `hello` (the function name) and `String` (the type).
+    _expect(_color(page, "code.hl.lean .const"), THEME["constColor"], "const color")
+    # `.var` on `name` (the parameter binding).
+    _expect(_color(page, "code.hl.lean .var"), THEME["varColor"], "var color")
+    # `.unknown` (operator-like tokens) falls back to `--verso-code-color`.
+    _expect(_color(page, "code.hl.lean .unknown"), THEME["codeColor"], "fallback code color")
+
+
+def _goto_diagnostics(page, server):
+    page.goto(server + "/Diagnostics/")
+
+
+def test_error_indicator(page, server):
+    _goto_diagnostics(page, server)
+    _expect(
+        _color(page, "pre.lean-output.error", "border-left-color"),
+        THEME["errorIndicatorColor"],
+        "lean-output.error indicator border",
+    )
diff --git a/lakefile.lean b/lakefile.lean
index cea6eac61..89750d2af 100644
--- a/lakefile.lean
+++ b/lakefile.lean
@@ -134,6 +134,15 @@ lean_exe «verso-tests» where
   srcDir := "src/tests"
   supportInterpreter := true
 
+lean_lib ThemeTestDoc where
+  srcDir := "src/tests"
+  roots := #[`ThemeTestDoc]
+
+lean_exe «theme-test-site» where
+  root := `ThemeTestMain
+  srcDir := "src/tests"
+  supportInterpreter := true
+
 lean_lib UsersGuide where
   srcDir := "doc"
   leanOptions := #[⟨`weak.linter.verso.manual.headerTags, true⟩]
diff --git a/src/tests/TestMain.lean b/src/tests/TestMain.lean
index 42452a3dd..8e3059af5 100644
--- a/src/tests/TestMain.lean
+++ b/src/tests/TestMain.lean
@@ -167,6 +167,31 @@ def testSearchJs (_ : Config) : IO Unit := do
   if fails > 0 then
     throw <| IO.userError s!"{fails} search JS tests failed"
 
+open Verso in
+/--
+Golden test for the default code theme's generated CSS. The expected fixture lives at
+`src/tests/golden/theme-css/default.expected` and is regenerated with `--update-expected`.
+-/
+def testThemeCss (cfg : Config) : IO Unit := do
+  IO.println "Running theme CSS golden test..."
+  let runTest (input : String) : IO String := do
+    let name := input.trimAscii
+    if name == "default" then
+      let varsBlock := s!":root \{\n{Theme.CodeTheme.Default.cssVariables}}\n"
+      let combined := varsBlock ++ "\n" ++ Code.highlightingStyle
+      -- Trim the trailing blank lines `highlightingStyle` ships with so the golden file
+      -- ends with a single newline (otherwise `git diff --check` flags the EOF blank).
+      let mut out := combined
+      while out.endsWith "\n\n" do out := (out.dropEnd 1).copy
+      return out
+    else
+      throw <| IO.userError s!"Unknown theme: {name}"
+  GoldenTest.runTests {
+    testDir := "src/tests/golden/theme-css",
+    updateExpected := cfg.updateExpected,
+    runTest
+  }
+
 def testBlog (_ : Config) : IO Unit := do
   IO.println "Running blog tests with Plausible..."
   let fails ← runBlogTests
@@ -361,7 +386,7 @@ def testBuildLog (_ : Config) : IO Unit := do
     throw <| IO.userError "redirected logging should still accumulate into the logger's buffers"
   IO.println "  All build-log tests passed."
 
-open Verso in
+open Verso Theme in
 def testColor (_ : Config) : IO Unit := do
   IO.println "Running color tests..."
   let check (name got expected : String) : IO Unit :=
@@ -397,6 +422,7 @@ def tests := [
   testColor,
   testColorMath,
   testColorAccessibility,
+  testThemeCss,
   testSerialization,
   testSearchJs,
   testBlog,
diff --git a/src/tests/Tests/Arbitrary.lean b/src/tests/Tests/Arbitrary.lean
index 8e526decc..decd6b82c 100644
--- a/src/tests/Tests/Arbitrary.lean
+++ b/src/tests/Tests/Arbitrary.lean
@@ -18,7 +18,7 @@ public meta import VersoManual.LicenseInfo
 public meta import VersoSearch
 public meta import VersoSearch.DomainSearch
 public meta import Verso.Output.Html
-public meta import Verso.Color.Types
+public meta import Verso.Theme.Color.Types
 public meta import MultiVerso.Manifest
 public meta import VersoManual.Basic
 import all VersoManual.Basic
@@ -439,17 +439,17 @@ instance : Shrinkable System.FilePath where
       parent :: (path.fileName.toList.flatMap shrink |>.map path.withFileName)
     else []
 
-instance : Arbitrary Verso.Color where
+instance : Arbitrary Verso.Theme.Color where
   arbitrary := do
     -- Bias the alpha channel: fully opaque (the common case) 60% of the time, fully transparent 5%,
     -- and uniformly random the rest. A uniform alpha would almost never be exactly opaque.
     let a ← frequency (pure 255) [(60, pure 255), (5, pure 0), (35, arbitrary)]
     return .rgba (← arbitrary) (← arbitrary) (← arbitrary) a
 
-instance : Shrinkable Verso.Color where
+instance : Shrinkable Verso.Theme.Color where
   shrink
     | .rgba r g b a =>
-      (shrink r |>.map (Verso.Color.rgba · g b a)) ++
-      (shrink g |>.map (Verso.Color.rgba r · b a)) ++
-      (shrink b |>.map (Verso.Color.rgba r g · a)) ++
-      (shrink a |>.map (Verso.Color.rgba r g b ·))
+      (shrink r |>.map (Verso.Theme.Color.rgba · g b a)) ++
+      (shrink g |>.map (Verso.Theme.Color.rgba r · b a)) ++
+      (shrink b |>.map (Verso.Theme.Color.rgba r g · a)) ++
+      (shrink a |>.map (Verso.Theme.Color.rgba r g b ·))
diff --git a/src/tests/Tests/Color.lean b/src/tests/Tests/Color.lean
index 9e892cee0..834db3ef4 100644
--- a/src/tests/Tests/Color.lean
+++ b/src/tests/Tests/Color.lean
@@ -3,7 +3,7 @@ Copyright (c) 2025 Lean FRO LLC. All rights reserved.
 Released under Apache 2.0 license as described in the file LICENSE.
 Author: David Thrane Christiansen
 -/
-import Verso.Color
+import Verso.Theme.Color
 import Lean.Elab.Command
 
 /-!
diff --git a/src/tests/Tests/ColorAccessibility.lean b/src/tests/Tests/ColorAccessibility.lean
index 62c5ebc1a..d868b4794 100644
--- a/src/tests/Tests/ColorAccessibility.lean
+++ b/src/tests/Tests/ColorAccessibility.lean
@@ -5,15 +5,15 @@ Author: David Thrane Christiansen
 -/
 module
 public import Plausible
-public meta import Verso.Color
+public meta import Verso.Theme.Color
 public meta import Tests.Arbitrary
 
 /-!
-Unit and property tests for the accessibility predicates and checks in `Verso.Color.Accessibility`.
+Unit and property tests for the accessibility predicates and checks in `Verso.Theme.Color.Accessibility`.
 -/
 
 open Plausible Gen Arbitrary Shrinkable
-open Verso Verso.Color
+open Verso Verso.Theme Verso.Theme.Color
 
 meta section
 
diff --git a/src/tests/Tests/ColorMath.lean b/src/tests/Tests/ColorMath.lean
index 55c29afe1..f3bd1ec78 100644
--- a/src/tests/Tests/ColorMath.lean
+++ b/src/tests/Tests/ColorMath.lean
@@ -5,16 +5,16 @@ Author: David Thrane Christiansen
 -/
 module
 public import Plausible
-public meta import Verso.Color
-import all Verso.Color.Math
+public meta import Verso.Theme.Color
+import all Verso.Theme.Color.Math
 public meta import Tests.Arbitrary
 
 /-!
-Unit and property tests for the color math in `Verso.Color.Math`.
+Unit and property tests for the color math in `Verso.Theme.Color.Math`.
 -/
 
 open Plausible Gen Arbitrary Shrinkable
-open Verso Verso.Color
+open Verso Verso.Theme Verso.Theme.Color
 
 meta section
 
@@ -46,7 +46,7 @@ instance : Shrinkable CVD where
 #eval (deltaE .black .black, deltaE .white .black)
 
 -- Dichromacy simulation leaves the gray axis unchanged.
-/-- info: (Verso.Color.rgba 128 128 128 255, Verso.Color.rgba 128 128 128 255, Verso.Color.rgba 128 128 128 255) -/
+/-- info: (Verso.Theme.Color.rgba 128 128 128 255, Verso.Theme.Color.rgba 128 128 128 255, Verso.Theme.Color.rgba 128 128 128 255) -/
 #guard_msgs in
 #eval (dichromacy .protanopia .gray, dichromacy .deuteranopia .gray, dichromacy .tritanopia .gray)
 
diff --git a/src/tests/ThemeTestDoc.lean b/src/tests/ThemeTestDoc.lean
new file mode 100644
index 000000000..7cc2456f4
--- /dev/null
+++ b/src/tests/ThemeTestDoc.lean
@@ -0,0 +1,40 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+
+import VersoManual
+
+open Verso.Genre Manual
+open Verso.Genre.Manual.InlineLean
+
+set_option pp.rawOnError true
+
+#doc (Manual) "Theme test" =>
+
+# Code samples
+
+A line of prose, followed by code that mixes a keyword, a const, and a literal.
+
+```lean
+def hello (name : String) : String := s!"hello, {name}"
+```
+
+# Diagnostics
+
+A block that errors, so the rendered HTML carries the `.lean-output.error` rule used by the
+theme's error indicator color:
+
+```lean +error (name := badProof)
+example : 2 + 2 = 5 := by rfl
+```
+
+```leanOutput badProof
+Tactic `rfl` failed: The left-hand side
+  2 + 2
+is not definitionally equal to the right-hand side
+  5
+
+⊢ 2 + 2 = 5
+```
diff --git a/src/tests/ThemeTestMain.lean b/src/tests/ThemeTestMain.lean
new file mode 100644
index 000000000..8b2834ae2
--- /dev/null
+++ b/src/tests/ThemeTestMain.lean
@@ -0,0 +1,57 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+
+import Verso
+import VersoManual
+import ThemeTestDoc
+
+open Verso Verso.Theme
+open Verso.Genre Manual
+
+/-!
+The customized {Lean.Doc.name}`Verso.Theme.CodeTheme` used by the browser test. Each color field
+holds a distinct sentinel hex value so Playwright can identify which theme field a rendered DOM
+color comes from.
+-/
+def testTheme : CodeTheme := {
+  name := "ThemeTest",
+  appearance := .light,
+  background := color%#000101,
+  codeBlockBackground := color%#000202,
+  textColor := color%#000303,
+  codeColor := color%#000404,
+  structureColor := color%#000505,
+  selectedColor := color%#000606,
+  infoColor := color%#000707,
+  infoIndicatorColor := color%#000808,
+  warningColor := color%#000909,
+  warningIndicatorColor := color%#000a0a,
+  errorColor := color%#000b0b,
+  errorIndicatorColor := color%#000c0c,
+  hoverBackground := color%#000d0d,
+  hoverBorderColor := color%#000e0e,
+  hoverText := color%#000f0f,
+  hoverSeparatorColor := color%#001010,
+  tokenHighlightBackground := color%#001111,
+  tacticStateBackground := color%#001212,
+  tacticStateBorderColor := color%#001313,
+  highlightOnCode := color%#001414,
+  highlightOnText := color%#001515,
+  uiOnCode := color%#001616,
+  const := { color := color%#001717, weight := 500, style := .italic, face := .sans },
+  keyword := { color := color%#001818, weight := 800, style := .italic, face := .serif },
+  «var» := { color := color%#001919, weight := 300, style := .normal, face := .mono },
+}
+
+def config : Config where
+  emitTeX := false
+  emitHtmlSingle := .no
+  emitHtmlMulti := .immediately
+  htmlDepth := 1
+
+def main : List String → IO UInt32 :=
+  manualMain (%doc ThemeTestDoc)
+    (config := { config with codeTheme := testTheme })
diff --git a/src/tests/golden/.gitignore b/src/tests/golden/.gitignore
new file mode 100644
index 000000000..7de0b67ed
--- /dev/null
+++ b/src/tests/golden/.gitignore
@@ -0,0 +1 @@
+*.output
diff --git a/src/tests/golden/theme-css/default.expected b/src/tests/golden/theme-css/default.expected
new file mode 100644
index 000000000..47a7eaea4
--- /dev/null
+++ b/src/tests/golden/theme-css/default.expected
@@ -0,0 +1,693 @@
+:root {
+  --verso-background-color: #ffffff;
+  --verso-code-background-color: #ffffff;
+  --verso-text-color: #000000;
+  --verso-code-color: #000000;
+  --verso-structure-color: #000000;
+  --verso-selected-color: #ddeeff;
+  --verso-info-color: #000000;
+  --verso-info-indicator-color: #4777ff;
+  --verso-warning-color: #000000;
+  --verso-warning-indicator-color: #e7a71d;
+  --verso-error-color: #cc0000;
+  --verso-error-indicator-color: #ff0000;
+  --verso-code-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --verso-code-const-color: #000000;
+  --verso-code-const-weight: 400;
+  --verso-code-const-style: normal;
+  --verso-code-const-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --verso-code-keyword-color: #000000;
+  --verso-code-keyword-weight: 700;
+  --verso-code-keyword-style: normal;
+  --verso-code-keyword-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --verso-code-var-color: #000000;
+  --verso-code-var-weight: 400;
+  --verso-code-var-style: italic;
+  --verso-code-var-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --verso-hover-background-color: #e5e5e5;
+  --verso-hover-border-color: #000000;
+  --verso-hover-text-color: #000000;
+  --verso-hover-separator-color: #cccccc;
+  --verso-token-highlight-background-color: #eeeeee;
+  --verso-tactic-state-background-color: #ffffff;
+  --verso-tactic-state-border-color: #888888;
+  --verso-highlight-on-code-color: #fff3b0;
+  --verso-highlight-on-text-color: #fff3b0;
+  --verso-ui-on-code-color: #888888;
+}
+
+
+
+.hl.lean {
+  white-space: pre;
+  font-weight: normal;
+  font-style: normal;
+  font-size: inherit;
+}
+
+.hl.lean .keyword {
+  color: var(--verso-code-keyword-color,);
+  font-weight: var(--verso-code-keyword-weight, bold);
+  font-style: var(--verso-code-keyword-style, normal);
+  font-family: var(--verso-code-keyword-font-family,);
+}
+
+.hl.lean .const {
+  color: var(--verso-code-const-color,);
+  font-weight: var(--verso-code-const-weight, normal);
+  font-style: var(--verso-code-const-style, normal);
+  font-family: var(--verso-code-const-font-family,);
+}
+
+.hl.lean .var {
+  color: var(--verso-code-var-color,);
+  font-weight: var(--verso-code-var-weight, normal);
+  font-style: var(--verso-code-var-style, italic);
+  font-family: var(--verso-code-var-font-family,);
+
+  position: relative;
+}
+
+.hl.lean .literal, .hl.lean .unknown {
+  color: var(--verso-code-color,);
+  font-weight: normal;
+  font-style: normal;
+  font-family: var(--verso-code-font-family,);
+}
+
+.hover-container {
+  width: 0;
+  height: 0;
+  position: relative;
+  display: inline;
+}
+
+.hl.lean a {
+  color: inherit;
+  text-decoration: currentcolor underline dotted;
+}
+
+.hl.lean a:hover {
+  text-decoration: currentcolor underline solid;
+}
+
+.hl.lean .hover-info {
+  white-space: normal;
+}
+
+.hl.lean .token .hover-info {
+  display: none;
+  position: absolute;
+  background-color: var(--verso-hover-background-color, #e5e5e5);
+  border: 1px solid var(--verso-hover-border-color, black);
+  padding: 0.5rem;
+  z-index: 300;
+}
+
+.hl.lean .hover-info.messages {
+  max-height: 10rem;
+  overflow-y: auto;
+  overflow-x: hidden;
+  scrollbar-gutter: stable;
+  padding: 0 0.5rem 0 0;
+  display: block;
+}
+
+.hl.lean .hover-info code {
+  white-space: pre-wrap;
+  background: none;
+  color: var(--verso-hover-text-color, black);
+}
+
+.hl.lean .hover-info.messages > code {
+  padding: 0.5rem;
+  display: block;
+  width: fit-content;
+}
+
+.hl.lean .hover-info.messages > code:only-child {
+  margin: 0;
+}
+
+.hl.lean .hover-info.messages > code {
+  margin: 0.1rem;
+}
+
+.hl.lean .hover-info.messages > code:not(:first-child) {
+  margin-top: 0rem;
+}
+
+.hl.lean {
+}
+
+.hl.lean.block {
+  display: block;
+}
+
+.hl.lean.inline {
+  display: inline;
+  white-space: pre-wrap;
+}
+
+.hl.lean * {
+}
+
+.hl.lean .token {
+  transition: all 0.25s; /* Slight fade for highlights */
+}
+
+@media (hover: hover) {
+  .hl.lean .token.binding-hl, .hl.lean .literal.string:hover, .hl.lean .token.typed:hover {
+    background-color: var(--verso-token-highlight-background-color, #eeeeee);
+    border-radius: 2px;
+    transition: none;
+  }
+}
+
+
+.hl.lean .has-info .token:not(.tactic-state):not(.tactic-state *), .hl.lean .has-info .inter-text:not(.tactic-state):not(.tactic-state *) {
+  text-decoration-style: wavy;
+  text-decoration-line: underline;
+  text-decoration-thickness: from-font;
+  text-decoration-skip-ink: none;
+}
+
+.hl.lean .has-info .hover-info {
+  display: none;
+  position: absolute;
+  transform: translate(0.25rem, 0.3rem);
+  border: 1px solid var(--verso-hover-border-color, black);
+  padding: 0.5rem;
+  z-index: 400;
+  text-align: left;
+}
+
+.hl.lean .has-info.error :not(.tactic-state):not(.tactic-state *){
+  text-decoration-color: var(--verso-error-indicator-color, red);
+}
+
+@media (hover: hover) {
+  .hl.lean .has-info.error:hover {
+    background-color: var(--verso-token-highlight-background-color, #eeeeee);
+  }
+}
+
+.hl.lean .hover-info.messages > code.error {
+  background-color: var(--verso-hover-background-color, #e5e5e5);
+  border-left: 0.2rem solid var(--verso-error-indicator-color, red);
+}
+
+.tippy-box[data-theme~='error'] .hl.lean .hover-info.messages > code.error {
+  background: none;
+  border: none;
+}
+
+.error .verso-message, .error .verso-message .token, .error .verso-message label {
+  color: var(--verso-error-color);
+}
+
+.error .verso-message .case-label:has(input[type="checkbox"])::before {
+  background-color: var(--verso-error-color) !important;
+}
+
+.hl.lean .has-info.warning :not(.tactic-state):not(.tactic-state *) {
+  text-decoration-color: var(--verso-warning-indicator-color);
+}
+
+@media (hover: hover) {
+  .hl.lean .has-info.warning:hover {
+    background-color: var(--verso-token-highlight-background-color, #eeeeee);
+  }
+}
+
+.hl.lean .hover-info.messages > code.warning {
+  background-color: var(--verso-hover-background-color, #e5e5e5);
+}
+
+.lean-output {
+  border-left: 0.2em solid transparent;
+  padding: 0 0 0 0.5em;
+  border-top-left-radius: 0;
+  border-bottom-left-radius: 0;
+}
+
+.lean-output.error {
+  border-color: var(--verso-error-indicator-color);
+}
+
+.lean-output.information {
+  border-color: var(--verso-info-indicator-color);
+}
+
+.lean-output.warning {
+  border-color: var(--verso-warning-indicator-color);
+}
+
+.tippy-box[data-theme~='warning'] .hl.lean .hover-info.messages > code.warning {
+  background: none;
+  border: none;
+}
+
+
+.hl.lean .has-info.information :not(.tactic-state):not(.tactic-state *) {
+  text-decoration-color: var(--verso-info-indicator-color, blue);
+}
+
+@media (hover: hover) {
+  .hl.lean .has-info.information:hover {
+    background-color: var(--verso-token-highlight-background-color, #eeeeee);
+  }
+}
+
+
+.hl.lean .hover-info.messages > code.information {
+  background-color: var(--verso-hover-background-color, #e5e5e5);
+  border-left: 0.2rem solid var(--verso-info-indicator-color, blue);
+}
+
+.tippy-box[data-theme~='info'] .hl.lean .hover-info.messages > code.information {
+  background: none;
+  border: none;
+}
+
+.hl.lean div.docstring {
+  font-family: var(--verso-text-font-family, sans-serif);
+  white-space: normal;
+  max-width: calc(min(40rem, 90vw));
+  width: max-content;
+}
+
+.hl.lean div.docstring > :last-child {
+  margin-bottom: 0;
+}
+
+.hl.lean div.docstring > :first-child {
+  margin-top: 0;
+}
+
+.hl.lean .hover-info .sep {
+  display: block;
+  width: auto;
+  margin-left: 1rem;
+  margin-right: 1rem;
+  margin-top: 0.5rem;
+  margin-bottom: 0.5rem;
+  padding: 0;
+  height: 1px;
+  border-top: 1px solid var(--verso-hover-separator-color, #cccccc);
+}
+
+.hl.lean code {
+  font-family: var(--verso-code-font-family);
+}
+
+.hl.lean .tactic-state {
+  display: none;
+  position: relative;
+  width: fit-content;
+  border: 1px solid var(--verso-tactic-state-border-color, #888888);
+  border-radius: 0.1rem;
+  padding: 0.5rem;
+  font-family: sans-serif;
+  background-color: var(--verso-tactic-state-background-color, #ffffff);
+}
+
+.hl.lean.popup .tactic-state {
+  position: static;
+  display: block;
+  width: auto;
+  border: none;
+  padding: 0.5rem;
+  font-family: sans-serif;
+  background-color: var(--verso-tactic-state-background-color, #ffffff);
+}
+
+
+.hl.lean .tactic {
+  position: relative;
+  display: inline;
+  vertical-align: top;
+  /* Without these, mobile Safari will start making font sizes inconsistent when its text size adjustment feature is triggered.*/
+  -webkit-text-size-adjust: 100%;
+  text-size-adjust: 100%;
+}
+
+.hl.lean .tactic:has(.tactic-toggle:checked) {
+  display: inline-grid;
+  grid-template-columns: 1fr;
+}
+
+.hl.lean .tactic-toggle:checked ~ .tactic-state {
+  display: inline-block;
+  vertical-align: top;
+  grid-row: 2;
+  justify-self: start;
+}
+
+.hl.lean .tactic > label {
+  position: relative;
+  grid-row: 1;
+  display: inline;
+}
+
+@media (hover: hover) {
+  .hl.lean .tactic:has(.tactic-toggle:not(:checked)) > label:hover {
+    background-color: var(--verso-token-highlight-background-color, #eeeeee);
+  }
+}
+
+.hl.lean .tactic-toggle {
+  position: absolute;
+  top: 0;
+  left: 0;
+  opacity: 0;
+  height: 0;
+  width: 0;
+  z-index: -10;
+}
+
+.hl.lean .tactic > label::after {
+  content: "";
+  border: 1px solid var(--verso-ui-on-code-color, #888888);
+  /* These need to be em, not rem, to scale with the font */
+  border-radius: 1em;
+  height: 0.25em;
+  vertical-align: middle;
+  width: 0.6em;
+  margin-left: 0.1em;
+  margin-right: 0.1em;
+  display: inline-block;
+  transition: all 0.5s;
+}
+
+/*
+@media (hover: hover) {
+  .hl.lean .tactic > label:hover::after {
+    border: 1px solid #aaaaaa;
+    background-color: #aaaaaa;
+    transition: all 0.5s;
+  }
+}
+*/
+
+.hl.lean .tactic > label:has(+ .tactic-toggle:checked)::after {
+  border: 1px solid var(--verso-ui-on-code-color, #888888);
+  background-color: var(--verso-ui-on-code-color, #888888);
+  transition: all 0.5s;
+}
+
+.hl.lean .tactic-state .goal + .goal {
+  margin-top: 1.5em;
+}
+
+/*
+Some CSS frameworks customize details/summary in ways not compatible with Verso's output.
+*/
+
+.hl.lean details {
+  display: block !important;
+  margin: 0;
+}
+
+.hl.lean details summary {
+  display: list-item !important;
+  margin: 0;
+}
+
+.hl.lean details summary:focus {
+  outline: none;
+  outline-offset: none;
+  color: inherit;
+}
+
+.hl.lean ul > li {
+  margin-bottom: 0;
+}
+
+.hl.lean details summary::marker {
+  display: inline !important;
+}
+
+.hl.lean details > summary:first-of-type {
+  list-style-type: disclosure-closed;
+  list-style-position: inside;
+}
+
+.hl.lean details[open] > summary:first-of-type {
+  list-style-type: disclosure-open;
+}
+
+.hl.lean details summary::before, .hl.lean details summary::after {
+  content: "" !important;
+  background: none;
+  display: none;
+}
+
+.hl.lean .tactic-state summary {
+  /* These need to be em, not rem, to scale with the font */
+  margin-left: -0.5em;
+}
+
+.hl.lean .tactic-state details {
+  /* These need to be em, not rem, to scale with the font */
+  padding-left: 0.5em;
+}
+
+.hl.lean .case-label {
+  display: block;
+  position: relative;
+}
+
+.hl.lean .case-label input[type="checkbox"] {
+  position: absolute;
+  top: 0;
+  left: 0;
+  opacity: 0;
+  height: 0;
+  width: 0;
+  z-index: -10;
+}
+
+.hl.lean .case-label:has(input[type="checkbox"])::before {
+  display: inline-block;
+  background-color: var(--verso-code-color, black);
+  content: ' ';
+  transition: ease 0.2s;
+  margin-right: 0.7em;
+  clip-path: polygon(100% 0, 0 0, 50% 100%);
+  width: 0.6em;
+  height: 0.6em;
+  vertical-align: middle;
+}
+
+.hl.lean .case-label:has(input[type="checkbox"]:not(:checked))::before {
+  transform: rotate(-90deg);
+}
+
+.hl.lean .case-label:has(input[type="checkbox"]) {
+
+}
+
+.hl.lean .case-label:has(input[type="checkbox"]:checked) {
+
+}
+
+
+.hl.lean .labeled-case > :not(:first-child) {
+  max-height: 0px;
+  display: block;
+  overflow: hidden;
+  transition: max-height 0.1s ease-in;
+  /* These need to be em, not rem, to scale with the font */
+  margin-left: 0.5em;
+  margin-top: 0.1em;
+}
+
+.hl.lean .labeled-case:has(.case-label input[type="checkbox"]:checked) > :not(:first-child) {
+  max-height: 100%;
+}
+
+
+.hl.lean .goal-name::before {
+  font-style: normal;
+  content: "case ";
+}
+
+.hl.lean .goal-name {
+  font-style: italic;
+  font-family: var(--verso-code-font-family);
+  color: inherit;
+}
+
+.hl.lean .hypotheses {
+  display: table;
+}
+
+.hl.lean .hypothesis {
+  display: table-row;
+}
+
+.hl.lean .hypothesis > * {
+  display: table-cell;
+}
+
+
+.hl.lean .hypotheses .colon {
+  text-align: center;
+  /* This needs to be em, not rem, to scale with the font */
+  min-width: 1em;
+}
+
+.hl.lean .hypotheses .name {
+  text-align: right;
+}
+
+.hl.lean .hypotheses .name,
+.hl.lean .hypotheses .type,
+.hl.lean .conclusion .type {
+  font-family: var(--verso-code-font-family);
+}
+
+.tippy-box {
+  /* Without these, mobile Safari will start making font sizes inconsistent when its text size adjustment feature is triggered.*/
+  -webkit-text-size-adjust: 100%;
+  text-size-adjust: 100%;
+}
+
+.tippy-box[data-theme~='lean'] {
+  background-color: var(--verso-hover-background-color, #e5e5e5);
+  color: var(--verso-hover-text-color, black);
+  border: 1px solid var(--verso-hover-border-color, black);
+}
+.tippy-box[data-theme~='lean'][data-placement^='top'] > .tippy-arrow::before {
+  border-top-color: var(--verso-hover-background-color, #e5e5e5);
+}
+.tippy-box[data-theme~='lean'][data-placement^='bottom'] > .tippy-arrow::before {
+  border-bottom-color: var(--verso-hover-background-color, #e5e5e5);
+}
+.tippy-box[data-theme~='lean'][data-placement^='left'] > .tippy-arrow::before {
+  border-left-color: var(--verso-hover-background-color, #e5e5e5);
+}
+.tippy-box[data-theme~='lean'][data-placement^='right'] > .tippy-arrow::before {
+  border-right-color: var(--verso-hover-background-color, #e5e5e5);
+}
+
+.tippy-box[data-theme~='message'][data-placement^='top'] > .tippy-arrow::before {
+  border-top-color: var(--verso-hover-background-color, #e5e5e5);
+  border-width: 11px 11px 0;
+}
+.tippy-box[data-theme~='message'][data-placement^='top'] > .tippy-arrow::after {
+  bottom: -11px;
+  border-width: 11px 11px 0;
+}
+.tippy-box[data-theme~='message'][data-placement^='bottom'] > .tippy-arrow::before {
+  border-width: 0 11px 11px;
+}
+.tippy-box[data-theme~='message'][data-placement^='bottom'] > .tippy-arrow::after {
+  top: -11px;
+  border-width: 0 11px 11px;
+}
+.tippy-box[data-theme~='message'][data-placement^='left'] > .tippy-arrow::before {
+  border-left-color: var(--verso-hover-background-color, #e5e5e5);
+  border-width: 11px 0 11px 11px;
+}
+.tippy-box[data-theme~='message'][data-placement^='left'] > .tippy-arrow::after {
+  right: -11px;
+  border-width: 11px 0 11px 11px;
+}
+
+.tippy-box[data-theme~='message'][data-placement^='right'] > .tippy-arrow::before {
+  border-right-color: var(--verso-hover-background-color, #e5e5e5);
+  border-width: 11px 11px 11px 0;
+}
+.tippy-box[data-theme~='message'][data-placement^='right'] > .tippy-arrow::after {
+  left: -11px;
+  border-width: 11px 11px 11px 0;
+}
+
+
+
+.tippy-box[data-theme~='warning'] {
+  background-color: var(--verso-hover-background-color, #e5e5e5);
+  color: var(--verso-hover-text-color, black);
+  border: 3px solid var(--verso-warning-indicator-color, #e7a71d);
+}
+
+.tippy-box[data-theme~='error'] {
+  background-color: var(--verso-hover-background-color, #e5e5e5);
+  color: var(--verso-hover-text-color, black);
+  border: 3px solid var(--verso-error-indicator-color, red);
+}
+
+.tippy-box[data-theme~='info'] {
+  background-color: var(--verso-hover-background-color, #e5e5e5);
+  color: var(--verso-hover-text-color, black);
+  border: 3px solid var(--verso-info-indicator-color, blue);
+}
+
+.tippy-box[data-theme~='tactic'] {
+  background-color: var(--verso-tactic-state-background-color, #ffffff);
+  color: var(--verso-hover-text-color, black);
+  border: 1px solid var(--verso-hover-border-color, black);
+}
+.tippy-box[data-theme~='tactic'][data-placement^='top'] > .tippy-arrow::before {
+  border-top-color: var(--verso-tactic-state-background-color, #ffffff);
+}
+.tippy-box[data-theme~='tactic'][data-placement^='bottom'] > .tippy-arrow::before {
+  border-bottom-color: var(--verso-tactic-state-background-color, #ffffff);
+}
+.tippy-box[data-theme~='tactic'][data-placement^='left'] > .tippy-arrow::before {
+  border-left-color: var(--verso-tactic-state-background-color, #ffffff);
+}
+.tippy-box[data-theme~='tactic'][data-placement^='right'] > .tippy-arrow::before {
+  border-right-color: var(--verso-tactic-state-background-color, #ffffff);
+}
+
+.extra-doc-links {
+  list-style-type: none;
+  margin-left: 0;
+  padding: 0;
+}
+
+.extra-doc-links > li {
+  display: inline-block;
+}
+
+.extra-doc-links > li:not(:last-child)::after {
+  content: '|';
+  display: inline-block;
+  margin: 0 0.25em;
+}
+
+.verso-message .trace {
+  display: block;
+}
+
+.verso-message .trace > summary::marker {
+  color: var(--verso-text-color);
+}
+
+.verso-message .trace-children {
+  margin: 0;
+  padding: 0;
+}
+
+.verso-message .trace-children > li {
+  list-style-type: none;
+  margin-left: 1.5em;
+}
+
+.verso-message .trace-children > li:not(:has(.trace)) {
+  margin-left: 0;
+}
+
+.verso-message .trace-class {
+  color: color-mix(in srgb, currentColor 70%, transparent);
+  font-weight: bold;
+  margin: 0;
+  padding: 0;
+}
+
+.verso-message .text {
+  white-space: pre-wrap;
+}
diff --git a/src/tests/golden/theme-css/default.input b/src/tests/golden/theme-css/default.input
new file mode 100644
index 000000000..331d858ce
--- /dev/null
+++ b/src/tests/golden/theme-css/default.input
@@ -0,0 +1 @@
+default
\ No newline at end of file
diff --git a/src/verso-manual/VersoManual.lean b/src/verso-manual/VersoManual.lean
index 7156ff13e..f6c55cfda 100644
--- a/src/verso-manual/VersoManual.lean
+++ b/src/verso-manual/VersoManual.lean
@@ -11,6 +11,8 @@ import Verso.Doc.Html
 import Verso.Output.TeX
 import Verso.Output.Html
 import Verso.Output.Html.CssVars
+import Verso.Theme.Code
+import Verso.Theme.Code.Defaults
 import Verso.Output.Html.KaTeX
 import Verso.Output.Html.ElasticLunr
 import Verso.Doc.Lsp
@@ -242,6 +244,11 @@ structure RenderConfig extends Config where
   How to insert links in rendered code
   -/
   linkTargets : TraverseState → Multi.AllRemotes → LinkTargets Manual.TraverseContext := (·.localTargets ++ ·.remoteTargets)
+  /--
+  The active {Lean.Doc.name}`Verso.Theme.CodeTheme`. Its CSS-variable block is written to
+  {lit}`verso-themes.css` so the page-level highlighting rules read the chosen colors.
+  -/
+  codeTheme : Verso.Theme.CodeTheme := Verso.Theme.CodeTheme.Default
 
 namespace Config
 
@@ -762,6 +769,24 @@ where
       h.putStrLn Html.«verso-vars.css»
     IO.FS.withFile (dir.join "book.css") .write fun h => do
       h.putStrLn Html.Css.pageStyle
+    IO.FS.withFile (dir.join "verso-themes.css") .write fun h => do
+      let assetRoot := s!"-verso-data/themes/{config.codeTheme.name}"
+      let faceRules := config.codeTheme.fontFaceRules assetRoot
+      unless faceRules.isEmpty do
+        h.putStrLn faceRules
+      h.putStrLn s!":root \{\n{config.codeTheme.cssVariables}}"
+      let extra := config.codeTheme.extraCss assetRoot
+      unless extra.isEmpty do
+        h.putStrLn ""
+        h.putStrLn extra
+    for (path, bytes, _, _) in config.codeTheme.fontAssets s!"-verso-data/themes/{config.codeTheme.name}" do
+      let abs := dir.join path
+      if let some p := abs.parent then ensureDir p
+      IO.FS.writeBinFile abs bytes
+    for a in config.codeTheme.assets do
+      let path := dir.join "-verso-data" |>.join "themes" |>.join config.codeTheme.name |>.join a.path
+      if let some p := path.parent then ensureDir p
+      IO.FS.writeBinFile path a.contents
     for (src, dest) in config.extraFiles do
       copyRecursively src (dir.join dest)
     for (src, dest) in config.extraFilesHtml do
@@ -830,6 +855,24 @@ where
       h.putStrLn Html.«verso-vars.css»
     IO.FS.withFile (root / "book.css") .write fun h => do
       h.putStrLn Html.Css.pageStyle
+    IO.FS.withFile (root / "verso-themes.css") .write fun h => do
+      let assetRoot := s!"-verso-data/themes/{config.codeTheme.name}"
+      let faceRules := config.codeTheme.fontFaceRules assetRoot
+      unless faceRules.isEmpty do
+        h.putStrLn faceRules
+      h.putStrLn s!":root \{\n{config.codeTheme.cssVariables}}"
+      let extra := config.codeTheme.extraCss assetRoot
+      unless extra.isEmpty do
+        h.putStrLn ""
+        h.putStrLn extra
+    for (path, bytes, _, _) in config.codeTheme.fontAssets s!"-verso-data/themes/{config.codeTheme.name}" do
+      let abs := root.join path
+      if let some p := abs.parent then ensureDir p
+      IO.FS.writeBinFile abs bytes
+    for a in config.codeTheme.assets do
+      let path := root.join "-verso-data" |>.join "themes" |>.join config.codeTheme.name |>.join a.path
+      if let some p := path.parent then ensureDir p
+      IO.FS.writeBinFile path a.contents
     for (src, dest) in config.extraFiles do
       copyRecursively src (root.join dest)
     for (src, dest) in config.extraFilesHtml do
@@ -944,9 +987,11 @@ open Verso.CLI
 
 def manualMain (text : Part Manual)
     (extensionImpls : ExtensionImpls := by exact extension_impls%)
+    (codeThemes : Verso.Theme.CodeThemeTable := by exact code_themes%)
     (options : List String)
     (config : RenderConfig := {})
     (extraSteps : List ExtraStep := []) : IO UInt32 :=
+  let _ := codeThemes
   ReaderT.run go extensionImpls
 
 where
diff --git a/src/verso-manual/VersoManual/Html.lean b/src/verso-manual/VersoManual/Html.lean
index 9d5d54892..18550c0a2 100644
--- a/src/verso-manual/VersoManual/Html.lean
+++ b/src/verso-manual/VersoManual/Html.lean
@@ -437,6 +437,7 @@ public def page
         <title>{{textTitle}}</title>
         <link rel="stylesheet" href="book.css" />
         <link rel="stylesheet" href="verso-vars.css" />
+        <link rel="stylesheet" href="verso-themes.css" />
         <script src="https://cdn.jsdelivr.net/npm/marked@11.1.1/marked.min.js" integrity="sha384-zbcZAIxlvJtNE3Dp5nxLXdXtXyxwOdnILY1TDPVmKFhl4r4nSUG1r8bcFXGVa4Te" crossorigin="anonymous"></script>
         {{ searchAssetTags }}
         {{extraJsFiles.map fun f => ({{<script src=s!"{f.1}" {{if f.2 then defer else #[]}}></script>}})}}
diff --git a/src/verso-search/VersoSearch.lean b/src/verso-search/VersoSearch.lean
index f4f8a464a..fd8f964fd 100644
--- a/src/verso-search/VersoSearch.lean
+++ b/src/verso-search/VersoSearch.lean
@@ -798,7 +798,7 @@ public class Indexable (genre : Verso.Doc.Genre) where
   /--
   Computes the full-text search priority for a part, using the same centered-at-50 convention as the
   quick-jump side. Returning {lean}`none` leaves the document at neutral; returning a signed integer
-  lets a genre fold section metadata, ancestor inheritance, or other emission-time adjustments into
+  lets a genre fold section metadata, ancestor inheritance, or other HTMl-generation-time adjustments into
   full-text scoring. This is an {lean}`Int` to allow it to accumulate adjustments that put it
   outside the usual range.
   -/
diff --git a/src/verso/Verso.lean b/src/verso/Verso.lean
index 5b19f8209..4735bd49f 100644
--- a/src/verso/Verso.lean
+++ b/src/verso/Verso.lean
@@ -8,7 +8,9 @@ module
 -- Import modules here that should be built as part of the library.
 public import Verso.CLI
 public import Verso.Code
-public import Verso.Color
+public import Verso.Theme.Code
+public import Verso.Theme.Code.Defaults
+public import Verso.Theme.Color
 public import Verso.Doc
 public import Verso.Doc.ArgParse
 public import Verso.Doc.Concrete
diff --git a/src/verso/Verso/Code/Highlighted.lean b/src/verso/Verso/Code/Highlighted.lean
index 8fbe0c57d..18526d4d6 100644
--- a/src/verso/Verso/Code/Highlighted.lean
+++ b/src/verso/Verso/Code/Highlighted.lean
@@ -709,8 +709,8 @@ public def highlightingStyle : String := "
 .hl.lean .token .hover-info {
   display: none;
   position: absolute;
-  background-color: #e5e5e5;
-  border: 1px solid black;
+  background-color: var(--verso-hover-background-color, #e5e5e5);
+  border: 1px solid var(--verso-hover-border-color, black);
   padding: 0.5rem;
   z-index: 300;
 }
@@ -727,7 +727,7 @@ public def highlightingStyle : String := "
 .hl.lean .hover-info code {
   white-space: pre-wrap;
   background: none;
-  color: black;
+  color: var(--verso-hover-text-color, black);
 }
 
 .hl.lean .hover-info.messages > code {
@@ -769,7 +769,7 @@ public def highlightingStyle : String := "
 
 @media (hover: hover) {
   .hl.lean .token.binding-hl, .hl.lean .literal.string:hover, .hl.lean .token.typed:hover {
-    background-color: #eee;
+    background-color: var(--verso-token-highlight-background-color, #eeeeee);
     border-radius: 2px;
     transition: none;
   }
@@ -787,25 +787,25 @@ public def highlightingStyle : String := "
   display: none;
   position: absolute;
   transform: translate(0.25rem, 0.3rem);
-  border: 1px solid black;
+  border: 1px solid var(--verso-hover-border-color, black);
   padding: 0.5rem;
   z-index: 400;
   text-align: left;
 }
 
 .hl.lean .has-info.error :not(.tactic-state):not(.tactic-state *){
-  text-decoration-color: red;
+  text-decoration-color: var(--verso-error-indicator-color, red);
 }
 
 @media (hover: hover) {
   .hl.lean .has-info.error:hover {
-    background-color: #ffb3b3;
+    background-color: var(--verso-token-highlight-background-color, #eeeeee);
   }
 }
 
 .hl.lean .hover-info.messages > code.error {
-  background-color: #e5e5e5;
-  border-left: 0.2rem solid #ffb3b3;
+  background-color: var(--verso-hover-background-color, #e5e5e5);
+  border-left: 0.2rem solid var(--verso-error-indicator-color, red);
 }
 
 .tippy-box[data-theme~='error'] .hl.lean .hover-info.messages > code.error {
@@ -827,12 +827,12 @@ public def highlightingStyle : String := "
 
 @media (hover: hover) {
   .hl.lean .has-info.warning:hover {
-    background-color:var(--verso-warning-color);
+    background-color: var(--verso-token-highlight-background-color, #eeeeee);
   }
 }
 
 .hl.lean .hover-info.messages > code.warning {
-  background-color: var(--verso-warning-color);
+  background-color: var(--verso-hover-background-color, #e5e5e5);
 }
 
 .lean-output {
@@ -854,11 +854,6 @@ public def highlightingStyle : String := "
   border-color: var(--verso-warning-indicator-color);
 }
 
-.hl.lean .hover-info.messages > code.error {
-  background-color: #e5e5e5;
-  border-left: 0.2rem solid var(--verso-warning-color);
-}
-
 .tippy-box[data-theme~='warning'] .hl.lean .hover-info.messages > code.warning {
   background: none;
   border: none;
@@ -871,14 +866,14 @@ public def highlightingStyle : String := "
 
 @media (hover: hover) {
   .hl.lean .has-info.information:hover {
-    background-color: #4777ff;
+    background-color: var(--verso-token-highlight-background-color, #eeeeee);
   }
 }
 
 
 .hl.lean .hover-info.messages > code.information {
-  background-color: #e5e5e5;
-  border-left: 0.2rem solid #4777ff;
+  background-color: var(--verso-hover-background-color, #e5e5e5);
+  border-left: 0.2rem solid var(--verso-info-indicator-color, blue);
 }
 
 .tippy-box[data-theme~='info'] .hl.lean .hover-info.messages > code.information {
@@ -910,7 +905,7 @@ public def highlightingStyle : String := "
   margin-bottom: 0.5rem;
   padding: 0;
   height: 1px;
-  border-top: 1px solid #ccc;
+  border-top: 1px solid var(--verso-hover-separator-color, #cccccc);
 }
 
 .hl.lean code {
@@ -921,11 +916,11 @@ public def highlightingStyle : String := "
   display: none;
   position: relative;
   width: fit-content;
-  border: 1px solid #888888;
+  border: 1px solid var(--verso-tactic-state-border-color, #888888);
   border-radius: 0.1rem;
   padding: 0.5rem;
   font-family: sans-serif;
-  background-color: #ffffff;
+  background-color: var(--verso-tactic-state-background-color, #ffffff);
 }
 
 .hl.lean.popup .tactic-state {
@@ -935,7 +930,7 @@ public def highlightingStyle : String := "
   border: none;
   padding: 0.5rem;
   font-family: sans-serif;
-  background-color: #ffffff;
+  background-color: var(--verso-tactic-state-background-color, #ffffff);
 }
 
 
@@ -968,7 +963,7 @@ public def highlightingStyle : String := "
 
 @media (hover: hover) {
   .hl.lean .tactic:has(.tactic-toggle:not(:checked)) > label:hover {
-    background-color: #eeeeee;
+    background-color: var(--verso-token-highlight-background-color, #eeeeee);
   }
 }
 
@@ -984,7 +979,7 @@ public def highlightingStyle : String := "
 
 .hl.lean .tactic > label::after {
   content: \"\";
-  border: 1px solid #bbbbbb;
+  border: 1px solid var(--verso-ui-on-code-color, #888888);
   /* These need to be em, not rem, to scale with the font */
   border-radius: 1em;
   height: 0.25em;
@@ -1007,8 +1002,8 @@ public def highlightingStyle : String := "
 */
 
 .hl.lean .tactic > label:has(+ .tactic-toggle:checked)::after {
-  border: 1px solid #999999;
-  background-color: #999999;
+  border: 1px solid var(--verso-ui-on-code-color, #888888);
+  background-color: var(--verso-ui-on-code-color, #888888);
   transition: all 0.5s;
 }
 
@@ -1086,7 +1081,7 @@ Some CSS frameworks customize details/summary in ways not compatible with Verso'
 
 .hl.lean .case-label:has(input[type=\"checkbox\"])::before {
   display: inline-block;
-  background-color: black;
+  background-color: var(--verso-code-color, black);
   content: ' ';
   transition: ease 0.2s;
   margin-right: 0.7em;
@@ -1171,25 +1166,25 @@ Some CSS frameworks customize details/summary in ways not compatible with Verso'
 }
 
 .tippy-box[data-theme~='lean'] {
-  background-color: #e5e5e5;
-  color: black;
-  border: 1px solid black;
+  background-color: var(--verso-hover-background-color, #e5e5e5);
+  color: var(--verso-hover-text-color, black);
+  border: 1px solid var(--verso-hover-border-color, black);
 }
 .tippy-box[data-theme~='lean'][data-placement^='top'] > .tippy-arrow::before {
-  border-top-color: #e5e5e5;
+  border-top-color: var(--verso-hover-background-color, #e5e5e5);
 }
 .tippy-box[data-theme~='lean'][data-placement^='bottom'] > .tippy-arrow::before {
-  border-bottom-color: #e5e5e5;
+  border-bottom-color: var(--verso-hover-background-color, #e5e5e5);
 }
 .tippy-box[data-theme~='lean'][data-placement^='left'] > .tippy-arrow::before {
-  border-left-color: #e5e5e5;
+  border-left-color: var(--verso-hover-background-color, #e5e5e5);
 }
 .tippy-box[data-theme~='lean'][data-placement^='right'] > .tippy-arrow::before {
-  border-right-color: #e5e5e5;
+  border-right-color: var(--verso-hover-background-color, #e5e5e5);
 }
 
 .tippy-box[data-theme~='message'][data-placement^='top'] > .tippy-arrow::before {
-  border-top-color: #e5e5e5;
+  border-top-color: var(--verso-hover-background-color, #e5e5e5);
   border-width: 11px 11px 0;
 }
 .tippy-box[data-theme~='message'][data-placement^='top'] > .tippy-arrow::after {
@@ -1204,7 +1199,7 @@ Some CSS frameworks customize details/summary in ways not compatible with Verso'
   border-width: 0 11px 11px;
 }
 .tippy-box[data-theme~='message'][data-placement^='left'] > .tippy-arrow::before {
-  border-left-color: #e5e5e5;
+  border-left-color: var(--verso-hover-background-color, #e5e5e5);
   border-width: 11px 0 11px 11px;
 }
 .tippy-box[data-theme~='message'][data-placement^='left'] > .tippy-arrow::after {
@@ -1213,7 +1208,7 @@ Some CSS frameworks customize details/summary in ways not compatible with Verso'
 }
 
 .tippy-box[data-theme~='message'][data-placement^='right'] > .tippy-arrow::before {
-  border-right-color: #e5e5e5;
+  border-right-color: var(--verso-hover-background-color, #e5e5e5);
   border-width: 11px 11px 11px 0;
 }
 .tippy-box[data-theme~='message'][data-placement^='right'] > .tippy-arrow::after {
@@ -1224,39 +1219,39 @@ Some CSS frameworks customize details/summary in ways not compatible with Verso'
 
 
 .tippy-box[data-theme~='warning'] {
-  background-color: #e5e5e5;
-  color: black;
-  border: 3px solid var(--verso-warning-color);
+  background-color: var(--verso-hover-background-color, #e5e5e5);
+  color: var(--verso-hover-text-color, black);
+  border: 3px solid var(--verso-warning-indicator-color, #e7a71d);
 }
 
 .tippy-box[data-theme~='error'] {
-  background-color: #e5e5e5;
-  color: black;
-  border: 3px solid #f7a7af;
+  background-color: var(--verso-hover-background-color, #e5e5e5);
+  color: var(--verso-hover-text-color, black);
+  border: 3px solid var(--verso-error-indicator-color, red);
 }
 
 .tippy-box[data-theme~='info'] {
-  background-color: #e5e5e5;
-  color: black;
-  border: 3px solid #99b3c2;
+  background-color: var(--verso-hover-background-color, #e5e5e5);
+  color: var(--verso-hover-text-color, black);
+  border: 3px solid var(--verso-info-indicator-color, blue);
 }
 
 .tippy-box[data-theme~='tactic'] {
-  background-color: white;
-  color: black;
-  border: 1px solid black;
+  background-color: var(--verso-tactic-state-background-color, #ffffff);
+  color: var(--verso-hover-text-color, black);
+  border: 1px solid var(--verso-hover-border-color, black);
 }
 .tippy-box[data-theme~='tactic'][data-placement^='top'] > .tippy-arrow::before {
-  border-top-color: white;
+  border-top-color: var(--verso-tactic-state-background-color, #ffffff);
 }
 .tippy-box[data-theme~='tactic'][data-placement^='bottom'] > .tippy-arrow::before {
-  border-bottom-color: white;
+  border-bottom-color: var(--verso-tactic-state-background-color, #ffffff);
 }
 .tippy-box[data-theme~='tactic'][data-placement^='left'] > .tippy-arrow::before {
-  border-left-color: white;
+  border-left-color: var(--verso-tactic-state-background-color, #ffffff);
 }
 .tippy-box[data-theme~='tactic'][data-placement^='right'] > .tippy-arrow::before {
-  border-right-color: white;
+  border-right-color: var(--verso-tactic-state-background-color, #ffffff);
 }
 
 .extra-doc-links {
diff --git a/src/verso/Verso/Color.lean b/src/verso/Verso/Color.lean
deleted file mode 100644
index 0b3dfe7b5..000000000
--- a/src/verso/Verso/Color.lean
+++ /dev/null
@@ -1,13 +0,0 @@
-/-
-Copyright (c) 2025 Lean FRO LLC. All rights reserved.
-Released under Apache 2.0 license as described in the file LICENSE.
-Author: David Thrane Christiansen
--/
-module
-
-public import Verso.Color.Types
-public import Verso.Color.Basic
-public import Verso.Color.Math
-public import Verso.Color.Accessibility
-public import Verso.Color.Widget
-public import Verso.Color.Syntax
diff --git a/src/verso/Verso/Font.lean b/src/verso/Verso/Font.lean
index 4998ab6b9..f5c5ea9af 100644
--- a/src/verso/Verso/Font.lean
+++ b/src/verso/Verso/Font.lean
@@ -124,7 +124,7 @@ public inductive Typeface where
   | files (family : String) (faces : Array FontFace)
 
 /-- Quotes a CSS string, escaping backslashes and double quotes so the name cannot break out. -/
-private def cssQuote (s : String) : String :=
+public def cssQuote (s : String) : String :=
   "\"" ++ (s.replace "\\" "\\\\" |>.replace "\"" "\\\"") ++ "\""
 
 /--
@@ -142,9 +142,9 @@ public def Typeface.cssFamily : Typeface → String
 Defines a {name}`FontFace` whose {name}`FontFace.bytes` are embedded from a file at compile time.
 
 The fields, in any order: {lit}`format` (required), {lit}`file` (required, a string literal path
-relative to the current source file), {lit}`weights` (defaults to {lit}`.fixed .regular`),
-{lit}`weight` (sugar: {lit}`weight := w` means {lit}`weights := .fixed w`), and {lit}`style`
-(defaults to {lit}`.normal`). For example:
+relative to the current source file), {lit}`weights` (defaults to {lean}`(.fixed .regular : FaceWeights)`),
+{lit}`weight` (sugar: {lit}`weight := w` is rewritten to a fixed-weight value), and {lit}`style`
+(defaults to {lean}`(.normal : FontStyle)`). For example:
 
 ```
 define_font_face sourceSansVariable where
@@ -156,7 +156,7 @@ define_font_face sourceSansVariable where
 syntax (name := defineFontFace) "define_font_face " ident " where" manyIndent(group(withPosition(ident " := " colGt term))) : command
 
 open Lean Elab Command in
-/-- Elaborates a {lit}`define_font_face` command into a {name}`FontFace` definition. -/
+/-- Elaborates a {kw (of := Verso.defineFontFace)}`define_font_face` command into a {name}`FontFace` definition. -/
 @[command_elab defineFontFace]
 public meta def elabDefineFontFace : CommandElab := fun stx => do
   let nameIdent := stx[1]
diff --git a/src/verso/Verso/Theme/Code.lean b/src/verso/Verso/Theme/Code.lean
new file mode 100644
index 000000000..356a75675
--- /dev/null
+++ b/src/verso/Verso/Theme/Code.lean
@@ -0,0 +1,445 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+public meta import Verso.Theme.Code.Ext
+public import Verso.Theme.Color
+public import Verso.Theme.Color.Accessibility
+public import Verso.Font
+public meta import Lean.Elab.Term
+
+set_option linter.missingDocs true
+set_option doc.verso true
+
+/-!
+The genre-neutral code theme: a typed set of colors, token styles, and font choices that the
+manual genre uses to render code blocks and inline code. Default values reproduce today's
+hardcoded chrome.
+-/
+
+namespace Verso.Theme
+
+/-- Whether a theme is intended for a light or a dark display. -/
+public inductive Appearance where
+  | light
+  | dark
+deriving DecidableEq, Repr
+
+/-- Styling for a single token kind: its color, weight, font style, and the face it uses. -/
+public structure TokenStyle where
+  /-- The token's text color. -/
+  color : Color
+  /-- The token's font weight (CSS 1–1000). -/
+  weight : Weight := .regular
+  /-- The token's font style (upright or italic). -/
+  style : FontStyle := .normal
+  /-- The font used for this token. -/
+  face : Typeface
+
+/-- A bundled asset (such as an image) shipped with a theme. -/
+public structure ThemeAsset where
+  /-- The output-relative path the asset will be written to. -/
+  path : String
+  /-- The asset bytes, embedded at compile time. -/
+  contents : ByteArray
+
+/--
+A typed code theme. Defaults reproduce today's hardcoded chrome, so a default-constructed theme is
+visually unchanged from the pre-theming look.
+
+Cascade-style defaults: fields that today read a CSS `var()` chain (for example a token color
+defaulting to the body code color) reference the earlier field directly. Lean evaluates the default
+at construction, so overriding a field overrides every later field that defaulted from it.
+-/
+public structure CodeTheme where
+  /-- A human-readable name for the theme (shown in the picker). -/
+  name : String
+  /-- Whether this theme is intended for a light or a dark display. -/
+  appearance : Appearance
+
+  /-- The font used for code blocks and inline code. -/
+  codeFace : Typeface := .mono
+
+  /-- The page and content background color. The contrast reference for body text. -/
+  background : Color := Color.white
+  /-- The background behind code blocks. The contrast reference for token colors. -/
+  codeBlockBackground : Color := background
+  /-- The background behind inline code in prose. When set, inline code gets padding and rounding. -/
+  inlineBackground : Option Color := none
+  /-- The color of body prose text. -/
+  textColor : Color := Color.black
+  /-- The color of code text. -/
+  codeColor : Color := textColor
+  /-- The color used for structural decoration (such as case labels). -/
+  structureColor : Color := textColor
+  /-- The background color used to highlight a selected token in code. -/
+  selectedColor : Color := color%#ddeeff
+
+  /-- The message-text color for informational diagnostics. -/
+  infoColor : Color := textColor
+  /-- The accent color (left border, underline) for informational diagnostics. -/
+  infoIndicatorColor : Color := color%#4777ff
+  /-- The message-text color for warning diagnostics. -/
+  warningColor : Color := textColor
+  /-- The accent color (left border, underline) for warning diagnostics. -/
+  warningIndicatorColor : Color := color%#e7a71d
+  /-- The message-text color for error diagnostics. -/
+  errorColor : Color := color%#cc0000
+  /-- The accent color (left border, underline) for error diagnostics. -/
+  errorIndicatorColor : Color := color%#ff0000
+
+  /-- Token styling for constants. -/
+  const : TokenStyle := { color := codeColor, weight := .regular, style := .normal, face := codeFace }
+  /-- Token styling for keywords. -/
+  keyword : TokenStyle := { color := codeColor, weight := .bold, style := .normal, face := codeFace }
+  /-- Token styling for variables (bound names). -/
+  «var» : TokenStyle := { color := codeColor, weight := .regular, style := .italic, face := codeFace }
+
+  /-- The background of hover popups, diagnostic boxes, and tooltips. -/
+  hoverBackground : Color := color%#e5e5e5
+  /-- The border color of hover popups and plain tooltips. -/
+  hoverBorderColor : Color := Color.black
+  /-- The text color inside hover popups. -/
+  hoverText : Color := textColor
+  /-- The separator line color inside hover popups. -/
+  hoverSeparatorColor : Color := color%#cccccc
+  /-- The background tint applied to a token on hover (independent of severity). -/
+  tokenHighlightBackground : Color := color%#eeeeee
+  /-- The background of a displayed tactic state. -/
+  tacticStateBackground : Color := Color.white
+  /-- The border color of a displayed tactic state. -/
+  tacticStateBorderColor : Color := color%#888888
+
+  /--
+  An accent background drawn behind highlighted code.
+  {name (full := Verso.Theme.CodeTheme.codeColor)}`codeColor` must read on it.
+  -/
+  highlightOnCode : Color := color%#fff3b0
+  /-- An accent background drawn behind highlighted code or prose. Both code and text must read on it. -/
+  highlightOnText : Color := highlightOnCode
+  /--
+  A neutral UI element color drawn against
+  {name (full := Verso.Theme.CodeTheme.codeBlockBackground)}`codeBlockBackground` (e.g. a toggle pill).
+  -/
+  uiOnCode : Color := color%#888888
+
+  /--
+  Theme-specific CSS appended after the standard variable block. The asset root path the function
+  receives is relative to {lit}`verso-themes.css` so {lit}`url()` references resolve from there.
+  -/
+  extraCss : (assetRoot : String) → String := fun _ => ""
+  /-- Non-font assets (such as images) bundled with the theme. -/
+  assets : Array ThemeAsset := #[]
+
+/-! # Attribute, environment extension, and materialization -/
+
+public section
+
+/--
+Attribute that registers a {Lean.Doc.name}`CodeTheme` declaration as an available theme. The
+declaration must be in the current module (not imported), and its registration name is the decl's
+name with macro scopes erased.
+-/
+syntax (name := code_theme) "code_theme" : attr
+
+open Lean in
+meta initialize
+  registerBuiltinAttribute {
+    name := `code_theme,
+    ref := by exact decl_name%,
+    add := fun decl _stx kind => do
+      unless kind == AttributeKind.global do
+        throwError "invalid attribute 'code_theme', must be global"
+      unless ((← getEnv).getModuleIdxFor? decl).isNone do
+        throwError "invalid attribute 'code_theme', declaration is in an imported module"
+      modifyEnv fun env => codeThemeExt.addEntry env decl.eraseMacroScopes
+    descr := "Registers a definition as an available code theme"
+  }
+
+end section
+
+/--
+A materialized table of registered {Lean.Doc.name}`CodeTheme` values, keyed by registration name.
+Built at runtime by the {lit}`code_themes%` term elaborator from the set of
+{Lean.Doc.name}`CodeTheme` declarations tagged with the {lit}`@[code_theme]` attribute.
+-/
+public structure CodeThemeTable where
+  /-- The map from a theme's registration name to its value. -/
+  themes : Lean.NameMap CodeTheme := {}
+
+namespace CodeThemeTable
+
+/-- The empty table. -/
+public def empty : CodeThemeTable := {}
+
+public instance : EmptyCollection CodeThemeTable := ⟨empty⟩
+
+/-- Looks up a theme by its registration name. -/
+public def find? (t : CodeThemeTable) (n : Lean.Name) : Option CodeTheme :=
+  t.themes.find? n
+
+/-- Inserts a theme under the given registration name. -/
+public def insert (t : CodeThemeTable) (n : Lean.Name) (theme : CodeTheme) : CodeThemeTable :=
+  ⟨t.themes.insert n theme⟩
+
+/-- Builds a table from a list of pairs. -/
+public def fromList (xs : List (Lean.Name × CodeTheme)) : CodeThemeTable :=
+  xs.foldl (fun (acc : CodeThemeTable) (p : Lean.Name × CodeTheme) => acc.insert p.1 p.2) empty
+
+end CodeThemeTable
+
+public section
+
+/-- Term elaborator that materializes the registered code-theme table at compile time. -/
+syntax (name := code_themes) "code_themes%" : term
+
+open Lean Elab Term in
+private meta def themePair [Monad m] [MonadRef m] [MonadQuotation m] (n : Name) : m Term := do
+  let quoted : Term := quote n
+  let ident ← mkCIdentFromRef n
+  `(($quoted, $(⟨ident⟩)))
+
+open Lean Elab Term in
+/-- Elaborator for the {lit}`code_themes%` macro: emits a {Lean.Doc.name}`Verso.Theme.CodeThemeTable`
+literal whose entries are every registered {Lean.Doc.name}`Verso.Theme.CodeTheme` decl. -/
+@[term_elab code_themes]
+meta def elabCodeThemes : TermElab := fun _stx expected? => do
+  let env ← getEnv
+  let mut names : Array Name := #[]
+  for n in codeThemeExt.getState env do
+    names := names.push n
+  for imported in codeThemeExt.toEnvExtension.getState env |>.importedEntries do
+    for n in imported do
+      names := names.push n
+  let stx ← `(Verso.Theme.CodeThemeTable.fromList [$[($(← names.mapM themePair) : Lean.Name × Verso.Theme.CodeTheme)],*])
+  elabTerm stx expected?
+
+end section
+
+/-! # Accessibility checking -/
+
+namespace CodeTheme
+
+/-- The display name and color of a token style, for accessibility reporting. -/
+private def tokenSummaries (theme : CodeTheme) : Array (String × Color) := #[
+    ("const", theme.const.color),
+    ("keyword", theme.keyword.color),
+    ("var", theme.«var».color)
+  ]
+
+/--
+Checks a theme for contrast and color-vision-deficiency problems. The checker is pure and genre
+neutral: it returns an {Lean.Doc.name}`Array` of {Lean.Doc.name}`Verso.Theme.Color.Issue` values
+whose {Lean.Doc.name}`Verso.Theme.Color.Issue.kind` field a caller routes to its severity flag.
+
+Body text uses the WCAG AA 4.5 threshold; UI accents and large-text positions use 3.0. Token
+distinguishability uses the CIEDE2000 threshold from
+{Lean.Doc.name}`Verso.Theme.Color.distinguishableThreshold`.
+-/
+public def checkAccessibility (theme : CodeTheme) : Array Color.Issue := Id.run do
+  let mut issues := #[]
+  -- Body and message text on the page background.
+  issues := issues ++ Color.contrastIssues Color.textContrastThreshold
+    "body text on background" theme.textColor theme.background
+  issues := issues ++ Color.contrastIssues Color.textContrastThreshold
+    "error message text on background" theme.errorColor theme.background
+  issues := issues ++ Color.contrastIssues Color.textContrastThreshold
+    "warning message text on background" theme.warningColor theme.background
+  issues := issues ++ Color.contrastIssues Color.textContrastThreshold
+    "info message text on background" theme.infoColor theme.background
+  -- Code tokens against the code-block background.
+  for (n, c) in theme.tokenSummaries do
+    issues := issues ++ Color.contrastIssues Color.textContrastThreshold
+      s!"{n} token on code background" c theme.codeBlockBackground
+  -- Inline-code background, when set, must read with the code color.
+  if let some bg := theme.inlineBackground then
+    issues := issues ++ Color.contrastIssues Color.textContrastThreshold
+      "code on inline background" theme.codeColor bg
+  -- Indicator accents against the page background.
+  issues := issues ++ Color.contrastIssues Color.largeContrastThreshold
+    "error indicator on background" theme.errorIndicatorColor theme.background
+  issues := issues ++ Color.contrastIssues Color.largeContrastThreshold
+    "warning indicator on background" theme.warningIndicatorColor theme.background
+  issues := issues ++ Color.contrastIssues Color.largeContrastThreshold
+    "info indicator on background" theme.infoIndicatorColor theme.background
+  -- Highlight backgrounds.
+  issues := issues ++ Color.contrastIssues Color.textContrastThreshold
+    "code on highlightOnCode" theme.codeColor theme.highlightOnCode
+  issues := issues ++ Color.contrastIssues Color.textContrastThreshold
+    "code on highlightOnText" theme.codeColor theme.highlightOnText
+  issues := issues ++ Color.contrastIssues Color.textContrastThreshold
+    "text on highlightOnText" theme.textColor theme.highlightOnText
+  -- UI element on code background (large/UI threshold).
+  issues := issues ++ Color.contrastIssues Color.largeContrastThreshold
+    "uiOnCode against code background" theme.uiOnCode theme.codeBlockBackground
+  -- Tactic state border on its background.
+  issues := issues ++ Color.contrastIssues Color.largeContrastThreshold
+    "tactic-state border on its background"
+    theme.tacticStateBorderColor theme.tacticStateBackground
+  -- Hover popup readability.
+  issues := issues ++ Color.contrastIssues Color.textContrastThreshold
+    "hover-popup text on hover background" theme.hoverText theme.hoverBackground
+  -- Tactic popups draw the same hover text on the tactic-state background.
+  issues := issues ++ Color.contrastIssues Color.textContrastThreshold
+    "hover-popup text on tactic-state background"
+    theme.hoverText theme.tacticStateBackground
+  -- Code drawn on the tactic-state background (for example a hypothesis).
+  issues := issues ++ Color.contrastIssues Color.textContrastThreshold
+    "code on tactic-state background" theme.codeColor theme.tacticStateBackground
+  -- Colorblindness: tokens and indicators stay mutually distinguishable.
+  issues := issues ++ Color.colorblindIssues Color.distinguishableThreshold
+    (theme.tokenSummaries ++ #[
+      ("error indicator", theme.errorIndicatorColor),
+      ("warning indicator", theme.warningIndicatorColor),
+      ("info indicator", theme.infoIndicatorColor)])
+  return issues
+
+end CodeTheme
+
+/-! # CSS variable block -/
+
+namespace CodeTheme
+
+/-- Renders a single `--name: value;` CSS declaration. -/
+private def cssDecl (name value : String) : String :=
+  s!"  --{name}: {value};\n"
+
+private def colorDecl (name : String) (c : Color) : String :=
+  cssDecl name (Color.css c)
+
+private def styleDecls (prefix' : String) (s : TokenStyle) : String :=
+  String.join [
+    colorDecl s!"{prefix'}-color" s.color,
+    cssDecl s!"{prefix'}-weight" (toString s.weight.val),
+    cssDecl s!"{prefix'}-style" (match s.style with | .normal => "normal" | .italic => "italic"),
+    cssDecl s!"{prefix'}-font-family" s.face.cssFamily
+  ]
+
+/--
+Renders the theme as the body of a CSS `:root { ... }` block: one `--verso-*` custom property per
+themed value. The output drives the page-level theme stylesheet and replaces the resolved values
+that today are hardcoded into {lit}`verso-vars.css` and {lit}`highlightingStyle`.
+-/
+public def cssVariables (theme : CodeTheme) : String :=
+  String.join [
+    colorDecl "verso-background-color" theme.background,
+    colorDecl "verso-code-background-color" theme.codeBlockBackground,
+    (match theme.inlineBackground with
+     | some c => colorDecl "verso-inline-code-background-color" c
+     | none => ""),
+    colorDecl "verso-text-color" theme.textColor,
+    colorDecl "verso-code-color" theme.codeColor,
+    colorDecl "verso-structure-color" theme.structureColor,
+    colorDecl "verso-selected-color" theme.selectedColor,
+    colorDecl "verso-info-color" theme.infoColor,
+    colorDecl "verso-info-indicator-color" theme.infoIndicatorColor,
+    colorDecl "verso-warning-color" theme.warningColor,
+    colorDecl "verso-warning-indicator-color" theme.warningIndicatorColor,
+    colorDecl "verso-error-color" theme.errorColor,
+    colorDecl "verso-error-indicator-color" theme.errorIndicatorColor,
+    cssDecl "verso-code-font-family" theme.codeFace.cssFamily,
+    styleDecls "verso-code-const" theme.const,
+    styleDecls "verso-code-keyword" theme.keyword,
+    styleDecls "verso-code-var" theme.«var»,
+    colorDecl "verso-hover-background-color" theme.hoverBackground,
+    colorDecl "verso-hover-border-color" theme.hoverBorderColor,
+    colorDecl "verso-hover-text-color" theme.hoverText,
+    colorDecl "verso-hover-separator-color" theme.hoverSeparatorColor,
+    colorDecl "verso-token-highlight-background-color" theme.tokenHighlightBackground,
+    colorDecl "verso-tactic-state-background-color" theme.tacticStateBackground,
+    colorDecl "verso-tactic-state-border-color" theme.tacticStateBorderColor,
+    colorDecl "verso-highlight-on-code-color" theme.highlightOnCode,
+    colorDecl "verso-highlight-on-text-color" theme.highlightOnText,
+    colorDecl "verso-ui-on-code-color" theme.uiOnCode
+  ]
+
+end CodeTheme
+
+/-! # Font assets and {lit}`@font-face` writing -/
+
+namespace CodeTheme
+
+/--
+Every {Lean.Doc.name}`Verso.Typeface` referenced by a theme. Built-in
+{Lean.Doc.name (full := Verso.Typeface.sans)}`sans`/{Lean.Doc.name (full := Verso.Typeface.serif)}`serif`/{Lean.Doc.name (full := Verso.Typeface.mono)}`mono`
+are skipped: only {Lean.Doc.name (full := Verso.Typeface.files)}`files` typefaces contribute font assets.
+-/
+public def fileTypefaces (theme : CodeTheme) : Array Typeface :=
+  let faces := #[theme.codeFace, theme.const.face, theme.keyword.face, theme.«var».face]
+  faces.filter fun
+    | .files _ _ => true
+    | _ => false
+
+/-- The output file extension for a font format. -/
+public def _root_.Verso.FontFormat.ext : FontFormat → String
+  | .woff2 => "woff2"
+  | .woff => "woff"
+  | .otf => "otf"
+  | .ttf => "ttf"
+
+/--
+Sanitizes a font-family name into a path-safe slug. Letters, digits, hyphens, underscores, and
+dots are preserved; every other character becomes a hyphen, runs of hyphens collapse, and the
+result is trimmed of leading/trailing hyphens. An empty result falls back to {lit}`font`.
+-/
+public def slugFamily (family : String) : String := Id.run do
+  let mut buf := ""
+  let mut prevHyphen := true
+  for c in family.toList do
+    let safe := c.isAlphanum || c == '-' || c == '_' || c == '.'
+    if safe then
+      buf := buf.push c
+      prevHyphen := false
+    else if !prevHyphen then
+      buf := buf.push '-'
+      prevHyphen := true
+  let mut s := buf
+  while s.endsWith "-" do s := (String.dropEnd s 1).copy
+  if s.isEmpty then s := "font"
+  return s
+
+/--
+Output-relative paths and bytes of every font file the theme uses. Each file is named
+{lit}`<slug>-<index>.<ext>` where {lit}`<slug>` is {Lean.Doc.name}`Verso.Theme.CodeTheme.slugFamily`
+applied to the family. The {lit}`assetRoot` is the directory the paths are relative to (no
+leading or trailing slash); the generated {lit}`@font-face` {lit}`url()`s also resolve from there.
+-/
+public def fontAssets (theme : CodeTheme) (assetRoot : String) :
+    Array (String × ByteArray × FontFace × String) := Id.run do
+  let mut out := #[]
+  for tf in theme.fileTypefaces do
+    if let .files family faces := tf then
+      let slug := slugFamily family
+      for (face, i) in faces.zipIdx do
+        let path := s!"{assetRoot}/fonts/{slug}-{i}.{face.format.ext}"
+        out := out.push (path, face.bytes, face, family)
+  return out
+
+private def weightDecl : FaceWeights → String
+  | .fixed w => toString w.val
+  | .variable lo hi _ => s!"{lo.val} {hi.val}"
+
+private def styleString : FontStyle → String
+  | .normal => "normal"
+  | .italic => "italic"
+
+/--
+The {lit}`@font-face` rules for every {Lean.Doc.name (full := Verso.Typeface.files)}`files`
+typeface the theme uses. The {lit}`url()` paths are relative, so the rules resolve from whatever
+stylesheet they end up in (in the manual genre, {lit}`verso-themes.css` at the site root).
+-/
+public def fontFaceRules (theme : CodeTheme) (assetRoot : String) : String := Id.run do
+  let mut out := ""
+  for (path, _bytes, face, family) in theme.fontAssets assetRoot do
+    out := out ++ s!"@font-face \{\n"
+    out := out ++ s!"  font-family: {cssQuote family};\n"
+    out := out ++ s!"  font-weight: {weightDecl face.weights};\n"
+    out := out ++ s!"  font-style: {styleString face.style};\n"
+    out := out ++ s!"  src: url({cssQuote path}) format({cssQuote face.format.css});\n"
+    out := out ++ "}\n"
+  return out
+
+end CodeTheme
diff --git a/src/verso/Verso/Theme/Code/Defaults.lean b/src/verso/Verso/Theme/Code/Defaults.lean
new file mode 100644
index 000000000..d5488e7ba
--- /dev/null
+++ b/src/verso/Verso/Theme/Code/Defaults.lean
@@ -0,0 +1,27 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+public import Verso.Theme.Code
+
+set_option linter.missingDocs true
+set_option doc.verso true
+
+/-!
+The built-in {Lean.Doc.name}`Verso.Theme.CodeTheme` values. The default theme reproduces today's
+hardcoded look so existing manuals render unchanged when no override is configured.
+-/
+
+namespace Verso.Theme
+
+/--
+The default code theme: typography-only styling that reproduces today's hardcoded look. Other
+built-in themes live alongside it in the {Lean.Doc.name}`Verso.Theme.CodeTheme` namespace.
+-/
+@[code_theme]
+public def CodeTheme.Default : CodeTheme where
+  name := "Default"
+  appearance := .light
diff --git a/src/verso/Verso/Theme/Code/Ext.lean b/src/verso/Verso/Theme/Code/Ext.lean
new file mode 100644
index 000000000..2deb49c99
--- /dev/null
+++ b/src/verso/Verso/Theme/Code/Ext.lean
@@ -0,0 +1,28 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+public import Lean.Environment
+
+public section
+
+open Lean
+
+namespace Verso.Theme
+
+/--
+Environment extension that records every declaration tagged with the `@[code_theme]` attribute.
+Each entry maps the registration name (the decl, erased of macro scopes) to itself, so the table
+is keyed and iterated by registration name.
+-/
+initialize codeThemeExt :
+    PersistentEnvExtension Name Name (NameSet) ←
+  registerPersistentEnvExtension {
+    mkInitial := pure {},
+    addImportedFn := fun _ => pure {},
+    addEntryFn := fun s n => s.insert n,
+    exportEntriesFn := fun s =>
+      s.toArray.qsort Name.quickLt
+  }
diff --git a/src/verso/Verso/Theme/Color.lean b/src/verso/Verso/Theme/Color.lean
new file mode 100644
index 000000000..16e17c2ee
--- /dev/null
+++ b/src/verso/Verso/Theme/Color.lean
@@ -0,0 +1,13 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+public import Verso.Theme.Color.Types
+public import Verso.Theme.Color.Basic
+public import Verso.Theme.Color.Math
+public import Verso.Theme.Color.Accessibility
+public import Verso.Theme.Color.Widget
+public import Verso.Theme.Color.Syntax
diff --git a/src/verso/Verso/Color/Accessibility.lean b/src/verso/Verso/Theme/Color/Accessibility.lean
similarity index 88%
rename from src/verso/Verso/Color/Accessibility.lean
rename to src/verso/Verso/Theme/Color/Accessibility.lean
index 70fa21000..2c59cef5b 100644
--- a/src/verso/Verso/Color/Accessibility.lean
+++ b/src/verso/Verso/Theme/Color/Accessibility.lean
@@ -5,8 +5,8 @@ Author: David Thrane Christiansen
 -/
 module
 
-public import Verso.Color.Types
-public import Verso.Color.Math
+public import Verso.Theme.Color.Types
+public import Verso.Theme.Color.Math
 
 set_option linter.missingDocs true
 set_option doc.verso true
@@ -20,7 +20,7 @@ This module contains genre-neutral accessibility predicates and checks built on
 
 -/
 
-namespace Verso
+namespace Verso.Theme
 
 namespace Color
 
@@ -32,8 +32,7 @@ deriving DecidableEq, Repr
 
 /--
 An accessibility problem found while checking a set of colors. It carries no severity; the caller
-maps {name}`IssueKind` to a severity. {lit}`offending` lists the colors involved, for error
-messages.
+maps {name}`IssueKind` to a severity. The offending colors are recorded for error messages.
 -/
 public structure Issue where
   /-- Whether this is a contrast or a color-vision-deficiency problem. -/
@@ -56,11 +55,11 @@ palette (which stays above it under all three dichromacies).
 -/
 public def distinguishableThreshold : Float := 5.0
 
-/-- Whether {lit}`fg` on {lit}`bg` meets the given WCAG contrast ratio. -/
+/-- Whether a foreground on a background meets the given WCAG contrast ratio. -/
 public def meetsContrast (threshold : Float) (fg bg : Color) : Bool :=
   contrastRatio fg bg ≥ threshold
 
-/-- Whether two colors differ by at least {lit}`threshold` in CIEDE2000 ΔE. -/
+/-- Whether two colors differ by at least the given threshold in CIEDE2000 ΔE. -/
 public def distinguishable? (threshold : Float) (c1 c2 : Color) : Bool :=
   deltaE c1 c2 ≥ threshold
 
@@ -69,9 +68,9 @@ public def isOpaque : Color → Bool
   | .rgba _ _ _ a => a == 255
 
 /--
-Composites {lit}`fg` over {lit}`bg` using {lit}`fg`'s alpha (straight alpha in sRGB, matching how a
-browser paints translucent content on a solid background). The result is opaque; the background's
-own alpha is ignored.
+Composites a foreground over a background using the foreground's alpha (straight alpha in sRGB,
+matching how a browser paints translucent content on a solid background). The result is opaque; the
+background's own alpha is ignored.
 -/
 public def over (fg bg : Color) : Color :=
   match fg, bg with
diff --git a/src/verso/Verso/Color/Basic.lean b/src/verso/Verso/Theme/Color/Basic.lean
similarity index 95%
rename from src/verso/Verso/Color/Basic.lean
rename to src/verso/Verso/Theme/Color/Basic.lean
index ca3df7b4c..191a0bbf2 100644
--- a/src/verso/Verso/Color/Basic.lean
+++ b/src/verso/Verso/Theme/Color/Basic.lean
@@ -5,17 +5,17 @@ Author: David Thrane Christiansen
 -/
 module
 
-public import Verso.Color.Types
+public import Verso.Theme.Color.Types
 
 set_option linter.missingDocs true
 set_option doc.verso true
 
 /-!
-The pure Lean API for {name (full := Verso.Color)}`Color`: a small set of named colors, CSS and TeX
+The pure Lean API for {name (full := Verso.Theme.Color)}`Color`: a small set of named colors, CSS and TeX
 rendering, and parsing of hex color strings.
 -/
 
-namespace Verso.Color
+namespace Verso.Theme.Color
 
 /--
 Constructs an opaque color.
diff --git a/src/verso/Verso/Color/Math.lean b/src/verso/Verso/Theme/Color/Math.lean
similarity index 98%
rename from src/verso/Verso/Color/Math.lean
rename to src/verso/Verso/Theme/Color/Math.lean
index c25f6fe03..66746c93a 100644
--- a/src/verso/Verso/Color/Math.lean
+++ b/src/verso/Verso/Theme/Color/Math.lean
@@ -5,7 +5,7 @@ Author: David Thrane Christiansen
 -/
 module
 
-public import Verso.Color.Types
+public import Verso.Theme.Color.Types
 
 set_option linter.missingDocs true
 set_option doc.verso true
@@ -31,10 +31,10 @@ Color math for accessibility checking, using the following:
   apart, including under the simulations above.
 
 All channels convert to {name}`Float` at the boundary (`/255`) and the math runs in {name}`Float`;
-the {name (full := Verso.Color)}`Color` type itself stays byte-exact.
+the {name (full := Verso.Theme.Color)}`Color` type itself stays byte-exact.
 -/
 
-namespace Verso
+namespace Verso.Theme
 
 namespace Color
 
diff --git a/src/verso/Verso/Color/Syntax.lean b/src/verso/Verso/Theme/Color/Syntax.lean
similarity index 91%
rename from src/verso/Verso/Color/Syntax.lean
rename to src/verso/Verso/Theme/Color/Syntax.lean
index 713c71af6..3ff0f8d76 100644
--- a/src/verso/Verso/Color/Syntax.lean
+++ b/src/verso/Verso/Theme/Color/Syntax.lean
@@ -14,13 +14,13 @@ public import Lean.PrettyPrinter.Formatter
 public import Lean.Elab.Term
 meta import Lean.PrettyPrinter
 meta import Lean.Elab.Term
-public meta import Verso.Color.Basic
-public meta import Verso.Color.Widget
+public meta import Verso.Theme.Color.Basic
+public meta import Verso.Theme.Color.Widget
 
 set_option linter.missingDocs true
 set_option doc.verso true
 
-namespace Verso
+namespace Verso.Theme
 
 public section
 
@@ -76,13 +76,13 @@ private meta def asHexString (stx : TSyntax colorHexKind) : String :=
 
 /--
 A color literal: `color%#rgb`, `color%#rrggbb`, or `color%#rrggbbaa` (case-insensitive hex, no space
-before the `#`). It is an ordinary term, usable anywhere a {name (full := Verso.Color)}`Color` is
+before the `#`). It is an ordinary term, usable anywhere a {name (full := Verso.Theme.Color)}`Color` is
 expected, including in structure-field defaults.
 -/
 syntax (name := colorLit) "color%" noWs colorHex : term
 
 open Elab Term in
-/-- Elaborates a {lit}`color%` literal to a {name (full := Verso.Color)}`Color` and attaches the
+/-- Elaborates a {lit}`color%` literal to a {name (full := Verso.Theme.Color)}`Color` and attaches the
 preview widget. -/
 @[term_elab colorLit]
 meta def elabColorLit : TermElab := fun stx expectedType? => do
@@ -94,6 +94,6 @@ meta def elabColorLit : TermElab := fun stx expectedType? => do
     | .error msg => throwErrorAt hexStx msg
   saveColorWidget (.rgba r g b a) stx
   let lit (n : UInt8) : Term := ⟨Syntax.mkNumLit (toString n.toNat)⟩
-  elabTerm (← `(Verso.Color.rgba $(lit r) $(lit g) $(lit b) $(lit a))) expectedType?
+  elabTerm (← `(Verso.Theme.Color.rgba $(lit r) $(lit g) $(lit b) $(lit a))) expectedType?
 
 end
diff --git a/src/verso/Verso/Color/Types.lean b/src/verso/Verso/Theme/Color/Types.lean
similarity index 97%
rename from src/verso/Verso/Color/Types.lean
rename to src/verso/Verso/Theme/Color/Types.lean
index 10ae38417..3f4419f03 100644
--- a/src/verso/Verso/Color/Types.lean
+++ b/src/verso/Verso/Theme/Color/Types.lean
@@ -8,7 +8,7 @@ module
 set_option linter.missingDocs true
 set_option doc.verso true
 
-namespace Verso
+namespace Verso.Theme
 
 -- This is an inductive with a single `rgba` constructor rather than a structure so that other color
 -- models (such as wide-gamut `oklch`) can be added later. The byte channels give a canonical
diff --git a/src/verso/Verso/Color/Widget.lean b/src/verso/Verso/Theme/Color/Widget.lean
similarity index 91%
rename from src/verso/Verso/Color/Widget.lean
rename to src/verso/Verso/Theme/Color/Widget.lean
index 28c880903..e04ed33ec 100644
--- a/src/verso/Verso/Color/Widget.lean
+++ b/src/verso/Verso/Theme/Color/Widget.lean
@@ -6,8 +6,8 @@ Author: David Thrane Christiansen
 module
 
 public meta import Lean.Widget.UserWidget
-public meta import Verso.Color.Basic
-public meta import Verso.Color.Math
+public meta import Verso.Theme.Color.Basic
+public meta import Verso.Theme.Color.Math
 
 set_option linter.missingDocs true
 set_option doc.verso true
@@ -17,7 +17,7 @@ The InfoView preview widget for colors. The CSS form is computed in Lean and han
 so the JavaScript only has to draw the swatch.
 -/
 
-namespace Verso
+namespace Verso.Theme
 
 public section
 
diff --git a/src/verso/Verso/Color/color-swatch.js b/src/verso/Verso/Theme/Color/color-swatch.js
similarity index 100%
rename from src/verso/Verso/Color/color-swatch.js
rename to src/verso/Verso/Theme/Color/color-swatch.js

From a08d0d98ea10c29448bdd5a4b9e1ba90255494ae Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Sat, 30 May 2026 13:33:27 +0200
Subject: [PATCH 07/31] feat: code TeX themes

Extends code themes to TeX output
---
 src/tests/TestMain.lean                       |   2 +-
 src/tests/Tests/Font.lean                     |  22 +++
 src/tests/Tests/HighlightedToTeX.lean         |  65 ++++++++
 .../code-content-doc/expected/tex/main.tex    | 145 ++++++++++--------
 .../diagram-doc/expected/tex/main.tex         |  29 +++-
 .../extra-files-doc/expected/tex/main.tex     |  29 +++-
 .../front-matter-doc/expected/tex/main.tex    |  29 +++-
 .../inheritance-doc/expected/tex/main.tex     |  31 +++-
 .../sample-doc/expected/tex/main.tex          |  31 +++-
 src/verso-manual/VersoManual.lean             |   8 +-
 src/verso-manual/VersoManual/TeX.lean         |  22 ++-
 src/verso-search/VersoSearch.lean             |   2 +-
 src/verso/Verso/Code/HighlightedToTex.lean    |  53 +++++--
 src/verso/Verso/Font.lean                     |  13 ++
 src/verso/Verso/Theme/Code.lean               |  87 ++++++++++-
 15 files changed, 437 insertions(+), 131 deletions(-)

diff --git a/src/tests/TestMain.lean b/src/tests/TestMain.lean
index 8e3059af5..0d4f19b75 100644
--- a/src/tests/TestMain.lean
+++ b/src/tests/TestMain.lean
@@ -57,7 +57,7 @@ def testTexOutput
   let runTest : IO Unit  :=
     open Verso Genre Manual in do
     let logger ← Verso.Logger.new
-    emitTeX versoConfig doc.toPart |>.run extension_impls% |>.run logger
+    emitTeX ({ versoConfig with : RenderConfig }) doc.toPart |>.run extension_impls% |>.run logger
 
   Verso.Integration.runTests { config with
     testDir := "src/tests/integration" / dir,
diff --git a/src/tests/Tests/Font.lean b/src/tests/Tests/Font.lean
index b311d70cf..49f88dac3 100644
--- a/src/tests/Tests/Font.lean
+++ b/src/tests/Tests/Font.lean
@@ -4,6 +4,8 @@ Released under Apache 2.0 license as described in the file LICENSE.
 Author: David Thrane Christiansen
 -/
 import Verso.Font
+import Verso.Theme.Code
+import Verso.Theme.Code.Defaults
 
 /-!
 Compile-time tests for `Verso.Font`: the `define_font_face` command embeds file bytes, `Weight`
@@ -68,3 +70,23 @@ define_font_face noFormat where
 #guard_msgs in
 define_font_face noFile where
   format := .ttf
+
+-- `slugFamily` keeps a usable hyphen-separated tail and falls back to "font" for empty input.
+/-- info: "Source-Sans-3" -/
+#guard_msgs in #eval Verso.Theme.CodeTheme.slugFamily "Source Sans 3"
+/-- info: "Fira-Mono" -/
+#guard_msgs in #eval Verso.Theme.CodeTheme.slugFamily "Fira/Mono"
+/-- info: "font" -/
+#guard_msgs in #eval Verso.Theme.CodeTheme.slugFamily "///"
+
+-- Two distinct families that slug to the same string get distinct asset paths via the typeface
+-- index, so one font's bytes can never overwrite the other.
+def collidingTheme : Verso.Theme.CodeTheme := {
+  Verso.Theme.CodeTheme.Default with
+  codeFace := .files "A B" #[katexMono],
+  const := { color := color%#000000, weight := .regular, style := .normal,
+             face := .files "A/B" #[katexMono] }
+}
+
+/-- info: #["assets/fonts/A-B-0-0.woff2", "assets/fonts/A-B-1-0.woff2"] -/
+#guard_msgs in #eval (collidingTheme.fontAssets "assets").map (·.1)
diff --git a/src/tests/Tests/HighlightedToTeX.lean b/src/tests/Tests/HighlightedToTeX.lean
index dba4aa078..caaf2a817 100644
--- a/src/tests/Tests/HighlightedToTeX.lean
+++ b/src/tests/Tests/HighlightedToTeX.lean
@@ -5,6 +5,11 @@ Author: Jason Reed
 -/
 module
 meta import all Verso.Code.HighlightedToTex
+public import Verso.Theme.Code
+public import Verso.Theme.Code.Defaults
+public import Verso.Font
+meta import all Verso.Theme.Code
+meta import all Verso.Theme.Code.Defaults
 open Verso.Doc.TeX (escapeForVerbatim)
 
 open SubVerso.Highlighting
@@ -12,3 +17,63 @@ open SubVerso.Highlighting
 /-- info: "\\symbol{123}\\symbol{124}\\symbol{125}\\symbol{92}" -/
 #guard_msgs in
 #eval escapeForVerbatim "{|}\\"
+
+/-! Token rendering wraps each semantic category in a `\verso…` macro. The four categories cover
+keywords, constants (including anonymous constructors and options), variables, and a catch-all
+literal bucket. -/
+
+/-- info: "\\versoKeyword{def}" -/
+#guard_msgs in #eval (highlightToken "def" (.keyword none none "")).asString
+
+/-- info: "\\versoConst{foo}" -/
+#guard_msgs in #eval (highlightToken "foo" (.const `foo "" none false none)).asString
+
+/-- info: "\\versoVar{x}" -/
+#guard_msgs in #eval (highlightToken "x" (.var ⟨`x⟩ "" none)).asString
+
+/-- info: "\\versoLiteral{42}" -/
+#guard_msgs in #eval (highlightToken "42" .unknown).asString
+
+/-! The fallback macro block defines the four `\verso…` macros with `\providecommand`, so a
+preamble that defines its own (theme-driven) versions wins without an explicit `\renewcommand`. -/
+
+/--
+info: "\\providecommand{\\versoKeyword}[1]{\\textbf{#1}}\n\\providecommand{\\versoConst}[1]{#1}\n\\providecommand{\\versoVar}[1]{\\textit{#1}}\n\\providecommand{\\versoLiteral}[1]{#1}\n"
+-/
+#guard_msgs in #eval texMacroFallbacks
+
+/-! The default code theme emits `\definecolor` blocks for its token and severity colors and
+redefines each `\verso…` macro to apply the resolved color, weight, and style. -/
+
+private def hasSub (s sub : String) : Bool := (s.splitOn sub).length > 1
+
+/-- info: true -/
+#guard_msgs in
+#eval
+  let p := Verso.Theme.CodeTheme.Default.texPreamble
+  -- Message-text and accent colors are emitted under distinct names: `errorColor` is the
+  -- message-body color (#cc0000 by default), `errorIndicatorColor` is the wavy-underline
+  -- accent (#ff0000). The keyword macro picks up bold (NFSS `eb`), and the mono font is
+  -- the bundled DejaVu Sans Mono.
+  hasSub p "\\definecolor{errorColor}{HTML}{CC0000}" &&
+  hasSub p "\\definecolor{errorIndicatorColor}{HTML}{FF0000}" &&
+  hasSub p "\\renewcommand{\\versoKeyword}[1]{\\textcolor{versoKeywordColor}{\\fontseries{eb}\\fontshape{n}\\selectfont #1}}" &&
+  hasSub p "\\setmonofont{DejaVu Sans Mono}"
+
+/-! A deliberately colorful theme really does color and style the keyword and const tokens. -/
+
+open Verso Verso.Theme in
+private def colorfulTheme : CodeTheme := {
+  CodeTheme.Default with
+  keyword := { color := color%#aa3300, weight := 600, style := .normal, face := .mono },
+  const := { color := color%#0044bb, weight := .regular, style := .italic, face := .mono }
+}
+
+/-- info: true -/
+#guard_msgs in
+#eval
+  let p := colorfulTheme.texPreamble
+  hasSub p "\\definecolor{versoKeywordColor}{HTML}{AA3300}" &&
+  hasSub p "\\renewcommand{\\versoKeyword}[1]{\\textcolor{versoKeywordColor}{\\fontseries{b}\\fontshape{n}\\selectfont #1}}" &&
+  hasSub p "\\definecolor{versoConstColor}{HTML}{0044BB}" &&
+  hasSub p "\\renewcommand{\\versoConst}[1]{\\textcolor{versoConstColor}{\\fontseries{m}\\fontshape{it}\\selectfont #1}}"
diff --git a/src/tests/integration/code-content-doc/expected/tex/main.tex b/src/tests/integration/code-content-doc/expected/tex/main.tex
index 2c081701c..9b8486643 100644
--- a/src/tests/integration/code-content-doc/expected/tex/main.tex
+++ b/src/tests/integration/code-content-doc/expected/tex/main.tex
@@ -51,12 +51,11 @@
 % Work around missing U+2011 (non-breaking hyphen) in Source Serif Pro
 \newunicodechar{‑}{-}
 
-\definecolor{errorColor}{HTML}{B91C1C}
-\definecolor{infoColor}{HTML}{1E6BB8}
-\definecolor{warningColor}{HTML}{D97706}
-\newcommand{\errorDecorate}[1]{\coloredwave{errorColor}{#1}}
-\newcommand{\infoDecorate}[1]{\coloredwave{infoColor}{#1}}
-\newcommand{\warningDecorate}[1]{\coloredwave{warningColor}{#1}}
+% Decoration accents (wavy underlines) use the *indicator* colors, distinct from the message
+% text colors. The theme block below redefines both.
+\newcommand{\errorDecorate}[1]{\coloredwave{errorIndicatorColor}{#1}}
+\newcommand{\infoDecorate}[1]{\coloredwave{infoIndicatorColor}{#1}}
+\newcommand{\warningDecorate}[1]{\coloredwave{warningIndicatorColor}{#1}}
 \DefineVerbatimEnvironment{LeanVerbatim}{Verbatim}
   {commandchars=\\\{\},fontsize=\small,breaklines=true}
 \DefineVerbatimEnvironment{FileVerbatim}{Verbatim}{commandchars=\\\{\},fontsize=\small,breaklines=true,frame=single,framesep=2mm,numbers=left}
@@ -124,6 +123,24 @@
 \renewcommand{\cftsectionfont}{\normalfont\sffamily}
 \renewcommand{\cftchapterpagefont}{\normalfont\sffamily}
 \renewcommand{\cftsectionpagefont}{\normalfont\sffamily}
+\providecommand{\versoKeyword}[1]{\textbf{#1}}
+\providecommand{\versoConst}[1]{#1}
+\providecommand{\versoVar}[1]{\textit{#1}}
+\providecommand{\versoLiteral}[1]{#1}
+\definecolor{versoCodeColor}{HTML}{000000}
+\definecolor{versoConstColor}{HTML}{000000}
+\definecolor{versoKeywordColor}{HTML}{000000}
+\definecolor{versoVarColor}{HTML}{000000}
+\definecolor{errorColor}{HTML}{CC0000}
+\definecolor{warningColor}{HTML}{000000}
+\definecolor{infoColor}{HTML}{000000}
+\definecolor{errorIndicatorColor}{HTML}{FF0000}
+\definecolor{warningIndicatorColor}{HTML}{E7A71D}
+\definecolor{infoIndicatorColor}{HTML}{4777FF}
+\renewcommand{\versoKeyword}[1]{\textcolor{versoKeywordColor}{\fontseries{eb}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoConst}[1]{\textcolor{versoConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoVar}[1]{\textcolor{versoVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoLiteral}[1]{\textcolor{versoCodeColor}{#1}}
 \setmonofont{DejaVu Sans Mono}
 
 \title{\sffamily Title of the Doc}
@@ -144,72 +161,72 @@
 \cleardoublepage
 Here is some code with vertical bars:
 \begin{LeanVerbatim}
-\textbf{def} or := (· \symbol{124}\symbol{124} ·)
-
+\versoKeyword{def} \versoConst{or} \versoLiteral{:=} \versoLiteral{(}\versoLiteral{·} \versoLiteral{\symbol{124}\symbol{124}} \versoLiteral{·}\versoLiteral{)}
+\versoLiteral{}
 \end{LeanVerbatim}
 
 Here is some with a variety of interesting Unicode, including characters where UTF-16 is funky:
 \begin{LeanVerbatim}
-\textbf{def} Set (\textit{α} : Type u) : Type u := \textit{α} → Prop
-
-\textbf{instance} : EmptyCollection (Set \textit{α}) \textbf{where}
-  emptyCollection := \textbf{fun} _ => False
-
-\textbf{instance} : Union (Set \textit{α}) \textbf{where}
-  union \textit{a} \textit{b} := \textbf{fun} \textit{x} => \textit{a} \textit{x} ∨ \textit{b} \textit{x}
-
-\textbf{instance} : Inter (Set \textit{α}) \textbf{where}
-  inter \textit{a} \textit{b} := \textbf{fun} \textit{x} => \textit{a} \textit{x} ∧ \textit{b} \textit{x}
-
-\textbf{instance} : Membership \textit{α} (Set \textit{α}) \textbf{where}
-  mem \textit{a} \textit{x} := \textit{a} \textit{x}
-
-@[\textbf{ext}]
-\textbf{theorem} Set.ext \symbol{123}\textit{a} \textit{b} : Set \textit{α}\symbol{125} :
-    (∀ \textit{x}, \textit{x} ∈ \textit{a} ↔ \textit{x} ∈ \textit{b}) → \textit{a} = \textit{b} := \textbf{by}
-  \textbf{intro} \textit{h}
-  \textbf{funext} \textit{x}
-  \textbf{exact} propext (\textit{h} \textit{x})
-
-\textbf{instance} : HasSubset (Set \textit{α}) \textbf{where}
-  Subset \textit{a} \textit{b} := ∀ \textit{x}, \textit{x} ∈ \textit{a} → \textit{x} ∈ \textit{b}
-
-@[\textbf{simp}, \textbf{grind} .]
-\textbf{theorem} Set.subset_refl \symbol{123}\textit{a} : Set \textit{α}\symbol{125} : \textit{a} ⊆ \textit{a} := \textbf{by}
-  \textbf{simp} [(· ⊆ ·)]
-
-@[\textbf{grind} ←]
-\textbf{theorem} Set.subset_union \symbol{123}\textit{a} \textit{b} \textit{c} : Set \textit{α}\symbol{125} :
-    \textit{a} ⊆ \textit{b} → \textit{a} ⊆ \textit{b} ∪ \textit{c} := \textbf{by}
-  \textbf{simp} [(· ⊆ ·), (· ∪ ·), (· ∈ ·)]
-  \textbf{intro} \textit{h}
-  \textbf{solve_by_elim}
-
-\textbf{def} Set.powerset (\textit{a} : Set \textit{α}) : Set (Set \textit{α}) :=
-  \textbf{fun} (\textit{x} : Set \textit{α}) => \textit{x} ⊆ \textit{a}
-
-\textbf{notation} "𝒫 " \textit{x} => Set.powerset \textit{x}
-
-\textbf{theorem} Set.powerset_empty_nonempty :
-    ∃ (\textit{a} : Set \textit{α}), \textit{a} ∈ 𝒫 \symbol{123}\symbol{125} := \textbf{by}
-  \textbf{constructor}
-  \textbf{case} w => \textbf{exact} \symbol{123}\symbol{125}
-  \textbf{simp} [(· ∈ ·), powerset]
-
-@[\infoDecorate{\textbf{grind?} →}]
-\textbf{theorem} Set.powerset_empty_unique (\textit{x} \textit{y} : Set \textit{α}) :
-    \textit{x} ∈ (𝒫 \symbol{123}\symbol{125}) → \textit{y} ∈ (𝒫 \symbol{123}\symbol{125}) → \textit{x} = \textit{y} := \textbf{by}
-  \textbf{intro} \textit{hx} \textit{hy}
-  \textbf{ext} \textit{x'}
-  \textbf{exact} (iff_false_right (\textit{hy} \textit{x'})).mpr (\textit{hx} \textit{x'})
-
+\versoKeyword{def} \versoConst{Set} \versoLiteral{(}\versoVar{α} \versoLiteral{:} \versoLiteral{Type} \versoLiteral{u}\versoLiteral{)} \versoLiteral{:} \versoLiteral{Type} \versoLiteral{u} \versoLiteral{:=} \versoVar{α} \versoLiteral{→} \versoLiteral{Prop}
+
+\versoKeyword{instance} \versoLiteral{:} \versoConst{EmptyCollection} \versoLiteral{(}\versoConst{Set} \versoVar{α}\versoLiteral{)} \versoKeyword{where}
+  \versoConst{emptyCollection} \versoLiteral{:=} \versoKeyword{fun} \versoLiteral{_} \versoLiteral{=>} \versoConst{False}
+
+\versoKeyword{instance} \versoLiteral{:} \versoConst{Union} \versoLiteral{(}\versoConst{Set} \versoVar{α}\versoLiteral{)} \versoKeyword{where}
+  \versoConst{union} \versoVar{a} \versoVar{b} \versoLiteral{:=} \versoKeyword{fun} \versoVar{x} \versoLiteral{=>} \versoVar{a} \versoVar{x} \versoLiteral{∨} \versoVar{b} \versoVar{x}
+
+\versoKeyword{instance} \versoLiteral{:} \versoConst{Inter} \versoLiteral{(}\versoConst{Set} \versoVar{α}\versoLiteral{)} \versoKeyword{where}
+  \versoConst{inter} \versoVar{a} \versoVar{b} \versoLiteral{:=} \versoKeyword{fun} \versoVar{x} \versoLiteral{=>} \versoVar{a} \versoVar{x} \versoLiteral{∧} \versoVar{b} \versoVar{x}
+
+\versoKeyword{instance} \versoLiteral{:} \versoConst{Membership} \versoVar{α} \versoLiteral{(}\versoConst{Set} \versoVar{α}\versoLiteral{)} \versoKeyword{where}
+  \versoConst{mem} \versoVar{a} \versoVar{x} \versoLiteral{:=} \versoVar{a} \versoVar{x}
+
+\versoLiteral{@[}\versoKeyword{ext}\versoLiteral{]}
+\versoKeyword{theorem} \versoConst{Set.ext} \versoLiteral{\symbol{123}}\versoVar{a} \versoVar{b} \versoLiteral{:} \versoConst{Set} \versoVar{α}\versoLiteral{\symbol{125}} \versoLiteral{:}
+    \versoLiteral{(}\versoLiteral{∀} \versoVar{x}\versoLiteral{,} \versoVar{x} \versoLiteral{∈} \versoVar{a} \versoLiteral{↔} \versoVar{x} \versoLiteral{∈} \versoVar{b}\versoLiteral{)} \versoLiteral{→} \versoVar{a} \versoLiteral{=} \versoVar{b} \versoLiteral{:=} \versoKeyword{by}
+  \versoKeyword{intro} \versoVar{h}
+  \versoKeyword{funext} \versoVar{x}
+  \versoKeyword{exact} \versoConst{propext} \versoLiteral{(}\versoVar{h} \versoVar{x}\versoLiteral{)}
+
+\versoKeyword{instance} \versoLiteral{:} \versoConst{HasSubset} \versoLiteral{(}\versoConst{Set} \versoVar{α}\versoLiteral{)} \versoKeyword{where}
+  \versoConst{Subset} \versoVar{a} \versoVar{b} \versoLiteral{:=} \versoLiteral{∀} \versoVar{x}\versoLiteral{,} \versoVar{x} \versoLiteral{∈} \versoVar{a} \versoLiteral{→} \versoVar{x} \versoLiteral{∈} \versoVar{b}
+
+\versoLiteral{@[}\versoKeyword{simp}\versoLiteral{,} \versoKeyword{grind} \versoLiteral{.}\versoLiteral{]}
+\versoKeyword{theorem} \versoConst{Set.subset_refl} \versoLiteral{\symbol{123}}\versoVar{a} \versoLiteral{:} \versoConst{Set} \versoVar{α}\versoLiteral{\symbol{125}} \versoLiteral{:} \versoVar{a} \versoLiteral{⊆} \versoVar{a} \versoLiteral{:=} \versoKeyword{by}
+  \versoKeyword{simp} \versoLiteral{[}\versoLiteral{(}\versoLiteral{·} \versoLiteral{⊆} \versoLiteral{·}\versoLiteral{)}\versoLiteral{]}
+
+\versoLiteral{@[}\versoKeyword{grind} \versoLiteral{←}\versoLiteral{]}
+\versoKeyword{theorem} \versoConst{Set.subset_union} \versoLiteral{\symbol{123}}\versoVar{a} \versoVar{b} \versoVar{c} \versoLiteral{:} \versoConst{Set} \versoVar{α}\versoLiteral{\symbol{125}} \versoLiteral{:}
+    \versoVar{a} \versoLiteral{⊆} \versoVar{b} \versoLiteral{→} \versoVar{a} \versoLiteral{⊆} \versoVar{b} \versoLiteral{∪} \versoVar{c} \versoLiteral{:=} \versoKeyword{by}
+  \versoKeyword{simp} \versoLiteral{[}\versoLiteral{(}\versoLiteral{·} \versoLiteral{⊆} \versoLiteral{·}\versoLiteral{)}\versoLiteral{,} \versoLiteral{(}\versoLiteral{·} \versoLiteral{∪} \versoLiteral{·}\versoLiteral{)}\versoLiteral{,} \versoLiteral{(}\versoLiteral{·} \versoLiteral{∈} \versoLiteral{·}\versoLiteral{)}\versoLiteral{]}
+  \versoKeyword{intro} \versoVar{h}
+  \versoKeyword{solve_by_elim}
+
+\versoKeyword{def} \versoConst{Set.powerset} \versoLiteral{(}\versoVar{a} \versoLiteral{:} \versoConst{Set} \versoVar{α}\versoLiteral{)} \versoLiteral{:} \versoConst{Set} \versoLiteral{(}\versoConst{Set} \versoVar{α}\versoLiteral{)} \versoLiteral{:=}
+  \versoKeyword{fun} \versoLiteral{(}\versoVar{x} \versoLiteral{:} \versoConst{Set} \versoVar{α}\versoLiteral{)} \versoLiteral{=>} \versoVar{x} \versoLiteral{⊆} \versoVar{a}
+
+\versoKeyword{notation} \versoLiteral{"𝒫 "} \versoVar{x} \versoLiteral{=>} \versoConst{Set.powerset} \versoVar{x}
+
+\versoKeyword{theorem} \versoConst{Set.powerset_empty_nonempty} \versoLiteral{:}
+    \versoLiteral{∃} \versoLiteral{(}\versoVar{a} \versoLiteral{:} \versoConst{Set} \versoVar{α}\versoLiteral{)}\versoLiteral{,} \versoVar{a} \versoLiteral{∈} \versoLiteral{𝒫} \versoLiteral{\symbol{123}}\versoLiteral{\symbol{125}} \versoLiteral{:=} \versoKeyword{by}
+  \versoKeyword{constructor}
+  \versoKeyword{case} \versoLiteral{w} \versoLiteral{=>} \versoKeyword{exact} \versoLiteral{\symbol{123}}\versoLiteral{\symbol{125}}
+  \versoKeyword{simp} \versoLiteral{[}\versoLiteral{(}\versoLiteral{·} \versoLiteral{∈} \versoLiteral{·}\versoLiteral{)}\versoLiteral{,} \versoConst{powerset}\versoLiteral{]}
+
+\versoLiteral{@[}\infoDecorate{\versoKeyword{grind?} \versoLiteral{→}}\versoLiteral{]}
+\versoKeyword{theorem} \versoConst{Set.powerset_empty_unique} \versoLiteral{(}\versoVar{x} \versoVar{y} \versoLiteral{:} \versoConst{Set} \versoVar{α}\versoLiteral{)} \versoLiteral{:}
+    \versoVar{x} \versoLiteral{∈} \versoLiteral{(}\versoLiteral{𝒫} \versoLiteral{\symbol{123}}\versoLiteral{\symbol{125}}\versoLiteral{)} \versoLiteral{→} \versoVar{y} \versoLiteral{∈} \versoLiteral{(}\versoLiteral{𝒫} \versoLiteral{\symbol{123}}\versoLiteral{\symbol{125}}\versoLiteral{)} \versoLiteral{→} \versoVar{x} \versoLiteral{=} \versoVar{y} \versoLiteral{:=} \versoKeyword{by}
+  \versoKeyword{intro} \versoVar{hx} \versoVar{hy}
+  \versoKeyword{ext} \versoVar{x'}
+  \versoKeyword{exact} \versoLiteral{(}\versoConst{iff_false_right} \versoLiteral{(}\versoVar{hy} \versoVar{x'}\versoLiteral{)}\versoLiteral{)}\versoLiteral{.}\versoConst{mpr} \versoLiteral{(}\versoVar{hx} \versoVar{x'}\versoLiteral{)}
+\versoLiteral{}
 \end{LeanVerbatim}
 
 And now some inline code:
 \begin{itemize}
-\item \LeanVerb|∀\textit{x} \textit{y} : Set _, \textit{x} ∈ ((𝒫 \textit{x}) ∪ (𝒫 \textit{y}))|
-\item \LeanVerb|true \symbol{124}\symbol{124} false|
-\item \LeanVerb|False → True|
+\item \LeanVerb|\versoLiteral{∀}\versoVar{x} \versoVar{y} \versoLiteral{:} \versoConst{Set} \versoLiteral{_}\versoLiteral{,} \versoVar{x} \versoLiteral{∈} \versoLiteral{(}\versoLiteral{(}\versoLiteral{𝒫} \versoVar{x}\versoLiteral{)} \versoLiteral{∪} \versoLiteral{(}\versoLiteral{𝒫} \versoVar{y}\versoLiteral{)}\versoLiteral{)}|
+\item \LeanVerb|\versoConst{true} \versoLiteral{\symbol{124}\symbol{124}} \versoConst{false}|
+\item \LeanVerb|\versoConst{False} \versoLiteral{→} \versoConst{True}|
 
 \end{itemize}
 
diff --git a/src/tests/integration/diagram-doc/expected/tex/main.tex b/src/tests/integration/diagram-doc/expected/tex/main.tex
index 47d521914..09cd3746b 100644
--- a/src/tests/integration/diagram-doc/expected/tex/main.tex
+++ b/src/tests/integration/diagram-doc/expected/tex/main.tex
@@ -51,12 +51,11 @@
 % Work around missing U+2011 (non-breaking hyphen) in Source Serif Pro
 \newunicodechar{‑}{-}
 
-\definecolor{errorColor}{HTML}{B91C1C}
-\definecolor{infoColor}{HTML}{1E6BB8}
-\definecolor{warningColor}{HTML}{D97706}
-\newcommand{\errorDecorate}[1]{\coloredwave{errorColor}{#1}}
-\newcommand{\infoDecorate}[1]{\coloredwave{infoColor}{#1}}
-\newcommand{\warningDecorate}[1]{\coloredwave{warningColor}{#1}}
+% Decoration accents (wavy underlines) use the *indicator* colors, distinct from the message
+% text colors. The theme block below redefines both.
+\newcommand{\errorDecorate}[1]{\coloredwave{errorIndicatorColor}{#1}}
+\newcommand{\infoDecorate}[1]{\coloredwave{infoIndicatorColor}{#1}}
+\newcommand{\warningDecorate}[1]{\coloredwave{warningIndicatorColor}{#1}}
 \DefineVerbatimEnvironment{LeanVerbatim}{Verbatim}
   {commandchars=\\\{\},fontsize=\small,breaklines=true}
 \DefineVerbatimEnvironment{FileVerbatim}{Verbatim}{commandchars=\\\{\},fontsize=\small,breaklines=true,frame=single,framesep=2mm,numbers=left}
@@ -124,6 +123,24 @@
 \renewcommand{\cftsectionfont}{\normalfont\sffamily}
 \renewcommand{\cftchapterpagefont}{\normalfont\sffamily}
 \renewcommand{\cftsectionpagefont}{\normalfont\sffamily}
+\providecommand{\versoKeyword}[1]{\textbf{#1}}
+\providecommand{\versoConst}[1]{#1}
+\providecommand{\versoVar}[1]{\textit{#1}}
+\providecommand{\versoLiteral}[1]{#1}
+\definecolor{versoCodeColor}{HTML}{000000}
+\definecolor{versoConstColor}{HTML}{000000}
+\definecolor{versoKeywordColor}{HTML}{000000}
+\definecolor{versoVarColor}{HTML}{000000}
+\definecolor{errorColor}{HTML}{CC0000}
+\definecolor{warningColor}{HTML}{000000}
+\definecolor{infoColor}{HTML}{000000}
+\definecolor{errorIndicatorColor}{HTML}{FF0000}
+\definecolor{warningIndicatorColor}{HTML}{E7A71D}
+\definecolor{infoIndicatorColor}{HTML}{4777FF}
+\renewcommand{\versoKeyword}[1]{\textcolor{versoKeywordColor}{\fontseries{eb}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoConst}[1]{\textcolor{versoConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoVar}[1]{\textcolor{versoVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoLiteral}[1]{\textcolor{versoCodeColor}{#1}}
 \setmonofont{DejaVu Sans Mono}
 
 \title{\sffamily Diagrams in the Manual genre}
diff --git a/src/tests/integration/extra-files-doc/expected/tex/main.tex b/src/tests/integration/extra-files-doc/expected/tex/main.tex
index c9aa89ea8..a4f708321 100644
--- a/src/tests/integration/extra-files-doc/expected/tex/main.tex
+++ b/src/tests/integration/extra-files-doc/expected/tex/main.tex
@@ -51,12 +51,11 @@
 % Work around missing U+2011 (non-breaking hyphen) in Source Serif Pro
 \newunicodechar{‑}{-}
 
-\definecolor{errorColor}{HTML}{B91C1C}
-\definecolor{infoColor}{HTML}{1E6BB8}
-\definecolor{warningColor}{HTML}{D97706}
-\newcommand{\errorDecorate}[1]{\coloredwave{errorColor}{#1}}
-\newcommand{\infoDecorate}[1]{\coloredwave{infoColor}{#1}}
-\newcommand{\warningDecorate}[1]{\coloredwave{warningColor}{#1}}
+% Decoration accents (wavy underlines) use the *indicator* colors, distinct from the message
+% text colors. The theme block below redefines both.
+\newcommand{\errorDecorate}[1]{\coloredwave{errorIndicatorColor}{#1}}
+\newcommand{\infoDecorate}[1]{\coloredwave{infoIndicatorColor}{#1}}
+\newcommand{\warningDecorate}[1]{\coloredwave{warningIndicatorColor}{#1}}
 \DefineVerbatimEnvironment{LeanVerbatim}{Verbatim}
   {commandchars=\\\{\},fontsize=\small,breaklines=true}
 \DefineVerbatimEnvironment{FileVerbatim}{Verbatim}{commandchars=\\\{\},fontsize=\small,breaklines=true,frame=single,framesep=2mm,numbers=left}
@@ -124,6 +123,24 @@
 \renewcommand{\cftsectionfont}{\normalfont\sffamily}
 \renewcommand{\cftchapterpagefont}{\normalfont\sffamily}
 \renewcommand{\cftsectionpagefont}{\normalfont\sffamily}
+\providecommand{\versoKeyword}[1]{\textbf{#1}}
+\providecommand{\versoConst}[1]{#1}
+\providecommand{\versoVar}[1]{\textit{#1}}
+\providecommand{\versoLiteral}[1]{#1}
+\definecolor{versoCodeColor}{HTML}{000000}
+\definecolor{versoConstColor}{HTML}{000000}
+\definecolor{versoKeywordColor}{HTML}{000000}
+\definecolor{versoVarColor}{HTML}{000000}
+\definecolor{errorColor}{HTML}{CC0000}
+\definecolor{warningColor}{HTML}{000000}
+\definecolor{infoColor}{HTML}{000000}
+\definecolor{errorIndicatorColor}{HTML}{FF0000}
+\definecolor{warningIndicatorColor}{HTML}{E7A71D}
+\definecolor{infoIndicatorColor}{HTML}{4777FF}
+\renewcommand{\versoKeyword}[1]{\textcolor{versoKeywordColor}{\fontseries{eb}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoConst}[1]{\textcolor{versoConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoVar}[1]{\textcolor{versoVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoLiteral}[1]{\textcolor{versoCodeColor}{#1}}
 \setmonofont{DejaVu Sans Mono}
 
 \title{\sffamily Extra Files Test Document}
diff --git a/src/tests/integration/front-matter-doc/expected/tex/main.tex b/src/tests/integration/front-matter-doc/expected/tex/main.tex
index 371a84f8e..716878d92 100644
--- a/src/tests/integration/front-matter-doc/expected/tex/main.tex
+++ b/src/tests/integration/front-matter-doc/expected/tex/main.tex
@@ -51,12 +51,11 @@
 % Work around missing U+2011 (non-breaking hyphen) in Source Serif Pro
 \newunicodechar{‑}{-}
 
-\definecolor{errorColor}{HTML}{B91C1C}
-\definecolor{infoColor}{HTML}{1E6BB8}
-\definecolor{warningColor}{HTML}{D97706}
-\newcommand{\errorDecorate}[1]{\coloredwave{errorColor}{#1}}
-\newcommand{\infoDecorate}[1]{\coloredwave{infoColor}{#1}}
-\newcommand{\warningDecorate}[1]{\coloredwave{warningColor}{#1}}
+% Decoration accents (wavy underlines) use the *indicator* colors, distinct from the message
+% text colors. The theme block below redefines both.
+\newcommand{\errorDecorate}[1]{\coloredwave{errorIndicatorColor}{#1}}
+\newcommand{\infoDecorate}[1]{\coloredwave{infoIndicatorColor}{#1}}
+\newcommand{\warningDecorate}[1]{\coloredwave{warningIndicatorColor}{#1}}
 \DefineVerbatimEnvironment{LeanVerbatim}{Verbatim}
   {commandchars=\\\{\},fontsize=\small,breaklines=true}
 \DefineVerbatimEnvironment{FileVerbatim}{Verbatim}{commandchars=\\\{\},fontsize=\small,breaklines=true,frame=single,framesep=2mm,numbers=left}
@@ -124,6 +123,24 @@
 \renewcommand{\cftsectionfont}{\normalfont\sffamily}
 \renewcommand{\cftchapterpagefont}{\normalfont\sffamily}
 \renewcommand{\cftsectionpagefont}{\normalfont\sffamily}
+\providecommand{\versoKeyword}[1]{\textbf{#1}}
+\providecommand{\versoConst}[1]{#1}
+\providecommand{\versoVar}[1]{\textit{#1}}
+\providecommand{\versoLiteral}[1]{#1}
+\definecolor{versoCodeColor}{HTML}{000000}
+\definecolor{versoConstColor}{HTML}{000000}
+\definecolor{versoKeywordColor}{HTML}{000000}
+\definecolor{versoVarColor}{HTML}{000000}
+\definecolor{errorColor}{HTML}{CC0000}
+\definecolor{warningColor}{HTML}{000000}
+\definecolor{infoColor}{HTML}{000000}
+\definecolor{errorIndicatorColor}{HTML}{FF0000}
+\definecolor{warningIndicatorColor}{HTML}{E7A71D}
+\definecolor{infoIndicatorColor}{HTML}{4777FF}
+\renewcommand{\versoKeyword}[1]{\textcolor{versoKeywordColor}{\fontseries{eb}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoConst}[1]{\textcolor{versoConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoVar}[1]{\textcolor{versoVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoLiteral}[1]{\textcolor{versoCodeColor}{#1}}
 \setmonofont{DejaVu Sans Mono}
 
 \title{\sffamily Front Matter Test Document}
diff --git a/src/tests/integration/inheritance-doc/expected/tex/main.tex b/src/tests/integration/inheritance-doc/expected/tex/main.tex
index 0600aab1b..c42d0377d 100644
--- a/src/tests/integration/inheritance-doc/expected/tex/main.tex
+++ b/src/tests/integration/inheritance-doc/expected/tex/main.tex
@@ -51,12 +51,11 @@
 % Work around missing U+2011 (non-breaking hyphen) in Source Serif Pro
 \newunicodechar{‑}{-}
 
-\definecolor{errorColor}{HTML}{B91C1C}
-\definecolor{infoColor}{HTML}{1E6BB8}
-\definecolor{warningColor}{HTML}{D97706}
-\newcommand{\errorDecorate}[1]{\coloredwave{errorColor}{#1}}
-\newcommand{\infoDecorate}[1]{\coloredwave{infoColor}{#1}}
-\newcommand{\warningDecorate}[1]{\coloredwave{warningColor}{#1}}
+% Decoration accents (wavy underlines) use the *indicator* colors, distinct from the message
+% text colors. The theme block below redefines both.
+\newcommand{\errorDecorate}[1]{\coloredwave{errorIndicatorColor}{#1}}
+\newcommand{\infoDecorate}[1]{\coloredwave{infoIndicatorColor}{#1}}
+\newcommand{\warningDecorate}[1]{\coloredwave{warningIndicatorColor}{#1}}
 \DefineVerbatimEnvironment{LeanVerbatim}{Verbatim}
   {commandchars=\\\{\},fontsize=\small,breaklines=true}
 \DefineVerbatimEnvironment{FileVerbatim}{Verbatim}{commandchars=\\\{\},fontsize=\small,breaklines=true,frame=single,framesep=2mm,numbers=left}
@@ -124,6 +123,24 @@
 \renewcommand{\cftsectionfont}{\normalfont\sffamily}
 \renewcommand{\cftchapterpagefont}{\normalfont\sffamily}
 \renewcommand{\cftsectionpagefont}{\normalfont\sffamily}
+\providecommand{\versoKeyword}[1]{\textbf{#1}}
+\providecommand{\versoConst}[1]{#1}
+\providecommand{\versoVar}[1]{\textit{#1}}
+\providecommand{\versoLiteral}[1]{#1}
+\definecolor{versoCodeColor}{HTML}{000000}
+\definecolor{versoConstColor}{HTML}{000000}
+\definecolor{versoKeywordColor}{HTML}{000000}
+\definecolor{versoVarColor}{HTML}{000000}
+\definecolor{errorColor}{HTML}{CC0000}
+\definecolor{warningColor}{HTML}{000000}
+\definecolor{infoColor}{HTML}{000000}
+\definecolor{errorIndicatorColor}{HTML}{FF0000}
+\definecolor{warningIndicatorColor}{HTML}{E7A71D}
+\definecolor{infoIndicatorColor}{HTML}{4777FF}
+\renewcommand{\versoKeyword}[1]{\textcolor{versoKeywordColor}{\fontseries{eb}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoConst}[1]{\textcolor{versoConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoVar}[1]{\textcolor{versoVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoLiteral}[1]{\textcolor{versoCodeColor}{#1}}
 \setmonofont{DejaVu Sans Mono}
 
 \title{\sffamily Title of the Doc}
@@ -143,7 +160,7 @@
 
 \cleardoublepage
 \begin{docstringBox}{structure}
-\LeanVerb|Verso.\allowbreak{}Integration.\allowbreak{}Inheritance\-Doc.\allowbreak{}Foo\-Extends : Type|\tcblower Documentation for FooExtends\par\noindent\textbf{Constructor}\par \par \LeanVerb|Verso.\allowbreak{}Integration.\allowbreak{}Inheritance\-Doc.\allowbreak{}Foo\-Extends.\allowbreak{}mk|\par\noindent\textbf{Extends}\par Verso.Integration.InheritanceDoc.FooExtends\par\noindent\textbf{Fields}\par \par \LeanVerb|bar\-Field1| : \LeanVerb|Bool|\par Inherited from \LeanVerb|Bar\-Extended|\par \LeanVerb|bar\-Field2| : \LeanVerb|Unit|\par Inherited from \LeanVerb|Bar\-Extended|\par \LeanVerb|foo\-Field1| : \LeanVerb|Nat|\par Documentation for fooField1\par \LeanVerb|foo\-Field2| : \LeanVerb|String|\par Documentation for fooField2
+\LeanVerb|\versoConst{Verso.\allowbreak{}Integration.\allowbreak{}Inheritance\-Doc.\allowbreak{}Foo\-Extends} \versoLiteral{:} \versoLiteral{Type}|\tcblower Documentation for FooExtends\par\noindent\textbf{Constructor}\par \par \LeanVerb|\versoConst{Verso.\allowbreak{}Integration.\allowbreak{}Inheritance\-Doc.\allowbreak{}Foo\-Extends.\allowbreak{}mk}|\par\noindent\textbf{Extends}\par Verso.Integration.InheritanceDoc.FooExtends\par\noindent\textbf{Fields}\par \par \LeanVerb|\versoLiteral{bar\-Field1}| : \LeanVerb|\versoConst{Bool}|\par Inherited from \LeanVerb|\versoConst{Bar\-Extended}|\par \LeanVerb|\versoLiteral{bar\-Field2}| : \LeanVerb|\versoConst{Unit}|\par Inherited from \LeanVerb|\versoConst{Bar\-Extended}|\par \LeanVerb|\versoConst{foo\-Field1}| : \LeanVerb|\versoConst{Nat}|\par Documentation for fooField1\par \LeanVerb|\versoConst{foo\-Field2}| : \LeanVerb|\versoConst{String}|\par Documentation for fooField2
 \end{docstringBox}
 
 
diff --git a/src/tests/integration/sample-doc/expected/tex/main.tex b/src/tests/integration/sample-doc/expected/tex/main.tex
index 7d0f48a24..cbcc6c95b 100644
--- a/src/tests/integration/sample-doc/expected/tex/main.tex
+++ b/src/tests/integration/sample-doc/expected/tex/main.tex
@@ -51,12 +51,11 @@
 % Work around missing U+2011 (non-breaking hyphen) in Source Serif Pro
 \newunicodechar{‑}{-}
 
-\definecolor{errorColor}{HTML}{B91C1C}
-\definecolor{infoColor}{HTML}{1E6BB8}
-\definecolor{warningColor}{HTML}{D97706}
-\newcommand{\errorDecorate}[1]{\coloredwave{errorColor}{#1}}
-\newcommand{\infoDecorate}[1]{\coloredwave{infoColor}{#1}}
-\newcommand{\warningDecorate}[1]{\coloredwave{warningColor}{#1}}
+% Decoration accents (wavy underlines) use the *indicator* colors, distinct from the message
+% text colors. The theme block below redefines both.
+\newcommand{\errorDecorate}[1]{\coloredwave{errorIndicatorColor}{#1}}
+\newcommand{\infoDecorate}[1]{\coloredwave{infoIndicatorColor}{#1}}
+\newcommand{\warningDecorate}[1]{\coloredwave{warningIndicatorColor}{#1}}
 \DefineVerbatimEnvironment{LeanVerbatim}{Verbatim}
   {commandchars=\\\{\},fontsize=\small,breaklines=true}
 \DefineVerbatimEnvironment{FileVerbatim}{Verbatim}{commandchars=\\\{\},fontsize=\small,breaklines=true,frame=single,framesep=2mm,numbers=left}
@@ -124,6 +123,24 @@
 \renewcommand{\cftsectionfont}{\normalfont\sffamily}
 \renewcommand{\cftchapterpagefont}{\normalfont\sffamily}
 \renewcommand{\cftsectionpagefont}{\normalfont\sffamily}
+\providecommand{\versoKeyword}[1]{\textbf{#1}}
+\providecommand{\versoConst}[1]{#1}
+\providecommand{\versoVar}[1]{\textit{#1}}
+\providecommand{\versoLiteral}[1]{#1}
+\definecolor{versoCodeColor}{HTML}{000000}
+\definecolor{versoConstColor}{HTML}{000000}
+\definecolor{versoKeywordColor}{HTML}{000000}
+\definecolor{versoVarColor}{HTML}{000000}
+\definecolor{errorColor}{HTML}{CC0000}
+\definecolor{warningColor}{HTML}{000000}
+\definecolor{infoColor}{HTML}{000000}
+\definecolor{errorIndicatorColor}{HTML}{FF0000}
+\definecolor{warningIndicatorColor}{HTML}{E7A71D}
+\definecolor{infoIndicatorColor}{HTML}{4777FF}
+\renewcommand{\versoKeyword}[1]{\textcolor{versoKeywordColor}{\fontseries{eb}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoConst}[1]{\textcolor{versoConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoVar}[1]{\textcolor{versoVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoLiteral}[1]{\textcolor{versoCodeColor}{#1}}
 \setmonofont{DejaVu Sans Mono}
 
 \title{\sffamily Title of the Doc}
@@ -143,7 +160,7 @@
 
 \cleardoublepage
 \begin{docstringBox}{def}
-\LeanVerb|Verso.\allowbreak{}Integration.\allowbreak{}Sample\-Doc.\allowbreak{}sample_constant : Type|\tcblower This is a docstring.Here's some more text with a \LeanVerb|code inline| in it.
+\LeanVerb|\versoConst{Verso.\allowbreak{}Integration.\allowbreak{}Sample\-Doc.\allowbreak{}sample_constant} \versoLiteral{:} \versoLiteral{Type}|\tcblower This is a docstring.Here's some more text with a \LeanVerb|code inline| in it.
 Here's when a \LeanVerb|code inline|
 occurs right before a line break.And then here's a paragraph break.
 \end{docstringBox}
diff --git a/src/verso-manual/VersoManual.lean b/src/verso-manual/VersoManual.lean
index f6c55cfda..acd9272f8 100644
--- a/src/verso-manual/VersoManual.lean
+++ b/src/verso-manual/VersoManual.lean
@@ -379,8 +379,8 @@ where
   isUnnumbered (p : Part Manual) : Bool := p.metadata.map (·.number) |>.isEqSome false
 
 open IO.FS in
-def emitTeX (config : Config) (text : Part Manual) : EmitM Unit := do
-  let (text, state) ← traverse text config
+def emitTeX (config : RenderConfig) (text : Part Manual) : EmitM Unit := do
+  let (text, state) ← traverse text config.toConfig
   let opts : TeX.Options Manual := {
     headerLevels := #["chapter", "section", "subsection", "subsubsection", "paragraph"],
     headerLevel := some ⟨0, by grind⟩
@@ -402,7 +402,7 @@ def emitTeX (config : Config) (text : Part Manual) : EmitM Unit := do
   withFile (dir.join "main.tex") .write fun h => do
     if config.verbose then
       IO.println s!"Saving {dir.join "main.tex"}"
-    h.putStrLn (preamble text.titleString authors date packages.toList preambleItems.toList)
+    h.putStrLn (preamble text.titleString authors date packages.toList preambleItems.toList config.codeTheme)
     -- \frontmatter is inserted by our hardcoded preamble before the ToC, so it doesn't get inserted
     -- here. If there's any text at the start of the front matter, then we need to clear it to a new
     -- recto page after the ToC
@@ -1049,7 +1049,7 @@ where
       if cfg.emitTeX then
         if cfg.verbose then
           IO.println s!"Saving TeX"
-        emitTeX cfg.toConfig text
+        emitTeX cfg text
 
       emitHtml cfg.emitHtmlSingle .single cfg text traverseHtmlSingle emitHtmlSingle
       emitHtml cfg.emitHtmlMulti .multi cfg text traverseHtmlMulti emitHtmlMulti
diff --git a/src/verso-manual/VersoManual/TeX.lean b/src/verso-manual/VersoManual/TeX.lean
index 96ff529b9..7619d35c8 100644
--- a/src/verso-manual/VersoManual/TeX.lean
+++ b/src/verso-manual/VersoManual/TeX.lean
@@ -4,9 +4,15 @@ Released under Apache 2.0 license as described in the file LICENSE.
 Author: David Thrane Christiansen
 -/
 module
+
+public import Verso.Code.HighlightedToTex
+public import Verso.Theme.Code
+
 namespace Verso.Genre.Manual.TeX
 
-public def preamble (title : String) (authors : List String) (date : String) (packages : List String) (extraPreamble : List String) : String :=
+public def preamble (title : String) (authors : List String) (date : String)
+    (packages : List String) (extraPreamble : List String)
+    (codeTheme : Verso.Theme.CodeTheme) : String :=
 r##"
 \documentclass{memoir}
 
@@ -60,12 +66,11 @@ r##"
 % Work around missing U+2011 (non-breaking hyphen) in Source Serif Pro
 \newunicodechar{‑}{-}
 
-\definecolor{errorColor}{HTML}{B91C1C}
-\definecolor{infoColor}{HTML}{1E6BB8}
-\definecolor{warningColor}{HTML}{D97706}
-\newcommand{\errorDecorate}[1]{\coloredwave{errorColor}{#1}}
-\newcommand{\infoDecorate}[1]{\coloredwave{infoColor}{#1}}
-\newcommand{\warningDecorate}[1]{\coloredwave{warningColor}{#1}}
+% Decoration accents (wavy underlines) use the *indicator* colors, distinct from the message
+% text colors. The theme block below redefines both.
+\newcommand{\errorDecorate}[1]{\coloredwave{errorIndicatorColor}{#1}}
+\newcommand{\infoDecorate}[1]{\coloredwave{infoIndicatorColor}{#1}}
+\newcommand{\warningDecorate}[1]{\coloredwave{warningIndicatorColor}{#1}}
 \DefineVerbatimEnvironment{LeanVerbatim}{Verbatim}
   {commandchars=\\\{\},fontsize=\small,breaklines=true}
 \DefineVerbatimEnvironment{FileVerbatim}{Verbatim}{commandchars=\\\{\},fontsize=\small,breaklines=true,frame=single,framesep=2mm,numbers=left}
@@ -135,8 +140,9 @@ r##"
 \renewcommand{\cftsectionfont}{\normalfont\sffamily}
 \renewcommand{\cftchapterpagefont}{\normalfont\sffamily}
 \renewcommand{\cftsectionpagefont}{\normalfont\sffamily}
-\setmonofont{DejaVu Sans Mono}
 "## ++
+SubVerso.Highlighting.texMacroFallbacks ++
+codeTheme.texPreamble ++
 "\n".intercalate extraPreamble ++
 r##"
 \title{\sffamily "## ++ title ++ r##"}
diff --git a/src/verso-search/VersoSearch.lean b/src/verso-search/VersoSearch.lean
index fd8f964fd..2324ac9a6 100644
--- a/src/verso-search/VersoSearch.lean
+++ b/src/verso-search/VersoSearch.lean
@@ -798,7 +798,7 @@ public class Indexable (genre : Verso.Doc.Genre) where
   /--
   Computes the full-text search priority for a part, using the same centered-at-50 convention as the
   quick-jump side. Returning {lean}`none` leaves the document at neutral; returning a signed integer
-  lets a genre fold section metadata, ancestor inheritance, or other HTMl-generation-time adjustments into
+  lets a genre fold section metadata, ancestor inheritance, or other HTML-generation-time adjustments into
   full-text scoring. This is an {lean}`Int` to allow it to accumulate adjustments that put it
   outside the usual range.
   -/
diff --git a/src/verso/Verso/Code/HighlightedToTex.lean b/src/verso/Verso/Code/HighlightedToTex.lean
index 0229fb43f..be4f43ad5 100644
--- a/src/verso/Verso/Code/HighlightedToTex.lean
+++ b/src/verso/Verso/Code/HighlightedToTex.lean
@@ -20,24 +20,39 @@ open Std (HashMap)
 namespace SubVerso.Highlighting
 
 /--
-Given an already escaped-for-verbatim string, and a token kind,
-returns TeX to display that token appropriately syntax-highlighted.
+Given an already escaped-for-verbatim string, and a token kind, returns TeX that wraps the
+content in the matching semantic macro: `\versoKeyword`, `\versoConst`, `\versoVar`, or
+`\versoLiteral`. The macros are defined by the consuming genre's preamble (the manual genre
+uses {Lean.Doc.name}`Verso.Theme.CodeTheme` to style them). For a fallback definition that
+reproduces the pre-theming look, see {Lean.Doc.name}`SubVerso.Highlighting.texMacroFallbacks`.
 -/
 public def highlightToken : String → Token.Kind → TeX
-| c, .keyword _ _ _ => .raw s!"\\textbf\{{c}}"
-| c, .const .. => .raw c
-| c, .anonCtor .. => .raw c
-| c, .option _ _ _ => .raw c
-| c, .var .. => .raw s!"\\textit\{{c}}"
-| c, .str _ => .raw c
-| c, .docComment => .raw c
-| c, .sort _ => .raw c
-| c, .levelVar _ => .raw c
-| c, .levelConst _ => .raw c
-| c, .moduleName _ => .raw c
-| c, .levelOp _ => .raw c
-| c, .withType _ => .raw c
-| c, .unknown => .raw c
+| c, .keyword _ _ _ => .raw s!"\\versoKeyword\{{c}}"
+| c, .const .. => .raw s!"\\versoConst\{{c}}"
+| c, .anonCtor .. => .raw s!"\\versoConst\{{c}}"
+| c, .option _ _ _ => .raw s!"\\versoConst\{{c}}"
+| c, .var .. => .raw s!"\\versoVar\{{c}}"
+| c, .str _ => .raw s!"\\versoLiteral\{{c}}"
+| c, .docComment => .raw s!"\\versoLiteral\{{c}}"
+| c, .sort _ => .raw s!"\\versoLiteral\{{c}}"
+| c, .levelVar _ => .raw s!"\\versoLiteral\{{c}}"
+| c, .levelConst _ => .raw s!"\\versoLiteral\{{c}}"
+| c, .moduleName _ => .raw s!"\\versoLiteral\{{c}}"
+| c, .levelOp _ => .raw s!"\\versoLiteral\{{c}}"
+| c, .withType _ => .raw s!"\\versoLiteral\{{c}}"
+| c, .unknown => .raw s!"\\versoLiteral\{{c}}"
+
+/--
+Fallback definitions for the four semantic token macros emitted by
+{Lean.Doc.name}`SubVerso.Highlighting.highlightToken`. Each uses `\providecommand`, so a genre
+preamble that defines its own (theme-driven) versions wins. The fallbacks reproduce today's
+unthemed look: keywords bold, variables italic, constants and literals plain.
+-/
+public def texMacroFallbacks : String :=
+"\\providecommand{\\versoKeyword}[1]{\\textbf{#1}}\n" ++
+"\\providecommand{\\versoConst}[1]{#1}\n" ++
+"\\providecommand{\\versoVar}[1]{\\textit{#1}}\n" ++
+"\\providecommand{\\versoLiteral}[1]{#1}\n"
 
 defmethod Highlighting.Token.toVerbatimTeX (t : Highlighting.Token) (lineBreaks : Bool := false) : Verso.Output.TeX :=
   highlightToken (escapeForVerbatim t.content lineBreaks) t.kind
@@ -48,6 +63,12 @@ Returns TeX that is appropriate for the content of a `\Verb` environment (from p
 with command characters `\`, `{`, and `}`.
 
 When `lineBreaks` is true, inserts line break opportunities in identifiers.
+
+**Preamble contract.** Output uses the four `\verso…` semantic macros emitted by
+{Lean.Doc.name}`SubVerso.Highlighting.highlightToken`. Any consumer that compiles the result must
+ensure those macros are defined, either by including
+{Lean.Doc.name}`SubVerso.Highlighting.texMacroFallbacks` in the preamble or by defining its own
+theme-driven versions (the manual genre installs both).
 -/
 public defmethod Highlighted.toVerbatimTeX (h : Highlighted) (lineBreaks : Bool := false) : Verso.Output.TeX :=
   match h with
diff --git a/src/verso/Verso/Font.lean b/src/verso/Verso/Font.lean
index f5c5ea9af..fca4ab13a 100644
--- a/src/verso/Verso/Font.lean
+++ b/src/verso/Verso/Font.lean
@@ -136,6 +136,19 @@ public def Typeface.cssFamily : Typeface → String
   | .mono => "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace"
   | .files family _ => cssQuote family
 
+/--
+The fontspec family name that LuaLaTeX should pick for a typeface. The built-in
+{name (full := Verso.Typeface.sans)}`sans`/{name (full := Verso.Typeface.serif)}`serif`/{name (full := Verso.Typeface.mono)}`mono`
+typefaces fall back to a system family known to ship with TeXLive's LuaLaTeX bundle; a
+{name (full := Verso.Typeface.files)}`files` typeface uses its declared family name directly so
+the corresponding fontspec files loaded elsewhere in the preamble resolve.
+-/
+public def Typeface.texFamily : Typeface → String
+  | .sans => "DejaVu Sans"
+  | .serif => "DejaVu Serif"
+  | .mono => "DejaVu Sans Mono"
+  | .files family _ => family
+
 /-! # Defining font faces -/
 
 /--
diff --git a/src/verso/Verso/Theme/Code.lean b/src/verso/Verso/Theme/Code.lean
index 356a75675..e7eb3f9c8 100644
--- a/src/verso/Verso/Theme/Code.lean
+++ b/src/verso/Verso/Theme/Code.lean
@@ -358,6 +358,79 @@ public def cssVariables (theme : CodeTheme) : String :=
 
 end CodeTheme
 
+/-! # TeX preamble -/
+
+namespace CodeTheme
+
+private def fontSeries (w : Weight) : String :=
+  -- The NFSS series codes that are widely supported by fontspec/luaotfload. We map the requested
+  -- numeric weight to the nearest standard series; LuaLaTeX uses the series to pick a face. A
+  -- finer mapping is unnecessary because the variable/extra weights are handled by the font
+  -- loader, not by `\fontseries`.
+  let v := w.val
+  if v ≤ 200 then "ul"
+  else if v ≤ 300 then "el"
+  else if v ≤ 350 then "l"
+  else if v ≤ 450 then "m"
+  else if v ≤ 550 then "sb"
+  else if v ≤ 650 then "b"
+  else if v ≤ 750 then "eb"
+  else "ub"
+
+private def fontShape : FontStyle → String
+  | .normal => "n"
+  | .italic => "it"
+
+private def tokenMacro (name : String) (s : TokenStyle) (colorName : String) : String :=
+  s!"\\renewcommand\{\\verso{name}}[1]\{\\textcolor\{{colorName}}\{\\fontseries\{{fontSeries s.weight}}\\fontshape\{{fontShape s.style}}\\selectfont #1}}\n"
+
+/--
+Returns a TeX preamble fragment that defines a theme-specific {lit}`xcolor` palette, redefines
+the four {lit}`\verso…` token macros so they apply the theme's per-token color, weight, and
+style, and sets the document mono font to {Lean.Doc.name (full := Verso.Typeface.texFamily)}`Verso.Typeface.texFamily` applied to
+{Lean.Doc.name (full := Verso.Theme.CodeTheme.codeFace)}`codeFace`.
+
+Two color names are emitted per severity: {lit}`errorColor`/{lit}`warningColor`/{lit}`infoColor`
+are the message-text colors, and {lit}`errorIndicatorColor`/{lit}`warningIndicatorColor`/{lit}`infoIndicatorColor`
+are the accent colors used for the wavy underlines and frames. The output is intended to be
+appended after Verso's manual preamble (which carries the {lit}`\providecommand` fallbacks for
+the {lit}`\verso…` macros). It uses {lit}`xcolor`'s {lit}`HTML` model and NFSS series/shape
+codes that fontspec understands under LuaLaTeX.
+-/
+public def texPreamble (theme : CodeTheme) : String :=
+  let codeColor := Color.tex theme.codeColor
+  let constColor := Color.tex theme.const.color
+  let keywordColor := Color.tex theme.keyword.color
+  let varColor := Color.tex theme.«var».color
+  -- Per the structure's semantics, the `*Color` fields are message-text colors and
+  -- `*IndicatorColor` are accent colors (underlines, frames, dingbats). Emit both as separate
+  -- `\definecolor` entries so the preamble can reference whichever the rule needs.
+  let errorTextColor := Color.tex theme.errorColor
+  let warningTextColor := Color.tex theme.warningColor
+  let infoTextColor := Color.tex theme.infoColor
+  let errorAccent := Color.tex theme.errorIndicatorColor
+  let warningAccent := Color.tex theme.warningIndicatorColor
+  let infoAccent := Color.tex theme.infoIndicatorColor
+  String.join [
+    s!"\\definecolor\{versoCodeColor}\{HTML}\{{codeColor}}\n",
+    s!"\\definecolor\{versoConstColor}\{HTML}\{{constColor}}\n",
+    s!"\\definecolor\{versoKeywordColor}\{HTML}\{{keywordColor}}\n",
+    s!"\\definecolor\{versoVarColor}\{HTML}\{{varColor}}\n",
+    s!"\\definecolor\{errorColor}\{HTML}\{{errorTextColor}}\n",
+    s!"\\definecolor\{warningColor}\{HTML}\{{warningTextColor}}\n",
+    s!"\\definecolor\{infoColor}\{HTML}\{{infoTextColor}}\n",
+    s!"\\definecolor\{errorIndicatorColor}\{HTML}\{{errorAccent}}\n",
+    s!"\\definecolor\{warningIndicatorColor}\{HTML}\{{warningAccent}}\n",
+    s!"\\definecolor\{infoIndicatorColor}\{HTML}\{{infoAccent}}\n",
+    tokenMacro "Keyword" theme.keyword "versoKeywordColor",
+    tokenMacro "Const" theme.const "versoConstColor",
+    tokenMacro "Var" theme.«var» "versoVarColor",
+    s!"\\renewcommand\{\\versoLiteral}[1]\{\\textcolor\{versoCodeColor}\{#1}}\n",
+    s!"\\setmonofont\{{theme.codeFace.texFamily}}\n"
+  ]
+
+end CodeTheme
+
 /-! # Font assets and {lit}`@font-face` writing -/
 
 namespace CodeTheme
@@ -403,18 +476,22 @@ public def slugFamily (family : String) : String := Id.run do
 
 /--
 Output-relative paths and bytes of every font file the theme uses. Each file is named
-{lit}`<slug>-<index>.<ext>` where {lit}`<slug>` is {Lean.Doc.name}`Verso.Theme.CodeTheme.slugFamily`
-applied to the family. The {lit}`assetRoot` is the directory the paths are relative to (no
-leading or trailing slash); the generated {lit}`@font-face` {lit}`url()`s also resolve from there.
+{lit}`<slug>-<typeface>-<face>.<ext>`, where {lit}`<slug>` is
+{Lean.Doc.name}`Verso.Theme.CodeTheme.slugFamily` applied to the family and {lit}`<typeface>` is
+the index of the typeface within the theme's {Lean.Doc.name}`Verso.Theme.CodeTheme.fileTypefaces`
+array. The typeface index keeps paths distinct even when two families slug to the same string
+(such as {lit}`"A B"` and {lit}`"A/B"` both becoming {lit}`A-B`). The {lit}`assetRoot` is the
+directory the paths are relative to (no leading or trailing slash); the generated
+{lit}`@font-face` {lit}`url()`s also resolve from there.
 -/
 public def fontAssets (theme : CodeTheme) (assetRoot : String) :
     Array (String × ByteArray × FontFace × String) := Id.run do
   let mut out := #[]
-  for tf in theme.fileTypefaces do
+  for (tf, ti) in theme.fileTypefaces.zipIdx do
     if let .files family faces := tf then
       let slug := slugFamily family
       for (face, i) in faces.zipIdx do
-        let path := s!"{assetRoot}/fonts/{slug}-{i}.{face.format.ext}"
+        let path := s!"{assetRoot}/fonts/{slug}-{ti}-{i}.{face.format.ext}"
         out := out.push (path, face.bytes, face, family)
   return out
 

From 3710eb14b724d94c15b99342ff035ed279913ace Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Sat, 30 May 2026 23:14:14 +0200
Subject: [PATCH 08/31] feat: use a theme for the Manual genre

Instead of custom CSS, themes are now represented as Lean values that
can be imported as libraries and selected by authors.
---
 .../test_theme_customization.py               | 129 +++++++++
 src/tests/Tests/ColorAccessibility.lean       |  56 ++++
 src/tests/ThemeTestDoc.lean                   |   3 +-
 src/tests/ThemeTestMain.lean                  |  23 +-
 src/tests/golden/theme-css/default.expected   |   2 +-
 .../code-content-doc/expected/tex/main.tex    |   2 +-
 .../diagram-doc/expected/tex/main.tex         |   2 +-
 .../extra-files-doc/expected/tex/main.tex     |   2 +-
 .../front-matter-doc/expected/tex/main.tex    |   2 +-
 .../inheritance-doc/expected/tex/main.tex     |   2 +-
 .../sample-doc/expected/tex/main.tex          |   2 +-
 src/verso-manual/VersoManual.lean             |  77 ++++--
 src/verso-manual/VersoManual/Html.lean        |   1 -
 src/verso-manual/VersoManual/Html/Style.lean  |  31 ++-
 src/verso-manual/VersoManual/Theme.lean       | 246 ++++++++++++++++++
 .../VersoManual/Theme/Defaults.lean           |  27 ++
 src/verso-manual/VersoManual/Theme/Ext.lean   |  29 +++
 src/verso/Verso/Theme/Code.lean               |  16 +-
 .../Verso/Theme/Color/Accessibility.lean      |   6 +
 static-web/search/search-box.css              |   6 +-
 static-web/search/search-highlight.css        |   2 +-
 static-web/search/search-page.css             |   4 +-
 22 files changed, 611 insertions(+), 59 deletions(-)
 create mode 100644 src/verso-manual/VersoManual/Theme.lean
 create mode 100644 src/verso-manual/VersoManual/Theme/Defaults.lean
 create mode 100644 src/verso-manual/VersoManual/Theme/Ext.lean

diff --git a/browser-tests/theme-customization/test_theme_customization.py b/browser-tests/theme-customization/test_theme_customization.py
index 6fe98da99..87cca718f 100644
--- a/browser-tests/theme-customization/test_theme_customization.py
+++ b/browser-tests/theme-customization/test_theme_customization.py
@@ -54,6 +54,14 @@ def _hex_to_rgb(h: str) -> str:
     "constColor": "#001717",
     "keywordColor": "#001818",
     "varColor": "#001919",
+    # ManualTheme additions (chrome).
+    "headerBackground": "#001b1b",
+    "tocBackground": "#001c1c",
+    "linkColor": "#002020",
+    "tocTextColor": "#002222",
+    "borderColor": "#001d1d",
+    "mutedColor": "#001e1e",
+    "highlightColor": "#001f1f",
 }
 
 
@@ -147,3 +155,124 @@ def test_error_indicator(page, server):
         THEME["errorIndicatorColor"],
         "lean-output.error indicator border",
     )
+
+
+def test_page_background(page):
+    _expect(_color(page, "body", "background-color"), THEME["background"], "body background")
+
+
+def test_body_text_color(page):
+    # `body` now sets `color: var(--verso-text-color)`. Inherited text in prose elements
+    # (paragraphs in `main`) should resolve to the theme's textColor rather than the
+    # browser-default black.
+    _expect(_color(page, "main p"), THEME["textColor"], "body prose color")
+
+
+def test_header_background(page):
+    _expect(
+        _color(page, "header", "background-color"),
+        THEME["headerBackground"],
+        "header background",
+    )
+
+
+def test_header_title_color(page):
+    # `.header-title` previously hardcoded `color: black`; the theme's `textColor` is now what
+    # the rendered title actually uses, so a theme with textColor != black is readable on
+    # a non-white header background.
+    _expect(
+        _color(page, ".header-title"),
+        THEME["textColor"],
+        "header title color",
+    )
+
+
+def test_toc_background_and_link_color(page):
+    _expect(
+        _color(page, "#toc", "background-color"),
+        THEME["tocBackground"],
+        "toc background",
+    )
+    # `#toc a` previously hardcoded `color: #333`; the theme's `tocTextColor` is now used,
+    # so a dark ToC background plus a light tocTextColor stays readable.
+    _expect(
+        _color(page, "#toc a"),
+        THEME["tocTextColor"],
+        "toc link color",
+    )
+
+
+def test_content_link_color(page, server):
+    # The doc has an `<a href="https://example.com/">` content link inside `main`. The new
+    # `main a { color: var(--verso-link-color) }` rule should pick up the theme's linkColor.
+    page.goto(server + "/Code-samples/")
+    _expect(
+        _color(page, 'main a[href^="https://example.com"]'),
+        THEME["linkColor"],
+        "content link color",
+    )
+
+
+def _root_var(page, name: str) -> str:
+    """Resolves a CSS custom property at the document-root level to its computed `rgb(...)`."""
+    return page.evaluate(
+        "(name) => {"
+        "  const raw = getComputedStyle(document.documentElement).getPropertyValue(name).trim();"
+        "  if (raw.startsWith('rgb')) return raw;"
+        "  const probe = document.createElement('span');"
+        "  probe.style.color = raw;"
+        "  document.body.appendChild(probe);"
+        "  const out = getComputedStyle(probe).color;"
+        "  probe.remove();"
+        "  return out;"
+        "}",
+        name,
+    ).strip()
+
+
+def test_border_var(page):
+    # `borderColor` is the search-input border color (and other chrome borders); the search box
+    # is mounted by JS so the variable is the most direct verification that the theme value
+    # reaches the page. (The CSS rules in search-box.css / search-page.css use
+    # `var(--verso-border-color, gray)` so a missing variable would fall back to gray.)
+    _expect(_root_var(page, "--verso-border-color"), THEME["borderColor"], "borderColor var")
+
+
+def test_prev_next_nav_color(page, server):
+    # The `.prev-next-buttons > *` rule previously forced `color: black`, ignoring the theme.
+    # It now reads `var(--verso-link-color)` so a dark page can still surface readable nav links.
+    page.goto(server + "/Code-samples/")
+    _expect(
+        _color(page, ".prev-next-buttons > a"),
+        THEME["linkColor"],
+        "prev/next nav link color",
+    )
+
+
+def test_search_placeholder_muted(page, server):
+    # The quick-search placeholder previously hardcoded `#888` and the "more results" row `#777`.
+    # Both now route through `--verso-muted-color`. The search box itself is mounted by JS;
+    # waiting for the placeholder text confirms the rule reaches a real rendered element.
+    page.goto(server + "/Code-samples/")
+    placeholder = page.locator("#search-wrapper .cb_edit:empty").first
+    placeholder.wait_for(state="attached", timeout=10000)
+    color = page.evaluate(
+        "() => getComputedStyle(document.querySelector('#search-wrapper .cb_edit:empty'),"
+        " '::before').getPropertyValue('color')"
+    ).strip()
+    _expect(color, THEME["mutedColor"], "search placeholder color")
+
+
+def test_search_match_highlight(page, server):
+    # Full-page search results render each matched term inside an `<em>`, whose background
+    # comes from `--verso-highlight-color` via `search-page.css`. Driving an actual search
+    # confirms a rendered match `<em>` consumes the theme value (root variable existence is
+    # not enough; the CSS rule has to actually read it).
+    page.goto(server + "/search/?q=hello")
+    em = page.locator(".search-page-list li.search-result em").first
+    em.wait_for(state="attached", timeout=10000)
+    _expect(
+        _color(page, ".search-page-list li.search-result em", "background-color"),
+        THEME["highlightColor"],
+        "search-result match highlight",
+    )
diff --git a/src/tests/Tests/ColorAccessibility.lean b/src/tests/Tests/ColorAccessibility.lean
index d868b4794..bb4355042 100644
--- a/src/tests/Tests/ColorAccessibility.lean
+++ b/src/tests/Tests/ColorAccessibility.lean
@@ -6,6 +6,8 @@ Author: David Thrane Christiansen
 module
 public import Plausible
 public meta import Verso.Theme.Color
+public meta import VersoManual.Theme
+public meta import VersoManual.Theme.Defaults
 public meta import Tests.Arbitrary
 
 /-!
@@ -71,6 +73,60 @@ def okabeIto : Array (String × Color) := #[
 #guard_msgs in
 #eval (colorblindIssues distinguishableThreshold okabeIto).isEmpty
 
+-- A pair of identical colors is not a colorblind issue: the theme is not relying on color to
+-- distinguish them (it might be using weight or style instead, as the default theme does).
+/-- info: true -/
+#guard_msgs in
+#eval (colorblindIssues distinguishableThreshold #[("a", .black), ("b", .black)]).isEmpty
+
+/-! ## `ManualTheme.checkAccessibility` -/
+
+-- The shipped default theme passes its own accessibility check.
+/-- info: true -/
+#guard_msgs in
+#eval ManualTheme.Default.checkAccessibility.isEmpty
+
+-- A low-contrast override (gray text on a near-white background) is flagged as a contrast
+-- problem (one per evaluated text pair against the page background).
+private def lowContrastTheme : ManualTheme := {
+  ManualTheme.Default with
+  textColor := color%#bbbbbb,
+}
+
+/-- info: true -/
+#guard_msgs in
+#eval (lowContrastTheme.checkAccessibility.any (·.kind == .contrast))
+
+-- A token palette that collapses under deuteranopia (a red and a green of matched lightness)
+-- is flagged as a CVD problem.
+private def cvdTheme : ManualTheme := {
+  ManualTheme.Default with
+  const := { ManualTheme.Default.const with color := color%#e60000 },
+  keyword := { ManualTheme.Default.keyword with color := color%#00a000 },
+}
+
+/-- info: true -/
+#guard_msgs in
+#eval (cvdTheme.checkAccessibility.any (·.kind == .colorblind))
+
+-- The contrast and colorblind checks are independent: the low-contrast theme has no colorblind
+-- issues, and the CVD theme has no contrast issues against the page background.
+/-- info: false -/
+#guard_msgs in
+#eval (lowContrastTheme.checkAccessibility.any (·.kind == .colorblind))
+
+-- A theme whose `highlightColor` is too close to `textColor` is flagged: search results render
+-- matched terms with `highlightColor` as their background, so the body text must read on it.
+private def badHighlightTheme : ManualTheme := {
+  ManualTheme.Default with
+  highlightColor := color%#333333,
+}
+
+/-- info: true -/
+#guard_msgs in
+#eval (badHighlightTheme.checkAccessibility.any (fun i =>
+  i.kind == .contrast && (i.message.splitOn "highlight").length > 1))
+
 /-! ## Property tests -/
 
 open scoped Plausible.Decorations in
diff --git a/src/tests/ThemeTestDoc.lean b/src/tests/ThemeTestDoc.lean
index 7cc2456f4..9fbfedf64 100644
--- a/src/tests/ThemeTestDoc.lean
+++ b/src/tests/ThemeTestDoc.lean
@@ -15,7 +15,8 @@ set_option pp.rawOnError true
 
 # Code samples
 
-A line of prose, followed by code that mixes a keyword, a const, and a literal.
+A line of prose with an [external content link](https://example.com/) that the browser test
+checks against the theme's `linkColor`. Then code that mixes a keyword, a const, and a literal.
 
 ```lean
 def hello (name : String) : String := s!"hello, {name}"
diff --git a/src/tests/ThemeTestMain.lean b/src/tests/ThemeTestMain.lean
index 8b2834ae2..910b01b8a 100644
--- a/src/tests/ThemeTestMain.lean
+++ b/src/tests/ThemeTestMain.lean
@@ -52,6 +52,27 @@ def config : Config where
   emitHtmlMulti := .immediately
   htmlDepth := 1
 
+def testManualTheme : ManualTheme := {
+  ManualTheme.Default with
+  toCodeTheme := testTheme,
+  surfaceColor := color%#001a1a,
+  headerBackground := color%#001b1b,
+  tocBackground := color%#001c1c,
+  borderColor := color%#001d1d,
+  mutedColor := color%#001e1e,
+  highlightColor := color%#001f1f,
+  linkColor := color%#002020,
+  visitedLinkColor := color%#002121,
+  tocTextColor := color%#002222,
+  burgerVisibleColor := color%#002323,
+  burgerVisibleShadowColor := color%#002424,
+  burgerHiddenColor := color%#002525,
+  burgerHiddenShadowColor := color%#002626
+}
+
 def main : List String → IO UInt32 :=
   manualMain (%doc ThemeTestDoc)
-    (config := { config with codeTheme := testTheme })
+    (config := { config with
+      manualTheme := testManualTheme,
+      strictThemeContrast := false,
+      strictThemeColorblind := false })
diff --git a/src/tests/golden/theme-css/default.expected b/src/tests/golden/theme-css/default.expected
index 47a7eaea4..5a79290b1 100644
--- a/src/tests/golden/theme-css/default.expected
+++ b/src/tests/golden/theme-css/default.expected
@@ -8,7 +8,7 @@
   --verso-info-color: #000000;
   --verso-info-indicator-color: #4777ff;
   --verso-warning-color: #000000;
-  --verso-warning-indicator-color: #e7a71d;
+  --verso-warning-indicator-color: #d97706;
   --verso-error-color: #cc0000;
   --verso-error-indicator-color: #ff0000;
   --verso-code-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
diff --git a/src/tests/integration/code-content-doc/expected/tex/main.tex b/src/tests/integration/code-content-doc/expected/tex/main.tex
index 9b8486643..ff617593e 100644
--- a/src/tests/integration/code-content-doc/expected/tex/main.tex
+++ b/src/tests/integration/code-content-doc/expected/tex/main.tex
@@ -135,7 +135,7 @@
 \definecolor{warningColor}{HTML}{000000}
 \definecolor{infoColor}{HTML}{000000}
 \definecolor{errorIndicatorColor}{HTML}{FF0000}
-\definecolor{warningIndicatorColor}{HTML}{E7A71D}
+\definecolor{warningIndicatorColor}{HTML}{D97706}
 \definecolor{infoIndicatorColor}{HTML}{4777FF}
 \renewcommand{\versoKeyword}[1]{\textcolor{versoKeywordColor}{\fontseries{eb}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoConst}[1]{\textcolor{versoConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
diff --git a/src/tests/integration/diagram-doc/expected/tex/main.tex b/src/tests/integration/diagram-doc/expected/tex/main.tex
index 09cd3746b..9926868b4 100644
--- a/src/tests/integration/diagram-doc/expected/tex/main.tex
+++ b/src/tests/integration/diagram-doc/expected/tex/main.tex
@@ -135,7 +135,7 @@
 \definecolor{warningColor}{HTML}{000000}
 \definecolor{infoColor}{HTML}{000000}
 \definecolor{errorIndicatorColor}{HTML}{FF0000}
-\definecolor{warningIndicatorColor}{HTML}{E7A71D}
+\definecolor{warningIndicatorColor}{HTML}{D97706}
 \definecolor{infoIndicatorColor}{HTML}{4777FF}
 \renewcommand{\versoKeyword}[1]{\textcolor{versoKeywordColor}{\fontseries{eb}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoConst}[1]{\textcolor{versoConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
diff --git a/src/tests/integration/extra-files-doc/expected/tex/main.tex b/src/tests/integration/extra-files-doc/expected/tex/main.tex
index a4f708321..3a1f744b4 100644
--- a/src/tests/integration/extra-files-doc/expected/tex/main.tex
+++ b/src/tests/integration/extra-files-doc/expected/tex/main.tex
@@ -135,7 +135,7 @@
 \definecolor{warningColor}{HTML}{000000}
 \definecolor{infoColor}{HTML}{000000}
 \definecolor{errorIndicatorColor}{HTML}{FF0000}
-\definecolor{warningIndicatorColor}{HTML}{E7A71D}
+\definecolor{warningIndicatorColor}{HTML}{D97706}
 \definecolor{infoIndicatorColor}{HTML}{4777FF}
 \renewcommand{\versoKeyword}[1]{\textcolor{versoKeywordColor}{\fontseries{eb}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoConst}[1]{\textcolor{versoConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
diff --git a/src/tests/integration/front-matter-doc/expected/tex/main.tex b/src/tests/integration/front-matter-doc/expected/tex/main.tex
index 716878d92..813348b4f 100644
--- a/src/tests/integration/front-matter-doc/expected/tex/main.tex
+++ b/src/tests/integration/front-matter-doc/expected/tex/main.tex
@@ -135,7 +135,7 @@
 \definecolor{warningColor}{HTML}{000000}
 \definecolor{infoColor}{HTML}{000000}
 \definecolor{errorIndicatorColor}{HTML}{FF0000}
-\definecolor{warningIndicatorColor}{HTML}{E7A71D}
+\definecolor{warningIndicatorColor}{HTML}{D97706}
 \definecolor{infoIndicatorColor}{HTML}{4777FF}
 \renewcommand{\versoKeyword}[1]{\textcolor{versoKeywordColor}{\fontseries{eb}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoConst}[1]{\textcolor{versoConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
diff --git a/src/tests/integration/inheritance-doc/expected/tex/main.tex b/src/tests/integration/inheritance-doc/expected/tex/main.tex
index c42d0377d..256fd484c 100644
--- a/src/tests/integration/inheritance-doc/expected/tex/main.tex
+++ b/src/tests/integration/inheritance-doc/expected/tex/main.tex
@@ -135,7 +135,7 @@
 \definecolor{warningColor}{HTML}{000000}
 \definecolor{infoColor}{HTML}{000000}
 \definecolor{errorIndicatorColor}{HTML}{FF0000}
-\definecolor{warningIndicatorColor}{HTML}{E7A71D}
+\definecolor{warningIndicatorColor}{HTML}{D97706}
 \definecolor{infoIndicatorColor}{HTML}{4777FF}
 \renewcommand{\versoKeyword}[1]{\textcolor{versoKeywordColor}{\fontseries{eb}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoConst}[1]{\textcolor{versoConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
diff --git a/src/tests/integration/sample-doc/expected/tex/main.tex b/src/tests/integration/sample-doc/expected/tex/main.tex
index cbcc6c95b..cd3eaf602 100644
--- a/src/tests/integration/sample-doc/expected/tex/main.tex
+++ b/src/tests/integration/sample-doc/expected/tex/main.tex
@@ -135,7 +135,7 @@
 \definecolor{warningColor}{HTML}{000000}
 \definecolor{infoColor}{HTML}{000000}
 \definecolor{errorIndicatorColor}{HTML}{FF0000}
-\definecolor{warningIndicatorColor}{HTML}{E7A71D}
+\definecolor{warningIndicatorColor}{HTML}{D97706}
 \definecolor{infoIndicatorColor}{HTML}{4777FF}
 \renewcommand{\versoKeyword}[1]{\textcolor{versoKeywordColor}{\fontseries{eb}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoConst}[1]{\textcolor{versoConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
diff --git a/src/verso-manual/VersoManual.lean b/src/verso-manual/VersoManual.lean
index acd9272f8..6d1feb477 100644
--- a/src/verso-manual/VersoManual.lean
+++ b/src/verso-manual/VersoManual.lean
@@ -13,6 +13,8 @@ import Verso.Output.Html
 import Verso.Output.Html.CssVars
 import Verso.Theme.Code
 import Verso.Theme.Code.Defaults
+import VersoManual.Theme
+import VersoManual.Theme.Defaults
 import Verso.Output.Html.KaTeX
 import Verso.Output.Html.ElasticLunr
 import Verso.Doc.Lsp
@@ -237,6 +239,20 @@ structure Config extends HtmlConfig, TeXConfig, OutputConfig where
   both sides.
   -/
   searchPriorities : SearchPriorities := {}
+
+  /--
+  When true (the default), contrast problems reported by
+  {Lean.Doc.name}`Verso.Theme.ManualTheme.checkAccessibility` fail the build. When false they are
+  logged as warnings and the build proceeds.
+  -/
+  strictThemeContrast : Bool := true
+
+  /--
+  When true (the default), color-vision-deficiency problems reported by
+  {Lean.Doc.name}`Verso.Theme.ManualTheme.checkAccessibility` fail the build. When false they are
+  logged as warnings and the build proceeds.
+  -/
+  strictThemeColorblind : Bool := true
 deriving ToJson, FromJson
 
 structure RenderConfig extends Config where
@@ -245,10 +261,12 @@ structure RenderConfig extends Config where
   -/
   linkTargets : TraverseState → Multi.AllRemotes → LinkTargets Manual.TraverseContext := (·.localTargets ++ ·.remoteTargets)
   /--
-  The active {Lean.Doc.name}`Verso.Theme.CodeTheme`. Its CSS-variable block is written to
-  {lit}`verso-themes.css` so the page-level highlighting rules read the chosen colors.
+  The active {Lean.Doc.name}`Verso.Theme.ManualTheme`. Its CSS-variable block (the
+  inherited {Lean.Doc.name}`Verso.Theme.CodeTheme` variables plus the manual-chrome
+  additions) is written to {lit}`verso-themes.css` so the page-level highlighting rules and
+  chrome read the chosen values.
   -/
-  codeTheme : Verso.Theme.CodeTheme := Verso.Theme.CodeTheme.Default
+  manualTheme : Verso.Theme.ManualTheme := Verso.Theme.ManualTheme.Default
 
 namespace Config
 
@@ -402,7 +420,7 @@ def emitTeX (config : RenderConfig) (text : Part Manual) : EmitM Unit := do
   withFile (dir.join "main.tex") .write fun h => do
     if config.verbose then
       IO.println s!"Saving {dir.join "main.tex"}"
-    h.putStrLn (preamble text.titleString authors date packages.toList preambleItems.toList config.codeTheme)
+    h.putStrLn (preamble text.titleString authors date packages.toList preambleItems.toList config.manualTheme.toCodeTheme)
     -- \frontmatter is inserted by our hardcoded preamble before the ToC, so it doesn't get inserted
     -- here. If there's any text at the start of the front matter, then we need to clear it to a new
     -- recto page after the ToC
@@ -765,26 +783,24 @@ where
     emitFindHtml toc dir state xrefJson config.toConfig
     if .search ∈ config.features then
       emitSearchResultsHtml toc dir titleToShow state config.toConfig
-    IO.FS.withFile (dir.join "verso-vars.css") .write fun h => do
-      h.putStrLn Html.«verso-vars.css»
     IO.FS.withFile (dir.join "book.css") .write fun h => do
       h.putStrLn Html.Css.pageStyle
     IO.FS.withFile (dir.join "verso-themes.css") .write fun h => do
-      let assetRoot := s!"-verso-data/themes/{config.codeTheme.name}"
-      let faceRules := config.codeTheme.fontFaceRules assetRoot
+      let assetRoot := s!"-verso-data/themes/{config.manualTheme.name}"
+      let faceRules := config.manualTheme.fontFaceRules assetRoot
       unless faceRules.isEmpty do
         h.putStrLn faceRules
-      h.putStrLn s!":root \{\n{config.codeTheme.cssVariables}}"
-      let extra := config.codeTheme.extraCss assetRoot
+      h.putStrLn s!":root \{\n{config.manualTheme.cssVariables}}"
+      let extra := config.manualTheme.extraCss assetRoot
       unless extra.isEmpty do
         h.putStrLn ""
         h.putStrLn extra
-    for (path, bytes, _, _) in config.codeTheme.fontAssets s!"-verso-data/themes/{config.codeTheme.name}" do
+    for (path, bytes, _, _) in config.manualTheme.fontAssets s!"-verso-data/themes/{config.manualTheme.name}" do
       let abs := dir.join path
       if let some p := abs.parent then ensureDir p
       IO.FS.writeBinFile abs bytes
-    for a in config.codeTheme.assets do
-      let path := dir.join "-verso-data" |>.join "themes" |>.join config.codeTheme.name |>.join a.path
+    for a in config.manualTheme.assets do
+      let path := dir.join "-verso-data" |>.join "themes" |>.join config.manualTheme.name |>.join a.path
       if let some p := path.parent then ensureDir p
       IO.FS.writeBinFile path a.contents
     for (src, dest) in config.extraFiles do
@@ -851,26 +867,24 @@ where
       if let some alt := text.metadata.bind (·.shortTitle) then
         alt
       else titleHtml
-    IO.FS.withFile (root / "verso-vars.css") .write fun h => do
-      h.putStrLn Html.«verso-vars.css»
     IO.FS.withFile (root / "book.css") .write fun h => do
       h.putStrLn Html.Css.pageStyle
     IO.FS.withFile (root / "verso-themes.css") .write fun h => do
-      let assetRoot := s!"-verso-data/themes/{config.codeTheme.name}"
-      let faceRules := config.codeTheme.fontFaceRules assetRoot
+      let assetRoot := s!"-verso-data/themes/{config.manualTheme.name}"
+      let faceRules := config.manualTheme.fontFaceRules assetRoot
       unless faceRules.isEmpty do
         h.putStrLn faceRules
-      h.putStrLn s!":root \{\n{config.codeTheme.cssVariables}}"
-      let extra := config.codeTheme.extraCss assetRoot
+      h.putStrLn s!":root \{\n{config.manualTheme.cssVariables}}"
+      let extra := config.manualTheme.extraCss assetRoot
       unless extra.isEmpty do
         h.putStrLn ""
         h.putStrLn extra
-    for (path, bytes, _, _) in config.codeTheme.fontAssets s!"-verso-data/themes/{config.codeTheme.name}" do
+    for (path, bytes, _, _) in config.manualTheme.fontAssets s!"-verso-data/themes/{config.manualTheme.name}" do
       let abs := root.join path
       if let some p := abs.parent then ensureDir p
       IO.FS.writeBinFile abs bytes
-    for a in config.codeTheme.assets do
-      let path := root.join "-verso-data" |>.join "themes" |>.join config.codeTheme.name |>.join a.path
+    for a in config.manualTheme.assets do
+      let path := root.join "-verso-data" |>.join "themes" |>.join config.manualTheme.name |>.join a.path
       if let some p := path.parent then ensureDir p
       IO.FS.writeBinFile path a.contents
     for (src, dest) in config.extraFiles do
@@ -988,10 +1002,12 @@ open Verso.CLI
 def manualMain (text : Part Manual)
     (extensionImpls : ExtensionImpls := by exact extension_impls%)
     (codeThemes : Verso.Theme.CodeThemeTable := by exact code_themes%)
+    (manualThemes : Verso.Theme.ManualThemeTable := by exact manual_themes%)
     (options : List String)
     (config : RenderConfig := {})
     (extraSteps : List ExtraStep := []) : IO UInt32 :=
   let _ := codeThemes
+  let _ := manualThemes
   ReaderT.run go extensionImpls
 
 where
@@ -1043,9 +1059,26 @@ where
   fixBase (base : String) : String :=
     if base.endsWith "/" then base else base ++ "/"
 
+  /--
+  Runs the theme's accessibility check and routes each {name (full := Verso.Color.Issue)}`Issue`
+  through {name}`MonadBuildLog`: contrast issues use {name (full := Verso.Genre.Manual.RenderConfig.strictThemeContrast)}`strictThemeContrast`
+  and colorblindness issues use {name (full := Verso.Genre.Manual.RenderConfig.strictThemeColorblind)}`strictThemeColorblind`
+  to decide error vs. warning. The build proceeds either way; logged errors set the exit code.
+  -/
+  runThemeAccessibilityCheck (cfg : RenderConfig) : ReaderT ExtensionImpls (BuildLogT IO) Unit := do
+    for issue in cfg.manualTheme.checkAccessibility do
+      let strict := match issue.kind with
+        | .contrast => cfg.strictThemeContrast
+        | .colorblind => cfg.strictThemeColorblind
+      let colors := issue.offending.toList.map Verso.Theme.Color.css |> ", ".intercalate
+      let suffix := if colors.isEmpty then "" else s!" ({colors})"
+      let msg := s!"theme '{cfg.manualTheme.name}': {issue.message}{suffix}"
+      if strict then Verso.reportError msg else Verso.reportWarning msg
+
   go (extensionImpls : ExtensionImpls) : IO UInt32 := do
     let cfg ← opts config options
     runWithLogger <| flip ReaderT.run extensionImpls do
+      runThemeAccessibilityCheck cfg
       if cfg.emitTeX then
         if cfg.verbose then
           IO.println s!"Saving TeX"
diff --git a/src/verso-manual/VersoManual/Html.lean b/src/verso-manual/VersoManual/Html.lean
index 18550c0a2..ff5c37cb3 100644
--- a/src/verso-manual/VersoManual/Html.lean
+++ b/src/verso-manual/VersoManual/Html.lean
@@ -436,7 +436,6 @@ public def page
         <meta name="viewport" content="height=device-height, width=device-width, initial-scale=1, minimum-scale=1, maximum-scale=1"/>
         <title>{{textTitle}}</title>
         <link rel="stylesheet" href="book.css" />
-        <link rel="stylesheet" href="verso-vars.css" />
         <link rel="stylesheet" href="verso-themes.css" />
         <script src="https://cdn.jsdelivr.net/npm/marked@11.1.1/marked.min.js" integrity="sha384-zbcZAIxlvJtNE3Dp5nxLXdXtXyxwOdnILY1TDPVmKFhl4r4nSUG1r8bcFXGVa4Te" crossorigin="anonymous"></script>
         {{ searchAssetTags }}
diff --git a/src/verso-manual/VersoManual/Html/Style.lean b/src/verso-manual/VersoManual/Html/Style.lean
index 9338eac02..172f8434f 100644
--- a/src/verso-manual/VersoManual/Html/Style.lean
+++ b/src/verso-manual/VersoManual/Html/Style.lean
@@ -24,9 +24,6 @@ public def pageStyle : String := r####"
     --verso-logo-height: var(--verso-header-height);
 
     /** Table of Contents appearance **/
-    --verso-toc-background-color: #fafafa;
-    --verso-toc-text-color: var(--verso-text-color);
-
     /* How long should the ToC animation take? */
     --verso-toc-transition-time: 0.4s;
 
@@ -38,10 +35,6 @@ public def pageStyle : String := r####"
     --verso-burger-width: 1.25rem;
     --verso-burger-line-width: 0.2rem;
     --verso-burger-line-radius: 0.2rem;
-    --verso-burger-toc-visible-color: var(--verso-toc-text-color);
-    --verso-burger-toc-visible-shadow-color: #ffffff;
-    --verso-burger-toc-hidden-color: #0e2431;
-    --verso-burger-toc-hidden-shadow-color: #ffffff;
 
     /* The "burger menu" may need to get bigger for mobile screens */
     --verso-mobile-burger-height: 1.5rem;
@@ -85,6 +78,8 @@ html {
 body {
     margin: 0;
     padding: 0;
+    background: var(--verso-background-color);
+    color: var(--verso-text-color);
 }
 
 /******** Theme ********/
@@ -124,7 +119,7 @@ header {
 	z-index: 99;
 	left: 0;
 	right: 0;
-	background: white;
+	background: var(--verso-header-background);
 	display: flex;
 	align-items: center;
 	height: var(--verso-header-height);
@@ -158,7 +153,7 @@ header {
 
 .header-title {
     text-decoration: none;
-    color: black;
+    color: var(--verso-text-color);
     font-size: 2rem;
     font-weight: bold;
     display: block;
@@ -275,13 +270,13 @@ main [id] {
 }
 
 #toc a {
-    color: #333;
+    color: var(--verso-toc-text-color);
     text-decoration: none;
 }
 
 #toc a:hover {
     text-decoration: underline;
-    color: #000;
+    color: var(--verso-toc-text-color);
 }
 
 .toc-title {
@@ -345,7 +340,7 @@ main [id] {
     width: calc(var(--verso-toc-triangle-width) + var(--verso-toc-triangle-left-space));
     height: var(--verso-toc-triangle-height);
     display: inline-block;
-    background-color: black;
+    background-color: var(--verso-toc-text-color);
     content: ' ';
     transition: ease 0.2s;
     margin-right: var(--verso-toc-triangle-margin);
@@ -443,7 +438,7 @@ main [id] {
     flex: 1;
     justify-content: center;
     align-items: center;
-    color: black;
+    color: var(--verso-link-color);
     text-decoration: none;
 }
 
@@ -738,6 +733,16 @@ main .section-toc a:hover {
     text-decoration: underline;
 }
 
+/* Content links pick up the theme's link colors. Scoped to `main` so chrome links (header,
+   ToC, search, permalinks) keep their own scoped rules. */
+main a {
+    color: var(--verso-link-color);
+}
+
+main a:visited {
+    color: var(--verso-visited-link-color);
+}
+
 /******** Manual-specific changes to highlighted Lean code ********/
 
 /* Don't scroll horizontally due to long identifiers (e.g. option names) */
diff --git a/src/verso-manual/VersoManual/Theme.lean b/src/verso-manual/VersoManual/Theme.lean
new file mode 100644
index 000000000..4d4c0d992
--- /dev/null
+++ b/src/verso-manual/VersoManual/Theme.lean
@@ -0,0 +1,246 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+public meta import VersoManual.Theme.Ext
+public import Verso.Theme.Code
+public meta import Lean.Elab.Term
+
+set_option linter.missingDocs true
+set_option doc.verso true
+
+/-!
+The manual genre's theme. {lit}`ManualTheme` extends {lit}`CodeTheme` with the additional color
+and font fields the manual chrome (page, header, ToC, search box, burger menu, content links)
+needs. The manual genre emits every {lit}`--verso-*` chrome variable from a single chosen manual
+theme.
+-/
+
+namespace Verso.Theme
+
+/--
+A manual-genre theme: a {Lean.Doc.name}`Verso.Theme.CodeTheme` plus the color and font fields the
+chrome needs (header background, ToC, burger menu, search box, content links). Defaults reproduce
+today's chrome.
+
+The cascade rule from {Lean.Doc.name}`Verso.Theme.CodeTheme` continues: a field that today reads
+the page background or text color defaults from the inherited field, so overriding the inherited
+field carries through.
+-/
+public structure ManualTheme extends CodeTheme where
+  /-- The font used for body prose. -/
+  textFace : Typeface := .sans
+  /-- The font used for headings, the ToC, navigation, and other structural text. -/
+  structureFace : Typeface := .sans
+
+  /-- A raised chrome surface tint (default for the ToC background and the search box). -/
+  surfaceColor : Color := color%#f8f9fa
+  /-- The header bar background. Defaults to the page background. -/
+  headerBackground : Color := background
+  /-- The ToC background. -/
+  tocBackground : Color := color%#fafafa
+
+  /-- The default border color for chrome elements such as the search box outline. Defaults to
+  a slate gray that clears WCAG 1.4.11 (3:1) against both white and the surface color. -/
+  borderColor : Color := color%#878787
+  /-- The default muted text color for chrome elements such as search hints. -/
+  mutedColor : Color := color%#777777
+  /-- The color used to highlight matched search terms. Defaults to the code theme's selection. -/
+  highlightColor : Color := selectedColor
+
+  /-- The color of content links in body prose. -/
+  linkColor : Color := color%#0066cc
+  /-- The color of visited content links. -/
+  visitedLinkColor : Color := linkColor
+
+  /-- The text color used inside the ToC. -/
+  tocTextColor : Color := textColor
+
+  /-- The color of the burger-menu lines while the ToC is visible. -/
+  burgerVisibleColor : Color := tocTextColor
+  /-- The shadow color drawn under the burger-menu lines while the ToC is visible. -/
+  burgerVisibleShadowColor : Color := Color.white
+  /-- The color of the burger-menu lines while the ToC is hidden. -/
+  burgerHiddenColor : Color := color%#0e2431
+  /-- The shadow color drawn under the burger-menu lines while the ToC is hidden. -/
+  burgerHiddenShadowColor : Color := Color.white
+
+/-! # Attribute and materialization -/
+
+public section
+
+/--
+Attribute that registers a {Lean.Doc.name}`ManualTheme` declaration as an available theme. The
+declaration must be in the current module (not imported), and its registration name is the decl's
+name with macro scopes erased.
+-/
+syntax (name := manual_theme) "manual_theme" : attr
+
+open Lean in
+meta initialize
+  registerBuiltinAttribute {
+    name := `manual_theme,
+    ref := by exact decl_name%,
+    add := fun decl _stx kind => do
+      unless kind == AttributeKind.global do
+        throwError "invalid attribute 'manual_theme', must be global"
+      unless ((← getEnv).getModuleIdxFor? decl).isNone do
+        throwError "invalid attribute 'manual_theme', declaration is in an imported module"
+      modifyEnv fun env => manualThemeExt.addEntry env decl.eraseMacroScopes
+    descr := "Registers a definition as an available manual theme"
+  }
+
+end section
+
+/--
+A materialized table of registered {Lean.Doc.name}`ManualTheme` values, keyed by registration
+name. Built at runtime by the {lit}`manual_themes%` term elaborator from the set of
+{Lean.Doc.name}`ManualTheme` declarations tagged with the {lit}`@[manual_theme]` attribute.
+-/
+public structure ManualThemeTable where
+  /-- The map from a theme's registration name to its value. -/
+  themes : Lean.NameMap ManualTheme := {}
+
+namespace ManualThemeTable
+
+/-- The empty table. -/
+public def empty : ManualThemeTable := {}
+
+public instance : EmptyCollection ManualThemeTable := ⟨empty⟩
+
+/-- Looks up a theme by its registration name. -/
+public def find? (t : ManualThemeTable) (n : Lean.Name) : Option ManualTheme :=
+  t.themes.find? n
+
+/-- Inserts a theme under the given registration name. -/
+public def insert (t : ManualThemeTable) (n : Lean.Name) (theme : ManualTheme) : ManualThemeTable :=
+  ⟨t.themes.insert n theme⟩
+
+/-- Builds a table from a list of pairs. -/
+public def fromList (xs : List (Lean.Name × ManualTheme)) : ManualThemeTable :=
+  xs.foldl (fun (acc : ManualThemeTable) (p : Lean.Name × ManualTheme) => acc.insert p.1 p.2) empty
+
+end ManualThemeTable
+
+public section
+
+/-- Term elaborator that materializes the registered manual-theme table at compile time. -/
+syntax (name := manual_themes) "manual_themes%" : term
+
+open Lean Elab Term in
+private meta def manualThemePair [Monad m] [MonadRef m] [MonadQuotation m] (n : Name) : m Term := do
+  let quoted : Term := quote n
+  let ident ← mkCIdentFromRef n
+  `(($quoted, $(⟨ident⟩)))
+
+open Lean Elab Term in
+/-- Elaborator for the {lit}`manual_themes%` macro: emits a
+{Lean.Doc.name}`Verso.Theme.ManualThemeTable` literal whose entries are every registered
+{Lean.Doc.name}`Verso.Theme.ManualTheme` decl. -/
+@[term_elab manual_themes]
+meta def elabManualThemes : TermElab := fun _stx expected? => do
+  let env ← getEnv
+  let mut names : Array Name := #[]
+  for n in manualThemeExt.getState env do
+    names := names.push n
+  for imported in manualThemeExt.toEnvExtension.getState env |>.importedEntries do
+    for n in imported do
+      names := names.push n
+  let stx ← `(Verso.Theme.ManualThemeTable.fromList [$[($(← names.mapM manualThemePair) : Lean.Name × Verso.Theme.ManualTheme)],*])
+  elabTerm stx expected?
+
+end section
+
+/-! # CSS variables -/
+
+namespace ManualTheme
+
+private def cssDecl (name value : String) : String :=
+  s!"  --{name}: {value};\n"
+
+private def colorDecl (name : String) (c : Color) : String :=
+  cssDecl name (Color.css c)
+
+/--
+The CSS-variable body for the manual-chrome fields a {Lean.Doc.name}`ManualTheme` adds on top of
+its inherited {Lean.Doc.name}`Verso.Theme.CodeTheme`. The manual genre concatenates this with
+{Lean.Doc.name}`Verso.Theme.CodeTheme.cssVariables` to produce the contents of its
+{lit}`:root` block.
+-/
+public def manualCssVariables (theme : ManualTheme) : String :=
+  String.join [
+    cssDecl "verso-text-font-family" theme.textFace.cssFamily,
+    cssDecl "verso-structure-font-family" theme.structureFace.cssFamily,
+    colorDecl "verso-surface-color" theme.surfaceColor,
+    colorDecl "verso-header-background" theme.headerBackground,
+    colorDecl "verso-toc-background-color" theme.tocBackground,
+    colorDecl "verso-border-color" theme.borderColor,
+    colorDecl "verso-muted-color" theme.mutedColor,
+    colorDecl "verso-highlight-color" theme.highlightColor,
+    colorDecl "verso-link-color" theme.linkColor,
+    colorDecl "verso-visited-link-color" theme.visitedLinkColor,
+    colorDecl "verso-toc-text-color" theme.tocTextColor,
+    colorDecl "verso-burger-toc-visible-color" theme.burgerVisibleColor,
+    colorDecl "verso-burger-toc-visible-shadow-color" theme.burgerVisibleShadowColor,
+    colorDecl "verso-burger-toc-hidden-color" theme.burgerHiddenColor,
+    colorDecl "verso-burger-toc-hidden-shadow-color" theme.burgerHiddenShadowColor
+  ]
+
+/--
+The full CSS-variable body for a {Lean.Doc.name}`ManualTheme`: the inherited
+{Lean.Doc.name}`Verso.Theme.CodeTheme` variables followed by the manual-chrome additions. This is
+what the manual genre writes into the body of {lit}`verso-themes.css`'s {lit}`:root` block.
+-/
+public def cssVariables (theme : ManualTheme) : String :=
+  theme.toCodeTheme.cssVariables ++ theme.manualCssVariables
+
+end ManualTheme
+
+/-! # Accessibility -/
+
+namespace ManualTheme
+
+/--
+Runs the inherited {Lean.Doc.name}`Verso.Theme.CodeTheme.checkAccessibility` and then verifies
+the manual-chrome pairs:
+
+- content {Lean.Doc.name (full := Verso.Theme.ManualTheme.linkColor)}`linkColor` and
+  {Lean.Doc.name (full := Verso.Theme.ManualTheme.visitedLinkColor)}`visitedLinkColor` against
+  the page background
+- {Lean.Doc.name (full := Verso.Theme.ManualTheme.tocTextColor)}`tocTextColor` against the
+  {Lean.Doc.name (full := Verso.Theme.ManualTheme.tocBackground)}`tocBackground`
+- the header title color (body text) against
+  {Lean.Doc.name (full := Verso.Theme.ManualTheme.headerBackground)}`headerBackground`
+- the search-box muted and border colors against the surface and page backgrounds
+- body text against the
+  {Lean.Doc.name (full := Verso.Theme.ManualTheme.highlightColor)}`highlightColor`, since search
+  results render matched terms with that color as their background
+-/
+public def checkAccessibility (theme : ManualTheme) : Array Color.Issue := Id.run do
+  let mut issues := theme.toCodeTheme.checkAccessibility
+  issues := issues ++ Color.contrastIssues Color.textContrastThreshold
+    "link color on page background" theme.linkColor theme.background
+  issues := issues ++ Color.contrastIssues Color.textContrastThreshold
+    "visited link color on page background" theme.visitedLinkColor theme.background
+  issues := issues ++ Color.contrastIssues Color.textContrastThreshold
+    "toc text on toc background" theme.tocTextColor theme.tocBackground
+  issues := issues ++ Color.contrastIssues Color.textContrastThreshold
+    "header title on header background" theme.textColor theme.headerBackground
+  issues := issues ++ Color.contrastIssues Color.textContrastThreshold
+    "body text on highlight background" theme.textColor theme.highlightColor
+  issues := issues ++ Color.contrastIssues Color.largeContrastThreshold
+    "border color on surface" theme.borderColor theme.surfaceColor
+  issues := issues ++ Color.contrastIssues Color.largeContrastThreshold
+    "border color on page background" theme.borderColor theme.background
+  -- "Muted text" is for incidental hints (search placeholder, secondary metadata) and so
+  -- uses the AA Large / UI 3.0 threshold rather than 4.5 for primary body text.
+  issues := issues ++ Color.contrastIssues Color.largeContrastThreshold
+    "muted text on surface" theme.mutedColor theme.surfaceColor
+  issues := issues ++ Color.contrastIssues Color.largeContrastThreshold
+    "muted text on page background" theme.mutedColor theme.background
+  return issues
+
+end ManualTheme
diff --git a/src/verso-manual/VersoManual/Theme/Defaults.lean b/src/verso-manual/VersoManual/Theme/Defaults.lean
new file mode 100644
index 000000000..58a71b686
--- /dev/null
+++ b/src/verso-manual/VersoManual/Theme/Defaults.lean
@@ -0,0 +1,27 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+public import VersoManual.Theme
+public import Verso.Theme.Code.Defaults
+
+set_option linter.missingDocs true
+set_option doc.verso true
+
+/-!
+Built-in {Lean.Doc.name}`Verso.Theme.ManualTheme` values. The default theme reproduces today's
+chrome so existing manuals render unchanged when no override is configured.
+-/
+
+namespace Verso.Theme
+
+/--
+The default manual theme: typography and chrome that reproduce today's hardcoded look. Other
+built-in themes live alongside it in the {Lean.Doc.name}`Verso.Theme.ManualTheme` namespace.
+-/
+@[manual_theme]
+public def ManualTheme.Default : ManualTheme where
+  toCodeTheme := CodeTheme.Default
diff --git a/src/verso-manual/VersoManual/Theme/Ext.lean b/src/verso-manual/VersoManual/Theme/Ext.lean
new file mode 100644
index 000000000..03d750aa6
--- /dev/null
+++ b/src/verso-manual/VersoManual/Theme/Ext.lean
@@ -0,0 +1,29 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+public import Lean.Environment
+
+public section
+
+open Lean
+
+namespace Verso.Theme
+
+/--
+Environment extension that records every declaration tagged with the `@[manual_theme]`
+attribute, keyed by the declaration name (with macro scopes erased). Kept distinct from the
+code-theme registry so a consumer that enumerates code themes does not see a duplicate for every
+manual theme.
+-/
+initialize manualThemeExt :
+    PersistentEnvExtension Name Name NameSet ←
+  registerPersistentEnvExtension {
+    mkInitial := pure {},
+    addImportedFn := fun _ => pure {},
+    addEntryFn := fun s n => s.insert n,
+    exportEntriesFn := fun s =>
+      s.toArray.qsort Name.quickLt
+  }
diff --git a/src/verso/Verso/Theme/Code.lean b/src/verso/Verso/Theme/Code.lean
index e7eb3f9c8..1887d1be6 100644
--- a/src/verso/Verso/Theme/Code.lean
+++ b/src/verso/Verso/Theme/Code.lean
@@ -84,8 +84,9 @@ public structure CodeTheme where
   infoIndicatorColor : Color := color%#4777ff
   /-- The message-text color for warning diagnostics. -/
   warningColor : Color := textColor
-  /-- The accent color (left border, underline) for warning diagnostics. -/
-  warningIndicatorColor : Color := color%#e7a71d
+  /-- The accent color (left border, underline) for warning diagnostics. Defaults to a darker
+  amber than the legacy {lit}`#e7a71d` so it clears WCAG 1.4.11 (3:1) against white. -/
+  warningIndicatorColor : Color := color%#d97706
   /-- The message-text color for error diagnostics. -/
   errorColor : Color := color%#cc0000
   /-- The accent color (left border, underline) for error diagnostics. -/
@@ -289,12 +290,11 @@ public def checkAccessibility (theme : CodeTheme) : Array Color.Issue := Id.run
   -- Code drawn on the tactic-state background (for example a hypothesis).
   issues := issues ++ Color.contrastIssues Color.textContrastThreshold
     "code on tactic-state background" theme.codeColor theme.tacticStateBackground
-  -- Colorblindness: tokens and indicators stay mutually distinguishable.
-  issues := issues ++ Color.colorblindIssues Color.distinguishableThreshold
-    (theme.tokenSummaries ++ #[
-      ("error indicator", theme.errorIndicatorColor),
-      ("warning indicator", theme.warningIndicatorColor),
-      ("info indicator", theme.infoIndicatorColor)])
+  -- Colorblindness: token colors stay mutually distinguishable. Severity indicators are
+  -- intentionally excluded here: error red and warning yellow/amber routinely collapse under
+  -- protanopia and deuteranopia, but they are visually paired with their distinct semantics
+  -- (text content, icons) so the color collision is not the only signal.
+  issues := issues ++ Color.colorblindIssues Color.distinguishableThreshold theme.tokenSummaries
   return issues
 
 end CodeTheme
diff --git a/src/verso/Verso/Theme/Color/Accessibility.lean b/src/verso/Verso/Theme/Color/Accessibility.lean
index 2c59cef5b..f072fb868 100644
--- a/src/verso/Verso/Theme/Color/Accessibility.lean
+++ b/src/verso/Verso/Theme/Color/Accessibility.lean
@@ -110,6 +110,11 @@ public def contrastIssues (threshold : Float) (description : String) (fg bg : Co
 Checks that the given named colors stay mutually distinguishable under each of the three
 dichromacies. Reports a {name (full := IssueKind.colorblind)}`colorblind` issue for any pair that
 collapses (ΔE below {name}`threshold`) under some simulation.
+
+Pairs that are already identical in normal vision are skipped: the theme is not relying on color
+to distinguish them, so a color-vision-deficient reader is in no worse a position than a
+normal-vision one. Such pairs typically encode their distinction through weight or style (e.g. a
+bold keyword versus an italic variable, both black).
 -/
 public def colorblindIssues (threshold : Float) (colors : Array (String × Color)) : Array Issue := Id.run do
   let mut out := #[]
@@ -117,6 +122,7 @@ public def colorblindIssues (threshold : Float) (colors : Array (String × Color
     for j in [i + 1:colors.size] do
       let (n1, c1) := colors[i]!
       let (n2, c2) := colors[j]!
+      if c1 == c2 then continue
       for cvd in [CVD.protanopia, CVD.deuteranopia, CVD.tritanopia] do
         unless distinguishable? threshold (dichromacy cvd c1) (dichromacy cvd c2) do
           out := out.push
diff --git a/static-web/search/search-box.css b/static-web/search/search-box.css
index b97787e0d..40f37fab4 100644
--- a/static-web/search/search-box.css
+++ b/static-web/search/search-box.css
@@ -37,7 +37,7 @@
     margin: 0;
     vertical-align: bottom;
     border: none;
-    border-bottom: 1px solid gray;
+    border-bottom: 1px solid var(--verso-border-color, gray);
     position: relative;
     cursor: pointer;
     width: var(--search-bar-width);
@@ -60,7 +60,7 @@
 #search-wrapper .cb_edit:empty:before {
     content: attr(placeholder);
     pointer-events: none;
-    color: #888;
+    color: var(--verso-muted-color, #888);
     font-family: sans-serif;
     display: block;
 }
@@ -228,7 +228,7 @@
 
 #search-wrapper .more-results {
     text-align: center;
-    color: #777;
+    color: var(--verso-muted-color, #777);
     font-size: 0.7rem;
 }
 
diff --git a/static-web/search/search-highlight.css b/static-web/search/search-highlight.css
index cbe2378dd..3a0929f3a 100644
--- a/static-web/search/search-highlight.css
+++ b/static-web/search/search-highlight.css
@@ -1,5 +1,5 @@
 .text-search-results {
-    background-color: var(--verso-selected-color);
+    background-color: var(--verso-highlight-color);
 }
 
 .text-search-results.focused {
diff --git a/static-web/search/search-page.css b/static-web/search/search-page.css
index 711c1fbe8..49df40d25 100644
--- a/static-web/search/search-page.css
+++ b/static-web/search/search-page.css
@@ -17,7 +17,7 @@
     font-family: inherit;
     color: var(--verso-text-color, black);
     background-color: var(--verso-background-color, white);
-    border: 1px solid gray;
+    border: 1px solid var(--verso-border-color, gray);
     border-radius: 0.2rem;
     outline: none;
 }
@@ -128,7 +128,7 @@
 .search-page-list li.search-result em {
     font-style: normal;
     text-decoration: none;
-    background-color: var(--verso-selected-color, #def);
+    background-color: var(--verso-highlight-color, #def);
     border-radius: 0.15em;
     padding: 0 0.1em;
 }

From b1d6dc9164f4972f5768425390adc8bbdadfcb78 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Sun, 31 May 2026 14:10:03 +0200
Subject: [PATCH 09/31] feat: theme picker UI

---
 .github/workflows/ci.yml                      |   8 +
 UsersGuideMain.lean                           |  10 +-
 .../test_theme_customization.py               |  25 +-
 browser-tests/theme-picker/__init__.py        |   0
 .../theme-picker/test_theme_picker.py         | 508 ++++++++++++++++++
 src/tests/TestMain.lean                       |   2 +-
 src/tests/Tests/ColorAccessibility.lean       |  12 +-
 src/tests/Tests/Font.lean                     |   2 +-
 src/tests/Tests/HighlightedToTeX.lean         |   4 +-
 src/tests/ThemeTestMain.lean                  |  24 +-
 src/verso-manual/VersoManual.lean             | 319 ++++++++---
 src/verso-manual/VersoManual/Html.lean        |  34 +-
 src/verso-manual/VersoManual/Html/Config.lean |  12 +-
 src/verso-manual/VersoManual/Html/Style.lean  |  16 +-
 src/verso-manual/VersoManual/Theme.lean       |  82 +++
 .../VersoManual/Theme/Assets.lean             |  35 ++
 .../VersoManual/Theme/Defaults.lean           | 480 ++++++++++++++++-
 src/verso-manual/VersoManual/Theme/Emit.lean  | 153 ++++++
 src/verso/Verso/Theme/Code/Defaults.lean      |   9 +-
 static-web/theme/theme-picker.css             | 176 ++++++
 static-web/theme/theme-picker.js              | 309 +++++++++++
 21 files changed, 2113 insertions(+), 107 deletions(-)
 create mode 100644 browser-tests/theme-picker/__init__.py
 create mode 100644 browser-tests/theme-picker/test_theme_picker.py
 create mode 100644 src/verso-manual/VersoManual/Theme/Assets.lean
 create mode 100644 src/verso-manual/VersoManual/Theme/Emit.lean
 create mode 100644 static-web/theme/theme-picker.css
 create mode 100644 static-web/theme/theme-picker.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 363616b03..a1d50c9ac 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -199,6 +199,14 @@ jobs:
                   uv run --project browser-tests --extra test pytest \
                     browser-tests/theme-customization -v
 
+            - name: Run theme picker browser test
+              run: |
+                  # The picker test rebuilds the user's guide so it sees every shipped
+                  # @[manual_theme] (Default, DefaultDark, ChromaticLight/Dark, BeaconLight/Dark)
+                  # and can exercise switching between them.
+                  uv run --project browser-tests --extra test pytest \
+                    browser-tests/theme-picker -v
+
             - name: Build the VersoHtml site for browser tests
               run: |
                   # The verso-html genre renders literate JSON into a standalone HTML site.
diff --git a/UsersGuideMain.lean b/UsersGuideMain.lean
index c3f44a417..e4efe7150 100644
--- a/UsersGuideMain.lean
+++ b/UsersGuideMain.lean
@@ -7,6 +7,14 @@ open Verso.Genre.Manual
 def config : Config := {
   sourceLink := some "https://github.com/leanprover/verso",
   issueLink := some "https://github.com/leanprover/verso/issues"
+  -- The user's guide ships every theme as a live example, including ones with documented
+  -- accessibility trade-offs — most notably the canonical Solarized palette, whose token
+  -- colors are below WCAG AA's 4.5:1 contrast threshold for normal text by design. The
+  -- coverage and default-accessibility checks still fire (the default theme pair must be
+  -- accessible, and the registered set must offer an accessible choice on both
+  -- appearances), and per-theme warnings still surface the individual issues; the per-theme
+  -- warnings are silenced here to keep the build log readable.
+  warnPerThemeAccessibility := false
 }
 
-def main := manualMain (%doc UsersGuide.Basic)
+def main := manualMain (%doc UsersGuide.Basic) (config := { config with : RenderConfig })
diff --git a/browser-tests/theme-customization/test_theme_customization.py b/browser-tests/theme-customization/test_theme_customization.py
index 87cca718f..f506f9f19 100644
--- a/browser-tests/theme-customization/test_theme_customization.py
+++ b/browser-tests/theme-customization/test_theme_customization.py
@@ -239,13 +239,26 @@ def test_border_var(page):
 
 
 def test_prev_next_nav_color(page, server):
-    # The `.prev-next-buttons > *` rule previously forced `color: black`, ignoring the theme.
-    # It now reads `var(--verso-link-color)` so a dark page can still surface readable nav links.
+    # The `.prev-next-buttons > *` rule previously hardcoded `color: black`. It now reads
+    # `var(--verso-text-color)` — section navigation is body-text colored, not link-colored,
+    # so it stays readable on any themed background without competing with content links.
+    # Both `:link` and `:visited` must land on text color; the visited-link rule for `main a`
+    # has higher specificity than `.prev-next-buttons > *` and would otherwise paint visited
+    # prev/next links in the visited-link color.
     page.goto(server + "/Code-samples/")
-    _expect(
-        _color(page, ".prev-next-buttons > a"),
-        THEME["linkColor"],
-        "prev/next nav link color",
+    # Force the prev page into the visited-link state by navigating to it once and back.
+    page.evaluate("history.replaceState({}, '', '/Diagnostics/')")
+    page.goto(server + "/Diagnostics/")
+    page.goto(server + "/Code-samples/")
+    colors = page.evaluate(
+        """() => {
+            const links = Array.from(document.querySelectorAll('.prev-next-buttons > a'));
+            return links.map(a => getComputedStyle(a).color);
+        }"""
+    )
+    expected = _hex_to_rgb(THEME["textColor"])
+    assert colors and all(c == expected for c in colors), (
+        f"all prev/next links should be {expected}; got {colors}"
     )
 
 
diff --git a/browser-tests/theme-picker/__init__.py b/browser-tests/theme-picker/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/browser-tests/theme-picker/test_theme_picker.py b/browser-tests/theme-picker/test_theme_picker.py
new file mode 100644
index 000000000..e619f7a58
--- /dev/null
+++ b/browser-tests/theme-picker/test_theme_picker.py
@@ -0,0 +1,508 @@
+"""
+Browser tests for the theme picker (gear button + popover + dropdowns).
+
+Builds the user's guide (which ships multiple themes via @[manual_theme]) and exercises:
+  * gear placement in header-tools, left of the search box
+  * popover open/close, role + aria-* attributes, Escape returns focus to the gear
+  * focus trap inside the popover
+  * theme switching via dropdown sets data-verso-theme and data-verso-appearance
+  * persistence across reloads via localStorage
+  * "match system" auto-mode follows matchMedia(prefers-color-scheme), single mode does not
+  * graceful degradation when localStorage throws (page still loads, default theme applied)
+"""
+
+import socket
+import subprocess
+import time
+from pathlib import Path
+
+import pytest
+from playwright.sync_api import sync_playwright
+
+
+HERE = Path(__file__).parent
+REPO_ROOT = HERE.parent.parent
+SITE_DIR = REPO_ROOT / "_out" / "usersguide" / "html-multi"
+
+
+def _find_free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+@pytest.fixture(scope="module")
+def built_site():
+    subprocess.check_call(
+        ["lake", "build", "usersguide"],
+        cwd=REPO_ROOT,
+    )
+    if SITE_DIR.parent.exists():
+        subprocess.check_call(["rm", "-rf", str(SITE_DIR.parent)], cwd=REPO_ROOT)
+    subprocess.check_call(
+        ["lake", "exe", "usersguide", "--output", "_out/usersguide",
+         "--without-tex", "--without-html-single", "--with-html-multi"],
+        cwd=REPO_ROOT,
+    )
+    assert SITE_DIR.exists(), f"Manual build did not produce {SITE_DIR}"
+    return SITE_DIR
+
+
+@pytest.fixture(scope="module")
+def server(built_site):
+    port = _find_free_port()
+    proc = subprocess.Popen(
+        ["python", "-m", "http.server", str(port), "--bind", "127.0.0.1"],
+        cwd=built_site,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    time.sleep(0.5)
+    try:
+        yield f"http://127.0.0.1:{port}"
+    finally:
+        proc.terminate()
+        proc.wait()
+
+
+@pytest.fixture(scope="module")
+def playwright_instance():
+    with sync_playwright() as p:
+        yield p
+
+
+@pytest.fixture(params=["chromium", "firefox"])
+def page(request, playwright_instance, server):
+    """Per-test page so localStorage / focus state don't leak between tests."""
+    browser = getattr(playwright_instance, request.param).launch()
+    context = browser.new_context()
+    p = context.new_page()
+    p.goto(server + "/")
+    yield p
+    context.close()
+    browser.close()
+
+
+def _picker_button(page):
+    return page.locator("#theme-picker-button")
+
+
+def _dialog(page):
+    return page.locator("#theme-picker-dialog")
+
+
+def test_gear_height_and_centering_match_search(page):
+    """The gear glyph's ink height should be about 90% of the search input's outer height,
+    and the two centers should be aligned vertically. (The user asked for "90% as tall as
+    the search field and vertically centered with respect to the search field".)"""
+    page.set_viewport_size({"width": 1400, "height": 800})
+    page.locator("#theme-picker-button").wait_for(state="visible", timeout=5000)
+    m = page.evaluate(
+        """() => {
+            const gear = document.querySelector('#theme-picker-button .theme-picker-gear');
+            const input = document.querySelector('#search-wrapper .cb_edit');
+            // The visible glyph rect, not the line-box, is what reads as "the gear's
+            // height" — `Range.getBoundingClientRect()` snaps to the rendered ink box.
+            const r = document.createRange();
+            r.selectNodeContents(gear);
+            const ink = r.getBoundingClientRect();
+            const ir = input.getBoundingClientRect();
+            return {
+                ink_h: ink.height,
+                input_h: ir.height,
+                ink_mid: (ink.top + ink.bottom) / 2,
+                input_mid: (ir.top + ir.bottom) / 2,
+            };
+        }"""
+    )
+    ratio = m["ink_h"] / m["input_h"]
+    offset = abs(m["ink_mid"] - m["input_mid"])
+    # The Unicode `⚙` glyph's visible cog is about 70-75% of its ink rect — i.e. an ink
+    # rect that matches the input optically reads smaller than the input. To get the gear
+    # to *look* like it matches the search field, the rendered ink rect needs to overshoot
+    # the input by ~15-25%. The acceptance band brackets that, with a little extra
+    # tolerance for cross-browser font metrics (Firefox renders the glyph metrics a couple
+    # of percent above Chromium at the same `font-size`).
+    assert 1.10 <= ratio <= 1.35, (
+        f"gear glyph height {m['ink_h']:.2f}px is {ratio:.2%} of the search input height "
+        f"({m['input_h']:.2f}px); want ~115–125% so the optical cog matches the field"
+    )
+    # Visual centering tolerance: one pixel is below the perceptual threshold for "off
+    # center" at standard zoom.
+    assert offset <= 1.0, (
+        f"gear glyph center is {offset:.2f}px from the search input center; want <1px"
+    )
+
+
+def test_gear_in_header_tools_left_of_search(page):
+    btn = _picker_button(page)
+    btn.wait_for(state="attached", timeout=5000)
+    assert btn.is_visible()
+    # The gear sits inside `.header-tools` and that block is ordered before the search
+    # box by the `order: -1` rule in theme-picker.css. Verify the gear is geometrically
+    # to the left of the search box on a desktop viewport.
+    page.set_viewport_size({"width": 1200, "height": 800})
+    gear_box = btn.bounding_box()
+    search = page.locator("#search-wrapper")
+    if search.count() > 0:
+        search_box = search.first.bounding_box()
+        if search_box is not None and gear_box is not None:
+            assert gear_box["x"] < search_box["x"], (
+                f"gear at x={gear_box['x']}, search at x={search_box['x']}"
+            )
+
+
+def test_popover_open_close_aria(page):
+    btn = _picker_button(page)
+    btn.wait_for(state="attached", timeout=5000)
+    assert btn.get_attribute("aria-expanded") == "false"
+    btn.click()
+    d = _dialog(page)
+    d.wait_for(state="attached", timeout=5000)
+    assert btn.get_attribute("aria-expanded") == "true"
+    assert d.get_attribute("role") == "dialog"
+    assert d.get_attribute("aria-label") is not None
+    # Escape closes and returns focus to the gear.
+    page.keyboard.press("Escape")
+    page.wait_for_function(
+        "document.getElementById('theme-picker-button').getAttribute('aria-expanded') === 'false'"
+    )
+    assert page.evaluate("document.activeElement.id") == "theme-picker-button"
+
+
+def test_focus_trap(page):
+    btn = _picker_button(page)
+    btn.click()
+    dialog = _dialog(page)
+    dialog.wait_for(state="attached", timeout=5000)
+    # The focus trap pushes Tab from the last focusable back to the first; just check that
+    # repeated Tab presses keep focus within the dialog.
+    for _ in range(10):
+        page.keyboard.press("Tab")
+        in_dialog = page.evaluate(
+            "document.getElementById('theme-picker-dialog').contains(document.activeElement)"
+        )
+        assert in_dialog, "focus escaped the dialog"
+
+
+def test_theme_switching_persists(page, server):
+    btn = _picker_button(page)
+    btn.click()
+    _dialog(page).wait_for(state="attached", timeout=5000)
+    # Force single mode (the toggle starts on auto/checked when the picker has both
+    # light and dark themes; unchecking it switches to single).
+    mode = page.locator("#theme-picker-mode")
+    if mode.is_checked():
+        mode.uncheck()
+    # Pick the second option in the single dropdown.
+    single = page.locator("#theme-picker-single")
+    options = single.locator("option").all_text_contents()
+    if len(options) < 2:
+        pytest.skip("not enough themes registered to test switching")
+    chosen = single.locator("option").nth(1).get_attribute("value")
+    single.select_option(value=chosen)
+    # The data attribute should reflect the choice immediately.
+    assert page.evaluate("document.documentElement.getAttribute('data-verso-theme')") == chosen
+    # localStorage persists it.
+    assert page.evaluate("localStorage.getItem('verso-theme-single')") == chosen
+    # Reload: the no-flash script reads localStorage and applies the same theme before paint.
+    page.goto(server + "/")
+    page.wait_for_load_state("domcontentloaded")
+    assert page.evaluate("document.documentElement.getAttribute('data-verso-theme')") == chosen
+
+
+def test_match_system_follows_media(page):
+    btn = _picker_button(page)
+    btn.click()
+    _dialog(page).wait_for(state="attached", timeout=5000)
+    mode = page.locator("#theme-picker-mode")
+    if not mode.is_checked():
+        mode.check()
+    # Emulate dark, then light; the inline script's matchMedia listener should swap themes.
+    page.emulate_media(color_scheme="dark")
+    page.wait_for_timeout(50)
+    dark_id = page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
+    page.emulate_media(color_scheme="light")
+    page.wait_for_timeout(50)
+    light_id = page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
+    assert dark_id != light_id, "auto mode should pick different themes for light vs dark"
+
+
+def test_single_mode_ignores_media(page):
+    btn = _picker_button(page)
+    btn.click()
+    _dialog(page).wait_for(state="attached", timeout=5000)
+    mode = page.locator("#theme-picker-mode")
+    if mode.is_checked():
+        mode.uncheck()
+    # Pick a specific theme.
+    chosen = page.locator("#theme-picker-single option").nth(0).get_attribute("value")
+    page.locator("#theme-picker-single").select_option(value=chosen)
+    # Emulating a media change must not override the chosen theme.
+    page.emulate_media(color_scheme="dark")
+    page.wait_for_timeout(50)
+    assert page.evaluate("document.documentElement.getAttribute('data-verso-theme')") == chosen
+    page.emulate_media(color_scheme="light")
+    page.wait_for_timeout(50)
+    assert page.evaluate("document.documentElement.getAttribute('data-verso-theme')") == chosen
+
+
+def test_auto_commit_applies_dropdown_value(page):
+    """In auto mode, changing the light dropdown while `prefers-color-scheme: light` is active
+    should immediately apply the chosen light theme. The committed `data-verso-theme` must
+    match the dropdown's value, not whatever was previously painted."""
+    page.emulate_media(color_scheme="light")
+    btn = _picker_button(page)
+    btn.click()
+    _dialog(page).wait_for(state="attached", timeout=5000)
+    mode = page.locator("#theme-picker-mode")
+    if not mode.is_checked():
+        mode.check()
+    # Find a light-appearance option that differs from the currently visible theme.
+    light = page.locator("#theme-picker-light")
+    current = page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
+    chosen = None
+    for opt in light.locator("option").all():
+        v = opt.get_attribute("value")
+        if v and v != current:
+            chosen = v
+            break
+    assert chosen is not None, "need at least two light themes to test commit"
+    light.select_option(value=chosen)
+    # The select-change handler fires `commit()`, which must apply the dropdown's value.
+    after = page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
+    assert after == chosen, (
+        f"auto-mode commit should apply dropdown value {chosen!r}, got {after!r}"
+    )
+
+
+def test_switching_themes_has_no_intermediate_state(page):
+    """Selecting a new theme in the dropdown must take `data-verso-theme` directly from the
+    old value to the new value. Any intermediate state — e.g. a hover/focus preview on the
+    *other* mode's dropdown firing during the click, or a transient default — would cause a
+    visible flash to an unrelated theme."""
+    btn = _picker_button(page)
+    btn.click()
+    _dialog(page).wait_for(state="attached", timeout=5000)
+    # Single mode keeps the test deterministic: only one dropdown is visible, so the test
+    # exercises the user path of "open the dialog, pick a different theme, see only the new
+    # theme paint."
+    mode = page.locator("#theme-picker-mode")
+    if mode.is_checked():
+        mode.uncheck()
+    # Install a MutationObserver that logs every value `data-verso-theme` takes from this
+    # point on, so we can assert the sequence after the switch.
+    page.evaluate(
+        """() => {
+            window.__versoThemeStates = [];
+            const obs = new MutationObserver(records => {
+                for (const r of records) {
+                    if (r.attributeName === 'data-verso-theme') {
+                        window.__versoThemeStates.push(
+                            document.documentElement.getAttribute('data-verso-theme')
+                        );
+                    }
+                }
+            });
+            obs.observe(document.documentElement, { attributes: true });
+            window.__versoStopObserver = () => obs.disconnect();
+        }"""
+    )
+    single = page.locator("#theme-picker-single")
+    initial = page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
+    target = None
+    for opt in single.locator("option").all():
+        v = opt.get_attribute("value")
+        if v and v != initial:
+            target = v
+            break
+    assert target is not None, "need at least two themes to test a switch"
+    single.select_option(value=target)
+    # Give the change handler a moment to run any cascaded events (focus/mouseenter previews,
+    # outside-click handler, etc.) so they show up in the recorded sequence.
+    page.wait_for_timeout(100)
+    page.evaluate("window.__versoStopObserver()")
+    states = page.evaluate("window.__versoThemeStates")
+    # The only value `data-verso-theme` should take during the switch is the chosen target.
+    # Any other id (e.g. PageTheme, defaultDark, etc.) means there was an intermediate paint.
+    bad = [s for s in states if s != target]
+    assert not bad, (
+        f"intermediate theme states during single-mode switch from {initial!r} to {target!r}: {bad}"
+    )
+
+
+def test_switching_light_themes_in_auto_has_no_dark_flash(page):
+    """In auto mode under `prefers-color-scheme: light`, switching the *light* dropdown must
+    not paint a dark theme in between. The hover/focus preview handlers were attached to the
+    dark dropdown too, so a stray mouseenter (Playwright's `select_option` walks the cursor
+    over the dialog) could fire `previewTheme(darkSel.value)` mid-switch."""
+    page.emulate_media(color_scheme="light")
+    btn = _picker_button(page)
+    btn.click()
+    _dialog(page).wait_for(state="attached", timeout=5000)
+    mode = page.locator("#theme-picker-mode")
+    if not mode.is_checked():
+        mode.check()
+    light = page.locator("#theme-picker-light")
+    dark = page.locator("#theme-picker-dark")
+    page.evaluate(
+        """() => {
+            window.__versoThemeStates = [];
+            const obs = new MutationObserver(records => {
+                for (const r of records) {
+                    if (r.attributeName === 'data-verso-theme') {
+                        window.__versoThemeStates.push(
+                            document.documentElement.getAttribute('data-verso-theme')
+                        );
+                    }
+                }
+            });
+            obs.observe(document.documentElement, { attributes: true });
+            window.__versoStopObserver = () => obs.disconnect();
+        }"""
+    )
+    initial = page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
+    target = None
+    for opt in light.locator("option").all():
+        v = opt.get_attribute("value")
+        if v and v != initial:
+            target = v
+            break
+    assert target is not None, "need at least two light themes to test a switch"
+    dark_value = dark.locator("option").first.get_attribute("value")
+    # Real-user flow: focus the light dropdown (as a normal user would click on it) and
+    # pick a new option. Hovering the *other* dropdown is also part of the picked-up bug,
+    # but a previous version fired the dark preview because a stray mouseenter on the dark
+    # dropdown landed during Playwright's option-click; both paths should land on the
+    # target theme and only on the target theme.
+    light.focus()
+    light.select_option(value=target)
+    page.wait_for_timeout(100)
+    page.evaluate("window.__versoStopObserver()")
+    states = page.evaluate("window.__versoThemeStates")
+    # The forbidden state is the *dark* one. Re-applying `initial` (the value the page
+    # already had when the test snapshotted it) is invisible to the user; only a flash to
+    # a different appearance, or to a third unrelated theme, is a real flicker.
+    assert dark_value not in states, (
+        f"dark theme {dark_value!r} appeared during a light-to-light switch; full sequence: {states}"
+    )
+    bad = [s for s in states if s not in (target, initial)]
+    assert not bad, (
+        f"unexpected intermediate themes during auto-mode light switch: {bad} (full: {states})"
+    )
+
+
+def test_single_mode_marks_single_default(page):
+    """The single-mode dropdown marks `data.defaultSingle` with " (default)", not the light
+    default unconditionally. Authors who set `defaultSingleAppearance := .dark` should see
+    the dark theme labelled as the default in single mode."""
+    btn = _picker_button(page)
+    btn.click()
+    _dialog(page).wait_for(state="attached", timeout=5000)
+    mode = page.locator("#theme-picker-mode")
+    if mode.is_checked():
+        mode.uncheck()
+    single_default_id = page.evaluate("window.versoThemes.defaultSingle")
+    # The option text for the single-default id is the only one with " (default)" appended.
+    marked = page.evaluate(
+        """(id) => {
+            const opts = Array.from(document.querySelectorAll('#theme-picker-single option'));
+            return opts
+                .filter(o => o.textContent.endsWith(' (default)'))
+                .map(o => o.value);
+        }""",
+        single_default_id,
+    )
+    assert marked == [single_default_id], (
+        f"single-mode (default) should mark only {single_default_id!r}, got {marked!r}"
+    )
+
+
+def test_themes_are_alphabetized(page):
+    """Every dropdown lists its themes in alphabetical order by display name."""
+    btn = _picker_button(page)
+    btn.click()
+    _dialog(page).wait_for(state="attached", timeout=5000)
+    mode = page.locator("#theme-picker-mode")
+    for sel_id, ensure_auto in [
+        ("#theme-picker-single", False),
+        ("#theme-picker-light", True),
+        ("#theme-picker-dark", True),
+    ]:
+        if ensure_auto and not mode.is_checked():
+            mode.check()
+        if not ensure_auto and mode.is_checked():
+            mode.uncheck()
+        texts = page.locator(f"{sel_id} option").all_text_contents()
+        assert texts == sorted(texts), (
+            f"{sel_id} options not alphabetised: {texts}"
+        )
+
+
+def test_match_system_toggle_hides_rows(page):
+    """The 'Theme' (single) row is visible only when Match system is OFF; Light and Dark are
+    visible only when Match system is ON. The `[hidden]` attribute on the row elements must
+    actually hide them — earlier CSS made the `.theme-picker-row { display: flex }` rule
+    win over the default `[hidden] { display: none }`, so the toggle did nothing."""
+    btn = _picker_button(page)
+    btn.click()
+    _dialog(page).wait_for(state="attached", timeout=5000)
+    mode = page.locator("#theme-picker-mode")
+
+    # Auto on -> Light + Dark visible, Theme hidden.
+    if not mode.is_checked():
+        mode.check()
+    assert page.locator("#theme-picker-light").is_visible()
+    assert page.locator("#theme-picker-dark").is_visible()
+    assert not page.locator("#theme-picker-single").is_visible()
+
+    # Auto off -> Theme visible, Light + Dark hidden.
+    mode.uncheck()
+    assert page.locator("#theme-picker-single").is_visible()
+    assert not page.locator("#theme-picker-light").is_visible()
+    assert not page.locator("#theme-picker-dark").is_visible()
+
+
+def test_outside_click_dismisses_popover(page):
+    """Clicking outside the popover closes the dialog and leaves the page on whatever theme
+    is currently committed. (The picker commits on `change` and no longer has a hover/focus
+    preview path, so dismissal is purely a "close the popover" action.)"""
+    btn = _picker_button(page)
+    btn.click()
+    _dialog(page).wait_for(state="attached", timeout=5000)
+    initial = page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
+    page.evaluate("document.body.click()")
+    page.wait_for_function(
+        "document.getElementById('theme-picker-button').getAttribute('aria-expanded') === 'false'"
+    )
+    assert page.evaluate("document.documentElement.getAttribute('data-verso-theme')") == initial
+
+
+def test_gear_toggle_close_dismisses_popover(page):
+    """Clicking the gear a second time closes the dialog without affecting the active theme."""
+    btn = _picker_button(page)
+    btn.click()
+    _dialog(page).wait_for(state="attached", timeout=5000)
+    initial = page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
+    btn.click()
+    page.wait_for_function(
+        "document.getElementById('theme-picker-button').getAttribute('aria-expanded') === 'false'"
+    )
+    assert page.evaluate("document.documentElement.getAttribute('data-verso-theme')") == initial
+
+
+def test_localStorage_disabled_still_loads(page, server):
+    """When localStorage throws, the page still renders and the default theme is applied."""
+    # Stub localStorage *before* navigation so the no-flash script sees the throwing version.
+    page.add_init_script("""
+        Object.defineProperty(window, 'localStorage', {
+            configurable: true,
+            get() { throw new Error('storage disabled'); }
+        });
+    """)
+    page.goto(server + "/")
+    page.wait_for_load_state("domcontentloaded")
+    theme = page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
+    appearance = page.evaluate("document.documentElement.getAttribute('data-verso-appearance')")
+    assert theme is not None and theme != "", "data-verso-theme should be set even without storage"
+    assert appearance in ("light", "dark"), f"unexpected appearance {appearance!r}"
diff --git a/src/tests/TestMain.lean b/src/tests/TestMain.lean
index 0d4f19b75..9557c17e7 100644
--- a/src/tests/TestMain.lean
+++ b/src/tests/TestMain.lean
@@ -177,7 +177,7 @@ def testThemeCss (cfg : Config) : IO Unit := do
   let runTest (input : String) : IO String := do
     let name := input.trimAscii
     if name == "default" then
-      let varsBlock := s!":root \{\n{Theme.CodeTheme.Default.cssVariables}}\n"
+      let varsBlock := s!":root \{\n{Theme.CodeTheme.ink.cssVariables}}\n"
       let combined := varsBlock ++ "\n" ++ Code.highlightingStyle
       -- Trim the trailing blank lines `highlightingStyle` ships with so the golden file
       -- ends with a single newline (otherwise `git diff --check` flags the EOF blank).
diff --git a/src/tests/Tests/ColorAccessibility.lean b/src/tests/Tests/ColorAccessibility.lean
index bb4355042..c0a7fcd95 100644
--- a/src/tests/Tests/ColorAccessibility.lean
+++ b/src/tests/Tests/ColorAccessibility.lean
@@ -84,12 +84,12 @@ def okabeIto : Array (String × Color) := #[
 -- The shipped default theme passes its own accessibility check.
 /-- info: true -/
 #guard_msgs in
-#eval ManualTheme.Default.checkAccessibility.isEmpty
+#eval ManualTheme.ink.checkAccessibility.isEmpty
 
 -- A low-contrast override (gray text on a near-white background) is flagged as a contrast
 -- problem (one per evaluated text pair against the page background).
 private def lowContrastTheme : ManualTheme := {
-  ManualTheme.Default with
+  ManualTheme.ink with
   textColor := color%#bbbbbb,
 }
 
@@ -100,9 +100,9 @@ private def lowContrastTheme : ManualTheme := {
 -- A token palette that collapses under deuteranopia (a red and a green of matched lightness)
 -- is flagged as a CVD problem.
 private def cvdTheme : ManualTheme := {
-  ManualTheme.Default with
-  const := { ManualTheme.Default.const with color := color%#e60000 },
-  keyword := { ManualTheme.Default.keyword with color := color%#00a000 },
+  ManualTheme.ink with
+  const.color := color%#e60000,
+  keyword.color := color%#00a000,
 }
 
 /-- info: true -/
@@ -118,7 +118,7 @@ private def cvdTheme : ManualTheme := {
 -- A theme whose `highlightColor` is too close to `textColor` is flagged: search results render
 -- matched terms with `highlightColor` as their background, so the body text must read on it.
 private def badHighlightTheme : ManualTheme := {
-  ManualTheme.Default with
+  ManualTheme.ink with
   highlightColor := color%#333333,
 }
 
diff --git a/src/tests/Tests/Font.lean b/src/tests/Tests/Font.lean
index 49f88dac3..4673c1068 100644
--- a/src/tests/Tests/Font.lean
+++ b/src/tests/Tests/Font.lean
@@ -82,7 +82,7 @@ define_font_face noFile where
 -- Two distinct families that slug to the same string get distinct asset paths via the typeface
 -- index, so one font's bytes can never overwrite the other.
 def collidingTheme : Verso.Theme.CodeTheme := {
-  Verso.Theme.CodeTheme.Default with
+  Verso.Theme.CodeTheme.ink with
   codeFace := .files "A B" #[katexMono],
   const := { color := color%#000000, weight := .regular, style := .normal,
              face := .files "A/B" #[katexMono] }
diff --git a/src/tests/Tests/HighlightedToTeX.lean b/src/tests/Tests/HighlightedToTeX.lean
index caaf2a817..fdab34cc0 100644
--- a/src/tests/Tests/HighlightedToTeX.lean
+++ b/src/tests/Tests/HighlightedToTeX.lean
@@ -50,7 +50,7 @@ private def hasSub (s sub : String) : Bool := (s.splitOn sub).length > 1
 /-- info: true -/
 #guard_msgs in
 #eval
-  let p := Verso.Theme.CodeTheme.Default.texPreamble
+  let p := Verso.Theme.CodeTheme.ink.texPreamble
   -- Message-text and accent colors are emitted under distinct names: `errorColor` is the
   -- message-body color (#cc0000 by default), `errorIndicatorColor` is the wavy-underline
   -- accent (#ff0000). The keyword macro picks up bold (NFSS `eb`), and the mono font is
@@ -64,7 +64,7 @@ private def hasSub (s sub : String) : Bool := (s.splitOn sub).length > 1
 
 open Verso Verso.Theme in
 private def colorfulTheme : CodeTheme := {
-  CodeTheme.Default with
+  CodeTheme.ink with
   keyword := { color := color%#aa3300, weight := 600, style := .normal, face := .mono },
   const := { color := color%#0044bb, weight := .regular, style := .italic, face := .mono }
 }
diff --git a/src/tests/ThemeTestMain.lean b/src/tests/ThemeTestMain.lean
index 910b01b8a..de0d8ccab 100644
--- a/src/tests/ThemeTestMain.lean
+++ b/src/tests/ThemeTestMain.lean
@@ -52,8 +52,9 @@ def config : Config where
   emitHtmlMulti := .immediately
   htmlDepth := 1
 
+@[manual_theme]
 def testManualTheme : ManualTheme := {
-  ManualTheme.Default with
+  ManualTheme.ink with
   toCodeTheme := testTheme,
   surfaceColor := color%#001a1a,
   headerBackground := color%#001b1b,
@@ -70,9 +71,24 @@ def testManualTheme : ManualTheme := {
   burgerHiddenShadowColor := color%#002626
 }
 
+/--
+Dark counterpart to `testManualTheme`. The validation pass requires a registered dark theme
+for `defaultDarkTheme`, but the test only inspects the unscoped `:root` block (the
+single-mode default, here `.light`), so the same sentinel palette under `.dark` is fine.
+-/
+@[manual_theme]
+def testManualThemeDark : ManualTheme := {
+  testManualTheme with
+  toCodeTheme := { testTheme with name := "ThemeTest Dark", appearance := .dark }
+}
+
 def main : List String → IO UInt32 :=
   manualMain (%doc ThemeTestDoc)
     (config := { config with
-      manualTheme := testManualTheme,
-      strictThemeContrast := false,
-      strictThemeColorblind := false })
+      defaultLightTheme := ``testManualTheme,
+      defaultDarkTheme := ``testManualThemeDark,
+      -- The sentinel palette deliberately violates accessibility; the test exercises rendering,
+      -- not the accessibility checks.
+      strictThemeCoverage := false,
+      strictDefaultThemeAccessibility := false,
+      warnPerThemeAccessibility := false })
diff --git a/src/verso-manual/VersoManual.lean b/src/verso-manual/VersoManual.lean
index 6d1feb477..8b27a1590 100644
--- a/src/verso-manual/VersoManual.lean
+++ b/src/verso-manual/VersoManual.lean
@@ -15,6 +15,8 @@ import Verso.Theme.Code
 import Verso.Theme.Code.Defaults
 import VersoManual.Theme
 import VersoManual.Theme.Defaults
+import VersoManual.Theme.Emit
+import VersoManual.Theme.Assets
 import Verso.Output.Html.KaTeX
 import Verso.Output.Html.ElasticLunr
 import Verso.Doc.Lsp
@@ -235,24 +237,42 @@ structure Config extends HtmlConfig, TeXConfig, OutputConfig where
 
   /--
   Global priorities that control the relative ranking of the semantic (quick-jump) and full-text
-  search result streams, each on a scale from {lit}`0` to {lit}`99`. Defaults are {lit}`50` on
+  search result streams, each on a scale from `0` to `99`. Defaults are `50` on
   both sides.
   -/
   searchPriorities : SearchPriorities := {}
 
   /--
-  When true (the default), contrast problems reported by
-  {Lean.Doc.name}`Verso.Theme.ManualTheme.checkAccessibility` fail the build. When false they are
-  logged as warnings and the build proceeds.
+  When true (the default), it is an error if no theme is accessible. When false the same problems
+  become warnings.
+
+  A theme counts as "accessible" if its `Verso.Theme.ManualTheme.checkAccessibility` returns no
+  issues. In other words:
+   * Every checked color pair meets the WCAG AA contrast threshold
+   * Every pair of token colors stays mutually distinguishable under each of the three dichromacies
+     (`protanopia`, `deuteranopia`, `tritanopia`).
+
+  With a single registered theme, that theme must be accessible. With multiple themes, there must be
+  at least one accessible light theme and one accessible dark theme so a reader on either appearance
+  can pick a usable theme.
   -/
-  strictThemeContrast : Bool := true
+  strictThemeCoverage : Bool := true
 
   /--
-  When true (the default), color-vision-deficiency problems reported by
-  {Lean.Doc.name}`Verso.Theme.ManualTheme.checkAccessibility` fail the build. When false they are
-  logged as warnings and the build proceeds.
+  When `true` (the default), the build errors if the configured `defaultLightTheme` or
+  `defaultDarkTheme` has any accessibility issues. When false the same problems become build-log
+  warnings and the build proceeds.
   -/
-  strictThemeColorblind : Bool := true
+  strictDefaultThemeAccessibility : Bool := true
+
+  /--
+  When `true` (the default), every registered theme that has accessibility issues emits a build-log
+  warning that names the theme and the specific issues. Setting this to `false` silences these
+  per-theme warnings — useful when shipping a documented trade-off (for example the canonical
+  Solarized palette, whose token colors are below WCAG AA's 4.5:1 contrast threshold for normal text
+  by design).
+  -/
+  warnPerThemeAccessibility : Bool := true
 deriving ToJson, FromJson
 
 structure RenderConfig extends Config where
@@ -261,12 +281,41 @@ structure RenderConfig extends Config where
   -/
   linkTargets : TraverseState → Multi.AllRemotes → LinkTargets Manual.TraverseContext := (·.localTargets ++ ·.remoteTargets)
   /--
-  The active {Lean.Doc.name}`Verso.Theme.ManualTheme`. Its CSS-variable block (the
-  inherited {Lean.Doc.name}`Verso.Theme.CodeTheme` variables plus the manual-chrome
-  additions) is written to {lit}`verso-themes.css` so the page-level highlighting rules and
-  chrome read the chosen values.
+  The subset of registered manual themes that should be available in the picker. When
+  `none` (the default), every registered theme is available.
+  -/
+  availableThemes : Option (Array Lean.Name) := none
+  /--
+  The default light-appearance theme. Its registration name must be a registered
+  `Verso.Theme.ManualTheme` whose appearance is `.light`.
+  -/
+  defaultLightTheme : Lean.Name := ``Verso.Theme.ManualTheme.ink
+  /--
+  The default dark-appearance theme. Its registration name must be a registered
+  `Verso.Theme.ManualTheme` whose appearance is `.dark`.
+  -/
+  defaultDarkTheme : Lean.Name := ``Verso.Theme.ManualTheme.argent
+  /--
+  The default for readers who do not follow the system appearance (the "single" picker mode):
+  choose `.light` so single-mode falls back to
+  `defaultLightTheme`,
+  or `.dark` so it falls back to
+  `defaultDarkTheme`.
+
+  Auto-mode behavior is unchanged either way: a reader who keeps "Match system" on still gets
+  the light or dark default depending on their OS preference. This setting only governs the
+  single-mode fallback (and what the picker marks as ` (default)` in the single-mode
+  dropdown).
+  -/
+  defaultSingleAppearance : Verso.Theme.Appearance := .light
+  /--
+  The materialized set of themes available to the picker. `manualMain` populates
+  this from `manualThemes%` filtered by
+  `availableThemes`; the
+  emit functions read it. Stored as an array so it can be threaded through the read-only
+  configuration without an extra reader layer.
   -/
-  manualTheme : Verso.Theme.ManualTheme := Verso.Theme.ManualTheme.Default
+  themeRegistry : Array (Lean.Name × Verso.Theme.ManualTheme) := #[]
 
 namespace Config
 
@@ -396,6 +445,73 @@ def DividedDoc.ofPart (part : Part Manual) : DividedDoc :=
 where
   isUnnumbered (p : Part Manual) : Bool := p.metadata.map (·.number) |>.isEqSome false
 
+/--
+Resolves the single-mode default theme name from the configured
+`Verso.Genre.Manual.RenderConfig.defaultSingleAppearance` — either
+`Verso.Genre.Manual.RenderConfig.defaultLightTheme` or
+`Verso.Genre.Manual.RenderConfig.defaultDarkTheme`.
+-/
+def defaultSingleName (config : RenderConfig) : Lean.Name :=
+  match config.defaultSingleAppearance with
+  | .light => config.defaultLightTheme
+  | .dark => config.defaultDarkTheme
+
+/--
+The single-default `Verso.Theme.ManualTheme` resolved from `themeRegistry`. This is the
+theme that drives `verso-themes.css`'s unscoped `:root` block — what the server-rendered
+HTML paints on first visit (before the no-flash script attaches a `data-verso-theme`) — and
+the TeX code styling.
+
+Falls back to a bare default `ManualTheme.ink` if neither the resolved single-default name
+nor either configured default appears in the registry (a defensive case; the validation pass
+in `manualMain` rejects unregistered defaults before this is called).
+-/
+def singleDefaultTheme (config : RenderConfig) : Verso.Theme.ManualTheme :=
+  let find (n : Lean.Name) : Option Verso.Theme.ManualTheme :=
+    config.themeRegistry.findSome? (fun (m, t) => if m == n then some t else none)
+  (find (defaultSingleName config) <|> find config.defaultLightTheme
+    <|> find config.defaultDarkTheme).getD Verso.Theme.ManualTheme.ink
+
+open IO.FS in
+/--
+Writes every theme-related asset for an output root: the multi-theme `verso-themes.css`, the
+picker `.js`/`.css`, the `window.versoThemes` data file, every theme's font bytes and bundled
+assets. Content-addressed font filenames in the theme registry ensure that two themes sharing the
+same font end up with one byte payload on disk.
+-/
+def writeThemeAssets (dir : System.FilePath) (config : RenderConfig) : IO Unit := do
+  ensureDir (dir / "-verso-data")
+  let themes := config.themeRegistry
+  let single := singleDefaultTheme config
+  -- verso-themes.css
+  withFile (dir / "verso-themes.css") .write fun h => do
+    h.putStrLn (Verso.Theme.«verso-themes.css» single themes
+      config.defaultLightTheme config.defaultDarkTheme)
+  -- Font bytes, deduplicated by output path: a theme's @font-face rules embed the per-theme
+  -- asset-root path, so writing one path and skipping a structurally-identical-bytes path under
+  -- a different theme root would leave that rule pointing at a missing file.
+  let mut writtenPaths : Std.HashSet String := {}
+  for (n, t) in themes do
+    let assetRoot := s!"-verso-data/themes/{n.toString}"
+    for (path, bytes, _, _) in t.fontAssets assetRoot do
+      if writtenPaths.contains path then continue
+      writtenPaths := writtenPaths.insert path
+      let abs := dir.join path
+      if let some p := abs.parent then ensureDir p
+      writeBinFile abs bytes
+  -- Theme-bundled assets (images, etc.).
+  for (n, t) in themes do
+    for a in t.assets do
+      let path := dir / "-verso-data" / "themes" / n.toString / a.path
+      if let some p := path.parent then ensureDir p
+      writeBinFile path a.contents
+  -- Picker assets + data file.
+  writeFile (dir / "-verso-data" / "theme-picker.js") Manual.Theme.«theme-picker.js»
+  writeFile (dir / "-verso-data" / "theme-picker.css") Manual.Theme.«theme-picker.css»
+  writeFile (dir / "-verso-data" / "verso-themes.js")
+    (Verso.Theme.windowVersoThemesJs themes config.defaultLightTheme config.defaultDarkTheme
+      (defaultSingleName config) Manual.Theme.codeSampleHtml)
+
 open IO.FS in
 def emitTeX (config : RenderConfig) (text : Part Manual) : EmitM Unit := do
   let (text, state) ← traverse text config.toConfig
@@ -420,7 +536,7 @@ def emitTeX (config : RenderConfig) (text : Part Manual) : EmitM Unit := do
   withFile (dir.join "main.tex") .write fun h => do
     if config.verbose then
       IO.println s!"Saving {dir.join "main.tex"}"
-    h.putStrLn (preamble text.titleString authors date packages.toList preambleItems.toList config.manualTheme.toCodeTheme)
+    h.putStrLn (preamble text.titleString authors date packages.toList preambleItems.toList (singleDefaultTheme config).toCodeTheme)
     -- \frontmatter is inserted by our hardcoded preamble before the ToC, so it doesn't get inserted
     -- here. If there's any text at the start of the front matter, then we need to clear it to a new
     -- recto page after the ToC
@@ -507,7 +623,8 @@ def page (toc : List Html.Toc)
     (state : TraverseState) (config : Config)
     (localItems : Array Html)
     (showNavButtons : Bool := true) (extraJs : List JS := [])
-    (extraHead : Html := .empty) : Html :=
+    (extraHead : Html := .empty)
+    (themeInitScript : String := "") (showThemePicker : Bool := false) : Html :=
   let toc := {
     title := htmlBookTitle, path := #[], id := "" , sectionNum := some #[], children := toc
   }
@@ -529,6 +646,7 @@ def page (toc : List Html.Toc)
     state.extraCss (state.extraJs.insertMany extraJs)
     (showNavButtons := showNavButtons)
     (logo := config.logo)
+    (logoDark := config.logoDark)
     (logoLink := config.logoLink)
     (repoLink := config.sourceLink)
     (issueLink := config.issueLink)
@@ -537,6 +655,8 @@ def page (toc : List Html.Toc)
     (extraJsFiles := featureJsFiles ++ extraJsFiles)
     (extraHead := config.extraHead |>.push extraHead)
     (extraContents := config.extraContents)
+    (themeInitScript := themeInitScript)
+    (showThemePicker := showThemePicker)
 
 def relativizeLinks (html : Html) : Html :=
     -- Make all absolute URLS be relative to the site root, because that'll make them `<base>`-relative
@@ -785,24 +905,7 @@ where
       emitSearchResultsHtml toc dir titleToShow state config.toConfig
     IO.FS.withFile (dir.join "book.css") .write fun h => do
       h.putStrLn Html.Css.pageStyle
-    IO.FS.withFile (dir.join "verso-themes.css") .write fun h => do
-      let assetRoot := s!"-verso-data/themes/{config.manualTheme.name}"
-      let faceRules := config.manualTheme.fontFaceRules assetRoot
-      unless faceRules.isEmpty do
-        h.putStrLn faceRules
-      h.putStrLn s!":root \{\n{config.manualTheme.cssVariables}}"
-      let extra := config.manualTheme.extraCss assetRoot
-      unless extra.isEmpty do
-        h.putStrLn ""
-        h.putStrLn extra
-    for (path, bytes, _, _) in config.manualTheme.fontAssets s!"-verso-data/themes/{config.manualTheme.name}" do
-      let abs := dir.join path
-      if let some p := abs.parent then ensureDir p
-      IO.FS.writeBinFile abs bytes
-    for a in config.manualTheme.assets do
-      let path := dir.join "-verso-data" |>.join "themes" |>.join config.manualTheme.name |>.join a.path
-      if let some p := path.parent then ensureDir p
-      IO.FS.writeBinFile path a.contents
+    writeThemeAssets dir config
     for (src, dest) in config.extraFiles do
       copyRecursively src (dir.join dest)
     for (src, dest) in config.extraFilesHtml do
@@ -819,8 +922,19 @@ where
       if config.verbose then
         IO.println s!"Saving {dir.join "index.html"}"
       h.putStrLn Html.doctype
+      -- Offer the picker only when the reader has a real choice. A registry with one entry
+      -- (or none) means the unscoped `:root` block already paints the only available theme.
+      let showThemePicker := config.themeRegistry.size > 1
+      let themeInitScript :=
+        if showThemePicker then
+          Verso.Theme.themeInitScript config.themeRegistry
+            config.defaultLightTheme config.defaultDarkTheme (defaultSingleName config)
+        else ""
       h.putStrLn <| Html.asString <| relativizeLinks <|
-        page toc ctxt.path text.titleString titleToShow pageContent state config.toConfig thisPageToc (showNavButtons := false)
+        page toc ctxt.path text.titleString titleToShow pageContent state config.toConfig thisPageToc
+          (showNavButtons := false)
+          (themeInitScript := themeInitScript)
+          (showThemePicker := showThemePicker)
 
 
 /--
@@ -869,24 +983,7 @@ where
       else titleHtml
     IO.FS.withFile (root / "book.css") .write fun h => do
       h.putStrLn Html.Css.pageStyle
-    IO.FS.withFile (root / "verso-themes.css") .write fun h => do
-      let assetRoot := s!"-verso-data/themes/{config.manualTheme.name}"
-      let faceRules := config.manualTheme.fontFaceRules assetRoot
-      unless faceRules.isEmpty do
-        h.putStrLn faceRules
-      h.putStrLn s!":root \{\n{config.manualTheme.cssVariables}}"
-      let extra := config.manualTheme.extraCss assetRoot
-      unless extra.isEmpty do
-        h.putStrLn ""
-        h.putStrLn extra
-    for (path, bytes, _, _) in config.manualTheme.fontAssets s!"-verso-data/themes/{config.manualTheme.name}" do
-      let abs := root.join path
-      if let some p := abs.parent then ensureDir p
-      IO.FS.writeBinFile abs bytes
-    for a in config.manualTheme.assets do
-      let path := root.join "-verso-data" |>.join "themes" |>.join config.manualTheme.name |>.join a.path
-      if let some p := path.parent then ensureDir p
-      IO.FS.writeBinFile path a.contents
+    writeThemeAssets root config
     for (src, dest) in config.extraFiles do
       copyRecursively src (root.join dest)
     for (src, dest) in config.extraFilesHtml do
@@ -955,8 +1052,18 @@ where
       if config.verbose then
         IO.println s!"Saving {dir.join "index.html"}"
       h.putStrLn Html.doctype
+      -- Offer the picker only when the reader has a real choice. A registry with one entry
+      -- (or none) means the unscoped `:root` block already paints the only available theme.
+      let showThemePicker := config.themeRegistry.size > 1
+      let themeInitScript :=
+        if showThemePicker then
+          Verso.Theme.themeInitScript config.themeRegistry
+            config.defaultLightTheme config.defaultDarkTheme (defaultSingleName config)
+        else ""
       h.putStrLn <| Html.asString <| relativizeLinks <|
         page bookContents ctxt.path part.titleString bookTitle pageContent state config.toConfig thisPageToc
+          (themeInitScript := themeInitScript)
+          (showThemePicker := showThemePicker)
     if depth > 0 ∧ part.htmlSplit != .never then
       for p in part.subParts do
         let nextFile := p.metadata.bind (·.file) |>.getD (p.titleString.sluggify.toString)
@@ -1007,8 +1114,7 @@ def manualMain (text : Part Manual)
     (config : RenderConfig := {})
     (extraSteps : List ExtraStep := []) : IO UInt32 :=
   let _ := codeThemes
-  let _ := manualThemes
-  ReaderT.run go extensionImpls
+  go extensionImpls manualThemes
 
 where
 
@@ -1060,24 +1166,97 @@ where
     if base.endsWith "/" then base else base ++ "/"
 
   /--
-  Runs the theme's accessibility check and routes each {name (full := Verso.Color.Issue)}`Issue`
-  through {name}`MonadBuildLog`: contrast issues use {name (full := Verso.Genre.Manual.RenderConfig.strictThemeContrast)}`strictThemeContrast`
-  and colorblindness issues use {name (full := Verso.Genre.Manual.RenderConfig.strictThemeColorblind)}`strictThemeColorblind`
-  to decide error vs. warning. The build proceeds either way; logged errors set the exit code.
+  Runs the theme set's accessibility checks at three tiers:
+
+  - **Coverage** (gated by
+    `strictThemeCoverage`):
+    the build must offer a usable theme. With a single registered theme it must be accessible;
+    with multiple themes at least one accessible light *and* one accessible dark must exist.
+
+  - **Default theme** (gated by
+    `strictDefaultThemeAccessibility`):
+    the configured `defaultLightTheme`
+    and `defaultDarkTheme`
+    must themselves be accessible.
+
+  - **Per-theme advisory** (gated by
+    `warnPerThemeAccessibility`):
+    every registered theme with any accessibility issues emits a build-log warning naming the
+    theme and the specific issues.
+
+  A theme counts as "accessible" iff its
+  `Verso.Theme.ManualTheme.checkAccessibility` returns no issues.
   -/
   runThemeAccessibilityCheck (cfg : RenderConfig) : ReaderT ExtensionImpls (BuildLogT IO) Unit := do
-    for issue in cfg.manualTheme.checkAccessibility do
-      let strict := match issue.kind with
-        | .contrast => cfg.strictThemeContrast
-        | .colorblind => cfg.strictThemeColorblind
-      let colors := issue.offending.toList.map Verso.Theme.Color.css |> ", ".intercalate
-      let suffix := if colors.isEmpty then "" else s!" ({colors})"
-      let msg := s!"theme '{cfg.manualTheme.name}': {issue.message}{suffix}"
-      if strict then Verso.reportError msg else Verso.reportWarning msg
-
-  go (extensionImpls : ExtensionImpls) : IO UInt32 := do
-    let cfg ← opts config options
+    let issuesOf (t : Verso.Theme.ManualTheme) := t.checkAccessibility
+    let isAccessible (t : Verso.Theme.ManualTheme) : Bool := (issuesOf t).isEmpty
+    -- Per-theme advisory.
+    if cfg.warnPerThemeAccessibility then
+      for (n, t) in cfg.themeRegistry do
+        for issue in issuesOf t do
+          let colors := issue.offending.toList.map Verso.Theme.Color.css |> ", ".intercalate
+          let suffix := if colors.isEmpty then "" else s!" ({colors})"
+          Verso.reportWarning s!"theme '{n.toString}' ({t.name}): {issue.message}{suffix}"
+    -- Coverage.
+    let routeCoverage (msg : String) : ReaderT ExtensionImpls (BuildLogT IO) Unit :=
+      if cfg.strictThemeCoverage then Verso.reportError msg else Verso.reportWarning msg
+    let accessible := cfg.themeRegistry.filter (fun (_, t) => isAccessible t)
+    if accessible.isEmpty then
+      routeCoverage "no registered theme is accessible; readers cannot pick a usable theme"
+    else if cfg.themeRegistry.size > 1 then
+      let anyLight := accessible.any (fun (_, t) => t.appearance == Verso.Theme.Appearance.light)
+      let anyDark := accessible.any (fun (_, t) => t.appearance == Verso.Theme.Appearance.dark)
+      unless anyLight do
+        routeCoverage "no registered light theme is accessible; readers on a light system cannot pick a usable theme"
+      unless anyDark do
+        routeCoverage "no registered dark theme is accessible; readers on a dark system cannot pick a usable theme"
+    -- Default theme accessibility.
+    let routeDefault (msg : String) : ReaderT ExtensionImpls (BuildLogT IO) Unit :=
+      if cfg.strictDefaultThemeAccessibility then Verso.reportError msg else Verso.reportWarning msg
+    let checkDefault (slot : String) (name : Lean.Name) :
+        ReaderT ExtensionImpls (BuildLogT IO) Unit := do
+      match cfg.themeRegistry.findSome? (fun (n, t) => if n == name then some t else none) with
+      | none => pure ()  -- already reported by validate
+      | some t =>
+        let issues := issuesOf t
+        unless issues.isEmpty do
+          routeDefault s!"{slot} '{name.toString}' ({t.name}) has {issues.size} accessibility issue{if issues.size == 1 then "" else "s"}"
+    checkDefault "defaultLightTheme" cfg.defaultLightTheme
+    checkDefault "defaultDarkTheme" cfg.defaultDarkTheme
+
+  /--
+  Builds the materialized theme registry for the build from the registered
+  `Verso.Theme.ManualTheme` table, filters it by the configured
+  `availableThemes`,
+  routes every `Verso.Theme.ManualThemeTable.ValidationError` through
+  `MonadBuildLog` as an error, and returns the populated config.
+  -/
+  resolveThemeRegistry (cfg : RenderConfig)
+      (table : Verso.Theme.ManualThemeTable) :
+      ReaderT ExtensionImpls (BuildLogT IO) RenderConfig := do
+    for e in table.validate cfg.defaultLightTheme cfg.defaultDarkTheme cfg.availableThemes do
+      Verso.reportError e.format
+    -- `availableThemes` semantics:
+    --   `none`        → every registered theme is available
+    --   `some [..xs]` → exactly those themes, with `defaultLightTheme` and
+    --                   `defaultDarkTheme` implicitly added if missing so the picker always
+    --                   contains the resolved default for each appearance.
+    -- The result always contains at least `defaultLightTheme` and `defaultDarkTheme` if those
+    -- are registered, so `singleDefaultTheme` can always resolve.
+    let expanded :=
+      match cfg.availableThemes with
+      | none => table.themes.foldl (init := #[]) (fun acc n t => acc.push (n, t))
+      | some xs =>
+        let withDefaults := xs
+          |>.append (if xs.contains cfg.defaultLightTheme then #[] else #[cfg.defaultLightTheme])
+          |>.append (if xs.contains cfg.defaultDarkTheme then #[] else #[cfg.defaultDarkTheme])
+        withDefaults.filterMap (fun n => (table.find? n).map (fun t => (n, t)))
+    return { cfg with themeRegistry := expanded }
+
+  go (extensionImpls : ExtensionImpls) (manualThemes : Verso.Theme.ManualThemeTable) : IO UInt32 := do
+    let baseCfg ← opts config options
     runWithLogger <| flip ReaderT.run extensionImpls do
+      let cfg ← resolveThemeRegistry baseCfg manualThemes
       runThemeAccessibilityCheck cfg
       if cfg.emitTeX then
         if cfg.verbose then
diff --git a/src/verso-manual/VersoManual/Html.lean b/src/verso-manual/VersoManual/Html.lean
index ff5c37cb3..3b8e10ffa 100644
--- a/src/verso-manual/VersoManual/Html.lean
+++ b/src/verso-manual/VersoManual/Html.lean
@@ -418,11 +418,14 @@ public def page
     (extraContents : Array Html := #[])
     (showNavButtons : Bool := true)
     (logo : Option String := none)
+    (logoDark : Option String := none)
     (logoLink : Option String := none)
     (repoLink : Option String := none)
     (issueLink : Option String := none)
     (extraStylesheets : List String := [])
-    (extraJsFiles : Array (String × Bool) := #[]) : Html :=
+    (extraJsFiles : Array (String × Bool) := #[])
+    (themeInitScript : String := "")
+    (showThemePicker : Bool := false) : Html :=
   let relativeRoot := String.join <| "./" :: path.toList.map (fun _ => "../")
   let defer := #[("defer", "defer")]
   {{
@@ -435,8 +438,19 @@ public def page
         <meta charset="utf-8"/>
         <meta name="viewport" content="height=device-height, width=device-width, initial-scale=1, minimum-scale=1, maximum-scale=1"/>
         <title>{{textTitle}}</title>
+        {{if themeInitScript.isEmpty then .empty else
+            {{<script>{{Html.text false themeInitScript}}</script>}} }}
         <link rel="stylesheet" href="book.css" />
         <link rel="stylesheet" href="verso-themes.css" />
+        {{if showThemePicker then
+            {{<link rel="stylesheet" href="-verso-data/theme-picker.css" />}}
+          else .empty }}
+        {{if showThemePicker then
+            {{<script src="-verso-data/verso-themes.js"></script>}}
+          else .empty }}
+        {{if showThemePicker then
+            {{<script src="-verso-data/theme-picker.js" defer="defer"></script>}}
+          else .empty }}
         <script src="https://cdn.jsdelivr.net/npm/marked@11.1.1/marked.min.js" integrity="sha384-zbcZAIxlvJtNE3Dp5nxLXdXtXyxwOdnILY1TDPVmKFhl4r4nSUG1r8bcFXGVa4Te" crossorigin="anonymous"></script>
         {{ searchAssetTags }}
         {{extraJsFiles.map fun f => ({{<script src=s!"{f.1}" {{if f.2 then defer else #[]}}></script>}})}}
@@ -449,16 +463,30 @@ public def page
         <header>
           <div class="header-logo-wrapper">
             {{if let some url := logo then
-                let logoHtml := {{<img src={{url}}/>}}
                 let logoDest :=
                   if let some root := logoLink then root
                   else "/"
-                {{<a href={{logoDest}} id="logo">{{logoHtml}}</a>}}
+                let lightImg :=
+                  if logoDark.isSome then
+                    {{<img class="logo-light" src={{url}}/>}}
+                  else
+                    {{<img src={{url}}/>}}
+                let darkImg :=
+                  if let some d := logoDark then {{<img class="logo-dark" src={{d}}/>}}
+                  else .empty
+                {{<a href={{logoDest}} id="logo">{{lightImg}}{{darkImg}}</a>}}
               else .empty }}
           </div>
           <div class="header-title-wrapper">
             <a href={{if let some dest := logoLink then dest else "/"}} class="header-title"><h1>{{bookTitle}}</h1></a>
           </div>
+          {{if showThemePicker then
+              {{<div class="header-tools">
+                  <button id="theme-picker-button" type="button" aria-haspopup="dialog" aria-expanded="false" aria-controls="theme-picker-dialog" aria-label="Theme settings" title="Theme settings">
+                    <span class="theme-picker-gear" aria-hidden="true">"⚙"</span>
+                  </button>
+                </div>}}
+            else .empty }}
         </header>
         <label for="toggle-toc" id="toggle-toc-click">
           <span class="line line1"/>
diff --git a/src/verso-manual/VersoManual/Html/Config.lean b/src/verso-manual/VersoManual/Html/Config.lean
index 128d83014..e2a62dadc 100644
--- a/src/verso-manual/VersoManual/Html/Config.lean
+++ b/src/verso-manual/VersoManual/Html/Config.lean
@@ -25,6 +25,12 @@ public structure HtmlConfig extends HtmlAssets where
   extraContents : Array Output.Html := #[]
   /-- The URL from which to draw the logo to show, if any -/
   logo : Option String := none
+  /--
+  The URL from which to draw the dark-appearance logo, if any. When set, the page renders both
+  the {lit}`logo` and {lit}`logoDark` images and CSS toggles them via {lit}`data-verso-appearance`.
+  When unset, {lit}`logo` is used in both appearances.
+  -/
+  logoDark : Option String := none
   /-- The URL that the logo should link to, if any (default is site root) -/
   logoLink : Option String := none
   /-- URL for source link -/
@@ -47,7 +53,7 @@ public structure HtmlConfig extends HtmlAssets where
 
 public instance : ToJson HtmlConfig where
   toJson := private fun
-    | { toHtmlAssets, htmlDepth, extraFilesHtml, extraHead, extraContents, logo, logoLink, sourceLink, issueLink, sectionTocDepth, rootTocDepth } =>
+    | { toHtmlAssets, htmlDepth, extraFilesHtml, extraHead, extraContents, logo, logoDark, logoLink, sourceLink, issueLink, sectionTocDepth, rootTocDepth } =>
       json%{
         "toHtmlAssets": $toHtmlAssets,
         "htmlDepth": $htmlDepth,
@@ -55,6 +61,7 @@ public instance : ToJson HtmlConfig where
         "extraHead": $extraHead,
         "extraContents": $extraContents,
         "logo": $logo,
+        "logoDark": $logoDark,
         "logoLink": $logoLink,
         "sourceLink": $sourceLink,
         "issueLink": $issueLink,
@@ -70,9 +77,10 @@ public instance : FromJson HtmlConfig where
     let extraHead <- v.getObjValAs? _ "extraHead"
     let extraContents <- v.getObjValAs? _ "extraContents"
     let logo <- v.getObjValAs? _ "logo"
+    let logoDark <- v.getObjValAs? _ "logoDark"
     let logoLink <- v.getObjValAs? _ "logoLink"
     let sourceLink <- v.getObjValAs? _ "sourceLink"
     let issueLink <- v.getObjValAs? _ "issueLink"
     let sectionTocDepth <- v.getObjValAs? _ "sectionTocDepth"
     let rootTocDepth <- v.getObjValAs? _ "rootTocDepth"
-    return { toHtmlAssets, htmlDepth, extraFilesHtml, extraHead, extraContents, logo, logoLink, sourceLink, issueLink, sectionTocDepth, rootTocDepth }
+    return { toHtmlAssets, htmlDepth, extraFilesHtml, extraHead, extraContents, logo, logoDark, logoLink, sourceLink, issueLink, sectionTocDepth, rootTocDepth }
diff --git a/src/verso-manual/VersoManual/Html/Style.lean b/src/verso-manual/VersoManual/Html/Style.lean
index 172f8434f..b52477c38 100644
--- a/src/verso-manual/VersoManual/Html/Style.lean
+++ b/src/verso-manual/VersoManual/Html/Style.lean
@@ -82,6 +82,12 @@ body {
     color: var(--verso-text-color);
 }
 
+/* Light/dark logo switching: when both images are rendered, show one based on the appearance
+   the no-flash script set on `<html>`. When only a light logo is rendered, no rule fires and it
+   is visible in both appearances by default. */
+:root[data-verso-appearance="dark"] #logo .logo-light { display: none; }
+:root[data-verso-appearance="light"] #logo .logo-dark { display: none; }
+
 /******** Theme ********/
 
 h1, h2, h3, h4, h5, h6 {
@@ -433,12 +439,18 @@ main [id] {
     max-width: var(--verso-content-max-width);
 }
 
-.prev-next-buttons > * {
+.prev-next-buttons > *,
+.prev-next-buttons > *:visited {
     display: flex;
     flex: 1;
     justify-content: center;
     align-items: center;
-    color: var(--verso-link-color);
+    /* Section nav is a link in form but reads as body navigation, not a content CTA, so it
+       tracks the body text color rather than `--verso-link-color`. Both `:link` and `:visited`
+       are pinned to text color, otherwise the `main a:visited` rule below (specificity 0,1,2
+       beats `.prev-next-buttons > *` at 0,1,0) recolors visited prev/next links to the
+       visited-link colour. */
+    color: var(--verso-text-color);
     text-decoration: none;
 }
 
diff --git a/src/verso-manual/VersoManual/Theme.lean b/src/verso-manual/VersoManual/Theme.lean
index 4d4c0d992..68764f361 100644
--- a/src/verso-manual/VersoManual/Theme.lean
+++ b/src/verso-manual/VersoManual/Theme.lean
@@ -244,3 +244,85 @@ public def checkAccessibility (theme : ManualTheme) : Array Color.Issue := Id.ru
   return issues
 
 end ManualTheme
+
+/-! # Theme-set validation -/
+
+namespace ManualThemeTable
+
+/--
+A theme's registration name is used as an identifier in {lit}`data-verso-theme`,
+{lit}`localStorage`, and asset paths. Each character must satisfy {lit}`[A-Za-z0-9._-]`;
+consecutive dots ({lit}`..`) are rejected to prevent path traversal in the asset directory; and
+the slug must contain at least one letter so a bare {lit}`.` is rejected.
+-/
+public def safeNameString (s : String) : Bool := Id.run do
+  if s.isEmpty then return false
+  if (s.splitOn "..").length > 1 then return false
+  let mut hasLetter := false
+  for c in s.toList do
+    if c.isAlpha then hasLetter := true
+    let ok := c.isAlphanum || c == '.' || c == '-' || c == '_'
+    unless ok do return false
+  return hasLetter
+
+/--
+Reasons a theme configuration can be rejected. Each carries enough detail to point an author at
+the specific theme or default slot that needs attention.
+-/
+public inductive ValidationError where
+  /-- The registration `Name.toString` contains characters outside `[A-Za-z0-9._-]`, contains
+  `..`, or has no letter. -/
+  | unsafeName (name : Lean.Name)
+  /-- `availableThemes` named a theme that is not registered with `@[manual_theme]`. -/
+  | unknownAvailable (name : Lean.Name)
+  /-- `defaultLightTheme` is not a registered manual theme. -/
+  | unknownDefaultLight (name : Lean.Name)
+  /-- `defaultDarkTheme` is not a registered manual theme. -/
+  | unknownDefaultDark (name : Lean.Name)
+  /-- `defaultLightTheme` names a theme whose appearance is not `.light`. -/
+  | defaultLightWrongAppearance (name : Lean.Name)
+  /-- `defaultDarkTheme` names a theme whose appearance is not `.dark`. -/
+  | defaultDarkWrongAppearance (name : Lean.Name)
+deriving Inhabited, Repr
+
+/-- Renders a {Lean.Doc.name}`Verso.Theme.ManualThemeTable.ValidationError` as a build-log message. -/
+public def ValidationError.format : ValidationError → String
+  | .unsafeName n =>
+    s!"theme registration name '{n}' is not safe for a URL path segment; only [A-Za-z0-9._-] are allowed, '..' is rejected, and at least one letter is required"
+  | .unknownAvailable n =>
+    s!"availableThemes lists '{n}', which is not a registered @[manual_theme]"
+  | .unknownDefaultLight n =>
+    s!"defaultLightTheme = '{n}' is not a registered @[manual_theme]"
+  | .unknownDefaultDark n =>
+    s!"defaultDarkTheme = '{n}' is not a registered @[manual_theme]"
+  | .defaultLightWrongAppearance n =>
+    s!"defaultLightTheme = '{n}' is registered but its appearance is not .light"
+  | .defaultDarkWrongAppearance n =>
+    s!"defaultDarkTheme = '{n}' is registered but its appearance is not .dark"
+
+/--
+Validates the configured theme set against the registered theme table. Returns the list of
+problems found (empty iff every check passes); the caller routes them through the build log.
+-/
+public def validate (table : ManualThemeTable)
+    (defaultLight defaultDark : Lean.Name)
+    (available : Option (Array Lean.Name)) : Array ValidationError := Id.run do
+  let mut errs := #[]
+  for (n, _) in table.themes.toList do
+    unless safeNameString n.toString do
+      errs := errs.push (.unsafeName n)
+  if let some xs := available then
+    for n in xs do
+      unless (table.find? n).isSome do
+        errs := errs.push (.unknownAvailable n)
+  match table.find? defaultLight with
+  | none => errs := errs.push (.unknownDefaultLight defaultLight)
+  | some t => unless t.appearance == .light do
+      errs := errs.push (.defaultLightWrongAppearance defaultLight)
+  match table.find? defaultDark with
+  | none => errs := errs.push (.unknownDefaultDark defaultDark)
+  | some t => unless t.appearance == .dark do
+      errs := errs.push (.defaultDarkWrongAppearance defaultDark)
+  return errs
+
+end ManualThemeTable
diff --git a/src/verso-manual/VersoManual/Theme/Assets.lean b/src/verso-manual/VersoManual/Theme/Assets.lean
new file mode 100644
index 000000000..cf7fc7945
--- /dev/null
+++ b/src/verso-manual/VersoManual/Theme/Assets.lean
@@ -0,0 +1,35 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+meta import Init.System.FilePath
+
+namespace Verso.Genre.Manual.Theme
+
+/-- The picker JavaScript: builds the dialog opened by `#theme-picker-button`. -/
+public def «theme-picker.js» : String := include_str "../../../../static-web/theme/theme-picker.js"
+
+/-- The picker styles. -/
+public def «theme-picker.css» : String := include_str "../../../../static-web/theme/theme-picker.css"
+
+/--
+A small fixed code sample the picker drops into the preview pane so the user can see what each
+candidate theme will look like. Rendered as `def greet name := s!"Hello, {name}"` using the
+same `.hl.lean` token classes the real highlighter emits, so token colors, weights, and the
+font family resolve from the candidate theme.
+-/
+public def codeSampleHtml : String :=
+  "<code class=\"hl lean block\">" ++
+  "<span class=\"keyword\">def</span> " ++
+  "<span class=\"const\">greet</span> " ++
+  "<span class=\"var\">name</span> " ++
+  "<span class=\"unknown\">:=</span> " ++
+  "<span class=\"keyword\">s!</span>" ++
+  "<span class=\"literal\">&quot;Hello, {</span>" ++
+  "<span class=\"var\">name</span>" ++
+  "<span class=\"literal\">}&quot;</span>" ++
+  "</code>"
+
+end Verso.Genre.Manual.Theme
diff --git a/src/verso-manual/VersoManual/Theme/Defaults.lean b/src/verso-manual/VersoManual/Theme/Defaults.lean
index 58a71b686..61c57b922 100644
--- a/src/verso-manual/VersoManual/Theme/Defaults.lean
+++ b/src/verso-manual/VersoManual/Theme/Defaults.lean
@@ -13,15 +13,485 @@ set_option doc.verso true
 
 /-!
 Built-in {Lean.Doc.name}`Verso.Theme.ManualTheme` values. The default theme reproduces today's
-chrome so existing manuals render unchanged when no override is configured.
+chrome so existing manuals render unchanged when no override is configured. The dark counterpart
+inverts the page and code backgrounds while preserving the typography-only token rendering.
+
+Additional families ({lit}`Chromatic`, {lit}`Beacon`, etc.) ship colorful syntax palettes for
+authors who want them; each family registers a light and a dark variant.
 -/
 
 namespace Verso.Theme
 
+/-! # Defaults: Ink (light) and Argent (dark) -/
+
+/--
+The light default manual theme. Named after the most ancient writing medium in use, after the
+inks made from soot or oak gall that have carried text for two thousand years. Typography and
+chrome reproduce today's hardcoded look.
+
+Other built-in themes live alongside it in the {Lean.Doc.name}`Verso.Theme.ManualTheme` namespace.
+-/
+@[manual_theme]
+public def ManualTheme.ink : ManualTheme where
+  toCodeTheme := { CodeTheme.ink with name := "Ink" }
+
+/--
+A common dark-appearance code-theme base: deep-charcoal backgrounds, brightened text, accent
+colors chosen for readability against the dark substrate. Other dark themes extend this. Every
+cascading field is overridden explicitly because Lean evaluates the {Lean.Doc.name}`Verso.Theme.CodeTheme`
+defaults at construction time, so {lit}`CodeTheme.ink with textColor := …` would otherwise
+leave dependent fields (token colors, message text colors, hover text) frozen at their
+original-light values.
+-/
+private def darkCodeBase : CodeTheme :=
+  let bg := color%#16181c
+  let codeBg := color%#1e2026
+  let text := color%#e8e8e8
+{
+  CodeTheme.ink with
+  appearance := .dark,
+  background := bg,
+  codeBlockBackground := codeBg,
+  textColor := text,
+  codeColor := text,
+  structureColor := text,
+  -- Message text colors must read on the dark page background.
+  errorColor := color%#ff8b8b,
+  warningColor := text,
+  infoColor := text,
+  -- Token colors default to the bright code color; colorful themes override these per token.
+  const   := { color := text, weight := .regular, style := .normal, face := .mono },
+  keyword := { color := text, weight := .bold,    style := .normal, face := .mono },
+  «var»   := { color := text, weight := .regular, style := .italic, face := .mono },
+  -- Hover popups read text on a slightly lighter surface.
+  hoverBackground := color%#2a2d33,
+  hoverText := text,
+  hoverBorderColor := color%#aaaaaa,
+  hoverSeparatorColor := color%#3a3d44,
+  tokenHighlightBackground := color%#33363d,
+  -- Tactic state uses the same surface as code blocks but with a visible border.
+  tacticStateBackground := codeBg,
+  tacticStateBorderColor := color%#aaaaaa,
+  selectedColor := color%#2a3f55,
+  -- Highlight accents on a dark substrate: a saturated tone that the bright text still reads on.
+  highlightOnCode := color%#3a2f00,
+  highlightOnText := color%#3a2f00,
+  uiOnCode := color%#aaaaaa
+}
+
+/--
+A common dark-appearance chrome base reused by the shipped dark themes. The chrome variables
+inherit from the dark code base where possible (so a uniform dark look) and use explicit values
+where contrast requires lighter chrome accents (borders, muted text, links). The burger menu
+lines pick up the text color (so the lines themselves are visible against the page background;
+without this override they default to the light theme's near-black `#0e2431`, which is
+invisible on a dark substrate and shows only the surrounding `drop-shadow`).
+-/
+private def darkChromeFields (code : CodeTheme) : ManualTheme := {
+  toCodeTheme := code,
+  surfaceColor := color%#1f2229,
+  tocBackground := color%#1a1c22,
+  borderColor := color%#a0a3ab,
+  mutedColor := color%#a8acb5,
+  linkColor := color%#6cb6ff,
+  visitedLinkColor := color%#a98aff,
+  burgerHiddenColor := code.textColor,
+  burgerVisibleColor := code.textColor,
+  burgerHiddenShadowColor := code.background,
+  burgerVisibleShadowColor := code.background
+}
+
+/--
+The dark default manual theme. Named after silver, the ink of choice for the dark-substrate
+manuscript traditions: silver-on-purple Byzantine and Carolingian codices like the *Codex
+Argenteus*, Flemish "Black Hours" such as Morgan MS M.493, and Korean *eunja sagyeong* (은자사경)
+sutras transcribed in silver ink on indigo *kamji* paper during the Goryeo dynasty. Same
+typography-only token rendering as {Lean.Doc.name}`Verso.Theme.ManualTheme.ink`, with inverted
+backgrounds and a light text color.
+-/
+@[manual_theme]
+public def ManualTheme.argent : ManualTheme :=
+  darkChromeFields { darkCodeBase with name := "Argent" }
+
+/-! # Chromatic — colorful syntax accents -/
+
+/--
+Chromatic light: full color plus typography for syntax tokens on a light background. Palette
+chosen so each token color meets WCAG AA on white and remains visually distinct under all three
+dichromacies (variables use a dark slate so the bold/italic typography is the dominant signal).
+-/
+@[manual_theme]
+public def ManualTheme.chromaticLight : ManualTheme where
+  toCodeTheme := {
+    CodeTheme.ink with
+    name := "Chromatic Light",
+    keyword.color := color%#a02828,
+    const.color   := color%#0b6b4f,
+    «var».color   := color%#404040
+  }
+
+/-- Chromatic dark: the colored Lean palette on a deep-charcoal background. -/
+@[manual_theme]
+public def ManualTheme.chromaticDark : ManualTheme :=
+  darkChromeFields {
+    darkCodeBase with
+    name := "Chromatic Dark",
+    keyword.color := color%#ff8b8b,
+    const.color   := color%#6cb6ff,
+    «var».color   := color%#c4c4c4
+  }
+
+/-! # Beacon — colorblind-safe syntax accents (Okabe-Ito) -/
+
+/--
+Beacon light: a colorblind-safe syntax palette drawn from the Okabe-Ito set. Black on white
+chrome; tokens use Okabe-Ito blue/orange/bluish-green so they stay distinguishable under all
+three dichromacies.
+-/
+@[manual_theme]
+public def ManualTheme.beaconLight : ManualTheme where
+  toCodeTheme := {
+    CodeTheme.ink with
+    name := "Beacon Light",
+    keyword.color := color%#005b8c,
+    const.color   := color%#5b3500,
+    «var».color   := color%#9c2400
+  }
+
+/--
+Beacon dark: the Okabe-Ito palette on a near-black background, with brightened variants chosen
+to keep distance under each dichromacy on the darker substrate.
+-/
+@[manual_theme]
+public def ManualTheme.beaconDark : ManualTheme :=
+  darkChromeFields {
+    darkCodeBase with
+    name := "Beacon Dark",
+    keyword.color := color%#56b4e9,
+    const.color   := color%#5bd6a4,
+    «var».color   := color%#f5a85a
+  }
+
+/-! # Solarized — Ethan Schoonover's standard palette -/
+
+/--
+Solarized light: Schoonover's standard cream-on-paper palette
+({lit}`base3` background, {lit}`base00` body text). Token accents reuse the named hues from
+the upstream Solarized definition.
+-/
+@[manual_theme]
+public def ManualTheme.solarizedLight : ManualTheme where
+  toCodeTheme := {
+    CodeTheme.ink with
+    name := "Solarized Light",
+    background := color%#fdf6e3,
+    codeBlockBackground := color%#eee8d5,
+    textColor := color%#586e75,
+    codeColor := color%#586e75,
+    structureColor := color%#586e75,
+    warningColor := color%#586e75,
+    infoColor := color%#586e75,
+    errorColor := color%#dc322f,
+    errorIndicatorColor := color%#dc322f,
+    warningIndicatorColor := color%#b58900,
+    infoIndicatorColor := color%#268bd2,
+    hoverBackground := color%#eee8d5,
+    hoverText := color%#586e75,
+    hoverBorderColor := color%#93a1a1,
+    hoverSeparatorColor := color%#93a1a1,
+    tokenHighlightBackground := color%#eee8d5,
+    tacticStateBackground := color%#eee8d5,
+    tacticStateBorderColor := color%#93a1a1,
+    selectedColor := color%#eee8d5,
+    highlightOnCode := color%#f7e7a3,
+    uiOnCode := color%#93a1a1,
+    keyword.color := color%#859900,
+    const.color   := color%#268bd2,
+    «var».color   := color%#6c71c4
+  }
+  surfaceColor := color%#eee8d5
+  tocBackground := color%#eee8d5
+  borderColor := color%#586e75
+  mutedColor := color%#657b83
+  linkColor := color%#268bd2
+  visitedLinkColor := color%#6c71c4
+
+/--
+Solarized dark: Schoonover's standard {lit}`base03` background with body text on {lit}`base0`.
+Same accent hues as the light variant; the relative-luminance jump comes from the substrate.
+-/
+@[manual_theme]
+public def ManualTheme.solarizedDark : ManualTheme :=
+  darkChromeFields {
+    darkCodeBase with
+    name := "Solarized Dark",
+    background := color%#002b36,
+    codeBlockBackground := color%#073642,
+    textColor := color%#93a1a1,
+    codeColor := color%#93a1a1,
+    structureColor := color%#93a1a1,
+    warningColor := color%#93a1a1,
+    infoColor := color%#93a1a1,
+    errorColor := color%#ff8b8b,
+    errorIndicatorColor := color%#dc322f,
+    warningIndicatorColor := color%#b58900,
+    infoIndicatorColor := color%#268bd2,
+    hoverBackground := color%#073642,
+    hoverText := color%#93a1a1,
+    hoverBorderColor := color%#586e75,
+    hoverSeparatorColor := color%#586e75,
+    tokenHighlightBackground := color%#073642,
+    tacticStateBackground := color%#073642,
+    tacticStateBorderColor := color%#586e75,
+    selectedColor := color%#073642,
+    highlightOnCode := color%#3a2f00,
+    uiOnCode := color%#93a1a1,
+    keyword.color := color%#b3d100,
+    const.color   := color%#6cb6ff,
+    «var».color   := color%#a98aff
+  }
+
+/-! # Sandstone — warm sepia (Rust/Ayu inspired) -/
+
+/-- Sandstone light: a warm cream background with terracotta and umber accents. -/
+@[manual_theme]
+public def ManualTheme.sandstoneLight : ManualTheme where
+  toCodeTheme := {
+    CodeTheme.ink with
+    name := "Sandstone Light",
+    background := color%#faf5ee,
+    codeBlockBackground := color%#f3e9d6,
+    textColor := color%#3b2a17,
+    codeColor := color%#3b2a17,
+    structureColor := color%#3b2a17,
+    warningColor := color%#3b2a17,
+    infoColor := color%#3b2a17,
+    errorColor := color%#a83232,
+    errorIndicatorColor := color%#c0392b,
+    warningIndicatorColor := color%#a05a00,
+    infoIndicatorColor := color%#1f6f8b,
+    hoverBackground := color%#f3e9d6,
+    hoverText := color%#3b2a17,
+    hoverBorderColor := color%#8c7257,
+    hoverSeparatorColor := color%#8c7257,
+    tokenHighlightBackground := color%#f3e9d6,
+    tacticStateBackground := color%#f3e9d6,
+    tacticStateBorderColor := color%#8c7257,
+    selectedColor := color%#f4d5a8,
+    highlightOnCode := color%#f4d5a8,
+    uiOnCode := color%#8c7257,
+    keyword.color := color%#a04a00,
+    const.color   := color%#1f6f8b,
+    «var».color   := color%#3b2a17
+  }
+  surfaceColor := color%#f3e9d6
+  tocBackground := color%#f3e9d6
+  borderColor := color%#8c7257
+  mutedColor := color%#7a5a40
+  linkColor := color%#a04a00
+  visitedLinkColor := color%#7a3a91
+
+/--
+Sandstone dark: weathered canyon walls at dusk — deep terracotta substrate with sunlit-buff
+text and warm vermilion / honey accents. No cool blues: the previous version's `#80c8e8`
+const broke the warm-palette family. Inspired by the Sedona red rocks, Petra at twilight, and
+the Vermilion Cliffs of Arizona-Utah.
+-/
+@[manual_theme]
+public def ManualTheme.sandstoneDark : ManualTheme :=
+  let base := darkChromeFields {
+    darkCodeBase with
+    name := "Sandstone Dark",
+    -- Dark canyon-shadow substrate. Slightly warmer than the legacy `#241a10`, with more
+    -- red and less yellow so it reads as weathered stone rather than coffee.
+    background := color%#2d1810,
+    codeBlockBackground := color%#3a2118,
+    -- Sunlit-buff text — the colour a sandstone face takes in late-afternoon light.
+    textColor := color%#f3d5a3,
+    codeColor := color%#f3d5a3,
+    structureColor := color%#f3d5a3,
+    warningColor := color%#f3d5a3,
+    infoColor := color%#f3d5a3,
+    errorColor := color%#ff8b8b,
+    errorIndicatorColor := color%#ff6f6f,
+    warningIndicatorColor := color%#e0a060,
+    infoIndicatorColor := color%#ffae5a,
+    hoverBackground := color%#4a2c20,
+    hoverText := color%#f3d5a3,
+    hoverBorderColor := color%#a87c52,
+    hoverSeparatorColor := color%#5e3925,
+    tokenHighlightBackground := color%#4a2c20,
+    tacticStateBackground := color%#3a2118,
+    tacticStateBorderColor := color%#a87c52,
+    selectedColor := color%#553626,
+    highlightOnCode := color%#6b4500,
+    highlightOnText := color%#6b4500,
+    uiOnCode := color%#a87c52,
+    -- Vermilion keyword, honey const, cream var (italic). All three are warm, distinguished
+    -- by hue *and* lightness so the palette stays distinct under most dichromacies even
+    -- without a cool accent.
+    keyword.color := color%#ff8c4a,
+    const.color   := color%#ffc266,
+    «var».color   := color%#f3d5a3
+  }
+  -- Override the generic dark-chrome accents with sandstone-tuned values so the search box
+  -- border, ToC background, and link colours stay in the warm family.
+  { base with
+    surfaceColor := color%#3a2118,
+    tocBackground := color%#2d1810,
+    borderColor := color%#a87c52,
+    mutedColor := color%#c89866,
+    linkColor := color%#ffae5a,
+    visitedLinkColor := color%#d49a8a }
+
+/-! # Steel (light) and Slate (dark) — cool high-contrast (Coal/Navy inspired) -/
+
+/-- Slate light: cool, near-white substrate with deep navy text. -/
+@[manual_theme]
+public def ManualTheme.steel : ManualTheme where
+  toCodeTheme := {
+    CodeTheme.ink with
+    name := "Steel",
+    background := color%#f4f6f8,
+    codeBlockBackground := color%#e3e8ee,
+    textColor := color%#0e2431,
+    codeColor := color%#0e2431,
+    structureColor := color%#0e2431,
+    warningColor := color%#0e2431,
+    infoColor := color%#0e2431,
+    errorColor := color%#a92020,
+    errorIndicatorColor := color%#c0392b,
+    warningIndicatorColor := color%#9c6500,
+    infoIndicatorColor := color%#1a5ea8,
+    hoverBackground := color%#e3e8ee,
+    hoverText := color%#0e2431,
+    hoverBorderColor := color%#46566a,
+    hoverSeparatorColor := color%#46566a,
+    tokenHighlightBackground := color%#e3e8ee,
+    tacticStateBackground := color%#e3e8ee,
+    tacticStateBorderColor := color%#46566a,
+    selectedColor := color%#c5d4e3,
+    highlightOnCode := color%#fff3b0,
+    uiOnCode := color%#46566a,
+    keyword.color := color%#1a5ea8,
+    const.color   := color%#2a6f4f,
+    «var».color   := color%#0e2431
+  }
+  surfaceColor := color%#e3e8ee
+  tocBackground := color%#e3e8ee
+  borderColor := color%#46566a
+  mutedColor := color%#465a70
+  linkColor := color%#1a5ea8
+  visitedLinkColor := color%#6c4ea8
+
+/-- Slate dark: coal/navy substrate, brightened slate accents. -/
+@[manual_theme]
+public def ManualTheme.slate : ManualTheme :=
+  darkChromeFields {
+    darkCodeBase with
+    name := "Slate",
+    background := color%#0e1822,
+    codeBlockBackground := color%#172533,
+    textColor := color%#dfe6ee,
+    codeColor := color%#dfe6ee,
+    structureColor := color%#dfe6ee,
+    warningColor := color%#dfe6ee,
+    infoColor := color%#dfe6ee,
+    errorColor := color%#ff8b8b,
+    errorIndicatorColor := color%#ff6f6f,
+    warningIndicatorColor := color%#e6b04a,
+    infoIndicatorColor := color%#6cb6ff,
+    hoverBackground := color%#1f3142,
+    hoverText := color%#dfe6ee,
+    hoverBorderColor := color%#7a8aa0,
+    hoverSeparatorColor := color%#3a4a5e,
+    tokenHighlightBackground := color%#1f3142,
+    tacticStateBackground := color%#172533,
+    tacticStateBorderColor := color%#7a8aa0,
+    selectedColor := color%#284a6a,
+    highlightOnCode := color%#3a2f00,
+    uiOnCode := color%#7a8aa0,
+    keyword.color := color%#6cb6ff,
+    const.color   := color%#7ad9a0,
+    «var».color   := color%#dfe6ee
+  }
+
+/-! # Hearth — cottagecore (cream/sage light, candlelit deep-olive dark) -/
+
+/--
+Hearth light: a cream substrate with sage and dusty rose accents and a serifed structure font.
+-/
+@[manual_theme]
+public def ManualTheme.hearthLight : ManualTheme where
+  toCodeTheme := {
+    CodeTheme.ink with
+    name := "Hearth Light",
+    background := color%#f7f1e3,
+    codeBlockBackground := color%#ede4cf,
+    textColor := color%#3d2f1f,
+    codeColor := color%#3d2f1f,
+    structureColor := color%#3d2f1f,
+    warningColor := color%#3d2f1f,
+    infoColor := color%#3d2f1f,
+    errorColor := color%#a04050,
+    errorIndicatorColor := color%#a04050,
+    warningIndicatorColor := color%#a07020,
+    infoIndicatorColor := color%#2f6e58,
+    hoverBackground := color%#ede4cf,
+    hoverText := color%#3d2f1f,
+    hoverBorderColor := color%#7a6952,
+    hoverSeparatorColor := color%#7a6952,
+    tokenHighlightBackground := color%#ede4cf,
+    tacticStateBackground := color%#ede4cf,
+    tacticStateBorderColor := color%#7a6952,
+    selectedColor := color%#e3cfae,
+    highlightOnCode := color%#e3cfae,
+    uiOnCode := color%#7a6952,
+    keyword.color := color%#2f6e58,
+    const.color   := color%#a04050,
+    «var».color   := color%#3d2f1f
+  }
+  textFace := .serif
+  structureFace := .serif
+  surfaceColor := color%#ede4cf
+  tocBackground := color%#ede4cf
+  borderColor := color%#7a6952
+  mutedColor := color%#6b5640
+  linkColor := color%#2f6e58
+  visitedLinkColor := color%#7a3a91
+
 /--
-The default manual theme: typography and chrome that reproduce today's hardcoded look. Other
-built-in themes live alongside it in the {Lean.Doc.name}`Verso.Theme.ManualTheme` namespace.
+Hearth dark: a deep-olive candlelit substrate with warm cream text. Serifed structure font, same
+muted sage and dusty rose accents as the light variant.
 -/
 @[manual_theme]
-public def ManualTheme.Default : ManualTheme where
-  toCodeTheme := CodeTheme.Default
+public def ManualTheme.hearthDark : ManualTheme :=
+  let base := darkChromeFields {
+    darkCodeBase with
+    name := "Hearth Dark",
+    background := color%#1e1e14,
+    codeBlockBackground := color%#262619,
+    textColor := color%#f1e7d2,
+    codeColor := color%#f1e7d2,
+    structureColor := color%#f1e7d2,
+    warningColor := color%#f1e7d2,
+    infoColor := color%#f1e7d2,
+    errorColor := color%#ff8b8b,
+    errorIndicatorColor := color%#ff7a90,
+    warningIndicatorColor := color%#e6a85a,
+    infoIndicatorColor := color%#80c8a8,
+    hoverBackground := color%#33321f,
+    hoverText := color%#f1e7d2,
+    hoverBorderColor := color%#a08a64,
+    hoverSeparatorColor := color%#4a4628,
+    tokenHighlightBackground := color%#33321f,
+    tacticStateBackground := color%#262619,
+    tacticStateBorderColor := color%#a08a64,
+    selectedColor := color%#33321f,
+    highlightOnCode := color%#5c4a00,
+    uiOnCode := color%#a08a64,
+    keyword.color := color%#9adcb0,
+    const.color   := color%#f5a8b8,
+    «var».color   := color%#f1e7d2
+  }
+  { base with textFace := .serif, structureFace := .serif }
diff --git a/src/verso-manual/VersoManual/Theme/Emit.lean b/src/verso-manual/VersoManual/Theme/Emit.lean
new file mode 100644
index 000000000..bcaa3a3b8
--- /dev/null
+++ b/src/verso-manual/VersoManual/Theme/Emit.lean
@@ -0,0 +1,153 @@
+/-
+Copyright (c) 2025 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+public import VersoManual.Theme
+public import Lean.Data.Json
+
+set_option linter.missingDocs true
+set_option doc.verso true
+
+/-!
+Build helpers for the runtime theme-selection scaffolding: the inline no-flash head script, the
+{lit}`window.versoThemes` data file, and the {lit}`:root[data-verso-theme="…"]`-scoped CSS
+written into {lit}`verso-themes.css`.
+-/
+
+namespace Verso.Theme
+
+open Lean (Json)
+
+/-- The pieces of a theme that the picker / no-flash script need at runtime, JSON-encoded. -/
+private def themeJson (n : Lean.Name) (t : ManualTheme) : Json :=
+  let appearance := match t.appearance with | .light => "light" | .dark => "dark"
+  Json.mkObj [
+    ("id", Json.str n.toString),
+    ("name", Json.str t.name),
+    ("appearance", Json.str appearance)
+  ]
+
+/--
+The contents of {lit}`-verso-data/verso-themes.js`. Exposes {lit}`window.versoThemes` with the
+shape `{ themes: [...], defaultLight, defaultDark, codeSample }` so the picker can render the
+choices and the live code preview.
+
+`codeSample` is a small fixed HTML string reusing the `.hl.lean` markup; the picker drops it
+inside a `data-verso-theme`-scoped element to show what each theme will look like.
+-/
+public def windowVersoThemesJs
+    (themes : Array (Lean.Name × ManualTheme))
+    (defaultLight defaultDark defaultSingle : Lean.Name)
+    (codeSample : String) : String :=
+  let entries := themes.map (fun (n, t) => themeJson n t)
+  let payload := Json.mkObj [
+    ("themes", Json.arr entries),
+    ("defaultLight", Json.str defaultLight.toString),
+    ("defaultDark", Json.str defaultDark.toString),
+    ("defaultSingle", Json.str defaultSingle.toString),
+    ("codeSample", Json.str codeSample)
+  ]
+  s!"window.versoThemes = {payload.compress};\n"
+
+/--
+The body of the synchronous head script that runs before paint and sets
+{lit}`data-verso-theme` and {lit}`data-verso-appearance` on the document root so the first
+painted frame matches the chosen theme. The {lit}`themes` argument is the available set; the
+defaults are inlined here (not read from {lit}`window.versoThemes`) to avoid an ordering race.
+
+Single-mode fallback is {lit}`defaultSingle` — the theme an author chose for readers who do
+not follow the system appearance. First visits (no stored mode) use the same fallback so the
+painted frame matches what the reader will see when they open the picker.
+-/
+public def themeInitScript
+    (themes : Array (Lean.Name × ManualTheme))
+    (defaultLight defaultDark defaultSingle : Lean.Name) : String :=
+  let pairs := themes.toList.map fun (n, t) =>
+    let a := match t.appearance with | .light => "light" | .dark => "dark"
+    s!"\"{n.toString}\":\"{a}\""
+  let table := "{" ++ ",".intercalate pairs ++ "}"
+  s!"(function() \{
+  var APPEARANCE = {table};
+  var DEFAULT_LIGHT = \"{defaultLight.toString}\";
+  var DEFAULT_DARK = \"{defaultDark.toString}\";
+  var DEFAULT_SINGLE = \"{defaultSingle.toString}\";
+  function readMode() \{ try \{ return localStorage.getItem(\"verso-theme-mode\"); } catch (e) \{ return null; } }
+  function readKey(k) \{ try \{ return localStorage.getItem(k); } catch (e) \{ return null; } }
+  var mode = readMode();
+  var prefersDark = window.matchMedia && window.matchMedia(\"(prefers-color-scheme: dark)\").matches;
+  var picked = null;
+  if (mode === \"single\") \{
+    picked = readKey(\"verso-theme-single\") || DEFAULT_SINGLE;
+  } else if (mode === \"auto\") \{
+    picked = prefersDark ? readKey(\"verso-theme-dark\") : readKey(\"verso-theme-light\");
+    if (!picked) picked = prefersDark ? DEFAULT_DARK : DEFAULT_LIGHT;
+  }
+  if (!picked || !APPEARANCE.hasOwnProperty(picked)) \{
+    // First visit (no mode set): use the single-mode default the author configured so the
+    // painted frame matches what the picker would show on this device.
+    picked = DEFAULT_SINGLE;
+  }
+  var appearance = APPEARANCE[picked] || (prefersDark ? \"dark\" : \"light\");
+  document.documentElement.setAttribute(\"data-verso-theme\", picked);
+  document.documentElement.setAttribute(\"data-verso-appearance\", appearance);
+  function onChange(e) \{
+    if ((readMode() || \"auto\") !== \"auto\") return;
+    var dark = e.matches;
+    var k = dark ? \"verso-theme-dark\" : \"verso-theme-light\";
+    var p = readKey(k);
+    if (!p || !APPEARANCE.hasOwnProperty(p)) p = dark ? DEFAULT_DARK : DEFAULT_LIGHT;
+    document.documentElement.setAttribute(\"data-verso-theme\", p);
+    document.documentElement.setAttribute(\"data-verso-appearance\", APPEARANCE[p]);
+  }
+  var mq = window.matchMedia && window.matchMedia(\"(prefers-color-scheme: dark)\");
+  if (mq) \{
+    if (mq.addEventListener) mq.addEventListener(\"change\", onChange);
+    else if (mq.addListener) mq.addListener(onChange);
+  }
+})();"
+
+/--
+Produces the body of {lit}`verso-themes.css`:
+
+- font-face rules from every available theme (one block per theme; content dedup is the caller's
+  job);
+- an unscoped `:root` block carrying the {lit}`single`'s variables — what the server-rendered
+  HTML uses before the no-flash script attaches {lit}`data-verso-theme`. `single` is the
+  resolved single-mode default theme;
+- an `@media (prefers-color-scheme: dark)` block carrying the {Lean.Doc.name}`Verso.Theme.ManualTheme`
+  named by `defaultDark` (no-JS fallback only — the no-flash script always sets a concrete
+  attribute);
+- one `:root[data-verso-theme="…"]` block per registered theme so the picker can swap themes by
+  flipping the attribute.
+
+`single` is always one of the registered themes, so its font and asset URLs resolve against
+the same {lit}`-verso-data/themes/<name>` root as the attribute-scoped blocks; no separate
+page-theme asset root is needed.
+-/
+public def «verso-themes.css»
+    (single : ManualTheme)
+    (themes : Array (Lean.Name × ManualTheme))
+    (_defaultLight defaultDark : Lean.Name) : String := Id.run do
+  let assetRoot (n : Lean.Name) : String := s!"-verso-data/themes/{n.toString}"
+  let mut out := ""
+  -- Font-face rules.
+  for (n, t) in themes do
+    let rules := t.fontFaceRules (assetRoot n)
+    unless rules.isEmpty do out := out ++ rules
+  -- Unscoped :root block from the single-mode default.
+  out := out ++ s!":root \{\n{single.cssVariables}}\n"
+  -- @media dark fallback for no-JS visitors.
+  if let some t := themes.findSome? (fun (n, t) => if n == defaultDark then some t else none) then
+    out := out ++ s!"@media (prefers-color-scheme: dark) \{\n  :root \{\n{t.cssVariables}  }\n}\n"
+  -- Attribute-scoped blocks for every registered theme.
+  for (n, t) in themes do
+    out := out ++ s!":root[data-verso-theme=\"{n.toString}\"] \{\n{t.cssVariables}}\n"
+    let extra := t.extraCss (assetRoot n)
+    unless extra.isEmpty do
+      out := out ++ s!":where(:root[data-verso-theme=\"{n.toString}\"]) \{\n{extra}}\n"
+  return out
+
+end Verso.Theme
diff --git a/src/verso/Verso/Theme/Code/Defaults.lean b/src/verso/Verso/Theme/Code/Defaults.lean
index d5488e7ba..399862b0b 100644
--- a/src/verso/Verso/Theme/Code/Defaults.lean
+++ b/src/verso/Verso/Theme/Code/Defaults.lean
@@ -18,10 +18,11 @@ hardcoded look so existing manuals render unchanged when no override is configur
 namespace Verso.Theme
 
 /--
-The default code theme: typography-only styling that reproduces today's hardcoded look. Other
-built-in themes live alongside it in the {Lean.Doc.name}`Verso.Theme.CodeTheme` namespace.
+The default code theme: typography-only styling that reproduces today's hardcoded look. Named
+after the most ancient writing medium in use; other built-in themes live alongside it in the
+{Lean.Doc.name}`Verso.Theme.CodeTheme` namespace.
 -/
 @[code_theme]
-public def CodeTheme.Default : CodeTheme where
-  name := "Default"
+public def CodeTheme.ink : CodeTheme where
+  name := "Ink"
   appearance := .light
diff --git a/static-web/theme/theme-picker.css b/static-web/theme/theme-picker.css
new file mode 100644
index 000000000..df06d567e
--- /dev/null
+++ b/static-web/theme/theme-picker.css
@@ -0,0 +1,176 @@
+/* Theme picker — gear button + popover + dropdowns.
+   Mounted by static-web/theme/theme-picker.js into `<div class="header-tools">`.
+   The gear is always rendered server-side as static HTML; the popover is built
+   on first open. */
+
+#theme-picker-button {
+    /* Plain glyph button — no box, matching the search input (also no border at rest) and
+       the burger menu (no box at all). Color flips to the link color when the popover is
+       open to signal the toggled state. */
+    appearance: none;
+    background: transparent;
+    border: none;
+    padding: 0;
+    color: var(--verso-text-color, inherit);
+    cursor: pointer;
+    font-family: var(--verso-structure-font-family);
+    font-size: 0.9rem;
+    line-height: 1;
+    display: inline-flex;
+    align-items: center;
+    gap: 0.3rem;
+    /* Ensure the gear paints above the title — `.header-title-wrapper` and friends have
+       no explicit z-index, but a positioned element without z-index can still get sorted
+       behind a later sibling in some rendering paths. Pin it. */
+    z-index: 2;
+}
+
+#theme-picker-button:focus-visible {
+    outline: 2px solid var(--verso-link-color, currentColor);
+    outline-offset: 2px;
+    border-radius: 0.2rem;
+}
+
+/* Pressed/open state — the dialog is showing. With no border or background, a color flip
+   does the toggled-state signalling. `aria-expanded` is what the JS already toggles, and
+   it is what screen readers announce. */
+#theme-picker-button[aria-expanded="true"] {
+    color: var(--verso-link-color, currentColor);
+}
+
+#theme-picker-button .theme-picker-gear {
+    /* The Unicode `⚙` glyph (U+2699) has a small drawn cog relative to its em-box — the
+       visible cog ink is roughly 70-75% of the rendered ink rect, so even a glyph whose
+       ink rect matches the search input still *reads* as noticeably smaller than the
+       adjacent text. To compensate, scale the font-size so the rendered ink rect is
+       ~115-125% of the search input outer height; that lands the optical cog size on the
+       search input's text cap-height plus a small visual halo, which reads as the "same
+       size as the search field" the user was after. The button itself is vertically
+       centered in the full-height header by `align-items: center` (set on `.header-tools`),
+       so the gear's line-box center sits at the header's vertical midline — same as the
+       search input's center, since the search wrapper also spans the full header height. */
+    font-size: 1.7rem;
+    line-height: 1;
+}
+
+#theme-picker-dialog {
+    /* Fixed so the right offset can match the gear's (also relative to the viewport's right
+       edge, via the same `--search-bar-width` math) and the popup drops directly under it. */
+    position: fixed;
+    top: calc(var(--verso-header-height, 3rem) + 0.25rem);
+    right: calc(var(--search-bar-width, 24rem) + 1rem);
+    z-index: 200;
+    background: var(--verso-surface-color, #f8f9fa);
+    color: var(--verso-text-color, #111);
+    border: 1px solid var(--verso-border-color, #999);
+    border-radius: 0.4rem;
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.18);
+    padding: 0.75rem;
+    width: min(22rem, calc(100vw - 1rem));
+    box-sizing: border-box;
+    /* Two-column grid: the label column auto-sizes to the widest label across all visible rows,
+       so Light/Dark/Theme dropdowns share a left edge. The rows themselves use
+       `display: contents` (below) so their label/select pairs become direct grid items. */
+    display: grid;
+    grid-template-columns: auto 1fr;
+    align-items: center;
+    column-gap: 0.5rem;
+    row-gap: 0.75rem;
+    font-family: var(--verso-structure-font-family);
+}
+
+#theme-picker-dialog[hidden] {
+    display: none;
+}
+
+#theme-picker-dialog .theme-picker-row {
+    display: contents;
+}
+
+/* The "Match system" row has a checkbox followed by its label, not a label column followed
+   by a control. Span both columns and lay it out as a flex pair so the checkbox sits flush
+   against its label instead of being orphaned in the label column with a gap to a label
+   stranded in the dropdown column. */
+/* `:where()` zeros the `:has` argument's specificity so the `[hidden]` rule above still wins
+   for any future code path that toggles this row. */
+#theme-picker-dialog .theme-picker-row:where(:has(> input[type="checkbox"])) {
+    display: flex;
+    align-items: center;
+    gap: 0.4rem;
+    grid-column: 1 / -1;
+}
+
+/* `[hidden]` toggles rely on this: `display: contents` on `.theme-picker-row` would
+   otherwise win over the default `display: none` the `hidden` attribute carries (and would
+   leak the row's children into the grid even when the row is hidden), so this rule restores
+   the expected hide. */
+#theme-picker-dialog .theme-picker-row[hidden] {
+    display: none;
+}
+
+#theme-picker-dialog .theme-picker-row select {
+    min-width: 0;
+    font: inherit;
+    padding: 0.2rem 0.3rem;
+    color: inherit;
+    background: var(--verso-background-color, white);
+    border: 1px solid var(--verso-border-color, #999);
+    border-radius: 0.25rem;
+}
+
+#theme-picker-preview {
+    /* The preview is meant to span the full popup width, not sit in the dropdown column. */
+    grid-column: 1 / -1;
+    border: 1px solid var(--verso-border-color, #999);
+    border-radius: 0.3rem;
+    background: var(--verso-code-background-color, #fff);
+    padding: 0.5rem;
+    font-family: var(--verso-code-font-family, monospace);
+    font-size: 0.85em;
+    overflow-x: auto;
+}
+
+@media (max-width: 600px) {
+    /* Full-screen sheet on small screens. */
+    #theme-picker-dialog {
+        position: fixed;
+        inset: 0;
+        top: var(--verso-header-height, 3rem);
+        right: 0;
+        bottom: 0;
+        left: 0;
+        width: auto;
+        max-width: none;
+        border-radius: 0;
+        border-width: 1px 0 0 0;
+    }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+    #theme-picker-dialog {
+        transition: opacity 0.15s ease;
+    }
+}
+
+@media print {
+    /* Don't show the picker (or its outputs) on print. */
+    #theme-picker-button,
+    #theme-picker-dialog {
+        display: none !important;
+    }
+}
+
+header .header-tools {
+    /* The search box is absolutely positioned at the right edge of `<header>` (see
+       static-web/search/search-box.css:#search-wrapper), so a normal-flow gear ends up either
+       at the far left or overlapping the search box. Mirror the search-box positioning with
+       an offset equal to the search bar width plus a small gap, so the visible order is
+       [logo] [title] ............ [theme-picker] [search]. */
+    position: absolute;
+    top: 0;
+    right: calc(var(--search-bar-width, 24rem) + 1rem);
+    height: var(--verso-header-height, 3rem);
+    display: flex;
+    align-items: center;
+    gap: 0.4rem;
+}
diff --git a/static-web/theme/theme-picker.js b/static-web/theme/theme-picker.js
new file mode 100644
index 000000000..d704984f3
--- /dev/null
+++ b/static-web/theme/theme-picker.js
@@ -0,0 +1,309 @@
+/* Theme picker.
+ *
+ * Builds and mounts the dialog opened by `#theme-picker-button` (which is rendered
+ * server-side as static HTML). Reads `window.versoThemes`, populates the dropdowns,
+ * persists choices to localStorage, and live-previews on hover/focus. The inline head
+ * script in `verso-themes.css`-paired no-flash block already set the initial theme;
+ * this file only handles user interaction. */
+
+(function () {
+    "use strict";
+
+    var data = window.versoThemes;
+    if (!data || !Array.isArray(data.themes) || data.themes.length === 0) return;
+
+    var button = document.getElementById("theme-picker-button");
+    if (!button) return;
+
+    // Graceful degradation: only one theme available -> hide the gear.
+    if (data.themes.length < 2) {
+        button.hidden = true;
+        return;
+    }
+
+    function readMode() {
+        try {
+            return localStorage.getItem("verso-theme-mode");
+        } catch (e) {
+            return null;
+        }
+    }
+    function writeMode(v) {
+        try {
+            if (v) localStorage.setItem("verso-theme-mode", v);
+            else localStorage.removeItem("verso-theme-mode");
+        } catch (e) {
+            /* localStorage may be disabled — fall through */
+        }
+    }
+    function readKey(k) {
+        try {
+            return localStorage.getItem(k);
+        } catch (e) {
+            return null;
+        }
+    }
+    function writeKey(k, v) {
+        try {
+            if (v) localStorage.setItem(k, v);
+            else localStorage.removeItem(k);
+        } catch (e) {
+            /* localStorage may be disabled */
+        }
+    }
+
+    function applyTheme(id) {
+        var t = data.themes.find(function (x) {
+            return x.id === id;
+        });
+        if (!t) return;
+        // Skip redundant attribute writes. `setAttribute` with the same value still fires
+        // MutationObservers and any attribute-selector style recomputation, so a focus
+        // preview that re-applies the already-visible theme would log as a spurious
+        // "intermediate state" in tests and could trigger a wasteful style pass at runtime.
+        var root = document.documentElement;
+        if (root.getAttribute("data-verso-theme") !== id) {
+            root.setAttribute("data-verso-theme", id);
+        }
+        if (root.getAttribute("data-verso-appearance") !== t.appearance) {
+            root.setAttribute("data-verso-appearance", t.appearance);
+        }
+    }
+
+    // The committed theme is whatever the no-flash script (or a previous picker commit)
+    // actually applied to `<html>`. Reading the attribute matches what the user is currently
+    // looking at — including the matchMedia result in auto mode — so Escape and outside-click
+    // revert to the visible state instead of guessing from localStorage.
+    function committedActiveId() {
+        return document.documentElement.getAttribute("data-verso-theme");
+    }
+
+    var dialog = null;
+    var trapHandlers = null;
+    var lastFocus = null;
+    // `trackedCommitted` is the id we should revert to when the dialog closes without a
+    // commit. It is captured on `open()` (= the visible theme at that moment, which is the
+    // last committed value since previews can only happen after open) and updated by `commit()`
+    // so a subsequent dismiss/Escape/outside-click never undoes a real commit.
+    var trackedCommitted = null;
+
+    function buildDialog() {
+        dialog = document.createElement("div");
+        dialog.id = "theme-picker-dialog";
+        dialog.setAttribute("role", "dialog");
+        dialog.setAttribute("aria-label", "Theme picker");
+        dialog.hidden = true;
+
+        // Alphabetize by display name.
+        var sortedThemes = data.themes.slice().sort(function (a, b) {
+            return a.name.localeCompare(b.name);
+        });
+        var lightThemes = sortedThemes.filter(function (t) {
+            return t.appearance === "light";
+        });
+        var darkThemes = sortedThemes.filter(function (t) {
+            return t.appearance === "dark";
+        });
+        var hasMixed = lightThemes.length > 0 && darkThemes.length > 0;
+
+        // "Match system" toggle, only when there's a mix of light and dark.
+        var modeRow = document.createElement("div");
+        modeRow.className = "theme-picker-row";
+        var modeLabel = document.createElement("label");
+        modeLabel.setAttribute("for", "theme-picker-mode");
+        modeLabel.textContent = "Match system";
+        var modeToggle = document.createElement("input");
+        modeToggle.type = "checkbox";
+        modeToggle.id = "theme-picker-mode";
+        modeToggle.checked = (readMode() || "auto") === "auto";
+        modeRow.appendChild(modeToggle);
+        modeRow.appendChild(modeLabel);
+        if (hasMixed) dialog.appendChild(modeRow);
+
+        // Appearance-scoped defaults: a theme is "the default" relative to a given dropdown.
+        // The light dropdown marks `defaultLight`; the dark dropdown marks `defaultDark`. The
+        // single-mode dropdown marks `defaultSingle` — the theme an author chose for readers
+        // who do not follow the system (either `defaultLight` or `defaultDark`, configured via
+        // `defaultSingleAppearance` on `RenderConfig`).
+        function isDefault(t, scope) {
+            if (scope === "dark") return t.id === data.defaultDark;
+            if (scope === "light") return t.id === data.defaultLight;
+            return t.id === data.defaultSingle;
+        }
+
+        function makeSelect(id, labelText, items, selected, scope) {
+            var row = document.createElement("div");
+            row.className = "theme-picker-row";
+            var l = document.createElement("label");
+            l.setAttribute("for", id);
+            l.textContent = labelText;
+            var s = document.createElement("select");
+            s.id = id;
+            items.forEach(function (t) {
+                var o = document.createElement("option");
+                o.value = t.id;
+                o.textContent = isDefault(t, scope) ? t.name + " (default)" : t.name;
+                if (t.id === selected) o.selected = true;
+                s.appendChild(o);
+            });
+            row.appendChild(l);
+            row.appendChild(s);
+            return { row: row, select: s };
+        }
+
+        var singleSel = makeSelect(
+            "theme-picker-single",
+            "Theme",
+            sortedThemes,
+            readKey("verso-theme-single") || data.defaultSingle,
+            "single",
+        );
+        var lightSel = makeSelect(
+            "theme-picker-light",
+            "Light",
+            lightThemes,
+            readKey("verso-theme-light") || data.defaultLight,
+            "light",
+        );
+        var darkSel = makeSelect(
+            "theme-picker-dark",
+            "Dark",
+            darkThemes,
+            readKey("verso-theme-dark") || data.defaultDark,
+            "dark",
+        );
+
+        dialog.appendChild(singleSel.row);
+        dialog.appendChild(lightSel.row);
+        dialog.appendChild(darkSel.row);
+
+        var preview = document.createElement("div");
+        preview.id = "theme-picker-preview";
+        preview.innerHTML = data.codeSample || "";
+        dialog.appendChild(preview);
+
+        function refreshLayout() {
+            var auto = modeToggle.checked;
+            singleSel.row.hidden = auto;
+            lightSel.row.hidden = !auto;
+            darkSel.row.hidden = !auto;
+        }
+        refreshLayout();
+
+        // The auto-mode active theme is the dropdown that matches the current
+        // `prefers-color-scheme`. Distinct from `committedActiveId()`, which reads the visible
+        // `data-verso-theme` and is only meaningful for cancel/revert paths.
+        function activeAutoThemeId() {
+            var prefersDark =
+                window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches;
+            return prefersDark ? darkSel.select.value : lightSel.select.value;
+        }
+
+        function commit() {
+            var newId;
+            if (modeToggle.checked) {
+                writeMode("auto");
+                writeKey("verso-theme-light", lightSel.select.value);
+                writeKey("verso-theme-dark", darkSel.select.value);
+                newId = activeAutoThemeId();
+            } else {
+                writeMode("single");
+                writeKey("verso-theme-single", singleSel.select.value);
+                newId = singleSel.select.value;
+            }
+            applyTheme(newId);
+            trackedCommitted = newId;
+        }
+
+        function previewTheme(id) {
+            if (id) applyTheme(id);
+        }
+
+        modeToggle.addEventListener("change", function () {
+            refreshLayout();
+            commit();
+        });
+        [singleSel.select, lightSel.select, darkSel.select].forEach(function (sel) {
+            sel.addEventListener("change", commit);
+            // No focus/hover preview: the picker commits immediately on `change`, so the
+            // user already gets visible feedback when they pick an option. Firing a
+            // preview on `focus` (or `mouseenter`) painted a stale "what's selected right
+            // now in this dropdown" theme between the user opening the dropdown and
+            // committing a new value — a perceivable mid-switch flash to the dropdown's
+            // current default or to the opposite-mode theme. Escape and outside-click
+            // still revert any in-flight preview, so a future re-introduction can hook
+            // back in here once the preview-vs-commit semantics are stabilised.
+        });
+
+        document.body.appendChild(dialog);
+    }
+
+    function focusable() {
+        return Array.from(
+            dialog.querySelectorAll("select, input, button, [tabindex]:not([tabindex='-1'])"),
+        ).filter(function (el) {
+            return !el.hidden && !el.disabled;
+        });
+    }
+
+    function trapTab(e) {
+        if (e.key !== "Tab") return;
+        var els = focusable();
+        if (els.length === 0) return;
+        var first = els[0],
+            last = els[els.length - 1];
+        if (e.shiftKey) {
+            if (document.activeElement === first) {
+                e.preventDefault();
+                last.focus();
+            }
+        } else {
+            if (document.activeElement === last) {
+                e.preventDefault();
+                first.focus();
+            }
+        }
+    }
+
+    function onEscape(e) {
+        if (e.key === "Escape" && !dialog.hidden) close();
+    }
+
+    function open() {
+        if (!dialog) buildDialog();
+        lastFocus = document.activeElement;
+        trackedCommitted = committedActiveId();
+        dialog.hidden = false;
+        button.setAttribute("aria-expanded", "true");
+        var f = focusable();
+        if (f.length) f[0].focus();
+        trapHandlers = trapTab;
+        dialog.addEventListener("keydown", trapHandlers);
+        document.addEventListener("keydown", onEscape);
+    }
+
+    function close() {
+        if (!dialog) return;
+        // Every dismiss path (Escape, outside click, gear-toggle) routes through here. If the
+        // user committed a choice, `trackedCommitted` is that choice; if they only previewed,
+        // it's the state at open. Reapplying it unconditionally reverts hover/focus previews.
+        if (trackedCommitted) applyTheme(trackedCommitted);
+        dialog.hidden = true;
+        button.setAttribute("aria-expanded", "false");
+        if (trapHandlers) dialog.removeEventListener("keydown", trapHandlers);
+        document.removeEventListener("keydown", onEscape);
+        if (lastFocus && lastFocus.focus) lastFocus.focus();
+    }
+
+    button.addEventListener("click", function () {
+        if (!dialog || dialog.hidden) open();
+        else close();
+    });
+
+    // Dismiss when clicking outside.
+    document.addEventListener("click", function (e) {
+        if (!dialog || dialog.hidden) return;
+        if (dialog.contains(e.target) || button.contains(e.target)) return;
+        close();
+    });
+})();

From df80fd5f81c34f499c28b04a773d8d5c2cab4b10 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Sun, 31 May 2026 14:21:10 +0200
Subject: [PATCH 10/31] formatting

---
 .../test_theme_customization.py               | 20 ++++--
 .../theme-picker/test_theme_picker.py         | 62 ++++++++++++++-----
 2 files changed, 62 insertions(+), 20 deletions(-)

diff --git a/browser-tests/theme-customization/test_theme_customization.py b/browser-tests/theme-customization/test_theme_customization.py
index f506f9f19..e3a4734eb 100644
--- a/browser-tests/theme-customization/test_theme_customization.py
+++ b/browser-tests/theme-customization/test_theme_customization.py
@@ -130,18 +130,24 @@ def _color(page, selector: str, prop: str = "color") -> str:
 
 def _expect(actual: str, hex_value: str, description: str) -> None:
     expected = _hex_to_rgb(hex_value)
-    assert actual == expected, f"{description}: expected {expected} ({hex_value}), got {actual}"
+    assert actual == expected, (
+        f"{description}: expected {expected} ({hex_value}), got {actual}"
+    )
 
 
 def test_token_colors(page):
     # The first `.keyword` in the only code block is `def`.
-    _expect(_color(page, "code.hl.lean .keyword"), THEME["keywordColor"], "keyword color")
+    _expect(
+        _color(page, "code.hl.lean .keyword"), THEME["keywordColor"], "keyword color"
+    )
     # `.const` on `hello` (the function name) and `String` (the type).
     _expect(_color(page, "code.hl.lean .const"), THEME["constColor"], "const color")
     # `.var` on `name` (the parameter binding).
     _expect(_color(page, "code.hl.lean .var"), THEME["varColor"], "var color")
     # `.unknown` (operator-like tokens) falls back to `--verso-code-color`.
-    _expect(_color(page, "code.hl.lean .unknown"), THEME["codeColor"], "fallback code color")
+    _expect(
+        _color(page, "code.hl.lean .unknown"), THEME["codeColor"], "fallback code color"
+    )
 
 
 def _goto_diagnostics(page, server):
@@ -158,7 +164,9 @@ def test_error_indicator(page, server):
 
 
 def test_page_background(page):
-    _expect(_color(page, "body", "background-color"), THEME["background"], "body background")
+    _expect(
+        _color(page, "body", "background-color"), THEME["background"], "body background"
+    )
 
 
 def test_body_text_color(page):
@@ -235,7 +243,9 @@ def test_border_var(page):
     # is mounted by JS so the variable is the most direct verification that the theme value
     # reaches the page. (The CSS rules in search-box.css / search-page.css use
     # `var(--verso-border-color, gray)` so a missing variable would fall back to gray.)
-    _expect(_root_var(page, "--verso-border-color"), THEME["borderColor"], "borderColor var")
+    _expect(
+        _root_var(page, "--verso-border-color"), THEME["borderColor"], "borderColor var"
+    )
 
 
 def test_prev_next_nav_color(page, server):
diff --git a/browser-tests/theme-picker/test_theme_picker.py b/browser-tests/theme-picker/test_theme_picker.py
index e619f7a58..981bf9d45 100644
--- a/browser-tests/theme-picker/test_theme_picker.py
+++ b/browser-tests/theme-picker/test_theme_picker.py
@@ -40,8 +40,16 @@ def built_site():
     if SITE_DIR.parent.exists():
         subprocess.check_call(["rm", "-rf", str(SITE_DIR.parent)], cwd=REPO_ROOT)
     subprocess.check_call(
-        ["lake", "exe", "usersguide", "--output", "_out/usersguide",
-         "--without-tex", "--without-html-single", "--with-html-multi"],
+        [
+            "lake",
+            "exe",
+            "usersguide",
+            "--output",
+            "_out/usersguide",
+            "--without-tex",
+            "--without-html-single",
+            "--with-html-multi",
+        ],
         cwd=REPO_ROOT,
     )
     assert SITE_DIR.exists(), f"Manual build did not produce {SITE_DIR}"
@@ -202,13 +210,19 @@ def test_theme_switching_persists(page, server):
     chosen = single.locator("option").nth(1).get_attribute("value")
     single.select_option(value=chosen)
     # The data attribute should reflect the choice immediately.
-    assert page.evaluate("document.documentElement.getAttribute('data-verso-theme')") == chosen
+    assert (
+        page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
+        == chosen
+    )
     # localStorage persists it.
     assert page.evaluate("localStorage.getItem('verso-theme-single')") == chosen
     # Reload: the no-flash script reads localStorage and applies the same theme before paint.
     page.goto(server + "/")
     page.wait_for_load_state("domcontentloaded")
-    assert page.evaluate("document.documentElement.getAttribute('data-verso-theme')") == chosen
+    assert (
+        page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
+        == chosen
+    )
 
 
 def test_match_system_follows_media(page):
@@ -224,8 +238,12 @@ def test_match_system_follows_media(page):
     dark_id = page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
     page.emulate_media(color_scheme="light")
     page.wait_for_timeout(50)
-    light_id = page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
-    assert dark_id != light_id, "auto mode should pick different themes for light vs dark"
+    light_id = page.evaluate(
+        "document.documentElement.getAttribute('data-verso-theme')"
+    )
+    assert dark_id != light_id, (
+        "auto mode should pick different themes for light vs dark"
+    )
 
 
 def test_single_mode_ignores_media(page):
@@ -241,10 +259,16 @@ def test_single_mode_ignores_media(page):
     # Emulating a media change must not override the chosen theme.
     page.emulate_media(color_scheme="dark")
     page.wait_for_timeout(50)
-    assert page.evaluate("document.documentElement.getAttribute('data-verso-theme')") == chosen
+    assert (
+        page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
+        == chosen
+    )
     page.emulate_media(color_scheme="light")
     page.wait_for_timeout(50)
-    assert page.evaluate("document.documentElement.getAttribute('data-verso-theme')") == chosen
+    assert (
+        page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
+        == chosen
+    )
 
 
 def test_auto_commit_applies_dropdown_value(page):
@@ -434,9 +458,7 @@ def test_themes_are_alphabetized(page):
         if not ensure_auto and mode.is_checked():
             mode.uncheck()
         texts = page.locator(f"{sel_id} option").all_text_contents()
-        assert texts == sorted(texts), (
-            f"{sel_id} options not alphabetised: {texts}"
-        )
+        assert texts == sorted(texts), f"{sel_id} options not alphabetised: {texts}"
 
 
 def test_match_system_toggle_hides_rows(page):
@@ -475,7 +497,10 @@ def test_outside_click_dismisses_popover(page):
     page.wait_for_function(
         "document.getElementById('theme-picker-button').getAttribute('aria-expanded') === 'false'"
     )
-    assert page.evaluate("document.documentElement.getAttribute('data-verso-theme')") == initial
+    assert (
+        page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
+        == initial
+    )
 
 
 def test_gear_toggle_close_dismisses_popover(page):
@@ -488,7 +513,10 @@ def test_gear_toggle_close_dismisses_popover(page):
     page.wait_for_function(
         "document.getElementById('theme-picker-button').getAttribute('aria-expanded') === 'false'"
     )
-    assert page.evaluate("document.documentElement.getAttribute('data-verso-theme')") == initial
+    assert (
+        page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
+        == initial
+    )
 
 
 def test_localStorage_disabled_still_loads(page, server):
@@ -503,6 +531,10 @@ def test_localStorage_disabled_still_loads(page, server):
     page.goto(server + "/")
     page.wait_for_load_state("domcontentloaded")
     theme = page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
-    appearance = page.evaluate("document.documentElement.getAttribute('data-verso-appearance')")
-    assert theme is not None and theme != "", "data-verso-theme should be set even without storage"
+    appearance = page.evaluate(
+        "document.documentElement.getAttribute('data-verso-appearance')"
+    )
+    assert theme is not None and theme != "", (
+        "data-verso-theme should be set even without storage"
+    )
     assert appearance in ("light", "dark"), f"unexpected appearance {appearance!r}"

From 36279e426c4e1306bb5d54c30d3b70ed2a1670d6 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Mon, 1 Jun 2026 07:33:21 +0200
Subject: [PATCH 11/31] cleanup

---
 src/tests/TestMain.lean                       |   3 +-
 src/tests/Tests/TexUtil.lean                  |   2 +-
 src/verso-manual/VersoManual.lean             | 145 +++++++++---------
 src/verso-manual/VersoManual/Basic.lean       |  34 +++-
 .../VersoManual/Bibliography.lean             |   6 +-
 src/verso-manual/VersoManual/InlineLean.lean  |   2 +-
 .../VersoManual/InlineLean/Block.lean         |   2 +-
 src/verso-manual/VersoManual/Table.lean       |   2 +-
 src/verso-manual/VersoManual/Theme.lean       | 102 ++++++------
 src/verso-manual/VersoManual/Theme/Emit.lean  |  16 +-
 src/verso-tutorial/VersoTutorial.lean         |   6 +-
 src/verso/Verso/Theme/Code.lean               |  12 +-
 src/verso/Verso/Theme/Color/Syntax.lean       |   6 +-
 13 files changed, 190 insertions(+), 148 deletions(-)

diff --git a/src/tests/TestMain.lean b/src/tests/TestMain.lean
index 9557c17e7..2827698ba 100644
--- a/src/tests/TestMain.lean
+++ b/src/tests/TestMain.lean
@@ -57,7 +57,8 @@ def testTexOutput
   let runTest : IO Unit  :=
     open Verso Genre Manual in do
     let logger ← Verso.Logger.new
-    emitTeX ({ versoConfig with : RenderConfig }) doc.toPart |>.run extension_impls% |>.run logger
+    emitTeX ({ versoConfig with : RenderConfig }) doc.toPart
+      |>.run ({} : Verso.Theme.ThemeRegistry) |>.run extension_impls% |>.run logger
 
   Verso.Integration.runTests { config with
     testDir := "src/tests/integration" / dir,
diff --git a/src/tests/Tests/TexUtil.lean b/src/tests/Tests/TexUtil.lean
index 43e0a1570..5b74efa45 100644
--- a/src/tests/Tests/TexUtil.lean
+++ b/src/tests/Tests/TexUtil.lean
@@ -39,4 +39,4 @@ def toTex (block : Doc.Block Genre.Manual) : IO Output.TeX := do
   -- Convert the block to TeX
   block.toTeX
     |>.run ⟨options, traverseContext, traverseState, {}⟩
-    |>.run' {} |>.run extension_impls |>.run logger
+    |>.run' {} |>.run ({} : Theme.ThemeRegistry) |>.run extension_impls |>.run logger
diff --git a/src/verso-manual/VersoManual.lean b/src/verso-manual/VersoManual.lean
index 8b27a1590..9b514f7a0 100644
--- a/src/verso-manual/VersoManual.lean
+++ b/src/verso-manual/VersoManual.lean
@@ -66,6 +66,7 @@ open Verso.Code (LinkTargets)
 open Verso.Code.Hover (Dedup State)
 open Verso.ArgParse
 open Verso (Logger Severity withLogger BuildLogT)
+open Verso.Theme (ThemeRegistry)
 
 namespace Verso.Genre
 
@@ -275,26 +276,28 @@ structure Config extends HtmlConfig, TeXConfig, OutputConfig where
   warnPerThemeAccessibility : Bool := true
 deriving ToJson, FromJson
 
+open Lean in
+open Verso.Theme in
 structure RenderConfig extends Config where
   /--
   How to insert links in rendered code
   -/
   linkTargets : TraverseState → Multi.AllRemotes → LinkTargets Manual.TraverseContext := (·.localTargets ++ ·.remoteTargets)
   /--
-  The subset of registered manual themes that should be available in the picker. When
-  `none` (the default), every registered theme is available.
+  The manual themes that should be available in the picker. When `none` (the default), every
+  theme registered with `@[manual_theme]` is available.
   -/
-  availableThemes : Option (Array Lean.Name) := none
+  availableThemes : Option NameSet := none
   /--
   The default light-appearance theme. Its registration name must be a registered
   `Verso.Theme.ManualTheme` whose appearance is `.light`.
   -/
-  defaultLightTheme : Lean.Name := ``Verso.Theme.ManualTheme.ink
+  defaultLightTheme : Name := ``Verso.Theme.ManualTheme.ink
   /--
   The default dark-appearance theme. Its registration name must be a registered
   `Verso.Theme.ManualTheme` whose appearance is `.dark`.
   -/
-  defaultDarkTheme : Lean.Name := ``Verso.Theme.ManualTheme.argent
+  defaultDarkTheme : Name := ``Verso.Theme.ManualTheme.argent
   /--
   The default for readers who do not follow the system appearance (the "single" picker mode):
   choose `.light` so single-mode falls back to
@@ -307,15 +310,7 @@ structure RenderConfig extends Config where
   single-mode fallback (and what the picker marks as ` (default)` in the single-mode
   dropdown).
   -/
-  defaultSingleAppearance : Verso.Theme.Appearance := .light
-  /--
-  The materialized set of themes available to the picker. `manualMain` populates
-  this from `manualThemes%` filtered by
-  `availableThemes`; the
-  emit functions read it. Stored as an array so it can be threaded through the read-only
-  configuration without an extra reader layer.
-  -/
-  themeRegistry : Array (Lean.Name × Verso.Theme.ManualTheme) := #[]
+  defaultSingleAppearance : Appearance := .light
 
 namespace Config
 
@@ -387,10 +382,6 @@ def TraverseState.ofConfig (config : HtmlConfig) : TraverseState := Id.run do
       st := st.addLicenseInfo li
   return st
 
-/--
-The monad in which manuals are converted to an output format.
--/
-abbrev EmitM : Type → Type := ReaderT ExtensionImpls (BuildLogT IO)
 
 def traverse (text : Part Manual) (config : Config) : EmitM (Part Manual × TraverseState) := do
   let topCtxt : Manual.TraverseContext := { draft := config.draft }
@@ -457,20 +448,20 @@ def defaultSingleName (config : RenderConfig) : Lean.Name :=
   | .dark => config.defaultDarkTheme
 
 /--
-The single-default `Verso.Theme.ManualTheme` resolved from `themeRegistry`. This is the
-theme that drives `verso-themes.css`'s unscoped `:root` block — what the server-rendered
-HTML paints on first visit (before the no-flash script attaches a `data-verso-theme`) — and
-the TeX code styling.
+The single-default `Verso.Theme.ManualTheme` resolved from the active
+{Lean.Doc.name}`Verso.Theme.ThemeRegistry`. This is the theme that drives
+`verso-themes.css`'s unscoped `:root` block — what the server-rendered HTML paints on first
+visit (before the no-flash script attaches a `data-verso-theme`) — and the TeX code styling.
 
 Falls back to a bare default `ManualTheme.ink` if neither the resolved single-default name
 nor either configured default appears in the registry (a defensive case; the validation pass
 in `manualMain` rejects unregistered defaults before this is called).
 -/
-def singleDefaultTheme (config : RenderConfig) : Verso.Theme.ManualTheme :=
-  let find (n : Lean.Name) : Option Verso.Theme.ManualTheme :=
-    config.themeRegistry.findSome? (fun (m, t) => if m == n then some t else none)
-  (find (defaultSingleName config) <|> find config.defaultLightTheme
-    <|> find config.defaultDarkTheme).getD Verso.Theme.ManualTheme.ink
+def singleDefaultTheme (registry : ThemeRegistry) (config : RenderConfig) :
+    Verso.Theme.ManualTheme :=
+  (registry.find? (defaultSingleName config)
+    <|> registry.find? config.defaultLightTheme
+    <|> registry.find? config.defaultDarkTheme).getD Verso.Theme.ManualTheme.ink
 
 open IO.FS in
 /--
@@ -479,10 +470,10 @@ picker `.js`/`.css`, the `window.versoThemes` data file, every theme's font byte
 assets. Content-addressed font filenames in the theme registry ensure that two themes sharing the
 same font end up with one byte payload on disk.
 -/
-def writeThemeAssets (dir : System.FilePath) (config : RenderConfig) : IO Unit := do
+def writeThemeAssets (dir : System.FilePath) (config : RenderConfig) : EmitM Unit := do
+  let themes ← readThe ThemeRegistry
   ensureDir (dir / "-verso-data")
-  let themes := config.themeRegistry
-  let single := singleDefaultTheme config
+  let single := singleDefaultTheme themes config
   -- verso-themes.css
   withFile (dir / "verso-themes.css") .write fun h => do
     h.putStrLn (Verso.Theme.«verso-themes.css» single themes
@@ -514,6 +505,7 @@ def writeThemeAssets (dir : System.FilePath) (config : RenderConfig) : IO Unit :
 
 open IO.FS in
 def emitTeX (config : RenderConfig) (text : Part Manual) : EmitM Unit := do
+  let registry ← readThe ThemeRegistry
   let (text, state) ← traverse text config.toConfig
   let opts : TeX.Options Manual := {
     headerLevels := #["chapter", "section", "subsection", "subsubsection", "paragraph"],
@@ -536,7 +528,7 @@ def emitTeX (config : RenderConfig) (text : Part Manual) : EmitM Unit := do
   withFile (dir.join "main.tex") .write fun h => do
     if config.verbose then
       IO.println s!"Saving {dir.join "main.tex"}"
-    h.putStrLn (preamble text.titleString authors date packages.toList preambleItems.toList (singleDefaultTheme config).toCodeTheme)
+    h.putStrLn (preamble text.titleString authors date packages.toList preambleItems.toList (singleDefaultTheme registry config).toCodeTheme)
     -- \frontmatter is inserted by our hardcoded preamble before the ToC, so it doesn't get inserted
     -- here. If there's any text at the start of the front matter, then we need to clear it to a new
     -- recto page after the ToC
@@ -861,7 +853,8 @@ def emitHtmlSingle
     emitSearchBox (dir / "-verso-search") state.quickJump config.searchPriorities (searchPagePath := some "search/")
     emitSearchIndex (dir / "-verso-search") state { draft := config.draft } text
 where
-  emitContent (dir : System.FilePath) : StateT (State Html) (ReaderT AllRemotes (ReaderT ExtensionImpls (BuildLogT IO))) Unit := do
+  emitContent (dir : System.FilePath) : StateT (State Html) (ReaderT AllRemotes EmitM) Unit := do
+    let registry ← readThe ThemeRegistry
     let authors := text.metadata.map (·.authors) |>.getD []
     let authorshipNote := text.metadata.bind (·.authorshipNote)
     let _date := text.metadata.bind (·.date) |>.getD "" -- TODO
@@ -924,10 +917,10 @@ where
       h.putStrLn Html.doctype
       -- Offer the picker only when the reader has a real choice. A registry with one entry
       -- (or none) means the unscoped `:root` block already paints the only available theme.
-      let showThemePicker := config.themeRegistry.size > 1
+      let showThemePicker := registry.size > 1
       let themeInitScript :=
         if showThemePicker then
-          Verso.Theme.themeInitScript config.themeRegistry
+          Verso.Theme.themeInitScript registry
             config.defaultLightTheme config.defaultDarkTheme (defaultSingleName config)
         else ""
       h.putStrLn <| Html.asString <| relativizeLinks <|
@@ -965,7 +958,7 @@ where
   Emits the data used by all pages in the site, such as JS and CSS, and then emits the root page
   (and thus its children).
   -/
-  emitContent (root : System.FilePath) : StateT (State Html) (ReaderT AllRemotes (ReaderT ExtensionImpls (BuildLogT IO))) Unit := do
+  emitContent (root : System.FilePath) : StateT (State Html) (ReaderT AllRemotes EmitM) Unit := do
     let authors := text.metadata.map (·.authors) |>.getD []
     let authorshipNote := text.metadata >>= (·.authorshipNote)
     let _date := text.metadata.bind (·.date) |>.getD "" -- TODO
@@ -1001,7 +994,8 @@ where
   -/
   emitPart (bookTitle : Html) (authors : List String) (authorshipNote : Option String) (bookContents)
       (opts ctxt state definitionIds linkTargets codeOptions)
-      (root : Bool) (depth : Nat) (dir : System.FilePath) (part : Part Manual) : StateT (State Html) (ReaderT AllRemotes (ReaderT ExtensionImpls (BuildLogT IO))) Unit := do
+      (root : Bool) (depth : Nat) (dir : System.FilePath) (part : Part Manual) : StateT (State Html) (ReaderT AllRemotes EmitM) Unit := do
+    let registry ← readThe ThemeRegistry
     let thisFile := part.metadata.bind (·.file) |>.getD (part.titleString.sluggify.toString)
     let dir := if root then dir else dir.join thisFile
     let sectionNum := sectionHtml ctxt
@@ -1054,10 +1048,10 @@ where
       h.putStrLn Html.doctype
       -- Offer the picker only when the reader has a real choice. A registry with one entry
       -- (or none) means the unscoped `:root` block already paints the only available theme.
-      let showThemePicker := config.themeRegistry.size > 1
+      let showThemePicker := registry.size > 1
       let themeInitScript :=
         if showThemePicker then
-          Verso.Theme.themeInitScript config.themeRegistry
+          Verso.Theme.themeInitScript registry
             config.defaultLightTheme config.defaultDarkTheme (defaultSingleName config)
         else ""
       h.putStrLn <| Html.asString <| relativizeLinks <|
@@ -1187,12 +1181,13 @@ where
   A theme counts as "accessible" iff its
   `Verso.Theme.ManualTheme.checkAccessibility` returns no issues.
   -/
-  runThemeAccessibilityCheck (cfg : RenderConfig) : ReaderT ExtensionImpls (BuildLogT IO) Unit := do
+  runThemeAccessibilityCheck (cfg : RenderConfig) (registry : ThemeRegistry) :
+      ReaderT ExtensionImpls (BuildLogT IO) Unit := do
     let issuesOf (t : Verso.Theme.ManualTheme) := t.checkAccessibility
     let isAccessible (t : Verso.Theme.ManualTheme) : Bool := (issuesOf t).isEmpty
     -- Per-theme advisory.
     if cfg.warnPerThemeAccessibility then
-      for (n, t) in cfg.themeRegistry do
+      for (n, t) in registry do
         for issue in issuesOf t do
           let colors := issue.offending.toList.map Verso.Theme.Color.css |> ", ".intercalate
           let suffix := if colors.isEmpty then "" else s!" ({colors})"
@@ -1200,12 +1195,12 @@ where
     -- Coverage.
     let routeCoverage (msg : String) : ReaderT ExtensionImpls (BuildLogT IO) Unit :=
       if cfg.strictThemeCoverage then Verso.reportError msg else Verso.reportWarning msg
-    let accessible := cfg.themeRegistry.filter (fun (_, t) => isAccessible t)
+    let accessible := registry.filter (fun _ t => isAccessible t)
     if accessible.isEmpty then
       routeCoverage "no registered theme is accessible; readers cannot pick a usable theme"
-    else if cfg.themeRegistry.size > 1 then
-      let anyLight := accessible.any (fun (_, t) => t.appearance == Verso.Theme.Appearance.light)
-      let anyDark := accessible.any (fun (_, t) => t.appearance == Verso.Theme.Appearance.dark)
+    else if registry.size > 1 then
+      let anyLight := accessible.any (fun _ t => t.appearance == Verso.Theme.Appearance.light)
+      let anyDark := accessible.any (fun _ t => t.appearance == Verso.Theme.Appearance.dark)
       unless anyLight do
         routeCoverage "no registered light theme is accessible; readers on a light system cannot pick a usable theme"
       unless anyDark do
@@ -1215,7 +1210,7 @@ where
       if cfg.strictDefaultThemeAccessibility then Verso.reportError msg else Verso.reportWarning msg
     let checkDefault (slot : String) (name : Lean.Name) :
         ReaderT ExtensionImpls (BuildLogT IO) Unit := do
-      match cfg.themeRegistry.findSome? (fun (n, t) => if n == name then some t else none) with
+      match registry.find? name with
       | none => pure ()  -- already reported by validate
       | some t =>
         let issues := issuesOf t
@@ -1225,15 +1220,14 @@ where
     checkDefault "defaultDarkTheme" cfg.defaultDarkTheme
 
   /--
-  Builds the materialized theme registry for the build from the registered
+  Builds the active {Lean.Doc.name}`Verso.Theme.ThemeRegistry` from the registered
   `Verso.Theme.ManualTheme` table, filters it by the configured
-  `availableThemes`,
-  routes every `Verso.Theme.ManualThemeTable.ValidationError` through
-  `MonadBuildLog` as an error, and returns the populated config.
+  `availableThemes`, and routes every
+  `Verso.Theme.ManualThemeTable.ValidationError` through `MonadBuildLog` as an error.
   -/
   resolveThemeRegistry (cfg : RenderConfig)
       (table : Verso.Theme.ManualThemeTable) :
-      ReaderT ExtensionImpls (BuildLogT IO) RenderConfig := do
+      ReaderT ExtensionImpls (BuildLogT IO) ThemeRegistry := do
     for e in table.validate cfg.defaultLightTheme cfg.defaultDarkTheme cfg.availableThemes do
       Verso.reportError e.format
     -- `availableThemes` semantics:
@@ -1243,33 +1237,36 @@ where
     --                   contains the resolved default for each appearance.
     -- The result always contains at least `defaultLightTheme` and `defaultDarkTheme` if those
     -- are registered, so `singleDefaultTheme` can always resolve.
-    let expanded :=
-      match cfg.availableThemes with
-      | none => table.themes.foldl (init := #[]) (fun acc n t => acc.push (n, t))
-      | some xs =>
-        let withDefaults := xs
-          |>.append (if xs.contains cfg.defaultLightTheme then #[] else #[cfg.defaultLightTheme])
-          |>.append (if xs.contains cfg.defaultDarkTheme then #[] else #[cfg.defaultDarkTheme])
-        withDefaults.filterMap (fun n => (table.find? n).map (fun t => (n, t)))
-    return { cfg with themeRegistry := expanded }
+    match cfg.availableThemes with
+    | none => return table.themes
+    | some xs =>
+      let withDefaults := xs
+        |>.append (if xs.contains cfg.defaultLightTheme then {} else {cfg.defaultLightTheme})
+        |>.append (if xs.contains cfg.defaultDarkTheme then {} else {cfg.defaultDarkTheme})
+      return withDefaults.foldl (init := ({} : ThemeRegistry)) fun acc n =>
+        match table.find? n with
+        | some t => acc.insert n t
+        | none => acc
 
   go (extensionImpls : ExtensionImpls) (manualThemes : Verso.Theme.ManualThemeTable) : IO UInt32 := do
-    let baseCfg ← opts config options
+    let cfg ← opts config options
     runWithLogger <| flip ReaderT.run extensionImpls do
-      let cfg ← resolveThemeRegistry baseCfg manualThemes
-      runThemeAccessibilityCheck cfg
-      if cfg.emitTeX then
-        if cfg.verbose then
-          IO.println s!"Saving TeX"
-        emitTeX cfg text
-
-      emitHtml cfg.emitHtmlSingle .single cfg text traverseHtmlSingle emitHtmlSingle
-      emitHtml cfg.emitHtmlMulti .multi cfg text traverseHtmlMulti emitHtmlMulti
-
-      if let some wcFile := cfg.wordCount then
-        if cfg.verbose then
-          IO.println s!"Saving word counts to {wcFile}"
-        wordCount wcFile cfg.toConfig text
+      let registry ← resolveThemeRegistry cfg manualThemes
+      runThemeAccessibilityCheck cfg registry
+      let body : EmitM Unit := do
+        if cfg.emitTeX then
+          if cfg.verbose then
+            IO.println s!"Saving TeX"
+          emitTeX cfg text
+
+        emitHtml cfg.emitHtmlSingle .single cfg text traverseHtmlSingle emitHtmlSingle
+        emitHtml cfg.emitHtmlMulti .multi cfg text traverseHtmlMulti emitHtmlMulti
+
+        if let some wcFile := cfg.wordCount then
+          if cfg.verbose then
+            IO.println s!"Saving word counts to {wcFile}"
+          wordCount wcFile cfg.toConfig text
+      body.run registry
 
   emitHtml
       (how : EmitHtml) (mode : Mode) (cfg : RenderConfig) (text : Part Manual)
diff --git a/src/verso-manual/VersoManual/Basic.lean b/src/verso-manual/VersoManual/Basic.lean
index cb31d5f40..098704edd 100644
--- a/src/verso-manual/VersoManual/Basic.lean
+++ b/src/verso-manual/VersoManual/Basic.lean
@@ -20,6 +20,7 @@ public import VersoSearch.DomainSearch
 import VersoManual.LicenseInfo
 import VersoManual.Html.Config
 public import VersoManual.Html.Features
+public import VersoManual.Theme
 public meta import VersoManual.Ext
 import Verso.Output.Html
 public import Verso.Output.TeX
@@ -677,6 +678,27 @@ structure ExtensionImpls where
 
 end Manual
 
+/--
+The monad in which TeX descriptor implementations (`BlockDescr.toTeX`,
+`InlineDescr.toTeX`) and the TeX emit pipeline run. Reads the resolved
+`Verso.Theme.ThemeRegistry`, the extension implementations table, and logs through the build
+log.
+
+Defined here (rather than in `VersoManual.lean`) so descriptor type signatures can name it
+without forward references. {name}`Verso.Genre.Manual.EmitM` is an alias to this from
+`VersoManual.lean`.
+-/
+public abbrev Manual.EmitM : Type → Type :=
+  ReaderT Verso.Theme.ThemeRegistry (ReaderT Manual.ExtensionImpls (BuildLogT IO))
+
+/--
+The monad in which HTML descriptor implementations (`BlockDescr.toHtml`,
+`InlineDescr.toHtml`) run. Same as {name}`Manual.EmitM`, with the remote cross-reference
+table read in addition.
+-/
+public abbrev Manual.EmitHtmlM : Type → Type :=
+  ReaderT Multi.AllRemotes Manual.EmitM
+
 /-- A genre for writing reference manuals and other book-like documents. -/
 @[expose]
 def Manual : Genre where
@@ -752,7 +774,7 @@ structure InlineDescr extends HtmlAssets where
   /--
   How to generate HTML. If {name}`none`, generating HTML from a document that contains this inline will fail.
   -/
-  toHtml : Option (InlineToHtml Manual (ReaderT AllRemotes (ReaderT ExtensionImpls (BuildLogT IO))))
+  toHtml : Option (InlineToHtml Manual EmitHtmlM)
 
   /--
   Should this inline be an entry in the page-local ToC? If so, how should it be represented?
@@ -771,7 +793,7 @@ structure InlineDescr extends HtmlAssets where
   How to generate TeX. If {name}`none`, generating TeX from a document that contains this inline
   will fail.
   -/
-  toTeX : Option (InlineToTeX Manual (ReaderT ExtensionImpls (BuildLogT IO)))
+  toTeX : Option (InlineToTeX Manual EmitM)
   /-- Required TeX `\usepackage` lines -/
   usePackages : List String := {}
   /-- Required items in the TeX preamble -/
@@ -795,7 +817,7 @@ structure BlockDescr extends HtmlAssets where
   How to generate HTML. If {name}`none`, generating HTML from a document that contains this block
   will fail.
   -/
-  toHtml : Option (BlockToHtml Manual (ReaderT AllRemotes (ReaderT ExtensionImpls (BuildLogT IO))))
+  toHtml : Option (BlockToHtml Manual EmitHtmlM)
 
   /--
   Should this block be an entry in the page-local ToC? If so, how should it be represented?
@@ -815,7 +837,7 @@ structure BlockDescr extends HtmlAssets where
   How to generate TeX. If {name}`none`, generating TeX from a document that contains this block
   will fail.
   -/
-  toTeX : Option (BlockToTeX Manual (ReaderT ExtensionImpls (BuildLogT IO)))
+  toTeX : Option (BlockToTeX Manual EmitM)
   /-- Required TeX `\usepackage` lines -/
   usePackages : List String := {}
   /-- Required items in the TeX preamble -/
@@ -1505,7 +1527,7 @@ instance : Traverse Manual TraverseM where
         pure <| some <| Inline.other ⟨name, some id, data⟩ content
 
 open Verso.Output.TeX in
-instance : TeX.GenreTeX Manual (ReaderT ExtensionImpls (BuildLogT IO)) where
+instance : TeX.GenreTeX Manual EmitM where
   part go metadata txt := do
     let st ← TeX.state
     let label? := do
@@ -1567,7 +1589,7 @@ def permalink (id : InternalId) (st : TraverseState) (inline : Bool := true) : H
 
 
 open Verso.Output.Html in
-instance : Html.GenreHtml Manual (ReaderT AllRemotes (ReaderT ExtensionImpls (BuildLogT IO))) where
+instance : Html.GenreHtml Manual EmitHtmlM where
   part go «meta» txt := do
     let st ← Verso.Doc.Html.HtmlT.state
     let attrs := meta.id.map (st.htmlId) |>.getD #[]
diff --git a/src/verso-manual/VersoManual/Bibliography.lean b/src/verso-manual/VersoManual/Bibliography.lean
index 0510112e1..680129901 100644
--- a/src/verso-manual/VersoManual/Bibliography.lean
+++ b/src/verso-manual/VersoManual/Bibliography.lean
@@ -205,7 +205,7 @@ where
 
 open Verso.Doc.TeX in
 open Verso.Output.TeX in
-def Citable.bibTeX (go : Doc.Inline Genre.Manual → TeXT Manual (ReaderT ExtensionImpls (BuildLogT IO)) TeX) (c : Citable) : TeXT Manual (ReaderT ExtensionImpls (BuildLogT IO)) TeX :=   wrap <$> open TeX in do
+def Citable.bibTeX (go : Doc.Inline Genre.Manual → TeXT Manual (EmitM) TeX) (c : Citable) : TeXT Manual (EmitM) TeX :=   wrap <$> open TeX in do
   match c with
   | .inProceedings p =>
     let authors ← andListTeX <$> p.authors.mapM go
@@ -288,10 +288,10 @@ where
 
 open Verso.Doc.TeX in
 def Citable.inlineTeX
-    (go : Doc.Inline Genre.Manual → TeXT Manual (ReaderT ExtensionImpls (BuildLogT IO)) Output.TeX)
+    (go : Doc.Inline Genre.Manual → TeXT Manual (EmitM) Output.TeX)
     (ps : List Citable)
     (fmt : Style) :
-    TeXT Manual (ReaderT ExtensionImpls (BuildLogT IO)) TeX := open TeX in do
+    TeXT Manual (EmitM) TeX := open TeX in do
   match fmt with
   | .textual =>
     let out : Array TeX ← ps.toArray.mapM fun p => do
diff --git a/src/verso-manual/VersoManual/InlineLean.lean b/src/verso-manual/VersoManual/InlineLean.lean
index 1cd245b26..a269cd4d0 100644
--- a/src/verso-manual/VersoManual/InlineLean.lean
+++ b/src/verso-manual/VersoManual/InlineLean.lean
@@ -59,7 +59,7 @@ inline_extension Inline.lean (hls : Highlighted) via withHighlighting where
         reportError <| "Couldn't deserialize Lean code while rendering inline HTML: " ++ err
         pure .empty
       | .ok (hl : Highlighted) =>
-        hl.toTeX (g := Manual) (m := ReaderT ExtensionImpls (BuildLogT IO))
+        hl.toTeX (g := Manual) (m := EmitM)
   toHtml :=
     open Verso.Output.Html in
     some <| fun _ _ data _ => do
diff --git a/src/verso-manual/VersoManual/InlineLean/Block.lean b/src/verso-manual/VersoManual/InlineLean/Block.lean
index 013d29f5a..dbd64f88f 100644
--- a/src/verso-manual/VersoManual/InlineLean/Block.lean
+++ b/src/verso-manual/VersoManual/InlineLean/Block.lean
@@ -47,7 +47,7 @@ block_extension Block.lean
         reportError <| "Couldn't deserialize Lean code block while rendering TeX: " ++ err
         pure .empty
       | .ok (hl : Highlighted) =>
-        hl.toTeX (g := Manual) (m := ReaderT ExtensionImpls (BuildLogT IO))
+        hl.toTeX (g := Manual) (m := EmitM)
   toHtml :=
     open Verso.Output.Html in
     some <| fun _ _ _ data _ => do
diff --git a/src/verso-manual/VersoManual/Table.lean b/src/verso-manual/VersoManual/Table.lean
index 4d082f0a3..2f8628a20 100644
--- a/src/verso-manual/VersoManual/Table.lean
+++ b/src/verso-manual/VersoManual/Table.lean
@@ -76,7 +76,7 @@ block_extension Block.table (columns : Nat) (header : Bool) (tag : Option String
           rows := rows.push (items.take columns |>.map (·.contents))
           items := items.extract columns items.size
 
-        let rowsOut : TeX.TeXT Manual (ReaderT ExtensionImpls (BuildLogT IO)) (Array Output.TeX) := do
+        let rowsOut : TeX.TeXT Manual (EmitM) (Array Output.TeX) := do
           rows.mapIdxM fun i r => do
             let cols ← r.mapM fun c => do
               let cell : Output.TeX ← Array.mapM goB c
diff --git a/src/verso-manual/VersoManual/Theme.lean b/src/verso-manual/VersoManual/Theme.lean
index 68764f361..4fb03ccc4 100644
--- a/src/verso-manual/VersoManual/Theme.lean
+++ b/src/verso-manual/VersoManual/Theme.lean
@@ -19,14 +19,16 @@ needs. The manual genre emits every {lit}`--verso-*` chrome variable from a sing
 theme.
 -/
 
+open Lean (Name)
+
 namespace Verso.Theme
 
 /--
-A manual-genre theme: a {Lean.Doc.name}`Verso.Theme.CodeTheme` plus the color and font fields the
+A manual-genre theme: a {name}`Verso.Theme.CodeTheme` plus the color and font fields the
 chrome needs (header background, ToC, burger menu, search box, content links). Defaults reproduce
 today's chrome.
 
-The cascade rule from {Lean.Doc.name}`Verso.Theme.CodeTheme` continues: a field that today reads
+The cascade rule from {name}`Verso.Theme.CodeTheme` continues: a field that today reads
 the page background or text color defaults from the inherited field, so overriding the inherited
 field carries through.
 -/
@@ -43,8 +45,10 @@ public structure ManualTheme extends CodeTheme where
   /-- The ToC background. -/
   tocBackground : Color := color%#fafafa
 
-  /-- The default border color for chrome elements such as the search box outline. Defaults to
-  a slate gray that clears WCAG 1.4.11 (3:1) against both white and the surface color. -/
+  /--
+  The default border color for chrome elements such as the search box outline. Defaults to
+  a slate gray that clears WCAG 1.4.11 (3:1) against both white and the surface color.
+  -/
   borderColor : Color := color%#878787
   /-- The default muted text color for chrome elements such as search hints. -/
   mutedColor : Color := color%#777777
@@ -73,7 +77,7 @@ public structure ManualTheme extends CodeTheme where
 public section
 
 /--
-Attribute that registers a {Lean.Doc.name}`ManualTheme` declaration as an available theme. The
+Attribute that registers a {name}`ManualTheme` declaration as an available theme. The
 declaration must be in the current module (not imported), and its registration name is the decl's
 name with macro scopes erased.
 -/
@@ -96,9 +100,9 @@ meta initialize
 end section
 
 /--
-A materialized table of registered {Lean.Doc.name}`ManualTheme` values, keyed by registration
+A materialized table of registered {name}`ManualTheme` values, keyed by registration
 name. Built at runtime by the {lit}`manual_themes%` term elaborator from the set of
-{Lean.Doc.name}`ManualTheme` declarations tagged with the {lit}`@[manual_theme]` attribute.
+{name}`ManualTheme` declarations tagged with the {lit}`@[manual_theme]` attribute.
 -/
 public structure ManualThemeTable where
   /-- The map from a theme's registration name to its value. -/
@@ -112,19 +116,31 @@ public def empty : ManualThemeTable := {}
 public instance : EmptyCollection ManualThemeTable := ⟨empty⟩
 
 /-- Looks up a theme by its registration name. -/
-public def find? (t : ManualThemeTable) (n : Lean.Name) : Option ManualTheme :=
+public def find? (t : ManualThemeTable) (n : Name) : Option ManualTheme :=
   t.themes.find? n
 
 /-- Inserts a theme under the given registration name. -/
-public def insert (t : ManualThemeTable) (n : Lean.Name) (theme : ManualTheme) : ManualThemeTable :=
+public def insert (t : ManualThemeTable) (n : Name) (theme : ManualTheme) : ManualThemeTable :=
   ⟨t.themes.insert n theme⟩
 
 /-- Builds a table from a list of pairs. -/
-public def fromList (xs : List (Lean.Name × ManualTheme)) : ManualThemeTable :=
-  xs.foldl (fun (acc : ManualThemeTable) (p : Lean.Name × ManualTheme) => acc.insert p.1 p.2) empty
+public def fromList (xs : List (Name × ManualTheme)) : ManualThemeTable :=
+  xs.foldl (fun (acc : ManualThemeTable) (p : Name × ManualTheme) => acc.insert p.1 p.2) empty
 
 end ManualThemeTable
 
+/--
+The active set of themes resolved for a build: the registered table filtered by the
+manual genre's {lit}`availableThemes` config, with the configured defaults auto-included.
+Flows through the emit pipeline via a {lean}`ReaderT` layer in the manual genre's
+{lit}`EmitM` rather than as a config field, since it is build-time state not user-authored
+configuration.
+
+Modeled as a {lean}`Lean.NameMap` so lookups are O(log n) and iteration is in stable name
+order across builds.
+-/
+public abbrev ThemeRegistry : Type := Lean.NameMap ManualTheme
+
 public section
 
 /-- Term elaborator that materializes the registered manual-theme table at compile time. -/
@@ -137,9 +153,11 @@ private meta def manualThemePair [Monad m] [MonadRef m] [MonadQuotation m] (n :
   `(($quoted, $(⟨ident⟩)))
 
 open Lean Elab Term in
-/-- Elaborator for the {lit}`manual_themes%` macro: emits a
-{Lean.Doc.name}`Verso.Theme.ManualThemeTable` literal whose entries are every registered
-{Lean.Doc.name}`Verso.Theme.ManualTheme` decl. -/
+/--
+Elaborator for the {lit}`manual_themes%` macro: emits a
+{name}`Verso.Theme.ManualThemeTable` literal whose entries are every registered
+{name}`Verso.Theme.ManualTheme` decl.
+-/
 @[term_elab manual_themes]
 meta def elabManualThemes : TermElab := fun _stx expected? => do
   let env ← getEnv
@@ -165,9 +183,9 @@ private def colorDecl (name : String) (c : Color) : String :=
   cssDecl name (Color.css c)
 
 /--
-The CSS-variable body for the manual-chrome fields a {Lean.Doc.name}`ManualTheme` adds on top of
-its inherited {Lean.Doc.name}`Verso.Theme.CodeTheme`. The manual genre concatenates this with
-{Lean.Doc.name}`Verso.Theme.CodeTheme.cssVariables` to produce the contents of its
+The CSS-variable body for the manual-chrome fields a {name}`ManualTheme` adds on top of
+its inherited {name}`Verso.Theme.CodeTheme`. The manual genre concatenates this with
+{name}`Verso.Theme.CodeTheme.cssVariables` to produce the contents of its
 {lit}`:root` block.
 -/
 public def manualCssVariables (theme : ManualTheme) : String :=
@@ -190,8 +208,8 @@ public def manualCssVariables (theme : ManualTheme) : String :=
   ]
 
 /--
-The full CSS-variable body for a {Lean.Doc.name}`ManualTheme`: the inherited
-{Lean.Doc.name}`Verso.Theme.CodeTheme` variables followed by the manual-chrome additions. This is
+The full CSS-variable body for a {name}`ManualTheme`: the inherited
+{name}`Verso.Theme.CodeTheme` variables followed by the manual-chrome additions. This is
 what the manual genre writes into the body of {lit}`verso-themes.css`'s {lit}`:root` block.
 -/
 public def cssVariables (theme : ManualTheme) : String :=
@@ -204,20 +222,15 @@ end ManualTheme
 namespace ManualTheme
 
 /--
-Runs the inherited {Lean.Doc.name}`Verso.Theme.CodeTheme.checkAccessibility` and then verifies
-the manual-chrome pairs:
-
-- content {Lean.Doc.name (full := Verso.Theme.ManualTheme.linkColor)}`linkColor` and
-  {Lean.Doc.name (full := Verso.Theme.ManualTheme.visitedLinkColor)}`visitedLinkColor` against
-  the page background
-- {Lean.Doc.name (full := Verso.Theme.ManualTheme.tocTextColor)}`tocTextColor` against the
-  {Lean.Doc.name (full := Verso.Theme.ManualTheme.tocBackground)}`tocBackground`
-- the header title color (body text) against
-  {Lean.Doc.name (full := Verso.Theme.ManualTheme.headerBackground)}`headerBackground`
+Runs the inherited {name}`Verso.Theme.CodeTheme.checkAccessibility` and then verifies the
+manual-chrome pairs:
+
+- content {name}`linkColor` and {name}`visitedLinkColor` against the page background
+- {name}`tocTextColor` against the {name}`tocBackground`
+- the header title color (body text) against {name}`headerBackground`
 - the search-box muted and border colors against the surface and page backgrounds
-- body text against the
-  {Lean.Doc.name (full := Verso.Theme.ManualTheme.highlightColor)}`highlightColor`, since search
-  results render matched terms with that color as their background
+- body text against the {name}`highlightColor`, since search results render matched terms with that
+  color as their background
 -/
 public def checkAccessibility (theme : ManualTheme) : Array Color.Issue := Id.run do
   let mut issues := theme.toCodeTheme.checkAccessibility
@@ -270,22 +283,24 @@ Reasons a theme configuration can be rejected. Each carries enough detail to poi
 the specific theme or default slot that needs attention.
 -/
 public inductive ValidationError where
-  /-- The registration `Name.toString` contains characters outside `[A-Za-z0-9._-]`, contains
-  `..`, or has no letter. -/
+  /--
+  The registration {name}`Name.toString` contains characters outside `[A-Za-z0-9._-]`, contains
+  `..`, or has no letter.
+  -/
   | unsafeName (name : Lean.Name)
-  /-- `availableThemes` named a theme that is not registered with `@[manual_theme]`. -/
+  /-- The set of avaialable themes named a theme that is not registered with {attr}`@[manual_theme]`. -/
   | unknownAvailable (name : Lean.Name)
-  /-- `defaultLightTheme` is not a registered manual theme. -/
+  /-- The default light theme is not a registered manual theme. -/
   | unknownDefaultLight (name : Lean.Name)
-  /-- `defaultDarkTheme` is not a registered manual theme. -/
+  /-- The default dark theme is not a registered manual theme. -/
   | unknownDefaultDark (name : Lean.Name)
-  /-- `defaultLightTheme` names a theme whose appearance is not `.light`. -/
+  /-- The default light theme is a dark theme. -/
   | defaultLightWrongAppearance (name : Lean.Name)
-  /-- `defaultDarkTheme` names a theme whose appearance is not `.dark`. -/
+  /-- The default dark theme is a light theme. -/
   | defaultDarkWrongAppearance (name : Lean.Name)
 deriving Inhabited, Repr
 
-/-- Renders a {Lean.Doc.name}`Verso.Theme.ManualThemeTable.ValidationError` as a build-log message. -/
+/-- Renders a {name}`ValidationError` as a build-log message. -/
 public def ValidationError.format : ValidationError → String
   | .unsafeName n =>
     s!"theme registration name '{n}' is not safe for a URL path segment; only [A-Za-z0-9._-] are allowed, '..' is rejected, and at least one letter is required"
@@ -300,13 +315,14 @@ public def ValidationError.format : ValidationError → String
   | .defaultDarkWrongAppearance n =>
     s!"defaultDarkTheme = '{n}' is registered but its appearance is not .dark"
 
+open Lean in
 /--
 Validates the configured theme set against the registered theme table. Returns the list of
 problems found (empty iff every check passes); the caller routes them through the build log.
 -/
 public def validate (table : ManualThemeTable)
-    (defaultLight defaultDark : Lean.Name)
-    (available : Option (Array Lean.Name)) : Array ValidationError := Id.run do
+    (defaultLight defaultDark : Name)
+    (available : Option NameSet) : Array ValidationError := Id.run do
   let mut errs := #[]
   for (n, _) in table.themes.toList do
     unless safeNameString n.toString do
@@ -324,5 +340,3 @@ public def validate (table : ManualThemeTable)
   | some t => unless t.appearance == .dark do
       errs := errs.push (.defaultDarkWrongAppearance defaultDark)
   return errs
-
-end ManualThemeTable
diff --git a/src/verso-manual/VersoManual/Theme/Emit.lean b/src/verso-manual/VersoManual/Theme/Emit.lean
index bcaa3a3b8..8aa6d8d53 100644
--- a/src/verso-manual/VersoManual/Theme/Emit.lean
+++ b/src/verso-manual/VersoManual/Theme/Emit.lean
@@ -39,10 +39,10 @@ choices and the live code preview.
 inside a `data-verso-theme`-scoped element to show what each theme will look like.
 -/
 public def windowVersoThemesJs
-    (themes : Array (Lean.Name × ManualTheme))
+    (themes : ThemeRegistry)
     (defaultLight defaultDark defaultSingle : Lean.Name)
     (codeSample : String) : String :=
-  let entries := themes.map (fun (n, t) => themeJson n t)
+  let entries := themes.foldl (init := #[]) (fun acc n t => acc.push (themeJson n t))
   let payload := Json.mkObj [
     ("themes", Json.arr entries),
     ("defaultLight", Json.str defaultLight.toString),
@@ -63,12 +63,12 @@ not follow the system appearance. First visits (no stored mode) use the same fal
 painted frame matches what the reader will see when they open the picker.
 -/
 public def themeInitScript
-    (themes : Array (Lean.Name × ManualTheme))
+    (themes : ThemeRegistry)
     (defaultLight defaultDark defaultSingle : Lean.Name) : String :=
-  let pairs := themes.toList.map fun (n, t) =>
+  let pairs := themes.foldl (init := ([] : List String)) fun acc n t =>
     let a := match t.appearance with | .light => "light" | .dark => "dark"
-    s!"\"{n.toString}\":\"{a}\""
-  let table := "{" ++ ",".intercalate pairs ++ "}"
+    s!"\"{n.toString}\":\"{a}\"" :: acc
+  let table := "{" ++ ",".intercalate pairs.reverse ++ "}"
   s!"(function() \{
   var APPEARANCE = {table};
   var DEFAULT_LIGHT = \"{defaultLight.toString}\";
@@ -129,7 +129,7 @@ page-theme asset root is needed.
 -/
 public def «verso-themes.css»
     (single : ManualTheme)
-    (themes : Array (Lean.Name × ManualTheme))
+    (themes : ThemeRegistry)
     (_defaultLight defaultDark : Lean.Name) : String := Id.run do
   let assetRoot (n : Lean.Name) : String := s!"-verso-data/themes/{n.toString}"
   let mut out := ""
@@ -140,7 +140,7 @@ public def «verso-themes.css»
   -- Unscoped :root block from the single-mode default.
   out := out ++ s!":root \{\n{single.cssVariables}}\n"
   -- @media dark fallback for no-JS visitors.
-  if let some t := themes.findSome? (fun (n, t) => if n == defaultDark then some t else none) then
+  if let some t := themes.find? defaultDark then
     out := out ++ s!"@media (prefers-color-scheme: dark) \{\n  :root \{\n{t.cssVariables}  }\n}\n"
   -- Attribute-scoped blocks for every registered theme.
   for (n, t) in themes do
diff --git a/src/verso-tutorial/VersoTutorial.lean b/src/verso-tutorial/VersoTutorial.lean
index 98b2dc070..cf1a487bf 100644
--- a/src/verso-tutorial/VersoTutorial.lean
+++ b/src/verso-tutorial/VersoTutorial.lean
@@ -262,12 +262,13 @@ partial def inlineToPage (i : Inline Tutorial) : EmitM (Inline Blog.Page) := do
   | .other .. =>
     let hoverSt ← getThe (Code.Hover.State Html)
     let (html, hoverSt) ←
-      Tutorial.toHtml (m := ReaderT AllRemotes (ReaderT ExtensionImpls (BuildLogT IO))) {}
+      Tutorial.toHtml (m := EmitHtmlM) {}
         {}
         (← readThe Manual.TraverseState)
         {} {} {} i
         |>.run hoverSt
         |>.run (← read).remoteContent
+        |>.run ({} : Theme.ThemeRegistry)
         |>.run (← readThe ExtensionImpls)
     set hoverSt
     return .other (.blob html) #[]
@@ -284,12 +285,13 @@ partial def blockToPage (b : Block Tutorial) : EmitM (Block Blog.Page) := do
   | .other .. =>
     let hoverSt ← getThe (Code.Hover.State Html)
     let (html, hoverSt) ←
-      Tutorial.toHtml (m := ReaderT AllRemotes (ReaderT ExtensionImpls (BuildLogT IO))) {}
+      Tutorial.toHtml (m := EmitHtmlM) {}
         {}
         (← readThe Manual.TraverseState)
         {} {} {} b
         |>.run hoverSt
         |>.run (← read).remoteContent
+        |>.run ({} : Theme.ThemeRegistry)
         |>.run (← readThe ExtensionImpls)
     set hoverSt
     return .other (.blob html) #[]
diff --git a/src/verso/Verso/Theme/Code.lean b/src/verso/Verso/Theme/Code.lean
index 1887d1be6..e6b797ccf 100644
--- a/src/verso/Verso/Theme/Code.lean
+++ b/src/verso/Verso/Theme/Code.lean
@@ -84,8 +84,10 @@ public structure CodeTheme where
   infoIndicatorColor : Color := color%#4777ff
   /-- The message-text color for warning diagnostics. -/
   warningColor : Color := textColor
-  /-- The accent color (left border, underline) for warning diagnostics. Defaults to a darker
-  amber than the legacy {lit}`#e7a71d` so it clears WCAG 1.4.11 (3:1) against white. -/
+  /--
+  The accent color (left border, underline) for warning diagnostics. Defaults to a darker
+  amber than the legacy {lit}`#e7a71d` so it clears WCAG 1.4.11 (3:1) against white.
+  -/
   warningIndicatorColor : Color := color%#d97706
   /-- The message-text color for error diagnostics. -/
   errorColor : Color := color%#cc0000
@@ -204,8 +206,10 @@ private meta def themePair [Monad m] [MonadRef m] [MonadQuotation m] (n : Name)
   `(($quoted, $(⟨ident⟩)))
 
 open Lean Elab Term in
-/-- Elaborator for the {lit}`code_themes%` macro: emits a {Lean.Doc.name}`Verso.Theme.CodeThemeTable`
-literal whose entries are every registered {Lean.Doc.name}`Verso.Theme.CodeTheme` decl. -/
+/--
+Elaborator for the {lit}`code_themes%` macro: emits a {Lean.Doc.name}`Verso.Theme.CodeThemeTable`
+literal whose entries are every registered {Lean.Doc.name}`Verso.Theme.CodeTheme` decl.
+-/
 @[term_elab code_themes]
 meta def elabCodeThemes : TermElab := fun _stx expected? => do
   let env ← getEnv
diff --git a/src/verso/Verso/Theme/Color/Syntax.lean b/src/verso/Verso/Theme/Color/Syntax.lean
index 3ff0f8d76..99bcd8d12 100644
--- a/src/verso/Verso/Theme/Color/Syntax.lean
+++ b/src/verso/Verso/Theme/Color/Syntax.lean
@@ -82,8 +82,10 @@ expected, including in structure-field defaults.
 syntax (name := colorLit) "color%" noWs colorHex : term
 
 open Elab Term in
-/-- Elaborates a {lit}`color%` literal to a {name (full := Verso.Theme.Color)}`Color` and attaches the
-preview widget. -/
+/--
+Elaborates a {lit}`color%` literal to a {name (full := Verso.Theme.Color)}`Color` and attaches
+the preview widget.
+-/
 @[term_elab colorLit]
 meta def elabColorLit : TermElab := fun stx expectedType? => do
   let hexStx := stx.getArg 1

From 136cf2f12e62ee81a2a2dd1e5e7984ee6e9957b4 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Mon, 1 Jun 2026 08:09:14 +0200
Subject: [PATCH 12/31] further cleanup

---
 src/verso-manual/VersoManual/Html/Style.lean  | 920 +----------------
 .../VersoManual/InlineLean/Block.lean         |   4 +-
 .../VersoManual/Theme/Assets.lean             |   4 +-
 static-web/manual/book.css                    | 940 ++++++++++++++++++
 .../{ => manual}/theme/theme-picker.css       |   0
 static-web/{ => manual}/theme/theme-picker.js |   0
 6 files changed, 950 insertions(+), 918 deletions(-)
 create mode 100644 static-web/manual/book.css
 rename static-web/{ => manual}/theme/theme-picker.css (100%)
 rename static-web/{ => manual}/theme/theme-picker.js (100%)

diff --git a/src/verso-manual/VersoManual/Html/Style.lean b/src/verso-manual/VersoManual/Html/Style.lean
index b52477c38..c863714da 100644
--- a/src/verso-manual/VersoManual/Html/Style.lean
+++ b/src/verso-manual/VersoManual/Html/Style.lean
@@ -4,918 +4,12 @@ Released under Apache 2.0 license as described in the file LICENSE.
 Author: David Thrane Christiansen
 -/
 module
+meta import Init.System.FilePath
 namespace Verso.Genre.Manual.Html.Css
 
-public def pageStyle : String := r####"
-/******** Customizability ********/
-
-:root {
-    /** Typography **/
-    /* What's the maximum line width, for legibility? */
-    --verso-content-max-width: 47rem;
-    /* Desktop font size */
-    --verso-font-size: 16px;
-    /* Mobile font size */
-    --verso-mobile-font-size: 16px;
-
-    /** Header appearance **/
-    --verso-header-height: 3rem;
-    /* Height of the displayed logo **/
-    --verso-logo-height: var(--verso-header-height);
-
-    /** Table of Contents appearance **/
-    /* How long should the ToC animation take? */
-    --verso-toc-transition-time: 0.4s;
-
-    /* How wide should the ToC be on non-mobile? */
-    --verso-toc-width: 18rem;
-
-    /** Variables that control the “burger menu” appearance **/
-    --verso-burger-height: 1.25rem;
-    --verso-burger-width: 1.25rem;
-    --verso-burger-line-width: 0.2rem;
-    --verso-burger-line-radius: 0.2rem;
-
-    /* The "burger menu" may need to get bigger for mobile screens */
-    --verso-mobile-burger-height: 1.5rem;
-    --verso-mobile-burger-width: 1.5rem;
-    --verso-mobile-burger-line-width: 0.3rem;
-    --verso-mobile-burger-line-radius: 0.3rem;
-}
-
-/******** Global parameters not intended for customization by themes ********/
-
-:root {
-    /* How much space to add on the sides of content for small screens and to place widgets. */
-    --verso--content-padding-x: 1.5rem;
-
-    /* Vertical margin for definition boxes and examples */
-    --verso--box-vertical-margin: 1.5rem;
-    --verso--box-padding: 1rem;
-}
-
-@media screen and (max-width: 700px) {
-  :root {
-    /* Reduce the standard padding on mobile */
-    --verso--content-padding-x: 1rem;
-  }
-}
-
-/******** Root font size - this is what rem is based on *********/
-
-html {
-    font-size: var(--verso-font-size);
-}
-
-@media screen and (max-width: 700px) {
-    html {
-        font-size: var(--verso-mobile-font-size);
-    }
-}
-
-/******** Reset ********/
-
-body {
-    margin: 0;
-    padding: 0;
-    background: var(--verso-background-color);
-    color: var(--verso-text-color);
-}
-
-/* Light/dark logo switching: when both images are rendered, show one based on the appearance
-   the no-flash script set on `<html>`. When only a light logo is rendered, no rule fires and it
-   is visible in both appearances by default. */
-:root[data-verso-appearance="dark"] #logo .logo-light { display: none; }
-:root[data-verso-appearance="light"] #logo .logo-dark { display: none; }
-
-/******** Theme ********/
-
-h1, h2, h3, h4, h5, h6 {
-    font-family: var(--verso-structure-font-family);
-    font-weight: bold;
-    text-rendering: optimizeLegibility;
-    margin-top: 1.5rem;
-}
-
-p, dt, dd {
-    font-family: var(--verso-text-font-family);
-    line-height: 1.45;
-}
-
-dt {
-    font-weight: bold;
-}
-
-dd > p:first-child {
-    margin-top: 0;
-}
-
-pre, code {
-    font-family: var(--verso-code-font-family);
-    font-variant-ligatures: none;
-    overflow-x: auto;
-    overflow-y: clip;
-}
-
-/******** Page Layout ********/
-
-header {
-	position: fixed;
-	top: 0;
-	z-index: 99;
-	left: 0;
-	right: 0;
-	background: var(--verso-header-background);
-	display: flex;
-	align-items: center;
-	height: var(--verso-header-height);
-	box-shadow: 0 0px 6px lightgray;
-}
-
-.header-logo-wrapper {
-    /* Make the logo always take up the same space as the toc */
-    flex-basis: var(--verso-toc-width);
-    /* Make padding be included in the width calculation */
-    box-sizing: border-box;
-    /* Add padding so it doesn't sit at the very edge of the screen. */
-    padding-left: .5rem;
-}
-
-@media screen and (max-width: 700px) {
-    .header-logo-wrapper {
-        display: none;
-    }
-}
-
-.header-title-wrapper {
-    /* The title wrapper grows to fill up the header */
-    flex: 1;
-}
-
-@media screen and (max-width: 1500px) {
-    /* Add the padding of the content when the content moves to the left */
-    padding-left: var(--verso--content-padding-x);
-}
-
-.header-title {
-    text-decoration: none;
-    color: var(--verso-text-color);
-    font-size: 2rem;
-    font-weight: bold;
-    display: block;
-    margin: 0 auto;
-    max-width: var(--verso-content-max-width);
-}
-
-@media screen and (max-width: 1500px) {
-    /* Move the title to the left, to align with the content that does the same. */
-    .header-title {
-        margin: 0;
-        max-width: unset;
-    }
-}
-
-@media screen and (max-width: 700px) {
-    /* There's no header logo on mobile, so the title just needs to reserve space for the burger */
-    .header-title {
-        margin-left: calc(var(--verso-burger-width) + 1.5rem); /* There's 0.5 rem padding on the burger, and we want some space */
-        max-width: unset;
-    }
-}
-
-.header-title h1 {
-    margin: 0;
-    font-size: inherit;
-    font-weight: inherit;
-    text-wrap: nowrap;
-}
-
-:root:has(header:empty) {
-    --verso-header-height: 0px;
-}
-
-.with-toc {
-    margin-top: var(--verso-header-height);
-}
-
-main [id] {
-  /* When jumping to something, display it below the header. We also add a little
-     whitespace, so it's easier to see that you are indeed viewing the whole item. */
-  scroll-margin-top: calc(var(--verso-header-height) + 1rem);
-}
-
-.with-toc #toc {
-    position: fixed;
-    z-index: 10;
-}
-
-/** Non-mobile **/
-.with-toc > main {
-    /* NB main > section also has padding that's added to this in practice */
-    padding-left: var(--verso-toc-width);
-}
-
-/** Mobile **/
-@media screen and (max-width: 700px) {
-    .with-toc > main {
-        padding-left: 0;
-    }
-}
-
-.with-toc #toc {
-    overflow-y: auto;
-}
-
-
-/******** Table of Contents ********/
-
-/* This backdrop should be hidden on desktop browsers, and show up when the ToC is open on mobile browsers */
-.toc-backdrop {
-    display: none;
-}
-
-@media screen and (max-width: 700px) {
-    .toc-backdrop {
-        display: block;
-    }
-    body:has(#toggle-toc:checked) .toc-backdrop {
-        position: fixed;
-        inset: 0;
-        background-color: #aaa8;
-        z-index: 9;
-    }
-    html:has(#toggle-toc:checked) {
-        overflow: hidden;
-    }
-}
-
-#toc {
-    background-color: var(--verso-toc-background-color);
-    color: var(--verso-toc-text-color);
-    display: flex;
-    flex-direction: column;
-    justify-content: space-between;
-    height: calc(100dvh - var(--verso-header-height));
-    width: var(--verso-toc-width);
-}
-
-@media screen and (max-width: 700px) {
-    #toc {
-        /* Push the toc off the page on mobile */
-        right: 100%;
-        transition: transform var(--verso-toc-transition-time) ease;
-    }
-
-    #toc:has(#toggle-toc:checked) {
-        transform: translateX(var(--verso-toc-width));
-    }
-}
-
-#toggle-toc {
-    display: none;
-}
-
-#toc a {
-    color: var(--verso-toc-text-color);
-    text-decoration: none;
-}
-
-#toc a:hover {
-    text-decoration: underline;
-    color: var(--verso-toc-text-color);
-}
-
-.toc-title {
-    /* The ToC title can be displayed when there is no room for the title in the header. */
-    display: none;
-    padding: 0 .5rem;
-}
-
-.toc-title h1 {
-    margin-bottom: 0;
-}
-
-#toc .split-tocs {
-    padding-left: 0;
-    padding-right: 0.5rem;
-    margin-top: 1.5rem;
-}
-
-#toc .split-toc.book {
-    margin-bottom: 2rem;
-}
-
-#toc .split-toc.book .title {
-    font-weight: 600;
-}
-
-#toc .split-toc {
-    margin-bottom: 1.5rem;
-    font-family: var(--verso-structure-font-family);
-}
-
-
-#toc .split-toc label.toggle-split-toc {
-}
-
-#toc .split-toc .title {
-    display: flex;
-    flex-wrap: nowrap;
-}
-
-#toc .split-toc label.toggle-split-toc input[type="checkbox"] {
-    display: inline-block;
-    position: absolute;
-    top: 0;
-    left: 0;
-    opacity: 0;
-    height: 0;
-    width: 0;
-    z-index: -10;
-}
-
-
-:root {
-    --verso-toc-triangle-width: 0.6rem;
-    --verso-toc-triangle-height: 0.6rem;
-    --verso-toc-triangle-left-space: 0.5rem;
-    --verso-toc-triangle-margin: 0.5rem;
-}
-
-#toc .split-toc label.toggle-split-toc::before {
-    width: calc(var(--verso-toc-triangle-width) + var(--verso-toc-triangle-left-space));
-    height: var(--verso-toc-triangle-height);
-    display: inline-block;
-    background-color: var(--verso-toc-text-color);
-    content: ' ';
-    transition: ease 0.2s;
-    margin-right: var(--verso-toc-triangle-margin);
-    clip-path: polygon(100% 0, var(--verso-toc-triangle-left-space) 0, calc(var(--verso-toc-triangle-left-space) + calc(calc(100% - var(--verso-toc-triangle-left-space)) / 2)) 100%);
-    transform-origin:
-        /* X axis: left spacing plus half the width to get the center*/
-        calc(var(--verso-toc-triangle-left-space) + calc(var(--verso-toc-triangle-width) / 2))
-        /* Y axis */
-        center;
-}
-
-#toc .split-toc label.toggle-split-toc:has(input[type="checkbox"]:not(:checked))::before {
-    transform: rotate(-90deg);
-}
-
-#toc .split-toc .no-toggle {
-    /* Line up triangle-less content with the triangled content */
-    width: calc(var(--verso-toc-triangle-width) + var(--verso-toc-triangle-left-space));
-    margin-right: var(--verso-toc-triangle-margin);
-    display: inline-block;
-}
-
-#toc .split-toc > :not(:first-child) {
-    max-height: 0px;
-    display: block;
-    overflow: hidden;
-    /* Line it up with the point of the disclosure triangle */
-    margin-left: calc(var(--verso-toc-triangle-left-space) + calc(var(--verso-toc-triangle-width) / 2));
-}
-
-#toc .split-toc:has(.toggle-split-toc input[type="checkbox"]:not(:checked)) > :not(:first-child) {
-    padding: 0;
-    margin: 0;
-}
-
-#toc .split-toc:has(.toggle-split-toc input[type="checkbox"]:checked) > :not(:first-child) {
-    max-height: 100%;
-}
-
-#toc .split-toc table {
-    border-left: 1px dotted;
-    padding-left: 1.2rem;
-    padding-top: 0.2rem;
-}
-
-#toc .split-toc td {
-    vertical-align: top;
-}
-
-#toc .split-toc > ol {
-    border-left: 1px dotted;
-    list-style-type: none;
-    padding-left: 0.5rem;
-    margin-left: 0;
-    margin-right: 0;
-    margin-bottom: 0.5rem;
-    margin-top: 0.5rem;
-    font-size: 0.9rem;
-}
-
-#toc .split-toc > ol > li {
-    text-indent: -1.5rem;
-    padding-left: 2.5rem;
-}
-
-#toc .split-toc > ol > li:has(.header) {
-    padding-left: 2rem;
-}
-
-#toc .split-toc .current td:not(.num), #toc .split-toc .title .current {
-    text-decoration-line: underline;
-    text-decoration-style: dotted;
-}
-
-#toc .split-toc td.num {
-    font-variant-numeric: tabular-nums;
-}
-
-/* Add a bit of visual space between numbered and unnumbered rows */
-#toc .split-toc tr:has(+ tr.unnumbered) td, #toc .split-toc tr.unnumbered:has(+ tr.numbered) td {
-  padding-bottom: 0.5rem;
-}
-
-.prev-next-buttons {
-    font-weight: bold;
-    font-family: var(--verso-structure-font-family);
-    display: flex;
-    justify-content: space-between;
-    flex-wrap: wrap;
-    max-width: var(--verso-content-max-width);
-}
-
-.prev-next-buttons > *,
-.prev-next-buttons > *:visited {
-    display: flex;
-    flex: 1;
-    justify-content: center;
-    align-items: center;
-    /* Section nav is a link in form but reads as body navigation, not a content CTA, so it
-       tracks the body text color rather than `--verso-link-color`. Both `:link` and `:visited`
-       are pinned to text color, otherwise the `main a:visited` rule below (specificity 0,1,2
-       beats `.prev-next-buttons > *` at 0,1,0) recolors visited prev/next links to the
-       visited-link colour. */
-    color: var(--verso-text-color);
-    text-decoration: none;
-}
-
-.prev-next-buttons > [rel=prev] {
-    justify-content: start;
-}
-
-.prev-next-buttons > [rel=next] {
-    justify-content: end;
-}
-
-.prev-next-buttons .local-button .where {
-    margin: 0 0.3rem;
-    /* Fix the position relative to the arrows. */
-    position: relative;
-    top: 0.1rem;
-}
-
-.prev-next-buttons .arrow {
-    font-family: var(--verso-code-font-family);
-    font-size: 150%;
-}
-
-#logo {
-    max-height: 100%;
-    display: block;
-}
-
-#logo img {
-    object-fit: contain;
-    max-height: var(--verso-logo-height);
-    display: block;
-}
-
-/******** Width-dependent layout elements ********/
-
-.narrow-only {
-    display: none;
-}
-
-@media screen and (max-width: 500px) {
-    .wide-only {
-        display: none;
-    }
-    .narrow-only {
-        display: revert;
-    }
-}
-
-@media screen and (min-width: 700px) and (max-width: 920px){
-    .wide-only {
-        display: none;
-    }
-    .narrow-only {
-        display: revert;
-    }
-}
-
-
-/******** Headerline ********/
-
-#toggle-toc-click {
-    /* Hidden on desktop */
-    display: none;
-}
-
-@media screen and (max-width: 700px) {
-    #toggle-toc-click {
-        display: inline-flex;
-        cursor: pointer;
-        /* This is the default, but it's needed to make the math work out so nice to be explicit: */
-        box-sizing: content-box;
-        width: var(--verso-burger-width);
-        height: var(--verso-burger-height);
-        flex-direction: column;
-        justify-content: space-between;
-        padding: 0.5rem;
-        position: fixed;
-        z-index: 100; /* Show on top of ToC/content */
-        /* Calculation to make it sit in the middle of the header. The .5rem is the padding added to #toggle-toc-click. */
-        top: calc((var(--verso-header-height) - var(--verso-burger-height) - 2 * .5rem) / 2);
-        filter: drop-shadow(1px 1px var(--verso-burger-toc-hidden-shadow-color)) drop-shadow(-1px -1px var(--verso-burger-toc-hidden-shadow-color));
-        transition:
-            height var(--verso-toc-transition-time) ease-in-out,
-            width var(--verso-toc-transition-time) ease-in-out;
-    }
-
-    body:has(#toggle-toc:checked) #toggle-toc-click {
-        filter: drop-shadow(1px 1px var(--verso-burger-toc-visible-shadow-color)) drop-shadow(-1px -1px var(--verso-burger-toc-visible-shadow-color));
-    }
-
-    body {
-        --verso-burger-width: var(--verso-mobile-burger-width);
-        --verso-burger-height: var(--verso-mobile-burger-height);
-        --verso-burger-line-width: var(--verso-mobile-burger-line-width);
-        --verso-burger-line-radius: var(--verso-mobile-burger-line-radius);
-    }
-}
-
-#toggle-toc-click .line {
-    display: block;
-    position: relative;
-    width: 100%;
-    height: var(--verso-burger-line-width);
-    border-radius: var(--verso-burger-line-radius);
-    background-color: var(--verso-burger-toc-hidden-color);
-    /* The background color has a transition in case a theme needs to override the line color
-       when the ToC menu is open */
-    transition:
-        background-color var(--verso-toc-transition-time) ease-in-out,
-        height var(--verso-toc-transition-time) ease-in-out,
-        width var(--verso-toc-transition-time) ease-in-out,
-        transform var(--verso-toc-transition-time) ease-in-out;
-    z-index: 15;
-}
-
-body:has(#toggle-toc:checked) #toggle-toc-click .line {
-    background-color: var(--verso-burger-toc-visible-color);
-}
-
-body:has(#toggle-toc:checked) #toggle-toc-click .line1 {
-    transform:
-        translateY(calc(calc(var(--verso-burger-height) - var(--verso-burger-line-width)) / 2))
-        rotate(45deg);
-}
-body:has(#toggle-toc:checked) #toggle-toc-click .line2 {
-    transform: scaleX(0);
-}
-body:has(#toggle-toc:checked) #toggle-toc-click .line3 {
-    transform:
-        translateY(calc(-1 * calc(calc(var(--verso-burger-height) - var(--verso-burger-line-width)) / 2)))
-        rotate(-45deg);
-}
-
-#meta-links {
-    list-style-type: none;
-    font-family: var(--verso-structure-font-family);
-    font-size: 90%;
-    display: flex;
-    justify-content: space-between;
-    padding: 0 1rem;
-}
-#meta-links li {
-    display: inline-block;
-}
-
-/******** Text ********/
-
-/*
-For words that are too long to fit on the screen, it's better to wrap than to have horizontal scrolling
-*/
-main h1, main h2, main h3, main h4, main h5, main h6 {
-  overflow-wrap: break-word;
-}
-
-main h1 {
-  font-size: 2.3rem;
-  line-height: 1.5;
-  margin-bottom: 1.3rem;
-}
-
-main h2 {
-  font-size: 1.7rem;
-  line-height: 1.5;
-  margin-bottom: 1rem;
-}
-
-main h3 {
-  font-size: 1.4rem;
-  line-height: 1.5;
-  margin-bottom: 0.2rem;
-}
-
-main h4 {
-  font-size: 1.2rem;
-  line-height: 1.25;
-  margin-bottom: 0.2rem;
-}
-
-main h5 {
-  font-size: 1rem;
-  line-height: 1.25;
-  margin-bottom: 0.2rem;
-}
-
-main h6 {
-  font-size: 1rem;
-  font-weight: 500;
-  line-height: 1.15;
-  margin-bottom: 0rem;
-}
-
-main .titlepage h1 {
-    text-align: center;
-}
-
-main .authors {
-    text-align: center;
-    font-family: var(--verso-structure-font-family);
-}
-
-main .authors {
-    text-align: center;
-    font-family: var(--verso-structure-font-family);
-}
-
-main .authors .author:only-of-type::after {
-    content: "";
-}
-
-main .authors .author:not(:last-of-type)::after {
-    content: ", ";
-}
-
-main .authors .author:nth-last-of-type(2)::after {
-    content: " and ";
-}
-
-main .authors .note {
-    margin: 0;
-    display: inline;
-    font-style: italic;
-
-}
-main .authors:has(.author) .note::before {
-  content: ", ";
-}
-
-/******** Main content ********/
-
-.content-wrapper {
-    padding: var(--verso--content-padding-x);
-    max-width: var(--verso-content-max-width);
-    margin: 0 auto;
-}
-
-@media screen and (max-width: 1500px) {
-    /* Left align the content when less than 1500px, to make room for the footnotes on the right. */
-    .content-wrapper {
-        margin: 0;
-        max-width: unset;
-    }
-}
-
-main > section {
-    position: relative;
-}
-
-@media screen and (max-width: 700px) {
-    /* Remove extra margin on mobile. */
-    main > section > :first-child {
-        margin-top: 0;
-    }
-}
-
-main section {
-    max-width: var(--verso-content-max-width);
-}
-
-main ol.section-toc, main .section-toc ol {
-    list-style-type: none;
-}
-
-main ol.section-toc {
-    /* This is to "undo" the text-indent: -3rem on the LI elements, which indents
-       subsequent lines but not the section number. */
-    padding-left: 3rem;
-}
-
-main .section-toc > li {
-    padding-bottom: 0.25rem;
-}
-
-main .section-toc ol {
-    padding-left: 0.5rem
-}
-
-main .section-toc li {
-    font-weight: bold;
-    font-family: var(--verso-structure-font-family);
-    margin-left: 1rem;
-    /* Indent text that isn't a section number */
-    text-indent: -3rem;
-}
-
-main .section-toc a, main .section-toc a:visited {
-    color: inherit;
-    text-decoration: none;
-}
-
-main .section-toc a:hover {
-    text-decoration: underline;
-}
-
-/* Content links pick up the theme's link colors. Scoped to `main` so chrome links (header,
-   ToC, search, permalinks) keep their own scoped rules. */
-main a {
-    color: var(--verso-link-color);
-}
-
-main a:visited {
-    color: var(--verso-visited-link-color);
-}
-
-/******** Manual-specific changes to highlighted Lean code ********/
-
-/* Don't scroll horizontally due to long identifiers (e.g. option names) */
-@media screen and (max-width: 700px) {
-    .hl.lean.inline {
-        overflow-wrap: break-word;
-    }
-}
-
-/******** Permalink widgets ********/
-
-.permalink-widget.inline {
-    opacity: 0;
-    text-decoration: none;
-    font-size: 50%;
-    vertical-align: 10%;
-    margin-left: 0.5rem;
-    width: 0;
-    position: relative;
-}
-
-.permalink-widget.inline > a {
-    position: absolute;
-    bottom: 0;
-    left: 0;
-}
-
-:hover > .permalink-widget.inline {
-    opacity: 1;
-}
-
-
-:has(> .permalink-widget.block) {
-    position: relative;
-}
-
-:hover > .permalink-widget.block {
-    opacity: 1;
-}
-
-.permalink-widget.block {
-    position: absolute;
-    right: calc(-1 * var(--verso--content-padding-x));
-    top: 0;
-    opacity: 0.1;
-    transition: opacity 0.5s;
-}
-
-/* On narrow screens, float the widget over the block instead of
-   putting it in the margin to avoid horizontal scrolling. */
-@media screen and (max-width: 700px) {
-    .permalink-widget.block {
-        right: 0;
-        opacity: 1;
-    }
-}
-
-.permalink-widget > a {
-  /* Don't show the colors here */
-  color: transparent;
-  text-shadow: 0 0 0 gray;
-  text-decoration: none;
-}
-
-.permalink-widget > a:hover {
-  text-decoration: none;
-}
-
-/*
-Don't shrink code blocks when there's marginalia that overlaps
-*/
-@media screen and (700px < width <= 1400px) {
-  .hl.lean.block {
-    clear: right;
-  }
-}
-
-/*
-Don't shrink doc blocks when there's marginalia that overlaps
-*/
-@media screen and (700px < width <= 1400px) {
-  .namedocs {
-    clear: right;
-  }
-}
-
-
-section > p, section > ul, section > ol {
-    margin-top: 1rem;
-    margin-bottom: 1rem;
-}
-
-div.paragraph > p:not(:first-child),
-div.paragraph > ul:not(:first-child),
-div.paragraph > ol:not(:first-child),
-div.paragraph > code.hl.lean.block:not(:first-child),
-div.paragraph > pre.syntax-error:not(:first-child),
-div.paragraph > dl:not(:first-child) {
-  margin-top: 0.5rem;
-}
-
-div.paragraph > p:not(:last-child),
-div.paragraph > ul:not(:last-child),
-div.paragraph > ol:not(:last-child),
-div.paragraph > code.hl.lean.block:not(:last-child),
-div.paragraph > pre.syntax-error:not(:last-child),
-div.paragraph > dl:not(:last-child) {
-  margin-bottom: 0.5rem;
-}
-
-ol li::marker {
-  font-family: var(--verso-text-font-family);
-}
-
-/*
-Don't impose margins on lists or list items from their contents.
-*/
-main section li > :first-child {
-  margin-top: 0;
-}
-main section li > :last-child {
-  margin-bottom: 0;
-}
-main section li:not(:first-child) {
-  margin-top: 0.5rem;
-}
-main section li:not(:last-child) {
-  margin-bottom: 0.5rem;
-}
-main section li ol {
-  margin-top: .5rem;
-}
-
-.hl.lean.block {
-    margin-top: 1em;
-    margin-bottom: 1em;
-    margin-left: 0.75em;
-}
-
-.lean-output {
-    overflow-x: auto;
-    margin: 0px;
-    margin: 0.5em .85em;
-    border-left: 0.2em solid red;
-    padding: 0 0.45em;
-}
-
-/* Different color for warning */
-.lean-output.warning {
-    border-color: var(--verso-warning-color);
-}
-
-/* Different color for information */
-.lean-output.information {
-    border-color: #0000c0;
-}
-
-
-/* TODO: fix upstream */
-.hl.lean code {
-    font-family: var(--verso-code-font-family) !important;
-}
-
-"####
+/--
+The contents of the manual genre's `book.css`, loaded from `static-web/manual/book.css` so
+the CSS can be edited (and reviewed) as CSS rather than as a Lean string literal. Written to
+the output root at emit time.
+-/
+public def pageStyle : String := include_str "../../../../static-web/manual/book.css"
diff --git a/src/verso-manual/VersoManual/InlineLean/Block.lean b/src/verso-manual/VersoManual/InlineLean/Block.lean
index dbd64f88f..172603b79 100644
--- a/src/verso-manual/VersoManual/InlineLean/Block.lean
+++ b/src/verso-manual/VersoManual/InlineLean/Block.lean
@@ -46,8 +46,7 @@ block_extension Block.lean
       | .error err =>
         reportError <| "Couldn't deserialize Lean code block while rendering TeX: " ++ err
         pure .empty
-      | .ok (hl : Highlighted) =>
-        hl.toTeX (g := Manual) (m := EmitM)
+      | .ok (hl : Highlighted) => hl.toTeX
   toHtml :=
     open Verso.Output.Html in
     some <| fun _ _ _ data _ => do
@@ -58,5 +57,4 @@ block_extension Block.lean
         reportError <| "Couldn't deserialize Lean code block while rendering HTML: " ++ err
         pure .empty
       | .ok (hl : Highlighted) =>
-
         hl.blockHtml (g := Manual) "examples"
diff --git a/src/verso-manual/VersoManual/Theme/Assets.lean b/src/verso-manual/VersoManual/Theme/Assets.lean
index cf7fc7945..3e801ad78 100644
--- a/src/verso-manual/VersoManual/Theme/Assets.lean
+++ b/src/verso-manual/VersoManual/Theme/Assets.lean
@@ -9,10 +9,10 @@ meta import Init.System.FilePath
 namespace Verso.Genre.Manual.Theme
 
 /-- The picker JavaScript: builds the dialog opened by `#theme-picker-button`. -/
-public def «theme-picker.js» : String := include_str "../../../../static-web/theme/theme-picker.js"
+public def «theme-picker.js» : String := include_str "../../../../static-web/manual/theme/theme-picker.js"
 
 /-- The picker styles. -/
-public def «theme-picker.css» : String := include_str "../../../../static-web/theme/theme-picker.css"
+public def «theme-picker.css» : String := include_str "../../../../static-web/manual/theme/theme-picker.css"
 
 /--
 A small fixed code sample the picker drops into the preview pane so the user can see what each
diff --git a/static-web/manual/book.css b/static-web/manual/book.css
new file mode 100644
index 000000000..5898d41ae
--- /dev/null
+++ b/static-web/manual/book.css
@@ -0,0 +1,940 @@
+/******** Customizability ********/
+
+:root {
+    /** Typography **/
+    /* What's the maximum line width, for legibility? */
+    --verso-content-max-width: 47rem;
+    /* Desktop font size */
+    --verso-font-size: 16px;
+    /* Mobile font size */
+    --verso-mobile-font-size: 16px;
+
+    /** Header appearance **/
+    --verso-header-height: 3rem;
+    /* Height of the displayed logo **/
+    --verso-logo-height: var(--verso-header-height);
+
+    /** Table of Contents appearance **/
+    /* How long should the ToC animation take? */
+    --verso-toc-transition-time: 0.4s;
+
+    /* How wide should the ToC be on non-mobile? */
+    --verso-toc-width: 18rem;
+
+    /** Variables that control the “burger menu” appearance **/
+    --verso-burger-height: 1.25rem;
+    --verso-burger-width: 1.25rem;
+    --verso-burger-line-width: 0.2rem;
+    --verso-burger-line-radius: 0.2rem;
+
+    /* The "burger menu" may need to get bigger for mobile screens */
+    --verso-mobile-burger-height: 1.5rem;
+    --verso-mobile-burger-width: 1.5rem;
+    --verso-mobile-burger-line-width: 0.3rem;
+    --verso-mobile-burger-line-radius: 0.3rem;
+}
+
+/******** Global parameters not intended for customization by themes ********/
+
+:root {
+    /* How much space to add on the sides of content for small screens and to place widgets. */
+    --verso--content-padding-x: 1.5rem;
+
+    /* Vertical margin for definition boxes and examples */
+    --verso--box-vertical-margin: 1.5rem;
+    --verso--box-padding: 1rem;
+}
+
+@media screen and (max-width: 700px) {
+    :root {
+        /* Reduce the standard padding on mobile */
+        --verso--content-padding-x: 1rem;
+    }
+}
+
+/******** Root font size - this is what rem is based on *********/
+
+html {
+    font-size: var(--verso-font-size);
+}
+
+@media screen and (max-width: 700px) {
+    html {
+        font-size: var(--verso-mobile-font-size);
+    }
+}
+
+/******** Reset ********/
+
+body {
+    margin: 0;
+    padding: 0;
+    background: var(--verso-background-color);
+    color: var(--verso-text-color);
+}
+
+/* Light/dark logo switching: when both images are rendered, show one based on the appearance
+   the no-flash script set on `<html>`. When only a light logo is rendered, no rule fires and it
+   is visible in both appearances by default. */
+:root[data-verso-appearance="dark"] #logo .logo-light {
+    display: none;
+}
+:root[data-verso-appearance="light"] #logo .logo-dark {
+    display: none;
+}
+
+/******** Theme ********/
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+    font-family: var(--verso-structure-font-family);
+    font-weight: bold;
+    text-rendering: optimizeLegibility;
+    margin-top: 1.5rem;
+}
+
+p,
+dt,
+dd {
+    font-family: var(--verso-text-font-family);
+    line-height: 1.45;
+}
+
+dt {
+    font-weight: bold;
+}
+
+dd > p:first-child {
+    margin-top: 0;
+}
+
+pre,
+code {
+    font-family: var(--verso-code-font-family);
+    font-variant-ligatures: none;
+    overflow-x: auto;
+    overflow-y: clip;
+}
+
+/******** Page Layout ********/
+
+header {
+    position: fixed;
+    top: 0;
+    z-index: 99;
+    left: 0;
+    right: 0;
+    background: var(--verso-header-background);
+    display: flex;
+    align-items: center;
+    height: var(--verso-header-height);
+    box-shadow: 0 0px 6px lightgray;
+}
+
+.header-logo-wrapper {
+    /* Make the logo always take up the same space as the toc */
+    flex-basis: var(--verso-toc-width);
+    /* Make padding be included in the width calculation */
+    box-sizing: border-box;
+    /* Add padding so it doesn't sit at the very edge of the screen. */
+    padding-left: 0.5rem;
+}
+
+@media screen and (max-width: 700px) {
+    .header-logo-wrapper {
+        display: none;
+    }
+}
+
+.header-title-wrapper {
+    /* The title wrapper grows to fill up the header */
+    flex: 1;
+}
+
+@media screen and (max-width: 1500px) {
+    /* Add the padding of the content when the content moves to the left */
+    padding-left: var(--verso--content-padding-x);
+}
+
+.header-title {
+    text-decoration: none;
+    color: var(--verso-text-color);
+    font-size: 2rem;
+    font-weight: bold;
+    display: block;
+    margin: 0 auto;
+    max-width: var(--verso-content-max-width);
+}
+
+@media screen and (max-width: 1500px) {
+    /* Move the title to the left, to align with the content that does the same. */
+    .header-title {
+        margin: 0;
+        max-width: unset;
+    }
+}
+
+@media screen and (max-width: 700px) {
+    /* There's no header logo on mobile, so the title just needs to reserve space for the burger */
+    .header-title {
+        margin-left: calc(
+            var(--verso-burger-width) + 1.5rem
+        ); /* There's 0.5 rem padding on the burger, and we want some space */
+        max-width: unset;
+    }
+}
+
+.header-title h1 {
+    margin: 0;
+    font-size: inherit;
+    font-weight: inherit;
+    text-wrap: nowrap;
+}
+
+:root:has(header:empty) {
+    --verso-header-height: 0px;
+}
+
+.with-toc {
+    margin-top: var(--verso-header-height);
+}
+
+main [id] {
+    /* When jumping to something, display it below the header. We also add a little
+     whitespace, so it's easier to see that you are indeed viewing the whole item. */
+    scroll-margin-top: calc(var(--verso-header-height) + 1rem);
+}
+
+.with-toc #toc {
+    position: fixed;
+    z-index: 10;
+}
+
+/** Non-mobile **/
+.with-toc > main {
+    /* NB main > section also has padding that's added to this in practice */
+    padding-left: var(--verso-toc-width);
+}
+
+/** Mobile **/
+@media screen and (max-width: 700px) {
+    .with-toc > main {
+        padding-left: 0;
+    }
+}
+
+.with-toc #toc {
+    overflow-y: auto;
+}
+
+/******** Table of Contents ********/
+
+/* This backdrop should be hidden on desktop browsers, and show up when the ToC is open on mobile browsers */
+.toc-backdrop {
+    display: none;
+}
+
+@media screen and (max-width: 700px) {
+    .toc-backdrop {
+        display: block;
+    }
+    body:has(#toggle-toc:checked) .toc-backdrop {
+        position: fixed;
+        inset: 0;
+        background-color: #aaa8;
+        z-index: 9;
+    }
+    html:has(#toggle-toc:checked) {
+        overflow: hidden;
+    }
+}
+
+#toc {
+    background-color: var(--verso-toc-background-color);
+    color: var(--verso-toc-text-color);
+    display: flex;
+    flex-direction: column;
+    justify-content: space-between;
+    height: calc(100dvh - var(--verso-header-height));
+    width: var(--verso-toc-width);
+}
+
+@media screen and (max-width: 700px) {
+    #toc {
+        /* Push the toc off the page on mobile */
+        right: 100%;
+        transition: transform var(--verso-toc-transition-time) ease;
+    }
+
+    #toc:has(#toggle-toc:checked) {
+        transform: translateX(var(--verso-toc-width));
+    }
+}
+
+#toggle-toc {
+    display: none;
+}
+
+#toc a {
+    color: var(--verso-toc-text-color);
+    text-decoration: none;
+}
+
+#toc a:hover {
+    text-decoration: underline;
+    color: var(--verso-toc-text-color);
+}
+
+.toc-title {
+    /* The ToC title can be displayed when there is no room for the title in the header. */
+    display: none;
+    padding: 0 0.5rem;
+}
+
+.toc-title h1 {
+    margin-bottom: 0;
+}
+
+#toc .split-tocs {
+    padding-left: 0;
+    padding-right: 0.5rem;
+    margin-top: 1.5rem;
+}
+
+#toc .split-toc.book {
+    margin-bottom: 2rem;
+}
+
+#toc .split-toc.book .title {
+    font-weight: 600;
+}
+
+#toc .split-toc {
+    margin-bottom: 1.5rem;
+    font-family: var(--verso-structure-font-family);
+}
+
+#toc .split-toc label.toggle-split-toc {
+}
+
+#toc .split-toc .title {
+    display: flex;
+    flex-wrap: nowrap;
+}
+
+#toc .split-toc label.toggle-split-toc input[type="checkbox"] {
+    display: inline-block;
+    position: absolute;
+    top: 0;
+    left: 0;
+    opacity: 0;
+    height: 0;
+    width: 0;
+    z-index: -10;
+}
+
+:root {
+    --verso-toc-triangle-width: 0.6rem;
+    --verso-toc-triangle-height: 0.6rem;
+    --verso-toc-triangle-left-space: 0.5rem;
+    --verso-toc-triangle-margin: 0.5rem;
+}
+
+#toc .split-toc label.toggle-split-toc::before {
+    width: calc(var(--verso-toc-triangle-width) + var(--verso-toc-triangle-left-space));
+    height: var(--verso-toc-triangle-height);
+    display: inline-block;
+    background-color: var(--verso-toc-text-color);
+    content: " ";
+    transition: ease 0.2s;
+    margin-right: var(--verso-toc-triangle-margin);
+    clip-path: polygon(
+        100% 0,
+        var(--verso-toc-triangle-left-space) 0,
+        calc(
+                var(--verso-toc-triangle-left-space) +
+                    calc(calc(100% - var(--verso-toc-triangle-left-space)) / 2)
+            )
+            100%
+    );
+    transform-origin:
+        /* X axis: left spacing plus half the width to get the center*/ calc(
+            var(--verso-toc-triangle-left-space) + calc(var(--verso-toc-triangle-width) / 2)
+        )
+        /* Y axis */ center;
+}
+
+#toc .split-toc label.toggle-split-toc:has(input[type="checkbox"]:not(:checked))::before {
+    transform: rotate(-90deg);
+}
+
+#toc .split-toc .no-toggle {
+    /* Line up triangle-less content with the triangled content */
+    width: calc(var(--verso-toc-triangle-width) + var(--verso-toc-triangle-left-space));
+    margin-right: var(--verso-toc-triangle-margin);
+    display: inline-block;
+}
+
+#toc .split-toc > :not(:first-child) {
+    max-height: 0px;
+    display: block;
+    overflow: hidden;
+    /* Line it up with the point of the disclosure triangle */
+    margin-left: calc(
+        var(--verso-toc-triangle-left-space) + calc(var(--verso-toc-triangle-width) / 2)
+    );
+}
+
+#toc .split-toc:has(.toggle-split-toc input[type="checkbox"]:not(:checked)) > :not(:first-child) {
+    padding: 0;
+    margin: 0;
+}
+
+#toc .split-toc:has(.toggle-split-toc input[type="checkbox"]:checked) > :not(:first-child) {
+    max-height: 100%;
+}
+
+#toc .split-toc table {
+    border-left: 1px dotted;
+    padding-left: 1.2rem;
+    padding-top: 0.2rem;
+}
+
+#toc .split-toc td {
+    vertical-align: top;
+}
+
+#toc .split-toc > ol {
+    border-left: 1px dotted;
+    list-style-type: none;
+    padding-left: 0.5rem;
+    margin-left: 0;
+    margin-right: 0;
+    margin-bottom: 0.5rem;
+    margin-top: 0.5rem;
+    font-size: 0.9rem;
+}
+
+#toc .split-toc > ol > li {
+    text-indent: -1.5rem;
+    padding-left: 2.5rem;
+}
+
+#toc .split-toc > ol > li:has(.header) {
+    padding-left: 2rem;
+}
+
+#toc .split-toc .current td:not(.num),
+#toc .split-toc .title .current {
+    text-decoration-line: underline;
+    text-decoration-style: dotted;
+}
+
+#toc .split-toc td.num {
+    font-variant-numeric: tabular-nums;
+}
+
+/* Add a bit of visual space between numbered and unnumbered rows */
+#toc .split-toc tr:has(+ tr.unnumbered) td,
+#toc .split-toc tr.unnumbered:has(+ tr.numbered) td {
+    padding-bottom: 0.5rem;
+}
+
+.prev-next-buttons {
+    font-weight: bold;
+    font-family: var(--verso-structure-font-family);
+    display: flex;
+    justify-content: space-between;
+    flex-wrap: wrap;
+    max-width: var(--verso-content-max-width);
+}
+
+.prev-next-buttons > *,
+.prev-next-buttons > *:visited {
+    display: flex;
+    flex: 1;
+    justify-content: center;
+    align-items: center;
+    /*
+    Section navigation links should have the color of text, regardless of their visited status, because they're
+    part of the site navigation. Without these rules, they show up link-colored.
+    */
+    color: var(--verso-text-color);
+    text-decoration: none;
+}
+
+.prev-next-buttons > [rel="prev"] {
+    justify-content: start;
+}
+
+.prev-next-buttons > [rel="next"] {
+    justify-content: end;
+}
+
+.prev-next-buttons .local-button .where {
+    margin: 0 0.3rem;
+    /* Fix the position relative to the arrows. */
+    position: relative;
+    top: 0.1rem;
+}
+
+.prev-next-buttons .arrow {
+    font-family: var(--verso-code-font-family);
+    font-size: 150%;
+}
+
+#logo {
+    max-height: 100%;
+    display: block;
+}
+
+#logo img {
+    object-fit: contain;
+    max-height: var(--verso-logo-height);
+    display: block;
+}
+
+/******** Width-dependent layout elements ********/
+
+.narrow-only {
+    display: none;
+}
+
+@media screen and (max-width: 500px) {
+    .wide-only {
+        display: none;
+    }
+    .narrow-only {
+        display: revert;
+    }
+}
+
+@media screen and (min-width: 700px) and (max-width: 920px) {
+    .wide-only {
+        display: none;
+    }
+    .narrow-only {
+        display: revert;
+    }
+}
+
+/******** Headerline ********/
+
+#toggle-toc-click {
+    /* Hidden on desktop */
+    display: none;
+}
+
+@media screen and (max-width: 700px) {
+    #toggle-toc-click {
+        display: inline-flex;
+        cursor: pointer;
+        /* This is the default, but it's needed to make the math work out so nice to be explicit: */
+        box-sizing: content-box;
+        width: var(--verso-burger-width);
+        height: var(--verso-burger-height);
+        flex-direction: column;
+        justify-content: space-between;
+        padding: 0.5rem;
+        position: fixed;
+        z-index: 100; /* Show on top of ToC/content */
+        /* Calculation to make it sit in the middle of the header. The .5rem is the padding added to #toggle-toc-click. */
+        top: calc((var(--verso-header-height) - var(--verso-burger-height) - 2 * 0.5rem) / 2);
+        filter: drop-shadow(1px 1px var(--verso-burger-toc-hidden-shadow-color))
+            drop-shadow(-1px -1px var(--verso-burger-toc-hidden-shadow-color));
+        transition:
+            height var(--verso-toc-transition-time) ease-in-out,
+            width var(--verso-toc-transition-time) ease-in-out;
+    }
+
+    body:has(#toggle-toc:checked) #toggle-toc-click {
+        filter: drop-shadow(1px 1px var(--verso-burger-toc-visible-shadow-color))
+            drop-shadow(-1px -1px var(--verso-burger-toc-visible-shadow-color));
+    }
+
+    body {
+        --verso-burger-width: var(--verso-mobile-burger-width);
+        --verso-burger-height: var(--verso-mobile-burger-height);
+        --verso-burger-line-width: var(--verso-mobile-burger-line-width);
+        --verso-burger-line-radius: var(--verso-mobile-burger-line-radius);
+    }
+}
+
+#toggle-toc-click .line {
+    display: block;
+    position: relative;
+    width: 100%;
+    height: var(--verso-burger-line-width);
+    border-radius: var(--verso-burger-line-radius);
+    background-color: var(--verso-burger-toc-hidden-color);
+    /* The background color has a transition in case a theme needs to override the line color
+       when the ToC menu is open */
+    transition:
+        background-color var(--verso-toc-transition-time) ease-in-out,
+        height var(--verso-toc-transition-time) ease-in-out,
+        width var(--verso-toc-transition-time) ease-in-out,
+        transform var(--verso-toc-transition-time) ease-in-out;
+    z-index: 15;
+}
+
+body:has(#toggle-toc:checked) #toggle-toc-click .line {
+    background-color: var(--verso-burger-toc-visible-color);
+}
+
+body:has(#toggle-toc:checked) #toggle-toc-click .line1 {
+    transform: translateY(
+            calc(calc(var(--verso-burger-height) - var(--verso-burger-line-width)) / 2)
+        )
+        rotate(45deg);
+}
+body:has(#toggle-toc:checked) #toggle-toc-click .line2 {
+    transform: scaleX(0);
+}
+body:has(#toggle-toc:checked) #toggle-toc-click .line3 {
+    transform: translateY(
+            calc(-1 * calc(calc(var(--verso-burger-height) - var(--verso-burger-line-width)) / 2))
+        )
+        rotate(-45deg);
+}
+
+#meta-links {
+    list-style-type: none;
+    font-family: var(--verso-structure-font-family);
+    font-size: 90%;
+    display: flex;
+    justify-content: space-between;
+    padding: 0 1rem;
+}
+#meta-links li {
+    display: inline-block;
+}
+
+/******** Text ********/
+
+/*
+For words that are too long to fit on the screen, it's better to wrap than to have horizontal scrolling
+*/
+main h1,
+main h2,
+main h3,
+main h4,
+main h5,
+main h6 {
+    overflow-wrap: break-word;
+}
+
+main h1 {
+    font-size: 2.3rem;
+    line-height: 1.5;
+    margin-bottom: 1.3rem;
+}
+
+main h2 {
+    font-size: 1.7rem;
+    line-height: 1.5;
+    margin-bottom: 1rem;
+}
+
+main h3 {
+    font-size: 1.4rem;
+    line-height: 1.5;
+    margin-bottom: 0.2rem;
+}
+
+main h4 {
+    font-size: 1.2rem;
+    line-height: 1.25;
+    margin-bottom: 0.2rem;
+}
+
+main h5 {
+    font-size: 1rem;
+    line-height: 1.25;
+    margin-bottom: 0.2rem;
+}
+
+main h6 {
+    font-size: 1rem;
+    font-weight: 500;
+    line-height: 1.15;
+    margin-bottom: 0rem;
+}
+
+main .titlepage h1 {
+    text-align: center;
+}
+
+main .authors {
+    text-align: center;
+    font-family: var(--verso-structure-font-family);
+}
+
+main .authors {
+    text-align: center;
+    font-family: var(--verso-structure-font-family);
+}
+
+main .authors .author:only-of-type::after {
+    content: "";
+}
+
+main .authors .author:not(:last-of-type)::after {
+    content: ", ";
+}
+
+main .authors .author:nth-last-of-type(2)::after {
+    content: " and ";
+}
+
+main .authors .note {
+    margin: 0;
+    display: inline;
+    font-style: italic;
+}
+main .authors:has(.author) .note::before {
+    content: ", ";
+}
+
+/******** Main content ********/
+
+.content-wrapper {
+    padding: var(--verso--content-padding-x);
+    max-width: var(--verso-content-max-width);
+    margin: 0 auto;
+}
+
+@media screen and (max-width: 1500px) {
+    /* Left align the content when less than 1500px, to make room for the footnotes on the right. */
+    .content-wrapper {
+        margin: 0;
+        max-width: unset;
+    }
+}
+
+main > section {
+    position: relative;
+}
+
+@media screen and (max-width: 700px) {
+    /* Remove extra margin on mobile. */
+    main > section > :first-child {
+        margin-top: 0;
+    }
+}
+
+main section {
+    max-width: var(--verso-content-max-width);
+}
+
+main ol.section-toc,
+main .section-toc ol {
+    list-style-type: none;
+}
+
+main ol.section-toc {
+    /* This is to "undo" the text-indent: -3rem on the LI elements, which indents
+       subsequent lines but not the section number. */
+    padding-left: 3rem;
+}
+
+main .section-toc > li {
+    padding-bottom: 0.25rem;
+}
+
+main .section-toc ol {
+    padding-left: 0.5rem;
+}
+
+main .section-toc li {
+    font-weight: bold;
+    font-family: var(--verso-structure-font-family);
+    margin-left: 1rem;
+    /* Indent text that isn't a section number */
+    text-indent: -3rem;
+}
+
+main .section-toc a,
+main .section-toc a:visited {
+    color: inherit;
+    text-decoration: none;
+}
+
+main .section-toc a:hover {
+    text-decoration: underline;
+}
+
+/* Content links pick up the theme's link colors. Scoped to `main` so chrome links (header,
+   ToC, search, permalinks) keep their own scoped rules. */
+main a {
+    color: var(--verso-link-color);
+}
+
+main a:visited {
+    color: var(--verso-visited-link-color);
+}
+
+/******** Manual-specific changes to highlighted Lean code ********/
+
+/* Don't scroll horizontally due to long identifiers (e.g. option names) */
+@media screen and (max-width: 700px) {
+    .hl.lean.inline {
+        overflow-wrap: break-word;
+    }
+}
+
+/******** Permalink widgets ********/
+
+.permalink-widget.inline {
+    opacity: 0;
+    text-decoration: none;
+    font-size: 50%;
+    vertical-align: 10%;
+    margin-left: 0.5rem;
+    width: 0;
+    position: relative;
+}
+
+.permalink-widget.inline > a {
+    position: absolute;
+    bottom: 0;
+    left: 0;
+}
+
+:hover > .permalink-widget.inline {
+    opacity: 1;
+}
+
+:has(> .permalink-widget.block) {
+    position: relative;
+}
+
+:hover > .permalink-widget.block {
+    opacity: 1;
+}
+
+.permalink-widget.block {
+    position: absolute;
+    right: calc(-1 * var(--verso--content-padding-x));
+    top: 0;
+    opacity: 0.1;
+    transition: opacity 0.5s;
+}
+
+/* On narrow screens, float the widget over the block instead of
+   putting it in the margin to avoid horizontal scrolling. */
+@media screen and (max-width: 700px) {
+    .permalink-widget.block {
+        right: 0;
+        opacity: 1;
+    }
+}
+
+.permalink-widget > a {
+    /* Don't show the colors here */
+    color: transparent;
+    text-shadow: 0 0 0 gray;
+    text-decoration: none;
+}
+
+.permalink-widget > a:hover {
+    text-decoration: none;
+}
+
+/*
+Don't shrink code blocks when there's marginalia that overlaps
+*/
+@media screen and (700px < width <= 1400px) {
+    .hl.lean.block {
+        clear: right;
+    }
+}
+
+/*
+Don't shrink doc blocks when there's marginalia that overlaps
+*/
+@media screen and (700px < width <= 1400px) {
+    .namedocs {
+        clear: right;
+    }
+}
+
+section > p,
+section > ul,
+section > ol {
+    margin-top: 1rem;
+    margin-bottom: 1rem;
+}
+
+div.paragraph > p:not(:first-child),
+div.paragraph > ul:not(:first-child),
+div.paragraph > ol:not(:first-child),
+div.paragraph > code.hl.lean.block:not(:first-child),
+div.paragraph > pre.syntax-error:not(:first-child),
+div.paragraph > dl:not(:first-child) {
+    margin-top: 0.5rem;
+}
+
+div.paragraph > p:not(:last-child),
+div.paragraph > ul:not(:last-child),
+div.paragraph > ol:not(:last-child),
+div.paragraph > code.hl.lean.block:not(:last-child),
+div.paragraph > pre.syntax-error:not(:last-child),
+div.paragraph > dl:not(:last-child) {
+    margin-bottom: 0.5rem;
+}
+
+ol li::marker {
+    font-family: var(--verso-text-font-family);
+}
+
+/*
+Don't impose margins on lists or list items from their contents.
+*/
+main section li > :first-child {
+    margin-top: 0;
+}
+main section li > :last-child {
+    margin-bottom: 0;
+}
+main section li:not(:first-child) {
+    margin-top: 0.5rem;
+}
+main section li:not(:last-child) {
+    margin-bottom: 0.5rem;
+}
+main section li ol {
+    margin-top: 0.5rem;
+}
+
+.hl.lean.block {
+    margin-top: 1em;
+    margin-bottom: 1em;
+    margin-left: 0.75em;
+}
+
+.lean-output {
+    overflow-x: auto;
+    margin: 0px;
+    margin: 0.5em 0.85em;
+    border-left: 0.2em solid red;
+    padding: 0 0.45em;
+}
+
+/* Different color for warning */
+.lean-output.warning {
+    border-color: var(--verso-warning-color);
+}
+
+/* Different color for information */
+.lean-output.information {
+    border-color: #0000c0;
+}
+
+/* TODO: fix upstream */
+.hl.lean code {
+    font-family: var(--verso-code-font-family) !important;
+}
diff --git a/static-web/theme/theme-picker.css b/static-web/manual/theme/theme-picker.css
similarity index 100%
rename from static-web/theme/theme-picker.css
rename to static-web/manual/theme/theme-picker.css
diff --git a/static-web/theme/theme-picker.js b/static-web/manual/theme/theme-picker.js
similarity index 100%
rename from static-web/theme/theme-picker.js
rename to static-web/manual/theme/theme-picker.js

From 206d39414cde854016291c400be5f2a31302e621 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Mon, 1 Jun 2026 08:25:39 +0200
Subject: [PATCH 13/31] more cleanup

---
 src/tests/ThemeTestMain.lean                  |   2 +-
 src/verso-manual/VersoManual.lean             |   4 +-
 .../VersoManual/Theme/Defaults.lean           | 191 ++++++++++--------
 src/verso-manual/VersoManual/Theme/Emit.lean  |  24 ++-
 src/verso/Verso/Code/HighlightedToTex.lean    |  10 +-
 src/verso/Verso/Theme/Code.lean               |  54 ++++-
 src/verso/Verso/Theme/Code/Defaults.lean      |   4 +-
 src/verso/Verso/Theme/Color/OkabeIto.lean     |  41 ++++
 src/verso/Verso/Theme/Color/Solarized.lean    |  64 ++++++
 static-web/manual/theme/theme-picker.css      |  28 +++
 static-web/manual/theme/theme-picker.js       |  64 +++++-
 11 files changed, 365 insertions(+), 121 deletions(-)
 create mode 100644 src/verso/Verso/Theme/Color/OkabeIto.lean
 create mode 100644 src/verso/Verso/Theme/Color/Solarized.lean

diff --git a/src/tests/ThemeTestMain.lean b/src/tests/ThemeTestMain.lean
index de0d8ccab..d2f353869 100644
--- a/src/tests/ThemeTestMain.lean
+++ b/src/tests/ThemeTestMain.lean
@@ -12,7 +12,7 @@ open Verso Verso.Theme
 open Verso.Genre Manual
 
 /-!
-The customized {Lean.Doc.name}`Verso.Theme.CodeTheme` used by the browser test. Each color field
+The customized {name}`Verso.Theme.CodeTheme` used by the browser test. Each color field
 holds a distinct sentinel hex value so Playwright can identify which theme field a rendered DOM
 color comes from.
 -/
diff --git a/src/verso-manual/VersoManual.lean b/src/verso-manual/VersoManual.lean
index 9b514f7a0..c176350fc 100644
--- a/src/verso-manual/VersoManual.lean
+++ b/src/verso-manual/VersoManual.lean
@@ -449,7 +449,7 @@ def defaultSingleName (config : RenderConfig) : Lean.Name :=
 
 /--
 The single-default `Verso.Theme.ManualTheme` resolved from the active
-{Lean.Doc.name}`Verso.Theme.ThemeRegistry`. This is the theme that drives
+{name}`Verso.Theme.ThemeRegistry`. This is the theme that drives
 `verso-themes.css`'s unscoped `:root` block — what the server-rendered HTML paints on first
 visit (before the no-flash script attaches a `data-verso-theme`) — and the TeX code styling.
 
@@ -1220,7 +1220,7 @@ where
     checkDefault "defaultDarkTheme" cfg.defaultDarkTheme
 
   /--
-  Builds the active {Lean.Doc.name}`Verso.Theme.ThemeRegistry` from the registered
+  Builds the active {name}`Verso.Theme.ThemeRegistry` from the registered
   `Verso.Theme.ManualTheme` table, filters it by the configured
   `availableThemes`, and routes every
   `Verso.Theme.ManualThemeTable.ValidationError` through `MonadBuildLog` as an error.
diff --git a/src/verso-manual/VersoManual/Theme/Defaults.lean b/src/verso-manual/VersoManual/Theme/Defaults.lean
index 61c57b922..63f072fbf 100644
--- a/src/verso-manual/VersoManual/Theme/Defaults.lean
+++ b/src/verso-manual/VersoManual/Theme/Defaults.lean
@@ -7,12 +7,14 @@ module
 
 public import VersoManual.Theme
 public import Verso.Theme.Code.Defaults
+public import Verso.Theme.Color.Solarized
+public import Verso.Theme.Color.OkabeIto
 
 set_option linter.missingDocs true
 set_option doc.verso true
 
 /-!
-Built-in {Lean.Doc.name}`Verso.Theme.ManualTheme` values. The default theme reproduces today's
+Built-in {name}`Verso.Theme.ManualTheme` values. The default theme reproduces today's
 chrome so existing manuals render unchanged when no override is configured. The dark counterpart
 inverts the page and code backgrounds while preserving the typography-only token rendering.
 
@@ -29,16 +31,16 @@ The light default manual theme. Named after the most ancient writing medium in u
 inks made from soot or oak gall that have carried text for two thousand years. Typography and
 chrome reproduce today's hardcoded look.
 
-Other built-in themes live alongside it in the {Lean.Doc.name}`Verso.Theme.ManualTheme` namespace.
+Other built-in themes live alongside it in the {name}`Verso.Theme.ManualTheme` namespace.
 -/
 @[manual_theme]
 public def ManualTheme.ink : ManualTheme where
-  toCodeTheme := { CodeTheme.ink with name := "Ink" }
+  toCodeTheme := CodeTheme.ink
 
 /--
 A common dark-appearance code-theme base: deep-charcoal backgrounds, brightened text, accent
 colors chosen for readability against the dark substrate. Other dark themes extend this. Every
-cascading field is overridden explicitly because Lean evaluates the {Lean.Doc.name}`Verso.Theme.CodeTheme`
+cascading field is overridden explicitly because Lean evaluates the {name}`Verso.Theme.CodeTheme`
 defaults at construction time, so {lit}`CodeTheme.ink with textColor := …` would otherwise
 leave dependent fields (token colors, message text colors, hover text) frozen at their
 original-light values.
@@ -60,17 +62,17 @@ private def darkCodeBase : CodeTheme :=
   warningColor := text,
   infoColor := text,
   -- Token colors default to the bright code color; colorful themes override these per token.
-  const   := { color := text, weight := .regular, style := .normal, face := .mono },
-  keyword := { color := text, weight := .bold,    style := .normal, face := .mono },
-  «var»   := { color := text, weight := .regular, style := .italic, face := .mono },
+  const := { color := text, weight := .regular, style := .normal, face := .mono },
+  keyword := { color := text, weight := .bold, style := .normal, face := .mono },
+  «var» := { color := text, weight := .regular, style := .italic, face := .mono },
   -- Hover popups read text on a slightly lighter surface.
   hoverBackground := color%#2a2d33,
   hoverText := text,
   hoverBorderColor := color%#aaaaaa,
   hoverSeparatorColor := color%#3a3d44,
   tokenHighlightBackground := color%#33363d,
-  -- Tactic state uses the same surface as code blocks but with a visible border.
-  tacticStateBackground := codeBg,
+  -- Tactic-state background inherits from `codeBlockBackground`; only the border needs a
+  -- lighter color to read on the dark substrate.
   tacticStateBorderColor := color%#aaaaaa,
   selectedColor := color%#2a3f55,
   -- Highlight accents on a dark substrate: a saturated tone that the bright text still reads on.
@@ -106,7 +108,7 @@ The dark default manual theme. Named after silver, the ink of choice for the dar
 manuscript traditions: silver-on-purple Byzantine and Carolingian codices like the *Codex
 Argenteus*, Flemish "Black Hours" such as Morgan MS M.493, and Korean *eunja sagyeong* (은자사경)
 sutras transcribed in silver ink on indigo *kamji* paper during the Goryeo dynasty. Same
-typography-only token rendering as {Lean.Doc.name}`Verso.Theme.ManualTheme.ink`, with inverted
+typography-only token rendering as {name}`Verso.Theme.ManualTheme.ink`, with inverted
 backgrounds and a light text color.
 -/
 @[manual_theme]
@@ -126,8 +128,8 @@ public def ManualTheme.chromaticLight : ManualTheme where
     CodeTheme.ink with
     name := "Chromatic Light",
     keyword.color := color%#a02828,
-    const.color   := color%#0b6b4f,
-    «var».color   := color%#404040
+    const.color := color%#0b6b4f,
+    «var».color := color%#404040
   }
 
 /-- Chromatic dark: the colored Lean palette on a deep-charcoal background. -/
@@ -137,8 +139,8 @@ public def ManualTheme.chromaticDark : ManualTheme :=
     darkCodeBase with
     name := "Chromatic Dark",
     keyword.color := color%#ff8b8b,
-    const.color   := color%#6cb6ff,
-    «var».color   := color%#c4c4c4
+    const.color := color%#6cb6ff,
+    «var».color := color%#c4c4c4
   }
 
 /-! # Beacon — colorblind-safe syntax accents (Okabe-Ito) -/
@@ -154,8 +156,8 @@ public def ManualTheme.beaconLight : ManualTheme where
     CodeTheme.ink with
     name := "Beacon Light",
     keyword.color := color%#005b8c,
-    const.color   := color%#5b3500,
-    «var».color   := color%#9c2400
+    const.color := color%#5b3500,
+    «var».color := color%#9c2400
   }
 
 /--
@@ -168,87 +170,98 @@ public def ManualTheme.beaconDark : ManualTheme :=
     darkCodeBase with
     name := "Beacon Dark",
     keyword.color := color%#56b4e9,
-    const.color   := color%#5bd6a4,
-    «var».color   := color%#f5a85a
+    const.color := color%#5bd6a4,
+    «var».color := color%#f5a85a
   }
 
 /-! # Solarized — Ethan Schoonover's standard palette -/
 
+open Color.Solarized in
 /--
 Solarized light: Schoonover's standard cream-on-paper palette
-({lit}`base3` background, {lit}`base00` body text). Token accents reuse the named hues from
-the upstream Solarized definition.
+({lit}`base3` background, {lit}`base01` primary content). Token accents reuse the named hues
+from the upstream Solarized definition.
 -/
 @[manual_theme]
-public def ManualTheme.solarizedLight : ManualTheme where
-  toCodeTheme := {
-    CodeTheme.ink with
-    name := "Solarized Light",
-    background := color%#fdf6e3,
-    codeBlockBackground := color%#eee8d5,
-    textColor := color%#586e75,
-    codeColor := color%#586e75,
-    structureColor := color%#586e75,
-    warningColor := color%#586e75,
-    infoColor := color%#586e75,
-    errorColor := color%#dc322f,
-    errorIndicatorColor := color%#dc322f,
-    warningIndicatorColor := color%#b58900,
-    infoIndicatorColor := color%#268bd2,
-    hoverBackground := color%#eee8d5,
-    hoverText := color%#586e75,
-    hoverBorderColor := color%#93a1a1,
-    hoverSeparatorColor := color%#93a1a1,
-    tokenHighlightBackground := color%#eee8d5,
-    tacticStateBackground := color%#eee8d5,
-    tacticStateBorderColor := color%#93a1a1,
-    selectedColor := color%#eee8d5,
-    highlightOnCode := color%#f7e7a3,
-    uiOnCode := color%#93a1a1,
-    keyword.color := color%#859900,
-    const.color   := color%#268bd2,
-    «var».color   := color%#6c71c4
+public def ManualTheme.solarizedLight : ManualTheme :=
+  {
+    toCodeTheme := {
+      CodeTheme.ink with
+      name := "Solarized Light",
+      sourceLink := some {
+        url := "https://ethanschoonover.com/solarized/",
+        text := "ethanschoonover.com/solarized"
+      },
+      background := base3,
+      codeBlockBackground := base2,
+      textColor := base01,
+      codeColor := base01,
+      structureColor := base01,
+      warningColor := base01,
+      infoColor := base01,
+      errorColor := red,
+      errorIndicatorColor := red,
+      warningIndicatorColor := yellow,
+      infoIndicatorColor := blue,
+      hoverBackground := base2,
+      hoverText := base01,
+      hoverBorderColor := base1,
+      hoverSeparatorColor := base1,
+      tokenHighlightBackground := base2,
+      tacticStateBorderColor := base1,
+      selectedColor := base2,
+      highlightOnCode := color%#f7e7a3,
+      uiOnCode := base1,
+      keyword.color := green,
+      const.color := blue,
+      «var».color := violet
+    },
+    surfaceColor := base2,
+    tocBackground := base2,
+    borderColor := base01,
+    mutedColor := base00,
+    linkColor := blue,
+    visitedLinkColor := violet
   }
-  surfaceColor := color%#eee8d5
-  tocBackground := color%#eee8d5
-  borderColor := color%#586e75
-  mutedColor := color%#657b83
-  linkColor := color%#268bd2
-  visitedLinkColor := color%#6c71c4
 
+open Color.Solarized in
 /--
-Solarized dark: Schoonover's standard {lit}`base03` background with body text on {lit}`base0`.
-Same accent hues as the light variant; the relative-luminance jump comes from the substrate.
+Solarized dark: Schoonover's standard {lit}`base03` background with body text on {lit}`base1`.
+Token accents are brightened off the standard palette so they keep clear contrast on the dark
+substrate.
 -/
 @[manual_theme]
 public def ManualTheme.solarizedDark : ManualTheme :=
   darkChromeFields {
     darkCodeBase with
     name := "Solarized Dark",
-    background := color%#002b36,
-    codeBlockBackground := color%#073642,
-    textColor := color%#93a1a1,
-    codeColor := color%#93a1a1,
-    structureColor := color%#93a1a1,
-    warningColor := color%#93a1a1,
-    infoColor := color%#93a1a1,
+    sourceLink := some {
+      url := "https://ethanschoonover.com/solarized/",
+      text := "ethanschoonover.com/solarized"
+    },
+    background := base03,
+    codeBlockBackground := base02,
+    textColor := base1,
+    codeColor := base1,
+    structureColor := base1,
+    warningColor := base1,
+    infoColor := base1,
     errorColor := color%#ff8b8b,
-    errorIndicatorColor := color%#dc322f,
-    warningIndicatorColor := color%#b58900,
-    infoIndicatorColor := color%#268bd2,
-    hoverBackground := color%#073642,
-    hoverText := color%#93a1a1,
-    hoverBorderColor := color%#586e75,
-    hoverSeparatorColor := color%#586e75,
-    tokenHighlightBackground := color%#073642,
-    tacticStateBackground := color%#073642,
-    tacticStateBorderColor := color%#586e75,
-    selectedColor := color%#073642,
+    errorIndicatorColor := red,
+    warningIndicatorColor := yellow,
+    infoIndicatorColor := blue,
+    hoverBackground := base02,
+    hoverText := base1,
+    hoverBorderColor := base01,
+    hoverSeparatorColor := base01,
+    tokenHighlightBackground := base02,
+    tacticStateBorderColor := base01,
+    selectedColor := base02,
     highlightOnCode := color%#3a2f00,
-    uiOnCode := color%#93a1a1,
+    uiOnCode := base1,
     keyword.color := color%#b3d100,
-    const.color   := color%#6cb6ff,
-    «var».color   := color%#a98aff
+    const.color := color%#6cb6ff,
+    «var».color := color%#a98aff
   }
 
 /-! # Sandstone — warm sepia (Rust/Ayu inspired) -/
@@ -281,8 +294,8 @@ public def ManualTheme.sandstoneLight : ManualTheme where
     highlightOnCode := color%#f4d5a8,
     uiOnCode := color%#8c7257,
     keyword.color := color%#a04a00,
-    const.color   := color%#1f6f8b,
-    «var».color   := color%#3b2a17
+    const.color := color%#1f6f8b,
+    «var».color := color%#3b2a17
   }
   surfaceColor := color%#f3e9d6
   tocBackground := color%#f3e9d6
@@ -331,8 +344,8 @@ public def ManualTheme.sandstoneDark : ManualTheme :=
     -- by hue *and* lightness so the palette stays distinct under most dichromacies even
     -- without a cool accent.
     keyword.color := color%#ff8c4a,
-    const.color   := color%#ffc266,
-    «var».color   := color%#f3d5a3
+    const.color := color%#ffc266,
+    «var».color := color%#f3d5a3
   }
   -- Override the generic dark-chrome accents with sandstone-tuned values so the search box
   -- border, ToC background, and link colours stay in the warm family.
@@ -374,8 +387,8 @@ public def ManualTheme.steel : ManualTheme where
     highlightOnCode := color%#fff3b0,
     uiOnCode := color%#46566a,
     keyword.color := color%#1a5ea8,
-    const.color   := color%#2a6f4f,
-    «var».color   := color%#0e2431
+    const.color := color%#2a6f4f,
+    «var».color := color%#0e2431
   }
   surfaceColor := color%#e3e8ee
   tocBackground := color%#e3e8ee
@@ -412,8 +425,8 @@ public def ManualTheme.slate : ManualTheme :=
     highlightOnCode := color%#3a2f00,
     uiOnCode := color%#7a8aa0,
     keyword.color := color%#6cb6ff,
-    const.color   := color%#7ad9a0,
-    «var».color   := color%#dfe6ee
+    const.color := color%#7ad9a0,
+    «var».color := color%#dfe6ee
   }
 
 /-! # Hearth — cottagecore (cream/sage light, candlelit deep-olive dark) -/
@@ -448,8 +461,8 @@ public def ManualTheme.hearthLight : ManualTheme where
     highlightOnCode := color%#e3cfae,
     uiOnCode := color%#7a6952,
     keyword.color := color%#2f6e58,
-    const.color   := color%#a04050,
-    «var».color   := color%#3d2f1f
+    const.color := color%#a04050,
+    «var».color := color%#3d2f1f
   }
   textFace := .serif
   structureFace := .serif
@@ -491,7 +504,7 @@ public def ManualTheme.hearthDark : ManualTheme :=
     highlightOnCode := color%#5c4a00,
     uiOnCode := color%#a08a64,
     keyword.color := color%#9adcb0,
-    const.color   := color%#f5a8b8,
-    «var».color   := color%#f1e7d2
+    const.color := color%#f5a8b8,
+    «var».color := color%#f1e7d2
   }
   { base with textFace := .serif, structureFace := .serif }
diff --git a/src/verso-manual/VersoManual/Theme/Emit.lean b/src/verso-manual/VersoManual/Theme/Emit.lean
index 8aa6d8d53..951eb8c94 100644
--- a/src/verso-manual/VersoManual/Theme/Emit.lean
+++ b/src/verso-manual/VersoManual/Theme/Emit.lean
@@ -24,10 +24,16 @@ open Lean (Json)
 /-- The pieces of a theme that the picker / no-flash script need at runtime, JSON-encoded. -/
 private def themeJson (n : Lean.Name) (t : ManualTheme) : Json :=
   let appearance := match t.appearance with | .light => "light" | .dark => "dark"
+  let description : Json := t.description.map Json.str |>.getD .null
+  let sourceLink : Json := match t.sourceLink with
+    | none => .null
+    | some s => Json.mkObj [("url", Json.str s.url), ("text", Json.str s.text)]
   Json.mkObj [
     ("id", Json.str n.toString),
     ("name", Json.str t.name),
-    ("appearance", Json.str appearance)
+    ("appearance", Json.str appearance),
+    ("description", description),
+    ("sourceLink", sourceLink)
   ]
 
 /--
@@ -35,8 +41,8 @@ The contents of {lit}`-verso-data/verso-themes.js`. Exposes {lit}`window.versoTh
 shape `{ themes: [...], defaultLight, defaultDark, codeSample }` so the picker can render the
 choices and the live code preview.
 
-`codeSample` is a small fixed HTML string reusing the `.hl.lean` markup; the picker drops it
-inside a `data-verso-theme`-scoped element to show what each theme will look like.
+{name}`codeSample` is a small fixed HTML string reusing the {lit}`.hl.lean` markup; the picker drops it
+inside a {lit}`data-verso-theme`-scoped element to show what each theme will look like.
 -/
 public def windowVersoThemesJs
     (themes : ThemeRegistry)
@@ -114,16 +120,16 @@ Produces the body of {lit}`verso-themes.css`:
 
 - font-face rules from every available theme (one block per theme; content dedup is the caller's
   job);
-- an unscoped `:root` block carrying the {lit}`single`'s variables — what the server-rendered
-  HTML uses before the no-flash script attaches {lit}`data-verso-theme`. `single` is the
+- an unscoped `:root` block carrying the {name}`single`'s variables — what the server-rendered
+  HTML uses before the no-flash script attaches {lit}`data-verso-theme`. {name}`single` is the
   resolved single-mode default theme;
-- an `@media (prefers-color-scheme: dark)` block carrying the {Lean.Doc.name}`Verso.Theme.ManualTheme`
-  named by `defaultDark` (no-JS fallback only — the no-flash script always sets a concrete
+- an {lit}`@media (prefers-color-scheme: dark)` block carrying the {name}`Verso.Theme.ManualTheme`
+  named by {name}`defaultDark` (no-JS fallback only — the no-flash script always sets a concrete
   attribute);
 - one `:root[data-verso-theme="…"]` block per registered theme so the picker can swap themes by
   flipping the attribute.
 
-`single` is always one of the registered themes, so its font and asset URLs resolve against
+{name}`single` is always one of the registered themes, so its font and asset URLs resolve against
 the same {lit}`-verso-data/themes/<name>` root as the attribute-scoped blocks; no separate
 page-theme asset root is needed.
 -/
@@ -149,5 +155,3 @@ public def «verso-themes.css»
     unless extra.isEmpty do
       out := out ++ s!":where(:root[data-verso-theme=\"{n.toString}\"]) \{\n{extra}}\n"
   return out
-
-end Verso.Theme
diff --git a/src/verso/Verso/Code/HighlightedToTex.lean b/src/verso/Verso/Code/HighlightedToTex.lean
index be4f43ad5..7d78c83ce 100644
--- a/src/verso/Verso/Code/HighlightedToTex.lean
+++ b/src/verso/Verso/Code/HighlightedToTex.lean
@@ -23,8 +23,8 @@ namespace SubVerso.Highlighting
 Given an already escaped-for-verbatim string, and a token kind, returns TeX that wraps the
 content in the matching semantic macro: `\versoKeyword`, `\versoConst`, `\versoVar`, or
 `\versoLiteral`. The macros are defined by the consuming genre's preamble (the manual genre
-uses {Lean.Doc.name}`Verso.Theme.CodeTheme` to style them). For a fallback definition that
-reproduces the pre-theming look, see {Lean.Doc.name}`SubVerso.Highlighting.texMacroFallbacks`.
+uses {name}`Verso.Theme.CodeTheme` to style them). For a fallback definition that
+reproduces the pre-theming look, see {name}`SubVerso.Highlighting.texMacroFallbacks`.
 -/
 public def highlightToken : String → Token.Kind → TeX
 | c, .keyword _ _ _ => .raw s!"\\versoKeyword\{{c}}"
@@ -44,7 +44,7 @@ public def highlightToken : String → Token.Kind → TeX
 
 /--
 Fallback definitions for the four semantic token macros emitted by
-{Lean.Doc.name}`SubVerso.Highlighting.highlightToken`. Each uses `\providecommand`, so a genre
+{name}`SubVerso.Highlighting.highlightToken`. Each uses `\providecommand`, so a genre
 preamble that defines its own (theme-driven) versions wins. The fallbacks reproduce today's
 unthemed look: keywords bold, variables italic, constants and literals plain.
 -/
@@ -65,9 +65,9 @@ with command characters `\`, `{`, and `}`.
 When `lineBreaks` is true, inserts line break opportunities in identifiers.
 
 **Preamble contract.** Output uses the four `\verso…` semantic macros emitted by
-{Lean.Doc.name}`SubVerso.Highlighting.highlightToken`. Any consumer that compiles the result must
+{name}`SubVerso.Highlighting.highlightToken`. Any consumer that compiles the result must
 ensure those macros are defined, either by including
-{Lean.Doc.name}`SubVerso.Highlighting.texMacroFallbacks` in the preamble or by defining its own
+{name}`SubVerso.Highlighting.texMacroFallbacks` in the preamble or by defining its own
 theme-driven versions (the manual genre installs both).
 -/
 public defmethod Highlighted.toVerbatimTeX (h : Highlighted) (lineBreaks : Bool := false) : Verso.Output.TeX :=
diff --git a/src/verso/Verso/Theme/Code.lean b/src/verso/Verso/Theme/Code.lean
index e6b797ccf..ddff9722e 100644
--- a/src/verso/Verso/Theme/Code.lean
+++ b/src/verso/Verso/Theme/Code.lean
@@ -46,6 +46,18 @@ public structure ThemeAsset where
   /-- The asset bytes, embedded at compile time. -/
   contents : ByteArray
 
+/--
+A hyperlink shown in the picker alongside a theme: a URL plus the visible link text. Used to
+point readers at a theme's canonical reference (for example the Solarized homepage for a
+Solarized port, or a designer's portfolio page).
+-/
+public structure SourceLink where
+  /-- The URL the link points to. -/
+  url : String
+  /-- The visible link text. -/
+  text : String
+deriving Repr
+
 /--
 A typed code theme. Defaults reproduce today's hardcoded chrome, so a default-constructed theme is
 visually unchanged from the pre-theming look.
@@ -59,6 +71,18 @@ public structure CodeTheme where
   name : String
   /-- Whether this theme is intended for a light or a dark display. -/
   appearance : Appearance
+  /--
+  An optional one- or two-sentence description shown alongside the theme in the picker. Useful
+  for noting design intent, palette family, or accessibility trade-offs (for example "Solarized
+  Light — the canonical palette, below WCAG AA on prose by design").
+  -/
+  description : Option String := none
+  /--
+  An optional canonical reference for the theme: a URL plus link text shown next to the name
+  in the picker. Points readers at an upstream homepage or specification when the theme is a
+  port (Solarized, Dracula, etc.).
+  -/
+  sourceLink : Option SourceLink := none
 
   /-- The font used for code blocks and inline code. -/
   codeFace : Typeface := .mono
@@ -111,8 +135,14 @@ public structure CodeTheme where
   hoverSeparatorColor : Color := color%#cccccc
   /-- The background tint applied to a token on hover (independent of severity). -/
   tokenHighlightBackground : Color := color%#eeeeee
-  /-- The background of a displayed tactic state. -/
-  tacticStateBackground : Color := Color.white
+  /--
+  The background of a displayed tactic state. Defaults to the surrounding
+  {name (full := Verso.Theme.CodeTheme.codeBlockBackground)}`codeBlockBackground`, so a theme
+  that recolors the code surface gets a matching tactic-state surface for free; themes that
+  want a distinct tactic-state tint (a slight raise to differentiate it from code) override
+  it explicitly.
+  -/
+  tacticStateBackground : Color := codeBlockBackground
   /-- The border color of a displayed tactic state. -/
   tacticStateBorderColor : Color := color%#888888
 
@@ -142,7 +172,7 @@ public structure CodeTheme where
 public section
 
 /--
-Attribute that registers a {Lean.Doc.name}`CodeTheme` declaration as an available theme. The
+Attribute that registers a {name}`CodeTheme` declaration as an available theme. The
 declaration must be in the current module (not imported), and its registration name is the decl's
 name with macro scopes erased.
 -/
@@ -165,9 +195,9 @@ meta initialize
 end section
 
 /--
-A materialized table of registered {Lean.Doc.name}`CodeTheme` values, keyed by registration name.
+A materialized table of registered {name}`CodeTheme` values, keyed by registration name.
 Built at runtime by the {lit}`code_themes%` term elaborator from the set of
-{Lean.Doc.name}`CodeTheme` declarations tagged with the {lit}`@[code_theme]` attribute.
+{name}`CodeTheme` declarations tagged with the {lit}`@[code_theme]` attribute.
 -/
 public structure CodeThemeTable where
   /-- The map from a theme's registration name to its value. -/
@@ -207,8 +237,8 @@ private meta def themePair [Monad m] [MonadRef m] [MonadQuotation m] (n : Name)
 
 open Lean Elab Term in
 /--
-Elaborator for the {lit}`code_themes%` macro: emits a {Lean.Doc.name}`Verso.Theme.CodeThemeTable`
-literal whose entries are every registered {Lean.Doc.name}`Verso.Theme.CodeTheme` decl.
+Elaborator for the {lit}`code_themes%` macro: emits a {name}`Verso.Theme.CodeThemeTable`
+literal whose entries are every registered {name}`Verso.Theme.CodeTheme` decl.
 -/
 @[term_elab code_themes]
 meta def elabCodeThemes : TermElab := fun _stx expected? => do
@@ -236,13 +266,15 @@ private def tokenSummaries (theme : CodeTheme) : Array (String × Color) := #[
   ]
 
 /--
+{open Verso.Theme.Color}
+
 Checks a theme for contrast and color-vision-deficiency problems. The checker is pure and genre
-neutral: it returns an {Lean.Doc.name}`Array` of {Lean.Doc.name}`Verso.Theme.Color.Issue` values
-whose {Lean.Doc.name}`Verso.Theme.Color.Issue.kind` field a caller routes to its severity flag.
+neutral: it returns an {Lean.Doc.name}`Array` of {Lean.Doc.name}`Issue` values
+whose {Lean.Doc.name}`Issue.kind` field a caller routes to its severity flag.
 
 Body text uses the WCAG AA 4.5 threshold; UI accents and large-text positions use 3.0. Token
 distinguishability uses the CIEDE2000 threshold from
-{Lean.Doc.name}`Verso.Theme.Color.distinguishableThreshold`.
+{Lean.Doc.name}`distinguishableThreshold`.
 -/
 public def checkAccessibility (theme : CodeTheme) : Array Color.Issue := Id.run do
   let mut issues := #[]
@@ -392,7 +424,7 @@ private def tokenMacro (name : String) (s : TokenStyle) (colorName : String) : S
 Returns a TeX preamble fragment that defines a theme-specific {lit}`xcolor` palette, redefines
 the four {lit}`\verso…` token macros so they apply the theme's per-token color, weight, and
 style, and sets the document mono font to {Lean.Doc.name (full := Verso.Typeface.texFamily)}`Verso.Typeface.texFamily` applied to
-{Lean.Doc.name (full := Verso.Theme.CodeTheme.codeFace)}`codeFace`.
+{Lean.Doc.name}`codeFace`.
 
 Two color names are emitted per severity: {lit}`errorColor`/{lit}`warningColor`/{lit}`infoColor`
 are the message-text colors, and {lit}`errorIndicatorColor`/{lit}`warningIndicatorColor`/{lit}`infoIndicatorColor`
diff --git a/src/verso/Verso/Theme/Code/Defaults.lean b/src/verso/Verso/Theme/Code/Defaults.lean
index 399862b0b..6c871cf7d 100644
--- a/src/verso/Verso/Theme/Code/Defaults.lean
+++ b/src/verso/Verso/Theme/Code/Defaults.lean
@@ -11,7 +11,7 @@ set_option linter.missingDocs true
 set_option doc.verso true
 
 /-!
-The built-in {Lean.Doc.name}`Verso.Theme.CodeTheme` values. The default theme reproduces today's
+The built-in {name}`Verso.Theme.CodeTheme` values. The default theme reproduces today's
 hardcoded look so existing manuals render unchanged when no override is configured.
 -/
 
@@ -20,7 +20,7 @@ namespace Verso.Theme
 /--
 The default code theme: typography-only styling that reproduces today's hardcoded look. Named
 after the most ancient writing medium in use; other built-in themes live alongside it in the
-{Lean.Doc.name}`Verso.Theme.CodeTheme` namespace.
+{name}`Verso.Theme.CodeTheme` namespace.
 -/
 @[code_theme]
 public def CodeTheme.ink : CodeTheme where
diff --git a/src/verso/Verso/Theme/Color/OkabeIto.lean b/src/verso/Verso/Theme/Color/OkabeIto.lean
new file mode 100644
index 000000000..d8907ea8c
--- /dev/null
+++ b/src/verso/Verso/Theme/Color/OkabeIto.lean
@@ -0,0 +1,41 @@
+/-
+Copyright (c) 2026 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+public import Verso.Theme.Color.Basic
+public import Verso.Theme.Color.Syntax
+
+set_option linter.missingDocs true
+set_option doc.verso true
+
+/-!
+Masataka Okabe and Kei Ito's colorblind-safe palette (2002,
+<https://jfly.uni-koeln.de/color/>) as named {name}`Verso.Theme.Color` constants. The eight
+hues stay distinguishable under protanopia, deuteranopia, and tritanopia, so they are a
+standard reference set for data visualization and code highlighting that must remain readable
+to dichromat readers.
+-/
+
+namespace Verso.Theme.Color.OkabeIto
+
+/-- Okabe-Ito black: {lit}`#000000`. -/
+public def black : Color := color%#000000
+/-- Okabe-Ito orange: {lit}`#e69f00`. -/
+public def orange : Color := color%#e69f00
+/-- Okabe-Ito sky blue: {lit}`#56b4e9`. -/
+public def skyBlue : Color := color%#56b4e9
+/-- Okabe-Ito bluish green: {lit}`#009e73`. -/
+public def bluishGreen : Color := color%#009e73
+/-- Okabe-Ito yellow: {lit}`#f0e442`. -/
+public def yellow : Color := color%#f0e442
+/-- Okabe-Ito blue: {lit}`#0072b2`. -/
+public def blue : Color := color%#0072b2
+/-- Okabe-Ito vermillion: {lit}`#d55e00`. -/
+public def vermillion : Color := color%#d55e00
+/-- Okabe-Ito reddish purple: {lit}`#cc79a7`. -/
+public def reddishPurple : Color := color%#cc79a7
+
+end Verso.Theme.Color.OkabeIto
diff --git a/src/verso/Verso/Theme/Color/Solarized.lean b/src/verso/Verso/Theme/Color/Solarized.lean
new file mode 100644
index 000000000..36dea25e3
--- /dev/null
+++ b/src/verso/Verso/Theme/Color/Solarized.lean
@@ -0,0 +1,64 @@
+/-
+Copyright (c) 2026 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+public import Verso.Theme.Color.Basic
+public import Verso.Theme.Color.Syntax
+
+set_option linter.missingDocs true
+set_option doc.verso true
+
+/-!
+Ethan Schoonover's *Solarized* palette as named {name}`Verso.Theme.Color` constants. Sixteen
+colors: eight monotone shades (the {lit}`base*` ramp) plus eight accent hues. The hex values are
+the canonical ones from the upstream reference at <https://ethanschoonover.com/solarized/>.
+
+The ramp's design rule is that any {lit}`base0X` (with leading zero) is dark-mode body text and
+any {lit}`baseY` is light-mode body text; the rest progress symmetrically between background and
+foreground for each appearance.
+-/
+
+namespace Verso.Theme.Color.Solarized
+
+/-! # Monotone ramp -/
+
+/-- {lit}`base03` — Solarized dark background. -/
+public def base03 : Color := color%#002b36
+/-- {lit}`base02` — Solarized dark highlights / content background. -/
+public def base02 : Color := color%#073642
+/-- {lit}`base01` — Solarized comments / secondary content (dark). Light primary content. -/
+public def base01 : Color := color%#586e75
+/-- {lit}`base00` — Solarized light secondary content. -/
+public def base00 : Color := color%#657b83
+/-- {lit}`base0` — Solarized dark body text. -/
+public def base0 : Color := color%#839496
+/-- {lit}`base1` — Solarized dark comments / secondary content. -/
+public def base1 : Color := color%#93a1a1
+/-- {lit}`base2` — Solarized light highlights / content background. -/
+public def base2 : Color := color%#eee8d5
+/-- {lit}`base3` — Solarized light background. -/
+public def base3 : Color := color%#fdf6e3
+
+/-! # Accent hues -/
+
+/-- Solarized yellow. -/
+public def yellow : Color := color%#b58900
+/-- Solarized orange. -/
+public def orange : Color := color%#cb4b16
+/-- Solarized red. -/
+public def red : Color := color%#dc322f
+/-- Solarized magenta. -/
+public def magenta : Color := color%#d33682
+/-- Solarized violet. -/
+public def violet : Color := color%#6c71c4
+/-- Solarized blue. -/
+public def blue : Color := color%#268bd2
+/-- Solarized cyan. -/
+public def cyan : Color := color%#2aa198
+/-- Solarized green. -/
+public def green : Color := color%#859900
+
+end Verso.Theme.Color.Solarized
diff --git a/static-web/manual/theme/theme-picker.css b/static-web/manual/theme/theme-picker.css
index df06d567e..33b9c2c12 100644
--- a/static-web/manual/theme/theme-picker.css
+++ b/static-web/manual/theme/theme-picker.css
@@ -130,6 +130,34 @@
     overflow-x: auto;
 }
 
+#theme-picker-about {
+    /* Theme metadata (description + canonical link) sits below the code preview. Spans both
+       columns and uses the structure font so it reads as prose rather than code. */
+    grid-column: 1 / -1;
+    font-size: 0.85em;
+    line-height: 1.35;
+    color: var(--verso-muted-color, #555);
+    display: flex;
+    flex-direction: column;
+    gap: 0.3rem;
+}
+
+#theme-picker-about[hidden] {
+    display: none;
+}
+
+#theme-picker-about p {
+    margin: 0;
+}
+
+#theme-picker-about p[hidden] {
+    display: none;
+}
+
+#theme-picker-source a {
+    color: var(--verso-link-color, inherit);
+}
+
 @media (max-width: 600px) {
     /* Full-screen sheet on small screens. */
     #theme-picker-dialog {
diff --git a/static-web/manual/theme/theme-picker.js b/static-web/manual/theme/theme-picker.js
index d704984f3..27c24d886 100644
--- a/static-web/manual/theme/theme-picker.js
+++ b/static-web/manual/theme/theme-picker.js
@@ -182,11 +182,70 @@
         preview.innerHTML = data.codeSample || "";
         dialog.appendChild(preview);
 
+        // Per-theme metadata panel: description paragraph and source-link line. Rendered below
+        // the code sample so the visual order is [chooser] [code sample] [about this theme].
+        // Themes without description/sourceLink leave the panel empty (and hidden by CSS).
+        var about = document.createElement("div");
+        about.id = "theme-picker-about";
+        var aboutDesc = document.createElement("p");
+        aboutDesc.id = "theme-picker-description";
+        var aboutLink = document.createElement("p");
+        aboutLink.id = "theme-picker-source";
+        var aboutLinkAnchor = document.createElement("a");
+        aboutLinkAnchor.target = "_blank";
+        aboutLinkAnchor.rel = "noopener noreferrer";
+        aboutLink.appendChild(aboutLinkAnchor);
+        about.appendChild(aboutDesc);
+        about.appendChild(aboutLink);
+        dialog.appendChild(about);
+
+        function activeMetaTheme() {
+            var prefersDark =
+                window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches;
+            var id;
+            if (modeToggle.checked) {
+                id = prefersDark ? darkSel.select.value : lightSel.select.value;
+            } else {
+                id = singleSel.select.value;
+            }
+            return data.themes.find(function (t) {
+                return t.id === id;
+            });
+        }
+
+        function refreshAbout() {
+            var t = activeMetaTheme();
+            if (!t) {
+                about.hidden = true;
+                return;
+            }
+            // Hide rows individually so a theme with only one of the two doesn't leave an
+            // empty paragraph slot.
+            if (t.description) {
+                aboutDesc.textContent = t.description;
+                aboutDesc.hidden = false;
+            } else {
+                aboutDesc.hidden = true;
+                aboutDesc.textContent = "";
+            }
+            if (t.sourceLink && t.sourceLink.url && t.sourceLink.text) {
+                aboutLinkAnchor.href = t.sourceLink.url;
+                aboutLinkAnchor.textContent = t.sourceLink.text;
+                aboutLink.hidden = false;
+            } else {
+                aboutLink.hidden = true;
+                aboutLinkAnchor.removeAttribute("href");
+                aboutLinkAnchor.textContent = "";
+            }
+            about.hidden = aboutDesc.hidden && aboutLink.hidden;
+        }
+
         function refreshLayout() {
             var auto = modeToggle.checked;
             singleSel.row.hidden = auto;
             lightSel.row.hidden = !auto;
             darkSel.row.hidden = !auto;
+            refreshAbout();
         }
         refreshLayout();
 
@@ -224,7 +283,10 @@
             commit();
         });
         [singleSel.select, lightSel.select, darkSel.select].forEach(function (sel) {
-            sel.addEventListener("change", commit);
+            sel.addEventListener("change", function () {
+                commit();
+                refreshAbout();
+            });
             // No focus/hover preview: the picker commits immediately on `change`, so the
             // user already gets visible feedback when they pick an option. Firing a
             // preview on `focus` (or `mouseenter`) painted a stale "what's selected right

From 3036f7e684664ab82f1cd939a454f3890918060e Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Mon, 1 Jun 2026 08:42:25 +0200
Subject: [PATCH 14/31] reorganize palettes

---
 .../VersoManual/Theme/Defaults.lean           | 25 ++++++---------
 src/verso/Verso.lean                          |  4 +--
 src/verso/Verso/Theme.lean                    | 16 ++++++++++
 src/verso/Verso/Theme/Code.lean               | 13 +-------
 src/verso/Verso/Theme/Code/Defaults.lean      |  4 +--
 src/verso/Verso/Theme/Code/Ext.lean           | 10 +++---
 src/verso/Verso/Theme/Color.lean              |  1 +
 src/verso/Verso/Theme/Color/Palettes.lean     | 17 ++++++++++
 .../Theme/Color/{ => Palettes}/OkabeIto.lean  | 16 ++++++++--
 .../Theme/Color/{ => Palettes}/Solarized.lean | 15 +++++++--
 src/verso/Verso/Theme/SourceLink.lean         | 31 +++++++++++++++++++
 11 files changed, 112 insertions(+), 40 deletions(-)
 create mode 100644 src/verso/Verso/Theme.lean
 create mode 100644 src/verso/Verso/Theme/Color/Palettes.lean
 rename src/verso/Verso/Theme/Color/{ => Palettes}/OkabeIto.lean (72%)
 rename src/verso/Verso/Theme/Color/{ => Palettes}/Solarized.lean (81%)
 create mode 100644 src/verso/Verso/Theme/SourceLink.lean

diff --git a/src/verso-manual/VersoManual/Theme/Defaults.lean b/src/verso-manual/VersoManual/Theme/Defaults.lean
index 63f072fbf..74c263513 100644
--- a/src/verso-manual/VersoManual/Theme/Defaults.lean
+++ b/src/verso-manual/VersoManual/Theme/Defaults.lean
@@ -7,8 +7,7 @@ module
 
 public import VersoManual.Theme
 public import Verso.Theme.Code.Defaults
-public import Verso.Theme.Color.Solarized
-public import Verso.Theme.Color.OkabeIto
+public import Verso.Theme.Color.Palettes
 
 set_option linter.missingDocs true
 set_option doc.verso true
@@ -155,6 +154,7 @@ public def ManualTheme.beaconLight : ManualTheme where
   toCodeTheme := {
     CodeTheme.ink with
     name := "Beacon Light",
+    sourceLink := some Color.Palettes.OkabeIto.sourceLink,
     keyword.color := color%#005b8c,
     const.color := color%#5b3500,
     «var».color := color%#9c2400
@@ -169,14 +169,15 @@ public def ManualTheme.beaconDark : ManualTheme :=
   darkChromeFields {
     darkCodeBase with
     name := "Beacon Dark",
-    keyword.color := color%#56b4e9,
+    sourceLink := some Color.Palettes.OkabeIto.sourceLink,
+    keyword.color := Color.Palettes.OkabeIto.skyBlue,
     const.color := color%#5bd6a4,
     «var».color := color%#f5a85a
   }
 
 /-! # Solarized — Ethan Schoonover's standard palette -/
 
-open Color.Solarized in
+open Color.Palettes.Solarized in
 /--
 Solarized light: Schoonover's standard cream-on-paper palette
 ({lit}`base3` background, {lit}`base01` primary content). Token accents reuse the named hues
@@ -187,11 +188,8 @@ public def ManualTheme.solarizedLight : ManualTheme :=
   {
     toCodeTheme := {
       CodeTheme.ink with
-      name := "Solarized Light",
-      sourceLink := some {
-        url := "https://ethanschoonover.com/solarized/",
-        text := "ethanschoonover.com/solarized"
-      },
+      name := s!"{Color.Palettes.Solarized.name} Light",
+      sourceLink := some Color.Palettes.Solarized.sourceLink,
       background := base3,
       codeBlockBackground := base2,
       textColor := base01,
@@ -224,7 +222,7 @@ public def ManualTheme.solarizedLight : ManualTheme :=
     visitedLinkColor := violet
   }
 
-open Color.Solarized in
+open Color.Palettes.Solarized in
 /--
 Solarized dark: Schoonover's standard {lit}`base03` background with body text on {lit}`base1`.
 Token accents are brightened off the standard palette so they keep clear contrast on the dark
@@ -234,11 +232,8 @@ substrate.
 public def ManualTheme.solarizedDark : ManualTheme :=
   darkChromeFields {
     darkCodeBase with
-    name := "Solarized Dark",
-    sourceLink := some {
-      url := "https://ethanschoonover.com/solarized/",
-      text := "ethanschoonover.com/solarized"
-    },
+    name := s!"{Color.Palettes.Solarized.name} Dark",
+    sourceLink := some Color.Palettes.Solarized.sourceLink,
     background := base03,
     codeBlockBackground := base02,
     textColor := base1,
diff --git a/src/verso/Verso.lean b/src/verso/Verso.lean
index 4735bd49f..a2590e881 100644
--- a/src/verso/Verso.lean
+++ b/src/verso/Verso.lean
@@ -8,9 +8,7 @@ module
 -- Import modules here that should be built as part of the library.
 public import Verso.CLI
 public import Verso.Code
-public import Verso.Theme.Code
-public import Verso.Theme.Code.Defaults
-public import Verso.Theme.Color
+public import Verso.Theme
 public import Verso.Doc
 public import Verso.Doc.ArgParse
 public import Verso.Doc.Concrete
diff --git a/src/verso/Verso/Theme.lean b/src/verso/Verso/Theme.lean
new file mode 100644
index 000000000..80838f378
--- /dev/null
+++ b/src/verso/Verso/Theme.lean
@@ -0,0 +1,16 @@
+/-
+Copyright (c) 2026 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+public import Verso.Theme.Color
+public import Verso.Theme.Code
+public import Verso.Theme.Code.Defaults
+
+/-!
+The full theme API: typed colors, color math and accessibility checks, named reference
+palettes, and the genre-neutral {lit}`CodeTheme` with its built-in defaults. Genres that
+need theme support (the manual genre) re-export their own theme additions on top of this.
+-/
diff --git a/src/verso/Verso/Theme/Code.lean b/src/verso/Verso/Theme/Code.lean
index ddff9722e..1673a4e75 100644
--- a/src/verso/Verso/Theme/Code.lean
+++ b/src/verso/Verso/Theme/Code.lean
@@ -8,6 +8,7 @@ module
 public meta import Verso.Theme.Code.Ext
 public import Verso.Theme.Color
 public import Verso.Theme.Color.Accessibility
+public import Verso.Theme.SourceLink
 public import Verso.Font
 public meta import Lean.Elab.Term
 
@@ -46,18 +47,6 @@ public structure ThemeAsset where
   /-- The asset bytes, embedded at compile time. -/
   contents : ByteArray
 
-/--
-A hyperlink shown in the picker alongside a theme: a URL plus the visible link text. Used to
-point readers at a theme's canonical reference (for example the Solarized homepage for a
-Solarized port, or a designer's portfolio page).
--/
-public structure SourceLink where
-  /-- The URL the link points to. -/
-  url : String
-  /-- The visible link text. -/
-  text : String
-deriving Repr
-
 /--
 A typed code theme. Defaults reproduce today's hardcoded chrome, so a default-constructed theme is
 visually unchanged from the pre-theming look.
diff --git a/src/verso/Verso/Theme/Code/Defaults.lean b/src/verso/Verso/Theme/Code/Defaults.lean
index 6c871cf7d..399862b0b 100644
--- a/src/verso/Verso/Theme/Code/Defaults.lean
+++ b/src/verso/Verso/Theme/Code/Defaults.lean
@@ -11,7 +11,7 @@ set_option linter.missingDocs true
 set_option doc.verso true
 
 /-!
-The built-in {name}`Verso.Theme.CodeTheme` values. The default theme reproduces today's
+The built-in {Lean.Doc.name}`Verso.Theme.CodeTheme` values. The default theme reproduces today's
 hardcoded look so existing manuals render unchanged when no override is configured.
 -/
 
@@ -20,7 +20,7 @@ namespace Verso.Theme
 /--
 The default code theme: typography-only styling that reproduces today's hardcoded look. Named
 after the most ancient writing medium in use; other built-in themes live alongside it in the
-{name}`Verso.Theme.CodeTheme` namespace.
+{Lean.Doc.name}`Verso.Theme.CodeTheme` namespace.
 -/
 @[code_theme]
 public def CodeTheme.ink : CodeTheme where
diff --git a/src/verso/Verso/Theme/Code/Ext.lean b/src/verso/Verso/Theme/Code/Ext.lean
index 2deb49c99..d71f78156 100644
--- a/src/verso/Verso/Theme/Code/Ext.lean
+++ b/src/verso/Verso/Theme/Code/Ext.lean
@@ -6,6 +6,9 @@ Author: David Thrane Christiansen
 module
 public import Lean.Environment
 
+set_option doc.verso true
+set_option linter.missingDocs true
+
 public section
 
 open Lean
@@ -13,12 +16,11 @@ open Lean
 namespace Verso.Theme
 
 /--
-Environment extension that records every declaration tagged with the `@[code_theme]` attribute.
-Each entry maps the registration name (the decl, erased of macro scopes) to itself, so the table
-is keyed and iterated by registration name.
+Environment extension recording the set of declarations tagged with the {lit}`@[code_theme]`
+attribute.
 -/
 initialize codeThemeExt :
-    PersistentEnvExtension Name Name (NameSet) ←
+    PersistentEnvExtension Name Name NameSet ←
   registerPersistentEnvExtension {
     mkInitial := pure {},
     addImportedFn := fun _ => pure {},
diff --git a/src/verso/Verso/Theme/Color.lean b/src/verso/Verso/Theme/Color.lean
index 16e17c2ee..ad43cd4b4 100644
--- a/src/verso/Verso/Theme/Color.lean
+++ b/src/verso/Verso/Theme/Color.lean
@@ -11,3 +11,4 @@ public import Verso.Theme.Color.Math
 public import Verso.Theme.Color.Accessibility
 public import Verso.Theme.Color.Widget
 public import Verso.Theme.Color.Syntax
+public import Verso.Theme.Color.Palettes
diff --git a/src/verso/Verso/Theme/Color/Palettes.lean b/src/verso/Verso/Theme/Color/Palettes.lean
new file mode 100644
index 000000000..d6c132e02
--- /dev/null
+++ b/src/verso/Verso/Theme/Color/Palettes.lean
@@ -0,0 +1,17 @@
+/-
+Copyright (c) 2026 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+public import Verso.Theme.Color.Palettes.Solarized
+public import Verso.Theme.Color.Palettes.OkabeIto
+
+/-!
+Named reference palettes used by the shipped themes. Each palette module exposes:
+
+- a {lit}`name : String` and {lit}`sourceLink : SourceLink` for the picker to display
+  alongside themes that build on the palette;
+- a set of named {name}`Verso.Theme.Color` constants holding the canonical hex values.
+-/
diff --git a/src/verso/Verso/Theme/Color/OkabeIto.lean b/src/verso/Verso/Theme/Color/Palettes/OkabeIto.lean
similarity index 72%
rename from src/verso/Verso/Theme/Color/OkabeIto.lean
rename to src/verso/Verso/Theme/Color/Palettes/OkabeIto.lean
index d8907ea8c..09cfc8cc5 100644
--- a/src/verso/Verso/Theme/Color/OkabeIto.lean
+++ b/src/verso/Verso/Theme/Color/Palettes/OkabeIto.lean
@@ -7,6 +7,7 @@ module
 
 public import Verso.Theme.Color.Basic
 public import Verso.Theme.Color.Syntax
+public import Verso.Theme.SourceLink
 
 set_option linter.missingDocs true
 set_option doc.verso true
@@ -19,7 +20,18 @@ standard reference set for data visualization and code highlighting that must re
 to dichromat readers.
 -/
 
-namespace Verso.Theme.Color.OkabeIto
+namespace Verso.Theme.Color.Palettes.OkabeIto
+
+/-! # Identity -/
+
+/-- The palette's display name, suitable as a prefix when naming themes built on it. -/
+public def name : String := "Okabe-Ito"
+
+/-- The canonical Okabe-Ito reference page, shown in the picker for themes that use it. -/
+public def sourceLink : Verso.Theme.SourceLink :=
+  { url := "https://jfly.uni-koeln.de/color/", text := "jfly.uni-koeln.de/color" }
+
+/-! # Hues -/
 
 /-- Okabe-Ito black: {lit}`#000000`. -/
 public def black : Color := color%#000000
@@ -38,4 +50,4 @@ public def vermillion : Color := color%#d55e00
 /-- Okabe-Ito reddish purple: {lit}`#cc79a7`. -/
 public def reddishPurple : Color := color%#cc79a7
 
-end Verso.Theme.Color.OkabeIto
+end Verso.Theme.Color.Palettes.OkabeIto
diff --git a/src/verso/Verso/Theme/Color/Solarized.lean b/src/verso/Verso/Theme/Color/Palettes/Solarized.lean
similarity index 81%
rename from src/verso/Verso/Theme/Color/Solarized.lean
rename to src/verso/Verso/Theme/Color/Palettes/Solarized.lean
index 36dea25e3..618a31011 100644
--- a/src/verso/Verso/Theme/Color/Solarized.lean
+++ b/src/verso/Verso/Theme/Color/Palettes/Solarized.lean
@@ -7,6 +7,7 @@ module
 
 public import Verso.Theme.Color.Basic
 public import Verso.Theme.Color.Syntax
+public import Verso.Theme.SourceLink
 
 set_option linter.missingDocs true
 set_option doc.verso true
@@ -21,7 +22,17 @@ any {lit}`baseY` is light-mode body text; the rest progress symmetrically betwee
 foreground for each appearance.
 -/
 
-namespace Verso.Theme.Color.Solarized
+namespace Verso.Theme.Color.Palettes.Solarized
+
+/-! # Identity -/
+
+/-- The palette's display name, suitable as a prefix when naming themes built on it. -/
+public def name : String := "Solarized"
+
+/-- The canonical Solarized homepage, shown in the picker for themes that use this palette. -/
+public def sourceLink : Verso.Theme.SourceLink :=
+  { url := "https://ethanschoonover.com/solarized/",
+    text := "ethanschoonover.com/solarized" }
 
 /-! # Monotone ramp -/
 
@@ -61,4 +72,4 @@ public def cyan : Color := color%#2aa198
 /-- Solarized green. -/
 public def green : Color := color%#859900
 
-end Verso.Theme.Color.Solarized
+end Verso.Theme.Color.Palettes.Solarized
diff --git a/src/verso/Verso/Theme/SourceLink.lean b/src/verso/Verso/Theme/SourceLink.lean
new file mode 100644
index 000000000..4dadb289a
--- /dev/null
+++ b/src/verso/Verso/Theme/SourceLink.lean
@@ -0,0 +1,31 @@
+/-
+Copyright (c) 2026 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+module
+
+set_option linter.missingDocs true
+set_option doc.verso true
+
+/-!
+A small reusable hyperlink type used by themes and palettes to point readers at canonical
+references (a Solarized homepage, a designer's portfolio, a palette specification, etc.).
+Lives in its own module so palette modules can expose a {lit}`SourceLink` value without
+depending on the full {lit}`CodeTheme` machinery.
+-/
+
+namespace Verso.Theme
+
+/--
+A hyperlink: the URL plus the visible link text. Surfaced by the picker UI alongside a theme
+or palette so readers can follow the link to its canonical reference.
+-/
+public structure SourceLink where
+  /-- The URL the link points to. -/
+  url : String
+  /-- The visible link text. -/
+  text : String
+deriving Repr
+
+end Verso.Theme

From 15b38b8c3610c8742c785549f4dc66f6a23cad26 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Mon, 1 Jun 2026 09:15:52 +0200
Subject: [PATCH 15/31] more cleanup

---
 src/verso-manual/VersoManual.lean             | 24 ++++++++-----
 src/verso-manual/VersoManual/Basic.lean       | 10 +++---
 src/verso-manual/VersoManual/Html/Config.lean | 17 ++++++---
 .../VersoManual/LicenseInfo/Licenses.lean     | 27 ++++++++++++++
 src/verso-manual/VersoManual/Theme.lean       | 23 +++++++-----
 .../VersoManual/Theme/Defaults.lean           | 31 ++++++++++------
 src/verso-manual/VersoManual/Theme/Emit.lean  |  2 +-
 src/verso/Verso/BuildLog.lean                 |  4 +--
 src/verso/Verso/Code/HighlightedToTex.lean    |  2 +-
 src/verso/Verso/Theme/Code.lean               | 24 ++++++-------
 src/verso/Verso/Theme/Code/Defaults.lean      | 12 ++++---
 src/verso/Verso/Theme/Color/Palettes.lean     |  4 ++-
 .../Verso/Theme/Color/Palettes/OkabeIto.lean  | 13 +++----
 .../Verso/Theme/Color/Palettes/Solarized.lean | 36 ++++++++++++++++---
 14 files changed, 157 insertions(+), 72 deletions(-)

diff --git a/src/verso-manual/VersoManual.lean b/src/verso-manual/VersoManual.lean
index c176350fc..1979c12c2 100644
--- a/src/verso-manual/VersoManual.lean
+++ b/src/verso-manual/VersoManual.lean
@@ -247,7 +247,7 @@ structure Config extends HtmlConfig, TeXConfig, OutputConfig where
   When true (the default), it is an error if no theme is accessible. When false the same problems
   become warnings.
 
-  A theme counts as "accessible" if its `Verso.Theme.ManualTheme.checkAccessibility` returns no
+  A theme counts as "accessible" if its `ManualTheme.checkAccessibility` returns no
   issues. In other words:
    * Every checked color pair meets the WCAG AA contrast threshold
    * Every pair of token colors stays mutually distinguishable under each of the three dichromacies
@@ -290,12 +290,12 @@ structure RenderConfig extends Config where
   availableThemes : Option NameSet := none
   /--
   The default light-appearance theme. Its registration name must be a registered
-  `Verso.Theme.ManualTheme` whose appearance is `.light`.
+  `ManualTheme` whose appearance is `.light`.
   -/
   defaultLightTheme : Name := ``Verso.Theme.ManualTheme.ink
   /--
   The default dark-appearance theme. Its registration name must be a registered
-  `Verso.Theme.ManualTheme` whose appearance is `.dark`.
+  `ManualTheme` whose appearance is `.dark`.
   -/
   defaultDarkTheme : Name := ``Verso.Theme.ManualTheme.argent
   /--
@@ -386,6 +386,12 @@ def TraverseState.ofConfig (config : HtmlConfig) : TraverseState := Id.run do
 def traverse (text : Part Manual) (config : Config) : EmitM (Part Manual × TraverseState) := do
   let topCtxt : Manual.TraverseContext := { draft := config.draft }
   let mut state : Manual.TraverseState := .ofConfig config.toHtmlConfig
+  -- Themes contribute their own third-party licenses (color palettes, fonts) on top of the
+  -- HtmlFeature ones already collected by `TraverseState.ofConfig`.
+  let registry ← readThe ThemeRegistry
+  for (_, theme) in registry do
+    for li in theme.licenses do
+      state := state.addLicenseInfo li
   let mut text := text
   if !config.draft then
     text := removeDraftParts text
@@ -448,8 +454,8 @@ def defaultSingleName (config : RenderConfig) : Lean.Name :=
   | .dark => config.defaultDarkTheme
 
 /--
-The single-default `Verso.Theme.ManualTheme` resolved from the active
-{name}`Verso.Theme.ThemeRegistry`. This is the theme that drives
+The single-default `ManualTheme` resolved from the active
+{name}`ThemeRegistry`. This is the theme that drives
 `verso-themes.css`'s unscoped `:root` block — what the server-rendered HTML paints on first
 visit (before the no-flash script attaches a `data-verso-theme`) — and the TeX code styling.
 
@@ -1179,7 +1185,7 @@ where
     theme and the specific issues.
 
   A theme counts as "accessible" iff its
-  `Verso.Theme.ManualTheme.checkAccessibility` returns no issues.
+  `ManualTheme.checkAccessibility` returns no issues.
   -/
   runThemeAccessibilityCheck (cfg : RenderConfig) (registry : ThemeRegistry) :
       ReaderT ExtensionImpls (BuildLogT IO) Unit := do
@@ -1220,10 +1226,10 @@ where
     checkDefault "defaultDarkTheme" cfg.defaultDarkTheme
 
   /--
-  Builds the active {name}`Verso.Theme.ThemeRegistry` from the registered
-  `Verso.Theme.ManualTheme` table, filters it by the configured
+  Builds the active {name}`ThemeRegistry` from the registered
+  `ManualTheme` table, filters it by the configured
   `availableThemes`, and routes every
-  `Verso.Theme.ManualThemeTable.ValidationError` through `MonadBuildLog` as an error.
+  `ManualThemeTable.ValidationError` through `MonadBuildLog` as an error.
   -/
   resolveThemeRegistry (cfg : RenderConfig)
       (table : Verso.Theme.ManualThemeTable) :
diff --git a/src/verso-manual/VersoManual/Basic.lean b/src/verso-manual/VersoManual/Basic.lean
index 098704edd..58e470325 100644
--- a/src/verso-manual/VersoManual/Basic.lean
+++ b/src/verso-manual/VersoManual/Basic.lean
@@ -680,13 +680,11 @@ end Manual
 
 /--
 The monad in which TeX descriptor implementations (`BlockDescr.toTeX`,
-`InlineDescr.toTeX`) and the TeX emit pipeline run. Reads the resolved
-`Verso.Theme.ThemeRegistry`, the extension implementations table, and logs through the build
-log.
+`InlineDescr.toTeX`) and the TeX emit pipeline run. Reads the resolved `ThemeRegistry`, the
+extension implementations table, and logs through the build log.
 
-Defined here (rather than in `VersoManual.lean`) so descriptor type signatures can name it
-without forward references. {name}`Verso.Genre.Manual.EmitM` is an alias to this from
-`VersoManual.lean`.
+Defined here (not in `VersoManual.lean`) so descriptor type signatures can name it without
+forward references.
 -/
 public abbrev Manual.EmitM : Type → Type :=
   ReaderT Verso.Theme.ThemeRegistry (ReaderT Manual.ExtensionImpls (BuildLogT IO))
diff --git a/src/verso-manual/VersoManual/Html/Config.lean b/src/verso-manual/VersoManual/Html/Config.lean
index e2a62dadc..4c47ee5a4 100644
--- a/src/verso-manual/VersoManual/Html/Config.lean
+++ b/src/verso-manual/VersoManual/Html/Config.lean
@@ -13,22 +13,29 @@ public import VersoManual.Html.Features
 public import VersoManual.Html.JsFile
 public import VersoManual.LicenseInfo
 
+set_option doc.verso true
+set_option linter.missingDocs true
+
 namespace Verso.Genre.Manual
 open Lean
 
+/--
+Configures the HTML used to render a manual.
+-/
 public structure HtmlConfig extends HtmlAssets where
   htmlDepth := 2
   extraFilesHtml : List (System.FilePath × String) := []
-  /-- Extra elements to add to every page's `head` tag -/
+  /-- Extra elements to add to every page's {lit}`head` tag -/
   extraHead : Array Output.Html := #[]
   /-- Extra elements to add to every page's contents -/
   extraContents : Array Output.Html := #[]
   /-- The URL from which to draw the logo to show, if any -/
   logo : Option String := none
   /--
+  {open HtmlConfig}
   The URL from which to draw the dark-appearance logo, if any. When set, the page renders both
-  the {lit}`logo` and {lit}`logoDark` images and CSS toggles them via {lit}`data-verso-appearance`.
-  When unset, {lit}`logo` is used in both appearances.
+  the {name}`logo` and {name}`logoDark` images and CSS toggles them via {lit}`data-verso-appearance`.
+  When unset, {name}`logo` is used in both appearances.
   -/
   logoDark : Option String := none
   /-- The URL that the logo should link to, if any (default is site root) -/
@@ -39,12 +46,12 @@ public structure HtmlConfig extends HtmlAssets where
   issueLink : Option String := none
   /--
   How deep should the local table of contents on each non-leaf HTML page?
-  `none` means "unlimited".
+  {name}`none` means "unlimited".
   -/
   sectionTocDepth : Option Nat := some 1
   /--
   How deep should the local table of contents on the root HTML page?
-  `none` means "unlimited".
+  {name}`none` means "unlimited".
   -/
   rootTocDepth : Option Nat := some 1
   -- This overrides the default value in HtmlAssets. That type may be used in other contexts where
diff --git a/src/verso-manual/VersoManual/LicenseInfo/Licenses.lean b/src/verso-manual/VersoManual/LicenseInfo/Licenses.lean
index 0ca2ea650..eecd51f1d 100644
--- a/src/verso-manual/VersoManual/LicenseInfo/Licenses.lean
+++ b/src/verso-manual/VersoManual/LicenseInfo/Licenses.lean
@@ -179,3 +179,30 @@ thereof, including modifications:
  * Notice of any changes or modifications, through a copyright statement on the new code or document such as "This software or document includes material copied from or derived from "Editable Combobox With Both List and Inline Autocomplete Example" at https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-both/. Copyright © 2024 World Wide Web Consortium. https://www.w3.org/copyright/software-license-2023/"
 
 "#
+
+public def solarized : LicenseInfo where
+  identifier := "MIT"
+  dependency := "Solarized"
+  howUsed := some "The Solarized Light and Solarized Dark themes reproduce the canonical Solarized color palette by Ethan Schoonover."
+  link := some "https://ethanschoonover.com/solarized/"
+  text := #[(some "The MIT License",
+r#"
+Copyright (c) 2011 Ethan Schoonover
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+"#)]
diff --git a/src/verso-manual/VersoManual/Theme.lean b/src/verso-manual/VersoManual/Theme.lean
index 4fb03ccc4..530fd6e29 100644
--- a/src/verso-manual/VersoManual/Theme.lean
+++ b/src/verso-manual/VersoManual/Theme.lean
@@ -7,6 +7,7 @@ module
 
 public meta import VersoManual.Theme.Ext
 public import Verso.Theme.Code
+public import VersoManual.LicenseInfo
 public meta import Lean.Elab.Term
 
 set_option linter.missingDocs true
@@ -20,15 +21,16 @@ theme.
 -/
 
 open Lean (Name)
+open Verso.Genre.Manual
 
 namespace Verso.Theme
 
 /--
-A manual-genre theme: a {name}`Verso.Theme.CodeTheme` plus the color and font fields the
+A manual-genre theme: a {name}`CodeTheme` plus the color and font fields the
 chrome needs (header background, ToC, burger menu, search box, content links). Defaults reproduce
 today's chrome.
 
-The cascade rule from {name}`Verso.Theme.CodeTheme` continues: a field that today reads
+The cascade rule from {name}`CodeTheme` continues: a field that today reads
 the page background or text color defaults from the inherited field, so overriding the inherited
 field carries through.
 -/
@@ -72,6 +74,11 @@ public structure ManualTheme extends CodeTheme where
   /-- The shadow color drawn under the burger-menu lines while the ToC is hidden. -/
   burgerHiddenShadowColor : Color := Color.white
 
+  /--
+  Third-party licenses the theme draws on (color palettes, fonts, etc.).
+  -/
+  licenses : Array LicenseInfo := #[]
+
 /-! # Attribute and materialization -/
 
 public section
@@ -155,8 +162,8 @@ private meta def manualThemePair [Monad m] [MonadRef m] [MonadQuotation m] (n :
 open Lean Elab Term in
 /--
 Elaborator for the {lit}`manual_themes%` macro: emits a
-{name}`Verso.Theme.ManualThemeTable` literal whose entries are every registered
-{name}`Verso.Theme.ManualTheme` decl.
+{name}`ManualThemeTable` literal whose entries are every registered
+{name}`ManualTheme` decl.
 -/
 @[term_elab manual_themes]
 meta def elabManualThemes : TermElab := fun _stx expected? => do
@@ -184,8 +191,8 @@ private def colorDecl (name : String) (c : Color) : String :=
 
 /--
 The CSS-variable body for the manual-chrome fields a {name}`ManualTheme` adds on top of
-its inherited {name}`Verso.Theme.CodeTheme`. The manual genre concatenates this with
-{name}`Verso.Theme.CodeTheme.cssVariables` to produce the contents of its
+its inherited {name}`CodeTheme`. The manual genre concatenates this with
+{name}`CodeTheme.cssVariables` to produce the contents of its
 {lit}`:root` block.
 -/
 public def manualCssVariables (theme : ManualTheme) : String :=
@@ -209,7 +216,7 @@ public def manualCssVariables (theme : ManualTheme) : String :=
 
 /--
 The full CSS-variable body for a {name}`ManualTheme`: the inherited
-{name}`Verso.Theme.CodeTheme` variables followed by the manual-chrome additions. This is
+{name}`CodeTheme` variables followed by the manual-chrome additions. This is
 what the manual genre writes into the body of {lit}`verso-themes.css`'s {lit}`:root` block.
 -/
 public def cssVariables (theme : ManualTheme) : String :=
@@ -222,7 +229,7 @@ end ManualTheme
 namespace ManualTheme
 
 /--
-Runs the inherited {name}`Verso.Theme.CodeTheme.checkAccessibility` and then verifies the
+Runs the inherited {name}`CodeTheme.checkAccessibility` and then verifies the
 manual-chrome pairs:
 
 - content {name}`linkColor` and {name}`visitedLinkColor` against the page background
diff --git a/src/verso-manual/VersoManual/Theme/Defaults.lean b/src/verso-manual/VersoManual/Theme/Defaults.lean
index 74c263513..6f3aa5490 100644
--- a/src/verso-manual/VersoManual/Theme/Defaults.lean
+++ b/src/verso-manual/VersoManual/Theme/Defaults.lean
@@ -6,6 +6,7 @@ Author: David Thrane Christiansen
 module
 
 public import VersoManual.Theme
+public import VersoManual.LicenseInfo.Licenses
 public import Verso.Theme.Code.Defaults
 public import Verso.Theme.Color.Palettes
 
@@ -13,7 +14,9 @@ set_option linter.missingDocs true
 set_option doc.verso true
 
 /-!
-Built-in {name}`Verso.Theme.ManualTheme` values. The default theme reproduces today's
+{open Verso.Theme}
+
+Built-in {name}`ManualTheme` values. The default theme reproduces today's
 chrome so existing manuals render unchanged when no override is configured. The dark counterpart
 inverts the page and code backgrounds while preserving the typography-only token rendering.
 
@@ -30,7 +33,7 @@ The light default manual theme. Named after the most ancient writing medium in u
 inks made from soot or oak gall that have carried text for two thousand years. Typography and
 chrome reproduce today's hardcoded look.
 
-Other built-in themes live alongside it in the {name}`Verso.Theme.ManualTheme` namespace.
+Other built-in themes live alongside it in the {name}`ManualTheme` namespace.
 -/
 @[manual_theme]
 public def ManualTheme.ink : ManualTheme where
@@ -39,7 +42,7 @@ public def ManualTheme.ink : ManualTheme where
 /--
 A common dark-appearance code-theme base: deep-charcoal backgrounds, brightened text, accent
 colors chosen for readability against the dark substrate. Other dark themes extend this. Every
-cascading field is overridden explicitly because Lean evaluates the {name}`Verso.Theme.CodeTheme`
+cascading field is overridden explicitly because Lean evaluates the {name}`CodeTheme`
 defaults at construction time, so {lit}`CodeTheme.ink with textColor := …` would otherwise
 leave dependent fields (token colors, message text colors, hover text) frozen at their
 original-light values.
@@ -85,8 +88,8 @@ A common dark-appearance chrome base reused by the shipped dark themes. The chro
 inherit from the dark code base where possible (so a uniform dark look) and use explicit values
 where contrast requires lighter chrome accents (borders, muted text, links). The burger menu
 lines pick up the text color (so the lines themselves are visible against the page background;
-without this override they default to the light theme's near-black `#0e2431`, which is
-invisible on a dark substrate and shows only the surrounding `drop-shadow`).
+without this override they default to the light theme's near-black {lit}`#0e2431`, which is
+invisible on a dark substrate and shows only the surrounding {lit}`drop-shadow`).
 -/
 private def darkChromeFields (code : CodeTheme) : ManualTheme := {
   toCodeTheme := code,
@@ -107,7 +110,7 @@ The dark default manual theme. Named after silver, the ink of choice for the dar
 manuscript traditions: silver-on-purple Byzantine and Carolingian codices like the *Codex
 Argenteus*, Flemish "Black Hours" such as Morgan MS M.493, and Korean *eunja sagyeong* (은자사경)
 sutras transcribed in silver ink on indigo *kamji* paper during the Goryeo dynasty. Same
-typography-only token rendering as {name}`Verso.Theme.ManualTheme.ink`, with inverted
+typography-only token rendering as {name}`ManualTheme.ink`, with inverted
 backgrounds and a light text color.
 -/
 @[manual_theme]
@@ -219,7 +222,8 @@ public def ManualTheme.solarizedLight : ManualTheme :=
     borderColor := base01,
     mutedColor := base00,
     linkColor := blue,
-    visitedLinkColor := violet
+    visitedLinkColor := violet,
+    licenses := #[Verso.Genre.Manual.Licenses.solarized]
   }
 
 open Color.Palettes.Solarized in
@@ -230,7 +234,7 @@ substrate.
 -/
 @[manual_theme]
 public def ManualTheme.solarizedDark : ManualTheme :=
-  darkChromeFields {
+  { darkChromeFields {
     darkCodeBase with
     name := s!"{Color.Palettes.Solarized.name} Dark",
     sourceLink := some Color.Palettes.Solarized.sourceLink,
@@ -257,9 +261,14 @@ public def ManualTheme.solarizedDark : ManualTheme :=
     keyword.color := color%#b3d100,
     const.color := color%#6cb6ff,
     «var».color := color%#a98aff
-  }
+  } with
+    -- Override the dark-chrome link defaults with the canonical Solarized blue/violet (they
+    -- clear contrast on `base03`).
+    linkColor := blue,
+    visitedLinkColor := violet,
+    licenses := #[Verso.Genre.Manual.Licenses.solarized] }
 
-/-! # Sandstone — warm sepia (Rust/Ayu inspired) -/
+/-! # Sandstone — warm sepia -/
 
 /-- Sandstone light: a warm cream background with terracotta and umber accents. -/
 @[manual_theme]
@@ -301,7 +310,7 @@ public def ManualTheme.sandstoneLight : ManualTheme where
 
 /--
 Sandstone dark: weathered canyon walls at dusk — deep terracotta substrate with sunlit-buff
-text and warm vermilion / honey accents. No cool blues: the previous version's `#80c8e8`
+text and warm vermilion / honey accents. No cool blues: the previous version's {lit}`#80c8e8`
 const broke the warm-palette family. Inspired by the Sedona red rocks, Petra at twilight, and
 the Vermilion Cliffs of Arizona-Utah.
 -/
diff --git a/src/verso-manual/VersoManual/Theme/Emit.lean b/src/verso-manual/VersoManual/Theme/Emit.lean
index 951eb8c94..e3e112c46 100644
--- a/src/verso-manual/VersoManual/Theme/Emit.lean
+++ b/src/verso-manual/VersoManual/Theme/Emit.lean
@@ -123,7 +123,7 @@ Produces the body of {lit}`verso-themes.css`:
 - an unscoped `:root` block carrying the {name}`single`'s variables — what the server-rendered
   HTML uses before the no-flash script attaches {lit}`data-verso-theme`. {name}`single` is the
   resolved single-mode default theme;
-- an {lit}`@media (prefers-color-scheme: dark)` block carrying the {name}`Verso.Theme.ManualTheme`
+- an {lit}`@media (prefers-color-scheme: dark)` block carrying the {name}`ManualTheme`
   named by {name}`defaultDark` (no-JS fallback only — the no-flash script always sets a concrete
   attribute);
 - one `:root[data-verso-theme="…"]` block per registered theme so the picker can swap themes by
diff --git a/src/verso/Verso/BuildLog.lean b/src/verso/Verso/BuildLog.lean
index 8ae3dc6ee..ac4621947 100644
--- a/src/verso/Verso/BuildLog.lean
+++ b/src/verso/Verso/BuildLog.lean
@@ -158,14 +158,14 @@ public instance [MonadLiftT IO m] : Coe (Logger IO) (Logger m) := ⟨Logger.lift
 
 /--
 Reports an error directly through a {name}`Logger` value. Most callers should use
-{name}`Verso.reportError` instead.
+{name}`reportError` instead.
 -/
 public def Logger.reportError (logger : Logger m) (text : String) (loc : Option SourceLoc := none) : m Unit :=
   logger.log .error text loc
 
 /--
 Reports a warning directly through a {name}`Logger` value. Most callers should use
-{name}`Verso.reportWarning` instead.
+{name}`reportWarning` instead.
 -/
 public def Logger.reportWarning (logger : Logger m) (text : String) (loc : Option SourceLoc := none) : m Unit :=
   logger.log .warning text loc
diff --git a/src/verso/Verso/Code/HighlightedToTex.lean b/src/verso/Verso/Code/HighlightedToTex.lean
index 7d78c83ce..c2e30b46e 100644
--- a/src/verso/Verso/Code/HighlightedToTex.lean
+++ b/src/verso/Verso/Code/HighlightedToTex.lean
@@ -24,7 +24,7 @@ Given an already escaped-for-verbatim string, and a token kind, returns TeX that
 content in the matching semantic macro: `\versoKeyword`, `\versoConst`, `\versoVar`, or
 `\versoLiteral`. The macros are defined by the consuming genre's preamble (the manual genre
 uses {name}`Verso.Theme.CodeTheme` to style them). For a fallback definition that
-reproduces the pre-theming look, see {name}`SubVerso.Highlighting.texMacroFallbacks`.
+reproduces the pre-theming look, see {name}`texMacroFallbacks`.
 -/
 public def highlightToken : String → Token.Kind → TeX
 | c, .keyword _ _ _ => .raw s!"\\versoKeyword\{{c}}"
diff --git a/src/verso/Verso/Theme/Code.lean b/src/verso/Verso/Theme/Code.lean
index 1673a4e75..915426997 100644
--- a/src/verso/Verso/Theme/Code.lean
+++ b/src/verso/Verso/Theme/Code.lean
@@ -126,7 +126,7 @@ public structure CodeTheme where
   tokenHighlightBackground : Color := color%#eeeeee
   /--
   The background of a displayed tactic state. Defaults to the surrounding
-  {name (full := Verso.Theme.CodeTheme.codeBlockBackground)}`codeBlockBackground`, so a theme
+  {name (full := CodeTheme.codeBlockBackground)}`codeBlockBackground`, so a theme
   that recolors the code surface gets a matching tactic-state surface for free; themes that
   want a distinct tactic-state tint (a slight raise to differentiate it from code) override
   it explicitly.
@@ -137,14 +137,14 @@ public structure CodeTheme where
 
   /--
   An accent background drawn behind highlighted code.
-  {name (full := Verso.Theme.CodeTheme.codeColor)}`codeColor` must read on it.
+  {name (full := CodeTheme.codeColor)}`codeColor` must read on it.
   -/
   highlightOnCode : Color := color%#fff3b0
   /-- An accent background drawn behind highlighted code or prose. Both code and text must read on it. -/
   highlightOnText : Color := highlightOnCode
   /--
   A neutral UI element color drawn against
-  {name (full := Verso.Theme.CodeTheme.codeBlockBackground)}`codeBlockBackground` (e.g. a toggle pill).
+  {name (full := CodeTheme.codeBlockBackground)}`codeBlockBackground` (e.g. a toggle pill).
   -/
   uiOnCode : Color := color%#888888
 
@@ -226,8 +226,8 @@ private meta def themePair [Monad m] [MonadRef m] [MonadQuotation m] (n : Name)
 
 open Lean Elab Term in
 /--
-Elaborator for the {lit}`code_themes%` macro: emits a {name}`Verso.Theme.CodeThemeTable`
-literal whose entries are every registered {name}`Verso.Theme.CodeTheme` decl.
+Elaborator for the {lit}`code_themes%` macro: emits a {name}`CodeThemeTable`
+literal whose entries are every registered {name}`CodeTheme` decl.
 -/
 @[term_elab code_themes]
 meta def elabCodeThemes : TermElab := fun _stx expected? => do
@@ -412,7 +412,7 @@ private def tokenMacro (name : String) (s : TokenStyle) (colorName : String) : S
 /--
 Returns a TeX preamble fragment that defines a theme-specific {lit}`xcolor` palette, redefines
 the four {lit}`\verso…` token macros so they apply the theme's per-token color, weight, and
-style, and sets the document mono font to {Lean.Doc.name (full := Verso.Typeface.texFamily)}`Verso.Typeface.texFamily` applied to
+style, and sets the document mono font to {Lean.Doc.name (full := Typeface.texFamily)}`texFamily` applied to
 {Lean.Doc.name}`codeFace`.
 
 Two color names are emitted per severity: {lit}`errorColor`/{lit}`warningColor`/{lit}`infoColor`
@@ -461,9 +461,9 @@ end CodeTheme
 namespace CodeTheme
 
 /--
-Every {Lean.Doc.name}`Verso.Typeface` referenced by a theme. Built-in
-{Lean.Doc.name (full := Verso.Typeface.sans)}`sans`/{Lean.Doc.name (full := Verso.Typeface.serif)}`serif`/{Lean.Doc.name (full := Verso.Typeface.mono)}`mono`
-are skipped: only {Lean.Doc.name (full := Verso.Typeface.files)}`files` typefaces contribute font assets.
+Every {Lean.Doc.name}`Typeface` referenced by a theme. Built-in
+{Lean.Doc.name (full := Typeface.sans)}`sans`/{Lean.Doc.name (full := Typeface.serif)}`serif`/{Lean.Doc.name (full := Typeface.mono)}`mono`
+are skipped: only {Lean.Doc.name (full := Typeface.files)}`files` typefaces contribute font assets.
 -/
 public def fileTypefaces (theme : CodeTheme) : Array Typeface :=
   let faces := #[theme.codeFace, theme.const.face, theme.keyword.face, theme.«var».face]
@@ -502,8 +502,8 @@ public def slugFamily (family : String) : String := Id.run do
 /--
 Output-relative paths and bytes of every font file the theme uses. Each file is named
 {lit}`<slug>-<typeface>-<face>.<ext>`, where {lit}`<slug>` is
-{Lean.Doc.name}`Verso.Theme.CodeTheme.slugFamily` applied to the family and {lit}`<typeface>` is
-the index of the typeface within the theme's {Lean.Doc.name}`Verso.Theme.CodeTheme.fileTypefaces`
+{Lean.Doc.name}`slugFamily` applied to the family and {lit}`<typeface>` is
+the index of the typeface within the theme's {Lean.Doc.name}`fileTypefaces`
 array. The typeface index keeps paths distinct even when two families slug to the same string
 (such as {lit}`"A B"` and {lit}`"A/B"` both becoming {lit}`A-B`). The {lit}`assetRoot` is the
 directory the paths are relative to (no leading or trailing slash); the generated
@@ -529,7 +529,7 @@ private def styleString : FontStyle → String
   | .italic => "italic"
 
 /--
-The {lit}`@font-face` rules for every {Lean.Doc.name (full := Verso.Typeface.files)}`files`
+The {lit}`@font-face` rules for every {Lean.Doc.name (full := Typeface.files)}`files`
 typeface the theme uses. The {lit}`url()` paths are relative, so the rules resolve from whatever
 stylesheet they end up in (in the manual genre, {lit}`verso-themes.css` at the site root).
 -/
diff --git a/src/verso/Verso/Theme/Code/Defaults.lean b/src/verso/Verso/Theme/Code/Defaults.lean
index 399862b0b..2f5cc9dc1 100644
--- a/src/verso/Verso/Theme/Code/Defaults.lean
+++ b/src/verso/Verso/Theme/Code/Defaults.lean
@@ -11,16 +11,18 @@ set_option linter.missingDocs true
 set_option doc.verso true
 
 /-!
-The built-in {Lean.Doc.name}`Verso.Theme.CodeTheme` values. The default theme reproduces today's
-hardcoded look so existing manuals render unchanged when no override is configured.
+{open Verso.Theme}
+
+The built-in {Lean.Doc.name}`CodeTheme` values. The default theme reproduces today's hardcoded look
+so existing manuals render unchanged when no override is configured.
 -/
 
 namespace Verso.Theme
 
 /--
-The default code theme: typography-only styling that reproduces today's hardcoded look. Named
-after the most ancient writing medium in use; other built-in themes live alongside it in the
-{Lean.Doc.name}`Verso.Theme.CodeTheme` namespace.
+The default code theme.
+
+This theme uses only typographical features to distinguish code elements, rather than color.
 -/
 @[code_theme]
 public def CodeTheme.ink : CodeTheme where
diff --git a/src/verso/Verso/Theme/Color/Palettes.lean b/src/verso/Verso/Theme/Color/Palettes.lean
index d6c132e02..fac858143 100644
--- a/src/verso/Verso/Theme/Color/Palettes.lean
+++ b/src/verso/Verso/Theme/Color/Palettes.lean
@@ -9,9 +9,11 @@ public import Verso.Theme.Color.Palettes.Solarized
 public import Verso.Theme.Color.Palettes.OkabeIto
 
 /-!
+{open Verso.Theme}
+
 Named reference palettes used by the shipped themes. Each palette module exposes:
 
 - a {lit}`name : String` and {lit}`sourceLink : SourceLink` for the picker to display
   alongside themes that build on the palette;
-- a set of named {name}`Verso.Theme.Color` constants holding the canonical hex values.
+- a set of named {name}`Color` constants holding the canonical hex values.
 -/
diff --git a/src/verso/Verso/Theme/Color/Palettes/OkabeIto.lean b/src/verso/Verso/Theme/Color/Palettes/OkabeIto.lean
index 09cfc8cc5..6334d6044 100644
--- a/src/verso/Verso/Theme/Color/Palettes/OkabeIto.lean
+++ b/src/verso/Verso/Theme/Color/Palettes/OkabeIto.lean
@@ -13,11 +13,12 @@ set_option linter.missingDocs true
 set_option doc.verso true
 
 /-!
-Masataka Okabe and Kei Ito's colorblind-safe palette (2002,
-<https://jfly.uni-koeln.de/color/>) as named {name}`Verso.Theme.Color` constants. The eight
-hues stay distinguishable under protanopia, deuteranopia, and tritanopia, so they are a
-standard reference set for data visualization and code highlighting that must remain readable
-to dichromat readers.
+{open Verso.Theme}
+
+[Masataka Okabe and Kei Ito's colorblind-safe palette (2002)](https://jfly.uni-koeln.de/color/) as
+named {name}`Color` constants. The eight hues stay distinguishable under protanopia, deuteranopia,
+and tritanopia, so they are a standard reference set for data visualization and code highlighting
+that must remain readable to dichromat readers.
 -/
 
 namespace Verso.Theme.Color.Palettes.OkabeIto
@@ -28,7 +29,7 @@ namespace Verso.Theme.Color.Palettes.OkabeIto
 public def name : String := "Okabe-Ito"
 
 /-- The canonical Okabe-Ito reference page, shown in the picker for themes that use it. -/
-public def sourceLink : Verso.Theme.SourceLink :=
+public def sourceLink : SourceLink :=
   { url := "https://jfly.uni-koeln.de/color/", text := "jfly.uni-koeln.de/color" }
 
 /-! # Hues -/
diff --git a/src/verso/Verso/Theme/Color/Palettes/Solarized.lean b/src/verso/Verso/Theme/Color/Palettes/Solarized.lean
index 618a31011..577464da8 100644
--- a/src/verso/Verso/Theme/Color/Palettes/Solarized.lean
+++ b/src/verso/Verso/Theme/Color/Palettes/Solarized.lean
@@ -3,6 +3,30 @@ Copyright (c) 2026 Lean FRO LLC. All rights reserved.
 Released under Apache 2.0 license as described in the file LICENSE.
 Author: David Thrane Christiansen
 -/
+
+/-
+The Solarized hex constants below are reproduced from Ethan Schoonover's Solarized palette,
+distributed under the MIT license. The notice is reproduced here verbatim per the license's
+attribution clause; the manual genre also includes it in the attribution page of any generated
+manual that includes a Solarized theme.
+
+  Copyright (c) 2011 Ethan Schoonover
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+  associated documentation files (the "Software"), to deal in the Software without restriction,
+  including without limitation the rights to use, copy, modify, merge, publish, distribute,
+  sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
+  furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all copies or
+  substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
+  NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+  DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT
+  OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+-/
 module
 
 public import Verso.Theme.Color.Basic
@@ -13,9 +37,11 @@ set_option linter.missingDocs true
 set_option doc.verso true
 
 /-!
-Ethan Schoonover's *Solarized* palette as named {name}`Verso.Theme.Color` constants. Sixteen
+{open Verso.Theme}
+
+Ethan Schoonover's _Solarized_ palette as named {name}`Color` constants. Sixteen
 colors: eight monotone shades (the {lit}`base*` ramp) plus eight accent hues. The hex values are
-the canonical ones from the upstream reference at <https://ethanschoonover.com/solarized/>.
+the canonical ones from the [upstream reference](https://ethanschoonover.com/solarized/).
 
 The ramp's design rule is that any {lit}`base0X` (with leading zero) is dark-mode body text and
 any {lit}`baseY` is light-mode body text; the rest progress symmetrically between background and
@@ -30,9 +56,9 @@ namespace Verso.Theme.Color.Palettes.Solarized
 public def name : String := "Solarized"
 
 /-- The canonical Solarized homepage, shown in the picker for themes that use this palette. -/
-public def sourceLink : Verso.Theme.SourceLink :=
-  { url := "https://ethanschoonover.com/solarized/",
-    text := "ethanschoonover.com/solarized" }
+public def sourceLink : SourceLink where
+  url := "https://ethanschoonover.com/solarized/"
+  text := "ethanschoonover.com/solarized"
 
 /-! # Monotone ramp -/
 

From e09d351623f065b703900a7bd606872ef82e0c1f Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Mon, 1 Jun 2026 09:31:42 +0200
Subject: [PATCH 16/31] Cleanup and one more theme

---
 generate.sh                                   |  45 +++--
 src/verso-manual/VersoManual/Basic.lean       |  27 +--
 .../VersoManual/LicenseInfo/Licenses.lean     |  28 +++
 .../VersoManual/Theme/Defaults.lean           |  96 ++++++++++
 src/verso/Verso/Theme/Color/Palettes.lean     |   1 +
 .../Verso/Theme/Color/Palettes/Nord.lean      | 166 ++++++++++++++++++
 6 files changed, 337 insertions(+), 26 deletions(-)
 create mode 100644 src/verso/Verso/Theme/Color/Palettes/Nord.lean

diff --git a/generate.sh b/generate.sh
index efd020c8d..b5bd058f1 100755
--- a/generate.sh
+++ b/generate.sh
@@ -2,7 +2,21 @@
 
 set -e
 
-if ! command -v inkscape >/dev/null 2>&1; then
+html_only=false
+for arg in "$@"; do
+  case "$arg" in
+    --html)
+      html_only=true
+      ;;
+    *)
+      echo "Unknown argument: $arg" >&2
+      echo "Usage: $0 [--html]" >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [ "$html_only" = false ] && ! command -v inkscape >/dev/null 2>&1; then
   if [ -f "/Applications/Inkscape.app/Contents/MacOS/inkscape" ]; then
     PATH="$PATH:/Applications/Inkscape.app/Contents/MacOS"
   else
@@ -11,20 +25,25 @@ if ! command -v inkscape >/dev/null 2>&1; then
   fi
 fi
 
-echo "Building the user's guide as TeX and HTML"
-lake exe usersguide --delay-html-multi multi.json --delay-html-single single.json --with-tex
-lake exe usersguide --resume-html-multi multi.json --resume-html-single single.json
+if [ "$html_only" = true ]; then
+  echo "Building the user's guide as HTML"
+  lake exe usersguide
+else
+  echo "Building the user's guide as TeX and HTML"
+  lake exe usersguide --delay-html-multi multi.json --delay-html-single single.json --with-tex
+  lake exe usersguide --resume-html-multi multi.json --resume-html-single single.json
 
-echo "Building the user's guide as PDF"
-mkdir -p _out/tex
-pushd _out/tex
-lualatex -shell-escape main
-lualatex -shell-escape main
-lualatex -shell-escape main
-popd
+  echo "Building the user's guide as PDF"
+  mkdir -p _out/tex
+  pushd _out/tex
+  lualatex -shell-escape main
+  lualatex -shell-escape main
+  lualatex -shell-escape main
+  popd
 
-echo "User's guide PDF is at:"
-readlink -f _out/tex/main.pdf
+  echo "User's guide PDF is at:"
+  readlink -f _out/tex/main.pdf
+fi
 
 echo "HTML is at:"
 readlink -f _out/html-single/index.html
diff --git a/src/verso-manual/VersoManual/Basic.lean b/src/verso-manual/VersoManual/Basic.lean
index 58e470325..50ecf67cb 100644
--- a/src/verso-manual/VersoManual/Basic.lean
+++ b/src/verso-manual/VersoManual/Basic.lean
@@ -676,26 +676,27 @@ structure ExtensionImpls where
   inlineDescrs : Lean.NameMap Dynamic
   blockDescrs : Lean.NameMap Dynamic
 
-end Manual
-
 /--
-The monad in which TeX descriptor implementations (`BlockDescr.toTeX`,
-`InlineDescr.toTeX`) and the TeX emit pipeline run. Reads the resolved `ThemeRegistry`, the
-extension implementations table, and logs through the build log.
+{open Verso.Theme}
+
+The monad in which TeX descriptor implementations (`BlockDescr.toTeX`, `InlineDescr.toTeX`) and the
+TeX generation pipeline run. Reads the resolved {name}`ThemeRegistry`, the extension implementations
+table, and logs through the build log.
 
-Defined here (not in `VersoManual.lean`) so descriptor type signatures can name it without
-forward references.
+Defined here (not in `VersoManual.lean`) so descriptor type signatures can name it without forward
+references.
 -/
-public abbrev Manual.EmitM : Type → Type :=
+public abbrev EmitM : Type → Type :=
   ReaderT Verso.Theme.ThemeRegistry (ReaderT Manual.ExtensionImpls (BuildLogT IO))
 
 /--
-The monad in which HTML descriptor implementations (`BlockDescr.toHtml`,
-`InlineDescr.toHtml`) run. Same as {name}`Manual.EmitM`, with the remote cross-reference
-table read in addition.
+The monad in which HTML descriptor implementations (`BlockDescr.toHtml`, `InlineDescr.toHtml`) run.
+Same as {name}`EmitM`, with the remote cross-reference table read in addition.
 -/
-public abbrev Manual.EmitHtmlM : Type → Type :=
-  ReaderT Multi.AllRemotes Manual.EmitM
+public abbrev EmitHtmlM : Type → Type :=
+  ReaderT Multi.AllRemotes EmitM
+
+end Manual
 
 /-- A genre for writing reference manuals and other book-like documents. -/
 @[expose]
diff --git a/src/verso-manual/VersoManual/LicenseInfo/Licenses.lean b/src/verso-manual/VersoManual/LicenseInfo/Licenses.lean
index eecd51f1d..fbf0e3286 100644
--- a/src/verso-manual/VersoManual/LicenseInfo/Licenses.lean
+++ b/src/verso-manual/VersoManual/LicenseInfo/Licenses.lean
@@ -206,3 +206,31 @@ COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 "#)]
+
+public def nord : LicenseInfo where
+  identifier := "MIT"
+  dependency := "Nord"
+  howUsed := some "The Nord and Nord Light themes reproduce the canonical Nord color palette by Sven Greb (Arctic Ice Studio)."
+  link := some "https://www.nordtheme.com/"
+  text := #[(some "MIT License (MIT)",
+r#"
+Copyright (c) 2016-present Sven Greb <development@svengreb.de> (https://www.svengreb.de)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"#)]
diff --git a/src/verso-manual/VersoManual/Theme/Defaults.lean b/src/verso-manual/VersoManual/Theme/Defaults.lean
index 6f3aa5490..09d0c7770 100644
--- a/src/verso-manual/VersoManual/Theme/Defaults.lean
+++ b/src/verso-manual/VersoManual/Theme/Defaults.lean
@@ -268,6 +268,102 @@ public def ManualTheme.solarizedDark : ManualTheme :=
     visitedLinkColor := violet,
     licenses := #[Verso.Genre.Manual.Licenses.solarized] }
 
+/-! # Nord — Sven Greb's arctic, north-bluish palette -/
+
+open Color.Palettes.Nord in
+/--
+Nord: the canonical Nord palette on its Polar Night substrate ({lit}`nord0` page, {lit}`nord1`
+code blocks). Frost hues color the keyword/const/var tokens; the Aurora reds, yellows, and
+greens drive diagnostics.
+-/
+@[manual_theme]
+public def ManualTheme.nord : ManualTheme :=
+  { darkChromeFields {
+      CodeTheme.ink with
+      name := Color.Palettes.Nord.name,
+      sourceLink := some Color.Palettes.Nord.sourceLink,
+      appearance := .dark,
+      background := nord0,
+      codeBlockBackground := nord1,
+      textColor := nord4,
+      codeColor := nord4,
+      structureColor := nord4,
+      warningColor := nord4,
+      infoColor := nord4,
+      errorColor := nord11,
+      errorIndicatorColor := nord11,
+      warningIndicatorColor := nord13,
+      infoIndicatorColor := nord8,
+      const := { color := nord8, weight := .regular, style := .normal, face := .mono },
+      keyword := { color := nord9, weight := .bold, style := .normal, face := .mono },
+      «var» := { color := nord4, weight := .regular, style := .italic, face := .mono },
+      hoverBackground := nord2,
+      hoverText := nord4,
+      hoverBorderColor := nord3,
+      hoverSeparatorColor := nord3,
+      tokenHighlightBackground := nord2,
+      tacticStateBorderColor := nord3,
+      selectedColor := nord2,
+      highlightOnCode := nord3,
+      highlightOnText := nord3,
+      uiOnCode := nord3
+    } with
+      surfaceColor := nord1,
+      tocBackground := nord0,
+      borderColor := nord3,
+      mutedColor := nord4,
+      linkColor := nord8,
+      visitedLinkColor := nord15,
+      licenses := #[Verso.Genre.Manual.Licenses.nord] }
+
+open Color.Palettes.Nord in
+/--
+Nord Light: the inverse Snow Storm substrate ({lit}`nord6` page, {lit}`nord5` code blocks)
+with darker Frost and Polar Night accents chosen so each token clears WCAG AA contrast on the
+light background. Token mapping matches Nord's documented intent ({lit}`nord10` for
+keywords/declarations, {lit}`nord13` for warnings, {lit}`nord15` for the visited-link purple).
+-/
+@[manual_theme]
+public def ManualTheme.nordLight : ManualTheme where
+  toCodeTheme := {
+    CodeTheme.ink with
+    name := s!"{Color.Palettes.Nord.name} Light",
+    sourceLink := some Color.Palettes.Nord.sourceLink,
+    background := nord6,
+    codeBlockBackground := nord5,
+    textColor := nord0,
+    codeColor := nord0,
+    structureColor := nord0,
+    warningColor := nord0,
+    infoColor := nord0,
+    errorColor := nord11,
+    errorIndicatorColor := nord11,
+    warningIndicatorColor := nord13,
+    infoIndicatorColor := nord10,
+    hoverBackground := nord5,
+    hoverText := nord0,
+    hoverBorderColor := nord3,
+    hoverSeparatorColor := nord3,
+    tokenHighlightBackground := nord5,
+    tacticStateBorderColor := nord3,
+    selectedColor := nord4,
+    highlightOnCode := nord4,
+    uiOnCode := nord3,
+    -- Frost hues for tokens: nord10 (deep blue) for keywords and declarations; nord3 (Polar
+    -- Night, the documented comments color) plus italic distinguishes variables from body
+    -- text without dropping below contrast threshold.
+    keyword.color := nord10,
+    const.color := nord10,
+    «var».color := nord3
+  }
+  surfaceColor := nord5
+  tocBackground := nord5
+  borderColor := nord3
+  mutedColor := nord3
+  linkColor := nord10
+  visitedLinkColor := nord15
+  licenses := #[Verso.Genre.Manual.Licenses.nord]
+
 /-! # Sandstone — warm sepia -/
 
 /-- Sandstone light: a warm cream background with terracotta and umber accents. -/
diff --git a/src/verso/Verso/Theme/Color/Palettes.lean b/src/verso/Verso/Theme/Color/Palettes.lean
index fac858143..027e4fab9 100644
--- a/src/verso/Verso/Theme/Color/Palettes.lean
+++ b/src/verso/Verso/Theme/Color/Palettes.lean
@@ -7,6 +7,7 @@ module
 
 public import Verso.Theme.Color.Palettes.Solarized
 public import Verso.Theme.Color.Palettes.OkabeIto
+public import Verso.Theme.Color.Palettes.Nord
 
 /-!
 {open Verso.Theme}
diff --git a/src/verso/Verso/Theme/Color/Palettes/Nord.lean b/src/verso/Verso/Theme/Color/Palettes/Nord.lean
new file mode 100644
index 000000000..660934de0
--- /dev/null
+++ b/src/verso/Verso/Theme/Color/Palettes/Nord.lean
@@ -0,0 +1,166 @@
+/-
+Copyright (c) 2026 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+
+/-
+The Nord hex constants below are reproduced from the *Nord* palette by Sven Greb (Arctic Ice
+Studio), distributed under the MIT license. The notice is reproduced here verbatim per the
+license's attribution clause; the manual genre also includes it in the attribution page of any
+generated manual that includes a Nord theme.
+
+  MIT License (MIT)
+
+  Copyright (c) 2016-present Sven Greb <development@svengreb.de> (https://www.svengreb.de)
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+  and associated documentation files (the "Software"), to deal in the Software without
+  restriction, including without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
+  Software is furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all copies or
+  substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+  BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+  DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+-/
+module
+
+public import Verso.Theme.Color.Basic
+public import Verso.Theme.Color.Syntax
+public import Verso.Theme.SourceLink
+
+set_option linter.missingDocs true
+set_option doc.verso true
+
+/-!
+{open Verso.Theme}
+
+Sven Greb's _Nord_ palette as named {name}`Color` constants. Sixteen colors organized in four
+groups, taken from the [canonical reference](https://www.nordtheme.com/docs/colors-and-palettes):
+
+: Polar Night
+
+  ({lit}`nord0`–{lit}`nord3`): deep arctic-night base, used for dark-substrate backgrounds and code
+  surfaces. : Snow Storm
+
+  ({lit}`nord4`–{lit}`nord6`): light, frosty whites for body text on dark backgrounds (and
+  substrates on light variants).
+
+: Frost
+
+  ({lit}`nord7`–{lit}`nord10`): four blue-green hues, the canonical syntax accents.
+
+: Aurora
+
+  ({lit}`nord11`–{lit}`nord15`): warm accent hues (red, orange, yellow, green, purple) used for
+  diagnostics and additional syntax categories.
+-/
+
+namespace Verso.Theme.Color.Palettes.Nord
+
+/-! # Identity -/
+
+/-- The palette's display name, suitable as a prefix when naming themes built on it. -/
+public def name : String := "Nord"
+
+/-- The canonical Nord homepage, shown in the picker for themes that use this palette. -/
+public def sourceLink : SourceLink :=
+  { url := "https://www.nordtheme.com/", text := "nordtheme.com" }
+
+/-! # Polar Night -/
+
+/--
+{lit}`nord0` — Polar Night, origin color. The canonical Nord background on dark-ambiance
+substrates; also serves as the plain-text color on bright-ambiance (light) backgrounds.
+-/
+public def nord0 : Color := color%#2e3440
+/--
+{lit}`nord1` — Polar Night, a shade lighter. Used for elevated UI surfaces such as status
+bars, panels, and buttons over the {lit}`nord0` substrate.
+-/
+public def nord1 : Color := color%#3b4252
+/--
+{lit}`nord2` — Polar Night, mid shade. Used for active editor lines and selection
+highlighting against the {lit}`nord0` substrate.
+-/
+public def nord2 : Color := color%#434c5e
+/--
+{lit}`nord3` — Polar Night, the lightest shade. Used for comments, indent guides, and other
+subtle UI accents.
+-/
+public def nord3 : Color := color%#4c566a
+
+/-! # Snow Storm -/
+
+/--
+{lit}`nord4` — Snow Storm, the darkest of the light shades. Used for the editor caret on dark
+substrates and for syntax variables and constants.
+-/
+public def nord4 : Color := color%#d8dee9
+/--
+{lit}`nord5` — Snow Storm, mid. Used for subtle UI text and for selection highlighting on
+bright-ambiance backgrounds.
+-/
+public def nord5 : Color := color%#e5e9f0
+/--
+{lit}`nord6` — Snow Storm, the lightest shade. The canonical bright-ambiance background; also
+serves as the plain syntax-text color on dark backgrounds.
+-/
+public def nord6 : Color := color%#eceff4
+
+/-! # Frost -/
+
+/--
+{lit}`nord7` — Frost, a calm muted cyan-green. Documented role: classes, types, and
+primitives in syntax highlighting.
+-/
+public def nord7 : Color := color%#8fbcbb
+/--
+{lit}`nord8` — Frost, brighter cyan; Nord's primary syntax accent. Documented role:
+declarations, calls, and execution statements.
+-/
+public def nord8 : Color := color%#88c0d0
+/--
+{lit}`nord9` — Frost, blue. Nord's secondary syntax accent. Documented role: keywords as
+well as support characters, operators, and tags.
+-/
+public def nord9 : Color := color%#81a1c1
+/--
+{lit}`nord10` — Frost, deep blue. Nord's tertiary syntax accent. Documented role: pragmas
+and preprocessor statements (e.g. the {lit}`#include` directive in C).
+-/
+public def nord10 : Color := color%#5e81ac
+
+/-! # Aurora -/
+
+/--
+{lit}`nord11` — Aurora red. Documented role: error states, Git deletions in UI chrome, and
+detected syntax errors.
+-/
+public def nord11 : Color := color%#bf616a
+/--
+{lit}`nord12` — Aurora orange. Documented role: indicators for "advanced functionality";
+annotations and decorators in syntax highlighting.
+-/
+public def nord12 : Color := color%#d08770
+/--
+{lit}`nord13` — Aurora yellow. Documented role: warning states, modified items in UI chrome,
+and escape characters in strings.
+-/
+public def nord13 : Color := color%#ebcb8b
+/--
+{lit}`nord14` — Aurora green. Documented role: success states, Git additions, and string
+literals in syntax highlighting.
+-/
+public def nord14 : Color := color%#a3be8c
+/--
+{lit}`nord15` — Aurora purple. Documented role: highlighting "uncommon functionality";
+numeric and floating-point literals in syntax highlighting.
+-/
+public def nord15 : Color := color%#b48ead

From 4c4df6d5da31cf0c25104cff0533f7c12ed02b45 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Mon, 1 Jun 2026 11:56:41 +0200
Subject: [PATCH 17/31] Dracula and fixes

---
 src/tests/Tests/HighlightedToTeX.lean         |   2 +-
 src/verso-manual/VersoManual.lean             |   9 +-
 .../VersoManual/LicenseInfo/Licenses.lean     |  28 ++
 src/verso-manual/VersoManual/Theme.lean       |  25 +-
 .../VersoManual/Theme/Defaults.lean           | 381 +++++++++++++++---
 src/verso/Verso/Code/Highlighted.lean         |  61 ++-
 src/verso/Verso/Code/HighlightedToTex.lean    |  28 +-
 src/verso/Verso/Theme/Code.lean               | 143 +++++--
 src/verso/Verso/Theme/Code/Defaults.lean      |  16 +
 src/verso/Verso/Theme/Color/Palettes.lean     |   1 +
 .../Verso/Theme/Color/Palettes/Dracula.lean   | 152 +++++++
 src/verso/Verso/Theme/Color/color-swatch.js   |   2 +-
 12 files changed, 747 insertions(+), 101 deletions(-)
 create mode 100644 src/verso/Verso/Theme/Color/Palettes/Dracula.lean

diff --git a/src/tests/Tests/HighlightedToTeX.lean b/src/tests/Tests/HighlightedToTeX.lean
index fdab34cc0..4fa73aff8 100644
--- a/src/tests/Tests/HighlightedToTeX.lean
+++ b/src/tests/Tests/HighlightedToTeX.lean
@@ -38,7 +38,7 @@ literal bucket. -/
 preamble that defines its own (theme-driven) versions wins without an explicit `\renewcommand`. -/
 
 /--
-info: "\\providecommand{\\versoKeyword}[1]{\\textbf{#1}}\n\\providecommand{\\versoConst}[1]{#1}\n\\providecommand{\\versoVar}[1]{\\textit{#1}}\n\\providecommand{\\versoLiteral}[1]{#1}\n"
+info: "\\providecommand{\\versoKeyword}[1]{\\textbf{#1}}\n\\providecommand{\\versoConst}[1]{#1}\n\\providecommand{\\versoVar}[1]{\\textit{#1}}\n\\providecommand{\\versoLiteral}[1]{#1}\n\\providecommand{\\versoLiteralString}[1]{#1}\n\\providecommand{\\versoDocComment}[1]{\\textit{#1}}\n\\providecommand{\\versoSort}[1]{#1}\n\\providecommand{\\versoLevelVar}[1]{\\textit{#1}}\n\\providecommand{\\versoLevelConst}[1]{#1}\n\\providecommand{\\versoLevelOp}[1]{#1}\n\\providecommand{\\versoModuleName}[1]{#1}\n"
 -/
 #guard_msgs in #eval texMacroFallbacks
 
diff --git a/src/verso-manual/VersoManual.lean b/src/verso-manual/VersoManual.lean
index 1979c12c2..be6a7b028 100644
--- a/src/verso-manual/VersoManual.lean
+++ b/src/verso-manual/VersoManual.lean
@@ -1221,7 +1221,14 @@ where
       | some t =>
         let issues := issuesOf t
         unless issues.isEmpty do
-          routeDefault s!"{slot} '{name.toString}' ({t.name}) has {issues.size} accessibility issue{if issues.size == 1 then "" else "s"}"
+          let plural := if issues.size == 1 then "" else "s"
+          let lines := issues.toList.map fun i =>
+            let colors := i.offending.toList.map Verso.Theme.Color.css |> ", ".intercalate
+            let suffix := if colors.isEmpty then "" else s!" ({colors})"
+            s!"  - {i.message}{suffix}"
+          let body := "\n".intercalate lines
+          routeDefault
+            s!"{slot} '{name.toString}' ({t.name}) has {issues.size} accessibility issue{plural}:\n{body}"
     checkDefault "defaultLightTheme" cfg.defaultLightTheme
     checkDefault "defaultDarkTheme" cfg.defaultDarkTheme
 
diff --git a/src/verso-manual/VersoManual/LicenseInfo/Licenses.lean b/src/verso-manual/VersoManual/LicenseInfo/Licenses.lean
index fbf0e3286..b0ba4c4de 100644
--- a/src/verso-manual/VersoManual/LicenseInfo/Licenses.lean
+++ b/src/verso-manual/VersoManual/LicenseInfo/Licenses.lean
@@ -234,3 +234,31 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 "#)]
+
+public def dracula : LicenseInfo where
+  identifier := "MIT"
+  dependency := "Dracula"
+  howUsed := some "The Dracula and Alucard themes reproduce the canonical color palettes from the Dracula theme spec by Zeno Rocha and contributors."
+  link := some "https://draculatheme.com/spec"
+  text := #[(some "The MIT License (MIT)",
+r#"
+Copyright (c) 2020 Dracula Theme
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+"#)]
diff --git a/src/verso-manual/VersoManual/Theme.lean b/src/verso-manual/VersoManual/Theme.lean
index 530fd6e29..9ec1bc1a3 100644
--- a/src/verso-manual/VersoManual/Theme.lean
+++ b/src/verso-manual/VersoManual/Theme.lean
@@ -41,25 +41,22 @@ public structure ManualTheme extends CodeTheme where
   structureFace : Typeface := .sans
 
   /-- A raised chrome surface tint (default for the ToC background and the search box). -/
-  surfaceColor : Color := color%#f8f9fa
+  surfaceColor : Color
   /-- The header bar background. Defaults to the page background. -/
   headerBackground : Color := background
   /-- The ToC background. -/
-  tocBackground : Color := color%#fafafa
+  tocBackground : Color
 
-  /--
-  The default border color for chrome elements such as the search box outline. Defaults to
-  a slate gray that clears WCAG 1.4.11 (3:1) against both white and the surface color.
-  -/
-  borderColor : Color := color%#878787
-  /-- The default muted text color for chrome elements such as search hints. -/
-  mutedColor : Color := color%#777777
+  /-- The border color for chrome elements such as the search box outline. -/
+  borderColor : Color
+  /-- The muted text color for chrome elements such as search hints. -/
+  mutedColor : Color
   /-- The color used to highlight matched search terms. Defaults to the code theme's selection. -/
   highlightColor : Color := selectedColor
 
   /-- The color of content links in body prose. -/
-  linkColor : Color := color%#0066cc
-  /-- The color of visited content links. -/
+  linkColor : Color
+  /-- The color of visited content links. Defaults to `linkColor`. -/
   visitedLinkColor : Color := linkColor
 
   /-- The text color used inside the ToC. -/
@@ -68,11 +65,11 @@ public structure ManualTheme extends CodeTheme where
   /-- The color of the burger-menu lines while the ToC is visible. -/
   burgerVisibleColor : Color := tocTextColor
   /-- The shadow color drawn under the burger-menu lines while the ToC is visible. -/
-  burgerVisibleShadowColor : Color := Color.white
+  burgerVisibleShadowColor : Color
   /-- The color of the burger-menu lines while the ToC is hidden. -/
-  burgerHiddenColor : Color := color%#0e2431
+  burgerHiddenColor : Color
   /-- The shadow color drawn under the burger-menu lines while the ToC is hidden. -/
-  burgerHiddenShadowColor : Color := Color.white
+  burgerHiddenShadowColor : Color
 
   /--
   Third-party licenses the theme draws on (color palettes, fonts, etc.).
diff --git a/src/verso-manual/VersoManual/Theme/Defaults.lean b/src/verso-manual/VersoManual/Theme/Defaults.lean
index 09d0c7770..bad376475 100644
--- a/src/verso-manual/VersoManual/Theme/Defaults.lean
+++ b/src/verso-manual/VersoManual/Theme/Defaults.lean
@@ -38,14 +38,22 @@ Other built-in themes live alongside it in the {name}`ManualTheme` namespace.
 @[manual_theme]
 public def ManualTheme.ink : ManualTheme where
   toCodeTheme := CodeTheme.ink
+  surfaceColor := color%#f8f9fa
+  tocBackground := color%#fafafa
+  borderColor := color%#878787
+  mutedColor := color%#777777
+  linkColor := color%#0066cc
+  burgerVisibleShadowColor := Color.white
+  burgerHiddenColor := color%#0e2431
+  burgerHiddenShadowColor := Color.white
 
 /--
 A common dark-appearance code-theme base: deep-charcoal backgrounds, brightened text, accent
-colors chosen for readability against the dark substrate. Other dark themes extend this. Every
-cascading field is overridden explicitly because Lean evaluates the {name}`CodeTheme`
-defaults at construction time, so {lit}`CodeTheme.ink with textColor := …` would otherwise
-leave dependent fields (token colors, message text colors, hover text) frozen at their
-original-light values.
+colors chosen for readability against the dark substrate. Other dark themes extend this.
+Every field whose default references another field is overridden explicitly: Lean evaluates
+defaults when the source theme is constructed, so {lit}`CodeTheme.ink with textColor := …`
+would otherwise leave dependent fields (token colors, message text colors, hover text,
+tactic-state background) frozen at their original light-substrate values.
 -/
 private def darkCodeBase : CodeTheme :=
   let bg := color%#16181c
@@ -67,14 +75,25 @@ private def darkCodeBase : CodeTheme :=
   const := { color := text, weight := .regular, style := .normal, face := .mono },
   keyword := { color := text, weight := .bold, style := .normal, face := .mono },
   «var» := { color := text, weight := .regular, style := .italic, face := .mono },
+  literal := { color := text, weight := .regular, style := .normal, face := .mono },
+  literalString := { color := text, weight := .regular, style := .normal, face := .mono },
+  docComment := { color := text, weight := .regular, style := .italic, face := .mono },
+  sort := { color := text, weight := .regular, style := .normal, face := .mono },
+  levelVar := { color := text, weight := .regular, style := .italic, face := .mono },
+  levelConst := { color := text, weight := .regular, style := .normal, face := .mono },
+  levelOp := { color := text, weight := .regular, style := .normal, face := .mono },
+  moduleName := { color := text, weight := .regular, style := .normal, face := .mono },
   -- Hover popups read text on a slightly lighter surface.
   hoverBackground := color%#2a2d33,
   hoverText := text,
   hoverBorderColor := color%#aaaaaa,
   hoverSeparatorColor := color%#3a3d44,
   tokenHighlightBackground := color%#33363d,
-  -- Tactic-state background inherits from `codeBlockBackground`; only the border needs a
-  -- lighter color to read on the dark substrate.
+  -- Tactic state uses the same surface as code blocks. `tacticStateBackground`'s default
+  -- is `codeBlockBackground`, but defaults are evaluated when the source theme is constructed
+  -- — `CodeTheme.ink` froze it at white — and `with` updates don't re-evaluate them. The
+  -- override has to be explicit here so the dark substrate flows through.
+  tacticStateBackground := codeBg,
   tacticStateBorderColor := color%#aaaaaa,
   selectedColor := color%#2a3f55,
   -- Highlight accents on a dark substrate: a saturated tone that the bright text still reads on.
@@ -105,6 +124,24 @@ private def darkChromeFields (code : CodeTheme) : ManualTheme := {
   burgerVisibleShadowColor := code.background
 }
 
+/--
+A light-appearance chrome base reused by the shipped light themes. Mirrors `darkChromeFields`
+for themes that want the default light chrome (Ink-style surface, ToC, borders, link colors,
+and burger lines) without spelling out each field. Themes with custom chrome set the fields
+explicitly.
+-/
+private def lightChromeFields (code : CodeTheme) : ManualTheme := {
+  toCodeTheme := code,
+  surfaceColor := color%#f8f9fa,
+  tocBackground := color%#fafafa,
+  borderColor := color%#878787,
+  mutedColor := color%#777777,
+  linkColor := color%#0066cc,
+  burgerVisibleShadowColor := Color.white,
+  burgerHiddenColor := color%#0e2431,
+  burgerHiddenShadowColor := Color.white
+}
+
 /--
 The dark default manual theme. Named after silver, the ink of choice for the dark-substrate
 manuscript traditions: silver-on-purple Byzantine and Carolingian codices like the *Codex
@@ -125,8 +162,8 @@ chosen so each token color meets WCAG AA on white and remains visually distinct
 dichromacies (variables use a dark slate so the bold/italic typography is the dominant signal).
 -/
 @[manual_theme]
-public def ManualTheme.chromaticLight : ManualTheme where
-  toCodeTheme := {
+public def ManualTheme.chromaticLight : ManualTheme :=
+  lightChromeFields {
     CodeTheme.ink with
     name := "Chromatic Light",
     keyword.color := color%#a02828,
@@ -147,25 +184,51 @@ public def ManualTheme.chromaticDark : ManualTheme :=
 
 /-! # Beacon — colorblind-safe syntax accents (Okabe-Ito) -/
 
+open Color.Palettes.OkabeIto in
 /--
-Beacon light: a colorblind-safe syntax palette drawn from the Okabe-Ito set. Black on white
-chrome; tokens use Okabe-Ito blue/orange/bluish-green so they stay distinguishable under all
-three dichromacies.
+Beacon light: a colorblind-safe syntax palette drawn from Okabe and Ito's canonical eight
+hues. Token mapping uses canonical Okabe-Ito hex values throughout, leaning on bold and
+italic typography to disambiguate where two kinds share a hue:
+
+- {lit}`blue` → keywords and universe operators (both bold; context disambiguates)
+- {lit}`bluishGreen` → defined names ({lit}`const`) and module/namespace paths
+- {lit}`vermillion` → bound variables (italic), universe-level variables (italic), and
+  sort formers ({lit}`Type`/{lit}`Prop`/{lit}`Sort`, bold)
+- {lit}`reddishPurple` → string literals
+- {lit}`orange` → numeric literals (universe-level numerics)
+- body text + italic → doc comments
+
+Okabe-Ito was designed for scientific visualization on white substrates and prioritizes
+colorblind safety over WCAG contrast. Several canonical hues sit between 3:1 and 4.5:1 on
+white; the per-theme accessibility check will flag them, and the suite-wide setting
+`warnPerThemeAccessibility` can downgrade those warnings. The colorblind-distinguishability
+property is preserved.
 -/
 @[manual_theme]
-public def ManualTheme.beaconLight : ManualTheme where
-  toCodeTheme := {
+public def ManualTheme.beaconLight : ManualTheme :=
+  lightChromeFields {
     CodeTheme.ink with
     name := "Beacon Light",
     sourceLink := some Color.Palettes.OkabeIto.sourceLink,
-    keyword.color := color%#005b8c,
-    const.color := color%#5b3500,
-    «var».color := color%#9c2400
+    keyword := { color := blue, weight := .bold, style := .normal, face := .mono },
+    const := { color := bluishGreen, weight := .regular, style := .normal, face := .mono },
+    «var» := { color := vermillion, weight := .regular, style := .italic, face := .mono },
+    literal := { color := Color.black, weight := .regular, style := .normal, face := .mono },
+    literalString := { color := reddishPurple, weight := .regular, style := .normal, face := .mono },
+    docComment := { color := Color.black, weight := .regular, style := .italic, face := .mono },
+    sort := { color := vermillion, weight := .bold, style := .normal, face := .mono },
+    levelVar := { color := vermillion, weight := .regular, style := .italic, face := .mono },
+    levelConst := { color := orange, weight := .regular, style := .normal, face := .mono },
+    levelOp := { color := blue, weight := .bold, style := .normal, face := .mono },
+    moduleName := { color := bluishGreen, weight := .regular, style := .normal, face := .mono }
   }
 
+open Color.Palettes.OkabeIto in
 /--
-Beacon dark: the Okabe-Ito palette on a near-black background, with brightened variants chosen
-to keep distance under each dichromacy on the darker substrate.
+Beacon dark: the Okabe-Ito palette on a near-black background. Same colorblind-safe goals as
+{Lean.Doc.name}`ManualTheme.beaconLight`, with the hues that are brightest on dark substrates
+({lit}`skyBlue`, {lit}`yellow`) carrying the most-used token kinds. Typography (bold, italic)
+disambiguates kinds that share a hue, the same way the light variant does.
 -/
 @[manual_theme]
 public def ManualTheme.beaconDark : ManualTheme :=
@@ -173,18 +236,37 @@ public def ManualTheme.beaconDark : ManualTheme :=
     darkCodeBase with
     name := "Beacon Dark",
     sourceLink := some Color.Palettes.OkabeIto.sourceLink,
-    keyword.color := Color.Palettes.OkabeIto.skyBlue,
-    const.color := color%#5bd6a4,
-    «var».color := color%#f5a85a
+    keyword := { color := skyBlue, weight := .bold, style := .normal, face := .mono },
+    const := { color := bluishGreen, weight := .regular, style := .normal, face := .mono },
+    «var» := { color := orange, weight := .regular, style := .italic, face := .mono },
+    literalString := { color := yellow, weight := .regular, style := .normal, face := .mono },
+    sort := { color := reddishPurple, weight := .bold, style := .normal, face := .mono },
+    levelVar := { color := orange, weight := .regular, style := .italic, face := .mono },
+    levelConst := { color := yellow, weight := .regular, style := .normal, face := .mono },
+    levelOp := { color := skyBlue, weight := .bold, style := .normal, face := .mono },
+    moduleName := { color := bluishGreen, weight := .regular, style := .normal, face := .mono }
   }
 
 /-! # Solarized — Ethan Schoonover's standard palette -/
 
 open Color.Palettes.Solarized in
 /--
-Solarized light: Schoonover's standard cream-on-paper palette
-({lit}`base3` background, {lit}`base01` primary content). Token accents reuse the named hues
-from the upstream Solarized definition.
+Solarized light: Schoonover's standard cream-on-paper palette ({lit}`base3` background,
+{lit}`base01` primary content). Token mapping uses canonical Solarized hues per common port
+conventions:
+
+- {lit}`green` → keywords
+- {lit}`blue` → defined names ({lit}`const`)
+- {lit}`violet` → bound variables ({lit}`var`)
+- {lit}`cyan` → string literals
+- {lit}`base1` → doc comments (Solarized's documented muted comment hue)
+- {lit}`yellow` → {lit}`Type`/{lit}`Prop`/{lit}`Sort` formers
+- {lit}`orange` → numeric literals (including universe-level numerics)
+- {lit}`magenta` → universe operators ({lit}`max`, {lit}`imax`) and module/namespace paths
+
+Solarized's documented comment color is base1, which is below WCAG AA 4.5 against base3
+substrate by design; the per-theme accessibility check flags this and the suite-wide setting
+`warnPerThemeAccessibility` can downgrade it.
 -/
 @[manual_theme]
 public def ManualTheme.solarizedLight : ManualTheme :=
@@ -213,9 +295,17 @@ public def ManualTheme.solarizedLight : ManualTheme :=
       selectedColor := base2,
       highlightOnCode := color%#f7e7a3,
       uiOnCode := base1,
-      keyword.color := green,
-      const.color := blue,
-      «var».color := violet
+      keyword := { color := green, weight := .bold, style := .normal, face := .mono },
+      const := { color := blue, weight := .regular, style := .normal, face := .mono },
+      «var» := { color := violet, weight := .regular, style := .italic, face := .mono },
+      literal := { color := base01, weight := .regular, style := .normal, face := .mono },
+      literalString := { color := cyan, weight := .regular, style := .normal, face := .mono },
+      docComment := { color := base1, weight := .regular, style := .italic, face := .mono },
+      sort := { color := yellow, weight := .regular, style := .normal, face := .mono },
+      levelVar := { color := violet, weight := .regular, style := .italic, face := .mono },
+      levelConst := { color := orange, weight := .regular, style := .normal, face := .mono },
+      levelOp := { color := magenta, weight := .regular, style := .normal, face := .mono },
+      moduleName := { color := magenta, weight := .regular, style := .normal, face := .mono }
     },
     surfaceColor := base2,
     tocBackground := base2,
@@ -223,14 +313,19 @@ public def ManualTheme.solarizedLight : ManualTheme :=
     mutedColor := base00,
     linkColor := blue,
     visitedLinkColor := violet,
+    burgerVisibleShadowColor := base3,
+    burgerHiddenColor := base01,
+    burgerHiddenShadowColor := base3,
     licenses := #[Verso.Genre.Manual.Licenses.solarized]
   }
 
 open Color.Palettes.Solarized in
 /--
 Solarized dark: Schoonover's standard {lit}`base03` background with body text on {lit}`base1`.
-Token accents are brightened off the standard palette so they keep clear contrast on the dark
-substrate.
+Token mapping uses canonical Solarized hues (the same accent assignments as
+{Lean.Doc.name}`ManualTheme.solarizedLight`); the relative-luminance jump comes entirely
+from the substrate. Doc comments use {lit}`base01`, Solarized's documented muted comment hue
+for dark substrates (lower contrast than body text, by design).
 -/
 @[manual_theme]
 public def ManualTheme.solarizedDark : ManualTheme :=
@@ -245,7 +340,7 @@ public def ManualTheme.solarizedDark : ManualTheme :=
     structureColor := base1,
     warningColor := base1,
     infoColor := base1,
-    errorColor := color%#ff8b8b,
+    errorColor := red,
     errorIndicatorColor := red,
     warningIndicatorColor := yellow,
     infoIndicatorColor := blue,
@@ -258,9 +353,17 @@ public def ManualTheme.solarizedDark : ManualTheme :=
     selectedColor := base02,
     highlightOnCode := color%#3a2f00,
     uiOnCode := base1,
-    keyword.color := color%#b3d100,
-    const.color := color%#6cb6ff,
-    «var».color := color%#a98aff
+    keyword := { color := green, weight := .bold, style := .normal, face := .mono },
+    const := { color := blue, weight := .regular, style := .normal, face := .mono },
+    «var» := { color := violet, weight := .regular, style := .italic, face := .mono },
+    literal := { color := base1, weight := .regular, style := .normal, face := .mono },
+    literalString := { color := cyan, weight := .regular, style := .normal, face := .mono },
+    docComment := { color := base01, weight := .regular, style := .italic, face := .mono },
+    sort := { color := yellow, weight := .regular, style := .normal, face := .mono },
+    levelVar := { color := violet, weight := .regular, style := .italic, face := .mono },
+    levelConst := { color := orange, weight := .regular, style := .normal, face := .mono },
+    levelOp := { color := magenta, weight := .regular, style := .normal, face := .mono },
+    moduleName := { color := magenta, weight := .regular, style := .normal, face := .mono }
   } with
     -- Override the dark-chrome link defaults with the canonical Solarized blue/violet (they
     -- clear contrast on `base03`).
@@ -273,8 +376,16 @@ public def ManualTheme.solarizedDark : ManualTheme :=
 open Color.Palettes.Nord in
 /--
 Nord: the canonical Nord palette on its Polar Night substrate ({lit}`nord0` page, {lit}`nord1`
-code blocks). Frost hues color the keyword/const/var tokens; the Aurora reds, yellows, and
-greens drive diagnostics.
+code blocks). Token mapping follows Nord's documented hue intent:
+
+- {lit}`nord9` ("keywords, support, operators, tags") → {lit}`keyword`
+- {lit}`nord8` ("declarations, calls, execution statements") → {lit}`const`
+- {lit}`nord4` ("syntax variables and constants") → {lit}`var`, with italic
+- {lit}`nord14` ("string syntax highlighting") → {lit}`literalString`
+- {lit}`nord3` ("comments") → {lit}`docComment`
+- {lit}`nord7` ("classes, types, and primitives") → {lit}`sort` and {lit}`moduleName`
+- {lit}`nord10` ("pragmas, preprocessor") → {lit}`levelOp` (universe-grammar built-ins)
+- {lit}`nord15` ("numbers, floating-point literals") → {lit}`levelConst`
 -/
 @[manual_theme]
 public def ManualTheme.nord : ManualTheme :=
@@ -297,6 +408,14 @@ public def ManualTheme.nord : ManualTheme :=
       const := { color := nord8, weight := .regular, style := .normal, face := .mono },
       keyword := { color := nord9, weight := .bold, style := .normal, face := .mono },
       «var» := { color := nord4, weight := .regular, style := .italic, face := .mono },
+      literal := { color := nord4, weight := .regular, style := .normal, face := .mono },
+      literalString := { color := nord14, weight := .regular, style := .normal, face := .mono },
+      docComment := { color := nord3, weight := .regular, style := .italic, face := .mono },
+      sort := { color := nord7, weight := .regular, style := .normal, face := .mono },
+      levelVar := { color := nord4, weight := .regular, style := .italic, face := .mono },
+      levelConst := { color := nord15, weight := .regular, style := .normal, face := .mono },
+      levelOp := { color := nord10, weight := .regular, style := .normal, face := .mono },
+      moduleName := { color := nord7, weight := .regular, style := .normal, face := .mono },
       hoverBackground := nord2,
       hoverText := nord4,
       hoverBorderColor := nord3,
@@ -319,9 +438,12 @@ public def ManualTheme.nord : ManualTheme :=
 open Color.Palettes.Nord in
 /--
 Nord Light: the inverse Snow Storm substrate ({lit}`nord6` page, {lit}`nord5` code blocks)
-with darker Frost and Polar Night accents chosen so each token clears WCAG AA contrast on the
-light background. Token mapping matches Nord's documented intent ({lit}`nord10` for
-keywords/declarations, {lit}`nord13` for warnings, {lit}`nord15` for the visited-link purple).
+with the canonical Nord hues for tokens. The same documented mapping as
+{Lean.Doc.name}`ManualTheme.nord` applies. Note that Nord — like Solarized — wasn't designed
+for a light substrate, so several token colors (Frost {lit}`nord7`–{lit}`nord9`, Aurora
+{lit}`nord13`–{lit}`nord14`) fall below WCAG AA contrast on {lit}`nord6`. Authors who care
+about strict accessibility on a light background should pick a different theme; the canonical
+hex values are preserved here so the look matches other Nord Light ports.
 -/
 @[manual_theme]
 public def ManualTheme.nordLight : ManualTheme where
@@ -349,12 +471,19 @@ public def ManualTheme.nordLight : ManualTheme where
     selectedColor := nord4,
     highlightOnCode := nord4,
     uiOnCode := nord3,
-    -- Frost hues for tokens: nord10 (deep blue) for keywords and declarations; nord3 (Polar
-    -- Night, the documented comments color) plus italic distinguishes variables from body
-    -- text without dropping below contrast threshold.
-    keyword.color := nord10,
-    const.color := nord10,
-    «var».color := nord3
+    -- Canonical Nord token mapping. `var` borrows `nord3` (the documented comments color)
+    -- because `nord4` is the dark-mode variable hue, which is illegible on `nord6`.
+    keyword := { color := nord9, weight := .bold, style := .normal, face := .mono },
+    const := { color := nord8, weight := .regular, style := .normal, face := .mono },
+    «var» := { color := nord3, weight := .regular, style := .italic, face := .mono },
+    literal := { color := nord0, weight := .regular, style := .normal, face := .mono },
+    literalString := { color := nord14, weight := .regular, style := .normal, face := .mono },
+    docComment := { color := nord3, weight := .regular, style := .italic, face := .mono },
+    sort := { color := nord7, weight := .regular, style := .normal, face := .mono },
+    levelVar := { color := nord3, weight := .regular, style := .italic, face := .mono },
+    levelConst := { color := nord15, weight := .regular, style := .normal, face := .mono },
+    levelOp := { color := nord10, weight := .regular, style := .normal, face := .mono },
+    moduleName := { color := nord7, weight := .regular, style := .normal, face := .mono }
   }
   surfaceColor := nord5
   tocBackground := nord5
@@ -362,8 +491,161 @@ public def ManualTheme.nordLight : ManualTheme where
   mutedColor := nord3
   linkColor := nord10
   visitedLinkColor := nord15
+  burgerVisibleShadowColor := nord6
+  burgerHiddenColor := nord0
+  burgerHiddenShadowColor := nord6
   licenses := #[Verso.Genre.Manual.Licenses.nord]
 
+/-! # Dracula and Alucard — Dracula spec palettes -/
+
+open Color.Palettes.DraculaClassic in
+/--
+Dracula: the canonical dark Dracula palette from the official spec. Token mapping follows
+the spec's documented hue roles:
+
+- Pink: keywords ({lit}`def`, {lit}`theorem`, …).
+- Green: function and definition names ({lit}`const` tokens) — Dracula's "functions, methods,
+  inherited classes" slot.
+- Cyan: module / namespace paths ({lit}`Foo.Bar` in {lit}`import` lines).
+- Purple: universe-grammar reserved words and operators — {lit}`Type`, {lit}`Prop`,
+  {lit}`Sort`, {lit}`max`, {lit}`imax`, {lit}`+`. Matches Dracula's "instance reserved words"
+  category.
+- Yellow: string literals.
+- Orange: numeric literals (currently surfaced via the boolean {lit}`extraCss` override below;
+  integer literals join once SubVerso tags numbers).
+- Red: error states.
+- Comment: doc comments.
+-/
+@[manual_theme]
+public def ManualTheme.dracula : ManualTheme :=
+  let code : CodeTheme := {
+    darkCodeBase with
+    name := Color.Palettes.DraculaClassic.name,
+    sourceLink := some Color.Palettes.DraculaClassic.sourceLink,
+    background := background,
+    codeBlockBackground := background,
+    textColor := foreground,
+    codeColor := foreground,
+    structureColor := foreground,
+    warningColor := foreground,
+    infoColor := foreground,
+    errorColor := red,
+    errorIndicatorColor := red,
+    warningIndicatorColor := orange,
+    infoIndicatorColor := cyan,
+    -- Hover popups land on the Selection color so they read as a raised surface tied to
+    -- the same palette.
+    hoverBackground := selection,
+    hoverText := foreground,
+    hoverBorderColor := currentLine,
+    hoverSeparatorColor := currentLine,
+    tokenHighlightBackground := selection,
+    tacticStateBackground := background,
+    tacticStateBorderColor := currentLine,
+    selectedColor := selection,
+    highlightOnCode := selection,
+    highlightOnText := selection,
+    uiOnCode := currentLine,
+    -- Token mapping per the Dracula spec's documented roles.
+    keyword.color := pink,
+    const.color := green,
+    «var».color := foreground,
+    literalString.color := yellow,
+    docComment.color := comment,
+    -- Universe grammar: sort formers and their operators share Purple, Dracula's
+    -- "instance reserved words" slot. `Type`, `Prop`, `Sort u`, `max`, `imax`, and `+`
+    -- (universe-level) all land on the same color so they read as one syntactic family.
+    sort := { color := purple, weight := .regular, style := .normal, face := .mono },
+    levelOp := { color := purple, weight := .regular, style := .normal, face := .mono },
+    -- Universe variables stay quiet (parallel to value-level `var`): body text, italic.
+    levelVar := { color := foreground, weight := .regular, style := .italic, face := .mono },
+    -- Numeric universe constants get the Orange "numbers" slot.
+    levelConst := { color := orange, weight := .regular, style := .normal, face := .mono },
+    -- Namespace paths land on Cyan ("classes, types, support").
+    moduleName := { color := cyan, weight := .regular, style := .normal, face := .mono },
+    -- The Dracula spec gives Orange to "numbers, constants, booleans". Verso doesn't yet have
+    -- a numeric-literal kind from the highlighter, but the `const` tokens for `Bool.true` and
+    -- `Bool.false` carry a `data-binding` attribute the highlighter emits, so a CSS attribute
+    -- selector can override their `const`-green color to the boolean Orange. When SubVerso
+    -- gains a numeric kind, the same trick (or a new `literal.number` rule) extends the same
+    -- treatment to integer literals.
+    extraCss := fun _ =>
+      ".hl.lean .const[data-binding=\"const-Bool.true\"],\n" ++
+      ".hl.lean .const[data-binding=\"const-Bool.false\"] { color: " ++ Color.css orange ++ "; }\n"
+  }
+  { darkChromeFields code with
+    -- Override the generic dark chrome with Dracula-palette values.
+    surfaceColor := selection,
+    tocBackground := background,
+    borderColor := currentLine,
+    mutedColor := comment,
+    linkColor := cyan,
+    visitedLinkColor := purple,
+    burgerVisibleShadowColor := background,
+    burgerHiddenColor := foreground,
+    burgerHiddenShadowColor := background,
+    licenses := #[Verso.Genre.Manual.Licenses.dracula] }
+
+open Color.Palettes.AlucardClassic in
+/--
+Alucard: the canonical light counterpart to Dracula from the official spec. Same documented
+token roles as {Lean.Doc.name}`ManualTheme.dracula`, drawn from the Alucard hex values
+(deeper saturations so each token meets WCAG AA contrast on the cream background).
+-/
+@[manual_theme]
+public def ManualTheme.alucard : ManualTheme where
+  toCodeTheme := {
+    CodeTheme.ink with
+    name := Color.Palettes.AlucardClassic.name,
+    sourceLink := some Color.Palettes.AlucardClassic.sourceLink,
+    background := background,
+    codeBlockBackground := background,
+    textColor := foreground,
+    codeColor := foreground,
+    structureColor := foreground,
+    warningColor := foreground,
+    infoColor := foreground,
+    errorColor := red,
+    errorIndicatorColor := red,
+    warningIndicatorColor := orange,
+    infoIndicatorColor := cyan,
+    hoverBackground := selection,
+    hoverText := foreground,
+    hoverBorderColor := currentLine,
+    hoverSeparatorColor := currentLine,
+    tokenHighlightBackground := selection,
+    tacticStateBorderColor := currentLine,
+    selectedColor := selection,
+    highlightOnCode := selection,
+    uiOnCode := currentLine,
+    keyword.color := pink,
+    const.color := green,
+    «var».color := foreground,
+    literalString.color := yellow,
+    docComment.color := comment,
+    -- Universe grammar: same Purple-grouped mapping as the dark Dracula. See that def for
+    -- the rationale.
+    sort := { color := purple, weight := .regular, style := .normal, face := .mono },
+    levelOp := { color := purple, weight := .regular, style := .normal, face := .mono },
+    levelVar := { color := foreground, weight := .regular, style := .italic, face := .mono },
+    levelConst := { color := orange, weight := .regular, style := .normal, face := .mono },
+    moduleName := { color := cyan, weight := .regular, style := .normal, face := .mono },
+    -- Same boolean-orange trick as the dark variant; see the Dracula def for the rationale.
+    extraCss := fun _ =>
+      ".hl.lean .const[data-binding=\"const-Bool.true\"],\n" ++
+      ".hl.lean .const[data-binding=\"const-Bool.false\"] { color: " ++ Color.css orange ++ "; }\n"
+  }
+  surfaceColor := selection
+  tocBackground := background
+  borderColor := currentLine
+  mutedColor := comment
+  linkColor := cyan
+  visitedLinkColor := purple
+  burgerVisibleShadowColor := background
+  burgerHiddenColor := foreground
+  burgerHiddenShadowColor := background
+  licenses := #[Verso.Genre.Manual.Licenses.dracula]
+
 /-! # Sandstone — warm sepia -/
 
 /-- Sandstone light: a warm cream background with terracotta and umber accents. -/
@@ -403,6 +685,9 @@ public def ManualTheme.sandstoneLight : ManualTheme where
   mutedColor := color%#7a5a40
   linkColor := color%#a04a00
   visitedLinkColor := color%#7a3a91
+  burgerVisibleShadowColor := color%#faf5ee
+  burgerHiddenColor := color%#3b2a17
+  burgerHiddenShadowColor := color%#faf5ee
 
 /--
 Sandstone dark: weathered canyon walls at dusk — deep terracotta substrate with sunlit-buff
@@ -496,6 +781,9 @@ public def ManualTheme.steel : ManualTheme where
   mutedColor := color%#465a70
   linkColor := color%#1a5ea8
   visitedLinkColor := color%#6c4ea8
+  burgerVisibleShadowColor := color%#f4f6f8
+  burgerHiddenColor := color%#0e2431
+  burgerHiddenShadowColor := color%#f4f6f8
 
 /-- Slate dark: coal/navy substrate, brightened slate accents. -/
 @[manual_theme]
@@ -572,6 +860,9 @@ public def ManualTheme.hearthLight : ManualTheme where
   mutedColor := color%#6b5640
   linkColor := color%#2f6e58
   visitedLinkColor := color%#7a3a91
+  burgerVisibleShadowColor := color%#f7f1de
+  burgerHiddenColor := color%#3d2f1f
+  burgerHiddenShadowColor := color%#f7f1de
 
 /--
 Hearth dark: a deep-olive candlelit substrate with warm cream text. Serifed structure font, same
diff --git a/src/verso/Verso/Code/Highlighted.lean b/src/verso/Verso/Code/Highlighted.lean
index 18526d4d6..67f104325 100644
--- a/src/verso/Verso/Code/Highlighted.lean
+++ b/src/verso/Verso/Code/Highlighted.lean
@@ -679,13 +679,72 @@ public def highlightingStyle : String := "
   position: relative;
 }
 
-.hl.lean .literal, .hl.lean .unknown {
+.hl.lean .unknown {
   color: var(--verso-code-color,);
   font-weight: normal;
   font-style: normal;
   font-family: var(--verso-code-font-family,);
 }
 
+.hl.lean .literal {
+  color: var(--verso-code-literal-color, var(--verso-code-color,));
+  font-weight: var(--verso-code-literal-weight, normal);
+  font-style: var(--verso-code-literal-style, normal);
+  font-family: var(--verso-code-literal-font-family, var(--verso-code-font-family,));
+}
+
+/* `.literal.string` is more specific than `.literal`, so its rule wins when both classes
+   apply (string literals). Other future `.literal.*` kinds will fall back to the `.literal`
+   rule above until they get their own variables. */
+.hl.lean .literal.string {
+  color: var(--verso-code-literal-string-color, var(--verso-code-literal-color, var(--verso-code-color,)));
+  font-weight: var(--verso-code-literal-string-weight, normal);
+  font-style: var(--verso-code-literal-string-style, normal);
+  font-family: var(--verso-code-literal-string-font-family, var(--verso-code-font-family,));
+}
+
+.hl.lean .doc-comment {
+  color: var(--verso-code-doc-comment-color, var(--verso-code-color,));
+  font-weight: var(--verso-code-doc-comment-weight, normal);
+  font-style: var(--verso-code-doc-comment-style, italic);
+  font-family: var(--verso-code-doc-comment-font-family, var(--verso-code-font-family,));
+}
+
+.hl.lean .sort {
+  color: var(--verso-code-sort-color, var(--verso-code-color,));
+  font-weight: var(--verso-code-sort-weight, normal);
+  font-style: var(--verso-code-sort-style, normal);
+  font-family: var(--verso-code-sort-font-family, var(--verso-code-font-family,));
+}
+
+.hl.lean .level-var {
+  color: var(--verso-code-level-var-color, var(--verso-code-color,));
+  font-weight: var(--verso-code-level-var-weight, normal);
+  font-style: var(--verso-code-level-var-style, italic);
+  font-family: var(--verso-code-level-var-font-family, var(--verso-code-font-family,));
+}
+
+.hl.lean .level-const {
+  color: var(--verso-code-level-const-color, var(--verso-code-color,));
+  font-weight: var(--verso-code-level-const-weight, normal);
+  font-style: var(--verso-code-level-const-style, normal);
+  font-family: var(--verso-code-level-const-font-family, var(--verso-code-font-family,));
+}
+
+.hl.lean .level-op {
+  color: var(--verso-code-level-op-color, var(--verso-code-color,));
+  font-weight: var(--verso-code-level-op-weight, normal);
+  font-style: var(--verso-code-level-op-style, normal);
+  font-family: var(--verso-code-level-op-font-family, var(--verso-code-font-family,));
+}
+
+.hl.lean .module-name {
+  color: var(--verso-code-module-name-color, var(--verso-code-color,));
+  font-weight: var(--verso-code-module-name-weight, normal);
+  font-style: var(--verso-code-module-name-style, normal);
+  font-family: var(--verso-code-module-name-font-family, var(--verso-code-font-family,));
+}
+
 .hover-container {
   width: 0;
   height: 0;
diff --git a/src/verso/Verso/Code/HighlightedToTex.lean b/src/verso/Verso/Code/HighlightedToTex.lean
index c2e30b46e..754157a85 100644
--- a/src/verso/Verso/Code/HighlightedToTex.lean
+++ b/src/verso/Verso/Code/HighlightedToTex.lean
@@ -32,27 +32,35 @@ public def highlightToken : String → Token.Kind → TeX
 | c, .anonCtor .. => .raw s!"\\versoConst\{{c}}"
 | c, .option _ _ _ => .raw s!"\\versoConst\{{c}}"
 | c, .var .. => .raw s!"\\versoVar\{{c}}"
-| c, .str _ => .raw s!"\\versoLiteral\{{c}}"
-| c, .docComment => .raw s!"\\versoLiteral\{{c}}"
-| c, .sort _ => .raw s!"\\versoLiteral\{{c}}"
-| c, .levelVar _ => .raw s!"\\versoLiteral\{{c}}"
-| c, .levelConst _ => .raw s!"\\versoLiteral\{{c}}"
-| c, .moduleName _ => .raw s!"\\versoLiteral\{{c}}"
-| c, .levelOp _ => .raw s!"\\versoLiteral\{{c}}"
+| c, .str _ => .raw s!"\\versoLiteralString\{{c}}"
+| c, .docComment => .raw s!"\\versoDocComment\{{c}}"
+| c, .sort _ => .raw s!"\\versoSort\{{c}}"
+| c, .levelVar _ => .raw s!"\\versoLevelVar\{{c}}"
+| c, .levelConst _ => .raw s!"\\versoLevelConst\{{c}}"
+| c, .moduleName _ => .raw s!"\\versoModuleName\{{c}}"
+| c, .levelOp _ => .raw s!"\\versoLevelOp\{{c}}"
 | c, .withType _ => .raw s!"\\versoLiteral\{{c}}"
 | c, .unknown => .raw s!"\\versoLiteral\{{c}}"
 
 /--
-Fallback definitions for the four semantic token macros emitted by
+Fallback definitions for the semantic token macros emitted by
 {name}`SubVerso.Highlighting.highlightToken`. Each uses `\providecommand`, so a genre
 preamble that defines its own (theme-driven) versions wins. The fallbacks reproduce today's
-unthemed look: keywords bold, variables italic, constants and literals plain.
+unthemed look: keywords bold, variables italic, constants and literals plain, doc comments
+italic.
 -/
 public def texMacroFallbacks : String :=
 "\\providecommand{\\versoKeyword}[1]{\\textbf{#1}}\n" ++
 "\\providecommand{\\versoConst}[1]{#1}\n" ++
 "\\providecommand{\\versoVar}[1]{\\textit{#1}}\n" ++
-"\\providecommand{\\versoLiteral}[1]{#1}\n"
+"\\providecommand{\\versoLiteral}[1]{#1}\n" ++
+"\\providecommand{\\versoLiteralString}[1]{#1}\n" ++
+"\\providecommand{\\versoDocComment}[1]{\\textit{#1}}\n" ++
+"\\providecommand{\\versoSort}[1]{#1}\n" ++
+"\\providecommand{\\versoLevelVar}[1]{\\textit{#1}}\n" ++
+"\\providecommand{\\versoLevelConst}[1]{#1}\n" ++
+"\\providecommand{\\versoLevelOp}[1]{#1}\n" ++
+"\\providecommand{\\versoModuleName}[1]{#1}\n"
 
 defmethod Highlighting.Token.toVerbatimTeX (t : Highlighting.Token) (lineBreaks : Bool := false) : Verso.Output.TeX :=
   highlightToken (escapeForVerbatim t.content lineBreaks) t.kind
diff --git a/src/verso/Verso/Theme/Code.lean b/src/verso/Verso/Theme/Code.lean
index 915426997..517346e25 100644
--- a/src/verso/Verso/Theme/Code.lean
+++ b/src/verso/Verso/Theme/Code.lean
@@ -51,9 +51,13 @@ public structure ThemeAsset where
 A typed code theme. Defaults reproduce today's hardcoded chrome, so a default-constructed theme is
 visually unchanged from the pre-theming look.
 
-Cascade-style defaults: fields that today read a CSS `var()` chain (for example a token color
-defaulting to the body code color) reference the earlier field directly. Lean evaluates the default
-at construction, so overriding a field overrides every later field that defaulted from it.
+Many field defaults refer to earlier fields (for example a token color defaults to
+{lit}`codeColor`, which in turn defaults to {lit}`textColor`). Lean evaluates defaults at
+the moment a theme value is constructed, so on a fresh construction overriding a referenced
+field propagates to every later field that defaulted from it. A {lit}`with` update against
+an *existing* theme value freezes the defaults that were already computed there, so a
+substantially different theme (a dark variant of a light base, say) needs to set the
+dependent fields explicitly.
 -/
 public structure CodeTheme where
   /-- A human-readable name for the theme (shown in the picker). -/
@@ -77,35 +81,32 @@ public structure CodeTheme where
   codeFace : Typeface := .mono
 
   /-- The page and content background color. The contrast reference for body text. -/
-  background : Color := Color.white
+  background : Color
   /-- The background behind code blocks. The contrast reference for token colors. -/
   codeBlockBackground : Color := background
   /-- The background behind inline code in prose. When set, inline code gets padding and rounding. -/
   inlineBackground : Option Color := none
   /-- The color of body prose text. -/
-  textColor : Color := Color.black
+  textColor : Color
   /-- The color of code text. -/
   codeColor : Color := textColor
   /-- The color used for structural decoration (such as case labels). -/
   structureColor : Color := textColor
   /-- The background color used to highlight a selected token in code. -/
-  selectedColor : Color := color%#ddeeff
+  selectedColor : Color
 
   /-- The message-text color for informational diagnostics. -/
   infoColor : Color := textColor
   /-- The accent color (left border, underline) for informational diagnostics. -/
-  infoIndicatorColor : Color := color%#4777ff
+  infoIndicatorColor : Color
   /-- The message-text color for warning diagnostics. -/
   warningColor : Color := textColor
-  /--
-  The accent color (left border, underline) for warning diagnostics. Defaults to a darker
-  amber than the legacy {lit}`#e7a71d` so it clears WCAG 1.4.11 (3:1) against white.
-  -/
-  warningIndicatorColor : Color := color%#d97706
+  /-- The accent color (left border, underline) for warning diagnostics. -/
+  warningIndicatorColor : Color
   /-- The message-text color for error diagnostics. -/
-  errorColor : Color := color%#cc0000
+  errorColor : Color
   /-- The accent color (left border, underline) for error diagnostics. -/
-  errorIndicatorColor : Color := color%#ff0000
+  errorIndicatorColor : Color
 
   /-- Token styling for constants. -/
   const : TokenStyle := { color := codeColor, weight := .regular, style := .normal, face := codeFace }
@@ -113,40 +114,87 @@ public structure CodeTheme where
   keyword : TokenStyle := { color := codeColor, weight := .bold, style := .normal, face := codeFace }
   /-- Token styling for variables (bound names). -/
   «var» : TokenStyle := { color := codeColor, weight := .regular, style := .italic, face := codeFace }
+  /--
+  Token styling for literal tokens. Today only string literals are tagged by the
+  highlighter, so the {lit}`{name}.string` field below is where strings get their color.
+  Other literal kinds (numbers, booleans) will gain distinct tags in future SubVerso
+  releases and will read from this field unless overridden.
+  -/
+  literal : TokenStyle := { color := codeColor, weight := .regular, style := .normal, face := codeFace }
+  /--
+  Token styling for string literals (CSS class {lit}`.literal.string`). Defaults to
+  {lit}`literal`; themes that want strings distinguished from other literals (e.g. Dracula's
+  yellow strings vs orange numbers) override it.
+  -/
+  literalString : TokenStyle := literal
+  /--
+  Token styling for doc comments (CSS class {lit}`.doc-comment`), i.e. {lit}`/-- … -/`
+  documentation blocks. SubVerso does not yet tag ordinary {lit}`--` line comments or
+  {lit}`/- … -/` block comments, so this field affects only the doc-comment kind.
+  -/
+  docComment : TokenStyle := { color := codeColor, weight := .regular, style := .italic, face := codeFace }
+  /--
+  Token styling for sort formers — {lit}`Type`, {lit}`Prop`, {lit}`Sort u`. CSS class
+  {lit}`.sort`. A distinct kind from {lit}`const` because sorts are the universe-of-types
+  formers, not ordinary named constants; themes typically color them in a different family
+  (often the "keyword" or "type" palette slot).
+  -/
+  sort : TokenStyle := { color := codeColor, weight := .regular, style := .normal, face := codeFace }
+  /--
+  Token styling for universe-level variables ({lit}`u`, {lit}`v`, … in a universe-parameter
+  context). CSS class {lit}`.level-var`. Bound-name semantics like {lit}`var`, but in the
+  level grammar.
+  -/
+  levelVar : TokenStyle := { color := codeColor, weight := .regular, style := .italic, face := codeFace }
+  /--
+  Token styling for universe-level numeric constants (the {lit}`3` in {lit}`Type 3`). CSS
+  class {lit}`.level-const`. A numeric literal in the level grammar.
+  -/
+  levelConst : TokenStyle := { color := codeColor, weight := .regular, style := .normal, face := codeFace }
+  /--
+  Token styling for universe-level operators ({lit}`max`, {lit}`imax`, {lit}`+`). CSS class
+  {lit}`.level-op`.
+  -/
+  levelOp : TokenStyle := { color := codeColor, weight := .regular, style := .normal, face := codeFace }
+  /--
+  Token styling for module names (an {lit}`import` target or a fully qualified namespace
+  path). CSS class {lit}`.module-name`. Distinct from {lit}`const` so themes can give
+  namespace paths a different treatment (often a quieter color).
+  -/
+  moduleName : TokenStyle := { color := codeColor, weight := .regular, style := .normal, face := codeFace }
 
   /-- The background of hover popups, diagnostic boxes, and tooltips. -/
-  hoverBackground : Color := color%#e5e5e5
+  hoverBackground : Color
   /-- The border color of hover popups and plain tooltips. -/
-  hoverBorderColor : Color := Color.black
+  hoverBorderColor : Color
   /-- The text color inside hover popups. -/
   hoverText : Color := textColor
   /-- The separator line color inside hover popups. -/
-  hoverSeparatorColor : Color := color%#cccccc
+  hoverSeparatorColor : Color
   /-- The background tint applied to a token on hover (independent of severity). -/
-  tokenHighlightBackground : Color := color%#eeeeee
+  tokenHighlightBackground : Color
   /--
-  The background of a displayed tactic state. Defaults to the surrounding
-  {name (full := CodeTheme.codeBlockBackground)}`codeBlockBackground`, so a theme
-  that recolors the code surface gets a matching tactic-state surface for free; themes that
-  want a distinct tactic-state tint (a slight raise to differentiate it from code) override
-  it explicitly.
+  The background of a displayed tactic state. Defaults to
+  {name (full := CodeTheme.codeBlockBackground)}`codeBlockBackground` for fresh constructions;
+  themes that want a distinct tactic-state tint (a slight raise to differentiate it from code)
+  override it explicitly.
   -/
   tacticStateBackground : Color := codeBlockBackground
   /-- The border color of a displayed tactic state. -/
-  tacticStateBorderColor : Color := color%#888888
+  tacticStateBorderColor : Color
 
   /--
   An accent background drawn behind highlighted code.
   {name (full := CodeTheme.codeColor)}`codeColor` must read on it.
   -/
-  highlightOnCode : Color := color%#fff3b0
+  highlightOnCode : Color
   /-- An accent background drawn behind highlighted code or prose. Both code and text must read on it. -/
   highlightOnText : Color := highlightOnCode
   /--
   A neutral UI element color drawn against
   {name (full := CodeTheme.codeBlockBackground)}`codeBlockBackground` (e.g. a toggle pill).
   -/
-  uiOnCode : Color := color%#888888
+  uiOnCode : Color
 
   /--
   Theme-specific CSS appended after the standard variable block. The asset root path the function
@@ -251,7 +299,15 @@ namespace CodeTheme
 private def tokenSummaries (theme : CodeTheme) : Array (String × Color) := #[
     ("const", theme.const.color),
     ("keyword", theme.keyword.color),
-    ("var", theme.«var».color)
+    ("var", theme.«var».color),
+    ("literal", theme.literal.color),
+    ("literal.string", theme.literalString.color),
+    ("doc-comment", theme.docComment.color),
+    ("sort", theme.sort.color),
+    ("level-var", theme.levelVar.color),
+    ("level-const", theme.levelConst.color),
+    ("level-op", theme.levelOp.color),
+    ("module-name", theme.moduleName.color)
   ]
 
 /--
@@ -369,6 +425,14 @@ public def cssVariables (theme : CodeTheme) : String :=
     styleDecls "verso-code-const" theme.const,
     styleDecls "verso-code-keyword" theme.keyword,
     styleDecls "verso-code-var" theme.«var»,
+    styleDecls "verso-code-literal" theme.literal,
+    styleDecls "verso-code-literal-string" theme.literalString,
+    styleDecls "verso-code-doc-comment" theme.docComment,
+    styleDecls "verso-code-sort" theme.sort,
+    styleDecls "verso-code-level-var" theme.levelVar,
+    styleDecls "verso-code-level-const" theme.levelConst,
+    styleDecls "verso-code-level-op" theme.levelOp,
+    styleDecls "verso-code-module-name" theme.moduleName,
     colorDecl "verso-hover-background-color" theme.hoverBackground,
     colorDecl "verso-hover-border-color" theme.hoverBorderColor,
     colorDecl "verso-hover-text-color" theme.hoverText,
@@ -427,6 +491,14 @@ public def texPreamble (theme : CodeTheme) : String :=
   let constColor := Color.tex theme.const.color
   let keywordColor := Color.tex theme.keyword.color
   let varColor := Color.tex theme.«var».color
+  let literalColor := Color.tex theme.literal.color
+  let literalStringColor := Color.tex theme.literalString.color
+  let docCommentColor := Color.tex theme.docComment.color
+  let sortColor := Color.tex theme.sort.color
+  let levelVarColor := Color.tex theme.levelVar.color
+  let levelConstColor := Color.tex theme.levelConst.color
+  let levelOpColor := Color.tex theme.levelOp.color
+  let moduleNameColor := Color.tex theme.moduleName.color
   -- Per the structure's semantics, the `*Color` fields are message-text colors and
   -- `*IndicatorColor` are accent colors (underlines, frames, dingbats). Emit both as separate
   -- `\definecolor` entries so the preamble can reference whichever the rule needs.
@@ -441,6 +513,14 @@ public def texPreamble (theme : CodeTheme) : String :=
     s!"\\definecolor\{versoConstColor}\{HTML}\{{constColor}}\n",
     s!"\\definecolor\{versoKeywordColor}\{HTML}\{{keywordColor}}\n",
     s!"\\definecolor\{versoVarColor}\{HTML}\{{varColor}}\n",
+    s!"\\definecolor\{versoLiteralColor}\{HTML}\{{literalColor}}\n",
+    s!"\\definecolor\{versoLiteralStringColor}\{HTML}\{{literalStringColor}}\n",
+    s!"\\definecolor\{versoDocCommentColor}\{HTML}\{{docCommentColor}}\n",
+    s!"\\definecolor\{versoSortColor}\{HTML}\{{sortColor}}\n",
+    s!"\\definecolor\{versoLevelVarColor}\{HTML}\{{levelVarColor}}\n",
+    s!"\\definecolor\{versoLevelConstColor}\{HTML}\{{levelConstColor}}\n",
+    s!"\\definecolor\{versoLevelOpColor}\{HTML}\{{levelOpColor}}\n",
+    s!"\\definecolor\{versoModuleNameColor}\{HTML}\{{moduleNameColor}}\n",
     s!"\\definecolor\{errorColor}\{HTML}\{{errorTextColor}}\n",
     s!"\\definecolor\{warningColor}\{HTML}\{{warningTextColor}}\n",
     s!"\\definecolor\{infoColor}\{HTML}\{{infoTextColor}}\n",
@@ -450,7 +530,14 @@ public def texPreamble (theme : CodeTheme) : String :=
     tokenMacro "Keyword" theme.keyword "versoKeywordColor",
     tokenMacro "Const" theme.const "versoConstColor",
     tokenMacro "Var" theme.«var» "versoVarColor",
-    s!"\\renewcommand\{\\versoLiteral}[1]\{\\textcolor\{versoCodeColor}\{#1}}\n",
+    tokenMacro "Literal" theme.literal "versoLiteralColor",
+    tokenMacro "LiteralString" theme.literalString "versoLiteralStringColor",
+    tokenMacro "DocComment" theme.docComment "versoDocCommentColor",
+    tokenMacro "Sort" theme.sort "versoSortColor",
+    tokenMacro "LevelVar" theme.levelVar "versoLevelVarColor",
+    tokenMacro "LevelConst" theme.levelConst "versoLevelConstColor",
+    tokenMacro "LevelOp" theme.levelOp "versoLevelOpColor",
+    tokenMacro "ModuleName" theme.moduleName "versoModuleNameColor",
     s!"\\setmonofont\{{theme.codeFace.texFamily}}\n"
   ]
 
diff --git a/src/verso/Verso/Theme/Code/Defaults.lean b/src/verso/Verso/Theme/Code/Defaults.lean
index 2f5cc9dc1..265de523e 100644
--- a/src/verso/Verso/Theme/Code/Defaults.lean
+++ b/src/verso/Verso/Theme/Code/Defaults.lean
@@ -23,8 +23,24 @@ namespace Verso.Theme
 The default code theme.
 
 This theme uses only typographical features to distinguish code elements, rather than color.
+The page is white, body and code text are black, and diagnostic accents match the pre-theming
+hardcoded values.
 -/
 @[code_theme]
 public def CodeTheme.ink : CodeTheme where
   name := "Ink"
   appearance := .light
+  background := Color.white
+  textColor := Color.black
+  selectedColor := color%#ddeeff
+  infoIndicatorColor := color%#4777ff
+  warningIndicatorColor := color%#d97706
+  errorColor := color%#cc0000
+  errorIndicatorColor := color%#ff0000
+  hoverBackground := color%#e5e5e5
+  hoverBorderColor := Color.black
+  hoverSeparatorColor := color%#cccccc
+  tokenHighlightBackground := color%#eeeeee
+  tacticStateBorderColor := color%#888888
+  highlightOnCode := color%#fff3b0
+  uiOnCode := color%#888888
diff --git a/src/verso/Verso/Theme/Color/Palettes.lean b/src/verso/Verso/Theme/Color/Palettes.lean
index 027e4fab9..ecc59af45 100644
--- a/src/verso/Verso/Theme/Color/Palettes.lean
+++ b/src/verso/Verso/Theme/Color/Palettes.lean
@@ -8,6 +8,7 @@ module
 public import Verso.Theme.Color.Palettes.Solarized
 public import Verso.Theme.Color.Palettes.OkabeIto
 public import Verso.Theme.Color.Palettes.Nord
+public import Verso.Theme.Color.Palettes.Dracula
 
 /-!
 {open Verso.Theme}
diff --git a/src/verso/Verso/Theme/Color/Palettes/Dracula.lean b/src/verso/Verso/Theme/Color/Palettes/Dracula.lean
new file mode 100644
index 000000000..7186365b4
--- /dev/null
+++ b/src/verso/Verso/Theme/Color/Palettes/Dracula.lean
@@ -0,0 +1,152 @@
+/-
+Copyright (c) 2026 Lean FRO LLC. All rights reserved.
+Released under Apache 2.0 license as described in the file LICENSE.
+Author: David Thrane Christiansen
+-/
+
+/-
+The Dracula and Alucard hex constants below are reproduced from the official Dracula spec at
+<https://draculatheme.com/spec>. The Dracula spec is distributed under the MIT license. The
+notice is reproduced here verbatim per the license's attribution clause; the manual genre
+also includes it in the attribution page of any generated manual that includes a Dracula or
+Alucard theme.
+
+  The MIT License (MIT)
+
+  Copyright (c) 2020 Dracula Theme
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy of this
+  software and associated documentation files (the "Software"), to deal in the Software
+  without restriction, including without limitation the rights to use, copy, modify, merge,
+  publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons
+  to whom the Software is furnished to do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all copies or
+  substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+  INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+  PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+  FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+  OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+  DEALINGS IN THE SOFTWARE.
+-/
+module
+
+public import Verso.Theme.Color.Basic
+public import Verso.Theme.Color.Syntax
+public import Verso.Theme.SourceLink
+
+set_option linter.missingDocs true
+set_option doc.verso true
+
+/-!
+{open Verso.Theme}
+
+The *Dracula* and *Alucard* palettes from the [official Dracula spec](https://draculatheme.com/spec)
+as named {name}`Color` constants. The Dracula Classic palette is the canonical dark theme
+(Dracula); Alucard Classic is its light-substrate counterpart (named after the *Castlevania*
+character, Dracula spelled backwards).
+
+Both palettes share twelve color slots with documented semantic intent. The hex values are
+the canonical ones from <https://draculatheme.com/spec>.
+-/
+
+namespace Verso.Theme.Color.Palettes
+
+/-! # Dracula Classic — the canonical dark palette -/
+
+namespace DraculaClassic
+
+/-- The palette's display name, suitable as a prefix when naming themes built on it. -/
+public def name : String := "Dracula"
+
+/-- The official Dracula spec page, shown in the picker for themes that use this palette. -/
+public def sourceLink : SourceLink :=
+  { url := "https://draculatheme.com/spec", text := "draculatheme.com/spec" }
+
+/-- Dracula Background ({lit}`#282A36`). Documented role: main background. -/
+public def background : Color := color%#282A36
+/--
+Dracula Current Line ({lit}`#6272A4`). Documented role: semantic current-line highlight
+(the active line indicator in editors).
+-/
+public def currentLine : Color := color%#6272A4
+/-- Dracula Selection ({lit}`#44475A`). Documented role: text selection. -/
+public def selection : Color := color%#44475A
+/-- Dracula Foreground ({lit}`#F8F8F2`). Documented role: default text. -/
+public def foreground : Color := color%#F8F8F2
+/-- Dracula Comment ({lit}`#6272A4`). Documented role: comments and disabled code. -/
+public def comment : Color := color%#6272A4
+/-- Dracula Red ({lit}`#FF5555`). Documented role: errors, warnings, deletions. -/
+public def red : Color := color%#FF5555
+/-- Dracula Orange ({lit}`#FFB86C`). Documented role: numbers, constants, booleans. -/
+public def orange : Color := color%#FFB86C
+/-- Dracula Yellow ({lit}`#F1FA8C`). Documented role: strings and text content. -/
+public def yellow : Color := color%#F1FA8C
+/--
+Dracula Green ({lit}`#50FA7B`). Documented role: functions, methods, inherited classes.
+-/
+public def green : Color := color%#50FA7B
+/--
+Dracula Cyan ({lit}`#8BE9FD`). Documented role: classes, types, support, regular
+expressions.
+-/
+public def cyan : Color := color%#8BE9FD
+/--
+Dracula Purple ({lit}`#BD93F9`). Documented role: instance reserved words and constants.
+-/
+public def purple : Color := color%#BD93F9
+/-- Dracula Pink ({lit}`#FF79C6`). Documented role: keywords and storage types. -/
+public def pink : Color := color%#FF79C6
+
+end DraculaClassic
+
+/-! # Alucard Classic — the canonical light counterpart -/
+
+namespace AlucardClassic
+
+/-- The palette's display name, suitable as a prefix when naming themes built on it. -/
+public def name : String := "Alucard"
+
+/-- The official Dracula spec page, shown in the picker for themes that use this palette. -/
+public def sourceLink : SourceLink :=
+  { url := "https://draculatheme.com/spec", text := "draculatheme.com/spec" }
+
+/-- Alucard Background ({lit}`#FFFBEB`). Documented role: main background. -/
+public def background : Color := color%#FFFBEB
+/--
+Alucard Current Line ({lit}`#6C664B`). Documented role: semantic current-line highlight.
+-/
+public def currentLine : Color := color%#6C664B
+/-- Alucard Selection ({lit}`#CFCFDE`). Documented role: text selection. -/
+public def selection : Color := color%#CFCFDE
+/-- Alucard Foreground ({lit}`#1F1F1F`). Documented role: default text. -/
+public def foreground : Color := color%#1F1F1F
+/-- Alucard Comment ({lit}`#6C664B`). Documented role: comments and disabled code. -/
+public def comment : Color := color%#6C664B
+/-- Alucard Red ({lit}`#CB3A2A`). Documented role: errors, warnings, deletions. -/
+public def red : Color := color%#CB3A2A
+/-- Alucard Orange ({lit}`#A34D14`). Documented role: numbers, constants, booleans. -/
+public def orange : Color := color%#A34D14
+/-- Alucard Yellow ({lit}`#846E15`). Documented role: strings and text content. -/
+public def yellow : Color := color%#846E15
+/--
+Alucard Green ({lit}`#14710A`). Documented role: functions, methods, inherited classes.
+-/
+public def green : Color := color%#14710A
+/--
+Alucard Cyan ({lit}`#036A96`). Documented role: classes, types, support, regular
+expressions.
+-/
+public def cyan : Color := color%#036A96
+/--
+Alucard Purple ({lit}`#644AC9`). Documented role: instance reserved words and constants.
+-/
+public def purple : Color := color%#644AC9
+/-- Alucard Pink ({lit}`#A3144D`). Documented role: keywords and storage types. -/
+public def pink : Color := color%#A3144D
+
+end AlucardClassic
+
+end Verso.Theme.Color.Palettes
diff --git a/src/verso/Verso/Theme/Color/color-swatch.js b/src/verso/Verso/Theme/Color/color-swatch.js
index ef9928ad2..b0dd72bc1 100644
--- a/src/verso/Verso/Theme/Color/color-swatch.js
+++ b/src/verso/Verso/Theme/Color/color-swatch.js
@@ -47,7 +47,7 @@ export default function (props) {
         e(
             "div",
             { style: { fontSize: "0.75em", opacity: 0.6, padding: "0 0.4em 0.1em" } },
-            "Color vision deficiency",
+            "Simulated color vision differences",
         ),
         cvdRow("Protanopia", props.protanopia),
         cvdRow("Deuteranopia", props.deuteranopia),

From 0f89a35e1f88b2c2845c863f1dd45282fe905f81 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Mon, 1 Jun 2026 12:06:47 +0200
Subject: [PATCH 18/31] Match upstream themes better

---
 .../VersoManual/Theme/Defaults.lean           | 107 +++++++++++-------
 1 file changed, 68 insertions(+), 39 deletions(-)

diff --git a/src/verso-manual/VersoManual/Theme/Defaults.lean b/src/verso-manual/VersoManual/Theme/Defaults.lean
index bad376475..84809eb35 100644
--- a/src/verso-manual/VersoManual/Theme/Defaults.lean
+++ b/src/verso-manual/VersoManual/Theme/Defaults.lean
@@ -225,10 +225,13 @@ public def ManualTheme.beaconLight : ManualTheme :=
 
 open Color.Palettes.OkabeIto in
 /--
-Beacon dark: the Okabe-Ito palette on a near-black background. Same colorblind-safe goals as
-{Lean.Doc.name}`ManualTheme.beaconLight`, with the hues that are brightest on dark substrates
-({lit}`skyBlue`, {lit}`yellow`) carrying the most-used token kinds. Typography (bold, italic)
-disambiguates kinds that share a hue, the same way the light variant does.
+Beacon dark: a Verso-side adaptation of the Okabe-Ito palette to a near-black background.
+Okabe and Ito designed the palette for scientific visualization on white substrates; the
+upstream specification does not define a dark-substrate syntax theme, so the token-to-hue
+mapping here is a Verso choice that preserves the canonical colorblind-distinguishability
+property while picking which hue carries which token kind. {lit}`skyBlue` and {lit}`yellow`
+carry the most-used kinds because they are brightest on dark substrates; typography (bold,
+italic) disambiguates kinds that share a hue, the same way the light variant does.
 -/
 @[manual_theme]
 public def ManualTheme.beaconDark : ManualTheme :=
@@ -251,15 +254,17 @@ public def ManualTheme.beaconDark : ManualTheme :=
 
 open Color.Palettes.Solarized in
 /--
-Solarized light: Schoonover's standard cream-on-paper palette ({lit}`base3` background,
-{lit}`base01` primary content). Token mapping uses canonical Solarized hues per common port
+Solarized light: Schoonover's standard cream-on-paper palette. Surface and foreground follow
+the canonical rebasing rules — {lit}`base3` background, {lit}`base00` primary body content,
+{lit}`base01` for emphasized content (headings, structural decoration), {lit}`base1` for
+secondary content (comments and muted chrome text). Accent hues map per common port
 conventions:
 
 - {lit}`green` → keywords
 - {lit}`blue` → defined names ({lit}`const`)
 - {lit}`violet` → bound variables ({lit}`var`)
 - {lit}`cyan` → string literals
-- {lit}`base1` → doc comments (Solarized's documented muted comment hue)
+- {lit}`base1` → doc comments (Solarized's documented muted secondary-content hue)
 - {lit}`yellow` → {lit}`Type`/{lit}`Prop`/{lit}`Sort` formers
 - {lit}`orange` → numeric literals (including universe-level numerics)
 - {lit}`magenta` → universe operators ({lit}`max`, {lit}`imax`) and module/namespace paths
@@ -277,17 +282,18 @@ public def ManualTheme.solarizedLight : ManualTheme :=
       sourceLink := some Color.Palettes.Solarized.sourceLink,
       background := base3,
       codeBlockBackground := base2,
-      textColor := base01,
-      codeColor := base01,
+      textColor := base00,
+      codeColor := base00,
+      -- Structural decoration (case labels) uses the canonical emphasized-content shade.
       structureColor := base01,
-      warningColor := base01,
-      infoColor := base01,
+      warningColor := base00,
+      infoColor := base00,
       errorColor := red,
       errorIndicatorColor := red,
       warningIndicatorColor := yellow,
       infoIndicatorColor := blue,
       hoverBackground := base2,
-      hoverText := base01,
+      hoverText := base00,
       hoverBorderColor := base1,
       hoverSeparatorColor := base1,
       tokenHighlightBackground := base2,
@@ -298,7 +304,7 @@ public def ManualTheme.solarizedLight : ManualTheme :=
       keyword := { color := green, weight := .bold, style := .normal, face := .mono },
       const := { color := blue, weight := .regular, style := .normal, face := .mono },
       «var» := { color := violet, weight := .regular, style := .italic, face := .mono },
-      literal := { color := base01, weight := .regular, style := .normal, face := .mono },
+      literal := { color := base00, weight := .regular, style := .normal, face := .mono },
       literalString := { color := cyan, weight := .regular, style := .normal, face := .mono },
       docComment := { color := base1, weight := .regular, style := .italic, face := .mono },
       sort := { color := yellow, weight := .regular, style := .normal, face := .mono },
@@ -310,7 +316,8 @@ public def ManualTheme.solarizedLight : ManualTheme :=
     surfaceColor := base2,
     tocBackground := base2,
     borderColor := base01,
-    mutedColor := base00,
+    -- Muted chrome text uses Solarized's "secondary content" shade.
+    mutedColor := base1,
     linkColor := blue,
     visitedLinkColor := violet,
     burgerVisibleShadowColor := base3,
@@ -321,11 +328,12 @@ public def ManualTheme.solarizedLight : ManualTheme :=
 
 open Color.Palettes.Solarized in
 /--
-Solarized dark: Schoonover's standard {lit}`base03` background with body text on {lit}`base1`.
-Token mapping uses canonical Solarized hues (the same accent assignments as
-{Lean.Doc.name}`ManualTheme.solarizedLight`); the relative-luminance jump comes entirely
-from the substrate. Doc comments use {lit}`base01`, Solarized's documented muted comment hue
-for dark substrates (lower contrast than body text, by design).
+Solarized dark: Schoonover's standard {lit}`base03` background. Surface and foreground follow
+the canonical rebasing rules — {lit}`base03` background, {lit}`base0` primary body content,
+{lit}`base1` for emphasized content (headings, structural decoration), {lit}`base01` for
+secondary content (comments and muted chrome text). Token accent assignments match
+{Lean.Doc.name}`ManualTheme.solarizedLight`; the relative-luminance jump comes entirely from
+the substrate.
 -/
 @[manual_theme]
 public def ManualTheme.solarizedDark : ManualTheme :=
@@ -335,28 +343,29 @@ public def ManualTheme.solarizedDark : ManualTheme :=
     sourceLink := some Color.Palettes.Solarized.sourceLink,
     background := base03,
     codeBlockBackground := base02,
-    textColor := base1,
-    codeColor := base1,
+    textColor := base0,
+    codeColor := base0,
+    -- Structural decoration uses the canonical emphasized-content shade.
     structureColor := base1,
-    warningColor := base1,
-    infoColor := base1,
+    warningColor := base0,
+    infoColor := base0,
     errorColor := red,
     errorIndicatorColor := red,
     warningIndicatorColor := yellow,
     infoIndicatorColor := blue,
     hoverBackground := base02,
-    hoverText := base1,
+    hoverText := base0,
     hoverBorderColor := base01,
     hoverSeparatorColor := base01,
     tokenHighlightBackground := base02,
     tacticStateBorderColor := base01,
     selectedColor := base02,
     highlightOnCode := color%#3a2f00,
-    uiOnCode := base1,
+    uiOnCode := base01,
     keyword := { color := green, weight := .bold, style := .normal, face := .mono },
     const := { color := blue, weight := .regular, style := .normal, face := .mono },
     «var» := { color := violet, weight := .regular, style := .italic, face := .mono },
-    literal := { color := base1, weight := .regular, style := .normal, face := .mono },
+    literal := { color := base0, weight := .regular, style := .normal, face := .mono },
     literalString := { color := cyan, weight := .regular, style := .normal, face := .mono },
     docComment := { color := base01, weight := .regular, style := .italic, face := .mono },
     sort := { color := yellow, weight := .regular, style := .normal, face := .mono },
@@ -365,10 +374,17 @@ public def ManualTheme.solarizedDark : ManualTheme :=
     levelOp := { color := magenta, weight := .regular, style := .normal, face := .mono },
     moduleName := { color := magenta, weight := .regular, style := .normal, face := .mono }
   } with
-    -- Override the dark-chrome link defaults with the canonical Solarized blue/violet (they
-    -- clear contrast on `base03`).
+    -- Solarized-tinted chrome instead of the generic dark-chrome accents.
+    surfaceColor := base02,
+    tocBackground := base02,
+    borderColor := base01,
+    mutedColor := base01,
     linkColor := blue,
     visitedLinkColor := violet,
+    burgerHiddenColor := base0,
+    burgerVisibleColor := base0,
+    burgerHiddenShadowColor := base03,
+    burgerVisibleShadowColor := base03,
     licenses := #[Verso.Genre.Manual.Licenses.solarized] }
 
 /-! # Nord — Sven Greb's arctic, north-bluish palette -/
@@ -437,13 +453,22 @@ public def ManualTheme.nord : ManualTheme :=
 
 open Color.Palettes.Nord in
 /--
-Nord Light: the inverse Snow Storm substrate ({lit}`nord6` page, {lit}`nord5` code blocks)
-with the canonical Nord hues for tokens. The same documented mapping as
-{Lean.Doc.name}`ManualTheme.nord` applies. Note that Nord — like Solarized — wasn't designed
-for a light substrate, so several token colors (Frost {lit}`nord7`–{lit}`nord9`, Aurora
-{lit}`nord13`–{lit}`nord14`) fall below WCAG AA contrast on {lit}`nord6`. Authors who care
-about strict accessibility on a light background should pick a different theme; the canonical
-hex values are preserved here so the look matches other Nord Light ports.
+Nord Light: Nord's bright-ambiance configuration as documented by the upstream spec —
+{lit}`nord6` as page background, {lit}`nord5` as the selection / active-line /
+text-highlight color, {lit}`nord0` as the plain syntax text color. Token accent assignments
+mirror the dark variant: the canonical Nord Frost and Aurora hues drive
+keyword/const/string/sort/etc., per Nord's documented per-color usage table.
+
+The spec does not explicitly designate a bright-ambiance color for syntax variables
+({lit}`nord4` is reserved for the dark-ambiance variable hue and is illegible on {lit}`nord6`),
+so {lit}`nord3` (Polar Night, documented "comments / indent guides") is reused with italic for
+{lit}`var`/{lit}`levelVar`/{lit}`docComment` — a pragmatic choice, not an upstream mapping.
+
+Several canonical Nord token colors — Frost {lit}`nord7`–{lit}`nord9` and Aurora
+{lit}`nord13`/{lit}`nord14` — fall below WCAG AA 4.5 against {lit}`nord6`. The per-theme
+accessibility check flags these and the suite-wide setting `warnPerThemeAccessibility` can
+downgrade them. The canonical hex values are preserved so the look matches other Nord Light
+ports.
 -/
 @[manual_theme]
 public def ManualTheme.nordLight : ManualTheme where
@@ -468,11 +493,15 @@ public def ManualTheme.nordLight : ManualTheme where
     hoverSeparatorColor := nord3,
     tokenHighlightBackground := nord5,
     tacticStateBorderColor := nord3,
-    selectedColor := nord4,
-    highlightOnCode := nord4,
+    -- Per the Nord spec, `nord5` is the documented bright-ambiance selection / text-highlight
+    -- color.
+    selectedColor := nord5,
+    highlightOnCode := nord5,
     uiOnCode := nord3,
-    -- Canonical Nord token mapping. `var` borrows `nord3` (the documented comments color)
-    -- because `nord4` is the dark-mode variable hue, which is illegible on `nord6`.
+    -- Canonical Nord token mapping. `var`/`levelVar`/`docComment` reuse `nord3` (the
+    -- documented "comments / indent guides" color) because the spec does not designate a
+    -- bright-ambiance variable hue and `nord4` (the dark-mode variable color) is illegible
+    -- on `nord6`.
     keyword := { color := nord9, weight := .bold, style := .normal, face := .mono },
     const := { color := nord8, weight := .regular, style := .normal, face := .mono },
     «var» := { color := nord3, weight := .regular, style := .italic, face := .mono },

From 9edc72cb45822cb584978e5df324ff2b95812248 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Tue, 2 Jun 2026 15:23:44 +0200
Subject: [PATCH 19/31] docs for themes

---
 doc/UsersGuide/Manuals.lean            | 200 +++++++++++++++++++++++++
 doc/UsersGuide/Output.lean             | 185 +++++++++++++++++++++++
 src/verso-manual/VersoManual.lean      |   7 +-
 src/verso/Verso/Theme/Color/Types.lean |   3 +-
 4 files changed, 392 insertions(+), 3 deletions(-)

diff --git a/doc/UsersGuide/Manuals.lean b/doc/UsersGuide/Manuals.lean
index 57b2c94c4..8e404faf9 100644
--- a/doc/UsersGuide/Manuals.lean
+++ b/doc/UsersGuide/Manuals.lean
@@ -304,3 +304,203 @@ The {name}`diagram` code block accepts an `inline` flag that marks it for inline
 Building PDFs from LaTeX output relies on the `svg` LaTeX package, which calls Inkscape to convert each emitted SVG to PDF at build time.
 This requires `inkscape` on the `PATH` as well as running `lualatex` with the `-shell-escape` flag.
 This flag allows LaTeX to execute arbitrary commands during compilation.
+
+# Themes
+%%%
+tag := "manual-themes"
+%%%
+
+The manual genre includes support for themes.
+Authors may select any number of themes to include, and readers may select any of these themes while reading.
+A theme for a manual includes a {ref "output-code-themes"}[code theme], in addition to selecting fonts and colors for the text and navigation interface.
+
+## Overview
+%%%
+tag := "manual-themes-overview"
+%%%
+
+The rendered HTML for a manual includes a "gear" button in the header that opens a popover widget.
+This widget offers two choices:
+ * A single theme, to be chose from a list and always used
+ * A light theme and a dark theme, to be selected automatically based on the browser's `prefers-color-scheme` setting.
+
+
+## The `ManualTheme` Structure
+%%%
+tag := "manual-themes-structure"
+%%%
+
+Authors specify a manual theme as a definition of type {name Verso.Theme.ManualTheme}`ManualTheme`.
+Manual themes must be registered using the `@[manual_theme]` attribute.
+Manual themes extend {ref "output-code-themes"}[code themes] with fonts and colors for textual content and navigation features.
+
+{docstring Theme.ManualTheme}
+
+## Built-In Themes
+%%%
+tag := "manual-themes-builtins"
+%%%
+
+
+```lean -show
+open Verso.Theme in
+/--
+info:
+Alucard (Verso.Theme.ManualTheme.alucard)
+Argent (Verso.Theme.ManualTheme.argent)
+Beacon Dark (Verso.Theme.ManualTheme.beaconDark)
+Beacon Light (Verso.Theme.ManualTheme.beaconLight)
+Chromatic Dark (Verso.Theme.ManualTheme.chromaticDark)
+Chromatic Light (Verso.Theme.ManualTheme.chromaticLight)
+Dracula (Verso.Theme.ManualTheme.dracula)
+Hearth Dark (Verso.Theme.ManualTheme.hearthDark)
+Hearth Light (Verso.Theme.ManualTheme.hearthLight)
+Ink (Verso.Theme.ManualTheme.ink)
+Nord (Verso.Theme.ManualTheme.nord)
+Nord Light (Verso.Theme.ManualTheme.nordLight)
+Sandstone Dark (Verso.Theme.ManualTheme.sandstoneDark)
+Sandstone Light (Verso.Theme.ManualTheme.sandstoneLight)
+Slate (Verso.Theme.ManualTheme.slate)
+Solarized Dark (Verso.Theme.ManualTheme.solarizedDark)
+Solarized Light (Verso.Theme.ManualTheme.solarizedLight)
+Steel (Verso.Theme.ManualTheme.steel)
+-/
+#guard_msgs in
+#eval show IO Unit from do
+  let table : ManualThemeTable := manual_themes%
+  let entries := table.themes.toList.map
+    (fun (p : Lean.Name × ManualTheme) => s!"{p.snd.name} ({p.fst})")
+  IO.println ""
+  for line in entries.toArray.qsort (· < ·) do
+    IO.println line
+```
+
+### Defaults: Ink and Argent
+%%%
+tag := "manual-default-themes"
+%%%
+
+The default light and dark themes are called _Ink_ and _Argent_, respectively.
+These themes use understated formatting, relying on typographical features such as weight and slant syntax and semantic highlighting.
+
+### Other Included Themes
+%%%
+tag := "manual-other-themes"
+%%%
+
+The remaining shipped themes fall into seven families, each with a light variant and a dark variant.
+
+: Chromatic
+
+  The _Chromatic_ themes are versions of _Ink_ and _Argent_ that use color in addition to typographical features for syntax highlighting.
+
+: Beacon
+
+  The _Beacon_ themes are variants of _Ink_ and _Argent_ that use the [Okabe-Ito palette](https://jfly.uni-koeln.de/color/) to ensure that different colors are distinct for readers with various forms of colorblindness.
+
+: Solarized
+
+  These themes use Schoonover's [Solarized](https://ethanschoonover.com/solarized/) palettes.
+  Note that these low-contrast themes are not particularly accessible, and thus should probably not be the default theme for a document.
+
+: Dracula and Alucard
+
+  _Dracula_ and _Alucard_ implement the [Dracula](https://draculatheme.com/spec) family of themes.
+
+
+: Nord
+
+  Greb's arctic, north-bluish [Nord](https://www.nordtheme.com/) palette in a Polar Night dark variant and a Snow Storm light variant.
+
+: Sandstone
+
+  The _Sandstone_ themes are a warm-sepia family: a cream-with-terracotta light variant and a deep canyon-shadow dark variant, both inspired by the deserts of the Southwest USA.
+
+: Steel and Slate
+
+  _Steel_ and _Slate_ use cool, high-contrast neutral colors.
+
+: Hearth
+
+  The _Hearth_ themes have a cream-and-sage light variant and a candlelit deep-olive dark variant, and use serif fonts.
+
+
+
+## Configuration
+%%%
+tag := "manual-themes-configuration"
+%%%
+
+The following fields of {name}`RenderConfig` are relevant to themes:
+
+: {name RenderConfig.availableThemes}`availableThemes`
+
+  This field lists the available themes. By default, it contains all themes that are registered with `@[manual_theme]`.
+  Authors can restrict readers to a subset of the registered themes by listing the desired themes here.
+
+: {name RenderConfig.defaultLightTheme}`defaultLightTheme`
+
+  When readers have configured their themes to follow the system preference, this is the default light theme.
+
+: {name RenderConfig.defaultDarkTheme}`defaultDarkTheme`
+
+  When readers have configured their themes to follow the system preference, this is the default dark theme.
+
+: {name RenderConfig.defaultSingleAppearance}`defaultSingleAppearance`
+
+  When readers have configured their themes to ignore the browser's request, this is the default theme. It may be light or dark.
+
+
+## Accessibility Checking
+%%%
+tag := "manual-themes-accessibility"
+%%%
+
+By default, manual themes are checked for common accessibility problems, including insufficient contrast between text and background and the use of colors that not all readers can distinguish.
+Verso issues a warning when an inaccessible theme is included, and it is an error when an inaccessible theme is the default.
+These checks are incomplete: themes may have accessibility problems that are not related to their choices of colors, and the automated tests do not take custom CSS into account.
+
+
+: {name Config.strictThemeCoverage}`strictThemeCoverage`
+
+  Verifies that the set of available themes offers at least one accessible choice for each appearance a reader might select.
+  With a single available theme, that theme must be accessible; with multiple available themes, at least one accessible light theme and one accessible dark theme must exist.
+  If {lean}`true` (the default), failing this check is an error.
+  If {lean}`false`, failing this check results in a warning.
+
+: {name Config.strictDefaultThemeAccessibility}`strictDefaultThemeAccessibility`
+
+  When {name}`true` (the default), Verso verifies that the configured {name RenderConfig.defaultLightTheme}`defaultLightTheme` and {name RenderConfig.defaultDarkTheme}`defaultDarkTheme` are accessible.
+  It is an error if either fails the accessibility check.
+
+: {name Config.warnPerThemeAccessibility}`warnPerThemeAccessibility`
+
+  Emits a build-log warning for every registered theme that has accessibility issues, naming the theme and the specific colors involved.
+  Defaults to {lean}`true`; set it to {lean}`false` to silence the per-theme advisories.
+
+### Downgrading Documented Trade-Offs
+%%%
+tag := "manual-themes-accessibility-downgrade"
+%%%
+
+Not all themes included with Verso are accessible to all readers.
+This is intentional on the part of their designers.
+For example, the _Solarized_ themes are intentionally low-contrast, and _Beacon Light_ prioritizes the Okabe-Ito palette's distinguishability for many varieties of color perception over contrast.
+
+By default, Verso warns about these themes if they're included in {name RenderConfig.availableThemes}`availableThemes`.
+To silence this warning, set {name Config.warnPerThemeAccessibility}`warnPerThemeAccessibility` to {name}`false`.
+By default, it is an error if a non-accessible theme is set as the default theme.
+Set {name Config.strictDefaultThemeAccessibility}`strictDefaultThemeAccessibility` to {name}`false` to disable this error.
+
+
+## PDF Output
+%%%
+tag := "manual-themes-pdf"
+%%%
+
+
+PDF output via TeX uses only a {ref "output-code-themes"}[code theme].
+The {name RenderConfig.pdfCodeTheme}`pdfCodeTheme` configuration field selects the code theme to be used to generate PDFs, defaulting to {name Theme.CodeTheme.ink}`ink`.
+This setting ignores the theme used for HTML output.
+The preamble in the resulting TeX uses `xcolor`'s `\definecolor` to define a named LaTeX color for each themeable color.
+Code is generated using _semantic_ macros such as `\versoVar` and `\versoConst`, so a `\renewcommand` is also generated to configure each category.
diff --git a/doc/UsersGuide/Output.lean b/doc/UsersGuide/Output.lean
index ba2ad0805..a301c954c 100644
--- a/doc/UsersGuide/Output.lean
+++ b/doc/UsersGuide/Output.lean
@@ -5,11 +5,14 @@ Author: David Thrane Christiansen
 -/
 import Lean.DocString.Syntax
 import VersoManual
+import VersoManual.InlineLean
 import VersoBlog
 
+
 open Verso Genre Manual
 
 open Verso.Genre.Blog (Page Post)
+open Verso.Genre.Manual.InlineLean
 
 open InlineLean
 open Verso.Doc
@@ -123,3 +126,185 @@ def mkList (xs : List TeX) : TeX :=
 
 \end{itemize}
 ```
+
+# Themes for Code
+%%%
+tag := "output-code-themes"
+%%%
+
+A {deftech}_code theme_ is a genre-neutral description of how rendered code should look, including colors, token styling, and font choices.
+Any Verso genre can use code themes.
+The built-in {name}`Manual` genre extends code themes with further fonts and colors.
+Please refer to its {ref "manual-themes"}[theming] documentation for more information.
+
+A code theme is a value of type {name Theme.CodeTheme}`CodeTheme` with the `@[code_theme]` attribute.
+
+## Colors and Palettes
+%%%
+tag := "code-themes-colors"
+%%%
+
+```lean -show
+open Verso.Theme
+```
+
+
+
+### The `Color` Type and `color%` Literal
+%%%
+tag := "code-themes-color-type"
+%%%
+
+Colors are represented by the {name}`Color` type.
+
+{docstring Verso.Theme.Color}
+
+{docstring Verso.Theme.Color.rgb}
+
+A number of built-in color constants are provided:
+
+{docstring Verso.Theme.Color.white}
+
+{docstring Verso.Theme.Color.black}
+
+{docstring Verso.Theme.Color.gray}
+
+{docstring Verso.Theme.Color.red}
+
+{docstring Verso.Theme.Color.green}
+
+{docstring Verso.Theme.Color.blue}
+
+{docstring Verso.Theme.Color.transparent}
+
+### Named Reference Palettes
+%%%
+tag := "code-theme-palettes"
+%%%
+
+To support bundled themes, Verso ships with a number of popular color palettes.
+Each palette has an associated namespace that contains the named colors from the palette along with a `name : String` and a `sourceLink` of type {name}`SourceLink`, which is a source that can be linked to in theme-selection UIs.
+
+{docstring Theme.SourceLink}
+
+: Okabe-Ito
+
+  Masataka Okabe and Kei Ito's eight-hue colorblind-safe palette, published in 2002 as part of their guidance on [accessible color use in scientific visualization](https://jfly.uni-koeln.de/color/).
+  The hues stay distinguishable under protanopia, deuteranopia, and tritanopia, which makes them a standard reference set for code highlighting that must remain readable to dichromat readers.
+  The namespace `Verso.Theme.Color.Palettes.OkabeIto` provides {name Verso.Theme.Color.Palettes.OkabeIto.black}`black`, {name Verso.Theme.Color.Palettes.OkabeIto.orange}`orange`, {name Verso.Theme.Color.Palettes.OkabeIto.skyBlue}`skyBlue`, {name Verso.Theme.Color.Palettes.OkabeIto.bluishGreen}`bluishGreen`, {name Verso.Theme.Color.Palettes.OkabeIto.yellow}`yellow`, {name Verso.Theme.Color.Palettes.OkabeIto.blue}`blue`, {name Verso.Theme.Color.Palettes.OkabeIto.vermillion}`vermillion`, and {name Verso.Theme.Color.Palettes.OkabeIto.reddishPurple}`reddishPurple`.
+
+: Solarized
+
+  Ethan Schoonover's standard cream-on-paper palette of sixteen colors: eight [monotones](https://ethanschoonover.com/solarized/) plus eight accent hues.
+  Schoonover's rebasing rule splits the monotones by substrate: `base0` and `base1` are dark-mode foreground tones (body text and emphasized content, respectively), `base00` and `base01` are the light-mode counterparts, and the four remaining shades (`base02`, `base03`, `base2`, `base3`) are background and highlight tones for each substrate.
+  The namespace `Verso.Theme.Color.Palettes.Solarized` provides {name Verso.Theme.Color.Palettes.Solarized.base03}`base03` through {name Verso.Theme.Color.Palettes.Solarized.base3}`base3` for the monotones and {name Verso.Theme.Color.Palettes.Solarized.yellow}`yellow`, {name Verso.Theme.Color.Palettes.Solarized.orange}`orange`, {name Verso.Theme.Color.Palettes.Solarized.red}`red`, {name Verso.Theme.Color.Palettes.Solarized.magenta}`magenta`, {name Verso.Theme.Color.Palettes.Solarized.violet}`violet`, {name Verso.Theme.Color.Palettes.Solarized.blue}`blue`, {name Verso.Theme.Color.Palettes.Solarized.cyan}`cyan`, and {name Verso.Theme.Color.Palettes.Solarized.green}`green` for the accent hues.
+
+: Dracula and Alucard
+
+  The canonical dark Dracula palette and its light-substrate counterpart Alucard, from the [official Dracula spec](https://draculatheme.com/spec).
+  Each palette shares twelve color slots — background, current line, selection, foreground, comment, red, orange, yellow, green, cyan, purple, pink — with documented semantic intent that ports the palette into syntax highlighting (pink for keywords, cyan for classes and types, orange for numbers and booleans, yellow for strings, green for functions, purple for instance reserved words, red for errors).
+  The namespaces `Verso.Theme.Color.Palettes.DraculaClassic` and `Verso.Theme.Color.Palettes.AlucardClassic` each provide the twelve named colors.
+
+: Nord
+
+  Sven Greb's arctic, north-bluish palette of sixteen colors organized in [four groups](https://www.nordtheme.com/docs/colors-and-palettes): *Polar Night* ({name Verso.Theme.Color.Palettes.Nord.nord0}`nord0` through {name Verso.Theme.Color.Palettes.Nord.nord3}`nord3`) for dark-substrate backgrounds and code surfaces, *Snow Storm* ({name Verso.Theme.Color.Palettes.Nord.nord4}`nord4` through {name Verso.Theme.Color.Palettes.Nord.nord6}`nord6`) for body text on dark backgrounds and substrates on light variants, *Frost* ({name Verso.Theme.Color.Palettes.Nord.nord7}`nord7` through {name Verso.Theme.Color.Palettes.Nord.nord10}`nord10`) for the canonical syntax accents, and *Aurora* ({name Verso.Theme.Color.Palettes.Nord.nord11}`nord11` through {name Verso.Theme.Color.Palettes.Nord.nord15}`nord15`) for warm accent hues used by diagnostics and additional syntax categories.
+  The namespace `Verso.Theme.Color.Palettes.Nord` provides each numbered constant.
+
+## Fonts and Typefaces
+%%%
+tag := "code-themes-fonts"
+%%%
+
+The {name}`Typeface` type represents a general typeface.
+There are three built-in faces, {name}`Typeface.sans`, {name}`Typeface.serif`, and {name}`Typeface.mono`, which stand for unspecified sans-serif, serif, and monospaced font faces.
+Specific font faces may be provided using the {name}`Typeface.files` constructor, which bundles font files with sufficient metadata to use them in a theme.
+
+{docstring Typeface}
+
+
+### `define_font_face`
+%%%
+tag := "code-themes-fonts-def"
+%%%
+
+To make it easier to include custom fonts, Verso provides the `define_font_face` command, which declares a {name}`FontFace` value by name and embeds the font file into the resulting `.olean` at compile time.
+This allows themes that include fonts to be distributed as ordinary Lean libraries.
+
+{docstring Verso.defineFontFace}
+
+These {name}`FontFace` declarations are then composed into a {name}`Typeface` via the {name}`Typeface.files` constructor.
+
+## The `CodeTheme` Structure
+%%%
+tag := "code-themes-structure"
+%%%
+
+{docstring Theme.CodeTheme}
+
+Remember to register code themes using the `@[code_theme]` attribute.
+
+## Accessibility Checking
+%%%
+tag := "code-themes-accessibility"
+%%%
+
+Code themes are checked for accessibility.
+These checks are by nature incomplete: they can discover the _presence_ of problems, but not their absence.
+Nonetheless, ensuring that the default theme used by a document passes these tests is a good first step towards accessbility.
+
+{docstring Theme.CodeTheme.checkAccessibility}
+
+The check compares the color fields of a {name Theme.CodeTheme}`CodeTheme` and returns an array of {name Theme.Color.Issue}`Issue` values, one per problem found.
+
+Themes may contain arbitrary CSS.
+In this case, some other means of checking accessibility should be used.
+
+### Contrast
+%%%
+tag := "code-themes-accessibility-contrast"
+%%%
+The contrast checker uses two thresholds: WCAG AA's 4.5:1 ratio for primary text and 3:1 for UI accents and large-text positions.
+
+The following contrasts are checked at the text threshold (4.5:1):
+
+ * Body, error-message, warning-message, and info-message text against the page background.
+ * Each themed token color against the code-block background.
+ * The code color against the inline-code background, when one is set.
+ * The code color against both highlight backgrounds, and body text against the prose-highlight background.
+ * Hover-popup text against the hover-popup background and against the tactic-state background.
+ * Code against the tactic-state background.
+
+The following contrasts are checked at the large text threshold (3:1):
+
+ * Each diagnostic accent (error, warning, info indicator) against the page background.
+ * The neutral UI-element color against the code-block background.
+ * The tactic-state border against the tactic-state background.
+
+Images that contain text are not automatically checked, and must be checked for accessiblity in some other way.
+
+### Color Perception
+%%%
+tag := "code-themes-accessibility-perception"
+%%%
+
+The eleven token colors are checked for perceptual distinctness in four separate modes:
+ * unmodified
+ * simulated protanopia
+ * simulated deuteranopia
+ * simulated tritanopia.
+
+Every pair must remain perceptibly distinct (CIEDE2000 ΔE above a tunable threshold).
+A pair of _identical_ colors is not an issue, because such themes have explicitly decided not to distinguish that pair using color.
+
+A translucent foreground is composited over its background (via {name Theme.Color.over}`Color.over`) before checking.
+A translucent _background_, by contrast, is itself reported as a contrast issue, because the effective backdrop is unknown.
+
+
+### The `Issue` Type
+%%%
+tag := "code-themes-accessibility-issues"
+%%%
+
+Issues are reported using the type {name Theme.Color.Issue}`Issue`, which describes the accessibility issue.
+
+{docstring Theme.Color.Issue}
diff --git a/src/verso-manual/VersoManual.lean b/src/verso-manual/VersoManual.lean
index be6a7b028..50b6f39a4 100644
--- a/src/verso-manual/VersoManual.lean
+++ b/src/verso-manual/VersoManual.lean
@@ -311,6 +311,10 @@ structure RenderConfig extends Config where
   dropdown).
   -/
   defaultSingleAppearance : Appearance := .light
+  /--
+  The {name}`CodeTheme` used for PDF output.
+  -/
+  pdfCodeTheme : Verso.Theme.CodeTheme := Verso.Theme.CodeTheme.ink
 
 namespace Config
 
@@ -511,7 +515,6 @@ def writeThemeAssets (dir : System.FilePath) (config : RenderConfig) : EmitM Uni
 
 open IO.FS in
 def emitTeX (config : RenderConfig) (text : Part Manual) : EmitM Unit := do
-  let registry ← readThe ThemeRegistry
   let (text, state) ← traverse text config.toConfig
   let opts : TeX.Options Manual := {
     headerLevels := #["chapter", "section", "subsection", "subsubsection", "paragraph"],
@@ -534,7 +537,7 @@ def emitTeX (config : RenderConfig) (text : Part Manual) : EmitM Unit := do
   withFile (dir.join "main.tex") .write fun h => do
     if config.verbose then
       IO.println s!"Saving {dir.join "main.tex"}"
-    h.putStrLn (preamble text.titleString authors date packages.toList preambleItems.toList (singleDefaultTheme registry config).toCodeTheme)
+    h.putStrLn (preamble text.titleString authors date packages.toList preambleItems.toList config.pdfCodeTheme)
     -- \frontmatter is inserted by our hardcoded preamble before the ToC, so it doesn't get inserted
     -- here. If there's any text at the start of the front matter, then we need to clear it to a new
     -- recto page after the ToC
diff --git a/src/verso/Verso/Theme/Color/Types.lean b/src/verso/Verso/Theme/Color/Types.lean
index 3f4419f03..f3efc0acb 100644
--- a/src/verso/Verso/Theme/Color/Types.lean
+++ b/src/verso/Verso/Theme/Color/Types.lean
@@ -15,8 +15,9 @@ namespace Verso.Theme
 -- `DecidableEq`, so colors round-trip through hex exactly and themes, fonts, and assets deduplicate
 -- by value.
 /--
-A color in sRGB with an alpha channel, each channel a byte.
+A color.
 -/
 public inductive Color where
+  /-- A color in sRGB with an alpha channel, each channel a byte. -/
   | rgba (red green blue alpha : UInt8)
 deriving DecidableEq, Repr, Inhabited

From 7d94a250fa3abb704ea54fd28e55686e076b41e0 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Wed, 3 Jun 2026 06:40:22 +0200
Subject: [PATCH 20/31] simplify test

---
 src/tests/Tests/ColorMath.lean | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/src/tests/Tests/ColorMath.lean b/src/tests/Tests/ColorMath.lean
index f3bd1ec78..1170228ef 100644
--- a/src/tests/Tests/ColorMath.lean
+++ b/src/tests/Tests/ColorMath.lean
@@ -120,15 +120,17 @@ def testDichromacyAlphaPreserved := testProp <| ∀ (cvd : CVD) (c : Color),
 def testLuminanceIgnoresAlpha := testProp <| ∀ (r g b a : UInt8),
   relativeLuminance (.rgba r g b a) == relativeLuminance (.rgba r g b 255)
 
+/-- Replaces a color's alpha channel with full opacity. -/
+private def «opaque» : Color → Color
+  | .rgba r g b _ => .rgba r g b 255
+
 /-- Contrast ratio ignores the alpha channel. -/
-def testContrastIgnoresAlpha := testProp <| ∀ (r1 g1 b1 a1 r2 g2 b2 a2 : UInt8),
-  contrastRatio (.rgba r1 g1 b1 a1) (.rgba r2 g2 b2 a2)
-    == contrastRatio (.rgba r1 g1 b1 255) (.rgba r2 g2 b2 255)
+def testContrastIgnoresAlpha := testProp <| ∀ (c1 c2 : Color),
+  contrastRatio c1 c2 == contrastRatio («opaque» c1) («opaque» c2)
 
 /-- ΔE ignores the alpha channel. -/
-def testDeltaEIgnoresAlpha := testProp <| ∀ (r1 g1 b1 a1 r2 g2 b2 a2 : UInt8),
-  deltaE (.rgba r1 g1 b1 a1) (.rgba r2 g2 b2 a2)
-    == deltaE (.rgba r1 g1 b1 255) (.rgba r2 g2 b2 255)
+def testDeltaEIgnoresAlpha := testProp <| ∀ (c1 c2 : Color),
+  deltaE c1 c2 == deltaE («opaque» c1) («opaque» c2)
 
 open Lean (Name)
 

From 04c8406119a1dc82cd07d2a3f6a05d878fafd388 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Wed, 3 Jun 2026 09:30:55 +0200
Subject: [PATCH 21/31] expected

---
 src/tests/golden/theme-css/default.expected   | 93 ++++++++++++++++++-
 .../code-content-doc/expected/tex/main.tex    | 28 +++++-
 .../diagram-doc/expected/tex/main.tex         | 24 ++++-
 .../extra-files-doc/expected/tex/main.tex     | 24 ++++-
 .../front-matter-doc/expected/tex/main.tex    | 24 ++++-
 .../inheritance-doc/expected/tex/main.tex     | 26 +++++-
 .../sample-doc/expected/tex/main.tex          | 26 +++++-
 7 files changed, 234 insertions(+), 11 deletions(-)

diff --git a/src/tests/golden/theme-css/default.expected b/src/tests/golden/theme-css/default.expected
index 5a79290b1..5c3efe4c3 100644
--- a/src/tests/golden/theme-css/default.expected
+++ b/src/tests/golden/theme-css/default.expected
@@ -24,6 +24,38 @@
   --verso-code-var-weight: 400;
   --verso-code-var-style: italic;
   --verso-code-var-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --verso-code-literal-color: #000000;
+  --verso-code-literal-weight: 400;
+  --verso-code-literal-style: normal;
+  --verso-code-literal-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --verso-code-literal-string-color: #000000;
+  --verso-code-literal-string-weight: 400;
+  --verso-code-literal-string-style: normal;
+  --verso-code-literal-string-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --verso-code-doc-comment-color: #000000;
+  --verso-code-doc-comment-weight: 400;
+  --verso-code-doc-comment-style: italic;
+  --verso-code-doc-comment-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --verso-code-sort-color: #000000;
+  --verso-code-sort-weight: 400;
+  --verso-code-sort-style: normal;
+  --verso-code-sort-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --verso-code-level-var-color: #000000;
+  --verso-code-level-var-weight: 400;
+  --verso-code-level-var-style: italic;
+  --verso-code-level-var-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --verso-code-level-const-color: #000000;
+  --verso-code-level-const-weight: 400;
+  --verso-code-level-const-style: normal;
+  --verso-code-level-const-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --verso-code-level-op-color: #000000;
+  --verso-code-level-op-weight: 400;
+  --verso-code-level-op-style: normal;
+  --verso-code-level-op-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --verso-code-module-name-color: #000000;
+  --verso-code-module-name-weight: 400;
+  --verso-code-module-name-style: normal;
+  --verso-code-module-name-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
   --verso-hover-background-color: #e5e5e5;
   --verso-hover-border-color: #000000;
   --verso-hover-text-color: #000000;
@@ -68,13 +100,72 @@
   position: relative;
 }
 
-.hl.lean .literal, .hl.lean .unknown {
+.hl.lean .unknown {
   color: var(--verso-code-color,);
   font-weight: normal;
   font-style: normal;
   font-family: var(--verso-code-font-family,);
 }
 
+.hl.lean .literal {
+  color: var(--verso-code-literal-color, var(--verso-code-color,));
+  font-weight: var(--verso-code-literal-weight, normal);
+  font-style: var(--verso-code-literal-style, normal);
+  font-family: var(--verso-code-literal-font-family, var(--verso-code-font-family,));
+}
+
+/* `.literal.string` is more specific than `.literal`, so its rule wins when both classes
+   apply (string literals). Other future `.literal.*` kinds will fall back to the `.literal`
+   rule above until they get their own variables. */
+.hl.lean .literal.string {
+  color: var(--verso-code-literal-string-color, var(--verso-code-literal-color, var(--verso-code-color,)));
+  font-weight: var(--verso-code-literal-string-weight, normal);
+  font-style: var(--verso-code-literal-string-style, normal);
+  font-family: var(--verso-code-literal-string-font-family, var(--verso-code-font-family,));
+}
+
+.hl.lean .doc-comment {
+  color: var(--verso-code-doc-comment-color, var(--verso-code-color,));
+  font-weight: var(--verso-code-doc-comment-weight, normal);
+  font-style: var(--verso-code-doc-comment-style, italic);
+  font-family: var(--verso-code-doc-comment-font-family, var(--verso-code-font-family,));
+}
+
+.hl.lean .sort {
+  color: var(--verso-code-sort-color, var(--verso-code-color,));
+  font-weight: var(--verso-code-sort-weight, normal);
+  font-style: var(--verso-code-sort-style, normal);
+  font-family: var(--verso-code-sort-font-family, var(--verso-code-font-family,));
+}
+
+.hl.lean .level-var {
+  color: var(--verso-code-level-var-color, var(--verso-code-color,));
+  font-weight: var(--verso-code-level-var-weight, normal);
+  font-style: var(--verso-code-level-var-style, italic);
+  font-family: var(--verso-code-level-var-font-family, var(--verso-code-font-family,));
+}
+
+.hl.lean .level-const {
+  color: var(--verso-code-level-const-color, var(--verso-code-color,));
+  font-weight: var(--verso-code-level-const-weight, normal);
+  font-style: var(--verso-code-level-const-style, normal);
+  font-family: var(--verso-code-level-const-font-family, var(--verso-code-font-family,));
+}
+
+.hl.lean .level-op {
+  color: var(--verso-code-level-op-color, var(--verso-code-color,));
+  font-weight: var(--verso-code-level-op-weight, normal);
+  font-style: var(--verso-code-level-op-style, normal);
+  font-family: var(--verso-code-level-op-font-family, var(--verso-code-font-family,));
+}
+
+.hl.lean .module-name {
+  color: var(--verso-code-module-name-color, var(--verso-code-color,));
+  font-weight: var(--verso-code-module-name-weight, normal);
+  font-style: var(--verso-code-module-name-style, normal);
+  font-family: var(--verso-code-module-name-font-family, var(--verso-code-font-family,));
+}
+
 .hover-container {
   width: 0;
   height: 0;
diff --git a/src/tests/integration/code-content-doc/expected/tex/main.tex b/src/tests/integration/code-content-doc/expected/tex/main.tex
index ff617593e..56ecd869f 100644
--- a/src/tests/integration/code-content-doc/expected/tex/main.tex
+++ b/src/tests/integration/code-content-doc/expected/tex/main.tex
@@ -127,10 +127,25 @@
 \providecommand{\versoConst}[1]{#1}
 \providecommand{\versoVar}[1]{\textit{#1}}
 \providecommand{\versoLiteral}[1]{#1}
+\providecommand{\versoLiteralString}[1]{#1}
+\providecommand{\versoDocComment}[1]{\textit{#1}}
+\providecommand{\versoSort}[1]{#1}
+\providecommand{\versoLevelVar}[1]{\textit{#1}}
+\providecommand{\versoLevelConst}[1]{#1}
+\providecommand{\versoLevelOp}[1]{#1}
+\providecommand{\versoModuleName}[1]{#1}
 \definecolor{versoCodeColor}{HTML}{000000}
 \definecolor{versoConstColor}{HTML}{000000}
 \definecolor{versoKeywordColor}{HTML}{000000}
 \definecolor{versoVarColor}{HTML}{000000}
+\definecolor{versoLiteralColor}{HTML}{000000}
+\definecolor{versoLiteralStringColor}{HTML}{000000}
+\definecolor{versoDocCommentColor}{HTML}{000000}
+\definecolor{versoSortColor}{HTML}{000000}
+\definecolor{versoLevelVarColor}{HTML}{000000}
+\definecolor{versoLevelConstColor}{HTML}{000000}
+\definecolor{versoLevelOpColor}{HTML}{000000}
+\definecolor{versoModuleNameColor}{HTML}{000000}
 \definecolor{errorColor}{HTML}{CC0000}
 \definecolor{warningColor}{HTML}{000000}
 \definecolor{infoColor}{HTML}{000000}
@@ -140,7 +155,14 @@
 \renewcommand{\versoKeyword}[1]{\textcolor{versoKeywordColor}{\fontseries{eb}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoConst}[1]{\textcolor{versoConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoVar}[1]{\textcolor{versoVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
-\renewcommand{\versoLiteral}[1]{\textcolor{versoCodeColor}{#1}}
+\renewcommand{\versoLiteral}[1]{\textcolor{versoLiteralColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLiteralString}[1]{\textcolor{versoLiteralStringColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoDocComment}[1]{\textcolor{versoDocCommentColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoSort}[1]{\textcolor{versoSortColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLevelVar}[1]{\textcolor{versoLevelVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoLevelConst}[1]{\textcolor{versoLevelConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLevelOp}[1]{\textcolor{versoLevelOpColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoModuleName}[1]{\textcolor{versoModuleNameColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \setmonofont{DejaVu Sans Mono}
 
 \title{\sffamily Title of the Doc}
@@ -167,7 +189,7 @@
 
 Here is some with a variety of interesting Unicode, including characters where UTF-16 is funky:
 \begin{LeanVerbatim}
-\versoKeyword{def} \versoConst{Set} \versoLiteral{(}\versoVar{α} \versoLiteral{:} \versoLiteral{Type} \versoLiteral{u}\versoLiteral{)} \versoLiteral{:} \versoLiteral{Type} \versoLiteral{u} \versoLiteral{:=} \versoVar{α} \versoLiteral{→} \versoLiteral{Prop}
+\versoKeyword{def} \versoConst{Set} \versoLiteral{(}\versoVar{α} \versoLiteral{:} \versoSort{Type} \versoLevelVar{u}\versoLiteral{)} \versoLiteral{:} \versoSort{Type} \versoLevelVar{u} \versoLiteral{:=} \versoVar{α} \versoLiteral{→} \versoSort{Prop}
 
 \versoKeyword{instance} \versoLiteral{:} \versoConst{EmptyCollection} \versoLiteral{(}\versoConst{Set} \versoVar{α}\versoLiteral{)} \versoKeyword{where}
   \versoConst{emptyCollection} \versoLiteral{:=} \versoKeyword{fun} \versoLiteral{_} \versoLiteral{=>} \versoConst{False}
@@ -205,7 +227,7 @@
 \versoKeyword{def} \versoConst{Set.powerset} \versoLiteral{(}\versoVar{a} \versoLiteral{:} \versoConst{Set} \versoVar{α}\versoLiteral{)} \versoLiteral{:} \versoConst{Set} \versoLiteral{(}\versoConst{Set} \versoVar{α}\versoLiteral{)} \versoLiteral{:=}
   \versoKeyword{fun} \versoLiteral{(}\versoVar{x} \versoLiteral{:} \versoConst{Set} \versoVar{α}\versoLiteral{)} \versoLiteral{=>} \versoVar{x} \versoLiteral{⊆} \versoVar{a}
 
-\versoKeyword{notation} \versoLiteral{"𝒫 "} \versoVar{x} \versoLiteral{=>} \versoConst{Set.powerset} \versoVar{x}
+\versoKeyword{notation} \versoLiteralString{"𝒫 "} \versoVar{x} \versoLiteral{=>} \versoConst{Set.powerset} \versoVar{x}
 
 \versoKeyword{theorem} \versoConst{Set.powerset_empty_nonempty} \versoLiteral{:}
     \versoLiteral{∃} \versoLiteral{(}\versoVar{a} \versoLiteral{:} \versoConst{Set} \versoVar{α}\versoLiteral{)}\versoLiteral{,} \versoVar{a} \versoLiteral{∈} \versoLiteral{𝒫} \versoLiteral{\symbol{123}}\versoLiteral{\symbol{125}} \versoLiteral{:=} \versoKeyword{by}
diff --git a/src/tests/integration/diagram-doc/expected/tex/main.tex b/src/tests/integration/diagram-doc/expected/tex/main.tex
index 9926868b4..3ae276c4a 100644
--- a/src/tests/integration/diagram-doc/expected/tex/main.tex
+++ b/src/tests/integration/diagram-doc/expected/tex/main.tex
@@ -127,10 +127,25 @@
 \providecommand{\versoConst}[1]{#1}
 \providecommand{\versoVar}[1]{\textit{#1}}
 \providecommand{\versoLiteral}[1]{#1}
+\providecommand{\versoLiteralString}[1]{#1}
+\providecommand{\versoDocComment}[1]{\textit{#1}}
+\providecommand{\versoSort}[1]{#1}
+\providecommand{\versoLevelVar}[1]{\textit{#1}}
+\providecommand{\versoLevelConst}[1]{#1}
+\providecommand{\versoLevelOp}[1]{#1}
+\providecommand{\versoModuleName}[1]{#1}
 \definecolor{versoCodeColor}{HTML}{000000}
 \definecolor{versoConstColor}{HTML}{000000}
 \definecolor{versoKeywordColor}{HTML}{000000}
 \definecolor{versoVarColor}{HTML}{000000}
+\definecolor{versoLiteralColor}{HTML}{000000}
+\definecolor{versoLiteralStringColor}{HTML}{000000}
+\definecolor{versoDocCommentColor}{HTML}{000000}
+\definecolor{versoSortColor}{HTML}{000000}
+\definecolor{versoLevelVarColor}{HTML}{000000}
+\definecolor{versoLevelConstColor}{HTML}{000000}
+\definecolor{versoLevelOpColor}{HTML}{000000}
+\definecolor{versoModuleNameColor}{HTML}{000000}
 \definecolor{errorColor}{HTML}{CC0000}
 \definecolor{warningColor}{HTML}{000000}
 \definecolor{infoColor}{HTML}{000000}
@@ -140,7 +155,14 @@
 \renewcommand{\versoKeyword}[1]{\textcolor{versoKeywordColor}{\fontseries{eb}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoConst}[1]{\textcolor{versoConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoVar}[1]{\textcolor{versoVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
-\renewcommand{\versoLiteral}[1]{\textcolor{versoCodeColor}{#1}}
+\renewcommand{\versoLiteral}[1]{\textcolor{versoLiteralColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLiteralString}[1]{\textcolor{versoLiteralStringColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoDocComment}[1]{\textcolor{versoDocCommentColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoSort}[1]{\textcolor{versoSortColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLevelVar}[1]{\textcolor{versoLevelVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoLevelConst}[1]{\textcolor{versoLevelConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLevelOp}[1]{\textcolor{versoLevelOpColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoModuleName}[1]{\textcolor{versoModuleNameColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \setmonofont{DejaVu Sans Mono}
 
 \title{\sffamily Diagrams in the Manual genre}
diff --git a/src/tests/integration/extra-files-doc/expected/tex/main.tex b/src/tests/integration/extra-files-doc/expected/tex/main.tex
index 3a1f744b4..07422dc90 100644
--- a/src/tests/integration/extra-files-doc/expected/tex/main.tex
+++ b/src/tests/integration/extra-files-doc/expected/tex/main.tex
@@ -127,10 +127,25 @@
 \providecommand{\versoConst}[1]{#1}
 \providecommand{\versoVar}[1]{\textit{#1}}
 \providecommand{\versoLiteral}[1]{#1}
+\providecommand{\versoLiteralString}[1]{#1}
+\providecommand{\versoDocComment}[1]{\textit{#1}}
+\providecommand{\versoSort}[1]{#1}
+\providecommand{\versoLevelVar}[1]{\textit{#1}}
+\providecommand{\versoLevelConst}[1]{#1}
+\providecommand{\versoLevelOp}[1]{#1}
+\providecommand{\versoModuleName}[1]{#1}
 \definecolor{versoCodeColor}{HTML}{000000}
 \definecolor{versoConstColor}{HTML}{000000}
 \definecolor{versoKeywordColor}{HTML}{000000}
 \definecolor{versoVarColor}{HTML}{000000}
+\definecolor{versoLiteralColor}{HTML}{000000}
+\definecolor{versoLiteralStringColor}{HTML}{000000}
+\definecolor{versoDocCommentColor}{HTML}{000000}
+\definecolor{versoSortColor}{HTML}{000000}
+\definecolor{versoLevelVarColor}{HTML}{000000}
+\definecolor{versoLevelConstColor}{HTML}{000000}
+\definecolor{versoLevelOpColor}{HTML}{000000}
+\definecolor{versoModuleNameColor}{HTML}{000000}
 \definecolor{errorColor}{HTML}{CC0000}
 \definecolor{warningColor}{HTML}{000000}
 \definecolor{infoColor}{HTML}{000000}
@@ -140,7 +155,14 @@
 \renewcommand{\versoKeyword}[1]{\textcolor{versoKeywordColor}{\fontseries{eb}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoConst}[1]{\textcolor{versoConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoVar}[1]{\textcolor{versoVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
-\renewcommand{\versoLiteral}[1]{\textcolor{versoCodeColor}{#1}}
+\renewcommand{\versoLiteral}[1]{\textcolor{versoLiteralColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLiteralString}[1]{\textcolor{versoLiteralStringColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoDocComment}[1]{\textcolor{versoDocCommentColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoSort}[1]{\textcolor{versoSortColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLevelVar}[1]{\textcolor{versoLevelVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoLevelConst}[1]{\textcolor{versoLevelConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLevelOp}[1]{\textcolor{versoLevelOpColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoModuleName}[1]{\textcolor{versoModuleNameColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \setmonofont{DejaVu Sans Mono}
 
 \title{\sffamily Extra Files Test Document}
diff --git a/src/tests/integration/front-matter-doc/expected/tex/main.tex b/src/tests/integration/front-matter-doc/expected/tex/main.tex
index 813348b4f..92a610412 100644
--- a/src/tests/integration/front-matter-doc/expected/tex/main.tex
+++ b/src/tests/integration/front-matter-doc/expected/tex/main.tex
@@ -127,10 +127,25 @@
 \providecommand{\versoConst}[1]{#1}
 \providecommand{\versoVar}[1]{\textit{#1}}
 \providecommand{\versoLiteral}[1]{#1}
+\providecommand{\versoLiteralString}[1]{#1}
+\providecommand{\versoDocComment}[1]{\textit{#1}}
+\providecommand{\versoSort}[1]{#1}
+\providecommand{\versoLevelVar}[1]{\textit{#1}}
+\providecommand{\versoLevelConst}[1]{#1}
+\providecommand{\versoLevelOp}[1]{#1}
+\providecommand{\versoModuleName}[1]{#1}
 \definecolor{versoCodeColor}{HTML}{000000}
 \definecolor{versoConstColor}{HTML}{000000}
 \definecolor{versoKeywordColor}{HTML}{000000}
 \definecolor{versoVarColor}{HTML}{000000}
+\definecolor{versoLiteralColor}{HTML}{000000}
+\definecolor{versoLiteralStringColor}{HTML}{000000}
+\definecolor{versoDocCommentColor}{HTML}{000000}
+\definecolor{versoSortColor}{HTML}{000000}
+\definecolor{versoLevelVarColor}{HTML}{000000}
+\definecolor{versoLevelConstColor}{HTML}{000000}
+\definecolor{versoLevelOpColor}{HTML}{000000}
+\definecolor{versoModuleNameColor}{HTML}{000000}
 \definecolor{errorColor}{HTML}{CC0000}
 \definecolor{warningColor}{HTML}{000000}
 \definecolor{infoColor}{HTML}{000000}
@@ -140,7 +155,14 @@
 \renewcommand{\versoKeyword}[1]{\textcolor{versoKeywordColor}{\fontseries{eb}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoConst}[1]{\textcolor{versoConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoVar}[1]{\textcolor{versoVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
-\renewcommand{\versoLiteral}[1]{\textcolor{versoCodeColor}{#1}}
+\renewcommand{\versoLiteral}[1]{\textcolor{versoLiteralColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLiteralString}[1]{\textcolor{versoLiteralStringColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoDocComment}[1]{\textcolor{versoDocCommentColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoSort}[1]{\textcolor{versoSortColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLevelVar}[1]{\textcolor{versoLevelVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoLevelConst}[1]{\textcolor{versoLevelConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLevelOp}[1]{\textcolor{versoLevelOpColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoModuleName}[1]{\textcolor{versoModuleNameColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \setmonofont{DejaVu Sans Mono}
 
 \title{\sffamily Front Matter Test Document}
diff --git a/src/tests/integration/inheritance-doc/expected/tex/main.tex b/src/tests/integration/inheritance-doc/expected/tex/main.tex
index 256fd484c..9f3f610fd 100644
--- a/src/tests/integration/inheritance-doc/expected/tex/main.tex
+++ b/src/tests/integration/inheritance-doc/expected/tex/main.tex
@@ -127,10 +127,25 @@
 \providecommand{\versoConst}[1]{#1}
 \providecommand{\versoVar}[1]{\textit{#1}}
 \providecommand{\versoLiteral}[1]{#1}
+\providecommand{\versoLiteralString}[1]{#1}
+\providecommand{\versoDocComment}[1]{\textit{#1}}
+\providecommand{\versoSort}[1]{#1}
+\providecommand{\versoLevelVar}[1]{\textit{#1}}
+\providecommand{\versoLevelConst}[1]{#1}
+\providecommand{\versoLevelOp}[1]{#1}
+\providecommand{\versoModuleName}[1]{#1}
 \definecolor{versoCodeColor}{HTML}{000000}
 \definecolor{versoConstColor}{HTML}{000000}
 \definecolor{versoKeywordColor}{HTML}{000000}
 \definecolor{versoVarColor}{HTML}{000000}
+\definecolor{versoLiteralColor}{HTML}{000000}
+\definecolor{versoLiteralStringColor}{HTML}{000000}
+\definecolor{versoDocCommentColor}{HTML}{000000}
+\definecolor{versoSortColor}{HTML}{000000}
+\definecolor{versoLevelVarColor}{HTML}{000000}
+\definecolor{versoLevelConstColor}{HTML}{000000}
+\definecolor{versoLevelOpColor}{HTML}{000000}
+\definecolor{versoModuleNameColor}{HTML}{000000}
 \definecolor{errorColor}{HTML}{CC0000}
 \definecolor{warningColor}{HTML}{000000}
 \definecolor{infoColor}{HTML}{000000}
@@ -140,7 +155,14 @@
 \renewcommand{\versoKeyword}[1]{\textcolor{versoKeywordColor}{\fontseries{eb}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoConst}[1]{\textcolor{versoConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoVar}[1]{\textcolor{versoVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
-\renewcommand{\versoLiteral}[1]{\textcolor{versoCodeColor}{#1}}
+\renewcommand{\versoLiteral}[1]{\textcolor{versoLiteralColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLiteralString}[1]{\textcolor{versoLiteralStringColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoDocComment}[1]{\textcolor{versoDocCommentColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoSort}[1]{\textcolor{versoSortColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLevelVar}[1]{\textcolor{versoLevelVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoLevelConst}[1]{\textcolor{versoLevelConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLevelOp}[1]{\textcolor{versoLevelOpColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoModuleName}[1]{\textcolor{versoModuleNameColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \setmonofont{DejaVu Sans Mono}
 
 \title{\sffamily Title of the Doc}
@@ -160,7 +182,7 @@
 
 \cleardoublepage
 \begin{docstringBox}{structure}
-\LeanVerb|\versoConst{Verso.\allowbreak{}Integration.\allowbreak{}Inheritance\-Doc.\allowbreak{}Foo\-Extends} \versoLiteral{:} \versoLiteral{Type}|\tcblower Documentation for FooExtends\par\noindent\textbf{Constructor}\par \par \LeanVerb|\versoConst{Verso.\allowbreak{}Integration.\allowbreak{}Inheritance\-Doc.\allowbreak{}Foo\-Extends.\allowbreak{}mk}|\par\noindent\textbf{Extends}\par Verso.Integration.InheritanceDoc.FooExtends\par\noindent\textbf{Fields}\par \par \LeanVerb|\versoLiteral{bar\-Field1}| : \LeanVerb|\versoConst{Bool}|\par Inherited from \LeanVerb|\versoConst{Bar\-Extended}|\par \LeanVerb|\versoLiteral{bar\-Field2}| : \LeanVerb|\versoConst{Unit}|\par Inherited from \LeanVerb|\versoConst{Bar\-Extended}|\par \LeanVerb|\versoConst{foo\-Field1}| : \LeanVerb|\versoConst{Nat}|\par Documentation for fooField1\par \LeanVerb|\versoConst{foo\-Field2}| : \LeanVerb|\versoConst{String}|\par Documentation for fooField2
+\LeanVerb|\versoConst{Verso.\allowbreak{}Integration.\allowbreak{}Inheritance\-Doc.\allowbreak{}Foo\-Extends} \versoLiteral{:} \versoSort{Type}|\tcblower Documentation for FooExtends\par\noindent\textbf{Constructor}\par \par \LeanVerb|\versoConst{Verso.\allowbreak{}Integration.\allowbreak{}Inheritance\-Doc.\allowbreak{}Foo\-Extends.\allowbreak{}mk}|\par\noindent\textbf{Extends}\par Verso.Integration.InheritanceDoc.FooExtends\par\noindent\textbf{Fields}\par \par \LeanVerb|\versoLiteral{bar\-Field1}| : \LeanVerb|\versoConst{Bool}|\par Inherited from \LeanVerb|\versoConst{Bar\-Extended}|\par \LeanVerb|\versoLiteral{bar\-Field2}| : \LeanVerb|\versoConst{Unit}|\par Inherited from \LeanVerb|\versoConst{Bar\-Extended}|\par \LeanVerb|\versoConst{foo\-Field1}| : \LeanVerb|\versoConst{Nat}|\par Documentation for fooField1\par \LeanVerb|\versoConst{foo\-Field2}| : \LeanVerb|\versoConst{String}|\par Documentation for fooField2
 \end{docstringBox}
 
 
diff --git a/src/tests/integration/sample-doc/expected/tex/main.tex b/src/tests/integration/sample-doc/expected/tex/main.tex
index cd3eaf602..e051bcf4e 100644
--- a/src/tests/integration/sample-doc/expected/tex/main.tex
+++ b/src/tests/integration/sample-doc/expected/tex/main.tex
@@ -127,10 +127,25 @@
 \providecommand{\versoConst}[1]{#1}
 \providecommand{\versoVar}[1]{\textit{#1}}
 \providecommand{\versoLiteral}[1]{#1}
+\providecommand{\versoLiteralString}[1]{#1}
+\providecommand{\versoDocComment}[1]{\textit{#1}}
+\providecommand{\versoSort}[1]{#1}
+\providecommand{\versoLevelVar}[1]{\textit{#1}}
+\providecommand{\versoLevelConst}[1]{#1}
+\providecommand{\versoLevelOp}[1]{#1}
+\providecommand{\versoModuleName}[1]{#1}
 \definecolor{versoCodeColor}{HTML}{000000}
 \definecolor{versoConstColor}{HTML}{000000}
 \definecolor{versoKeywordColor}{HTML}{000000}
 \definecolor{versoVarColor}{HTML}{000000}
+\definecolor{versoLiteralColor}{HTML}{000000}
+\definecolor{versoLiteralStringColor}{HTML}{000000}
+\definecolor{versoDocCommentColor}{HTML}{000000}
+\definecolor{versoSortColor}{HTML}{000000}
+\definecolor{versoLevelVarColor}{HTML}{000000}
+\definecolor{versoLevelConstColor}{HTML}{000000}
+\definecolor{versoLevelOpColor}{HTML}{000000}
+\definecolor{versoModuleNameColor}{HTML}{000000}
 \definecolor{errorColor}{HTML}{CC0000}
 \definecolor{warningColor}{HTML}{000000}
 \definecolor{infoColor}{HTML}{000000}
@@ -140,7 +155,14 @@
 \renewcommand{\versoKeyword}[1]{\textcolor{versoKeywordColor}{\fontseries{eb}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoConst}[1]{\textcolor{versoConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoVar}[1]{\textcolor{versoVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
-\renewcommand{\versoLiteral}[1]{\textcolor{versoCodeColor}{#1}}
+\renewcommand{\versoLiteral}[1]{\textcolor{versoLiteralColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLiteralString}[1]{\textcolor{versoLiteralStringColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoDocComment}[1]{\textcolor{versoDocCommentColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoSort}[1]{\textcolor{versoSortColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLevelVar}[1]{\textcolor{versoLevelVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoLevelConst}[1]{\textcolor{versoLevelConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLevelOp}[1]{\textcolor{versoLevelOpColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoModuleName}[1]{\textcolor{versoModuleNameColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \setmonofont{DejaVu Sans Mono}
 
 \title{\sffamily Title of the Doc}
@@ -160,7 +182,7 @@
 
 \cleardoublepage
 \begin{docstringBox}{def}
-\LeanVerb|\versoConst{Verso.\allowbreak{}Integration.\allowbreak{}Sample\-Doc.\allowbreak{}sample_constant} \versoLiteral{:} \versoLiteral{Type}|\tcblower This is a docstring.Here's some more text with a \LeanVerb|code inline| in it.
+\LeanVerb|\versoConst{Verso.\allowbreak{}Integration.\allowbreak{}Sample\-Doc.\allowbreak{}sample_constant} \versoLiteral{:} \versoSort{Type}|\tcblower This is a docstring.Here's some more text with a \LeanVerb|code inline| in it.
 Here's when a \LeanVerb|code inline|
 occurs right before a line break.And then here's a paragraph break.
 \end{docstringBox}

From eb25f7b068fdefb80bcdcff1e72a89a95857823e Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Wed, 3 Jun 2026 16:16:57 +0200
Subject: [PATCH 22/31] Fix theme picker hovers

---
 .../theme-picker/test_theme_picker.py         |  76 +++++++
 src/tests/Tests/HighlightedToTeX.lean         |   2 +-
 src/tests/golden/theme-css/default.expected   |  61 +++++-
 .../code-content-doc/expected/tex/main.tex    |  12 ++
 .../diagram-doc/expected/tex/main.tex         |  12 ++
 .../extra-files-doc/expected/tex/main.tex     |  12 ++
 .../front-matter-doc/expected/tex/main.tex    |  12 ++
 .../inheritance-doc/expected/tex/main.tex     |  12 ++
 .../sample-doc/expected/tex/main.tex          |  12 ++
 src/verso-manual/VersoManual.lean             |  27 ++-
 .../VersoManual/Theme/Assets.lean             |  91 +++++++--
 .../VersoManual/Theme/Defaults.lean           | 191 +++++++++++++++---
 src/verso/Verso/Code/Highlighted.lean         |  79 +++++++-
 src/verso/Verso/Code/HighlightedToTex.lean    |  23 ++-
 src/verso/Verso/Theme/Code.lean               | 106 +++++-----
 static-web/manual/book.css                    |  66 ++++--
 static-web/manual/theme/theme-picker.css      |  12 +-
 static-web/manual/theme/theme-picker.js       |  13 ++
 18 files changed, 670 insertions(+), 149 deletions(-)

diff --git a/browser-tests/theme-picker/test_theme_picker.py b/browser-tests/theme-picker/test_theme_picker.py
index 981bf9d45..922d800ab 100644
--- a/browser-tests/theme-picker/test_theme_picker.py
+++ b/browser-tests/theme-picker/test_theme_picker.py
@@ -538,3 +538,79 @@ def test_localStorage_disabled_still_loads(page, server):
         "data-verso-theme should be set even without storage"
     )
     assert appearance in ("light", "dark"), f"unexpected appearance {appearance!r}"
+
+
+def test_picker_preview_token_hover_shows_tippy(page):
+    """Hovering a token in the picker's code-sample preview should pop a Tippy tooltip, the
+    same way it does for tokens in the main page body.
+
+    The picker preview is built on first popover open via `preview.innerHTML = data.codeSample`.
+    The page's tippy-init script runs at DOMContentLoaded over `document.querySelectorAll(
+    tokenSelector)` — before the picker preview exists — so without follow-up wiring those
+    tokens get no `_tippy` instance and hovering them does nothing. This test currently fails
+    and is the acceptance criterion for that fix.
+    """
+    btn = _picker_button(page)
+    btn.click()
+    _dialog(page).wait_for(state="attached", timeout=5000)
+    preview = page.locator("#theme-picker-preview")
+    preview.wait_for(state="attached", timeout=5000)
+    # Pick a real hover-bearing token from the baked sample (e.g. `def greet (...) := ...`
+    # produces `.const.token` and `.var.token` entries with `data-verso-hover` IDs that
+    # reference the global `-verso-docs.json`).
+    token = preview.locator(".token[data-verso-hover]").first
+    token.wait_for(state="attached", timeout=5000)
+    # The bug shows up two ways and the test asserts both. (1) The preview token has no
+    # `_tippy` instance attached (the page-level tippy-init scanned the DOM before the
+    # picker preview existed). (2) Hovering the token does not produce a `.tippy-box`.
+    has_tippy = page.evaluate(
+        "el => !!el._tippy",
+        token.element_handle(),
+    )
+    assert has_tippy, "picker preview token should have a Tippy instance bound"
+    token.scroll_into_view_if_needed()
+    token.hover()
+    # The page-body tippy-init uses `delay: [100, null]`, so allow a brief settle window.
+    page.wait_for_selector(".tippy-box", state="visible", timeout=3000)
+
+
+def test_picker_preview_binding_highlight(page):
+    """Hovering an identifier in the picker preview should add `.binding-hl` to its other
+    occurrences in the preview — the same binding-highlight effect the manual's body code
+    gets.
+
+    The per-`.hl.lean` mouseover handler is attached at DOMContentLoaded over
+    `document.querySelectorAll('.hl.lean')`; the picker preview is built later, so without a
+    follow-up `window.versoAttachBindingHighlights(...)` call the listener never fires and
+    hovering one `name` leaves the other one untouched.
+    """
+    btn = _picker_button(page)
+    btn.click()
+    _dialog(page).wait_for(state="attached", timeout=5000)
+    preview = page.locator("#theme-picker-preview")
+    preview.wait_for(state="attached", timeout=5000)
+    # The code sample is `def greet (name : String) (count := 1) := ...intercalate count s!"Hello, {name}"`,
+    # so there are two `.var.token` elements with the same `data-binding` for `name` and two
+    # for `count`. Pick the first var token's binding, then count its peers before / after
+    # the hover.
+    bindings = preview.locator(".token[data-binding^='var-']")
+    bindings.first.wait_for(state="attached", timeout=5000)
+    first_binding = bindings.first.get_attribute("data-binding")
+    assert first_binding, "expected first var token to have a data-binding"
+    peers = preview.locator(f".token[data-binding='{first_binding}']")
+    peer_count = peers.count()
+    assert peer_count >= 2, (
+        f"expected at least two `{first_binding}` tokens in the preview, got {peer_count}"
+    )
+    # Hover the first occurrence and confirm the others gain `.binding-hl`.
+    bindings.first.scroll_into_view_if_needed()
+    bindings.first.hover()
+    page.wait_for_function(
+        f"""() => {{
+            const peers = document.querySelectorAll(
+                "#theme-picker-preview .token[data-binding='{first_binding}']");
+            const hl = Array.from(peers).filter(el => el.classList.contains('binding-hl'));
+            return hl.length === peers.length && peers.length >= 2;
+        }}""",
+        timeout=3000,
+    )
diff --git a/src/tests/Tests/HighlightedToTeX.lean b/src/tests/Tests/HighlightedToTeX.lean
index 30196151b..9d29bb1c1 100644
--- a/src/tests/Tests/HighlightedToTeX.lean
+++ b/src/tests/Tests/HighlightedToTeX.lean
@@ -38,7 +38,7 @@ literal bucket. -/
 preamble that defines its own (theme-driven) versions wins without an explicit `\renewcommand`. -/
 
 /--
-info: "\\providecommand{\\versoKeyword}[1]{\\textbf{#1}}\n\\providecommand{\\versoConst}[1]{#1}\n\\providecommand{\\versoVar}[1]{\\textit{#1}}\n\\providecommand{\\versoLiteral}[1]{#1}\n\\providecommand{\\versoLiteralString}[1]{#1}\n\\providecommand{\\versoDocComment}[1]{\\textit{#1}}\n\\providecommand{\\versoSort}[1]{#1}\n\\providecommand{\\versoLevelVar}[1]{\\textit{#1}}\n\\providecommand{\\versoLevelConst}[1]{#1}\n\\providecommand{\\versoLevelOp}[1]{#1}\n\\providecommand{\\versoModuleName}[1]{#1}\n\\providecommand{\\versoDelim}[1]{#1}\n\\providecommand{\\versoOperator}[1]{#1}\n\\providecommand{\\versoBracket}[1]{#1}\n\\providecommand{\\versoSeparator}[1]{#1}\n"
+info: "\\providecommand{\\versoKeyword}[1]{\\textbf{#1}}\n\\providecommand{\\versoConst}[1]{#1}\n\\providecommand{\\versoVar}[1]{\\textit{#1}}\n\\providecommand{\\versoLiteral}[1]{#1}\n\\providecommand{\\versoLiteralString}[1]{#1}\n\\providecommand{\\versoDocComment}[1]{\\textit{#1}}\n\\providecommand{\\versoSort}[1]{#1}\n\\providecommand{\\versoLevelVar}[1]{\\textit{#1}}\n\\providecommand{\\versoLevelConst}[1]{#1}\n\\providecommand{\\versoLevelOp}[1]{#1}\n\\providecommand{\\versoModuleName}[1]{#1}\n\\providecommand{\\versoDelim}[1]{#1}\n\\providecommand{\\versoOperator}[1]{#1}\n\\providecommand{\\versoBracket}[1]{#1}\n\\providecommand{\\versoSeparator}[1]{#1}\n\\providecommand{\\versoLiteralNumber}[1]{#1}\n\\providecommand{\\versoLiteralChar}[1]{#1}\n\\providecommand{\\versoComment}[1]{#1}\n\\providecommand{\\versoCommentDelim}[1]{#1}\n"
 -/
 #guard_msgs in #eval texMacroFallbacks
 
diff --git a/src/tests/golden/theme-css/default.expected b/src/tests/golden/theme-css/default.expected
index 0e8cbcfd2..4c9a558d7 100644
--- a/src/tests/golden/theme-css/default.expected
+++ b/src/tests/golden/theme-css/default.expected
@@ -32,10 +32,26 @@
   --verso-code-literal-string-weight: 400;
   --verso-code-literal-string-style: normal;
   --verso-code-literal-string-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --verso-code-literal-number-color: #000000;
+  --verso-code-literal-number-weight: 400;
+  --verso-code-literal-number-style: normal;
+  --verso-code-literal-number-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --verso-code-literal-char-color: #000000;
+  --verso-code-literal-char-weight: 400;
+  --verso-code-literal-char-style: normal;
+  --verso-code-literal-char-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
   --verso-code-doc-comment-color: #000000;
   --verso-code-doc-comment-weight: 400;
   --verso-code-doc-comment-style: italic;
   --verso-code-doc-comment-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --verso-code-comment-color: #000000;
+  --verso-code-comment-weight: 400;
+  --verso-code-comment-style: normal;
+  --verso-code-comment-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  --verso-code-comment-delim-color: #000000;
+  --verso-code-comment-delim-weight: 400;
+  --verso-code-comment-delim-style: normal;
+  --verso-code-comment-delim-font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
   --verso-code-sort-color: #000000;
   --verso-code-sort-weight: 400;
   --verso-code-sort-style: normal;
@@ -182,16 +198,11 @@
   font-family: var(--verso-code-module-name-font-family, var(--verso-code-font-family,));
 }
 
-/* The lexically-classified token kinds added by SubVerso (anon-ctor, number, char, comment,
-   wildcard) default to the unthemed `.unknown` appearance. The themeable rules above already
-   cover the semantic kinds (`.literal`, `.doc-comment`, etc.) and win when both apply (e.g.
-   `.anon-ctor` also carries `.const`; a number nested inside a literal span is still themed
-   by `.literal`). Future phases may introduce dedicated theme buckets for numbers, characters,
-   and comments. */
+/* `.anon-ctor` (anonymous-constructor brackets) and `.wildcard` (`_` holes) default to the
+   unthemed `.unknown` appearance — neither has its own theme bucket yet. `.anon-ctor` also
+   carries the `.const` class, so the themeable `.const` rule above wins for it where set.
+   Number, character, and comment kinds are themed via their own rules further down. */
 .hl.lean .anon-ctor,
-.hl.lean .number,
-.hl.lean .char,
-.hl.lean .comment,
 .hl.lean .wildcard {
   color: var(--verso-code-color,);
   font-weight: normal;
@@ -199,6 +210,38 @@
   font-family: var(--verso-code-font-family,);
 }
 
+.hl.lean .literal.number {
+  color: var(--verso-code-literal-number-color, var(--verso-code-literal-color, var(--verso-code-color,)));
+  font-weight: var(--verso-code-literal-number-weight, normal);
+  font-style: var(--verso-code-literal-number-style, normal);
+  font-family: var(--verso-code-literal-number-font-family, var(--verso-code-font-family,));
+}
+
+.hl.lean .literal.char {
+  color: var(--verso-code-literal-char-color, var(--verso-code-literal-string-color, var(--verso-code-literal-color, var(--verso-code-color,))));
+  font-weight: var(--verso-code-literal-char-weight, normal);
+  font-style: var(--verso-code-literal-char-style, normal);
+  font-family: var(--verso-code-literal-char-font-family, var(--verso-code-font-family,));
+}
+
+/* `.comment` covers line and block comments (their elements carry `comment line` and
+   `comment block` class pairs respectively); `.comment.delimiter` is a more specific
+   override for the `--` / `/-` / `-/` punctuation. The themeable `.doc-comment` rule above
+   wins for doc comments since SubVerso tags them with their own class entirely. */
+.hl.lean .comment {
+  color: var(--verso-code-comment-color, var(--verso-code-color,));
+  font-weight: var(--verso-code-comment-weight, normal);
+  font-style: var(--verso-code-comment-style, normal);
+  font-family: var(--verso-code-comment-font-family, var(--verso-code-font-family,));
+}
+
+.hl.lean .comment.delimiter {
+  color: var(--verso-code-comment-delim-color, var(--verso-code-comment-color, var(--verso-code-color,)));
+  font-weight: var(--verso-code-comment-delim-weight, normal);
+  font-style: var(--verso-code-comment-delim-style, normal);
+  font-family: var(--verso-code-comment-delim-font-family, var(--verso-code-font-family,));
+}
+
 /* `.delim` is the built-in syntactic delimiter family (`:=`, `=>`, `←`, `@`, `:`, `|`). The
    three punctuation buckets — `.punctuation.operator`, `.punctuation.bracket`,
    `.punctuation.separator` — are themed independently below; their CSS variables resolve
diff --git a/src/tests/integration/code-content-doc/expected/tex/main.tex b/src/tests/integration/code-content-doc/expected/tex/main.tex
index 127701cc2..8e2c4c4e9 100644
--- a/src/tests/integration/code-content-doc/expected/tex/main.tex
+++ b/src/tests/integration/code-content-doc/expected/tex/main.tex
@@ -138,13 +138,21 @@
 \providecommand{\versoOperator}[1]{#1}
 \providecommand{\versoBracket}[1]{#1}
 \providecommand{\versoSeparator}[1]{#1}
+\providecommand{\versoLiteralNumber}[1]{#1}
+\providecommand{\versoLiteralChar}[1]{#1}
+\providecommand{\versoComment}[1]{#1}
+\providecommand{\versoCommentDelim}[1]{#1}
 \definecolor{versoCodeColor}{HTML}{000000}
 \definecolor{versoConstColor}{HTML}{000000}
 \definecolor{versoKeywordColor}{HTML}{000000}
 \definecolor{versoVarColor}{HTML}{000000}
 \definecolor{versoLiteralColor}{HTML}{000000}
 \definecolor{versoLiteralStringColor}{HTML}{000000}
+\definecolor{versoLiteralNumberColor}{HTML}{000000}
+\definecolor{versoLiteralCharColor}{HTML}{000000}
 \definecolor{versoDocCommentColor}{HTML}{000000}
+\definecolor{versoCommentColor}{HTML}{000000}
+\definecolor{versoCommentDelimColor}{HTML}{000000}
 \definecolor{versoSortColor}{HTML}{000000}
 \definecolor{versoLevelVarColor}{HTML}{000000}
 \definecolor{versoLevelConstColor}{HTML}{000000}
@@ -165,7 +173,11 @@
 \renewcommand{\versoVar}[1]{\textcolor{versoVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
 \renewcommand{\versoLiteral}[1]{\textcolor{versoLiteralColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoLiteralString}[1]{\textcolor{versoLiteralStringColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLiteralNumber}[1]{\textcolor{versoLiteralNumberColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLiteralChar}[1]{\textcolor{versoLiteralCharColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoDocComment}[1]{\textcolor{versoDocCommentColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoComment}[1]{\textcolor{versoCommentColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoCommentDelim}[1]{\textcolor{versoCommentDelimColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoSort}[1]{\textcolor{versoSortColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoLevelVar}[1]{\textcolor{versoLevelVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
 \renewcommand{\versoLevelConst}[1]{\textcolor{versoLevelConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
diff --git a/src/tests/integration/diagram-doc/expected/tex/main.tex b/src/tests/integration/diagram-doc/expected/tex/main.tex
index f8e7d1294..5b8dcf60e 100644
--- a/src/tests/integration/diagram-doc/expected/tex/main.tex
+++ b/src/tests/integration/diagram-doc/expected/tex/main.tex
@@ -138,13 +138,21 @@
 \providecommand{\versoOperator}[1]{#1}
 \providecommand{\versoBracket}[1]{#1}
 \providecommand{\versoSeparator}[1]{#1}
+\providecommand{\versoLiteralNumber}[1]{#1}
+\providecommand{\versoLiteralChar}[1]{#1}
+\providecommand{\versoComment}[1]{#1}
+\providecommand{\versoCommentDelim}[1]{#1}
 \definecolor{versoCodeColor}{HTML}{000000}
 \definecolor{versoConstColor}{HTML}{000000}
 \definecolor{versoKeywordColor}{HTML}{000000}
 \definecolor{versoVarColor}{HTML}{000000}
 \definecolor{versoLiteralColor}{HTML}{000000}
 \definecolor{versoLiteralStringColor}{HTML}{000000}
+\definecolor{versoLiteralNumberColor}{HTML}{000000}
+\definecolor{versoLiteralCharColor}{HTML}{000000}
 \definecolor{versoDocCommentColor}{HTML}{000000}
+\definecolor{versoCommentColor}{HTML}{000000}
+\definecolor{versoCommentDelimColor}{HTML}{000000}
 \definecolor{versoSortColor}{HTML}{000000}
 \definecolor{versoLevelVarColor}{HTML}{000000}
 \definecolor{versoLevelConstColor}{HTML}{000000}
@@ -165,7 +173,11 @@
 \renewcommand{\versoVar}[1]{\textcolor{versoVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
 \renewcommand{\versoLiteral}[1]{\textcolor{versoLiteralColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoLiteralString}[1]{\textcolor{versoLiteralStringColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLiteralNumber}[1]{\textcolor{versoLiteralNumberColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLiteralChar}[1]{\textcolor{versoLiteralCharColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoDocComment}[1]{\textcolor{versoDocCommentColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoComment}[1]{\textcolor{versoCommentColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoCommentDelim}[1]{\textcolor{versoCommentDelimColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoSort}[1]{\textcolor{versoSortColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoLevelVar}[1]{\textcolor{versoLevelVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
 \renewcommand{\versoLevelConst}[1]{\textcolor{versoLevelConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
diff --git a/src/tests/integration/extra-files-doc/expected/tex/main.tex b/src/tests/integration/extra-files-doc/expected/tex/main.tex
index 258387a31..b6dfe70c2 100644
--- a/src/tests/integration/extra-files-doc/expected/tex/main.tex
+++ b/src/tests/integration/extra-files-doc/expected/tex/main.tex
@@ -138,13 +138,21 @@
 \providecommand{\versoOperator}[1]{#1}
 \providecommand{\versoBracket}[1]{#1}
 \providecommand{\versoSeparator}[1]{#1}
+\providecommand{\versoLiteralNumber}[1]{#1}
+\providecommand{\versoLiteralChar}[1]{#1}
+\providecommand{\versoComment}[1]{#1}
+\providecommand{\versoCommentDelim}[1]{#1}
 \definecolor{versoCodeColor}{HTML}{000000}
 \definecolor{versoConstColor}{HTML}{000000}
 \definecolor{versoKeywordColor}{HTML}{000000}
 \definecolor{versoVarColor}{HTML}{000000}
 \definecolor{versoLiteralColor}{HTML}{000000}
 \definecolor{versoLiteralStringColor}{HTML}{000000}
+\definecolor{versoLiteralNumberColor}{HTML}{000000}
+\definecolor{versoLiteralCharColor}{HTML}{000000}
 \definecolor{versoDocCommentColor}{HTML}{000000}
+\definecolor{versoCommentColor}{HTML}{000000}
+\definecolor{versoCommentDelimColor}{HTML}{000000}
 \definecolor{versoSortColor}{HTML}{000000}
 \definecolor{versoLevelVarColor}{HTML}{000000}
 \definecolor{versoLevelConstColor}{HTML}{000000}
@@ -165,7 +173,11 @@
 \renewcommand{\versoVar}[1]{\textcolor{versoVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
 \renewcommand{\versoLiteral}[1]{\textcolor{versoLiteralColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoLiteralString}[1]{\textcolor{versoLiteralStringColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLiteralNumber}[1]{\textcolor{versoLiteralNumberColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLiteralChar}[1]{\textcolor{versoLiteralCharColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoDocComment}[1]{\textcolor{versoDocCommentColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoComment}[1]{\textcolor{versoCommentColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoCommentDelim}[1]{\textcolor{versoCommentDelimColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoSort}[1]{\textcolor{versoSortColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoLevelVar}[1]{\textcolor{versoLevelVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
 \renewcommand{\versoLevelConst}[1]{\textcolor{versoLevelConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
diff --git a/src/tests/integration/front-matter-doc/expected/tex/main.tex b/src/tests/integration/front-matter-doc/expected/tex/main.tex
index 59086c290..037e23e12 100644
--- a/src/tests/integration/front-matter-doc/expected/tex/main.tex
+++ b/src/tests/integration/front-matter-doc/expected/tex/main.tex
@@ -138,13 +138,21 @@
 \providecommand{\versoOperator}[1]{#1}
 \providecommand{\versoBracket}[1]{#1}
 \providecommand{\versoSeparator}[1]{#1}
+\providecommand{\versoLiteralNumber}[1]{#1}
+\providecommand{\versoLiteralChar}[1]{#1}
+\providecommand{\versoComment}[1]{#1}
+\providecommand{\versoCommentDelim}[1]{#1}
 \definecolor{versoCodeColor}{HTML}{000000}
 \definecolor{versoConstColor}{HTML}{000000}
 \definecolor{versoKeywordColor}{HTML}{000000}
 \definecolor{versoVarColor}{HTML}{000000}
 \definecolor{versoLiteralColor}{HTML}{000000}
 \definecolor{versoLiteralStringColor}{HTML}{000000}
+\definecolor{versoLiteralNumberColor}{HTML}{000000}
+\definecolor{versoLiteralCharColor}{HTML}{000000}
 \definecolor{versoDocCommentColor}{HTML}{000000}
+\definecolor{versoCommentColor}{HTML}{000000}
+\definecolor{versoCommentDelimColor}{HTML}{000000}
 \definecolor{versoSortColor}{HTML}{000000}
 \definecolor{versoLevelVarColor}{HTML}{000000}
 \definecolor{versoLevelConstColor}{HTML}{000000}
@@ -165,7 +173,11 @@
 \renewcommand{\versoVar}[1]{\textcolor{versoVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
 \renewcommand{\versoLiteral}[1]{\textcolor{versoLiteralColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoLiteralString}[1]{\textcolor{versoLiteralStringColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLiteralNumber}[1]{\textcolor{versoLiteralNumberColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLiteralChar}[1]{\textcolor{versoLiteralCharColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoDocComment}[1]{\textcolor{versoDocCommentColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoComment}[1]{\textcolor{versoCommentColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoCommentDelim}[1]{\textcolor{versoCommentDelimColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoSort}[1]{\textcolor{versoSortColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoLevelVar}[1]{\textcolor{versoLevelVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
 \renewcommand{\versoLevelConst}[1]{\textcolor{versoLevelConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
diff --git a/src/tests/integration/inheritance-doc/expected/tex/main.tex b/src/tests/integration/inheritance-doc/expected/tex/main.tex
index 88ad612b1..b2170fbbf 100644
--- a/src/tests/integration/inheritance-doc/expected/tex/main.tex
+++ b/src/tests/integration/inheritance-doc/expected/tex/main.tex
@@ -138,13 +138,21 @@
 \providecommand{\versoOperator}[1]{#1}
 \providecommand{\versoBracket}[1]{#1}
 \providecommand{\versoSeparator}[1]{#1}
+\providecommand{\versoLiteralNumber}[1]{#1}
+\providecommand{\versoLiteralChar}[1]{#1}
+\providecommand{\versoComment}[1]{#1}
+\providecommand{\versoCommentDelim}[1]{#1}
 \definecolor{versoCodeColor}{HTML}{000000}
 \definecolor{versoConstColor}{HTML}{000000}
 \definecolor{versoKeywordColor}{HTML}{000000}
 \definecolor{versoVarColor}{HTML}{000000}
 \definecolor{versoLiteralColor}{HTML}{000000}
 \definecolor{versoLiteralStringColor}{HTML}{000000}
+\definecolor{versoLiteralNumberColor}{HTML}{000000}
+\definecolor{versoLiteralCharColor}{HTML}{000000}
 \definecolor{versoDocCommentColor}{HTML}{000000}
+\definecolor{versoCommentColor}{HTML}{000000}
+\definecolor{versoCommentDelimColor}{HTML}{000000}
 \definecolor{versoSortColor}{HTML}{000000}
 \definecolor{versoLevelVarColor}{HTML}{000000}
 \definecolor{versoLevelConstColor}{HTML}{000000}
@@ -165,7 +173,11 @@
 \renewcommand{\versoVar}[1]{\textcolor{versoVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
 \renewcommand{\versoLiteral}[1]{\textcolor{versoLiteralColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoLiteralString}[1]{\textcolor{versoLiteralStringColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLiteralNumber}[1]{\textcolor{versoLiteralNumberColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLiteralChar}[1]{\textcolor{versoLiteralCharColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoDocComment}[1]{\textcolor{versoDocCommentColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoComment}[1]{\textcolor{versoCommentColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoCommentDelim}[1]{\textcolor{versoCommentDelimColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoSort}[1]{\textcolor{versoSortColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoLevelVar}[1]{\textcolor{versoLevelVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
 \renewcommand{\versoLevelConst}[1]{\textcolor{versoLevelConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
diff --git a/src/tests/integration/sample-doc/expected/tex/main.tex b/src/tests/integration/sample-doc/expected/tex/main.tex
index 0e6e99d4c..47916a36d 100644
--- a/src/tests/integration/sample-doc/expected/tex/main.tex
+++ b/src/tests/integration/sample-doc/expected/tex/main.tex
@@ -138,13 +138,21 @@
 \providecommand{\versoOperator}[1]{#1}
 \providecommand{\versoBracket}[1]{#1}
 \providecommand{\versoSeparator}[1]{#1}
+\providecommand{\versoLiteralNumber}[1]{#1}
+\providecommand{\versoLiteralChar}[1]{#1}
+\providecommand{\versoComment}[1]{#1}
+\providecommand{\versoCommentDelim}[1]{#1}
 \definecolor{versoCodeColor}{HTML}{000000}
 \definecolor{versoConstColor}{HTML}{000000}
 \definecolor{versoKeywordColor}{HTML}{000000}
 \definecolor{versoVarColor}{HTML}{000000}
 \definecolor{versoLiteralColor}{HTML}{000000}
 \definecolor{versoLiteralStringColor}{HTML}{000000}
+\definecolor{versoLiteralNumberColor}{HTML}{000000}
+\definecolor{versoLiteralCharColor}{HTML}{000000}
 \definecolor{versoDocCommentColor}{HTML}{000000}
+\definecolor{versoCommentColor}{HTML}{000000}
+\definecolor{versoCommentDelimColor}{HTML}{000000}
 \definecolor{versoSortColor}{HTML}{000000}
 \definecolor{versoLevelVarColor}{HTML}{000000}
 \definecolor{versoLevelConstColor}{HTML}{000000}
@@ -165,7 +173,11 @@
 \renewcommand{\versoVar}[1]{\textcolor{versoVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
 \renewcommand{\versoLiteral}[1]{\textcolor{versoLiteralColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoLiteralString}[1]{\textcolor{versoLiteralStringColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLiteralNumber}[1]{\textcolor{versoLiteralNumberColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoLiteralChar}[1]{\textcolor{versoLiteralCharColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoDocComment}[1]{\textcolor{versoDocCommentColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
+\renewcommand{\versoComment}[1]{\textcolor{versoCommentColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
+\renewcommand{\versoCommentDelim}[1]{\textcolor{versoCommentDelimColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoSort}[1]{\textcolor{versoSortColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
 \renewcommand{\versoLevelVar}[1]{\textcolor{versoLevelVarColor}{\fontseries{m}\fontshape{it}\selectfont #1}}
 \renewcommand{\versoLevelConst}[1]{\textcolor{versoLevelConstColor}{\fontseries{m}\fontshape{n}\selectfont #1}}
diff --git a/src/verso-manual/VersoManual.lean b/src/verso-manual/VersoManual.lean
index 50b6f39a4..763d5d467 100644
--- a/src/verso-manual/VersoManual.lean
+++ b/src/verso-manual/VersoManual.lean
@@ -480,7 +480,8 @@ picker `.js`/`.css`, the `window.versoThemes` data file, every theme's font byte
 assets. Content-addressed font filenames in the theme registry ensure that two themes sharing the
 same font end up with one byte payload on disk.
 -/
-def writeThemeAssets (dir : System.FilePath) (config : RenderConfig) : EmitM Unit := do
+def writeThemeAssets (dir : System.FilePath) (config : RenderConfig)
+    (codeSampleHtml : String) : EmitM Unit := do
   let themes ← readThe ThemeRegistry
   ensureDir (dir / "-verso-data")
   let single := singleDefaultTheme themes config
@@ -511,7 +512,7 @@ def writeThemeAssets (dir : System.FilePath) (config : RenderConfig) : EmitM Uni
   writeFile (dir / "-verso-data" / "theme-picker.css") Manual.Theme.«theme-picker.css»
   writeFile (dir / "-verso-data" / "verso-themes.js")
     (Verso.Theme.windowVersoThemesJs themes config.defaultLightTheme config.defaultDarkTheme
-      (defaultSingleName config) Manual.Theme.codeSampleHtml)
+      (defaultSingleName config) codeSampleHtml)
 
 open IO.FS in
 def emitTeX (config : RenderConfig) (text : Part Manual) : EmitM Unit := do
@@ -907,7 +908,16 @@ where
       emitSearchResultsHtml toc dir titleToShow state config.toConfig
     IO.FS.withFile (dir.join "book.css") .write fun h => do
       h.putStrLn Html.Css.pageStyle
-    writeThemeAssets dir config
+    -- Render the picker preview against the in-progress hover state so its `data-verso-hover`
+    -- IDs end up in the global `-verso-docs.json` the page loads — the same lookup the picker
+    -- JS already does for every other token. Without this the picker tokens have hover IDs
+    -- that reference nothing.
+    let codeSampleCtx : Verso.Code.HighlightHtmlM.Context Manual := {
+      linkTargets := {}, traverseContext := {}, definitionIds := {}, options := {}
+    }
+    let (codeSampleHtml, htmlState') := Manual.Theme.codeSampleHtml codeSampleCtx (← get)
+    set htmlState'
+    writeThemeAssets dir config codeSampleHtml
     for (src, dest) in config.extraFiles do
       copyRecursively src (dir.join dest)
     for (src, dest) in config.extraFilesHtml do
@@ -985,7 +995,16 @@ where
       else titleHtml
     IO.FS.withFile (root / "book.css") .write fun h => do
       h.putStrLn Html.Css.pageStyle
-    writeThemeAssets root config
+    -- Render the picker preview against the in-progress hover state so its `data-verso-hover`
+    -- IDs end up in the global `-verso-docs.json` the page loads — the same lookup the picker
+    -- JS already does for every other token. Without this the picker tokens have hover IDs
+    -- that reference nothing.
+    let codeSampleCtx : Verso.Code.HighlightHtmlM.Context Manual := {
+      linkTargets := {}, traverseContext := {}, definitionIds := {}, options := {}
+    }
+    let (codeSampleHtml, htmlState') := Manual.Theme.codeSampleHtml codeSampleCtx (← get)
+    set htmlState'
+    writeThemeAssets root config codeSampleHtml
     for (src, dest) in config.extraFiles do
       copyRecursively src (root.join dest)
     for (src, dest) in config.extraFilesHtml do
diff --git a/src/verso-manual/VersoManual/Theme/Assets.lean b/src/verso-manual/VersoManual/Theme/Assets.lean
index a4e0751c5..7945d94ab 100644
--- a/src/verso-manual/VersoManual/Theme/Assets.lean
+++ b/src/verso-manual/VersoManual/Theme/Assets.lean
@@ -5,6 +5,13 @@ Author: David Thrane Christiansen
 -/
 module
 meta import Init.System.FilePath
+public meta import Lean.Elab.Frontend
+public meta import Lean.Elab.Term
+public meta import SubVerso.Highlighting
+public meta import SubVerso.Highlighting.Code
+public meta import SubVerso.Compat
+public import SubVerso.Highlighting
+public import Verso.Code.Highlighted
 
 namespace Verso.Genre.Manual.Theme
 
@@ -14,22 +21,72 @@ public def «theme-picker.js» : String := include_str "../../../../static-web/m
 /-- The picker styles. -/
 public def «theme-picker.css» : String := include_str "../../../../static-web/manual/theme/theme-picker.css"
 
+section
+open Lean Elab Term
+
+/--
+Elaborates `input` as a sequence of Lean commands and returns SubVerso's highlighting of the result.
+-/
+private meta def highlightFromString (input : String) :
+    TermElabM SubVerso.Highlighting.Highlighted := do
+  let inputCtx := Parser.mkInputContext input "<codeSample>"
+  -- Turn on app-fn tagging so per-identifier `TermInfo` is recorded
+  let opts := pp.tagAppFns.set ({} : Lean.Options) true
+  let scope : Command.Scope := { header := "", opts }
+  let commandState : Command.State := {
+    env := (← getEnv),
+    maxRecDepth := (← MonadRecDepth.getMaxRecDepth),
+    scopes := [scope]
+  }
+  let (result, _) ←
+    SubVerso.Compat.Frontend.processCommands Lean.mkNullNode
+      |>.run { inputCtx } |>.run { commandState, parserState := {}, cmdPos := 0 }
+  let items := result.items.filter (·.commandSyntax.getKind != ``Lean.Parser.Command.eoi)
+  let mut hls : SubVerso.Highlighting.Highlighted := .empty
+  let mut lastPos : String.Pos.Raw := 0
+  for item in items do
+    let hl ← withTheReader Core.Context (fun ctx => { ctx with fileMap := inputCtx.fileMap }) do
+      unless item.messages.toArray.isEmpty do
+        throwError "Highlighting source produced messages: {← item.messages.toArray.mapM (·.toString)}"
+      SubVerso.Highlighting.highlightIncludingUnparsed item.commandSyntax (startPos? := lastPos)
+        item.messages.toArray item.info
+    lastPos := (item.commandSyntax.getTrailingTailPos?).getD lastPos
+    hls := hls ++ hl
+  return hls
+
+/--
+At compile time, parses, elaborates, and highlights the given Lean source string, then quotes the
+result as a `Highlighted` value.
+-/
+syntax (name := codeSampleTerm) "code_sample% " str : term
+
+@[term_elab codeSampleTerm]
+public meta def elabCodeSampleTerm : TermElab := fun stx expectedType? => do
+  match stx with
+  | `(code_sample% $src:str) =>
+    let hl ← highlightFromString src.getString
+    let q : Lean.Term := Lean.quote hl
+    elabTerm q expectedType?
+  | _ => throwUnsupportedSyntax
+
+end
+
+public def codeSampleHighlighted : SubVerso.Highlighting.Highlighted :=
+  code_sample% r#"def greet (name : String) (count := 1) : String :=
+  "\n".intercalate <|
+    List.replicate count s!"Hello, {name}""#
+
+open Verso.Code Verso.Output in
 /--
-A small fixed code sample the picker drops into the preview pane so the user can see what each
-candidate theme will look like. Rendered as `def greet name := s!"Hello, {name}"` using the
-same `.hl.lean` token classes the real highlighter emits, so token colors, weights, and the
-font family resolve from the candidate theme.
+Renders the code sample to HTML. The hover state is needed because the code sample itself may need
+hovers.
 -/
-public def codeSampleHtml : String :=
-  "<code class=\"hl lean block\">" ++
-  "<span class=\"keyword\">def</span> " ++
-  "<span class=\"const\">greet</span> " ++
-  "<span class=\"var\">name</span> " ++
-  "<span class=\"delim\">:=</span> " ++
-  "<span class=\"keyword\">s!</span>" ++
-  "<span class=\"literal string\">&quot;Hello, {</span>" ++
-  "<span class=\"var\">name</span>" ++
-  "<span class=\"literal string\">}&quot;</span>" ++
-  "</code>"
-
-end Verso.Genre.Manual.Theme
+public def codeSampleHtml {g : Verso.Doc.Genre}
+    (ctx : HighlightHtmlM.Context g) (state : Hover.State Html) :
+    String × Hover.State Html :=
+  -- Distinct `data-lean-context` from any page-level code block so the page-side
+  -- binding-highlight lookup (cached by `context+binding`) naturally scopes its
+  -- matching-token search to the preview itself rather than leaking into the document.
+  let (html, state') :=
+    ((codeSampleHighlighted.blockHtml (g := g) "verso-theme-picker") |>.run ctx) |>.run state
+  (html.asString (breakLines := false), state')
diff --git a/src/verso-manual/VersoManual/Theme/Defaults.lean b/src/verso-manual/VersoManual/Theme/Defaults.lean
index 47ca23761..4a3c290fd 100644
--- a/src/verso-manual/VersoManual/Theme/Defaults.lean
+++ b/src/verso-manual/VersoManual/Theme/Defaults.lean
@@ -87,6 +87,10 @@ private def darkCodeBase : CodeTheme :=
   operator := { color := text, weight := .regular, style := .normal, face := .mono },
   bracket := { color := text, weight := .regular, style := .normal, face := .mono },
   separator := { color := text, weight := .regular, style := .normal, face := .mono },
+  literalNumber := { color := text, weight := .regular, style := .normal, face := .mono },
+  literalChar := { color := text, weight := .regular, style := .normal, face := .mono },
+  comment := { color := text, weight := .regular, style := .normal, face := .mono },
+  commentDelim := { color := text, weight := .regular, style := .normal, face := .mono },
   -- Hover popups read text on a slightly lighter surface.
   hoverBackground := color%#2a2d33,
   hoverText := text,
@@ -219,6 +223,10 @@ public def ManualTheme.beaconLight : ManualTheme :=
     «var» := { color := vermillion, weight := .regular, style := .italic, face := .mono },
     literal := { color := Color.black, weight := .regular, style := .normal, face := .mono },
     literalString := { color := reddishPurple, weight := .regular, style := .normal, face := .mono },
+    -- Per the docstring's "orange → numeric literals": real number literals get orange too,
+    -- not just `levelConst`. Character literals share the string hue.
+    literalNumber := { color := orange, weight := .regular, style := .normal, face := .mono },
+    literalChar := { color := reddishPurple, weight := .regular, style := .normal, face := .mono },
     docComment := { color := Color.black, weight := .regular, style := .italic, face := .mono },
     sort := { color := vermillion, weight := .bold, style := .normal, face := .mono },
     levelVar := { color := vermillion, weight := .regular, style := .italic, face := .mono },
@@ -247,6 +255,9 @@ public def ManualTheme.beaconDark : ManualTheme :=
     const := { color := bluishGreen, weight := .regular, style := .normal, face := .mono },
     «var» := { color := orange, weight := .regular, style := .italic, face := .mono },
     literalString := { color := yellow, weight := .regular, style := .normal, face := .mono },
+    -- Pair real number literals with `levelConst` on yellow; characters share the string hue.
+    literalNumber := { color := yellow, weight := .regular, style := .normal, face := .mono },
+    literalChar := { color := yellow, weight := .regular, style := .normal, face := .mono },
     sort := { color := reddishPurple, weight := .bold, style := .normal, face := .mono },
     levelVar := { color := orange, weight := .regular, style := .italic, face := .mono },
     levelConst := { color := yellow, weight := .regular, style := .normal, face := .mono },
@@ -310,11 +321,27 @@ public def ManualTheme.solarizedLight : ManualTheme :=
       «var» := { color := violet, weight := .regular, style := .italic, face := .mono },
       literal := { color := base00, weight := .regular, style := .normal, face := .mono },
       literalString := { color := cyan, weight := .regular, style := .normal, face := .mono },
+      -- Numbers and characters → cyan, matching Solarized vim's `Number`/`Character` mapping
+      -- (the `Constant` family). Operator → green (links to `Statement`).
+      literalNumber := { color := cyan, weight := .regular, style := .normal, face := .mono },
+      literalChar := { color := cyan, weight := .regular, style := .normal, face := .mono },
+      operator := { color := green, weight := .regular, style := .normal, face := .mono },
+      -- `delim`/`bracket`/`separator` are spelled out at base00 (Solarized Light's body
+      -- code color). Without these, `CodeTheme.ink with` would leave them frozen at Ink's
+      -- black `codeColor`.
+      delim := { color := base00, weight := .regular, style := .normal, face := .mono },
+      bracket := { color := base00, weight := .regular, style := .normal, face := .mono },
+      separator := { color := base00, weight := .regular, style := .normal, face := .mono },
       docComment := { color := base1, weight := .regular, style := .italic, face := .mono },
+      -- Comments → base1, Solarized's documented "secondary content" shade on the light
+      -- substrate. This is intentionally sub-AA per the spec (Schoonover's contrast trade-off
+      -- to background-out commentary); the per-theme accessibility check flags it.
+      comment := { color := base1, weight := .regular, style := .italic, face := .mono },
+      commentDelim := { color := base1, weight := .regular, style := .italic, face := .mono },
       sort := { color := yellow, weight := .regular, style := .normal, face := .mono },
       levelVar := { color := violet, weight := .regular, style := .italic, face := .mono },
-      levelConst := { color := orange, weight := .regular, style := .normal, face := .mono },
-      levelOp := { color := magenta, weight := .regular, style := .normal, face := .mono },
+      levelConst := { color := cyan, weight := .regular, style := .normal, face := .mono },
+      levelOp := { color := green, weight := .regular, style := .normal, face := .mono },
       moduleName := { color := magenta, weight := .regular, style := .normal, face := .mono }
     },
     surfaceColor := base2,
@@ -371,11 +398,24 @@ public def ManualTheme.solarizedDark : ManualTheme :=
     «var» := { color := violet, weight := .regular, style := .italic, face := .mono },
     literal := { color := base0, weight := .regular, style := .normal, face := .mono },
     literalString := { color := cyan, weight := .regular, style := .normal, face := .mono },
+    -- Spec-aligned: cyan for Number/Character, green for Operator. See `solarizedLight`
+    -- for the same role rationale.
+    literalNumber := { color := cyan, weight := .regular, style := .normal, face := .mono },
+    literalChar := { color := cyan, weight := .regular, style := .normal, face := .mono },
+    operator := { color := green, weight := .regular, style := .normal, face := .mono },
+    -- `delim`/`bracket`/`separator` spelled out at base0 (Solarized Dark's body code
+    -- color). `darkCodeBase with` leaves them at the generic dark base's `#e8e8e8`
+    -- otherwise — readable but off-palette.
+    delim := { color := base0, weight := .regular, style := .normal, face := .mono },
+    bracket := { color := base0, weight := .regular, style := .normal, face := .mono },
+    separator := { color := base0, weight := .regular, style := .normal, face := .mono },
     docComment := { color := base01, weight := .regular, style := .italic, face := .mono },
+    comment := { color := base01, weight := .regular, style := .italic, face := .mono },
+    commentDelim := { color := base01, weight := .regular, style := .italic, face := .mono },
     sort := { color := yellow, weight := .regular, style := .normal, face := .mono },
     levelVar := { color := violet, weight := .regular, style := .italic, face := .mono },
-    levelConst := { color := orange, weight := .regular, style := .normal, face := .mono },
-    levelOp := { color := magenta, weight := .regular, style := .normal, face := .mono },
+    levelConst := { color := cyan, weight := .regular, style := .normal, face := .mono },
+    levelOp := { color := green, weight := .regular, style := .normal, face := .mono },
     moduleName := { color := magenta, weight := .regular, style := .normal, face := .mono }
   } with
     -- Solarized-tinted chrome instead of the generic dark-chrome accents.
@@ -443,10 +483,21 @@ public def ManualTheme.nord : ManualTheme :=
       levelOp := { color := nord10, weight := .regular, style := .normal, face := .mono },
       moduleName := { color := nord7, weight := .regular, style := .normal, face := .mono },
       -- Symbolic operators → nord9, the Nord syntax doc's "operators, support, tags" slot.
-      -- `delim` is left at the body color: it bundles `:` and `|` along with `:=`/`=>`,
-      -- and painting the whole family nord9 would put a syntax accent on every typed binder.
-      -- `bracket` and `separator` cascade from `delim` and so also stay on nord4.
+      -- `delim`, `bracket`, and `separator` ride on nord4 (the body color): `.delim` bundles
+      -- `:` and `|` with `:=`/`=>`, and painting them nord9 would put a syntax accent on every
+      -- typed binder. These are spelled out because `CodeTheme.ink with` doesn't re-evaluate
+      -- the cascade defaults — they'd otherwise stay frozen at Ink's black `codeColor`.
+      delim := { color := nord4, weight := .regular, style := .normal, face := .mono },
       operator := { color := nord9, weight := .regular, style := .normal, face := .mono },
+      bracket := { color := nord4, weight := .regular, style := .normal, face := .mono },
+      separator := { color := nord4, weight := .regular, style := .normal, face := .mono },
+      -- Per the Nord syntax doc: nord15 ("numbers, floating-point literals") → numbers;
+      -- chars share nord14 with strings (no separate slot); nord3 ("comments / indent
+      -- guides") → ordinary line and block comments and their delimiters.
+      literalNumber := { color := nord15, weight := .regular, style := .normal, face := .mono },
+      literalChar := { color := nord14, weight := .regular, style := .normal, face := .mono },
+      comment := { color := nord3, weight := .regular, style := .normal, face := .mono },
+      commentDelim := { color := nord3, weight := .regular, style := .normal, face := .mono },
       hoverBackground := nord2,
       hoverText := nord4,
       hoverBorderColor := nord3,
@@ -529,9 +580,18 @@ public def ManualTheme.nordLight : ManualTheme where
     levelOp := { color := nord10, weight := .regular, style := .normal, face := .mono },
     moduleName := { color := nord7, weight := .regular, style := .normal, face := .mono },
     -- Symbolic operators → nord9 (the Nord syntax doc's "operators, support, tags" slot).
-    -- See `ManualTheme.nord` for the rationale that keeps `delim` on body color rather than
-    -- accenting it.
-    operator := { color := nord9, weight := .regular, style := .normal, face := .mono }
+    -- `delim`/`bracket`/`separator` ride on nord0 (the body code color). See
+    -- `ManualTheme.nord` for the rationale and the `with`-doesn't-re-evaluate-defaults note.
+    delim := { color := nord0, weight := .regular, style := .normal, face := .mono },
+    operator := { color := nord9, weight := .regular, style := .normal, face := .mono },
+    bracket := { color := nord0, weight := .regular, style := .normal, face := .mono },
+    separator := { color := nord0, weight := .regular, style := .normal, face := .mono },
+    -- Same per-spec role assignments as the dark variant: nord15 numbers, nord14 chars,
+    -- nord3 comments.
+    literalNumber := { color := nord15, weight := .regular, style := .normal, face := .mono },
+    literalChar := { color := nord14, weight := .regular, style := .normal, face := .mono },
+    comment := { color := nord3, weight := .regular, style := .normal, face := .mono },
+    commentDelim := { color := nord3, weight := .regular, style := .normal, face := .mono }
   }
   surfaceColor := nord5
   tocBackground := nord5
@@ -561,12 +621,14 @@ the spec's documented hue roles:
   {lit}`Prop`, {lit}`Sort u`) and {lit}`moduleName` (namespace paths in {lit}`import` lines).
 - Green ("Functions, Methods, Inherited Classes"): {lit}`const` — Lean's named-constant
   references are largely function and definition names.
-- Yellow ("Strings, Text Content"): {lit}`literalString`.
-- Orange ("Numbers, Constants, Booleans"): {lit}`levelConst` (universe numerals) and the
-  boolean {lit}`Bool.true` / {lit}`Bool.false` (surfaced through {lit}`extraCss` for now;
-  integer literals join once SubVerso gains a {lit}`literal.number` field).
+- Yellow ("Strings, Text Content"): {lit}`literalString` and {lit}`literalChar` (the
+  Dracula spec does not give characters a separate slot).
+- Orange ("Numbers, Constants, Booleans"): {lit}`literalNumber`, {lit}`levelConst` (universe
+  numerals), and the boolean {lit}`Bool.true` / {lit}`Bool.false` (still surfaced through
+  {lit}`extraCss` until SubVerso classifies booleans).
 - Red ("Errors, Warnings, Deletions"): {lit}`errorColor` / {lit}`errorIndicatorColor`.
-- Comment ("Comments and disabled code"): {lit}`docComment`.
+- Comment ("Comments and disabled code"): {lit}`docComment` plus the new {lit}`comment` /
+  {lit}`commentDelim` fields for ordinary {lit}`--` and {lit}`/- … -/` comments.
 - Foreground: bound variables ({lit}`var`, {lit}`levelVar`), the built-in delimiter family
   ({lit}`delim` — {lit}`:=`, {lit}`=>`, {lit}`:`, {lit}`|`, …), and the {lit}`bracket` /
   {lit}`separator` punctuation buckets, since the Dracula spec does not assign a syntax
@@ -632,6 +694,16 @@ public def ManualTheme.dracula : ManualTheme :=
     -- foreground, matching Dracula's convention of leaving brackets and item separators
     -- unstyled.
     operator := { color := pink, weight := .regular, style := .normal, face := .mono },
+    -- Numbers → Orange ("Numbers, Constants, Booleans"). Chars share Yellow with strings
+    -- (Dracula does not give characters a distinct slot). Comments and their delimiters →
+    -- Dracula's Comment color (a soft steel-blue), no italic — italic is reserved for
+    -- doc comments in our default rendering. `commentDelim` is spelled out explicitly: the
+    -- `comment := comment` cascade was frozen at `CodeTheme.ink`'s black `codeColor` when
+    -- this struct was constructed, so a bare `comment` override wouldn't reach it.
+    literalNumber := { color := orange, weight := .regular, style := .normal, face := .mono },
+    literalChar := { color := yellow, weight := .regular, style := .normal, face := .mono },
+    comment := { color := comment, weight := .regular, style := .normal, face := .mono },
+    commentDelim := { color := comment, weight := .regular, style := .normal, face := .mono },
     -- The Dracula spec gives Orange to "numbers, constants, booleans". Verso doesn't yet have
     -- a numeric-literal kind from the highlighter, but the `const` tokens for `Bool.true` and
     -- `Bool.false` carry a `data-binding` attribute the highlighter emits, so a CSS attribute
@@ -700,11 +772,20 @@ public def ManualTheme.alucard : ManualTheme where
     levelVar := { color := foreground, weight := .regular, style := .italic, face := .mono },
     levelConst := { color := orange, weight := .regular, style := .normal, face := .mono },
     moduleName := { color := cyan, weight := .regular, style := .normal, face := .mono },
-    -- Symbolic operators → Pink; `delim`, `bracket`, and `separator` stay on body
-    -- foreground. See `ManualTheme.dracula` for the rationale (SubVerso's `.delim` is too
-    -- coarse to single out binding markers, so painting the whole bucket would also paint
-    -- every type-ascription `:`).
+    -- Symbolic operators → Pink. `delim`/`bracket`/`separator` are spelled out at the
+    -- Alucard foreground rather than relying on the cascade default: `CodeTheme.ink with`
+    -- doesn't re-evaluate the `{ color := codeColor, ... }` cascades, so without these
+    -- explicit overrides they'd stay frozen at Ink's black `codeColor`.
+    delim := { color := foreground, weight := .regular, style := .normal, face := .mono },
     operator := { color := pink, weight := .regular, style := .normal, face := .mono },
+    bracket := { color := foreground, weight := .regular, style := .normal, face := .mono },
+    separator := { color := foreground, weight := .regular, style := .normal, face := .mono },
+    -- Numbers → Orange; chars → Yellow (same as strings); comments and their delimiters →
+    -- Alucard's Comment color. Same role assignments as the dark variant.
+    literalNumber := { color := orange, weight := .regular, style := .normal, face := .mono },
+    literalChar := { color := yellow, weight := .regular, style := .normal, face := .mono },
+    comment := { color := comment, weight := .regular, style := .normal, face := .mono },
+    commentDelim := { color := comment, weight := .regular, style := .normal, face := .mono },
     -- Same boolean-orange trick as the dark variant; see the Dracula def for the rationale.
     extraCss := fun _ =>
       ".hl.lean .const[data-binding=\"const-Bool.true\"],\n" ++
@@ -752,7 +833,17 @@ public def ManualTheme.sandstoneLight : ManualTheme where
     uiOnCode := color%#8c7257,
     keyword.color := color%#a04a00,
     const.color := color%#1f6f8b,
-    «var».color := color%#3b2a17
+    «var».color := color%#3b2a17,
+    -- Spell out the punctuation, literal, and comment families at the Sandstone body
+    -- color so `CodeTheme.ink with` doesn't leave them frozen at Ink's black `codeColor`.
+    delim := { color := color%#3b2a17, weight := .regular, style := .normal, face := .mono },
+    operator := { color := color%#3b2a17, weight := .regular, style := .normal, face := .mono },
+    bracket := { color := color%#3b2a17, weight := .regular, style := .normal, face := .mono },
+    separator := { color := color%#3b2a17, weight := .regular, style := .normal, face := .mono },
+    literalNumber := { color := color%#3b2a17, weight := .regular, style := .normal, face := .mono },
+    literalChar := { color := color%#3b2a17, weight := .regular, style := .normal, face := .mono },
+    comment := { color := color%#3b2a17, weight := .regular, style := .normal, face := .mono },
+    commentDelim := { color := color%#3b2a17, weight := .regular, style := .normal, face := .mono }
   }
   surfaceColor := color%#f3e9d6
   tocBackground := color%#f3e9d6
@@ -805,7 +896,17 @@ public def ManualTheme.sandstoneDark : ManualTheme :=
     -- without a cool accent.
     keyword.color := color%#ff8c4a,
     const.color := color%#ffc266,
-    «var».color := color%#f3d5a3
+    «var».color := color%#f3d5a3,
+    -- Align punctuation, literals, and comments with the Sandstone Dark sunlit-buff body
+    -- color rather than `darkCodeBase`'s generic `#e8e8e8`.
+    delim := { color := color%#f3d5a3, weight := .regular, style := .normal, face := .mono },
+    operator := { color := color%#f3d5a3, weight := .regular, style := .normal, face := .mono },
+    bracket := { color := color%#f3d5a3, weight := .regular, style := .normal, face := .mono },
+    separator := { color := color%#f3d5a3, weight := .regular, style := .normal, face := .mono },
+    literalNumber := { color := color%#f3d5a3, weight := .regular, style := .normal, face := .mono },
+    literalChar := { color := color%#f3d5a3, weight := .regular, style := .normal, face := .mono },
+    comment := { color := color%#f3d5a3, weight := .regular, style := .normal, face := .mono },
+    commentDelim := { color := color%#f3d5a3, weight := .regular, style := .normal, face := .mono }
   }
   -- Override the generic dark-chrome accents with sandstone-tuned values so the search box
   -- border, ToC background, and link colours stay in the warm family.
@@ -848,7 +949,17 @@ public def ManualTheme.steel : ManualTheme where
     uiOnCode := color%#46566a,
     keyword.color := color%#1a5ea8,
     const.color := color%#2a6f4f,
-    «var».color := color%#0e2431
+    «var».color := color%#0e2431,
+    -- Spell out the punctuation, literal, and comment families at the Steel deep-navy body
+    -- color so `CodeTheme.ink with` doesn't leave them frozen at Ink's black `codeColor`.
+    delim := { color := color%#0e2431, weight := .regular, style := .normal, face := .mono },
+    operator := { color := color%#0e2431, weight := .regular, style := .normal, face := .mono },
+    bracket := { color := color%#0e2431, weight := .regular, style := .normal, face := .mono },
+    separator := { color := color%#0e2431, weight := .regular, style := .normal, face := .mono },
+    literalNumber := { color := color%#0e2431, weight := .regular, style := .normal, face := .mono },
+    literalChar := { color := color%#0e2431, weight := .regular, style := .normal, face := .mono },
+    comment := { color := color%#0e2431, weight := .regular, style := .normal, face := .mono },
+    commentDelim := { color := color%#0e2431, weight := .regular, style := .normal, face := .mono }
   }
   surfaceColor := color%#e3e8ee
   tocBackground := color%#e3e8ee
@@ -889,7 +1000,17 @@ public def ManualTheme.slate : ManualTheme :=
     uiOnCode := color%#7a8aa0,
     keyword.color := color%#6cb6ff,
     const.color := color%#7ad9a0,
-    «var».color := color%#dfe6ee
+    «var».color := color%#dfe6ee,
+    -- Align punctuation, literals, and comments with the Slate body color so they don't
+    -- inherit `darkCodeBase`'s generic `#e8e8e8` (close, but off-palette).
+    delim := { color := color%#dfe6ee, weight := .regular, style := .normal, face := .mono },
+    operator := { color := color%#dfe6ee, weight := .regular, style := .normal, face := .mono },
+    bracket := { color := color%#dfe6ee, weight := .regular, style := .normal, face := .mono },
+    separator := { color := color%#dfe6ee, weight := .regular, style := .normal, face := .mono },
+    literalNumber := { color := color%#dfe6ee, weight := .regular, style := .normal, face := .mono },
+    literalChar := { color := color%#dfe6ee, weight := .regular, style := .normal, face := .mono },
+    comment := { color := color%#dfe6ee, weight := .regular, style := .normal, face := .mono },
+    commentDelim := { color := color%#dfe6ee, weight := .regular, style := .normal, face := .mono }
   }
 
 /-! # Hearth — cottagecore (cream/sage light, candlelit deep-olive dark) -/
@@ -925,7 +1046,17 @@ public def ManualTheme.hearthLight : ManualTheme where
     uiOnCode := color%#7a6952,
     keyword.color := color%#2f6e58,
     const.color := color%#a04050,
-    «var».color := color%#3d2f1f
+    «var».color := color%#3d2f1f,
+    -- Spell out the punctuation, literal, and comment families at the Hearth body color so
+    -- `CodeTheme.ink with` doesn't leave them frozen at Ink's black `codeColor`.
+    delim := { color := color%#3d2f1f, weight := .regular, style := .normal, face := .mono },
+    operator := { color := color%#3d2f1f, weight := .regular, style := .normal, face := .mono },
+    bracket := { color := color%#3d2f1f, weight := .regular, style := .normal, face := .mono },
+    separator := { color := color%#3d2f1f, weight := .regular, style := .normal, face := .mono },
+    literalNumber := { color := color%#3d2f1f, weight := .regular, style := .normal, face := .mono },
+    literalChar := { color := color%#3d2f1f, weight := .regular, style := .normal, face := .mono },
+    comment := { color := color%#3d2f1f, weight := .regular, style := .normal, face := .mono },
+    commentDelim := { color := color%#3d2f1f, weight := .regular, style := .normal, face := .mono }
   }
   textFace := .serif
   structureFace := .serif
@@ -971,6 +1102,16 @@ public def ManualTheme.hearthDark : ManualTheme :=
     uiOnCode := color%#a08a64,
     keyword.color := color%#9adcb0,
     const.color := color%#f5a8b8,
-    «var».color := color%#f1e7d2
+    «var».color := color%#f1e7d2,
+    -- Align punctuation, literals, and comments with the Hearth Dark candlelit-cream body
+    -- color rather than `darkCodeBase`'s generic `#e8e8e8`.
+    delim := { color := color%#f1e7d2, weight := .regular, style := .normal, face := .mono },
+    operator := { color := color%#f1e7d2, weight := .regular, style := .normal, face := .mono },
+    bracket := { color := color%#f1e7d2, weight := .regular, style := .normal, face := .mono },
+    separator := { color := color%#f1e7d2, weight := .regular, style := .normal, face := .mono },
+    literalNumber := { color := color%#f1e7d2, weight := .regular, style := .normal, face := .mono },
+    literalChar := { color := color%#f1e7d2, weight := .regular, style := .normal, face := .mono },
+    comment := { color := color%#f1e7d2, weight := .regular, style := .normal, face := .mono },
+    commentDelim := { color := color%#f1e7d2, weight := .regular, style := .normal, face := .mono }
   }
   { base with textFace := .serif, structureFace := .serif }
diff --git a/src/verso/Verso/Code/Highlighted.lean b/src/verso/Verso/Code/Highlighted.lean
index 816b4bd07..eadd3e452 100644
--- a/src/verso/Verso/Code/Highlighted.lean
+++ b/src/verso/Verso/Code/Highlighted.lean
@@ -749,16 +749,11 @@ public def highlightingStyle : String := "
   font-family: var(--verso-code-module-name-font-family, var(--verso-code-font-family,));
 }
 
-/* The lexically-classified token kinds added by SubVerso (anon-ctor, number, char, comment,
-   wildcard) default to the unthemed `.unknown` appearance. The themeable rules above already
-   cover the semantic kinds (`.literal`, `.doc-comment`, etc.) and win when both apply (e.g.
-   `.anon-ctor` also carries `.const`; a number nested inside a literal span is still themed
-   by `.literal`). Future phases may introduce dedicated theme buckets for numbers, characters,
-   and comments. */
+/* `.anon-ctor` (anonymous-constructor brackets) and `.wildcard` (`_` holes) default to the
+   unthemed `.unknown` appearance — neither has its own theme bucket yet. `.anon-ctor` also
+   carries the `.const` class, so the themeable `.const` rule above wins for it where set.
+   Number, character, and comment kinds are themed via their own rules further down. */
 .hl.lean .anon-ctor,
-.hl.lean .number,
-.hl.lean .char,
-.hl.lean .comment,
 .hl.lean .wildcard {
   color: var(--verso-code-color,);
   font-weight: normal;
@@ -766,6 +761,38 @@ public def highlightingStyle : String := "
   font-family: var(--verso-code-font-family,);
 }
 
+.hl.lean .literal.number {
+  color: var(--verso-code-literal-number-color, var(--verso-code-literal-color, var(--verso-code-color,)));
+  font-weight: var(--verso-code-literal-number-weight, normal);
+  font-style: var(--verso-code-literal-number-style, normal);
+  font-family: var(--verso-code-literal-number-font-family, var(--verso-code-font-family,));
+}
+
+.hl.lean .literal.char {
+  color: var(--verso-code-literal-char-color, var(--verso-code-literal-string-color, var(--verso-code-literal-color, var(--verso-code-color,))));
+  font-weight: var(--verso-code-literal-char-weight, normal);
+  font-style: var(--verso-code-literal-char-style, normal);
+  font-family: var(--verso-code-literal-char-font-family, var(--verso-code-font-family,));
+}
+
+/* `.comment` covers line and block comments (their elements carry `comment line` and
+   `comment block` class pairs respectively); `.comment.delimiter` is a more specific
+   override for the `--` / `/-` / `-/` punctuation. The themeable `.doc-comment` rule above
+   wins for doc comments since SubVerso tags them with their own class entirely. */
+.hl.lean .comment {
+  color: var(--verso-code-comment-color, var(--verso-code-color,));
+  font-weight: var(--verso-code-comment-weight, normal);
+  font-style: var(--verso-code-comment-style, normal);
+  font-family: var(--verso-code-comment-font-family, var(--verso-code-font-family,));
+}
+
+.hl.lean .comment.delimiter {
+  color: var(--verso-code-comment-delim-color, var(--verso-code-comment-color, var(--verso-code-color,)));
+  font-weight: var(--verso-code-comment-delim-weight, normal);
+  font-style: var(--verso-code-comment-delim-style, normal);
+  font-family: var(--verso-code-comment-delim-font-family, var(--verso-code-font-family,));
+}
+
 /* `.delim` is the built-in syntactic delimiter family (`:=`, `=>`, `←`, `@`, `:`, `|`). The
    three punctuation buckets — `.punctuation.operator`, `.punctuation.bracket`,
    `.punctuation.separator` — are themed independently below; their CSS variables resolve
@@ -1462,7 +1489,7 @@ window.onload = () => {
       }
       return tokens;
     }
-    for (const container of document.querySelectorAll(\".hl.lean\")) {
+    function attachBindingHighlights(container) {
       container.addEventListener(\"mouseover\", (event) => {
         const c = event.target.closest(\".token\");
         if (!c || !c.dataset.binding || c.dataset.binding === \"\" || !container.contains(c)) return;
@@ -1482,6 +1509,12 @@ window.onload = () => {
         highlightedTokens = [];
       });
     }
+    // Exposed for the theme picker, which builds its code-sample preview after this script
+    // has already scanned the document.
+    window.versoAttachBindingHighlights = attachBindingHighlights;
+    for (const container of document.querySelectorAll(\".hl.lean\")) {
+      attachBindingHighlights(container);
+    }
     /* Render docstrings */
     if ('undefined' !== typeof marked) {
         for (const d of document.querySelectorAll(\"code.docstring, pre.docstring\")) {
@@ -1631,7 +1664,31 @@ window.onload = () => {
       }
 
       const tokenSelector = '.hl.lean .const.token, .hl.lean .keyword.token, .hl.lean .literal.token, .hl.lean .option.token, .hl.lean .var.token, .hl.lean .typed.token, .hl.lean .has-info, .hl.lean .tactic, .hl.lean .level-var, .hl.lean .level-const, .hl.lean .level-op, .hl.lean .sort';
-      tippy(Array.from(document.querySelectorAll(tokenSelector)).filter(el => !isInsideClosedTactic(el)), defaultTippyProps);
+      // Tippy + data-tippy-theme initialization, scoped to `root` so it can run on a DOM
+      // subtree that didn't exist at DOMContentLoaded — the picker preview is built on first
+      // popover open and needs this same wiring applied to its tokens.
+      function versoInitTippy(root) {
+        root.querySelectorAll('.hl.lean .const.token, .hl.lean .keyword.token, .hl.lean .literal.token, .hl.lean .option.token, .hl.lean .var.token, .hl.lean .typed.token, .hl.lean .level-var, .hl.lean .level-const, .hl.lean .level-op, .hl.lean .sort').forEach(element => {
+          element.setAttribute('data-tippy-theme', 'lean');
+        });
+        root.querySelectorAll('.hl.lean .has-info.warning').forEach(element => {
+          element.setAttribute('data-tippy-theme', 'warning message');
+        });
+        root.querySelectorAll('.hl.lean .has-info.information').forEach(element => {
+          element.setAttribute('data-tippy-theme', 'info message');
+        });
+        root.querySelectorAll('.hl.lean .has-info.error').forEach(element => {
+          element.setAttribute('data-tippy-theme', 'error message');
+        });
+        root.querySelectorAll('.hl.lean .tactic').forEach(element => {
+          element.setAttribute('data-tippy-theme', 'tactic');
+        });
+        tippy(Array.from(root.querySelectorAll(tokenSelector)).filter(el => !el._tippy && !isInsideClosedTactic(el)), defaultTippyProps);
+      }
+      // Exposed for the theme picker (which builds its code-sample preview after this script
+      // has already scanned the document).
+      window.versoInitTippy = versoInitTippy;
+      versoInitTippy(document);
 
       // Create/destroy token tippys when tactic checkbox toggles
       const tacticTippySelector = '.const.token, .keyword.token, .literal.token, .option.token, .var.token, .typed.token, .has-info, .level-var, .level-const, .level-op, .sort';
diff --git a/src/verso/Verso/Code/HighlightedToTex.lean b/src/verso/Verso/Code/HighlightedToTex.lean
index 32b022f2f..dc17e772b 100644
--- a/src/verso/Verso/Code/HighlightedToTex.lean
+++ b/src/verso/Verso/Code/HighlightedToTex.lean
@@ -48,17 +48,14 @@ public def highlightToken : String → Token.Kind → TeX
 | c, .operator .. => .raw s!"\\versoOperator\{{c}}"
 | c, .bracket .. => .raw s!"\\versoBracket\{{c}}"
 | c, .separator .. => .raw s!"\\versoSeparator\{{c}}"
--- The remaining lexical-ish kinds added by SubVerso (wildcard, num, char, line/block
--- comments, comment delimiter) currently route through `\versoLiteral` so PDF output keeps
--- the "default to the unknown/code appearance" semantics the HTML side gives them via its
--- lexical-default CSS rule. They are likely to gain their own theme buckets (numbers,
--- characters, comments) in a later phase.
+| c, .num .. => .raw s!"\\versoLiteralNumber\{{c}}"
+| c, .char .. => .raw s!"\\versoLiteralChar\{{c}}"
+| c, .lineComment => .raw s!"\\versoComment\{{c}}"
+| c, .blockComment => .raw s!"\\versoComment\{{c}}"
+| c, .commentDelim => .raw s!"\\versoCommentDelim\{{c}}"
+-- Wildcards (`_` holes) have no dedicated theme bucket yet, so they route through
+-- `\versoLiteral` like `.unknown` does.
 | c, .wildcard .. => .raw s!"\\versoLiteral\{{c}}"
-| c, .num .. => .raw s!"\\versoLiteral\{{c}}"
-| c, .char .. => .raw s!"\\versoLiteral\{{c}}"
-| c, .lineComment => .raw s!"\\versoLiteral\{{c}}"
-| c, .blockComment => .raw s!"\\versoLiteral\{{c}}"
-| c, .commentDelim => .raw s!"\\versoLiteral\{{c}}"
 | c, .unknown => .raw s!"\\versoLiteral\{{c}}"
 
 /--
@@ -83,7 +80,11 @@ public def texMacroFallbacks : String :=
 "\\providecommand{\\versoDelim}[1]{#1}\n" ++
 "\\providecommand{\\versoOperator}[1]{#1}\n" ++
 "\\providecommand{\\versoBracket}[1]{#1}\n" ++
-"\\providecommand{\\versoSeparator}[1]{#1}\n"
+"\\providecommand{\\versoSeparator}[1]{#1}\n" ++
+"\\providecommand{\\versoLiteralNumber}[1]{#1}\n" ++
+"\\providecommand{\\versoLiteralChar}[1]{#1}\n" ++
+"\\providecommand{\\versoComment}[1]{#1}\n" ++
+"\\providecommand{\\versoCommentDelim}[1]{#1}\n"
 
 defmethod Highlighting.Token.toVerbatimTeX (t : Highlighting.Token) (lineBreaks : Bool := false) : Verso.Output.TeX :=
   highlightToken (escapeForVerbatim t.content lineBreaks) t.kind
diff --git a/src/verso/Verso/Theme/Code.lean b/src/verso/Verso/Theme/Code.lean
index e64498f1c..1a839ebf1 100644
--- a/src/verso/Verso/Theme/Code.lean
+++ b/src/verso/Verso/Theme/Code.lean
@@ -66,14 +66,13 @@ public structure CodeTheme where
   appearance : Appearance
   /--
   An optional one- or two-sentence description shown alongside the theme in the picker. Useful
-  for noting design intent, palette family, or accessibility trade-offs (for example "Solarized
-  Light — the canonical palette, below WCAG AA on prose by design").
+  for noting design intent, palette family, or accessibility trade-offs.
   -/
   description : Option String := none
   /--
   An optional canonical reference for the theme: a URL plus link text shown next to the name
   in the picker. Points readers at an upstream homepage or specification when the theme is a
-  port (Solarized, Dracula, etc.).
+  port.
   -/
   sourceLink : Option SourceLink := none
 
@@ -115,83 +114,73 @@ public structure CodeTheme where
   /-- Token styling for variables (bound names). -/
   «var» : TokenStyle := { color := codeColor, weight := .regular, style := .italic, face := codeFace }
   /--
-  Token styling for literal tokens. Today only string literals are tagged by the
-  highlighter, so the {lit}`{name}.string` field below is where strings get their color.
-  Other literal kinds (numbers, booleans) will gain distinct tags in future SubVerso
-  releases and will read from this field unless overridden.
+  Token styling for literal tokens.
   -/
   literal : TokenStyle := { color := codeColor, weight := .regular, style := .normal, face := codeFace }
   /--
-  Token styling for string literals (CSS class {lit}`.literal.string`). Defaults to
-  {lit}`literal`; themes that want strings distinguished from other literals (e.g. Dracula's
-  yellow strings vs orange numbers) override it.
+  Token styling for string literals.
   -/
   literalString : TokenStyle := literal
   /--
-  Token styling for doc comments (CSS class {lit}`.doc-comment`), i.e. {lit}`/-- … -/`
-  documentation blocks. SubVerso does not yet tag ordinary {lit}`--` line comments or
-  {lit}`/- … -/` block comments, so this field affects only the doc-comment kind.
+  Token styling for numeric literals.
+  -/
+  literalNumber : TokenStyle := literal
+  /--
+  Token styling for character literals.
+  -/
+  literalChar : TokenStyle := literalString
+  /--
+  Token styling for docstrings.
   -/
   docComment : TokenStyle := { color := codeColor, weight := .regular, style := .italic, face := codeFace }
   /--
-  Token styling for sort formers — {lit}`Type`, {lit}`Prop`, {lit}`Sort u`. CSS class
-  {lit}`.sort`. A distinct kind from {lit}`const` because sorts are the universe-of-types
-  formers, not ordinary named constants; themes typically color them in a different family
-  (often the "keyword" or "type" palette slot).
+  Token styling for the body text of ordinary comments, both {lit}`--` line comments and
+  {lit}`/- … -/` block comments.
+  -/
+  comment : TokenStyle := { color := codeColor, weight := .regular, style := .normal, face := codeFace }
+  /--
+  Token styling for comment delimiters — the {lit}`--` opener of a line comment and the
+  {lit}`/-`/{lit}`-/` openers/closers of a block comment.
+  -/
+  commentDelim : TokenStyle := comment
+  /--
+  Token styling for sort formers: {lit}`Type`, {lit}`Prop`, {lit}`Sort`.
   -/
   sort : TokenStyle := { color := codeColor, weight := .regular, style := .normal, face := codeFace }
   /--
   Token styling for universe-level variables ({lit}`u`, {lit}`v`, … in a universe-parameter
-  context). CSS class {lit}`.level-var`. Bound-name semantics like {lit}`var`, but in the
-  level grammar.
+  context).
   -/
   levelVar : TokenStyle := { color := codeColor, weight := .regular, style := .italic, face := codeFace }
   /--
-  Token styling for universe-level numeric constants (the {lit}`3` in {lit}`Type 3`). CSS
-  class {lit}`.level-const`. A numeric literal in the level grammar.
+  Token styling for universe-level numeric constants (the {lit}`3` in {lit}`Type 3`).
   -/
   levelConst : TokenStyle := { color := codeColor, weight := .regular, style := .normal, face := codeFace }
   /--
-  Token styling for universe-level operators ({lit}`max`, {lit}`imax`, {lit}`+`). CSS class
-  {lit}`.level-op`.
+  Token styling for universe-level operators ({lit}`max`, {lit}`imax`, {lit}`+`).
   -/
   levelOp : TokenStyle := { color := codeColor, weight := .regular, style := .normal, face := codeFace }
   /--
-  Token styling for module names (an {lit}`import` target or a fully qualified namespace
-  path). CSS class {lit}`.module-name`. Distinct from {lit}`const` so themes can give
-  namespace paths a different treatment (often a quieter color).
+  Token styling for module names (e.g. an {lit}`import` target).
   -/
   moduleName : TokenStyle := { color := codeColor, weight := .regular, style := .normal, face := codeFace }
   /--
-  Token styling for built-in syntactic delimiters such as {lit}`:=`, {lit}`=>`, {lit}`←`,
-  {lit}`@`, {lit}`:`, {lit}`|`. CSS class {lit}`.delim`. Cascades from
-  {name (full := CodeTheme.codeColor)}`codeColor`/{name (full := CodeTheme.codeFace)}`codeFace`
-  by default so the unthemed look matches plain code; the three punctuation buckets below
-  ({name (full := CodeTheme.operator)}`operator`, {name (full := CodeTheme.bracket)}`bracket`,
-  {name (full := CodeTheme.separator)}`separator`) cascade from this field, so setting
-  {name (full := CodeTheme.delim)}`delim` re-colors all four at once unless one of the
-  buckets is overridden.
+  Token styling for built-in syntactic delimiters such as {lit}`:=`, {lit}`=>`, {lit}`←`, {lit}`@`,
+  {lit}`:`, {lit}`|`. CSS class {lit}`.delim`.
   -/
   delim : TokenStyle := { color := codeColor, weight := .regular, style := .normal, face := codeFace }
   /--
-  Token styling for symbolic operator atoms such as {lit}`+`, {lit}`::`, {lit}`>>=`. CSS
-  class {lit}`.punctuation.operator`. Defaults to
-  {name (full := CodeTheme.delim)}`delim` because most themes group operators with the
-  binding-marker family; themes that treat operators distinctly (Nord paints operators
-  {lit}`nord9`; Dracula leaves brackets plain but colors operators Pink) override this field.
+  Token styling for symbolic operator atoms such as {lit}`+`, {lit}`::`, {lit}`>>=`. CSS class
+  {lit}`.punctuation.operator`.
   -/
   operator : TokenStyle := delim
   /--
-  Token styling for paired delimiter atoms such as {lit}`(` {lit}`)`, {lit}`[` {lit}`]`,
-  {lit}`{` {lit}`}`, {lit}`⟨`, {lit}`⟩`. CSS class {lit}`.punctuation.bracket`. Defaults to
-  {name (full := CodeTheme.delim)}`delim`; themes that want brackets in body color while
-  operators carry a syntax-accent override this back to a foreground color.
+  Token styling for paired delimiter atoms such as {lit}`(` {lit}`)`, {lit}`[` {lit}`]`, {lit}`{`
+  {lit}`}`, {lit}`⟨`, {lit}`⟩`.
   -/
   bracket : TokenStyle := delim
   /--
-  Token styling for item-separator atoms such as {lit}`,` and {lit}`;`. CSS class
-  {lit}`.punctuation.separator`. Defaults to {name (full := CodeTheme.delim)}`delim` for the
-  same reason as {name (full := CodeTheme.bracket)}`bracket`.
+  Token styling for item-separator atoms such as {lit}`,` and {lit}`;`.
   -/
   separator : TokenStyle := delim
 
@@ -206,10 +195,7 @@ public structure CodeTheme where
   /-- The background tint applied to a token on hover (independent of severity). -/
   tokenHighlightBackground : Color
   /--
-  The background of a displayed tactic state. Defaults to
-  {name (full := CodeTheme.codeBlockBackground)}`codeBlockBackground` for fresh constructions;
-  themes that want a distinct tactic-state tint (a slight raise to differentiate it from code)
-  override it explicitly.
+  The background of a displayed tactic state.
   -/
   tacticStateBackground : Color := codeBlockBackground
   /-- The border color of a displayed tactic state. -/
@@ -334,7 +320,11 @@ private def tokenSummaries (theme : CodeTheme) : Array (String × Color) := #[
     ("var", theme.«var».color),
     ("literal", theme.literal.color),
     ("literal.string", theme.literalString.color),
+    ("literal.number", theme.literalNumber.color),
+    ("literal.char", theme.literalChar.color),
     ("doc-comment", theme.docComment.color),
+    ("comment", theme.comment.color),
+    ("comment.delimiter", theme.commentDelim.color),
     ("sort", theme.sort.color),
     ("level-var", theme.levelVar.color),
     ("level-const", theme.levelConst.color),
@@ -463,7 +453,11 @@ public def cssVariables (theme : CodeTheme) : String :=
     styleDecls "verso-code-var" theme.«var»,
     styleDecls "verso-code-literal" theme.literal,
     styleDecls "verso-code-literal-string" theme.literalString,
+    styleDecls "verso-code-literal-number" theme.literalNumber,
+    styleDecls "verso-code-literal-char" theme.literalChar,
     styleDecls "verso-code-doc-comment" theme.docComment,
+    styleDecls "verso-code-comment" theme.comment,
+    styleDecls "verso-code-comment-delim" theme.commentDelim,
     styleDecls "verso-code-sort" theme.sort,
     styleDecls "verso-code-level-var" theme.levelVar,
     styleDecls "verso-code-level-const" theme.levelConst,
@@ -533,7 +527,11 @@ public def texPreamble (theme : CodeTheme) : String :=
   let varColor := Color.tex theme.«var».color
   let literalColor := Color.tex theme.literal.color
   let literalStringColor := Color.tex theme.literalString.color
+  let literalNumberColor := Color.tex theme.literalNumber.color
+  let literalCharColor := Color.tex theme.literalChar.color
   let docCommentColor := Color.tex theme.docComment.color
+  let commentColor := Color.tex theme.comment.color
+  let commentDelimColor := Color.tex theme.commentDelim.color
   let sortColor := Color.tex theme.sort.color
   let levelVarColor := Color.tex theme.levelVar.color
   let levelConstColor := Color.tex theme.levelConst.color
@@ -559,7 +557,11 @@ public def texPreamble (theme : CodeTheme) : String :=
     s!"\\definecolor\{versoVarColor}\{HTML}\{{varColor}}\n",
     s!"\\definecolor\{versoLiteralColor}\{HTML}\{{literalColor}}\n",
     s!"\\definecolor\{versoLiteralStringColor}\{HTML}\{{literalStringColor}}\n",
+    s!"\\definecolor\{versoLiteralNumberColor}\{HTML}\{{literalNumberColor}}\n",
+    s!"\\definecolor\{versoLiteralCharColor}\{HTML}\{{literalCharColor}}\n",
     s!"\\definecolor\{versoDocCommentColor}\{HTML}\{{docCommentColor}}\n",
+    s!"\\definecolor\{versoCommentColor}\{HTML}\{{commentColor}}\n",
+    s!"\\definecolor\{versoCommentDelimColor}\{HTML}\{{commentDelimColor}}\n",
     s!"\\definecolor\{versoSortColor}\{HTML}\{{sortColor}}\n",
     s!"\\definecolor\{versoLevelVarColor}\{HTML}\{{levelVarColor}}\n",
     s!"\\definecolor\{versoLevelConstColor}\{HTML}\{{levelConstColor}}\n",
@@ -580,7 +582,11 @@ public def texPreamble (theme : CodeTheme) : String :=
     tokenMacro "Var" theme.«var» "versoVarColor",
     tokenMacro "Literal" theme.literal "versoLiteralColor",
     tokenMacro "LiteralString" theme.literalString "versoLiteralStringColor",
+    tokenMacro "LiteralNumber" theme.literalNumber "versoLiteralNumberColor",
+    tokenMacro "LiteralChar" theme.literalChar "versoLiteralCharColor",
     tokenMacro "DocComment" theme.docComment "versoDocCommentColor",
+    tokenMacro "Comment" theme.comment "versoCommentColor",
+    tokenMacro "CommentDelim" theme.commentDelim "versoCommentDelimColor",
     tokenMacro "Sort" theme.sort "versoSortColor",
     tokenMacro "LevelVar" theme.levelVar "versoLevelVarColor",
     tokenMacro "LevelConst" theme.levelConst "versoLevelConstColor",
diff --git a/static-web/manual/book.css b/static-web/manual/book.css
index 5898d41ae..f03407ff0 100644
--- a/static-web/manual/book.css
+++ b/static-web/manual/book.css
@@ -151,13 +151,27 @@ header {
 }
 
 .header-title-wrapper {
-    /* The title wrapper grows to fill up the header */
+    /* The title wrapper grows to fill up the header. `min-width: 0` overrides flex's
+       default min-content sizing so the wrapper can shrink narrower than the title's
+       intrinsic width — the title is then clipped (ellipsis) instead of expanding the flex
+       row and pushing the gear off screen. */
     flex: 1;
-}
-
-@media screen and (max-width: 1500px) {
-    /* Add the padding of the content when the content moves to the left */
-    padding-left: var(--verso--content-padding-x);
+    min-width: 0;
+    /* Center the inline-block title within the wrapper. The `@media (max-width: 1500px)`
+       block below switches this to `left` so the title aligns with the left-aligned content
+       column at narrow viewport widths. */
+    text-align: center;
+    /* Reserve room on the right for the absolutely-positioned gear at the right of the
+       header, plus a 1rem spacer between the title text and the gear. Without this, a
+       long title could run flush against the gear (or under it), and the spacer would
+       still be clickable as part of the title link. The reservation is:
+         search-bar-width   the absolute offset reserved for the search box
+         + 1rem             the gear's `right: calc(... + 1rem)` from theme-picker.css
+         + 2.5rem           visual width of the gear glyph button
+         + 1rem             the spacer between the title and the gear
+       The `--search-bar-width` variable shrinks to 12rem under the mobile breakpoint, so
+       this stays sensible at narrow widths automatically. */
+    padding-right: calc(var(--search-bar-width, 24rem) + 4.5rem);
 }
 
 .header-title {
@@ -165,26 +179,33 @@ header {
     color: var(--verso-text-color);
     font-size: 2rem;
     font-weight: bold;
-    display: block;
-    margin: 0 auto;
-    max-width: var(--verso-content-max-width);
+    /* `inline-block` so the clickable anchor only spans its content (the h1), not the entire
+       wrapper width — clicks in the empty area around the title text no longer follow the
+       title link. `max-width: 100%` plus `overflow: hidden` constrains the anchor to its
+       wrapper, so the `text-overflow: ellipsis` on the h1 below has a width to clip
+       against. */
+    display: inline-block;
+    max-width: 100%;
+    overflow: hidden;
+    vertical-align: middle;
 }
 
 @media screen and (max-width: 1500px) {
-    /* Move the title to the left, to align with the content that does the same. */
-    .header-title {
-        margin: 0;
-        max-width: unset;
+    /* Left-align the title to match the left-aligned content column at narrower viewports
+       (replacing the older `margin: 0; max-width: unset` rule on the `<a>`, which only made
+       sense while the title was `display: block`). */
+    .header-title-wrapper {
+        text-align: left;
+        padding-left: var(--verso--content-padding-x);
     }
 }
 
 @media screen and (max-width: 700px) {
-    /* There's no header logo on mobile, so the title just needs to reserve space for the burger */
-    .header-title {
-        margin-left: calc(
-            var(--verso-burger-width) + 1.5rem
-        ); /* There's 0.5 rem padding on the burger, and we want some space */
-        max-width: unset;
+    /* No header logo on mobile; the title wrapper reserves burger room on the left via
+       `padding-left` on itself (replacing the older `margin-left` on `.header-title`, which
+       no longer makes sense with the inline-block anchor). */
+    .header-title-wrapper {
+        padding-left: calc(var(--verso-burger-width) + 1.5rem);
     }
 }
 
@@ -192,7 +213,12 @@ header {
     margin: 0;
     font-size: inherit;
     font-weight: inherit;
-    text-wrap: nowrap;
+    /* `white-space: nowrap` + `overflow: hidden` clips a too-long title at the wrapper's
+       reserved boundary (no ellipsis — the "…" eats character space we'd rather give the
+       title itself). The previous `text-wrap: nowrap` only suppressed wrapping without
+       giving the overflow a clip strategy. */
+    white-space: nowrap;
+    overflow: hidden;
 }
 
 :root:has(header:empty) {
diff --git a/static-web/manual/theme/theme-picker.css b/static-web/manual/theme/theme-picker.css
index 33b9c2c12..bcc210536 100644
--- a/static-web/manual/theme/theme-picker.css
+++ b/static-web/manual/theme/theme-picker.css
@@ -66,7 +66,14 @@
     border-radius: 0.4rem;
     box-shadow: 0 4px 16px rgba(0, 0, 0, 0.18);
     padding: 0.75rem;
-    width: min(22rem, calc(100vw - 1rem));
+    /* Size the popup to its content — typically the longest line of the code preview —
+       rather than capping it at 22rem. The min-width keeps short content (a one-row picker
+       with no source link) from collapsing too narrow; the viewport-minus-margin max-width
+       keeps it on screen at small widths, at which point `overflow-x: auto` on
+       `#theme-picker-preview` takes over for any line still wider than the viewport. */
+    width: max-content;
+    min-width: min(22rem, calc(100vw - 1rem));
+    max-width: calc(100vw - 1rem);
     box-sizing: border-box;
     /* Two-column grid: the label column auto-sizes to the widest label across all visible rows,
        so Light/Dark/Theme dropdowns share a left edge. The rows themselves use
@@ -127,6 +134,9 @@
     padding: 0.5rem;
     font-family: var(--verso-code-font-family, monospace);
     font-size: 0.85em;
+    /* Fallback for when the dialog itself has hit its viewport-minus-margin cap and a line of
+       the code sample is still wider — at that point we can't grow further, so scroll. The
+       dialog's `width: max-content` handles the normal case by sizing to the longest line. */
     overflow-x: auto;
 }
 
diff --git a/static-web/manual/theme/theme-picker.js b/static-web/manual/theme/theme-picker.js
index 27c24d886..8580fa61a 100644
--- a/static-web/manual/theme/theme-picker.js
+++ b/static-web/manual/theme/theme-picker.js
@@ -181,6 +181,19 @@
         preview.id = "theme-picker-preview";
         preview.innerHTML = data.codeSample || "";
         dialog.appendChild(preview);
+        // Attach the same tippy popovers and binding-highlight mouseover handlers the
+        // manual's body code gets. Both initializers are exposed on `window` by the
+        // page-level highlighting script in `Highlighted.lean`; they scan a given root, so
+        // we can apply them to the preview after the page-level init has already finished
+        // scanning the document. Without these calls the preview's tokens get no `_tippy`
+        // instance and hovering a binding doesn't highlight its other occurrences.
+        if (typeof window.versoInitTippy === "function") {
+            window.versoInitTippy(preview);
+        }
+        if (typeof window.versoAttachBindingHighlights === "function") {
+            var hl = preview.querySelector(".hl.lean");
+            if (hl) window.versoAttachBindingHighlights(hl);
+        }
 
         // Per-theme metadata panel: description paragraph and source-link line. Rendered below
         // the code sample so the visual order is [chooser] [code sample] [about this theme].

From f8c3d6dd0901970fb3f3186a7bb026f5e06e86e5 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Wed, 3 Jun 2026 16:45:48 +0200
Subject: [PATCH 23/31] No Nord Light (not really a thing)

---
 doc/UsersGuide/Manuals.lean                   |  3 +-
 .../VersoManual/LicenseInfo/Licenses.lean     |  2 +-
 .../VersoManual/Theme/Defaults.lean           | 87 -------------------
 3 files changed, 2 insertions(+), 90 deletions(-)

diff --git a/doc/UsersGuide/Manuals.lean b/doc/UsersGuide/Manuals.lean
index 8e404faf9..cc8f7a05c 100644
--- a/doc/UsersGuide/Manuals.lean
+++ b/doc/UsersGuide/Manuals.lean
@@ -357,7 +357,6 @@ Hearth Dark (Verso.Theme.ManualTheme.hearthDark)
 Hearth Light (Verso.Theme.ManualTheme.hearthLight)
 Ink (Verso.Theme.ManualTheme.ink)
 Nord (Verso.Theme.ManualTheme.nord)
-Nord Light (Verso.Theme.ManualTheme.nordLight)
 Sandstone Dark (Verso.Theme.ManualTheme.sandstoneDark)
 Sandstone Light (Verso.Theme.ManualTheme.sandstoneLight)
 Slate (Verso.Theme.ManualTheme.slate)
@@ -410,7 +409,7 @@ The remaining shipped themes fall into seven families, each with a light variant
 
 : Nord
 
-  Greb's arctic, north-bluish [Nord](https://www.nordtheme.com/) palette in a Polar Night dark variant and a Snow Storm light variant.
+  Sven Greb's blue-based [Nord](https://www.nordtheme.com/) palette on its Polar Night substrate.
 
 : Sandstone
 
diff --git a/src/verso-manual/VersoManual/LicenseInfo/Licenses.lean b/src/verso-manual/VersoManual/LicenseInfo/Licenses.lean
index b0ba4c4de..130753ae7 100644
--- a/src/verso-manual/VersoManual/LicenseInfo/Licenses.lean
+++ b/src/verso-manual/VersoManual/LicenseInfo/Licenses.lean
@@ -210,7 +210,7 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 public def nord : LicenseInfo where
   identifier := "MIT"
   dependency := "Nord"
-  howUsed := some "The Nord and Nord Light themes reproduce the canonical Nord color palette by Sven Greb (Arctic Ice Studio)."
+  howUsed := some "The Nord theme reproduces the canonical Nord color palette by Sven Greb (Arctic Ice Studio)."
   link := some "https://www.nordtheme.com/"
   text := #[(some "MIT License (MIT)",
 r#"
diff --git a/src/verso-manual/VersoManual/Theme/Defaults.lean b/src/verso-manual/VersoManual/Theme/Defaults.lean
index 4a3c290fd..579951692 100644
--- a/src/verso-manual/VersoManual/Theme/Defaults.lean
+++ b/src/verso-manual/VersoManual/Theme/Defaults.lean
@@ -517,93 +517,6 @@ public def ManualTheme.nord : ManualTheme :=
       visitedLinkColor := nord15,
       licenses := #[Verso.Genre.Manual.Licenses.nord] }
 
-open Color.Palettes.Nord in
-/--
-Nord Light: Nord's bright-ambiance configuration as documented by the upstream spec —
-{lit}`nord6` as page background, {lit}`nord5` as the selection / active-line /
-text-highlight color, {lit}`nord0` as the plain syntax text color. Token accent assignments
-mirror the dark variant: the canonical Nord Frost and Aurora hues drive
-keyword/const/string/sort/etc., per Nord's documented per-color usage table.
-
-The spec does not explicitly designate a bright-ambiance color for syntax variables
-({lit}`nord4` is reserved for the dark-ambiance variable hue and is illegible on {lit}`nord6`),
-so {lit}`nord3` (Polar Night, documented "comments / indent guides") is reused with italic for
-{lit}`var`/{lit}`levelVar`/{lit}`docComment` — a pragmatic choice, not an upstream mapping.
-
-Several canonical Nord token colors — Frost {lit}`nord7`–{lit}`nord9` and Aurora
-{lit}`nord13`/{lit}`nord14` — fall below WCAG AA 4.5 against {lit}`nord6`. The per-theme
-accessibility check flags these and the suite-wide setting `warnPerThemeAccessibility` can
-downgrade them. The canonical hex values are preserved so the look matches other Nord Light
-ports.
--/
-@[manual_theme]
-public def ManualTheme.nordLight : ManualTheme where
-  toCodeTheme := {
-    CodeTheme.ink with
-    name := s!"{Color.Palettes.Nord.name} Light",
-    sourceLink := some Color.Palettes.Nord.sourceLink,
-    background := nord6,
-    codeBlockBackground := nord5,
-    textColor := nord0,
-    codeColor := nord0,
-    structureColor := nord0,
-    warningColor := nord0,
-    infoColor := nord0,
-    errorColor := nord11,
-    errorIndicatorColor := nord11,
-    warningIndicatorColor := nord13,
-    infoIndicatorColor := nord10,
-    hoverBackground := nord5,
-    hoverText := nord0,
-    hoverBorderColor := nord3,
-    hoverSeparatorColor := nord3,
-    tokenHighlightBackground := nord5,
-    tacticStateBorderColor := nord3,
-    -- Per the Nord spec, `nord5` is the documented bright-ambiance selection / text-highlight
-    -- color.
-    selectedColor := nord5,
-    highlightOnCode := nord5,
-    uiOnCode := nord3,
-    -- Canonical Nord token mapping. `var`/`levelVar`/`docComment` reuse `nord3` (the
-    -- documented "comments / indent guides" color) because the spec does not designate a
-    -- bright-ambiance variable hue and `nord4` (the dark-mode variable color) is illegible
-    -- on `nord6`.
-    keyword := { color := nord9, weight := .bold, style := .normal, face := .mono },
-    const := { color := nord8, weight := .regular, style := .normal, face := .mono },
-    «var» := { color := nord3, weight := .regular, style := .italic, face := .mono },
-    literal := { color := nord0, weight := .regular, style := .normal, face := .mono },
-    literalString := { color := nord14, weight := .regular, style := .normal, face := .mono },
-    docComment := { color := nord3, weight := .regular, style := .italic, face := .mono },
-    sort := { color := nord7, weight := .regular, style := .normal, face := .mono },
-    levelVar := { color := nord3, weight := .regular, style := .italic, face := .mono },
-    levelConst := { color := nord15, weight := .regular, style := .normal, face := .mono },
-    levelOp := { color := nord10, weight := .regular, style := .normal, face := .mono },
-    moduleName := { color := nord7, weight := .regular, style := .normal, face := .mono },
-    -- Symbolic operators → nord9 (the Nord syntax doc's "operators, support, tags" slot).
-    -- `delim`/`bracket`/`separator` ride on nord0 (the body code color). See
-    -- `ManualTheme.nord` for the rationale and the `with`-doesn't-re-evaluate-defaults note.
-    delim := { color := nord0, weight := .regular, style := .normal, face := .mono },
-    operator := { color := nord9, weight := .regular, style := .normal, face := .mono },
-    bracket := { color := nord0, weight := .regular, style := .normal, face := .mono },
-    separator := { color := nord0, weight := .regular, style := .normal, face := .mono },
-    -- Same per-spec role assignments as the dark variant: nord15 numbers, nord14 chars,
-    -- nord3 comments.
-    literalNumber := { color := nord15, weight := .regular, style := .normal, face := .mono },
-    literalChar := { color := nord14, weight := .regular, style := .normal, face := .mono },
-    comment := { color := nord3, weight := .regular, style := .normal, face := .mono },
-    commentDelim := { color := nord3, weight := .regular, style := .normal, face := .mono }
-  }
-  surfaceColor := nord5
-  tocBackground := nord5
-  borderColor := nord3
-  mutedColor := nord3
-  linkColor := nord10
-  visitedLinkColor := nord15
-  burgerVisibleShadowColor := nord6
-  burgerHiddenColor := nord0
-  burgerHiddenShadowColor := nord6
-  licenses := #[Verso.Genre.Manual.Licenses.nord]
-
 /-! # Dracula and Alucard — Dracula spec palettes -/
 
 open Color.Palettes.DraculaClassic in

From 5030575629dd8e054c627248a2852817e325e7f8 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Wed, 3 Jun 2026 17:36:17 +0200
Subject: [PATCH 24/31] doc cleanup

---
 doc/UsersGuide/Manuals.lean | 13 ++++++++-----
 doc/UsersGuide/Output.lean  |  4 ++--
 2 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/doc/UsersGuide/Manuals.lean b/doc/UsersGuide/Manuals.lean
index cc8f7a05c..d41e3289b 100644
--- a/doc/UsersGuide/Manuals.lean
+++ b/doc/UsersGuide/Manuals.lean
@@ -319,10 +319,10 @@ A theme for a manual includes a {ref "output-code-themes"}[code theme], in addit
 tag := "manual-themes-overview"
 %%%
 
-The rendered HTML for a manual includes a "gear" button in the header that opens a popover widget.
+When multiple themes are available, the rendered HTML for a manual includes a “gear” button in the header that opens a popover widget.
 This widget offers two choices:
- * A single theme, to be chose from a list and always used
- * A light theme and a dark theme, to be selected automatically based on the browser's `prefers-color-scheme` setting.
+ * a single theme, chosen by the user
+ * a light theme and a dark theme, to be selected automatically based on the browser's `prefers-color-scheme` setting.
 
 
 ## The `ManualTheme` Structure
@@ -387,7 +387,8 @@ These themes use understated formatting, relying on typographical features such
 tag := "manual-other-themes"
 %%%
 
-The remaining shipped themes fall into seven families, each with a light variant and a dark variant.
+:::paragraph
+The remaining shipped themes fall into several families, some with both light and dark variants:
 
 : Chromatic
 
@@ -423,6 +424,7 @@ The remaining shipped themes fall into seven families, each with a light variant
 
   The _Hearth_ themes have a cream-and-sage light variant and a candlelit deep-olive dark variant, and use serif fonts.
 
+:::
 
 
 ## Configuration
@@ -436,6 +438,7 @@ The following fields of {name}`RenderConfig` are relevant to themes:
 
   This field lists the available themes. By default, it contains all themes that are registered with `@[manual_theme]`.
   Authors can restrict readers to a subset of the registered themes by listing the desired themes here.
+  The default light and dark themes are implicitly considered part of the available theme set.
 
 : {name RenderConfig.defaultLightTheme}`defaultLightTheme`
 
@@ -447,7 +450,7 @@ The following fields of {name}`RenderConfig` are relevant to themes:
 
 : {name RenderConfig.defaultSingleAppearance}`defaultSingleAppearance`
 
-  When readers have configured their themes to ignore the browser's request, this is the default theme. It may be light or dark.
+  When readers have configured their themes to ignore the browser's request, this selects between the default light theme or the default dark theme as the single default.
 
 
 ## Accessibility Checking
diff --git a/doc/UsersGuide/Output.lean b/doc/UsersGuide/Output.lean
index a301c954c..a7cb82a13 100644
--- a/doc/UsersGuide/Output.lean
+++ b/doc/UsersGuide/Output.lean
@@ -250,7 +250,7 @@ tag := "code-themes-accessibility"
 
 Code themes are checked for accessibility.
 These checks are by nature incomplete: they can discover the _presence_ of problems, but not their absence.
-Nonetheless, ensuring that the default theme used by a document passes these tests is a good first step towards accessbility.
+Nonetheless, ensuring that the default theme used by a document passes these tests is a good first step towards accessibility.
 
 {docstring Theme.CodeTheme.checkAccessibility}
 
@@ -280,7 +280,7 @@ The following contrasts are checked at the large text threshold (3:1):
  * The neutral UI-element color against the code-block background.
  * The tactic-state border against the tactic-state background.
 
-Images that contain text are not automatically checked, and must be checked for accessiblity in some other way.
+Images that contain text are not automatically checked, and must be checked for accessibility in some other way.
 
 ### Color Perception
 %%%

From acf3a330b31f57c2a0e36aeab1b55ae1095bfa0d Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Wed, 3 Jun 2026 17:39:12 +0200
Subject: [PATCH 25/31] more doc cleanup

---
 doc/UsersGuide/Manuals.lean | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/UsersGuide/Manuals.lean b/doc/UsersGuide/Manuals.lean
index d41e3289b..d17842b1f 100644
--- a/doc/UsersGuide/Manuals.lean
+++ b/doc/UsersGuide/Manuals.lean
@@ -401,7 +401,7 @@ The remaining shipped themes fall into several families, some with both light an
 : Solarized
 
   These themes use Schoonover's [Solarized](https://ethanschoonover.com/solarized/) palettes.
-  Note that these low-contrast themes are not particularly accessible, and thus should probably not be the default theme for a document.
+  Note that these low-contrast themes are not particularly accessible, and thus should not be used as the default theme for a document.
 
 : Dracula and Alucard
 

From 83a0e68868f2a05c977891b6d96dd9355d176601 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Wed, 3 Jun 2026 17:41:34 +0200
Subject: [PATCH 26/31] conflicts

---
 .../literate-config/lake-manifest.json        | 123 ------------------
 .../literate-multi-root/lake-manifest.json    | 123 ------------------
 2 files changed, 246 deletions(-)

diff --git a/test-projects/literate-config/lake-manifest.json b/test-projects/literate-config/lake-manifest.json
index b64ecc31b..8929157e6 100644
--- a/test-projects/literate-config/lake-manifest.json
+++ b/test-projects/literate-config/lake-manifest.json
@@ -1,125 +1,3 @@
-<<<<<<< HEAD
-{"version": "1.2.0",
- "packagesDir": ".lake/packages",
- "packages":
- [{"type": "path",
-   "scope": "",
-   "name": "verso",
-   "manifestFile": "lake-manifest.json",
-   "inherited": false,
-   "dir": "../..",
-   "configFile": "lakefile.lean"},
-  {"url": "https://github.com/leanprover/illuminate",
-   "type": "git",
-   "subDir": null,
-   "scope": "",
-   "rev": "99ada816d9929a51132d5b5dc4f43c51f16d67d8",
-   "name": "illuminate",
-   "manifestFile": "lake-manifest.json",
-   "inputRev": "main",
-   "inherited": true,
-   "configFile": "lakefile.lean"},
-  {"url": "https://github.com/leanprover-community/plausible",
-   "type": "git",
-   "subDir": null,
-   "scope": "",
-   "rev": "a456461b368b71d2accd95234832cd9c174b5437",
-   "name": "plausible",
-   "manifestFile": "lake-manifest.json",
-   "inputRev": "main",
-   "inherited": true,
-   "configFile": "lakefile.toml"},
-  {"url": "https://github.com/acmepjz/md4lean",
-   "type": "git",
-   "subDir": null,
-   "scope": "",
-   "rev": "6a3fb240133bcb7e1a066fdc784b3fdc304e3fc5",
-   "name": "MD4Lean",
-   "manifestFile": "lake-manifest.json",
-   "inputRev": "main",
-   "inherited": true,
-   "configFile": "lakefile.lean"},
-  {"url": "https://github.com/leanprover/subverso",
-   "type": "git",
-   "subDir": null,
-   "scope": "",
-   "rev": "ce893b9042128037e2d3c0158b9567fab9fae268",
-   "name": "subverso",
-   "manifestFile": "lake-manifest.json",
-   "inputRev": "main",
-   "inherited": true,
-   "configFile": "lakefile.lean"}],
- "name": "«literate-config-test»",
- "lakeDir": ".lake",
- "fixedToolchain": false}
-||||||| 891a59f2
-{
-  "version": "1.2.0",
-  "packagesDir": ".lake/packages",
-  "packages": [
-    {
-      "type": "path",
-      "scope": "",
-      "name": "verso",
-      "manifestFile": "lake-manifest.json",
-      "inherited": false,
-      "dir": "../..",
-      "configFile": "lakefile.lean"
-    },
-    {
-      "url": "https://github.com/leanprover/illuminate",
-      "type": "git",
-      "subDir": null,
-      "scope": "",
-      "rev": "99ada816d9929a51132d5b5dc4f43c51f16d67d8",
-      "name": "illuminate",
-      "manifestFile": "lake-manifest.json",
-      "inputRev": "main",
-      "inherited": true,
-      "configFile": "lakefile.lean"
-    },
-    {
-      "url": "https://github.com/leanprover-community/plausible",
-      "type": "git",
-      "subDir": null,
-      "scope": "",
-      "rev": "86210d4ad1b08b086d0bd638637a75246523dbb8",
-      "name": "plausible",
-      "manifestFile": "lake-manifest.json",
-      "inputRev": "main",
-      "inherited": true,
-      "configFile": "lakefile.toml"
-    },
-    {
-      "url": "https://github.com/acmepjz/md4lean",
-      "type": "git",
-      "subDir": null,
-      "scope": "",
-      "rev": "6a3fb240133bcb7e1a066fdc784b3fdc304e3fc5",
-      "name": "MD4Lean",
-      "manifestFile": "lake-manifest.json",
-      "inputRev": "main",
-      "inherited": true,
-      "configFile": "lakefile.lean"
-    },
-    {
-      "url": "https://github.com/leanprover/subverso",
-      "type": "git",
-      "subDir": null,
-      "scope": "",
-      "rev": "ce893b9042128037e2d3c0158b9567fab9fae268",
-      "name": "subverso",
-      "manifestFile": "lake-manifest.json",
-      "inputRev": "main",
-      "inherited": true,
-      "configFile": "lakefile.lean"
-    }
-  ],
-  "name": "«literate-config-test»",
-  "lakeDir": ".lake",
-  "fixedToolchain": false
-}
-=======
 {"version": "1.2.0",
  "packagesDir": ".lake/packages",
  "packages":
@@ -173,4 +51,3 @@
  "name": "«literate-config-test»",
  "lakeDir": ".lake",
  "fixedToolchain": false}
->>>>>>> upstream/main
diff --git a/test-projects/literate-multi-root/lake-manifest.json b/test-projects/literate-multi-root/lake-manifest.json
index a912faf83..7b3de6354 100644
--- a/test-projects/literate-multi-root/lake-manifest.json
+++ b/test-projects/literate-multi-root/lake-manifest.json
@@ -1,125 +1,3 @@
-<<<<<<< HEAD
-{"version": "1.2.0",
- "packagesDir": ".lake/packages",
- "packages":
- [{"type": "path",
-   "scope": "",
-   "name": "verso",
-   "manifestFile": "lake-manifest.json",
-   "inherited": false,
-   "dir": "../..",
-   "configFile": "lakefile.lean"},
-  {"url": "https://github.com/leanprover/illuminate",
-   "type": "git",
-   "subDir": null,
-   "scope": "",
-   "rev": "99ada816d9929a51132d5b5dc4f43c51f16d67d8",
-   "name": "illuminate",
-   "manifestFile": "lake-manifest.json",
-   "inputRev": "main",
-   "inherited": true,
-   "configFile": "lakefile.lean"},
-  {"url": "https://github.com/leanprover-community/plausible",
-   "type": "git",
-   "subDir": null,
-   "scope": "",
-   "rev": "a456461b368b71d2accd95234832cd9c174b5437",
-   "name": "plausible",
-   "manifestFile": "lake-manifest.json",
-   "inputRev": "main",
-   "inherited": true,
-   "configFile": "lakefile.toml"},
-  {"url": "https://github.com/acmepjz/md4lean",
-   "type": "git",
-   "subDir": null,
-   "scope": "",
-   "rev": "6a3fb240133bcb7e1a066fdc784b3fdc304e3fc5",
-   "name": "MD4Lean",
-   "manifestFile": "lake-manifest.json",
-   "inputRev": "main",
-   "inherited": true,
-   "configFile": "lakefile.lean"},
-  {"url": "https://github.com/leanprover/subverso",
-   "type": "git",
-   "subDir": null,
-   "scope": "",
-   "rev": "ce893b9042128037e2d3c0158b9567fab9fae268",
-   "name": "subverso",
-   "manifestFile": "lake-manifest.json",
-   "inputRev": "main",
-   "inherited": true,
-   "configFile": "lakefile.lean"}],
- "name": "«literate-multi-root-test»",
- "lakeDir": ".lake",
- "fixedToolchain": false}
-||||||| 891a59f2
-{
-  "version": "1.2.0",
-  "packagesDir": ".lake/packages",
-  "packages": [
-    {
-      "type": "path",
-      "scope": "",
-      "name": "verso",
-      "manifestFile": "lake-manifest.json",
-      "inherited": false,
-      "dir": "../..",
-      "configFile": "lakefile.lean"
-    },
-    {
-      "url": "https://github.com/leanprover/illuminate",
-      "type": "git",
-      "subDir": null,
-      "scope": "",
-      "rev": "99ada816d9929a51132d5b5dc4f43c51f16d67d8",
-      "name": "illuminate",
-      "manifestFile": "lake-manifest.json",
-      "inputRev": "main",
-      "inherited": true,
-      "configFile": "lakefile.lean"
-    },
-    {
-      "url": "https://github.com/leanprover-community/plausible",
-      "type": "git",
-      "subDir": null,
-      "scope": "",
-      "rev": "86210d4ad1b08b086d0bd638637a75246523dbb8",
-      "name": "plausible",
-      "manifestFile": "lake-manifest.json",
-      "inputRev": "main",
-      "inherited": true,
-      "configFile": "lakefile.toml"
-    },
-    {
-      "url": "https://github.com/acmepjz/md4lean",
-      "type": "git",
-      "subDir": null,
-      "scope": "",
-      "rev": "6a3fb240133bcb7e1a066fdc784b3fdc304e3fc5",
-      "name": "MD4Lean",
-      "manifestFile": "lake-manifest.json",
-      "inputRev": "main",
-      "inherited": true,
-      "configFile": "lakefile.lean"
-    },
-    {
-      "url": "https://github.com/leanprover/subverso",
-      "type": "git",
-      "subDir": null,
-      "scope": "",
-      "rev": "ce893b9042128037e2d3c0158b9567fab9fae268",
-      "name": "subverso",
-      "manifestFile": "lake-manifest.json",
-      "inputRev": "main",
-      "inherited": true,
-      "configFile": "lakefile.lean"
-    }
-  ],
-  "name": "«literate-multi-root-test»",
-  "lakeDir": ".lake",
-  "fixedToolchain": false
-}
-=======
 {"version": "1.2.0",
  "packagesDir": ".lake/packages",
  "packages":
@@ -173,4 +51,3 @@
  "name": "«literate-multi-root-test»",
  "lakeDir": ".lake",
  "fixedToolchain": false}
->>>>>>> upstream/main

From 653b5ca45614adf371e48a3b94d5f52c8ecb7b6c Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Thu, 4 Jun 2026 00:16:23 +0200
Subject: [PATCH 27/31] fix: golden test

---
 src/tests/golden/theme-css/default.expected | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/tests/golden/theme-css/default.expected b/src/tests/golden/theme-css/default.expected
index 4c9a558d7..22eb43b0f 100644
--- a/src/tests/golden/theme-css/default.expected
+++ b/src/tests/golden/theme-css/default.expected
@@ -532,7 +532,7 @@
   text-size-adjust: 100%;
 }
 
-.hl.lean .tactic:has(.tactic-toggle:checked) {
+.hl.lean .tactic:has(> .tactic-toggle:checked) {
   display: inline-grid;
   grid-template-columns: 1fr;
 }
@@ -551,7 +551,10 @@
 }
 
 @media (hover: hover) {
-  .hl.lean .tactic:has(.tactic-toggle:not(:checked)) > label:hover {
+  /* Highlight a region on hover only when its own toggle is unchecked, and only the innermost
+     hovered region: `label:hover` bubbles to ancestor labels, so suppress the highlight on a region
+     whose label contains a more deeply nested hovered tactic label. */
+  .hl.lean .tactic:has(> .tactic-toggle:not(:checked)) > label:hover:not(:has(.tactic > label:hover)) {
     background-color: var(--verso-token-highlight-background-color, #eeeeee);
   }
 }

From fa17b44a0bc3ab51bd65b50e319cbbaf66b0602a Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Thu, 4 Jun 2026 05:49:15 +0200
Subject: [PATCH 28/31] fix: escape TeX % outside verbatim

---
 src/verso/Verso/Doc/TeX.lean | 56 +++++++++++++++++++++++++++++-------
 1 file changed, 45 insertions(+), 11 deletions(-)

diff --git a/src/verso/Verso/Doc/TeX.lean b/src/verso/Verso/Doc/TeX.lean
index fe0c0af13..b8b5c13da 100644
--- a/src/verso/Verso/Doc/TeX.lean
+++ b/src/verso/Verso/Doc/TeX.lean
@@ -10,6 +10,8 @@ import Verso.Method
 public import Verso.Output.TeX
 public import Verso.BuildLog
 
+set_option doc.verso true
+
 namespace Verso.Doc.TeX
 
 open Verso (Severity SourceSpan MonadBuildLog Logger reportError reportWarning)
@@ -23,7 +25,7 @@ public structure Options (g : Genre) where
 public structure TeXContext where
   /--
   True if we are currently rendering TeX in a fragile environment
-  (specifically, one which cannot accommodate `\Verb`)
+  (specifically, one which cannot accommodate {lit}`\Verb`)
   -/
   inFragile : Bool := false
 
@@ -110,9 +112,9 @@ def replaceChars (s : String) (replace : Char → Option String) : String :=
   loop "" 0
 
 /--
-Escapes a single character in an appropriate way for uses of `\Verb` and
-`\begin{Verbatim}...\end{Verbatim}` (from package `fancyvrb`) with
-command characters `\`, `{`, and `}`.
+Escapes a single character in an appropriate way for uses of {lit}`\Verb` and
+`\begin{Verbatim}...\end{Verbatim}` (from package {lit}`fancyvrb`) with
+command characters {lit}`\`, {lit}`{`, and {lit}`}`.
 -/
 private def escapeCharForVerbatim (c : Char) : Option String :=
   match c with
@@ -123,6 +125,26 @@ private def escapeCharForVerbatim (c : Char) : Option String :=
   | '#' => some "\\symbol{35}" -- FIXME: this is really just a test
   | _ => none
 
+/--
+Escapes a string for use as the argument of {lit}`\texttt{…}` in a fragile environment (a
+section heading, a {lit}`\href` link text — places where {lit}`\Verb` is not allowed). All
+ten TeX special characters need replacement: {lit}`\`, {lit}`{`, {lit}`}`,
+{lit}`%`, {lit}`#`, {lit}`$`, {lit}`&`, {lit}`_`, {lit}`^`, and {lit}`~`.
+-/
+private def escapeForTexttt (s : String) : String :=
+  replaceChars s fun
+    | '\\' => some "\\textbackslash{}"
+    | '{' => some "\\{"
+    | '}' => some "\\}"
+    | '%' => some "\\%"
+    | '#' => some "\\#"
+    | '$' => some "\\$"
+    | '&' => some "\\&"
+    | '_' => some "\\_"
+    | '^' => some "\\textasciicircum{}"
+    | '~' => some "\\textasciitilde{}"
+    | _ => none
+
 /--
 Tracks the previous character class for inserting line break opportunities.
 -/
@@ -137,12 +159,12 @@ private inductive PrevChar
   | other
 
 /--
-Escapes a string in an appropriate way for uses of `\Verb` and
-`\begin{Verbatim}...\end{Verbatim}` (from package `fancyvrb`) with
-command characters `\`, `{`, and `}`.
+Escapes a string in an appropriate way for uses of {lit}`\Verb` and
+{lit}`\begin{Verbatim}...\end{Verbatim}` (from package {lit}`fancyvrb`) with command characters {lit}`\`, {lit}`{`, and
+{lit}`}`.
 
-When `lineBreaks` is true, inserts line break opportunities:
-- After `.`: insert `\allowbreak{}` (no hyphen on break)
+When {lit}`lineBreaks` is true, inserts line break opportunities:
+- After {lit}`.`: insert {lit}`\allowbreak{}` (no hyphen on break)
 - On lowercase→uppercase transition: insert `\-` (soft hyphen)
 - On digit→letter transition: insert `\-` (soft hyphen)
 -/
@@ -176,7 +198,10 @@ verbatim-like environment depending on whether we're in a fragile environment.
 -/
 public def verbatimInline [Monad m] [GenreTeX g m] (t : TeX) : TeXT g m Verso.Output.TeX := do
   if (← texContext).inFragile then
-    pure (.seq #[.raw "\\texttt{", t, .raw "}"]) -- TODO: better escaping for texttt
+    -- Callers pre-escape `t` for their target environment. For plain code spans the
+    -- branching is in the `.code` arm of `Inline.toTeX`, which picks `escapeForTexttt` for
+    -- this branch and `escapeForVerbatim` for the `\LeanVerb` branch below.
+    pure (.seq #[.raw "\\texttt{", t, .raw "}"])
   else
     pure (.seq #[.raw "\\LeanVerb|", t, .raw "|"])
 
@@ -199,7 +224,16 @@ public partial defmethod Inline.toTeX : Inline g → TeXT g m TeX
     pure \TeX{\emph{\Lean{← content.mapM toTeX}}}
   | .bold content => do
     pure \TeX{\textbf{\Lean{← content.mapM toTeX}}}
-  | .code str => verbatimInline (.raw <| escapeForVerbatim str)
+  | .code str => do
+    -- In a fragile environment (section heading, `\href` link text — anywhere `\Verb` is
+    -- disallowed) we wrap with `\texttt{…}` instead, which means the body has to be escaped
+    -- against all ten TeX special characters rather than just the four that matter inside
+    -- `\Verb|…|`. The verbatim escape leaves `%` literal, which would start a TeX comment
+    -- that eats the rest of the heading.
+    if (← texContext).inFragile then
+      pure <| .seq #[.raw "\\texttt{", .raw (escapeForTexttt str), .raw "}"]
+    else
+      verbatimInline (.raw <| escapeForVerbatim str)
   | .math .inline str => pure <| .raw s!"${str}$"
   | .math .display str => pure <| .raw s!"\\[{str}\\]"
   | .concat inlines => inlines.mapM toTeX

From ff6ab1ce5d185bf85786b4be4384a3c686f60713 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Thu, 4 Jun 2026 07:43:59 +0200
Subject: [PATCH 29/31] chore: test cleanup

---
 src/tests/Tests/ColorMath.lean        | 55 ++++++++++++++++++++++-----
 src/tests/Tests/Font.lean             |  2 +-
 src/tests/Tests/HighlightedToTeX.lean |  2 +-
 3 files changed, 47 insertions(+), 12 deletions(-)

diff --git a/src/tests/Tests/ColorMath.lean b/src/tests/Tests/ColorMath.lean
index 1170228ef..a68904b4b 100644
--- a/src/tests/Tests/ColorMath.lean
+++ b/src/tests/Tests/ColorMath.lean
@@ -19,12 +19,12 @@ open Verso Verso.Theme Verso.Theme.Color
 meta section
 
 /-- Approximate float equality to a tolerance. -/
-def approx (tol a b : Float) : Bool := (a - b).abs ≤ tol
+def approx (ε a b : Float) : Bool := (a - b).abs ≤ ε
 
-/-- Whether two colors' channels are all within `tol` of each other. -/
-def channelsClose (tol : Nat) : Color → Color → Bool
+/-- Whether two colors' channels are all within `ε` of each other. -/
+def channelsClose (ε : Nat) : Color → Color → Bool
   | .rgba r1 g1 b1 a1, .rgba r2 g2 b2 a2 =>
-    let near (x y : UInt8) : Bool := (Int.ofNat x.toNat - Int.ofNat y.toNat).natAbs ≤ tol
+    let near (x y : UInt8) : Bool := (Int.ofNat x.toNat - Int.ofNat y.toNat).natAbs ≤ ε
     near r1 r2 && near g1 g2 && near b1 b2 && near a1 a2
 
 instance : Arbitrary CVD where
@@ -53,7 +53,7 @@ instance : Shrinkable CVD where
 -- Red and green, far apart normally, collapse closer together under deuteranopia.
 /-- info: true -/
 #guard_msgs in
-#eval decide (deltaE (dichromacy .deuteranopia .red) (dichromacy .deuteranopia .green) < deltaE .red .green)
+#eval deltaE (dichromacy .deuteranopia .red) (dichromacy .deuteranopia .green) < deltaE .red .green
 
 /-! ## Property tests -/
 
@@ -132,6 +132,39 @@ def testContrastIgnoresAlpha := testProp <| ∀ (c1 c2 : Color),
 def testDeltaEIgnoresAlpha := testProp <| ∀ (c1 c2 : Color),
   deltaE c1 c2 == deltaE («opaque» c1) («opaque» c2)
 
+/--
+Deuteranopia collapses pure red and pure green toward each other: the simulated ΔE between
+{lit}`(r, 0, 0)` and {lit}`(0, g, 0)` never exceeds the original ΔE (within a small numerical
+tolerance for sRGB round-trip and 8-bit rounding).
+
+`≤` rather than strict `<` because the degenerate `r = g = 0` case has both colors equal to
+black and both ΔEs equal to zero. The strict inequality is exercised by the targeted
+spot-check {Lean.Doc.name}`testDeuteranopiaRedGreenSpotCheck` below, which uses pure-saturated
+red and green so the collapse is unambiguous.
+-/
+def testDeuteranopiaCollapsesRedGreen := testProp <| ∀ (r g : UInt8),
+  let red : Color := .rgba r 0 0 255
+  let green : Color := .rgba 0 g 0 255
+  let simRed := dichromacy .deuteranopia red
+  let simGreen := dichromacy .deuteranopia green
+  -- A tiny tolerance absorbs sRGB encode-decode round-trip plus 8-bit rounding noise on the
+  -- ΔE pipeline. Without it the inequality can flip by ~1e-3 at boundary inputs.
+  deltaE simRed simGreen ≤ deltaE red green + 0.001
+
+/--
+Spot check: pure saturated red and pure saturated green are far apart normally but collapse
+much closer together under deuteranopia. Asserts the simulated ΔE drops to less than half the
+unsimulated one — well outside any quantization noise band, so the directionality of the
+collapse is what the test actually exercises (where the bounded-form property
+{Lean.Doc.name}`testDeuteranopiaCollapsesRedGreen` only asserts non-increase).
+-/
+def testDeuteranopiaRedGreenSpotCheck := testProp <|
+  let red : Color := .rgba 255 0 0 255
+  let green : Color := .rgba 0 255 0 255
+  let simRed := dichromacy .deuteranopia red
+  let simGreen := dichromacy .deuteranopia green
+  deltaE simRed simGreen < deltaE red green / 2
+
 open Lean (Name)
 
 def colorMathTests : List (Name × (Σ p, IO <| TestResult p)) := [
@@ -148,6 +181,8 @@ def colorMathTests : List (Name × (Σ p, IO <| TestResult p)) := [
   (`testLuminanceIgnoresAlpha, ⟨_, testLuminanceIgnoresAlpha⟩),
   (`testContrastIgnoresAlpha, ⟨_, testContrastIgnoresAlpha⟩),
   (`testDeltaEIgnoresAlpha, ⟨_, testDeltaEIgnoresAlpha⟩),
+  (`testDeuteranopiaCollapsesRedGreen, ⟨_, testDeuteranopiaCollapsesRedGreen⟩),
+  (`testDeuteranopiaRedGreenSpotCheck, ⟨_, testDeuteranopiaRedGreenSpotCheck⟩),
 ]
 
 public def runColorMathTests : IO Nat := do
@@ -228,7 +263,7 @@ def cvdReferenceVectors : List (Color × Color × Color × Color) := [
 private def chanMaxDiff : Color → Color → Nat
   | .rgba r1 g1 b1 _, .rgba r2 g2 b2 _ =>
     let d (x y : UInt8) : Nat := (Int.ofNat x.toNat - Int.ofNat y.toNat).natAbs
-    Nat.max (d r1 r2) (Nat.max (d g1 g2) (d b1 b2))
+    max (d r1 r2) <| max (d g1 g2) (d b1 b2)
 
 /--
 The greatest per-channel deviation of `dichromacy` from the DaltonLens reference, over all vectors
@@ -237,9 +272,9 @@ explains) fails the test.
 -/
 def cvdReferenceMaxDeviation : Nat :=
   cvdReferenceVectors.foldl (init := 0) fun acc (c, p, de, t) =>
-    Nat.max acc <|
-      Nat.max (chanMaxDiff (dichromacy .protanopia c) p) <|
-        Nat.max (chanMaxDiff (dichromacy .deuteranopia c) de) (chanMaxDiff (dichromacy .tritanopia c) t)
+    max acc <|
+      max (chanMaxDiff (dichromacy .protanopia c) p) <|
+        max (chanMaxDiff (dichromacy .deuteranopia c) de) (chanMaxDiff (dichromacy .tritanopia c) t)
 
 -- `dichromacy` matches the DaltonLens reference across all 50 vectors and all three deficiencies. The
 -- largest per-channel deviation is 7, for one tritanopia color (`rgba 81 61 202`) that sits near the
@@ -312,4 +347,4 @@ def sharmaMaxDeviation : Float :=
 -- hue-rotation and near-zero-chroma cases).
 /-- info: true -/
 #guard_msgs in
-#eval decide (sharmaMaxDeviation < 0.0001)
+#eval sharmaMaxDeviation < 0.0001
diff --git a/src/tests/Tests/Font.lean b/src/tests/Tests/Font.lean
index 4673c1068..8fbe66e1d 100644
--- a/src/tests/Tests/Font.lean
+++ b/src/tests/Tests/Font.lean
@@ -21,7 +21,7 @@ define_font_face katexMono where
   file := "../../../vendored-js/katex/fonts/KaTeX_Typewriter-Regular.woff2"
 
 /-- info: true -/
-#guard_msgs in #eval decide (katexMono.bytes.size > 1000)
+#guard_msgs in #eval katexMono.bytes.size > 1000
 /-- info: Verso.FontFormat.woff2 -/
 #guard_msgs in #eval katexMono.format
 /-- info: Verso.FontStyle.normal -/
diff --git a/src/tests/Tests/HighlightedToTeX.lean b/src/tests/Tests/HighlightedToTeX.lean
index 9d29bb1c1..a526d34eb 100644
--- a/src/tests/Tests/HighlightedToTeX.lean
+++ b/src/tests/Tests/HighlightedToTeX.lean
@@ -45,7 +45,7 @@ info: "\\providecommand{\\versoKeyword}[1]{\\textbf{#1}}\n\\providecommand{\\ver
 /-! The default code theme emits `\definecolor` blocks for its token and severity colors and
 redefines each `\verso…` macro to apply the resolved color, weight, and style. -/
 
-private def hasSub (s sub : String) : Bool := (s.splitOn sub).length > 1
+private def hasSub (s sub : String) : Bool := s.any sub
 
 /-- info: true -/
 #guard_msgs in

From 9ec8b4029939842ee7b257560bcf38565dcd5fd3 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Thu, 4 Jun 2026 13:28:55 +0200
Subject: [PATCH 30/31] docs fixes

---
 src/verso-manual/VersoManual.lean       | 11 +++-
 src/verso-manual/VersoManual/Theme.lean | 59 ++++++++++++++++++-
 src/verso/Verso/Theme/Code.lean         | 75 ++++++++++++++++++++-----
 3 files changed, 128 insertions(+), 17 deletions(-)

diff --git a/src/verso-manual/VersoManual.lean b/src/verso-manual/VersoManual.lean
index 763d5d467..6db4623dd 100644
--- a/src/verso-manual/VersoManual.lean
+++ b/src/verso-manual/VersoManual.lean
@@ -501,9 +501,18 @@ def writeThemeAssets (dir : System.FilePath) (config : RenderConfig)
       let abs := dir.join path
       if let some p := abs.parent then ensureDir p
       writeBinFile abs bytes
-  -- Theme-bundled assets (images, etc.).
+  -- Theme-bundled assets (images, etc.). Defensively skip any asset whose path is unsafe
+  -- (`..` segments, leading/trailing/double `/`, backslashes) — the validation pass logs an
+  -- `unsafeAssetPath` error for these, but build-log errors are non-fatal and the build
+  -- continues into emission, so the writer must independently refuse to honor the bad path.
+  -- Without this guard a malicious or buggy theme could clobber files outside its asset root
+  -- via a path like `../../book.css`.
   for (n, t) in themes do
     for a in t.assets do
+      unless Verso.Theme.ThemeAsset.safePath a.path do
+        Verso.reportError
+          s!"refusing to write theme asset for '{n.toString}': unsafe path '{a.path}'"
+        continue
       let path := dir / "-verso-data" / "themes" / n.toString / a.path
       if let some p := path.parent then ensureDir p
       writeBinFile path a.contents
diff --git a/src/verso-manual/VersoManual/Theme.lean b/src/verso-manual/VersoManual/Theme.lean
index 9ec1bc1a3..bfa4bb65c 100644
--- a/src/verso-manual/VersoManual/Theme.lean
+++ b/src/verso-manual/VersoManual/Theme.lean
@@ -56,7 +56,7 @@ public structure ManualTheme extends CodeTheme where
 
   /-- The color of content links in body prose. -/
   linkColor : Color
-  /-- The color of visited content links. Defaults to `linkColor`. -/
+  /-- The color of visited content links. Defaults to {name (full := ManualTheme.linkColor)}`linkColor`. -/
   visitedLinkColor : Color := linkColor
 
   /-- The text color used inside the ToC. -/
@@ -262,6 +262,51 @@ public def checkAccessibility (theme : ManualTheme) : Array Color.Issue := Id.ru
 
 end ManualTheme
 
+/-! # Font Asset Enumeration -/
+
+namespace ManualTheme
+
+/--
+The file-backed typefaces that this manual theme needs to emit as font assets.
+
+This starts with the code faces from {name}`CodeTheme.fileTypefaces`, then adds {name}`textFace` and
+{name}`structureFace`, which the manual chrome reads from CSS variables emitted by
+{name}`manualCssVariables`. Built-in typefaces are omitted; only
+{name (full := Typeface.files)}`files` values need copied font bytes and {lit}`@font-face` rules.
+-/
+public def fileTypefaces (theme : ManualTheme) : Array Verso.Typeface :=
+  let inherited := theme.toCodeTheme.fileTypefaces
+  let extras := #[theme.textFace, theme.structureFace].filter fun
+    | .files _ _ => true
+    | _ => false
+  inherited ++ extras
+
+/--
+Output-relative paths and bytes of every font file the manual theme uses, including the
+chrome's {name}`textFace` and {name}`structureFace`. Same naming scheme as
+{name}`CodeTheme.fontAssets`.
+-/
+public def fontAssets (theme : ManualTheme) (assetRoot : String) :
+    Array (String × ByteArray × Verso.FontFace × String) := Id.run do
+  let mut out := #[]
+  for (tf, ti) in theme.fileTypefaces.zipIdx do
+    if let .files family faces := tf then
+      let slug := Verso.Theme.CodeTheme.slugFamily family
+      for (face, i) in faces.zipIdx do
+        let path := s!"{assetRoot}/fonts/{slug}-{ti}-{i}.{face.format.ext}"
+        out := out.push (path, face.bytes, face, family)
+  return out
+
+/--
+The {lit}`@font-face` rules for every {name (full := Typeface.files)}`files`
+typeface the manual theme uses, including the chrome faces. Same content shape as
+{name}`CodeTheme.fontFaceRules`.
+-/
+public def fontFaceRules (theme : ManualTheme) (assetRoot : String) : String :=
+  Verso.Theme.CodeTheme.formatFontFaceRules (theme.fontAssets assetRoot)
+
+end ManualTheme
+
 /-! # Theme-set validation -/
 
 namespace ManualThemeTable
@@ -292,6 +337,11 @@ public inductive ValidationError where
   `..`, or has no letter.
   -/
   | unsafeName (name : Lean.Name)
+  /--
+  The theme {lit}`theme` includes a {name}`Verso.Theme.ThemeAsset` whose {lit}`path` would escape the
+  theme's asset directory ({lit}`-verso-data/themes/<name>/`).
+  -/
+  | unsafeAssetPath (theme : Lean.Name) (path : String)
   /-- The set of avaialable themes named a theme that is not registered with {attr}`@[manual_theme]`. -/
   | unknownAvailable (name : Lean.Name)
   /-- The default light theme is not a registered manual theme. -/
@@ -308,6 +358,8 @@ deriving Inhabited, Repr
 public def ValidationError.format : ValidationError → String
   | .unsafeName n =>
     s!"theme registration name '{n}' is not safe for a URL path segment; only [A-Za-z0-9._-] are allowed, '..' is rejected, and at least one letter is required"
+  | .unsafeAssetPath t p =>
+    s!"theme '{t}' includes an asset whose path '{p}' would escape its asset directory (-verso-data/themes/{t}/); paths must be relative, contain no '..' or '.' segments, no backslash, and no leading/trailing/double '/'"
   | .unknownAvailable n =>
     s!"availableThemes lists '{n}', which is not a registered @[manual_theme]"
   | .unknownDefaultLight n =>
@@ -328,9 +380,12 @@ public def validate (table : ManualThemeTable)
     (defaultLight defaultDark : Name)
     (available : Option NameSet) : Array ValidationError := Id.run do
   let mut errs := #[]
-  for (n, _) in table.themes.toList do
+  for (n, t) in table.themes.toList do
     unless safeNameString n.toString do
       errs := errs.push (.unsafeName n)
+    for asset in t.assets do
+      unless Verso.Theme.ThemeAsset.safePath asset.path do
+        errs := errs.push (.unsafeAssetPath n asset.path)
   if let some xs := available then
     for n in xs do
       unless (table.find? n).isSome do
diff --git a/src/verso/Verso/Theme/Code.lean b/src/verso/Verso/Theme/Code.lean
index 1a839ebf1..ffe0ae332 100644
--- a/src/verso/Verso/Theme/Code.lean
+++ b/src/verso/Verso/Theme/Code.lean
@@ -47,6 +47,23 @@ public structure ThemeAsset where
   /-- The asset bytes, embedded at compile time. -/
   contents : ByteArray
 
+/--
+Whether a {Lean.Doc.name (full := ThemeAsset.path)}`ThemeAsset.path` is safe to join under the
+theme's asset directory ({lit}`-verso-data/themes/<name>/`) without escaping it. Required so a
+theme can't ship an asset whose path contains {lit}`..` segments or starts with {lit}`/` and
+silently clobber site files outside its own root.
+
+A path is safe iff: it is non-empty; contains no backslash; and every {lit}`/`-separated segment
+is non-empty (rejects leading/trailing/double slashes) and is neither {lit}`.` nor {lit}`..`.
+-/
+public def ThemeAsset.safePath (p : String) : Bool := Id.run do
+  if p.isEmpty then return false
+  if p.contains '\\' then return false
+  for segment in p.splitOn "/" do
+    if segment.isEmpty then return false
+    if segment == "." || segment == ".." then return false
+  return true
+
 /--
 A typed code theme. Defaults reproduce today's hardcoded chrome, so a default-constructed theme is
 visually unchanged from the pre-theming look.
@@ -606,13 +623,30 @@ end CodeTheme
 namespace CodeTheme
 
 /--
-Every {Lean.Doc.name}`Typeface` referenced by a theme. Built-in
-{Lean.Doc.name (full := Typeface.sans)}`sans`/{Lean.Doc.name (full := Typeface.serif)}`serif`/{Lean.Doc.name (full := Typeface.mono)}`mono`
-are skipped: only {Lean.Doc.name (full := Typeface.files)}`files` typefaces contribute font assets.
+The file-backed typefaces that this code theme needs to emit as font assets.
+
+{Lean.Doc.name}`cssVariables` writes a {lit}`font-family` value for each code-face field. When one
+of those fields uses {Lean.Doc.name (full := Typeface.files)}`files`, the generated stylesheet also
+needs matching {lit}`@font-face` rules and copied font bytes. This function therefore checks every
+code-face field that can appear in CSS variables and keeps only {lit}`files` values.
+
+Built-in {Lean.Doc.name (full := Typeface.sans)}`sans`,
+{Lean.Doc.name (full := Typeface.serif)}`serif`, and
+{Lean.Doc.name (full := Typeface.mono)}`mono` typefaces are omitted because they resolve to system
+fonts. Later asset generation deduplicates repeated typefaces, so the same file-backed family may
+safely appear in multiple fields.
 -/
 public def fileTypefaces (theme : CodeTheme) : Array Typeface :=
-  let faces := #[theme.codeFace, theme.const.face, theme.keyword.face, theme.«var».face,
-    theme.delim.face, theme.operator.face, theme.bracket.face, theme.separator.face]
+  let faces := #[
+    theme.codeFace,
+    theme.const.face, theme.keyword.face, theme.«var».face,
+    theme.literal.face, theme.literalString.face,
+    theme.literalNumber.face, theme.literalChar.face,
+    theme.docComment.face, theme.comment.face, theme.commentDelim.face,
+    theme.sort.face, theme.levelVar.face, theme.levelConst.face,
+    theme.levelOp.face, theme.moduleName.face,
+    theme.delim.face, theme.operator.face, theme.bracket.face, theme.separator.face
+  ]
   faces.filter fun
     | .files _ _ => true
     | _ => false
@@ -666,28 +700,41 @@ public def fontAssets (theme : CodeTheme) (assetRoot : String) :
         out := out.push (path, face.bytes, face, family)
   return out
 
-private def weightDecl : FaceWeights → String
+/-- The CSS {lit}`font-weight` value for a face — either a single number for a fixed-weight
+face or a {lit}`<lo> <hi>` range for a variable face. -/
+public def faceWeightDecl : FaceWeights → String
   | .fixed w => toString w.val
   | .variable lo hi _ => s!"{lo.val} {hi.val}"
 
-private def styleString : FontStyle → String
+/-- The CSS {lit}`font-style` value for a face: {lit}`normal` or {lit}`italic`. -/
+public def faceStyleDecl : FontStyle → String
   | .normal => "normal"
   | .italic => "italic"
 
 /--
-The {lit}`@font-face` rules for every {Lean.Doc.name (full := Typeface.files)}`files`
-typeface the theme uses. The {lit}`url()` paths are relative, so the rules resolve from whatever
-stylesheet they end up in (in the manual genre, {lit}`verso-themes.css` at the site root).
+Renders an {lit}`@font-face` block per entry in an asset list (as returned by
+{Lean.Doc.name (full := CodeTheme.fontAssets)}`fontAssets`). Factored out so the manual genre can
+build {lit}`verso-themes.css` rules from its own asset enumeration (which also covers chrome
+{lit}`textFace` / {lit}`structureFace`) without reimplementing the formatter.
 -/
-public def fontFaceRules (theme : CodeTheme) (assetRoot : String) : String := Id.run do
+public def formatFontFaceRules (assets : Array (String × ByteArray × FontFace × String)) :
+    String := Id.run do
   let mut out := ""
-  for (path, _bytes, face, family) in theme.fontAssets assetRoot do
+  for (path, _bytes, face, family) in assets do
     out := out ++ s!"@font-face \{\n"
     out := out ++ s!"  font-family: {cssQuote family};\n"
-    out := out ++ s!"  font-weight: {weightDecl face.weights};\n"
-    out := out ++ s!"  font-style: {styleString face.style};\n"
+    out := out ++ s!"  font-weight: {faceWeightDecl face.weights};\n"
+    out := out ++ s!"  font-style: {faceStyleDecl face.style};\n"
     out := out ++ s!"  src: url({cssQuote path}) format({cssQuote face.format.css});\n"
     out := out ++ "}\n"
   return out
 
+/--
+The {lit}`@font-face` rules for every {Lean.Doc.name (full := Typeface.files)}`files`
+typeface the theme uses. The {lit}`url()` paths are relative, so the rules resolve from whatever
+stylesheet they end up in (in the manual genre, {lit}`verso-themes.css` at the site root).
+-/
+public def fontFaceRules (theme : CodeTheme) (assetRoot : String) : String :=
+  formatFontFaceRules (theme.fontAssets assetRoot)
+
 end CodeTheme

From ac0d25ad2180fba43af5f3d731fd4de2a5aac6f8 Mon Sep 17 00:00:00 2001
From: David Thrane Christiansen <david@davidchristiansen.dk>
Date: Fri, 5 Jun 2026 11:36:16 +0200
Subject: [PATCH 31/31] Rework theme picker

It now has two levels: light/dark/follow; then specific theme
selection.
---
 .../theme-picker/test_theme_picker.py         | 315 ++++++++++--------
 doc/UsersGuide/Manuals.lean                   |  12 +-
 src/tests/ThemeTestMain.lean                  |  32 +-
 src/verso-manual/VersoManual.lean             |  64 +---
 src/verso-manual/VersoManual/Theme/Emit.lean  | 115 +++++--
 static-web/manual/theme/theme-picker.css      |  86 +++--
 static-web/manual/theme/theme-picker.js       | 278 +++++++++-------
 7 files changed, 532 insertions(+), 370 deletions(-)

diff --git a/browser-tests/theme-picker/test_theme_picker.py b/browser-tests/theme-picker/test_theme_picker.py
index 922d800ab..f10c0a38b 100644
--- a/browser-tests/theme-picker/test_theme_picker.py
+++ b/browser-tests/theme-picker/test_theme_picker.py
@@ -5,9 +5,11 @@
   * gear placement in header-tools, left of the search box
   * popover open/close, role + aria-* attributes, Escape returns focus to the gear
   * focus trap inside the popover
-  * theme switching via dropdown sets data-verso-theme and data-verso-appearance
-  * persistence across reloads via localStorage
-  * "match system" auto-mode follows matchMedia(prefers-color-scheme), single mode does not
+  * the Appearance radios (Light / Dark / Follow system) drive data-verso-theme and
+    data-verso-appearance, and persist across reloads via localStorage
+  * "Follow system" tracks matchMedia(prefers-color-scheme); Light/Dark lock the appearance
+  * the collapsible "Theme choices" section is expanded only when a non-default light or dark
+    theme is stored
   * graceful degradation when localStorage throws (page still loads, default theme applied)
 """
 
@@ -99,6 +101,18 @@ def _dialog(page):
     return page.locator("#theme-picker-dialog")
 
 
+def _expand_choices(page):
+    """Open the collapsible Light/Dark "Theme choices" section if it isn't already open."""
+    choices = page.locator("#theme-picker-choices")
+    if choices.count() and choices.get_attribute("open") is None:
+        page.locator("#theme-picker-choices > summary").click()
+
+
+def _set_mode(page, mode):
+    """Select an Appearance radio button: 'light', 'dark', or 'auto'."""
+    page.locator(f"#theme-picker-mode-{mode}").check()
+
+
 def test_gear_height_and_centering_match_search(page):
     """The gear glyph's ink height should be about 90% of the search input's outer height,
     and the two centers should be aligned vertically. (The user asked for "90% as tall as
@@ -193,29 +207,69 @@ def test_focus_trap(page):
         assert in_dialog, "focus escaped the dialog"
 
 
-def test_theme_switching_persists(page, server):
+def test_appearance_radios_offer_light_dark_follow_system(page):
+    """The Appearance group offers exactly Light / Dark / Follow system radios, in that order."""
     btn = _picker_button(page)
     btn.click()
     _dialog(page).wait_for(state="attached", timeout=5000)
-    # Force single mode (the toggle starts on auto/checked when the picker has both
-    # light and dark themes; unchecking it switches to single).
-    mode = page.locator("#theme-picker-mode")
-    if mode.is_checked():
-        mode.uncheck()
-    # Pick the second option in the single dropdown.
-    single = page.locator("#theme-picker-single")
-    options = single.locator("option").all_text_contents()
-    if len(options) < 2:
-        pytest.skip("not enough themes registered to test switching")
-    chosen = single.locator("option").nth(1).get_attribute("value")
-    single.select_option(value=chosen)
-    # The data attribute should reflect the choice immediately.
+    radios = page.locator("#theme-picker-mode input[type=radio]")
+    values = radios.evaluate_all("els => els.map(e => e.value)")
+    labels = page.locator("#theme-picker-mode .theme-picker-radio").all_text_contents()
+    assert values == ["light", "dark", "auto"], f"unexpected radio values {values!r}"
+    assert [t.strip() for t in labels] == ["Light", "Dark", "Follow system"], (
+        f"unexpected radio labels {labels!r}"
+    )
+
+
+def test_first_visit_defaults_to_follow_system(page):
+    """A fresh visitor (no stored mode) sees the Appearance group on 'Follow system'."""
+    btn = _picker_button(page)
+    btn.click()
+    _dialog(page).wait_for(state="attached", timeout=5000)
+    assert page.locator("#theme-picker-mode-auto").is_checked()
+    assert not page.locator("#theme-picker-mode-light").is_checked()
+    assert not page.locator("#theme-picker-mode-dark").is_checked()
+
+
+def test_default_mode_exposed_and_drives_initial_radio(page):
+    """`window.versoThemes.defaultMode` is the author-configured starting mode (the user's guide
+    uses the default `followSystem`, encoded as `auto`), and the picker starts on it when nothing
+    is stored."""
+    default_mode = page.evaluate("window.versoThemes.defaultMode")
+    assert default_mode == "auto", (
+        f"expected exposed defaultMode 'auto', got {default_mode!r}"
+    )
+    btn = _picker_button(page)
+    btn.click()
+    _dialog(page).wait_for(state="attached", timeout=5000)
+    assert page.locator(f"#theme-picker-mode-{default_mode}").is_checked()
+
+
+def test_light_mode_switching_persists(page, server):
+    """Selecting Light mode and a non-default light theme sets the data attributes and
+    survives a reload (the no-flash script reapplies it before paint)."""
+    btn = _picker_button(page)
+    btn.click()
+    _dialog(page).wait_for(state="attached", timeout=5000)
+    _set_mode(page, "light")
+    _expand_choices(page)
+    light = page.locator("#theme-picker-light")
+    current = page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
+    chosen = None
+    for opt in light.locator("option").all():
+        v = opt.get_attribute("value")
+        if v and v != current:
+            chosen = v
+            break
+    if chosen is None:
+        pytest.skip("not enough light themes registered to test switching")
+    light.select_option(value=chosen)
     assert (
         page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
         == chosen
     )
-    # localStorage persists it.
-    assert page.evaluate("localStorage.getItem('verso-theme-single')") == chosen
+    assert page.evaluate("localStorage.getItem('verso-theme-light')") == chosen
+    assert page.evaluate("localStorage.getItem('verso-theme-mode')") == "light"
     # Reload: the no-flash script reads localStorage and applies the same theme before paint.
     page.goto(server + "/")
     page.wait_for_load_state("domcontentloaded")
@@ -225,44 +279,49 @@ def test_theme_switching_persists(page, server):
     )
 
 
-def test_match_system_follows_media(page):
+def test_follow_system_tracks_media(page):
     btn = _picker_button(page)
     btn.click()
     _dialog(page).wait_for(state="attached", timeout=5000)
-    mode = page.locator("#theme-picker-mode")
-    if not mode.is_checked():
-        mode.check()
+    _set_mode(page, "auto")
     # Emulate dark, then light; the inline script's matchMedia listener should swap themes.
     page.emulate_media(color_scheme="dark")
     page.wait_for_timeout(50)
     dark_id = page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
+    dark_appearance = page.evaluate(
+        "document.documentElement.getAttribute('data-verso-appearance')"
+    )
     page.emulate_media(color_scheme="light")
     page.wait_for_timeout(50)
     light_id = page.evaluate(
         "document.documentElement.getAttribute('data-verso-theme')"
     )
+    light_appearance = page.evaluate(
+        "document.documentElement.getAttribute('data-verso-appearance')"
+    )
     assert dark_id != light_id, (
-        "auto mode should pick different themes for light vs dark"
+        "Follow system should pick different themes for light vs dark"
     )
+    assert dark_appearance == "dark" and light_appearance == "light"
 
 
-def test_single_mode_ignores_media(page):
+def test_locked_appearance_ignores_media(page):
+    """Light mode locks the appearance: a system media change must not override the theme."""
     btn = _picker_button(page)
     btn.click()
     _dialog(page).wait_for(state="attached", timeout=5000)
-    mode = page.locator("#theme-picker-mode")
-    if mode.is_checked():
-        mode.uncheck()
-    # Pick a specific theme.
-    chosen = page.locator("#theme-picker-single option").nth(0).get_attribute("value")
-    page.locator("#theme-picker-single").select_option(value=chosen)
-    # Emulating a media change must not override the chosen theme.
+    _set_mode(page, "light")
+    chosen = page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
     page.emulate_media(color_scheme="dark")
     page.wait_for_timeout(50)
     assert (
         page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
         == chosen
     )
+    assert (
+        page.evaluate("document.documentElement.getAttribute('data-verso-appearance')")
+        == "light"
+    )
     page.emulate_media(color_scheme="light")
     page.wait_for_timeout(50)
     assert (
@@ -272,17 +331,15 @@ def test_single_mode_ignores_media(page):
 
 
 def test_auto_commit_applies_dropdown_value(page):
-    """In auto mode, changing the light dropdown while `prefers-color-scheme: light` is active
+    """In Follow-system mode under `prefers-color-scheme: light`, changing the light dropdown
     should immediately apply the chosen light theme. The committed `data-verso-theme` must
     match the dropdown's value, not whatever was previously painted."""
     page.emulate_media(color_scheme="light")
     btn = _picker_button(page)
     btn.click()
     _dialog(page).wait_for(state="attached", timeout=5000)
-    mode = page.locator("#theme-picker-mode")
-    if not mode.is_checked():
-        mode.check()
-    # Find a light-appearance option that differs from the currently visible theme.
+    _set_mode(page, "auto")
+    _expand_choices(page)
     light = page.locator("#theme-picker-light")
     current = page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
     chosen = None
@@ -293,7 +350,6 @@ def test_auto_commit_applies_dropdown_value(page):
             break
     assert chosen is not None, "need at least two light themes to test commit"
     light.select_option(value=chosen)
-    # The select-change handler fires `commit()`, which must apply the dropdown's value.
     after = page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
     assert after == chosen, (
         f"auto-mode commit should apply dropdown value {chosen!r}, got {after!r}"
@@ -302,18 +358,16 @@ def test_auto_commit_applies_dropdown_value(page):
 
 def test_switching_themes_has_no_intermediate_state(page):
     """Selecting a new theme in the dropdown must take `data-verso-theme` directly from the
-    old value to the new value. Any intermediate state — e.g. a hover/focus preview on the
-    *other* mode's dropdown firing during the click, or a transient default — would cause a
-    visible flash to an unrelated theme."""
+    old value to the new value. Any intermediate state — e.g. a transient default — would
+    cause a visible flash to an unrelated theme."""
     btn = _picker_button(page)
     btn.click()
     _dialog(page).wait_for(state="attached", timeout=5000)
-    # Single mode keeps the test deterministic: only one dropdown is visible, so the test
-    # exercises the user path of "open the dialog, pick a different theme, see only the new
-    # theme paint."
-    mode = page.locator("#theme-picker-mode")
-    if mode.is_checked():
-        mode.uncheck()
+    # Light mode keeps the test deterministic: the active theme is exactly the light dropdown's
+    # value, so the test exercises "open the dialog, pick a different light theme, see only the
+    # new theme paint."
+    _set_mode(page, "light")
+    _expand_choices(page)
     # Install a MutationObserver that logs every value `data-verso-theme` takes from this
     # point on, so we can assert the sequence after the switch.
     page.evaluate(
@@ -332,41 +386,37 @@ def test_switching_themes_has_no_intermediate_state(page):
             window.__versoStopObserver = () => obs.disconnect();
         }"""
     )
-    single = page.locator("#theme-picker-single")
+    light = page.locator("#theme-picker-light")
     initial = page.evaluate("document.documentElement.getAttribute('data-verso-theme')")
     target = None
-    for opt in single.locator("option").all():
+    for opt in light.locator("option").all():
         v = opt.get_attribute("value")
         if v and v != initial:
             target = v
             break
-    assert target is not None, "need at least two themes to test a switch"
-    single.select_option(value=target)
-    # Give the change handler a moment to run any cascaded events (focus/mouseenter previews,
-    # outside-click handler, etc.) so they show up in the recorded sequence.
+    assert target is not None, "need at least two light themes to test a switch"
+    light.select_option(value=target)
+    # Give the change handler a moment to run any cascaded events so they show up in the
+    # recorded sequence.
     page.wait_for_timeout(100)
     page.evaluate("window.__versoStopObserver()")
     states = page.evaluate("window.__versoThemeStates")
     # The only value `data-verso-theme` should take during the switch is the chosen target.
-    # Any other id (e.g. PageTheme, defaultDark, etc.) means there was an intermediate paint.
     bad = [s for s in states if s != target]
     assert not bad, (
-        f"intermediate theme states during single-mode switch from {initial!r} to {target!r}: {bad}"
+        f"intermediate theme states during light-mode switch from {initial!r} to {target!r}: {bad}"
     )
 
 
 def test_switching_light_themes_in_auto_has_no_dark_flash(page):
-    """In auto mode under `prefers-color-scheme: light`, switching the *light* dropdown must
-    not paint a dark theme in between. The hover/focus preview handlers were attached to the
-    dark dropdown too, so a stray mouseenter (Playwright's `select_option` walks the cursor
-    over the dialog) could fire `previewTheme(darkSel.value)` mid-switch."""
+    """In Follow-system mode under `prefers-color-scheme: light`, switching the *light*
+    dropdown must not paint a dark theme in between."""
     page.emulate_media(color_scheme="light")
     btn = _picker_button(page)
     btn.click()
     _dialog(page).wait_for(state="attached", timeout=5000)
-    mode = page.locator("#theme-picker-mode")
-    if not mode.is_checked():
-        mode.check()
+    _set_mode(page, "auto")
+    _expand_choices(page)
     light = page.locator("#theme-picker-light")
     dark = page.locator("#theme-picker-dark")
     page.evaluate(
@@ -394,19 +444,13 @@ def test_switching_light_themes_in_auto_has_no_dark_flash(page):
             break
     assert target is not None, "need at least two light themes to test a switch"
     dark_value = dark.locator("option").first.get_attribute("value")
-    # Real-user flow: focus the light dropdown (as a normal user would click on it) and
-    # pick a new option. Hovering the *other* dropdown is also part of the picked-up bug,
-    # but a previous version fired the dark preview because a stray mouseenter on the dark
-    # dropdown landed during Playwright's option-click; both paths should land on the
-    # target theme and only on the target theme.
     light.focus()
     light.select_option(value=target)
     page.wait_for_timeout(100)
     page.evaluate("window.__versoStopObserver()")
     states = page.evaluate("window.__versoThemeStates")
-    # The forbidden state is the *dark* one. Re-applying `initial` (the value the page
-    # already had when the test snapshotted it) is invisible to the user; only a flash to
-    # a different appearance, or to a third unrelated theme, is a real flicker.
+    # The forbidden state is the *dark* one. Re-applying `initial` (the value the page already
+    # had) is invisible; only a flash to a different appearance is a real flicker.
     assert dark_value not in states, (
         f"dark theme {dark_value!r} appeared during a light-to-light switch; full sequence: {states}"
     )
@@ -416,79 +460,91 @@ def test_switching_light_themes_in_auto_has_no_dark_flash(page):
     )
 
 
-def test_single_mode_marks_single_default(page):
-    """The single-mode dropdown marks `data.defaultSingle` with " (default)", not the light
-    default unconditionally. Authors who set `defaultSingleAppearance := .dark` should see
-    the dark theme labelled as the default in single mode."""
+def test_theme_dropdowns_mark_their_defaults(page):
+    """The light dropdown marks `defaultLight` with ' (default)' and the dark dropdown marks
+    `defaultDark` — each appearance's own default, not the other's."""
     btn = _picker_button(page)
     btn.click()
     _dialog(page).wait_for(state="attached", timeout=5000)
-    mode = page.locator("#theme-picker-mode")
-    if mode.is_checked():
-        mode.uncheck()
-    single_default_id = page.evaluate("window.versoThemes.defaultSingle")
-    # The option text for the single-default id is the only one with " (default)" appended.
-    marked = page.evaluate(
-        """(id) => {
-            const opts = Array.from(document.querySelectorAll('#theme-picker-single option'));
-            return opts
-                .filter(o => o.textContent.endsWith(' (default)'))
-                .map(o => o.value);
-        }""",
-        single_default_id,
-    )
-    assert marked == [single_default_id], (
-        f"single-mode (default) should mark only {single_default_id!r}, got {marked!r}"
-    )
-
-
-def test_themes_are_alphabetized(page):
-    """Every dropdown lists its themes in alphabetical order by display name."""
+    _expand_choices(page)
+    default_light = page.evaluate("window.versoThemes.defaultLight")
+    default_dark = page.evaluate("window.versoThemes.defaultDark")
+    light_marked = page.evaluate(
+        """() => Array.from(document.querySelectorAll('#theme-picker-light option'))
+            .filter(o => o.textContent.endsWith(' (default)')).map(o => o.value)"""
+    )
+    dark_marked = page.evaluate(
+        """() => Array.from(document.querySelectorAll('#theme-picker-dark option'))
+            .filter(o => o.textContent.endsWith(' (default)')).map(o => o.value)"""
+    )
+    assert light_marked == [default_light], (
+        f"light dropdown (default) should mark only {default_light!r}, got {light_marked!r}"
+    )
+    assert dark_marked == [default_dark], (
+        f"dark dropdown (default) should mark only {default_dark!r}, got {dark_marked!r}"
+    )
+
+
+def test_theme_dropdowns_are_alphabetized(page):
+    """The Light and Dark theme dropdowns list their themes in alphabetical order by display
+    name."""
     btn = _picker_button(page)
     btn.click()
     _dialog(page).wait_for(state="attached", timeout=5000)
-    mode = page.locator("#theme-picker-mode")
-    for sel_id, ensure_auto in [
-        ("#theme-picker-single", False),
-        ("#theme-picker-light", True),
-        ("#theme-picker-dark", True),
-    ]:
-        if ensure_auto and not mode.is_checked():
-            mode.check()
-        if not ensure_auto and mode.is_checked():
-            mode.uncheck()
+    _expand_choices(page)
+    for sel_id in ["#theme-picker-light", "#theme-picker-dark"]:
         texts = page.locator(f"{sel_id} option").all_text_contents()
         assert texts == sorted(texts), f"{sel_id} options not alphabetised: {texts}"
 
 
-def test_match_system_toggle_hides_rows(page):
-    """The 'Theme' (single) row is visible only when Match system is OFF; Light and Dark are
-    visible only when Match system is ON. The `[hidden]` attribute on the row elements must
-    actually hide them — earlier CSS made the `.theme-picker-row { display: flex }` rule
-    win over the default `[hidden] { display: none }`, so the toggle did nothing."""
+def test_choices_collapsed_by_default(page):
+    """With nothing customized, the 'Theme choices' section is collapsed (so the picker is a
+    one-line Appearance dropdown)."""
     btn = _picker_button(page)
     btn.click()
     _dialog(page).wait_for(state="attached", timeout=5000)
-    mode = page.locator("#theme-picker-mode")
+    choices = page.locator("#theme-picker-choices")
+    assert choices.count() == 1, "expected a collapsible #theme-picker-choices section"
+    assert choices.get_attribute("open") is None, "choices should start collapsed"
+    assert not page.locator("#theme-picker-light").is_visible()
 
-    # Auto on -> Light + Dark visible, Theme hidden.
-    if not mode.is_checked():
-        mode.check()
-    assert page.locator("#theme-picker-light").is_visible()
-    assert page.locator("#theme-picker-dark").is_visible()
-    assert not page.locator("#theme-picker-single").is_visible()
 
-    # Auto off -> Theme visible, Light + Dark hidden.
-    mode.uncheck()
-    assert page.locator("#theme-picker-single").is_visible()
-    assert not page.locator("#theme-picker-light").is_visible()
-    assert not page.locator("#theme-picker-dark").is_visible()
+def test_choices_expanded_when_custom_theme_stored(page, server):
+    """Once a non-default light theme is stored, the 'Theme choices' section opens by default
+    on the next load so the customized choice is visible."""
+    btn = _picker_button(page)
+    btn.click()
+    _dialog(page).wait_for(state="attached", timeout=5000)
+    _expand_choices(page)
+    light = page.locator("#theme-picker-light")
+    default_light = page.evaluate("window.versoThemes.defaultLight")
+    chosen = None
+    for opt in light.locator("option").all():
+        v = opt.get_attribute("value")
+        if v and v != default_light:
+            chosen = v
+            break
+    if chosen is None:
+        pytest.skip(
+            "only one light theme registered; cannot store a non-default choice"
+        )
+    light.select_option(value=chosen)
+    # Reload: a fresh dialog is built, reading the stored non-default light theme.
+    page.goto(server + "/")
+    page.wait_for_load_state("domcontentloaded")
+    btn = _picker_button(page)
+    btn.click()
+    _dialog(page).wait_for(state="attached", timeout=5000)
+    choices = page.locator("#theme-picker-choices")
+    assert choices.get_attribute("open") is not None, (
+        "choices should be expanded when a non-default theme is stored"
+    )
+    assert page.locator("#theme-picker-light").is_visible()
 
 
 def test_outside_click_dismisses_popover(page):
     """Clicking outside the popover closes the dialog and leaves the page on whatever theme
-    is currently committed. (The picker commits on `change` and no longer has a hover/focus
-    preview path, so dismissal is purely a "close the popover" action.)"""
+    is currently committed."""
     btn = _picker_button(page)
     btn.click()
     _dialog(page).wait_for(state="attached", timeout=5000)
@@ -547,8 +603,7 @@ def test_picker_preview_token_hover_shows_tippy(page):
     The picker preview is built on first popover open via `preview.innerHTML = data.codeSample`.
     The page's tippy-init script runs at DOMContentLoaded over `document.querySelectorAll(
     tokenSelector)` — before the picker preview exists — so without follow-up wiring those
-    tokens get no `_tippy` instance and hovering them does nothing. This test currently fails
-    and is the acceptance criterion for that fix.
+    tokens get no `_tippy` instance and hovering them does nothing.
     """
     btn = _picker_button(page)
     btn.click()
@@ -560,9 +615,6 @@ def test_picker_preview_token_hover_shows_tippy(page):
     # reference the global `-verso-docs.json`).
     token = preview.locator(".token[data-verso-hover]").first
     token.wait_for(state="attached", timeout=5000)
-    # The bug shows up two ways and the test asserts both. (1) The preview token has no
-    # `_tippy` instance attached (the page-level tippy-init scanned the DOM before the
-    # picker preview existed). (2) Hovering the token does not produce a `.tippy-box`.
     has_tippy = page.evaluate(
         "el => !!el._tippy",
         token.element_handle(),
@@ -578,11 +630,6 @@ def test_picker_preview_binding_highlight(page):
     """Hovering an identifier in the picker preview should add `.binding-hl` to its other
     occurrences in the preview — the same binding-highlight effect the manual's body code
     gets.
-
-    The per-`.hl.lean` mouseover handler is attached at DOMContentLoaded over
-    `document.querySelectorAll('.hl.lean')`; the picker preview is built later, so without a
-    follow-up `window.versoAttachBindingHighlights(...)` call the listener never fires and
-    hovering one `name` leaves the other one untouched.
     """
     btn = _picker_button(page)
     btn.click()
diff --git a/doc/UsersGuide/Manuals.lean b/doc/UsersGuide/Manuals.lean
index d17842b1f..225eaf9bf 100644
--- a/doc/UsersGuide/Manuals.lean
+++ b/doc/UsersGuide/Manuals.lean
@@ -320,10 +320,9 @@ tag := "manual-themes-overview"
 %%%
 
 When multiple themes are available, the rendered HTML for a manual includes a “gear” button in the header that opens a popover widget.
-This widget offers two choices:
- * a single theme, chosen by the user
- * a light theme and a dark theme, to be selected automatically based on the browser's `prefers-color-scheme` setting.
-
+At the top, an _Appearance_ selector offers radio buttons for _Light_, _Dark_, and _Follow system_.
+Beneath it, a collapsible _Theme choices_ section provides dropdown menus to select specific themes for light and dark modes.
+The light theme is used in _Light_ mode and the dark theme in _Dark_ mode, while _Follow system_ switches between them automatically based on the browser's `prefers-color-scheme` setting.
 
 ## The `ManualTheme` Structure
 %%%
@@ -448,10 +447,11 @@ The following fields of {name}`RenderConfig` are relevant to themes:
 
   When readers have configured their themes to follow the system preference, this is the default dark theme.
 
-: {name RenderConfig.defaultSingleAppearance}`defaultSingleAppearance`
+: {name RenderConfig.defaultAppearance}`defaultAppearance`
 
-  When readers have configured their themes to ignore the browser's request, this selects between the default light theme or the default dark theme as the single default.
+  The mode that new readers start in. With {name Verso.Theme.ThemeMode.followSystem}`followSystem` (the default), the picker starts on _Follow system_. With {name Verso.Theme.ThemeMode.light}`light` or {name Verso.Theme.ThemeMode.dark}`dark`, new readers start on that fixed appearance instead, which is useful when a document should default to one appearance regardless of the reader's operating system setting. Readers can always switch in the picker.
 
+In {name Verso.Theme.ThemeMode.followSystem}`followSystem` mode, readers without JavaScript are served the default light theme, with the default dark theme swapped in via a `prefers-color-scheme: dark` media query, so they follow their system appearance too; in {name Verso.Theme.ThemeMode.light}`light` or {name Verso.Theme.ThemeMode.dark}`dark` mode they are served that appearance's default unconditionally.
 
 ## Accessibility Checking
 %%%
diff --git a/src/tests/ThemeTestMain.lean b/src/tests/ThemeTestMain.lean
index d2f353869..14bbeb5c0 100644
--- a/src/tests/ThemeTestMain.lean
+++ b/src/tests/ThemeTestMain.lean
@@ -73,8 +73,8 @@ def testManualTheme : ManualTheme := {
 
 /--
 Dark counterpart to `testManualTheme`. The validation pass requires a registered dark theme
-for `defaultDarkTheme`, but the test only inspects the unscoped `:root` block (the
-single-mode default, here `.light`), so the same sentinel palette under `.dark` is fine.
+for `defaultDarkTheme`, but the browser test only inspects the unscoped `:root` block (the light
+default in the default follow-system mode), so the same sentinel palette under `.dark` is fine.
 -/
 @[manual_theme]
 def testManualThemeDark : ManualTheme := {
@@ -82,6 +82,34 @@ def testManualThemeDark : ManualTheme := {
   toCodeTheme := { testTheme with name := "ThemeTest Dark", appearance := .dark }
 }
 
+/-!
+Unit checks for the no-JavaScript / picker scaffolding driven by {name}`Verso.Theme.ThemeMode`. A
+two-theme registry (one light, one dark) stands in for a real build's available set. The report
+below records, per generated output, whether the mode-dependent content is present.
+
+Follow-system mode pairs a light `:root` with a `prefers-color-scheme: dark` media block; light and
+dark mode emit a single `:root` with no media swap. The configured mode must also reach the
+no-flash script (as `DEFAULT_MODE`) and the picker's `window.versoThemes` data file.
+-/
+private def modeCheckRegistry : ThemeRegistry :=
+  (({} : ThemeRegistry).insert `light ManualTheme.ink).insert `dark ManualTheme.argent
+
+private def hasSubstr (haystack needle : String) : Bool :=
+  (haystack.splitOn needle).length > 1
+
+/--
+info: css @media(dark) by mode -> followSystem=true light=false dark=false
+themeInitScript inlines the configured mode: true
+windowVersoThemesJs carries the configured mode: true
+-/
+#guard_msgs in
+#eval do
+  let mediaFor (m : ThemeMode) : Bool :=
+    hasSubstr («verso-themes.css» modeCheckRegistry `light `dark m) "@media (prefers-color-scheme: dark)"
+  IO.println s!"css @media(dark) by mode -> followSystem={mediaFor .followSystem} light={mediaFor .light} dark={mediaFor .dark}"
+  IO.println s!"themeInitScript inlines the configured mode: {hasSubstr (themeInitScript modeCheckRegistry `light `dark .dark) "var DEFAULT_MODE = \"dark\""}"
+  IO.println s!"windowVersoThemesJs carries the configured mode: {hasSubstr (windowVersoThemesJs modeCheckRegistry `light `dark .light "sample") "\"defaultMode\":\"light\""}"
+
 def main : List String → IO UInt32 :=
   manualMain (%doc ThemeTestDoc)
     (config := { config with
diff --git a/src/verso-manual/VersoManual.lean b/src/verso-manual/VersoManual.lean
index 6db4623dd..538854935 100644
--- a/src/verso-manual/VersoManual.lean
+++ b/src/verso-manual/VersoManual.lean
@@ -292,29 +292,20 @@ structure RenderConfig extends Config where
   The default light-appearance theme. Its registration name must be a registered
   `ManualTheme` whose appearance is `.light`.
   -/
-  defaultLightTheme : Name := ``Verso.Theme.ManualTheme.ink
+  defaultLightTheme : Name := ``ManualTheme.ink
   /--
   The default dark-appearance theme. Its registration name must be a registered
   `ManualTheme` whose appearance is `.dark`.
   -/
-  defaultDarkTheme : Name := ``Verso.Theme.ManualTheme.argent
+  defaultDarkTheme : Name := ``ManualTheme.argent
   /--
-  The default for readers who do not follow the system appearance (the "single" picker mode):
-  choose `.light` so single-mode falls back to
-  `defaultLightTheme`,
-  or `.dark` so it falls back to
-  `defaultDarkTheme`.
-
-  Auto-mode behavior is unchanged either way: a reader who keeps "Match system" on still gets
-  the light or dark default depending on their OS preference. This setting only governs the
-  single-mode fallback (and what the picker marks as ` (default)` in the single-mode
-  dropdown).
+  The appearance new readers start in.
   -/
-  defaultSingleAppearance : Appearance := .light
+  defaultAppearance : ThemeMode := .followSystem
   /--
   The {name}`CodeTheme` used for PDF output.
   -/
-  pdfCodeTheme : Verso.Theme.CodeTheme := Verso.Theme.CodeTheme.ink
+  pdfCodeTheme : CodeTheme := CodeTheme.ink
 
 namespace Config
 
@@ -446,33 +437,6 @@ def DividedDoc.ofPart (part : Part Manual) : DividedDoc :=
 where
   isUnnumbered (p : Part Manual) : Bool := p.metadata.map (·.number) |>.isEqSome false
 
-/--
-Resolves the single-mode default theme name from the configured
-`Verso.Genre.Manual.RenderConfig.defaultSingleAppearance` — either
-`Verso.Genre.Manual.RenderConfig.defaultLightTheme` or
-`Verso.Genre.Manual.RenderConfig.defaultDarkTheme`.
--/
-def defaultSingleName (config : RenderConfig) : Lean.Name :=
-  match config.defaultSingleAppearance with
-  | .light => config.defaultLightTheme
-  | .dark => config.defaultDarkTheme
-
-/--
-The single-default `ManualTheme` resolved from the active
-{name}`ThemeRegistry`. This is the theme that drives
-`verso-themes.css`'s unscoped `:root` block — what the server-rendered HTML paints on first
-visit (before the no-flash script attaches a `data-verso-theme`) — and the TeX code styling.
-
-Falls back to a bare default `ManualTheme.ink` if neither the resolved single-default name
-nor either configured default appears in the registry (a defensive case; the validation pass
-in `manualMain` rejects unregistered defaults before this is called).
--/
-def singleDefaultTheme (registry : ThemeRegistry) (config : RenderConfig) :
-    Verso.Theme.ManualTheme :=
-  (registry.find? (defaultSingleName config)
-    <|> registry.find? config.defaultLightTheme
-    <|> registry.find? config.defaultDarkTheme).getD Verso.Theme.ManualTheme.ink
-
 open IO.FS in
 /--
 Writes every theme-related asset for an output root: the multi-theme `verso-themes.css`, the
@@ -484,11 +448,10 @@ def writeThemeAssets (dir : System.FilePath) (config : RenderConfig)
     (codeSampleHtml : String) : EmitM Unit := do
   let themes ← readThe ThemeRegistry
   ensureDir (dir / "-verso-data")
-  let single := singleDefaultTheme themes config
   -- verso-themes.css
   withFile (dir / "verso-themes.css") .write fun h => do
-    h.putStrLn (Verso.Theme.«verso-themes.css» single themes
-      config.defaultLightTheme config.defaultDarkTheme)
+    h.putStrLn (Theme.«verso-themes.css» themes
+      config.defaultLightTheme config.defaultDarkTheme config.defaultAppearance)
   -- Font bytes, deduplicated by output path: a theme's @font-face rules embed the per-theme
   -- asset-root path, so writing one path and skipping a structurally-identical-bytes path under
   -- a different theme root would leave that rule pointing at a missing file.
@@ -509,7 +472,7 @@ def writeThemeAssets (dir : System.FilePath) (config : RenderConfig)
   -- via a path like `../../book.css`.
   for (n, t) in themes do
     for a in t.assets do
-      unless Verso.Theme.ThemeAsset.safePath a.path do
+      unless Theme.ThemeAsset.safePath a.path do
         Verso.reportError
           s!"refusing to write theme asset for '{n.toString}': unsafe path '{a.path}'"
         continue
@@ -520,8 +483,8 @@ def writeThemeAssets (dir : System.FilePath) (config : RenderConfig)
   writeFile (dir / "-verso-data" / "theme-picker.js") Manual.Theme.«theme-picker.js»
   writeFile (dir / "-verso-data" / "theme-picker.css") Manual.Theme.«theme-picker.css»
   writeFile (dir / "-verso-data" / "verso-themes.js")
-    (Verso.Theme.windowVersoThemesJs themes config.defaultLightTheme config.defaultDarkTheme
-      (defaultSingleName config) codeSampleHtml)
+    (Theme.windowVersoThemesJs themes config.defaultLightTheme config.defaultDarkTheme
+      config.defaultAppearance codeSampleHtml)
 
 open IO.FS in
 def emitTeX (config : RenderConfig) (text : Part Manual) : EmitM Unit := do
@@ -949,7 +912,7 @@ where
       let themeInitScript :=
         if showThemePicker then
           Verso.Theme.themeInitScript registry
-            config.defaultLightTheme config.defaultDarkTheme (defaultSingleName config)
+            config.defaultLightTheme config.defaultDarkTheme config.defaultAppearance
         else ""
       h.putStrLn <| Html.asString <| relativizeLinks <|
         page toc ctxt.path text.titleString titleToShow pageContent state config.toConfig thisPageToc
@@ -1089,7 +1052,7 @@ where
       let themeInitScript :=
         if showThemePicker then
           Verso.Theme.themeInitScript registry
-            config.defaultLightTheme config.defaultDarkTheme (defaultSingleName config)
+            config.defaultLightTheme config.defaultDarkTheme config.defaultAppearance
         else ""
       h.putStrLn <| Html.asString <| relativizeLinks <|
         page bookContents ctxt.path part.titleString bookTitle pageContent state config.toConfig thisPageToc
@@ -1280,7 +1243,8 @@ where
     --                   `defaultDarkTheme` implicitly added if missing so the picker always
     --                   contains the resolved default for each appearance.
     -- The result always contains at least `defaultLightTheme` and `defaultDarkTheme` if those
-    -- are registered, so `singleDefaultTheme` can always resolve.
+    -- are registered, so `verso-themes.css` always has a light and a dark default to fall back
+    -- to for readers without JavaScript.
     match cfg.availableThemes with
     | none => return table.themes
     | some xs =>
diff --git a/src/verso-manual/VersoManual/Theme/Emit.lean b/src/verso-manual/VersoManual/Theme/Emit.lean
index e3e112c46..757e61eb7 100644
--- a/src/verso-manual/VersoManual/Theme/Emit.lean
+++ b/src/verso-manual/VersoManual/Theme/Emit.lean
@@ -21,6 +21,27 @@ namespace Verso.Theme
 
 open Lean (Json)
 
+/--
+The theme mode a manual starts new readers in, and the appearance it serves to readers without
+JavaScript.
+-/
+public inductive ThemeMode where
+  /-- Track the operating system's {lit}`prefers-color-scheme`. -/
+  | followSystem
+  /-- Always start with the default light theme. -/
+  | light
+  /-- Always start with the default dark theme. -/
+  | dark
+deriving DecidableEq, Repr
+
+instance : Inhabited ThemeMode := ⟨.followSystem⟩
+
+/-- The picker and no-flash mode string for a theme mode: {lit}`auto`, {lit}`light`, or {lit}`dark`. -/
+public def ThemeMode.modeString : ThemeMode → String
+  | .followSystem => "auto"
+  | .light => "light"
+  | .dark => "dark"
+
 /-- The pieces of a theme that the picker / no-flash script need at runtime, JSON-encoded. -/
 private def themeJson (n : Lean.Name) (t : ManualTheme) : Json :=
   let appearance := match t.appearance with | .light => "light" | .dark => "dark"
@@ -38,22 +59,26 @@ private def themeJson (n : Lean.Name) (t : ManualTheme) : Json :=
 
 /--
 The contents of {lit}`-verso-data/verso-themes.js`. Exposes {lit}`window.versoThemes` with the
-shape `{ themes: [...], defaultLight, defaultDark, codeSample }` so the picker can render the
-choices and the live code preview.
+shape `{ themes: [...], defaultLight, defaultDark, defaultMode, codeSample }` so the picker can
+render the choices and the live code preview.
+
+{name}`defaultMode` is the {name}`ThemeMode` an author configured, encoded as the picker's mode
+string, so a new reader's Appearance control starts on it.
 
 {name}`codeSample` is a small fixed HTML string reusing the {lit}`.hl.lean` markup; the picker drops it
 inside a {lit}`data-verso-theme`-scoped element to show what each theme will look like.
 -/
 public def windowVersoThemesJs
     (themes : ThemeRegistry)
-    (defaultLight defaultDark defaultSingle : Lean.Name)
+    (defaultLight defaultDark : Lean.Name)
+    (defaultMode : ThemeMode)
     (codeSample : String) : String :=
   let entries := themes.foldl (init := #[]) (fun acc n t => acc.push (themeJson n t))
   let payload := Json.mkObj [
     ("themes", Json.arr entries),
     ("defaultLight", Json.str defaultLight.toString),
     ("defaultDark", Json.str defaultDark.toString),
-    ("defaultSingle", Json.str defaultSingle.toString),
+    ("defaultMode", Json.str defaultMode.modeString),
     ("codeSample", Json.str codeSample)
   ]
   s!"window.versoThemes = {payload.compress};\n"
@@ -64,13 +89,17 @@ The body of the synchronous head script that runs before paint and sets
 painted frame matches the chosen theme. The {lit}`themes` argument is the available set; the
 defaults are inlined here (not read from {lit}`window.versoThemes`) to avoid an ordering race.
 
-Single-mode fallback is {lit}`defaultSingle` — the theme an author chose for readers who do
-not follow the system appearance. First visits (no stored mode) use the same fallback so the
-painted frame matches what the reader will see when they open the picker.
+The stored {lit}`verso-theme-mode` is one of {lit}`light`, {lit}`dark`, or {lit}`auto`.
+In {lit}`light`/{lit}`dark` mode the painted theme is the reader's chosen light or dark theme
+(falling back to {lit}`defaultLight`/{lit}`defaultDark`); in {lit}`auto` mode it tracks the OS
+{lit}`prefers-color-scheme`. First visits (no stored mode) use the author's configured
+{name}`ThemeMode` (inlined as {lit}`DEFAULT_MODE`), which defaults to {lit}`auto` so a new reader
+follows their system appearance.
 -/
 public def themeInitScript
     (themes : ThemeRegistry)
-    (defaultLight defaultDark defaultSingle : Lean.Name) : String :=
+    (defaultLight defaultDark : Lean.Name)
+    (defaultMode : ThemeMode) : String :=
   let pairs := themes.foldl (init := ([] : List String)) fun acc n t =>
     let a := match t.appearance with | .light => "light" | .dark => "dark"
     s!"\"{n.toString}\":\"{a}\"" :: acc
@@ -79,28 +108,28 @@ public def themeInitScript
   var APPEARANCE = {table};
   var DEFAULT_LIGHT = \"{defaultLight.toString}\";
   var DEFAULT_DARK = \"{defaultDark.toString}\";
-  var DEFAULT_SINGLE = \"{defaultSingle.toString}\";
+  var DEFAULT_MODE = \"{defaultMode.modeString}\";
   function readMode() \{ try \{ return localStorage.getItem(\"verso-theme-mode\"); } catch (e) \{ return null; } }
   function readKey(k) \{ try \{ return localStorage.getItem(k); } catch (e) \{ return null; } }
-  var mode = readMode();
   var prefersDark = window.matchMedia && window.matchMedia(\"(prefers-color-scheme: dark)\").matches;
+  var mode = readMode() || DEFAULT_MODE;
   var picked = null;
-  if (mode === \"single\") \{
-    picked = readKey(\"verso-theme-single\") || DEFAULT_SINGLE;
-  } else if (mode === \"auto\") \{
-    picked = prefersDark ? readKey(\"verso-theme-dark\") : readKey(\"verso-theme-light\");
-    if (!picked) picked = prefersDark ? DEFAULT_DARK : DEFAULT_LIGHT;
+  if (mode === \"light\") \{
+    picked = readKey(\"verso-theme-light\") || DEFAULT_LIGHT;
+  } else if (mode === \"dark\") \{
+    picked = readKey(\"verso-theme-dark\") || DEFAULT_DARK;
+  } else \{
+    picked = prefersDark ? (readKey(\"verso-theme-dark\") || DEFAULT_DARK)
+                         : (readKey(\"verso-theme-light\") || DEFAULT_LIGHT);
   }
   if (!picked || !APPEARANCE.hasOwnProperty(picked)) \{
-    // First visit (no mode set): use the single-mode default the author configured so the
-    // painted frame matches what the picker would show on this device.
-    picked = DEFAULT_SINGLE;
+    picked = prefersDark ? DEFAULT_DARK : DEFAULT_LIGHT;
   }
   var appearance = APPEARANCE[picked] || (prefersDark ? \"dark\" : \"light\");
   document.documentElement.setAttribute(\"data-verso-theme\", picked);
   document.documentElement.setAttribute(\"data-verso-appearance\", appearance);
   function onChange(e) \{
-    if ((readMode() || \"auto\") !== \"auto\") return;
+    if ((readMode() || DEFAULT_MODE) !== \"auto\") return;
     var dark = e.matches;
     var k = dark ? \"verso-theme-dark\" : \"verso-theme-light\";
     var p = readKey(k);
@@ -120,34 +149,52 @@ Produces the body of {lit}`verso-themes.css`:
 
 - font-face rules from every available theme (one block per theme; content dedup is the caller's
   job);
-- an unscoped `:root` block carrying the {name}`single`'s variables — what the server-rendered
-  HTML uses before the no-flash script attaches {lit}`data-verso-theme`. {name}`single` is the
-  resolved single-mode default theme;
-- an {lit}`@media (prefers-color-scheme: dark)` block carrying the {name}`ManualTheme`
-  named by {name}`defaultDark` (no-JS fallback only — the no-flash script always sets a concrete
-  attribute);
+- the no-JavaScript defaults, governed by {name}`defaultMode`. In {name (full := ThemeMode.followSystem)}`followSystem`
+  mode, when both {name}`defaultLight` and {name}`defaultDark` are available, an unscoped `:root`
+  block carries the light default and an {lit}`@media (prefers-color-scheme: dark)` block carries
+  the dark default, so readers without JavaScript follow their system appearance. In
+  {name (full := ThemeMode.light)}`light`/{name (full := ThemeMode.dark)}`dark` mode (or when only
+  one appearance has a theme), a single `:root` block carries that appearance's default and there
+  is no media-query swap. The no-flash script always sets a concrete {lit}`data-verso-theme`, so
+  this affects only readers without JavaScript and the first pre-script frame;
 - one `:root[data-verso-theme="…"]` block per registered theme so the picker can swap themes by
   flipping the attribute.
 
-{name}`single` is always one of the registered themes, so its font and asset URLs resolve against
-the same {lit}`-verso-data/themes/<name>` root as the attribute-scoped blocks; no separate
+The default themes are always among the registered themes, so their font and asset URLs resolve
+against the same {lit}`-verso-data/themes/<name>` root as the attribute-scoped blocks; no separate
 page-theme asset root is needed.
 -/
 public def «verso-themes.css»
-    (single : ManualTheme)
     (themes : ThemeRegistry)
-    (_defaultLight defaultDark : Lean.Name) : String := Id.run do
+    (defaultLight defaultDark : Lean.Name)
+    (defaultMode : ThemeMode) : String := Id.run do
   let assetRoot (n : Lean.Name) : String := s!"-verso-data/themes/{n.toString}"
   let mut out := ""
   -- Font-face rules.
   for (n, t) in themes do
     let rules := t.fontFaceRules (assetRoot n)
     unless rules.isEmpty do out := out ++ rules
-  -- Unscoped :root block from the single-mode default.
-  out := out ++ s!":root \{\n{single.cssVariables}}\n"
-  -- @media dark fallback for no-JS visitors.
-  if let some t := themes.find? defaultDark then
-    out := out ++ s!"@media (prefers-color-scheme: dark) \{\n  :root \{\n{t.cssVariables}  }\n}\n"
+  -- No-JavaScript defaults. In follow-system mode with both defaults available, a light `:root`
+  -- plus a dark media block lets no-JS readers track the system. In light/dark mode, or when only
+  -- one appearance has a theme, a single `:root` block carries that appearance's default with no
+  -- media swap. (The available set always contains both defaults, so the missing-default `<|>`
+  -- chains are defensive.)
+  let light? := themes.find? defaultLight
+  let dark? := themes.find? defaultDark
+  let any? := themes.toList.head?.map (·.2)
+  let rootOf (t : ManualTheme) : String := s!":root \{\n{t.cssVariables}}\n"
+  match defaultMode with
+  | .followSystem =>
+    match light?, dark? with
+    | some l, some d =>
+      out := out ++ rootOf l
+      out := out ++ s!"@media (prefers-color-scheme: dark) \{\n  :root \{\n{d.cssVariables}  }\n}\n"
+    | _, _ =>
+      if let some t := light? <|> dark? <|> any? then out := out ++ rootOf t
+  | .light =>
+    if let some t := light? <|> dark? <|> any? then out := out ++ rootOf t
+  | .dark =>
+    if let some t := dark? <|> light? <|> any? then out := out ++ rootOf t
   -- Attribute-scoped blocks for every registered theme.
   for (n, t) in themes do
     out := out ++ s!":root[data-verso-theme=\"{n.toString}\"] \{\n{t.cssVariables}}\n"
diff --git a/static-web/manual/theme/theme-picker.css b/static-web/manual/theme/theme-picker.css
index bcc210536..d19f6c6e6 100644
--- a/static-web/manual/theme/theme-picker.css
+++ b/static-web/manual/theme/theme-picker.css
@@ -75,14 +75,12 @@
     min-width: min(22rem, calc(100vw - 1rem));
     max-width: calc(100vw - 1rem);
     box-sizing: border-box;
-    /* Two-column grid: the label column auto-sizes to the widest label across all visible rows,
-       so Light/Dark/Theme dropdowns share a left edge. The rows themselves use
-       `display: contents` (below) so their label/select pairs become direct grid items. */
-    display: grid;
-    grid-template-columns: auto 1fr;
-    align-items: center;
-    column-gap: 0.5rem;
-    row-gap: 0.75rem;
+    /* Stack the controls vertically: the Appearance radios, the collapsible theme choices,
+       the code preview, and the per-theme metadata. Each is laid out on its own below. */
+    display: flex;
+    flex-direction: column;
+    align-items: stretch;
+    gap: 0.75rem;
     font-family: var(--verso-structure-font-family);
 }
 
@@ -90,32 +88,61 @@
     display: none;
 }
 
-#theme-picker-dialog .theme-picker-row {
-    display: contents;
+/* Appearance radio group. Strip the fieldset's default border and inset so it reads as a
+   labeled cluster of radios rather than a boxed form section. */
+#theme-picker-mode {
+    border: none;
+    margin: 0;
+    padding: 0;
+    min-width: 0;
+}
+
+#theme-picker-mode > legend {
+    padding: 0;
+    margin-bottom: 0.35rem;
+    color: inherit;
 }
 
-/* The "Match system" row has a checkbox followed by its label, not a label column followed
-   by a control. Span both columns and lay it out as a flex pair so the checkbox sits flush
-   against its label instead of being orphaned in the label column with a gap to a label
-   stranded in the dropdown column. */
-/* `:where()` zeros the `:has` argument's specificity so the `[hidden]` rule above still wins
-   for any future code path that toggles this row. */
-#theme-picker-dialog .theme-picker-row:where(:has(> input[type="checkbox"])) {
+#theme-picker-mode .theme-picker-radios {
     display: flex;
+    flex-wrap: wrap;
+    gap: 0.25rem 1rem;
+}
+
+#theme-picker-mode .theme-picker-radio {
+    display: inline-flex;
     align-items: center;
-    gap: 0.4rem;
-    grid-column: 1 / -1;
+    gap: 0.3rem;
+    cursor: pointer;
 }
 
-/* `[hidden]` toggles rely on this: `display: contents` on `.theme-picker-row` would
-   otherwise win over the default `display: none` the `hidden` attribute carries (and would
-   leak the row's children into the grid even when the row is hidden), so this rule restores
-   the expected hide. */
-#theme-picker-dialog .theme-picker-row[hidden] {
-    display: none;
+/* The collapsible "Theme choices" section holds the Light and Dark theme dropdowns. */
+#theme-picker-choices > summary {
+    cursor: pointer;
+    color: inherit;
+    margin-bottom: 0.5rem;
+}
+
+#theme-picker-choices > summary:focus-visible {
+    outline: 2px solid var(--verso-link-color, currentColor);
+    outline-offset: 2px;
+    border-radius: 0.2rem;
+}
+
+/* Each theme row is its own two-column grid with a fixed label column, so the Light and Dark
+   selects share a left edge regardless of label width. */
+#theme-picker-dialog .theme-picker-row {
+    display: grid;
+    grid-template-columns: 3rem 1fr;
+    align-items: center;
+    column-gap: 0.5rem;
+}
+
+#theme-picker-dialog .theme-picker-row + .theme-picker-row {
+    margin-top: 0.5rem;
 }
 
-#theme-picker-dialog .theme-picker-row select {
+#theme-picker-dialog select {
     min-width: 0;
     font: inherit;
     padding: 0.2rem 0.3rem;
@@ -126,8 +153,6 @@
 }
 
 #theme-picker-preview {
-    /* The preview is meant to span the full popup width, not sit in the dropdown column. */
-    grid-column: 1 / -1;
     border: 1px solid var(--verso-border-color, #999);
     border-radius: 0.3rem;
     background: var(--verso-code-background-color, #fff);
@@ -141,9 +166,8 @@
 }
 
 #theme-picker-about {
-    /* Theme metadata (description + canonical link) sits below the code preview. Spans both
-       columns and uses the structure font so it reads as prose rather than code. */
-    grid-column: 1 / -1;
+    /* Theme metadata (description + canonical link) sits below the code preview, using the
+       structure font so it reads as prose rather than code. */
     font-size: 0.85em;
     line-height: 1.35;
     color: var(--verso-muted-color, #555);
diff --git a/static-web/manual/theme/theme-picker.js b/static-web/manual/theme/theme-picker.js
index 8580fa61a..85d049771 100644
--- a/static-web/manual/theme/theme-picker.js
+++ b/static-web/manual/theme/theme-picker.js
@@ -4,7 +4,13 @@
  * server-side as static HTML). Reads `window.versoThemes`, populates the dropdowns,
  * persists choices to localStorage, and live-previews on hover/focus. The inline head
  * script in `verso-themes.css`-paired no-flash block already set the initial theme;
- * this file only handles user interaction. */
+ * this file only handles user interaction.
+ *
+ * Controls: an "Appearance" radio group (Light / Dark / Follow system) chooses the mode, and a
+ * collapsible "Theme choices" section holds a Light-theme and a Dark-theme dropdown. The mode
+ * is stored in `verso-theme-mode` ("light" | "dark" | "auto"); the two theme choices in
+ * `verso-theme-light` / `verso-theme-dark`. A new reader with nothing stored starts on
+ * `data.defaultMode` (the author-configured default, "auto" unless overridden). */
 
 (function () {
     "use strict";
@@ -52,6 +58,10 @@
         }
     }
 
+    function prefersDark() {
+        return !!(window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches);
+    }
+
     function applyTheme(id) {
         var t = data.themes.find(function (x) {
             return x.id === id;
@@ -106,29 +116,11 @@
         });
         var hasMixed = lightThemes.length > 0 && darkThemes.length > 0;
 
-        // "Match system" toggle, only when there's a mix of light and dark.
-        var modeRow = document.createElement("div");
-        modeRow.className = "theme-picker-row";
-        var modeLabel = document.createElement("label");
-        modeLabel.setAttribute("for", "theme-picker-mode");
-        modeLabel.textContent = "Match system";
-        var modeToggle = document.createElement("input");
-        modeToggle.type = "checkbox";
-        modeToggle.id = "theme-picker-mode";
-        modeToggle.checked = (readMode() || "auto") === "auto";
-        modeRow.appendChild(modeToggle);
-        modeRow.appendChild(modeLabel);
-        if (hasMixed) dialog.appendChild(modeRow);
-
-        // Appearance-scoped defaults: a theme is "the default" relative to a given dropdown.
-        // The light dropdown marks `defaultLight`; the dark dropdown marks `defaultDark`. The
-        // single-mode dropdown marks `defaultSingle` — the theme an author chose for readers
-        // who do not follow the system (either `defaultLight` or `defaultDark`, configured via
-        // `defaultSingleAppearance` on `RenderConfig`).
+        // A theme is "the default" relative to a given appearance: the light dropdown marks
+        // `defaultLight`, the dark dropdown marks `defaultDark`.
         function isDefault(t, scope) {
             if (scope === "dark") return t.id === data.defaultDark;
-            if (scope === "light") return t.id === data.defaultLight;
-            return t.id === data.defaultSingle;
+            return t.id === data.defaultLight;
         }
 
         function makeSelect(id, labelText, items, selected, scope) {
@@ -151,31 +143,138 @@
             return { row: row, select: s };
         }
 
-        var singleSel = makeSelect(
-            "theme-picker-single",
-            "Theme",
-            sortedThemes,
-            readKey("verso-theme-single") || data.defaultSingle,
-            "single",
-        );
-        var lightSel = makeSelect(
-            "theme-picker-light",
-            "Light",
-            lightThemes,
-            readKey("verso-theme-light") || data.defaultLight,
-            "light",
-        );
-        var darkSel = makeSelect(
-            "theme-picker-dark",
-            "Dark",
-            darkThemes,
-            readKey("verso-theme-dark") || data.defaultDark,
-            "dark",
-        );
-
-        dialog.appendChild(singleSel.row);
-        dialog.appendChild(lightSel.row);
-        dialog.appendChild(darkSel.row);
+        // `getActive` returns the theme id the current control state selects; `commit` persists
+        // the choices and applies the active theme. Both are wired up per layout below.
+        var getActive;
+        var commit;
+
+        if (hasMixed) {
+            // Appearance: a Light / Dark / Follow system radio group.
+            var modeGroup = document.createElement("fieldset");
+            modeGroup.id = "theme-picker-mode";
+            var modeLegend = document.createElement("legend");
+            modeLegend.textContent = "Appearance";
+            modeGroup.appendChild(modeLegend);
+            var modeOptions = document.createElement("div");
+            modeOptions.className = "theme-picker-radios";
+            var currentMode = readMode() || data.defaultMode || "auto";
+            var modeInputs = [];
+            [
+                ["light", "Light"],
+                ["dark", "Dark"],
+                ["auto", "Follow system"],
+            ].forEach(function (m) {
+                var wrap = document.createElement("label");
+                wrap.className = "theme-picker-radio";
+                var input = document.createElement("input");
+                input.type = "radio";
+                input.name = "verso-appearance";
+                input.value = m[0];
+                input.id = "theme-picker-mode-" + m[0];
+                if (m[0] === currentMode) input.checked = true;
+                var span = document.createElement("span");
+                span.textContent = m[1];
+                wrap.appendChild(input);
+                wrap.appendChild(span);
+                modeOptions.appendChild(wrap);
+                modeInputs.push(input);
+            });
+            modeGroup.appendChild(modeOptions);
+            dialog.appendChild(modeGroup);
+
+            function currentModeValue() {
+                for (var i = 0; i < modeInputs.length; i++) {
+                    if (modeInputs[i].checked) return modeInputs[i].value;
+                }
+                return "auto";
+            }
+
+            // Collapsible light/dark theme choices. Expanded by default only when the reader has
+            // moved either choice off its default, so the common case stays a one-line picker.
+            var details = document.createElement("details");
+            details.id = "theme-picker-choices";
+            var summary = document.createElement("summary");
+            summary.textContent = "Theme choices";
+            details.appendChild(summary);
+
+            var lightSel = makeSelect(
+                "theme-picker-light",
+                "Light",
+                lightThemes,
+                readKey("verso-theme-light") || data.defaultLight,
+                "light",
+            );
+            var darkSel = makeSelect(
+                "theme-picker-dark",
+                "Dark",
+                darkThemes,
+                readKey("verso-theme-dark") || data.defaultDark,
+                "dark",
+            );
+            details.appendChild(lightSel.row);
+            details.appendChild(darkSel.row);
+            details.open =
+                lightSel.select.value !== data.defaultLight ||
+                darkSel.select.value !== data.defaultDark;
+            dialog.appendChild(details);
+
+            getActive = function () {
+                var mode = currentModeValue();
+                if (mode === "light") return lightSel.select.value;
+                if (mode === "dark") return darkSel.select.value;
+                return prefersDark() ? darkSel.select.value : lightSel.select.value;
+            };
+            commit = function () {
+                writeMode(currentModeValue());
+                writeKey("verso-theme-light", lightSel.select.value);
+                writeKey("verso-theme-dark", darkSel.select.value);
+                var id = getActive();
+                applyTheme(id);
+                trackedCommitted = id;
+            };
+
+            modeInputs.forEach(function (input) {
+                input.addEventListener("change", function () {
+                    commit();
+                    refreshAbout();
+                });
+            });
+            [lightSel.select, darkSel.select].forEach(function (sel) {
+                sel.addEventListener("change", function () {
+                    commit();
+                    refreshAbout();
+                });
+            });
+        } else {
+            // Single-appearance fallback: only one of light/dark themes exists, so there is no
+            // appearance choice to make. (In practice the available set always contains both a
+            // light and a dark default, so this path is defensive.)
+            var only = lightThemes.length ? lightThemes : darkThemes;
+            var scope = lightThemes.length ? "light" : "dark";
+            var soleSel = makeSelect(
+                "theme-picker-single",
+                "Theme",
+                only,
+                readKey("verso-theme-" + scope) ||
+                    (scope === "light" ? data.defaultLight : data.defaultDark),
+                scope,
+            );
+            dialog.appendChild(soleSel.row);
+
+            getActive = function () {
+                return soleSel.select.value;
+            };
+            commit = function () {
+                writeMode(scope);
+                writeKey("verso-theme-" + scope, soleSel.select.value);
+                applyTheme(soleSel.select.value);
+                trackedCommitted = soleSel.select.value;
+            };
+            soleSel.select.addEventListener("change", function () {
+                commit();
+                refreshAbout();
+            });
+        }
 
         var preview = document.createElement("div");
         preview.id = "theme-picker-preview";
@@ -213,14 +312,7 @@
         dialog.appendChild(about);
 
         function activeMetaTheme() {
-            var prefersDark =
-                window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches;
-            var id;
-            if (modeToggle.checked) {
-                id = prefersDark ? darkSel.select.value : lightSel.select.value;
-            } else {
-                id = singleSel.select.value;
-            }
+            var id = getActive();
             return data.themes.find(function (t) {
                 return t.id === id;
             });
@@ -252,72 +344,32 @@
             }
             about.hidden = aboutDesc.hidden && aboutLink.hidden;
         }
+        refreshAbout();
 
-        function refreshLayout() {
-            var auto = modeToggle.checked;
-            singleSel.row.hidden = auto;
-            lightSel.row.hidden = !auto;
-            darkSel.row.hidden = !auto;
-            refreshAbout();
-        }
-        refreshLayout();
-
-        // The auto-mode active theme is the dropdown that matches the current
-        // `prefers-color-scheme`. Distinct from `committedActiveId()`, which reads the visible
-        // `data-verso-theme` and is only meaningful for cancel/revert paths.
-        function activeAutoThemeId() {
-            var prefersDark =
-                window.matchMedia && window.matchMedia("(prefers-color-scheme: dark)").matches;
-            return prefersDark ? darkSel.select.value : lightSel.select.value;
-        }
-
-        function commit() {
-            var newId;
-            if (modeToggle.checked) {
-                writeMode("auto");
-                writeKey("verso-theme-light", lightSel.select.value);
-                writeKey("verso-theme-dark", darkSel.select.value);
-                newId = activeAutoThemeId();
-            } else {
-                writeMode("single");
-                writeKey("verso-theme-single", singleSel.select.value);
-                newId = singleSel.select.value;
-            }
-            applyTheme(newId);
-            trackedCommitted = newId;
-        }
-
-        function previewTheme(id) {
-            if (id) applyTheme(id);
-        }
-
-        modeToggle.addEventListener("change", function () {
-            refreshLayout();
-            commit();
-        });
-        [singleSel.select, lightSel.select, darkSel.select].forEach(function (sel) {
-            sel.addEventListener("change", function () {
-                commit();
-                refreshAbout();
-            });
-            // No focus/hover preview: the picker commits immediately on `change`, so the
-            // user already gets visible feedback when they pick an option. Firing a
-            // preview on `focus` (or `mouseenter`) painted a stale "what's selected right
-            // now in this dropdown" theme between the user opening the dropdown and
-            // committing a new value — a perceivable mid-switch flash to the dropdown's
-            // current default or to the opposite-mode theme. Escape and outside-click
-            // still revert any in-flight preview, so a future re-introduction can hook
-            // back in here once the preview-vs-commit semantics are stabilised.
-        });
+        // The picker commits immediately on `change`, so the user already gets visible feedback
+        // when they pick an option. There is no focus/hover preview: firing a preview on `focus`
+        // painted a stale "what's selected right now in this dropdown" theme between the user
+        // opening the dropdown and committing a new value — a perceivable mid-switch flash.
+        // Escape and outside-click still revert any in-flight preview, so a future
+        // re-introduction can hook back in here once the preview-vs-commit semantics are
+        // stabilised.
 
         document.body.appendChild(dialog);
     }
 
     function focusable() {
         return Array.from(
-            dialog.querySelectorAll("select, input, button, [tabindex]:not([tabindex='-1'])"),
+            dialog.querySelectorAll(
+                "select, input, button, summary, a[href], [tabindex]:not([tabindex='-1'])",
+            ),
         ).filter(function (el) {
-            return !el.hidden && !el.disabled;
+            if (el.hidden || el.disabled || el.offsetParent === null) return false;
+            // A collapsed <details> drops its content from the tab order, but the controls
+            // inside still report a non-null `offsetParent`. Exclude them explicitly so the
+            // trap's last element is the summary, not an unreachable select — otherwise Tab
+            // walks past the summary toward those phantom controls and escapes the dialog.
+            if (el.tagName !== "SUMMARY" && el.closest("details:not([open])")) return false;
+            return true;
         });
     }