Ship deterministic hand-authored SVG generators for print-quality figures backed by real published datasets. Ships the .mjs generator pattern reading from data/<slug>.json, the data-sha256 audit hash embed for provenance, the dataset-first rule with contract tests pinning headline numbers, the dataset-inversion procedure for reverse-engineering data from an approved sample SVG, the fix-in-generator-never-in-SVG rule, and the figure-count hoist to one JSON. Use when authoring reproducible book or report figures, when a figure's numbers might drift silently, or when reverse-engineering data from a graphic whose dataset is missing.
Ship deterministic hand-authored SVG generators for print-quality figures backed by real published datasets. Ships the .mjs generator pattern reading from data/<slug>.json, the data-sha256 audit hash embed for provenance, the dataset-first rule with contract tests pinning headline numbers, the dataset-inversion procedure for reverse-engineering data from an approved sample SVG, the fix-in-generator-never-in-SVG rule, and the figure-count hoist to one JSON. Use when authoring reproducible book or report figures, when a figure's numbers might drift silently, or when reverse-engineering data from a graphic whose dataset is missing.
lastReviewed
2026-07-29T00:00:00.000Z
Figure generator discipline
Deterministic figure production for books, reports, and any artifact where a figure's numbers have to survive re-generation and stay auditable. Distilled from a shipped book — Fabio Correa's The Defensible Decision, 53 figures across 14 chapters, every generator hand-authored, every dataset published — via Alex_DDA's dd-book-illustrator skill.
The engineering side of the illustration workflow. print-svg-style-guide governs how figures LOOK; this skill governs how they get MADE, VERSIONED, and AUDITED.
When to invoke
Authoring a new figure for a book, report, or exec-facing document whose numbers should stay traceable
Re-authoring an existing figure whose data has drifted or whose script is missing
Reverse-engineering the underlying dataset from an approved sample SVG
Setting up a contract test for a new figure's headline numbers
Diagnosing why a figure's numbers do not match the surrounding prose
The generator pattern
Every shipped figure is emitted by a deterministic .mjs script that:
Reads from data/<slug>.json — never inlines the numbers
Computes a SHA-256 hash of the source data
Embeds the hash in the SVG as an XML comment (<!-- data-sha256: ... -->)
Emits to assets/figures/<NN>-<slug>.svg (or the project's chosen path)
Layout math is exact. Statistical-chart libraries (Vega-Lite, ECharts, Chart.js via the flint-chart MCP server) own final geometry — they stretch within a baseSize ceiling and return their own computedSize. Print-legibility gates and bounds gates need the generator to own layout, not the renderer.
Regen is byte-stable. Given the same dataset, a hand-authored generator produces byte-identical output. That is what makes data-sha256 a useful audit hash.
Debugging is easier. When a figure looks wrong, console.log() inside the generator shows exactly the numbers it saw. A renderer failure hides behind opaque layout errors.
flint-chart still has a role — as an EXPLORATION tool during the design pass (Step 5a of the [chart-big-idea → flint-chart → hand-author] pipeline). Flint helps pick a chart family faster than reasoning from scratch. The shipped artifact, though, is always a hand-authored generator when the target is print.
Dataset-first rule
Every figure must be backed by a REAL, PUBLISHED dataset. Never inline composite numbers. The rule holds for character-anchored figures and generic figures alike; the reader must be able to reproduce the scenario.
The publication set for each dataset:
data/<slug>.json (source of truth)
data/<slug>.csv (human-readable copy for readers who prefer tables)
data/<slug>.schema.json (JSON Schema so downstream consumers can validate)
For a companion-site workflow (static-site publication):
Publish to datasets/<slug>/ on the site (schema page + CSV + JSON + README)
Publication is a PREREQUISITE for shipping the figure, not a follow-up
Naming convention: <slug> describes the figure content, not the character or the chapter. q3-region-revenue is right; chapter-5-figure-4 is not. Readers look up datasets by concept, not by figure number, so the concept has to be in the name.
Contract tests (pin the headline numbers)
For every figure, write a contract test that pins the values the surrounding prose cites. Runs via Node's built-in test runner.
Per-segment values the prose names ($1.7M variance in EMEA)
Ordinal claims (2.18× larger, third-lowest, only region falling)
What NOT to pin
The full dataset shape (schema tests belong in a separate <slug>.schema.test.mjs)
Numbers that appear ONLY in the figure and never in prose (over-constrained; makes future dataset edits noisy)
Register the test
Many projects use an explicit test list (e.g., dd:contract in the DDA workflow). Dropping a new <slug>-contract.test.mjs into scripts/ does nothing if the harness enumerates its tests explicitly. Add the test to whatever list the project maintains. The tell is the test count: if it did not rise by the number of tests you wrote, you are not wired in.
Both edits ship together — the per-figure script and the aggregate list.
Fix in the generator, never in the SVG
Manual SVG edits get clobbered on the next regen. The rule is absolute:
Symptom
Fix in
Number wrong in the SVG
The generator's layout math, or the dataset
Text truncated
The generator's layout — see print-svg-style-guide § "when text won't fit" (cut / reflow / abbreviate / grow)
Color miscoded
The generator's palette lookup, not the SVG's fill attribute
XML-invalid comment (-- inside, bare &)
The generator's comment emission — see render-verify § SVG XML invalid
Regenerating clobbers your patch
That is the rule working, not a bug
The one legitimate exception: a one-off, throwaway figure that will never regenerate. If you are SURE, hand-edit the SVG. But then treat that SVG as the source of truth and delete the generator, so the next contributor is not misled.
Dataset inversion (reverse-engineer the data from an approved sample SVG)
Sometimes an approved sample SVG exists but its underlying dataset is missing. Do not reconstruct the data from prose descriptions — prose fabricates. Invert the sample.
Procedure
Extract axis tick coordinates and their labeled values from the sample.
Look for <text> elements near axis lines with numeric content; those are tick labels. Match each label to the <line> coordinate it labels.
Solve two ticks for the linear scale:
pxPerUnit = (y1 - y2) / (v2 - v1)
where y1, y2 are pixel Y coordinates of two ticks and v1, v2 are their labeled values. Example from a shipped case: Fig 6.6 solved to 2.25 px per point.
Invert every data-point coordinate through the scale.
Round to the domain's natural precision (integer, one decimal, etc.).
The test that the derivation is faithful: every derived value resolves to an EXACT value on the natural grid. Fig 6.6's 24 data points all landed on integers — no fractional pixels, no rounding fudge. If they do not, either the scale is wrong or the sample is drawing something other than the dataset you think it is.
Feed the derived values into the generator and verify byte-identity. The output polylines should be byte-identical to the sample. That is the strongest evidence the dataset faithfully encodes the approved design.
Why inversion beats prose reconstruction
Prose fabricates. In a real case, prose said "EMEA is the only region falling" — the sample proved three regions decline and the two lines diverge (gaps 10 → 15 → 20 → 30). A generator authored from the prose would have shipped one wrong region trajectory. The sample doesn't lie, and the byte-identity check is the strongest possible verification.
Figure-count hoist (one JSON, not scattered constants)
When a project runs multiple gates that all depend on "how many figures are expected," hoist the count into one JSON file. Every gate reads from it. Adding a figure touches ONE file.
{"expectedFigures":62,"expectedPages":439}
Consumers read the same file:
check-placeholders.cjs — counts ![...]() declarations in chapter markdown
build-pdf.js — counts figures embedded as data-URIs during the build
check-rendered-figures.cjs — counts /Image XObjects in the built PDF
check-placeholders.test.cjs — the contract test for the above
JSON, not a .js module, is deliberate: if the root package.json declares "type": "module", the .js build script is ESM and cannot require(), while the gate scripts are .cjs. JSON is the only format both read without a bridge (CJS require, ESM readFileSync + JSON.parse).
Before hoisting, the figure count typically lives scattered across three or four files. Three of the four go silently stale on the next figure. Bump one number, hope the rest catch up, discover in a slow build that one did not. Hoist eliminates the class of drift.
Page count: measure, do not predict
expectedPages must be read off the PDF-build output, never assumed. A figure does not reliably add a page. In the DDA workflow, Fig 5.4 added a page; Fig 6.6 did not (439 → 439). Set the value AFTER the build, not before.
Anti-patterns
Don't
Do
Inline numbers in the generator (const q3Total = 28400000)
Read from data/<slug>.json and hash the raw text into the SVG
Ship a figure without a contract test
Numeric truth is the argument's substrate; drift without a test is silent
Hand-edit the emitted SVG to fix a defect
Grep scripts/generate-* for the filename first — fix the generator, then re-run it
Reconstruct a dataset from prose descriptions
Prose fabricates. Invert the sample instead
Bump the figure count without hoisting
Every gate that reads a figure count separately is a future stale-count bug
Predict expectedPages from figure count
Measure it off the built PDF
Skip test-registration ("the test file exists, it must run")
Explicit test lists silently skip unregistered files. The tell is the test count did not rise
Ship a figure whose SVG passes every gate but is XML-invalid
See render-verify § SVG XML invalid. Inline HTML is lenient; <img> is strict
Adapted from The Defensible Decision (Fabio Correa) via the dd-book-illustrator skill in Alex_DDA. The generator pattern, contract-test discipline, and dataset-inversion procedure are book-tested across 53 shipped figures.
