@brandon_m_behring/book-scaffold-astro 4.10.0 → 4.11.0

package/CLAUDE.md

@@ -166,9 +166,16 @@ See `recipes/09-validation.md` to extend.
 
 ### Add a figure
 
-1. Drop PDF in `figures/<topic>/<name>.pdf` (or set `BOOK_FIGURES_PATH`).
+1. Drop a PDF in `figures/<topic>/<name>.pdf`, or a TikZ standalone `.tex` (auto-compiled), or set `BOOK_FIGURES_PATH`.
 2. `npm run build:figures` produces `public/figures/<topic>/<name>.svg`.
-3. Reference: `<Figure src="/figures/<topic>/<name>.svg" caption="..." id="..." />`.
+3. Reference: `<Figure src="/figures/<topic>/<name>.svg" caption="..." alt="..." id="..." />`.
+
+**Accessibility + dark mode (v4.11.0, #84).** `build:figures` rewrites every generated SVG so one file serves both themes: it adds `role="img"` and remaps the *neutral* fills/strokes to `var(--diagram-ink|paper|grid, <original>)` (saturated accent colors are left as authored). `<Figure>` **inlines** a local `.svg` (vs `<img>`), so the page's `--diagram-*` tokens cascade in and the figure tracks the in-page dark-mode toggle; `caption`/`alt`/`desc` become the SVG's `<title>`/`<desc>`. Notes:
+
+- `alt` is the short accessible name (defaults to `caption`); `desc` is an optional longer description.
+- Non-SVG (`.png` fallback), remote, or unreadable `src` keep the `<img>` render.
+- Opt a figure out of theming with a `%! no-theme` line in its source `.tex`.
+- After upgrading, re-run `npm run build:figures` to theme pre-existing figures (the rewrite is idempotent).
 
 ### Add a new component
 

package/bin/book-scaffold.mjs

@@ -29,6 +29,7 @@ Sub-commands:
   build-labels       Emit src/data/labels.json for cross-references (Phase C).
   build-bib          BibTeX -> references.json (+ sources/manifest.yaml -> sources.json).
   build-figures      PDF -> SVG via pdftocairo / pdftoppm fallback (+ TikZ in v4.2.0).
+                     Each SVG gets role="img" + dark-mode var(--diagram-*) fills (v4.11.0).
   build-tips         Scan chapters for <Tip> instances; emit src/data/tips.json (v4.3.0).
   build-exercises    Scan chapters for <Exercise> instances; emit src/data/exercises.json (v4.4.0).
   render-notebooks   ipynb -> HTML via Jupyter nbconvert.

package/components/Figure.astro

@@ -4,13 +4,22 @@
  * `\label{...}` pattern with a single component.
  *
  * Source assets are emitted under public/figures/weekNN/ by
- * scripts/build-figures.sh (Phase 2.4); src paths are absolute from
- * site root.
+ * scripts/build-figures.mjs; src paths are absolute from site root.
+ *
+ * v4.11.0 (#84): a local pipeline `.svg` is **inlined** (read from public/ +
+ * `set:html`) rather than referenced via `<img>`. Inlining puts the SVG in the
+ * host DOM, so the page's tokens.css `--diagram-*` cascade in — the figure
+ * tracks the in-page dark-mode toggle (an `<img>`-loaded SVG is CSS-isolated
+ * and could only follow the OS preference). Inlining also lets a11y
+ * `<title>`/`<desc>` come from this component's props (assembleSvg). Non-SVG
+ * (the pdftoppm `.png` fallback), remote, or unreadable `src` gracefully keep
+ * the `<img>` render — a figure must never crash a build.
  *
  * Usage:
  *   <Figure
  *     src="/figures/week04/ex2_hippo_eigenvalues.svg"
  *     caption="HiPPO-LegS eigenvalue structure for N = 16 and N = 64."
+ *     alt="Two overlaid eigenvalue spectra forming nested arcs."
  *     width="100%"
  *     id="w4-fig-hippo-eigenvalues"
  *   />
@@ -18,18 +27,41 @@
  * The id prop registers the figure with the cross-reference label map
  * (consumed by `<XRef>`).
  */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { shouldInline, assembleSvg } from '../src/lib/figure.mjs';
+
 interface Props {
   src: string;
   caption?: string;
   width?: string;
   id?: string;
   alt?: string;
+  /** Long-form description → SVG <desc> (alt stays the short accessible name). */
+  desc?: string;
 }
 
-const { src, caption, width = '100%', id, alt } = Astro.props;
+const { src, caption, width = '100%', id, alt, desc } = Astro.props;
 const altText = alt ?? caption ?? '';
+
+// Inline a local pipeline SVG so host CSS variables theme it + a11y nodes come
+// from props. Any read failure falls back to <img> below (never throws).
+let inlineSvg: string | null = null;
+if (shouldInline(src)) {
+  try {
+    const raw = readFileSync(join(process.cwd(), 'public', src), 'utf8');
+    const idBase = id ?? `fig-${src.replace(/^\/+/, '').replace(/\.[^.]+$/, '')}`;
+    inlineSvg = assembleSvg(raw, { caption, alt, desc, width, idBase });
+  } catch {
+    inlineSvg = null;
+  }
+}
 ---
 <figure class="figure" id={id}>
-  <img src={src} alt={altText} style={`width: ${width}; max-width: 100%;`} />
+  {inlineSvg ? (
+    <Fragment set:html={inlineSvg} />
+  ) : (
+    <img src={src} alt={altText} style={`width: ${width}; max-width: 100%;`} />
+  )}
   {caption && <figcaption>{caption}</figcaption>}
 </figure>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books. Profile-aware (academic / tools / minimal); ships Tufte typography, KaTeX, BibTeX citations, Pagefind, Cloudflare Workers deploy. See PACKAGE_DESIGN.md for the API contract.",
-  "version": "4.10.0",
+  "version": "4.11.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",

package/recipes/04-component-library.md

@@ -64,7 +64,7 @@ Supported `type` values: `theorem`, `proposition`, `lemma`, `corollary`, `defini
 |---|---|---|
 | `Cite` | Inline citation linked to `/references` | `<Cite key="gu2024mamba" page="3" />` |
 | `XRef` | Cross-reference to a labeled element | `<XRef id="thm:zoh-stability" />` |
-| `Figure` | Image + caption + id | `<Figure src="/figures/week04/eigenvalues.svg" caption="…" id="fig-eig" />` |
+| `Figure` | Image/SVG + caption + id; local SVGs inline for a11y + dark mode (`alt`, `desc`) | `<Figure src="/figures/week04/eigenvalues.svg" caption="…" alt="…" id="fig-eig" />` |
 | `MarginNote` | Right-margin annotation (Tufte-style) | `<MarginNote>side comment</MarginNote>` |
 | `Sidenote` | Auto-numbered marginalia | `<Sidenote>numbered note</Sidenote>` |
 | `WeekRef` | Jump-link to a week chapter | `<WeekRef week={4} />` |

package/scripts/build-figures.mjs

@@ -23,7 +23,17 @@
  * Falls back to pdftoppm (PNG @ 200 DPI) if pdftocairo produces an
  * unreasonably small (likely malformed) SVG.
  *
- * Idempotent: skips when the target SVG is newer than the source PDF.
+ * v4.11.0 (closes #84): each generated SVG gets a post-export rewrite
+ * (recolorSvg) that injects role="img" + a CSS-variable theming layer so one
+ * SVG serves light + dark. Neutral fills/strokes are remapped to
+ * var(--diagram-ink|paper|grid, <original>) via injected attribute-selector
+ * rules (the original attribute stays as the fallback); saturated accent colors
+ * are left untouched. A `%! no-theme` line in the source .tex opts a figure out.
+ * <Figure> inlines local SVGs so they track the in-page [data-theme] toggle.
+ *
+ * Idempotent: skips when the target SVG is newer than the source PDF (and the
+ * recolor itself is a no-op on an already-themed SVG, so re-runs after an
+ * upgrade safely theme pre-existing figures).
  * Run on `prebuild` so Astro always sees fresh figures.
  *
  * Graceful skip: when pdftocairo / pdftoppm aren't on PATH (e.g. Cloudflare
@@ -32,10 +42,11 @@
  * from PDFs on every `npm run dev`.
  */
 import { readdir, stat, mkdir } from 'node:fs/promises';
-import { existsSync, statSync } from 'node:fs';
+import { existsSync, statSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
+import { recolorSvg } from '../src/lib/figure.mjs';
 
 // --help / -h: non-mutating (closes #14).
 const USAGE = `Usage: book-scaffold build-figures
@@ -44,6 +55,10 @@ Figure pipeline. PDF -> SVG via pdftocairo (PNG fallback via pdftoppm at
 200dpi). Walks figures/ (or BOOK_FIGURES_PATH), emits to public/figures/.
 Graceful-skip if pdftocairo / pdftoppm not on PATH.
 
+Each SVG is rewritten to be accessible + dark-mode-aware: role="img" plus
+var(--diagram-ink|paper|grid, orig) fills (a "%! no-theme" line in the
+source .tex opts out). <Figure> inlines local SVGs so they track the theme.
+
 Env:
   BOOK_FIGURES_PATH   Override figures source (default: figures/).
 
@@ -179,6 +194,25 @@ function convertToSvg(srcPath, dstPath) {
   return size >= MIN_SVG_BYTES;
 }
 
+// v4.11.0 (#84): a `%! no-theme` line (anywhere in the source .tex) opts a
+// figure out of the dark-mode/a11y rewrite. Matches `%!` then `no-theme`,
+// tolerant of surrounding whitespace — distinct from BibTeX `%`-line comments.
+const NO_THEME_RE = /^\s*%!\s*no-theme\b/m;
+
+/**
+ * v4.11.0 (#84): apply the theming rewrite to a generated SVG in place.
+ * No-op (returns false) if the file is absent or recolorSvg leaves it unchanged
+ * (already themed / nothing neutral to remap). Idempotent.
+ */
+function themeIfSvg(svgPath, optOut) {
+  if (!existsSync(svgPath)) return false;
+  const original = readFileSync(svgPath, 'utf8');
+  const themed = recolorSvg(original, { optOut });
+  if (themed === original) return false;
+  writeFileSync(svgPath, themed, 'utf8');
+  return true;
+}
+
 function convertToPng(srcPath, pngStem) {
   // pdftoppm: -r 200 (DPI), -png, single page (first only).
   const r = spawnSync(
@@ -251,6 +285,7 @@ async function main() {
   let converted = 0;
   let skipped = 0;
   let pngFallback = 0;
+  let themed = 0;
 
   for (const { relPath } of pdfs) {
     total++;
@@ -259,7 +294,20 @@ async function main() {
     const svgPath = resolve(FIGURES_DST, `${stem}.svg`);
     const pngPath = resolve(FIGURES_DST, `${stem}.png`);
 
-    if (isUpToDate(srcPath, svgPath) || isUpToDate(srcPath, pngPath)) {
+    // Opt-out via `%! no-theme` in the source .tex (TikZ figures only).
+    const texSibling = resolve(FIGURES_SRC, `${stem}.tex`);
+    const optOut =
+      existsSync(texSibling) && NO_THEME_RE.test(readFileSync(texSibling, 'utf8'));
+
+    // Cached SVG: still run the (idempotent) rewrite so an upgrade themes
+    // pre-existing figures without forcing a source touch. PNG fallbacks are
+    // raster — nothing to theme.
+    if (isUpToDate(srcPath, svgPath)) {
+      if (themeIfSvg(svgPath, optOut)) themed++;
+      skipped++;
+      continue;
+    }
+    if (isUpToDate(srcPath, pngPath)) {
       skipped++;
       continue;
     }
@@ -269,14 +317,17 @@ async function main() {
     if (!svgOK) {
       convertToPng(srcPath, svgPath.replace(/\.svg$/, ''));
       pngFallback++;
+    } else if (themeIfSvg(svgPath, optOut)) {
+      themed++;
     }
     converted++;
   }
 
   const tikzNote = tikzCompiled > 0 ? `, ${tikzCompiled} tikz→pdf` : '';
+  const themedNote = themed > 0 ? `, ${themed} themed` : '';
   console.log(
     `build-figures: ${total} total, ${converted} converted ` +
-      `(${pngFallback} png fallback), ${skipped} cached${tikzNote}`,
+      `(${pngFallback} png fallback), ${skipped} cached${themedNote}${tikzNote}`,
   );
 }
 

package/src/lib/figure.mjs

@@ -0,0 +1,245 @@
+/**
+ * src/lib/figure.mjs — pure SVG transforms for the figure pipeline (v4.11.0, #84).
+ *
+ * Two concerns, one module so the `data-diagram-*` sentinels stay DRY:
+ *
+ *   • BUILD side — `recolorSvg()` rewrites a pdftocairo SVG to be theme-aware
+ *     (called by scripts/build-figures.mjs after each PDF→SVG conversion).
+ *   • RENDER side — `shouldInline()` + `assembleSvg()` let Figure.astro inline a
+ *     local pipeline SVG with a11y <title>/<desc> from the <Figure> props.
+ *
+ * Why a stylesheet, not presentation attributes: `var()` inside a presentation
+ * attribute (`fill="var(--x, …)"`) has unreliable browser support, whereas
+ * `var()` in a real <style> rule is universal. So `recolorSvg` injects an
+ * attribute-selector rule per distinct neutral color and never mutates a
+ * drawing element — the untouched `fill=""`/`stroke=""` attribute is the
+ * automatic fallback where `var()` is unsupported.
+ *
+ * Why inline (vs <img>): an SVG loaded via <img> is CSS-isolated, so a host
+ * page's `var(--diagram-*)` cannot reach it — it could only follow the OS
+ * prefers-color-scheme via the embedded <style data-diagram-theme>. Inlining
+ * puts the SVG in the host DOM, so the host's tokens.css (which tracks the
+ * in-page [data-theme] toggle) themes it. `assembleSvg` therefore STRIPS the
+ * embedded theme block so the host is the sole source of --diagram-*.
+ *
+ * Pure string ops only — no `node:` imports — so the module bundles for any
+ * consumer (Figure.astro imports it; fs lives in the .astro/.mjs callers).
+ */
+
+// Standalone self-theming defaults: used only when the SVG is NOT inlined
+// (direct file open / <img>). Hex literals because host CSS vars don't exist
+// there. Mirrors styles/tokens.css light + dark neutral values.
+export const DIAGRAM_THEME_CSS =
+  ':root{--diagram-ink:#1A1A19;--diagram-paper:#FDFCF9;--diagram-grid:#B5B3AA}' +
+  '@media (prefers-color-scheme:dark){:root{' +
+  '--diagram-ink:#E8E5DD;--diagram-paper:#1A1816;--diagram-grid:#3A3632}}';
+
+const DIAGRAM_VAR = {
+  ink: '--diagram-ink',
+  paper: '--diagram-paper',
+  grid: '--diagram-grid',
+};
+
+/**
+ * Parse a solid SVG paint into {r,g,b} in [0,1], or null when it is not a
+ * concrete color we should remap (none / url(...) / currentColor / inherit).
+ * Handles pdftocairo's `rgb(R%, G%, B%)` plus `rgb(r,g,b)` and #hex for safety.
+ */
+export function parseColor(value) {
+  if (typeof value !== 'string') return null;
+  const v = value.trim();
+  let m;
+  if ((m = v.match(/^rgb\(\s*([\d.]+)%\s*,\s*([\d.]+)%\s*,\s*([\d.]+)%\s*\)$/i))) {
+    return { r: +m[1] / 100, g: +m[2] / 100, b: +m[3] / 100 };
+  }
+  if ((m = v.match(/^rgb\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*\)$/i))) {
+    return { r: +m[1] / 255, g: +m[2] / 255, b: +m[3] / 255 };
+  }
+  if ((m = v.match(/^#([0-9a-f]{3})$/i))) {
+    const [a, b, c] = m[1];
+    return { r: parseInt(a + a, 16) / 255, g: parseInt(b + b, 16) / 255, b: parseInt(c + c, 16) / 255 };
+  }
+  if ((m = v.match(/^#([0-9a-f]{6})$/i))) {
+    return {
+      r: parseInt(m[1].slice(0, 2), 16) / 255,
+      g: parseInt(m[1].slice(2, 4), 16) / 255,
+      b: parseInt(m[1].slice(4, 6), 16) / 255,
+    };
+  }
+  return null;
+}
+
+/**
+ * Classify a color as 'ink' | 'paper' | 'grid', or null to leave it untouched.
+ * Saturated colors (chroma over threshold) are intentional accents and keep
+ * their hue across themes; only near-neutral colors are remapped, split by
+ * relative luminance into dark ink / light paper / mid gridlines.
+ */
+export function classifyColor(value) {
+  const c = parseColor(value);
+  if (!c) return null;
+  const chroma = Math.max(c.r, c.g, c.b) - Math.min(c.r, c.g, c.b);
+  if (chroma > 0.12) return null; // saturated accent — preserve as authored
+  const lum = 0.2126 * c.r + 0.7152 * c.g + 0.0722 * c.b;
+  if (lum < 0.3) return 'ink';
+  if (lum > 0.9) return 'paper';
+  return 'grid';
+}
+
+// Escape a value for use inside a CSS [attr="…"] selector string.
+function cssAttrEscape(s) {
+  return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+/**
+ * Rewrite a pdftocairo SVG to be theme-aware + carry role="img". Pure and
+ * idempotent (a second pass is a no-op). `opts.optOut` short-circuits, returning
+ * the input unchanged (the `%! no-theme` authoring escape hatch).
+ *
+ * Injects, right after the opening <svg> tag:
+ *   <style data-diagram-theme> — standalone var defaults + @media(dark).
+ *   <style data-diagram-map>   — `[fill="C"]{fill:var(--diagram-X, C)}` … per
+ *                                 distinct neutral color C. Elements are NOT
+ *                                 modified; the attribute stays as fallback.
+ */
+export function recolorSvg(svg, { optOut = false } = {}) {
+  if (typeof svg !== 'string') return svg;
+  if (optOut || svg.includes('data-diagram-map')) return svg;
+
+  const openMatch = svg.match(/<svg\b[^>]*>/i);
+  if (!openMatch) return svg;
+
+  // Distinct concrete colors used as fill="" / stroke="" attributes.
+  const found = new Map(); // original string → class
+  const attrRe = /\b(?:fill|stroke)="([^"]+)"/g;
+  let am;
+  while ((am = attrRe.exec(svg)) !== null) {
+    if (found.has(am[1])) continue;
+    const cls = classifyColor(am[1]);
+    if (cls) found.set(am[1], cls);
+  }
+
+  let openTag = openMatch[0];
+  if (!/\srole=/i.test(openTag)) openTag = openTag.replace(/<svg\b/i, '<svg role="img"');
+
+  // Nothing neutral to remap — still surface role="img" for a11y, no <style>.
+  if (found.size === 0) {
+    return openTag === openMatch[0]
+      ? svg
+      : svg.slice(0, openMatch.index) + openTag + svg.slice(openMatch.index + openMatch[0].length);
+  }
+
+  let mapCss = '';
+  for (const [orig, cls] of found) {
+    const v = DIAGRAM_VAR[cls];
+    const sel = cssAttrEscape(orig);
+    mapCss +=
+      `[fill="${sel}"]{fill:var(${v}, ${orig})}` +
+      `[stroke="${sel}"]{stroke:var(${v}, ${orig})}`;
+  }
+
+  const styleBlocks =
+    `<style data-diagram-theme>${DIAGRAM_THEME_CSS}</style>` +
+    `<style data-diagram-map>${mapCss}</style>`;
+
+  return (
+    svg.slice(0, openMatch.index) +
+    openTag +
+    styleBlocks +
+    svg.slice(openMatch.index + openMatch[0].length)
+  );
+}
+
+// ── Render side ────────────────────────────────────────────────────────────
+
+/** Should <Figure> inline `src` (local pipeline .svg) vs render <img>? */
+export function shouldInline(src) {
+  return (
+    typeof src === 'string' &&
+    src.startsWith('/') &&
+    !src.startsWith('//') && // protocol-relative = remote host
+    /\.svg$/i.test(src)
+  );
+}
+
+const THEME_BLOCK_RE = /<style\b[^>]*\bdata-diagram-theme\b[^>]*>[\s\S]*?<\/style>/gi;
+
+/** Remove the standalone self-theming block so the host tokens.css is the sole
+ *  source of --diagram-* once the SVG is inlined into the page. */
+export function stripThemeBlock(svg) {
+  return typeof svg === 'string' ? svg.replace(THEME_BLOCK_RE, '') : svg;
+}
+
+function escapeXml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function ensureSvgAttr(openTag, name, value) {
+  const re = new RegExp(`\\s${name}=`, 'i');
+  if (re.test(openTag)) return openTag;
+  return openTag.replace(/<svg\b/i, `<svg ${name}="${value}"`);
+}
+
+function setSvgAttr(openTag, name, value) {
+  const re = new RegExp(`\\s${name}="[^"]*"`, 'i');
+  if (re.test(openTag)) return openTag.replace(re, ` ${name}="${value}"`);
+  return openTag.replace(/<svg\b/i, `<svg ${name}="${value}"`);
+}
+
+function mergeSvgStyle(openTag, css) {
+  const re = /\sstyle="([^"]*)"/i;
+  const m = openTag.match(re);
+  if (m) {
+    const existing = m[1].trim().replace(/;\s*$/, '');
+    return openTag.replace(re, ` style="${existing ? existing + ';' : ''}${css}"`);
+  }
+  return openTag.replace(/<svg\b/i, `<svg style="${css}"`);
+}
+
+/**
+ * Prepare a raw pipeline SVG for inline embedding in <Figure>:
+ *   - strip the standalone <style data-diagram-theme> (host tokens.css themes it);
+ *   - replace any pre-existing <title>/<desc> with ones from the call-site props
+ *     (caption → <title>, desc ?? alt → <desc>) and wire aria-labelledby;
+ *   - ensure role="img" and a responsive width on the root <svg>.
+ * Pure string transform; output is a trusted local build artifact (set:html).
+ */
+export function assembleSvg(raw, opts = {}) {
+  const { caption, alt, desc, width = '100%', idBase = 'figure' } = opts;
+  if (typeof raw !== 'string') return '';
+
+  let svg = stripThemeBlock(raw);
+  const openMatch = svg.match(/<svg\b[^>]*>/i);
+  if (!openMatch) return svg;
+
+  let openTag = openMatch[0];
+  let body = svg
+    .slice(openMatch.index + openTag.length)
+    .replace(/<title\b[^>]*>[\s\S]*?<\/title>/gi, '')
+    .replace(/<desc\b[^>]*>[\s\S]*?<\/desc>/gi, '');
+
+  const titleText = caption ?? alt ?? '';
+  const descText = desc ?? (alt && alt !== titleText ? alt : '');
+  const id = String(idBase).replace(/[^a-zA-Z0-9_-]/g, '-');
+
+  const a11y = [];
+  const labelledby = [];
+  if (titleText) {
+    a11y.push(`<title id="${id}-title">${escapeXml(titleText)}</title>`);
+    labelledby.push(`${id}-title`);
+  }
+  if (descText) {
+    a11y.push(`<desc id="${id}-desc">${escapeXml(descText)}</desc>`);
+    labelledby.push(`${id}-desc`);
+  }
+
+  openTag = ensureSvgAttr(openTag, 'role', 'img');
+  if (labelledby.length) openTag = setSvgAttr(openTag, 'aria-labelledby', labelledby.join(' '));
+  openTag = mergeSvgStyle(openTag, `width:${width};max-width:100%;height:auto`);
+
+  return `${svg.slice(0, openMatch.index)}${openTag}${a11y.join('')}${body}`;
+}

package/styles/tokens.css

@@ -51,6 +51,15 @@
   --callout-worked:   var(--warm-plum);
   --callout-learn:    var(--warm-gold);
 
+  /* Diagram semantic roles (v4.11.0, #84): theme-aware TikZ→SVG figures.
+   * build-figures remaps an SVG's neutral fills/strokes to these via
+   * var(--diagram-*, <original>); <Figure> inlines the SVG so this cascade
+   * reaches it. They point at existing roles, so they auto-flip in dark mode
+   * (no dark-block edits) — ink↔text, paper↔page bg, grid↔border. */
+  --diagram-ink:      var(--color-text);
+  --diagram-paper:    var(--color-bg);
+  --diagram-grid:     var(--color-border);
+
   /* ===== Typography scale ===== */
   --font-body: 'Roboto Variable', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
   --font-code: 'Source Code Pro Variable', ui-monospace, SFMono-Regular, 'SF Mono', Menlo, monospace;