@brandon_m_behring/book-scaffold-astro 4.30.0 → 4.31.0

package/CLAUDE.md

@@ -229,9 +229,11 @@ See `recipes/09-validation.md` to extend.
 2. `npm run build:figures` produces `public/figures/<topic>/<name>.svg`.
 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:
+**Accessibility + dark mode (v4.11.0, #84; #161/#164).** `build:figures` rewrites every generated SVG so one file serves both themes: it adds `role="img"`, maps exact Warm–Tol authoring colors to semantic `--fig-*`, maps the seven chromatic Okabe–Ito colors to stable `--series-1..7`, and remaps neutral fills/strokes to the backward-compatible `--diagram-ink|paper|grid` aliases. Canonical series-8 black is indistinguishable from structural ink after PDF export; both resolve through `--fig-ink` in either theme. Unknown saturated colors stay authored. `<Figure>` **inlines** a local `.svg` (vs `<img>`), so the page's tokens cascade in and the figure tracks the in-page dark-mode toggle; `alt` (falling back to `caption`) becomes the SVG's accessible `<title>`, and `desc` becomes its optional longer `<desc>`. Notes:
 
 - `alt` is the short accessible name (defaults to `caption`); `desc` is an optional longer description.
+- For pale fills, export the canonical base color with a separate opacity (`fill opacity` / `alpha`), not a pre-blended tint such as `warmblue!13`; see `recipes/24-figure-authoring-standard.md`.
+- Use `--fig-*` for meaning and `--series-*` only for categorical ordinals. Always add a non-color cue (label, marker, dash, shape, or texture).
 - 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).

package/bin/book-scaffold.mjs

@@ -29,7 +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).
+                     Adds a11y + theme-aware semantic/categorical palette mappings.
   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

@@ -8,9 +8,9 @@
  *
  * 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
+ * host DOM, so tokens.css `--fig-*`, `--series-*`, and `--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.
@@ -29,7 +29,7 @@
  */
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { shouldInline, assembleSvg } from '../src/lib/figure.mjs';
+import { publicSvgPath, assembleSvg } from '../src/lib/figure.mjs';
 
 interface Props {
   src: string;
@@ -47,9 +47,10 @@ 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)) {
+const localSvgPath = publicSvgPath(src, import.meta.env.BASE_URL);
+if (localSvgPath) {
   try {
-    const raw = readFileSync(join(process.cwd(), 'public', src), 'utf8');
+    const raw = readFileSync(join(process.cwd(), 'public', localSvgPath), 'utf8');
     const idBase = id ?? `fig-${src.replace(/^\/+/, '').replace(/\.[^.]+$/, '')}`;
     inlineSvg = assembleSvg(raw, { caption, alt, desc, width, idBase });
   } catch {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books with five typed presets, Tufte typography, citations, search, PDF, and Cloudflare deployment.",
-  "version": "4.30.0",
+  "version": "4.31.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -174,6 +174,8 @@
   ],
   "scripts": {
     "build": "tsup",
+    "sync:figure-tokens": "node scripts/sync-figure-tokens.mjs --write",
+    "check:figure-tokens": "node scripts/sync-figure-tokens.mjs --check",
     "check:types": "tsc -p tests/types/tsconfig.json",
     "prepublishOnly": "npm run build && npm run check:types",
     "test": "node --test tests/*.test.mjs"

package/recipes/03-asset-pipelines.md

@@ -2,7 +2,12 @@
 
 **Profile**: any (build:figures and build:notebooks both graceful-skip when source dirs / tools are absent).
 
-**TL;DR**: Put PDFs in `figures/`, Jupyter notebooks in `notebooks/`. `npm run dev` / `npm run build` runs both pipelines via the `build:assets` prebuild hook. Output: `public/figures/*.svg` (PDF→SVG via `pdftocairo`) and `public/notebooks/*.html` (ipynb→HTML via `uv run jupyter nbconvert`).
+**TL;DR**: Put PDFs in `figures/`, Jupyter notebooks in `notebooks/`, then run
+`npm run build:figures` and `npm run build:notebooks` explicitly. Output:
+`public/figures/*.svg` (PDF→SVG via `pdftocairo`) and
+`public/notebooks/*.html` (ipynb→HTML via `uv run jupyter nbconvert`). These
+optional system-tool pipelines are not part of `prebuild`; generated books run
+validation there instead.
 
 ## How each pipeline works
 
@@ -11,6 +16,7 @@
 - **Source**: `figures/` at scaffold root (override via `BOOK_FIGURES_PATH` env var; e.g. `BOOK_FIGURES_PATH=../shared/figures` to share with a LaTeX sibling)
 - **Output**: `public/figures/<same-subdir-structure>/<stem>.svg`
 - **Tool**: `pdftocairo` (poppler-utils) with `pdftoppm` fallback for malformed SVG
+- **Theming**: canonical Warm–Tol / Okabe–Ito colors and neutral paints are mapped to theme-aware CSS variables; see [Recipe 24](24-figure-authoring-standard.md)
 - **Idempotency**: skips when SVG mtime >= PDF mtime
 - **Graceful skip**: if `pdftocairo` or `pdftoppm` not on PATH (Cloudflare build container), warns and exits 0 — committed SVGs under `public/figures/` are served as-is
 
@@ -58,8 +64,9 @@ Cloudflare Workers build containers don't have `pdftocairo` or `uv` installed. T
 
 1. **Commit derived artifacts** (recommended for low-friction deploy):
    - Edit `.gitignore`: remove the `public/figures/` and `public/notebooks/` lines.
-   - Run `npm run build:assets` locally; commit the generated outputs.
-   - CI's prebuild gracefully skips (tools missing), serves committed artifacts.
+   - Run `npm run build:figures` and `npm run build:notebooks` locally; commit
+     the generated outputs.
+   - CI serves the committed artifacts without needing either optional system tool.
    - Trade-off: ~3 MB of binary artifacts in git history.
 
 2. **Install poppler + uv in CI**: prepend `apt-get install -y poppler-utils && curl -LsSf https://astral.sh/uv/install.sh | sh && ...` to the build command. More setup; cleaner repo.
@@ -71,12 +78,13 @@ post_transformers chose option 1 (see commit `f7fa75d`).
 - **Notebooks should be output-free** for a clean rendered HTML — clear outputs before committing, or use `nbstripout` as a pre-commit hook. Cells with embedded outputs render those outputs in the HTML; this may or may not be what you want.
 - **Stub-size threshold** at 1500 bytes is empirical from post_transformers — adjust via `NOTEBOOK_STUB_BYTES` if your placeholder notebooks are larger.
 - **`pdftocairo` produces a tiny SVG** for some PDF inputs (vector layers ungrouped, etc.). The script auto-falls back to `pdftoppm -r 200 -png` at 200 DPI when SVG output is < 200 bytes.
+- **Do not pre-blend semantic fills** (`warmblue!13`, for example). Export the canonical base color with a separate opacity so the SVG rewrite can preserve its role in dark mode. Recipe 24 has TikZ and matplotlib examples.
 
 ## Canonical files
 
 - `scripts/build-figures.mjs:23-32` — path resolution + env overrides
 - `scripts/render-notebooks.mjs:30-46` — same
-- `package.json` `prebuild` / `predev` / `build:assets` — orchestration
+- `package.json` `build:figures` / `build:notebooks` — explicit authoring commands
 - `.gitignore` — toggles whether artifacts are committed
 
 ## Reference implementation

package/recipes/16-tikz-figures.md

@@ -4,7 +4,11 @@
 
 ## TL;DR
 
-Drop `figures/<topic>/diagram.tex` (standalone TikZ source). Run `npm run build:figures` (or it's wired into `prebuild`). Get `public/figures/<topic>/diagram.svg` ready to reference in MDX as `<Figure src="/figures/<topic>/diagram.svg" />`.
+Drop `figures/<topic>/diagram.tex` (standalone TikZ source). Run
+`npm run build:figures` explicitly; figure conversion is not wired into
+`prebuild` because TeX and Poppler are optional system tools. The command emits
+`public/figures/<topic>/diagram.svg`, ready to reference in MDX as
+`<Figure src="/figures/<topic>/diagram.svg" />`.
 
 ## The TikZ source
 
@@ -25,6 +29,13 @@ Use the `standalone` document class; configure for SVG via `tikz` option. Recomm
 
 The `border=2mm` adds a small margin around the figure so it doesn't crop right at the edge.
 
+For theme-aware color, define the canonical Warm–Tol or Okabe–Ito hex and use
+`fill opacity` rather than an xcolor pre-blend such as `warmblue!13`. The base
+color survives PDF export and `build-figures` can map it to `--fig-*` or
+`--series-*`; the pre-blended RGB cannot preserve its meaning. See
+[Recipe 24 — Figure authoring standard](24-figure-authoring-standard.md) for
+the palette, accessible description pattern, and dual-theme release gate.
+
 ## Discovery rule
 
 `build-figures` walks `figures/` (or `BOOK_FIGURES_PATH`) for both `.pdf` and `.tex` files. For each `.tex` source:
@@ -136,6 +147,6 @@ layout: wide      # widens --measure-main to 80ch; omit (or 'default') for the s
 
 ## See also
 
-- `recipes/06-figures.md` — overall figure pipeline + matplotlib/svg sources
+- `recipes/24-figure-authoring-standard.md` — palette, matplotlib/TikZ authoring, dark mode, and accessibility
 - `PACKAGE_DESIGN.md §7` — peer dependencies (lists `pdflatex` as optional system dep)
 - `PACKAGE_DESIGN.md §8` — `book-scaffold` CLI reference (build-figures subcommand)

package/recipes/24-figure-authoring-standard.md

@@ -0,0 +1,241 @@
+# Recipe 24 — Figure authoring standard
+
+**Profile**: any profile that publishes diagrams, plots, or TikZ figures.
+
+**TL;DR**: Use `--fig-*` when a color means something and `--series-1` through
+`--series-8` when colors only distinguish data series. Author exported figures
+with the canonical hex plus a separate opacity; `build:figures` maps those
+colors to theme-aware CSS variables. Every figure needs a useful caption and
+accessible description, and color must never be the only way to read it.
+
+## 1. Choose the right color contract
+
+Semantic colors keep the same meaning across a book:
+
+| Token | Meaning | Light | Dark | Export hex |
+|---|---|---|---|---|
+| `--fig-blue` | default, lightweight, informational | `#3B6FA0` | `#7297BB` | `#3B6FA0` |
+| `--fig-green` | positive or successful outcome | `#4A7E3F` | `#7DA275` | `#4A7E3F` |
+| `--fig-rose` | caution or problem | `#C06858` | `#D29287` | `#C06858` |
+| `--fig-plum` | authority, control, or heaviest weight | `#8A4E82` | `#AB80A5` | `#8A4E82` |
+| `--fig-gold` | packaging, coordination, or convergence | `#9D7D34` | `#D2B575` | `#C09840` |
+| `--fig-crimson` | failure or severe problem | `#A03838` | `#BB7070` | `#A03838` |
+| `--fig-ink` | labels, essential outlines, axes | `#1A1A19` | `#E8E5DD` | `#1A1A19` or black |
+| `--fig-paper` | figure background | `#FDFCF9` | `#1A1816` | `#FDFCF9` or white |
+| `--fig-grid` | essential gridlines and secondary structure | `#8C8981` | `#746E67` | `#B5B3AA` or a mid-neutral |
+
+`--fig-gold` resolves to a slightly darker gold in the light theme so an
+essential stroke clears 3:1 against `--fig-paper`. The export rewrite still
+recognizes the canonical `#C09840` authoring value.
+
+Categorical plots use the stable Okabe–Ito order:
+
+| Ordinal | Token | Canonical color |
+|---:|---|---|
+| 1 | `--series-1` | orange `#E69F00` |
+| 2 | `--series-2` | sky blue `#56B4E9` |
+| 3 | `--series-3` | bluish green `#009E73` |
+| 4 | `--series-4` | yellow `#F0E442` |
+| 5 | `--series-5` | blue `#0072B2` |
+| 6 | `--series-6` | vermillion `#D55E00` |
+| 7 | `--series-7` | reddish purple `#CC79A7` |
+| 8 | `--series-8` | theme ink (canonical authoring color: black) |
+
+Series 1–7 use the same canonical value in light and dark; each already clears
+3:1 against the dark figure paper. Series 8 changes with `--fig-ink`.
+
+Assign series in that order and keep the ordinal attached to the same series
+when a chart or theme changes. Never use `--series-*` to mean good, bad,
+warning, or success; those meanings belong to `--fig-*`.
+
+After PDF export, canonical series-8 black is indistinguishable from labels and
+axes. The rewrite therefore maps it to structural ink; `--series-8` aliases the
+same `--fig-ink` value, so it still renders correctly in both themes. Use
+`var(--series-8)` directly in a CSS-native SVG if you need to override that
+ordinal independently.
+
+## 2. CSS-native SVG: the preferred hand-authored form
+
+Use variables directly. Pale fills should be computed from the current figure
+paper, while their solid borders carry the category:
+
+```svg
+<svg role="img" aria-labelledby="pipeline-title pipeline-desc"
+     viewBox="0 0 420 140" xmlns="http://www.w3.org/2000/svg">
+  <title id="pipeline-title">A three-stage publishing pipeline</title>
+  <desc id="pipeline-desc">
+    Draft flows to review and then publication. Review is the only caution stage.
+  </desc>
+  <style>
+    .label { fill: var(--fig-ink); font: 16px sans-serif; }
+    .edge { fill: none; stroke: var(--fig-ink); stroke-width: 2; }
+    .draft {
+      fill: color-mix(in srgb, var(--fig-blue) 14%, var(--fig-paper));
+      stroke: var(--fig-blue);
+    }
+    .review {
+      fill: color-mix(in srgb, var(--fig-rose) 14%, var(--fig-paper));
+      stroke: var(--fig-rose);
+    }
+    .published {
+      fill: color-mix(in srgb, var(--fig-green) 14%, var(--fig-paper));
+      stroke: var(--fig-green);
+    }
+    .node { stroke-width: 3; }
+  </style>
+  <!-- geometry omitted -->
+</svg>
+```
+
+When this is a local SVG rendered by `<Figure>`, the host page supplies the
+variables and its light/dark toggle changes the figure immediately. An SVG
+loaded from another origin cannot inherit host variables.
+
+For a categorical chart, use `stroke: var(--series-1)`, then `--series-2`, and
+so on. Give every line a second channel too: different dashes, markers, or a
+direct text label.
+
+## 3. TikZ and matplotlib exports
+
+PDF cannot carry CSS variables. `build:figures` therefore recognizes the exact
+Warm–Tol and Okabe–Ito authoring colors in the generated SVG and maps them back
+to variables. Unknown saturated colors stay exactly as authored.
+
+The important rule is **base color plus separate opacity**. Do not use a
+pre-blended low-chroma color such as `figblue!13`: after PDF export it is only
+an anonymous near-white RGB and can be mistaken for figure paper.
+
+TikZ:
+
+```latex
+\definecolor{figblue}{HTML}{3B6FA0}
+\definecolor{figrose}{HTML}{C06858}
+\definecolor{seriesone}{HTML}{E69F00}
+
+\node[
+  draw=figblue,
+  fill=figblue,
+  fill opacity=.14,
+  text opacity=1,
+  line width=1.2pt,
+] (draft) {Draft};
+\node[draw=figrose, fill=figrose, fill opacity=.14, text opacity=1] (review) {Review};
+\draw[seriesone, very thick, dashed] plot coordinates {(0,0) (1,2) (2,3)};
+```
+
+Matplotlib:
+
+```python
+import matplotlib.pyplot as plt
+
+FIG = {
+    "blue": "#3B6FA0",
+    "rose": "#C06858",
+    "green": "#4A7E3F",
+}
+SERIES = [
+    "#E69F00", "#56B4E9", "#009E73", "#F0E442",
+    "#0072B2", "#D55E00", "#CC79A7", "#000000",
+]
+
+fig, ax = plt.subplots()
+# Keep the canvas transparent: the host's --fig-paper must show through after
+# PDF → SVG conversion instead of baking a light-only rectangle into the plot.
+fig.patch.set_alpha(0)
+ax.set_facecolor("none")
+ax.fill_between(x, low, high, color=FIG["blue"], alpha=.14)
+ax.plot(x, mean, color=FIG["blue"], linewidth=2)
+ax.plot(x, baseline, color=SERIES[0], linestyle="--", marker="o", label="Baseline")
+fig.savefig(
+    "figures/results/summary.pdf",
+    format="pdf",
+    transparent=True,
+    bbox_inches="tight",
+)
+```
+
+Then run `npm run build:figures` to preserve the vector PDF→SVG path. Export a
+raster (`.png`) only when the source is true pixel data, such as a photograph
+or instrument raster. Lines, text, markers, and diagram geometry should remain
+vector PDF/SVG. Re-run the command after upgrading the scaffold so
+already-generated SVGs receive new mappings; the rewrite is idempotent.
+
+## 4. Accessible name and description
+
+Use `<Figure>` as the accessibility boundary:
+
+```mdx
+<Figure
+  src="/figures/results/summary.svg"
+  id="fig-results-summary"
+  caption="Review catches most defects before publication."
+  alt="Three-stage publishing pipeline"
+  desc="Draft flows right to review, then publication. The review node is marked as a caution stage, and the publication node is marked as a successful outcome."
+/>
+```
+
+- `caption` states the point the reader should take from the figure.
+- `alt` is a short accessible name, not a duplicate of every visible label.
+- `desc` gives reading order, relationships, trend, and any conclusion carried
+  by position, shape, line style, or color.
+- For a local pipeline SVG, `<Figure>` replaces stale `<title>`/`<desc>` nodes
+  with these props and wires `aria-labelledby` automatically.
+- Raster and remote images remain `<img>` elements, so give them complete alt
+  text and put any longer explanation in adjacent prose.
+
+Do not write “blue means success” as the only description. Name the category
+and the redundant cue: “the successful outcome is the green node with a check
+mark.”
+
+## 5. Contrast and color-vision rules
+
+Okabe–Ito is color-vision-deficiency-friendly; that does not make every hue a
+high-contrast thin line on light paper. In particular, orange, sky blue,
+yellow, and reddish purple need redundant encoding.
+
+- Never encode a distinction by color alone. Add marker shape, dash pattern,
+  direct labels, texture, or position.
+- Use `--fig-ink` for axes, text, arrowheads, and essential outlines.
+- Give pale semantic areas a solid `--fig-*` border. The semantic strokes and
+  `--fig-grid` clear WCAG's 3:1 non-text contrast threshold in both themes.
+- Outline small categorical marks with `--fig-ink`; use thicker/dashed lines
+  and markers for categorical series that do not clear 3:1 by color alone.
+- Do not reorder `--series-*` in dark mode. `--series-8` follows theme ink so
+  the neutral series remains visible rather than staying literal black.
+
+## 6. Dual-theme release gate
+
+Before publishing a new figure:
+
+1. Run `npm run build:figures` and confirm the SVG contains one
+   `data-diagram-map` style block.
+2. Render it through `<Figure>` with explicit light and dark page themes.
+3. Open the standalone SVG with both OS color schemes; its embedded defaults
+   should also switch.
+4. Check labels, axes, arrowheads, boundaries, and all series at the smallest
+   published size.
+5. Inspect a grayscale or common CVD simulation and verify that markers,
+   dashes, labels, or shapes preserve every distinction.
+6. Confirm the caption and screen-reader description communicate the takeaway
+   without relying on color names.
+
+If automatic recoloring is genuinely wrong for a special TikZ figure, add a
+`%! no-theme` line to its `.tex` source and supply a fully authored light/dark
+solution yourself. That escape hatch opts out of both palette and neutral
+mapping.
+
+## Canonical files
+
+- `src/lib/figure-palette.mjs` — sole palette manifest + generated CSS/theme renderers
+- `styles/tokens.css` — public `--fig-*`, `--series-*`, and compatibility tokens
+- `src/lib/figure.mjs` — exact palette recognition and SVG theme injection
+- `scripts/sync-figure-tokens.mjs` — checks or refreshes the generated token block
+- `scripts/build-figures.mjs` — PDF/TikZ conversion pipeline
+- `components/Figure.astro` — inlining plus accessible `<title>`/`<desc>`
+- `tests/figure-palette.test.mjs` — token, mapping, theme, and contrast contract
+
+## See also
+
+- [Recipe 03 — Asset pipelines](03-asset-pipelines.md)
+- [Recipe 04 — Component library](04-component-library.md)
+- [Recipe 16 — TikZ figures](16-tikz-figures.md)

package/recipes/README.md

@@ -29,6 +29,7 @@ Terse pointers into canonical code for the most common book-authoring workflows.
 | 21 | [Multiple guides in one app](21-multi-guide-single-app.md) | any | `generateId` namespacing over one collection; flat-slug footgun; interim until multibook (#80) |
 | 22 | [Responsive navigation and multi-book routing](22-responsive-nav-and-multibook-routing.md) | any | Mobile/desktop nav, base-aware route ownership, and the interim multi-book routing contract |
 | 23 | [Interactive demo substrate](23-interactive-demo-substrate.md) | any | Opt-in Preact shell, slider, stat cards, theme colors, a11y, and reduced motion |
+| 24 | [Figure authoring standard](24-figure-authoring-standard.md) | any | Warm–Tol semantics, Okabe–Ito series, dual-theme exports, contrast, and accessible descriptions |
 
 ## How to read recipes
 

package/scripts/build-figures.mjs

@@ -25,21 +25,22 @@
  *
  * 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.
+ * SVG serves light + dark. Known Warm–Tol semantic and Okabe–Ito categorical
+ * colors are mapped to var(--fig-*|--series-*, <original>); neutral paints map
+ * to var(--diagram-ink|paper|grid, <original>). Unknown saturated colors stay
+ * authored. 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.
+ * Run explicitly with `npm run build:figures`; optional system tools keep this
+ * authoring pipeline out of the generated project's `prebuild` hook.
  *
  * Graceful skip: when pdftocairo / pdftoppm aren't on PATH (e.g. Cloudflare
  * build container), the script warns and exits 0. Committed SVGs/PNGs under
- * public/figures/ are served as-is. Local devs with poppler-utils regenerate
- * from PDFs on every `npm run dev`.
+ * public/figures/ are served as-is. Local authors with poppler-utils regenerate
+ * from PDFs when source figures change.
  */
 import { readdir, stat, mkdir } from 'node:fs/promises';
 import { existsSync, statSync, readFileSync, writeFileSync } from 'node:fs';
@@ -56,8 +57,10 @@ Figure pipeline. PDF -> SVG via pdftocairo (PNG fallback via pdftoppm at
 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.
+exact Warm–Tol/Okabe–Ito palette mappings and neutral
+var(--diagram-ink|paper|grid, orig) mappings. Use base color + separate opacity,
+not a pre-blended tint. 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/).
@@ -202,7 +205,7 @@ 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.
+ * (already themed / nothing themeable to remap). Idempotent.
  */
 function themeIfSvg(svgPath, optOut) {
   if (!existsSync(svgPath)) return false;

package/scripts/render-notebooks.mjs

@@ -16,7 +16,8 @@
  * canonical; the notebook is a code companion.
  *
  * Idempotent: skips when the target HTML is newer than the source .ipynb.
- * Run on `prebuild` so Astro always sees fresh notebook HTML.
+ * Run explicitly with `npm run build:notebooks`; optional system tools keep
+ * this authoring pipeline out of the generated project's `prebuild` hook.
  *
  * Style scoping: nbconvert's `basic` template emits HTML without nbviewer
  * chrome, but with embedded <style> tags. To prevent CSS bleed, each

package/scripts/sync-figure-tokens.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+/** Regenerate or verify the manifest-owned block in styles/tokens.css. */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import {
+  FIGURE_TOKEN_BLOCK_END,
+  FIGURE_TOKEN_BLOCK_START,
+  renderFigureTokenCssBlock,
+} from '../src/lib/figure-palette.mjs';
+
+const TOKENS_PATH = fileURLToPath(new URL('../styles/tokens.css', import.meta.url));
+const args = new Set(process.argv.slice(2));
+const write = args.has('--write');
+if (args.size > 1 || (args.size === 1 && !write && !args.has('--check'))) {
+  console.error('Usage: node scripts/sync-figure-tokens.mjs [--check|--write]');
+  process.exit(2);
+}
+
+const css = readFileSync(TOKENS_PATH, 'utf8');
+const start = css.indexOf(FIGURE_TOKEN_BLOCK_START);
+const endStart = css.indexOf(FIGURE_TOKEN_BLOCK_END, start);
+if (start < 0 || endStart < 0) {
+  throw new Error('tokens.css is missing the generated figure-token block markers.');
+}
+const end = endStart + FIGURE_TOKEN_BLOCK_END.length;
+const expected = renderFigureTokenCssBlock();
+const actual = css.slice(start, end);
+
+if (write) {
+  if (actual === expected) {
+    console.log('sync-figure-tokens: tokens.css already current');
+  } else {
+    writeFileSync(TOKENS_PATH, css.slice(0, start) + expected + css.slice(end), 'utf8');
+    console.log('sync-figure-tokens: updated styles/tokens.css');
+  }
+} else if (actual !== expected) {
+  console.error(
+    'sync-figure-tokens: styles/tokens.css drifted from src/lib/figure-palette.mjs; ' +
+    'run npm run sync:figure-tokens --workspace package',
+  );
+  process.exit(1);
+} else {
+  console.log('sync-figure-tokens: tokens.css matches the palette manifest');
+}

package/src/lib/figure-palette.mjs

@@ -0,0 +1,162 @@
+/**
+ * Canonical figure palette contract (#161, #164).
+ *
+ * This pure manifest owns every authored RGB, host token value, and standalone
+ * SVG value. `figure.mjs` derives its exact SVG mappings and embedded theme CSS
+ * from it; `tokens.css` carries a checked generated block rendered below.
+ * Keep semantic Warm–Tol roles separate from ordinal Okabe–Ito series.
+ */
+
+function frozenEntries(entries) {
+  return Object.freeze(entries.map((entry) => Object.freeze(entry)));
+}
+
+export const SEMANTIC_FIGURE_TOKENS = frozenEntries([
+  {
+    family: 'semantic', name: 'blue', token: '--fig-blue', label: 'default / lightweight',
+    authoring: '#3B6FA0', hostLight: '#3B6FA0', standaloneLight: '#3B6FA0',
+    hostDark: '#7297BB', standaloneDark: '#7297BB',
+  },
+  {
+    family: 'semantic', name: 'rose', token: '--fig-rose', label: 'caution / problem',
+    authoring: '#C06858', hostLight: '#C06858', standaloneLight: '#C06858',
+    hostDark: '#D29287', standaloneDark: '#D29287',
+  },
+  {
+    family: 'semantic', name: 'green', token: '--fig-green', label: 'positive outcome',
+    authoring: '#4A7E3F', hostLight: '#4A7E3F', standaloneLight: '#4A7E3F',
+    hostDark: '#7DA275', standaloneDark: '#7DA275',
+  },
+  {
+    family: 'semantic', name: 'plum', token: '--fig-plum', label: 'authority / heaviest',
+    authoring: '#8A4E82', hostLight: '#8A4E82', standaloneLight: '#8A4E82',
+    hostDark: '#AB80A5', standaloneDark: '#AB80A5',
+  },
+  {
+    family: 'semantic', name: 'gold', token: '--fig-gold', label: 'packaging / coordination',
+    // Export the canonical Warm–Tol gold; the light host value is deliberately
+    // darker so an essential stroke clears 3:1 against figure paper.
+    authoring: '#C09840', hostLight: '#9D7D34', standaloneLight: '#9D7D34',
+    hostDark: '#D2B575', standaloneDark: '#D2B575',
+  },
+  {
+    family: 'semantic', name: 'crimson', token: '--fig-crimson', label: 'failure / severe problem',
+    authoring: '#A03838', hostLight: '#A03838', standaloneLight: '#A03838',
+    hostDark: '#BB7070', standaloneDark: '#BB7070',
+  },
+]);
+
+export const STRUCTURAL_FIGURE_TOKENS = frozenEntries([
+  {
+    family: 'structural', name: 'ink', token: '--fig-ink', label: 'labels / axes / outlines',
+    hostLight: 'var(--color-text)', standaloneLight: '#1A1A19',
+    hostDark: 'var(--color-text)', standaloneDark: '#E8E5DD',
+  },
+  {
+    family: 'structural', name: 'paper', token: '--fig-paper', label: 'figure background',
+    hostLight: 'var(--color-bg)', standaloneLight: '#FDFCF9',
+    hostDark: 'var(--color-bg)', standaloneDark: '#1A1816',
+  },
+  {
+    family: 'structural', name: 'grid', token: '--fig-grid', label: 'essential secondary structure',
+    hostLight: '#8C8981', standaloneLight: '#8C8981',
+    hostDark: '#746E67', standaloneDark: '#746E67',
+  },
+]);
+
+export const SERIES_FIGURE_TOKENS = frozenEntries([
+  { family: 'series', ordinal: 1, name: 'orange', token: '--series-1', authoring: '#E69F00', hostLight: '#E69F00', standaloneLight: '#E69F00', hostDark: '#E69F00', standaloneDark: '#E69F00' },
+  { family: 'series', ordinal: 2, name: 'sky blue', token: '--series-2', authoring: '#56B4E9', hostLight: '#56B4E9', standaloneLight: '#56B4E9', hostDark: '#56B4E9', standaloneDark: '#56B4E9' },
+  { family: 'series', ordinal: 3, name: 'bluish green', token: '--series-3', authoring: '#009E73', hostLight: '#009E73', standaloneLight: '#009E73', hostDark: '#009E73', standaloneDark: '#009E73' },
+  { family: 'series', ordinal: 4, name: 'yellow', token: '--series-4', authoring: '#F0E442', hostLight: '#F0E442', standaloneLight: '#F0E442', hostDark: '#F0E442', standaloneDark: '#F0E442' },
+  { family: 'series', ordinal: 5, name: 'blue', token: '--series-5', authoring: '#0072B2', hostLight: '#0072B2', standaloneLight: '#0072B2', hostDark: '#0072B2', standaloneDark: '#0072B2' },
+  { family: 'series', ordinal: 6, name: 'vermillion', token: '--series-6', authoring: '#D55E00', hostLight: '#D55E00', standaloneLight: '#D55E00', hostDark: '#D55E00', standaloneDark: '#D55E00' },
+  { family: 'series', ordinal: 7, name: 'reddish purple', token: '--series-7', authoring: '#CC79A7', hostLight: '#CC79A7', standaloneLight: '#CC79A7', hostDark: '#CC79A7', standaloneDark: '#CC79A7' },
+  {
+    family: 'series', ordinal: 8, name: 'neutral ink', token: '--series-8',
+    authoring: '#000000', hostLight: 'var(--fig-ink)', standaloneLight: 'var(--fig-ink)',
+    hostDark: 'var(--fig-ink)', standaloneDark: 'var(--fig-ink)',
+    // PDF export loses the distinction between categorical black and labels.
+    // Both aliases resolve through --fig-ink, so the rendered value agrees.
+    svgVariable: '--diagram-ink',
+  },
+]);
+
+export const FIGURE_TOKEN_DEFINITIONS = Object.freeze([
+  ...SEMANTIC_FIGURE_TOKENS,
+  ...STRUCTURAL_FIGURE_TOKENS,
+  ...SERIES_FIGURE_TOKENS,
+]);
+
+export const FIGURE_COMPATIBILITY_ALIASES = frozenEntries([
+  { token: '--diagram-ink', value: 'var(--fig-ink)' },
+  { token: '--diagram-paper', value: 'var(--fig-paper)' },
+  { token: '--diagram-grid', value: 'var(--fig-grid)' },
+]);
+
+export const FIGURE_AUTHORING_COLOR_MAP = Object.freeze([
+  ...SEMANTIC_FIGURE_TOKENS,
+  ...SERIES_FIGURE_TOKENS,
+].map((entry) => Object.freeze({
+  family: entry.family,
+  authoring: entry.authoring,
+  token: entry.token,
+  variable: entry.svgVariable ?? entry.token,
+})));
+
+export const FIGURE_TOKEN_BLOCK_START = '/* BEGIN GENERATED FIGURE TOKENS — source: src/lib/figure-palette.mjs */';
+export const FIGURE_TOKEN_BLOCK_END = '/* END GENERATED FIGURE TOKENS */';
+
+function declarations(entries, key, { comments = false } = {}) {
+  return entries.map((entry) => {
+    const comment = comments ? ` /* ${entry.label ?? entry.name} */` : '';
+    return `  ${entry.token}: ${entry[key]};${comment}`;
+  });
+}
+
+/** Render the checked block committed in styles/tokens.css. */
+export function renderFigureTokenCssBlock() {
+  const light = [
+    ...declarations(SEMANTIC_FIGURE_TOKENS, 'hostLight', { comments: true }),
+    ...declarations(STRUCTURAL_FIGURE_TOKENS, 'hostLight', { comments: true }),
+    '',
+    '  /* Canonical Okabe–Ito order. Never reorder ordinals per chart or theme. */',
+    ...declarations(SERIES_FIGURE_TOKENS, 'hostLight', { comments: true }),
+    '',
+    '  /* Backward-compatible aliases used by build-figures since v4.11.0. */',
+    ...FIGURE_COMPATIBILITY_ALIASES.map((entry) => `  ${entry.token}: ${entry.value};`),
+  ];
+  const dark = declarations(FIGURE_TOKEN_DEFINITIONS, 'hostDark');
+
+  return [
+    FIGURE_TOKEN_BLOCK_START,
+    '/* Do not edit this block by hand. Semantic Warm–Tol roles and ordinal',
+    ' * Okabe–Ito series are intentionally separate public contracts. */',
+    ':root {',
+    ...light,
+    '}',
+    '',
+    '@media (prefers-color-scheme: dark) {',
+    '  :root:not([data-theme="light"]) {',
+    ...dark.map((line) => `  ${line}`),
+    '  }',
+    '}',
+    '',
+    ':root[data-theme="dark"] {',
+    ...dark,
+    '}',
+    FIGURE_TOKEN_BLOCK_END,
+  ].join('\n');
+}
+
+/** Render minified defaults embedded into standalone generated SVGs. */
+export function renderStandaloneFigureThemeCss() {
+  const themed = (key) => FIGURE_TOKEN_DEFINITIONS
+    .map((entry) => `${entry.token}:${entry[key]}`)
+    .join(';');
+  const aliases = FIGURE_COMPATIBILITY_ALIASES
+    .map((entry) => `${entry.token}:${entry.value}`)
+    .join(';');
+  return `:root{${themed('standaloneLight')};${aliases}}` +
+    `@media (prefers-color-scheme:dark){:root{${themed('standaloneDark')}}}`;
+}

package/src/lib/figure.mjs

@@ -11,7 +11,7 @@
  * 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
+ * attribute-selector rule per distinct themeable color and never mutates a
  * drawing element — the untouched `fill=""`/`stroke=""` attribute is the
  * automatic fallback where `var()` is unsupported.
  *
@@ -20,19 +20,22 @@
  * 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-*.
+ * embedded theme block so the host is the sole source of --fig-*, --series-*,
+ * and the backward-compatible --diagram-* aliases.
  *
  * 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).
  */
 
+import {
+  FIGURE_AUTHORING_COLOR_MAP,
+  renderStandaloneFigureThemeCss,
+} from './figure-palette.mjs';
+
 // 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}}';
+// there. Generated from the same pure manifest as the host tokens.css block.
+export const DIAGRAM_THEME_CSS = renderStandaloneFigureThemeCss();
 
 const DIAGRAM_VAR = {
   ink: '--diagram-ink',
@@ -40,6 +43,24 @@ const DIAGRAM_VAR = {
   grid: '--diagram-grid',
 };
 
+// Exact canonical authoring colors. Match by parsed RGB rather than source
+// spelling so #3B6FA0, rgb(59,111,160), and Poppler's rgb(23.137%,…) all
+// resolve to one semantic variable. Palette recognition MUST run before the
+// neutral heuristic: base hue + fill-opacity remains themeable, whereas a
+// pre-blended pale tint can otherwise look neutral and collapse to paper.
+function rgbKeyFromHex(hex) {
+  return [1, 3, 5]
+    .map((offset) => Number.parseInt(hex.slice(offset, offset + 2), 16))
+    .join(',');
+}
+
+const PALETTE_VAR_BY_RGB = new Map(
+  FIGURE_AUTHORING_COLOR_MAP.map(({ authoring, variable }) => [
+    rgbKeyFromHex(authoring),
+    variable,
+  ]),
+);
+
 /**
  * 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).
@@ -86,11 +107,32 @@ export function classifyColor(value) {
   return 'grid';
 }
 
+/**
+ * Return the CSS custom property for a known Warm–Tol / Okabe–Ito color, or
+ * for a neutral paint classified as ink/paper/grid. Unknown saturated colors
+ * return null and stay exactly as authored.
+ */
+export function figureColorVariable(value) {
+  const c = parseColor(value);
+  if (c && [c.r, c.g, c.b].every((channel) => channel >= 0 && channel <= 1)) {
+    const key = [c.r, c.g, c.b].map((channel) => Math.round(channel * 255)).join(',');
+    const paletteVar = PALETTE_VAR_BY_RGB.get(key);
+    if (paletteVar) return paletteVar;
+  }
+
+  const cls = classifyColor(value);
+  return cls ? DIAGRAM_VAR[cls] : null;
+}
+
 // Escape a value for use inside a CSS [attr="…"] selector string.
 function cssAttrEscape(s) {
   return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
 }
 
+const THEME_BLOCK_RE = /<style\b[^>]*\bdata-diagram-theme\b[^>]*>[\s\S]*?<\/style>/gi;
+const MAP_BLOCK_RE = /<style\b[^>]*\bdata-diagram-map\b[^>]*>[\s\S]*?<\/style>/gi;
+const CURRENT_MAP_RE = /\bdata-diagram-map=(?:"2"|'2')/i;
+
 /**
  * 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
@@ -98,55 +140,63 @@ function cssAttrEscape(s) {
  *
  * 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.
+ *   <style data-diagram-map="2"> — `[fill="C"]{fill:var(--fig-X, C)}` … per
+ *                                 distinct known-palette or 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;
+  if (optOut || CURRENT_MAP_RE.test(svg)) return svg;
+  if (!/<svg\b[^>]*>/i.test(svg)) return svg;
 
-  const openMatch = svg.match(/<svg\b[^>]*>/i);
-  if (!openMatch) return svg;
+  // A pre-v2 map contains only neutral roles. Remove its generated blocks and
+  // rebuild from the untouched presentation attributes so cached SVGs gain
+  // palette mappings after an upgrade without needing a source-file touch.
+  const cleanSvg = svg.includes('data-diagram-map')
+    ? svg.replace(THEME_BLOCK_RE, '').replace(MAP_BLOCK_RE, '')
+    : svg;
+
+  const openMatch = cleanSvg.match(/<svg\b[^>]*>/i);
+  if (!openMatch) return svg; // defensive: generated-block cleanup never removes <svg>
 
   // Distinct concrete colors used as fill="" / stroke="" attributes.
-  const found = new Map(); // original string → class
+  const found = new Map(); // original string → CSS custom property
   const attrRe = /\b(?:fill|stroke)="([^"]+)"/g;
   let am;
-  while ((am = attrRe.exec(svg)) !== null) {
+  while ((am = attrRe.exec(cleanSvg)) !== null) {
     if (found.has(am[1])) continue;
-    const cls = classifyColor(am[1]);
-    if (cls) found.set(am[1], cls);
+    const variable = figureColorVariable(am[1]);
+    if (variable) found.set(am[1], variable);
   }
 
   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>.
+  // Nothing themeable 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);
+      ? cleanSvg
+      : cleanSvg.slice(0, openMatch.index) + openTag + cleanSvg.slice(openMatch.index + openMatch[0].length);
   }
 
   let mapCss = '';
-  for (const [orig, cls] of found) {
-    const v = DIAGRAM_VAR[cls];
+  for (const [orig, variable] of found) {
     const sel = cssAttrEscape(orig);
     mapCss +=
-      `[fill="${sel}"]{fill:var(${v}, ${orig})}` +
-      `[stroke="${sel}"]{stroke:var(${v}, ${orig})}`;
+      `[fill="${sel}"]{fill:var(${variable}, ${orig})}` +
+      `[stroke="${sel}"]{stroke:var(${variable}, ${orig})}`;
   }
 
   const styleBlocks =
     `<style data-diagram-theme>${DIAGRAM_THEME_CSS}</style>` +
-    `<style data-diagram-map>${mapCss}</style>`;
+    `<style data-diagram-map="2">${mapCss}</style>`;
 
   return (
-    svg.slice(0, openMatch.index) +
+    cleanSvg.slice(0, openMatch.index) +
     openTag +
     styleBlocks +
-    svg.slice(openMatch.index + openMatch[0].length)
+    cleanSvg.slice(openMatch.index + openMatch[0].length)
   );
 }
 
@@ -162,10 +212,36 @@ export function shouldInline(src) {
   );
 }
 
-const THEME_BLOCK_RE = /<style\b[^>]*\bdata-diagram-theme\b[^>]*>[\s\S]*?<\/style>/gi;
+/**
+ * Convert a local SVG URL into a path relative to the consumer's `public/`
+ * directory. Astro prefixes dynamic asset URLs with BASE_URL on non-root
+ * deployments, but that prefix is a URL concern and is not present on disk.
+ * Literal root URLs remain supported so this helper is backward-compatible.
+ *
+ * Reject dot segments and backslashes before the filesystem boundary. Figure
+ * sources are author-controlled, but an inline helper should never make an
+ * out-of-tree file available to `set:html` accidentally.
+ */
+export function publicSvgPath(src, base = '/') {
+  if (!shouldInline(src) || src.includes('\\')) return null;
+
+  const baseSegments = typeof base === 'string'
+    ? base.split('/').filter(Boolean)
+    : [];
+  const normalizedBase = baseSegments.length ? `/${baseSegments.join('/')}/` : '/';
+  const withoutBase = normalizedBase !== '/' && src.startsWith(normalizedBase)
+    ? src.slice(normalizedBase.length)
+    : src.replace(/^\/+/, '');
+  const segments = withoutBase.split('/');
+
+  if (!segments.length || segments.some((segment) => !segment || segment === '.' || segment === '..')) {
+    return null;
+  }
+  return segments.join('/');
+}
 
-/** 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. */
+/** Remove the standalone self-theming block so host tokens.css is the sole
+ *  source of figure variables once the SVG is inlined into the page. */
 export function stripThemeBlock(svg) {
   return typeof svg === 'string' ? svg.replace(THEME_BLOCK_RE, '') : svg;
 }
@@ -204,7 +280,7 @@ function mergeSvgStyle(openTag, 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;
+ *     (alt ?? caption → <title>, desc → <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).
  */
@@ -222,23 +298,23 @@ export function assembleSvg(raw, opts = {}) {
     .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 : '');
+  // Match the raster fallback: `alt` is the short accessible name. A caption
+  // is only its fallback, while `desc` remains the optional long description.
+  const titleText = alt ?? caption ?? '';
+  const descText = desc ?? '';
   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(' '));
+  if (titleText) openTag = setSvgAttr(openTag, 'aria-labelledby', `${id}-title`);
+  if (descText) openTag = setSvgAttr(openTag, 'aria-describedby', `${id}-desc`);
   openTag = mergeSvgStyle(openTag, `width:${width};max-width:100%;height:auto`);
 
   return `${svg.slice(0, openMatch.index)}${openTag}${a11y.join('')}${body}`;

package/styles/tokens.css

@@ -54,15 +54,6 @@
   --callout-learn:    var(--warm-gold);
   --callout-diagnostic: color-mix(in srgb, var(--warm-blue) 55%, var(--warm-green)); /* #110 DIKTA self-check — teal blend, distinct from plum Practice */
 
-  /* 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;
@@ -212,3 +203,76 @@
   --astro-code-token-parameter:         color-mix(in srgb, var(--warm-blue)  55%, white);
   --astro-code-token-function:          color-mix(in srgb, var(--warm-gold)  65%, white);
 }
+
+/* BEGIN GENERATED FIGURE TOKENS — source: src/lib/figure-palette.mjs */
+/* Do not edit this block by hand. Semantic Warm–Tol roles and ordinal
+ * Okabe–Ito series are intentionally separate public contracts. */
+:root {
+  --fig-blue: #3B6FA0; /* default / lightweight */
+  --fig-rose: #C06858; /* caution / problem */
+  --fig-green: #4A7E3F; /* positive outcome */
+  --fig-plum: #8A4E82; /* authority / heaviest */
+  --fig-gold: #9D7D34; /* packaging / coordination */
+  --fig-crimson: #A03838; /* failure / severe problem */
+  --fig-ink: var(--color-text); /* labels / axes / outlines */
+  --fig-paper: var(--color-bg); /* figure background */
+  --fig-grid: #8C8981; /* essential secondary structure */
+
+  /* Canonical Okabe–Ito order. Never reorder ordinals per chart or theme. */
+  --series-1: #E69F00; /* orange */
+  --series-2: #56B4E9; /* sky blue */
+  --series-3: #009E73; /* bluish green */
+  --series-4: #F0E442; /* yellow */
+  --series-5: #0072B2; /* blue */
+  --series-6: #D55E00; /* vermillion */
+  --series-7: #CC79A7; /* reddish purple */
+  --series-8: var(--fig-ink); /* neutral ink */
+
+  /* Backward-compatible aliases used by build-figures since v4.11.0. */
+  --diagram-ink: var(--fig-ink);
+  --diagram-paper: var(--fig-paper);
+  --diagram-grid: var(--fig-grid);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) {
+    --fig-blue: #7297BB;
+    --fig-rose: #D29287;
+    --fig-green: #7DA275;
+    --fig-plum: #AB80A5;
+    --fig-gold: #D2B575;
+    --fig-crimson: #BB7070;
+    --fig-ink: var(--color-text);
+    --fig-paper: var(--color-bg);
+    --fig-grid: #746E67;
+    --series-1: #E69F00;
+    --series-2: #56B4E9;
+    --series-3: #009E73;
+    --series-4: #F0E442;
+    --series-5: #0072B2;
+    --series-6: #D55E00;
+    --series-7: #CC79A7;
+    --series-8: var(--fig-ink);
+  }
+}
+
+:root[data-theme="dark"] {
+  --fig-blue: #7297BB;
+  --fig-rose: #D29287;
+  --fig-green: #7DA275;
+  --fig-plum: #AB80A5;
+  --fig-gold: #D2B575;
+  --fig-crimson: #BB7070;
+  --fig-ink: var(--color-text);
+  --fig-paper: var(--color-bg);
+  --fig-grid: #746E67;
+  --series-1: #E69F00;
+  --series-2: #56B4E9;
+  --series-3: #009E73;
+  --series-4: #F0E442;
+  --series-5: #0072B2;
+  --series-6: #D55E00;
+  --series-7: #CC79A7;
+  --series-8: var(--fig-ink);
+}
+/* END GENERATED FIGURE TOKENS */