@brandon_m_behring/book-scaffold-astro 4.29.0 → 4.31.0

package/CLAUDE.md

@@ -201,6 +201,7 @@ the full precedence and customization contract.
 - Literal `<Theorem n>` values that disagree with `labels.json` (dynamic expressions and `label=` overrides are skipped)
 - Missing `<Figure src>` files under `public/`
 - Internal markdown links that don't resolve
+- Authored root-absolute Markdown/HTML/JSX `href` or `src` targets that escape a configured non-root Astro `base` (#190). Structurally parsed and decoded literal targets fail with file/line context; root-base books, external/protocol-relative URLs, fragments, dynamic JSX expressions, and already base-prefixed targets are unaffected. `rel="external"` does not change URL resolution or opt out. Validation never rewrites prose.
 - Study-guide questions (v4.17.0, #112) — a question whose frontmatter `domain` isn't in `examDomains`, and duplicate question `id`s
 
 Missing `src/data/labels.json` or `references.json` self-heals before checks by running the corresponding package build script; an existing artifact is never rewritten implicitly.
@@ -228,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.29.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"
@@ -190,9 +192,6 @@
     },
     "rehype-katex": {
       "optional": true
-    },
-    "remark-math": {
-      "optional": true
     }
   },
   "dependencies": {
@@ -203,6 +202,8 @@
     "@fontsource-variable/roboto": "^5.2.10",
     "@fontsource-variable/source-code-pro": "^5.2.7",
     "pagefind": "^1.5.2",
+    "parse5": "^7.3.0",
+    "remark-math": "^6.0.0",
     "remark-mdx": "^3.1.1",
     "remark-parse": "^11.0.0",
     "unified": "^11.0.5",

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/09-validation.md

@@ -2,7 +2,7 @@
 
 **Profile**: any (Cite checks skip under non-academic).
 
-**TL;DR**: `npm run validate` runs `scripts/validate.mjs` against all chapter MDX files. It first regenerates missing `labels.json` and `references.json`, then catches typo'd bibkeys / XRef ids / Figure paths / internal links that `astro build` would either miss or surface with poor context. Auto-runs as `prebuild`; recommend wiring into pre-commit too.
+**TL;DR**: `npm run validate` runs `scripts/validate.mjs` against chapter MD/MDX files (plus its question-collection checks). It first regenerates missing `labels.json` and `references.json`, then catches typo'd bibkeys / XRef ids / Figure paths / internal links that `astro build` would either miss or surface with poor context. Auto-runs as `prebuild`; recommend wiring into pre-commit too.
 
 ## What gets checked
 
@@ -17,6 +17,7 @@
 | `<BookLink book= to=>` both present; `book=` registered; literal fragment target resolves in a declared sibling labels index (#96, #147) | all | Pre-flights the component's build-time throw and dead cross-book anchors across all files at once. |
 | Questions collection: unique `id`s + `domain` in `examDomains` (#112); `<Rationale appendix>` carries `for=` (#114, v4.21.0) | all, when `src/content/questions/` exists | Duplicate ids break the appendix/flashcards cross-ref key; an unregistered domain throws one-at-a-time at build; an appendix rationale without its anchor target throws at build. |
 | `los[].anchor` ↔ `{/* anchor: <slug> */}` prose markers agree both ways (#130, v4.20.0) | all, when frontmatter has `los:` | A declared objective whose prose marker is missing/misspelled (or an orphan marker) builds green otherwise — frontmatter↔prose drift only a hand audit would catch. |
+| Literal authored Markdown/HTML/JSX `href`/`src` stays inside a non-root Astro `base` (#190) | all | A browser resolves `/chapters/...` from the host root, bypassing Astro's deployment base and producing a convincing 404. This is a build-blocking error, not a rewrite. |
 
 Validate also emits two **non-blocking shadow-route warnings** (exit code unaffected): a consumer-owned `src/pages/chapters/[...slug].astro` without `routes: { chapters: false }` (v4.6.0, #76), and a consumer-owned `src/pages/index.astro` without `routes: { landing: false }` (v4.20.0, #129 — Astro has announced this collision becomes a hard error). See [recipe 18](./18-chapter-route-ownership.md).
 
@@ -48,6 +49,24 @@ Heading-entry keys are intentionally opaque and path-qualified: `#summary` can l
 
 A declared `labels` file that is missing, unreadable, malformed, or not a JSON object is an error. An unknown book, unknown fragment, wrong path, or malformed label entry is also an error with the source file and target. Dynamic `book=`/`to=` expressions and prop spreads cannot be evaluated safely, so they emit explicit skip warnings. URL strings and `{ url }` descriptors likewise warn for literal fragment links because no index was declared. Non-fragment route links warn and skip: labels indexes describe anchors, not every sibling route.
 
+## Authored links under a non-root base (#190)
+
+When evaluated `astro.config.*` sets a non-root base such as `base: '/library/books/'`, a root-absolute authored URL escapes that deployment mount:
+
+```mdx
+<!-- Errors: both resolve from the host root, outside /library/books/. -->
+[Chapter one](/chapters/one/)
+<img src="/figures/overview.svg" alt="Overview" />
+
+<!-- Valid: explicitly remains inside the configured base. -->
+[Chapter one](/library/books/chapters/one/)
+<a href={`${import.meta.env.BASE_URL}references/`}>References</a>
+```
+
+The validator structurally parses inline Markdown links and images, Markdown reference definitions, quoted or unquoted HTML `href`/`src`, and quoted or statically braced JSX string attributes. HTML entities and JavaScript string escapes are decoded before containment is checked. It reports the authored file and line, the evaluated target, the evaluated base, and a browser-normalized base-prefixed replacement. It also scans question MD/MDX files already visited by validation.
+
+The check is deliberately validation-only: it does not mutate or rewrite content, and there is no opt-out. Under the root base (`/`) it is inert. Protocol URLs (`https:`, `mailto:`, `data:`, and others), protocol-relative URLs (`//cdn…`), fragments, relative targets, targets already inside the base, and dynamic JSX expressions are excluded. `rel="external"` describes a relationship but does not change where a browser navigates, so it does not exempt a host-root URL. Frontmatter, comments, fenced/inline/indented code examples, and `<pre>`/`<code>` examples are excluded by their parsed Markdown/MDX structure so documentation snippets do not become false diagnostics.
+
 ## Missing generated artifacts
 
 `src/data/labels.json` and `src/data/references.json` are derived and normally gitignored. v4.27+ `validate` self-heals either missing file unconditionally by invoking the package's own `build-labels` or `build-bib` command before loading data. Existing files are untouched. A failed child command stops validation with the child's original diagnostic and exit status.
@@ -96,7 +115,7 @@ For pre-commit: add to `.pre-commit-config.yaml`:
 
 ## Preset / chaptersBase resolution (v4.7.0+, #75)
 
-The validator evaluates `astro.config.*` through Vite first. A resolved scaffold integration supplies the composed preset and `numberStyle`, so CLI tooling sees the same Style chain as the Astro build. Without such an integration, the legacy preset chain remains: `--preset` → process `BOOK_PRESET`/`BOOK_PROFILE` → root `.env` → the literal value in `defineBookSchemas` → a warned `minimal` v4 compatibility fallback. Every selected value is checked against the five-preset enum; config-evaluation failures stop validation instead of silently using defaults.
+The validator evaluates `astro.config.*` through Vite first. A resolved scaffold integration supplies the composed preset and `numberStyle`, so CLI tooling sees the same Style chain as the Astro build. The evaluated Astro `base` is read from that same config regardless of whether the scaffold integration is present; omission defaults to `/`. Without such an integration, the legacy preset chain remains: `--preset` → process `BOOK_PRESET`/`BOOK_PROFILE` → root `.env` → the literal value in `defineBookSchemas` → a warned `minimal` v4 compatibility fallback. Every selected value is checked against the five-preset enum; config-evaluation failures stop validation instead of silently using defaults.
 
 `chaptersBase` resolution still consults `BOOK_CHAPTERS_DIR`, content configuration, then `src/content/chapters`. The v4.5+ canonical form is:
 

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