--- title: FIGURES.md — figures & visualizations summary: The standard for every diagram and chart - HTML when a figure has state, two tokenized inline-SVG scaffolds when it does not, one palette each, and a generated diagram carries the same accessible name a hand-drawn one does. when: > Read this BEFORE drawing the first shape of any figure that will ship: a chart, a graph, a timeline, a ratio, an architecture diagram, a flow, a loop, a pipeline. It gives the two inline-SVG scaffolds to copy, the token palette, the type scale, and the rule that no figure publishes without an accessible name. Don't skip because it is "just a quick diagram" or because a mermaid fence is faster to type - a freehanded figure will not match the family, and a mermaid fence without a label is refused and degrades to a code block rather than rendering. --- # Figures & visualizations: the standard > The standard for every diagram and chart in Tjakoen's notes, docs, and pages. Companion to > [`VOICE.md`](VOICE.md) (which owns the prose); this file owns the pictures. The point is that a > figure should be built to a **contract**, not hand-drawn from zero each time. Every figure here is > **inline SVG**, built to one of two scaffolds, so it renders on the published no-build site with zero > dependencies and every figure is a member of the same family: you re-skin them all by editing tokens, > never by editing shapes. Same philosophy as the rest of the stack: tokens are the theme, DRY to a > fault, design tells the truth. ## Three figure shapes, two media (the one rule) **A figure that has state is HTML. A figure that does not is inline SVG.** That is the whole decision, and it was settled on 2026-08-18 after the fourth attempt at a note whose figures had to work at reading size and at the back of a room. | The figure is… | Build it as | Why | |---|---|---| | **Something a reader can change** (a dial, a toggle, a cursor, a run) | **HTML + CSS**, in a shared module, mounted by both the post and the deck | An SVG viewBox fixes proportions to whatever the author guessed. HTML scales with its container, so one figure serves a paragraph and a projector without two drawings, and the state lives where state belongs. | | **Quantitative data-viz** (bars, ratios, timelines, the multiplier) | the **data-viz scaffold** below | Precise proportions, exact labels, one fixed measure down the page; it carries its own palette so it looks identical everywhere, even committed as an image. | | **A flow, loop, relationship, or architecture** (steps, cycles, one box into the next) | the **flow scaffold** below | It sizes to its own content and themes with the site (it inverts in dark), so a diagram reads as part of the page it lives on. | **What changed, and what did not.** The earlier rule said "everything is inline SVG", with a live version allowed only as a progressive enhancement layered over a static one. That inverted in practice: on `notes/build-the-floor.md` five of six figures are HTML and the fallback is a sentence of prose rather than a second drawing, because maintaining a picture and its interactive twin means they drift. **The fallback rule still stands in spirit: what the server sends must argue the point by itself.** For an HTML figure that means the host wraps a real sentence describing what the figure shows, not an empty div. No-JS, print, a crawler and the static export all still get the argument. **Where the live modules live.** `scripts/figure-*.js`, one mount per figure, registered in `scripts/figures.js` for prose and imported by the deck's own driver for slides. The behaviour is written once so a slide and a paragraph cannot argue two different things from the same picture. Every mount returns `false` on unexpected markup so the caller can restore the fallback. **Status is weight, not hue.** `--color-accent` resolves to ink in this theme, so colour carries no signal. Filled, hollow and faint are the three states available, and they mean something: filled is done or counted, hollow is present but unabsorbed, faint is not yet. Which of the two SVG scaffolds you copy, when SVG is still right, is decided by what the figure *is*: | The figure is… | Copy | Palette | Why | |---|---|---|---| | **Quantitative data-viz** — bars, ratios, timelines, the multiplier | the **data-viz scaffold** below | self-contained e-ink palette, hardcoded on the root | Precise proportions, exact labels, one fixed measure down the page; it carries its own palette so it looks identical everywhere, even committed as an image. | | **A flow, loop, relationship, or architecture** — steps, cycles, "A → B → C" | the **flow scaffold** below | inherits the page's `--color-*` theme tokens | It sizes to its own content and themes with the site (it inverts in dark), so a diagram reads as part of the page it lives on, not a pasted-in light rectangle. | **On mermaid.** For most of this standard's life it could not be published at all: the site ships zero framework JS, MILL had no server-side renderer, and a mermaid block that looked right in an editor preview arrived **blank on the live site**. Practice converged on hand-built flow SVGs, and that is still the default. **This changed on 2026-08-16.** MILL renders a mermaid fence to inline SVG on the server, styled with the page's own theme tokens, and since mill 0.4.0 the fence has to carry a label saying in words what the diagram shows. A fence with no label is refused, warned about, and degraded to a code block, which is why an unlabelled diagram cannot reach a page by accident. Reach for the flow scaffold first anyway: a hand-built flow is smaller, it needs no render step, and it is the family the rest of the site is drawn in. Mermaid earns its place when a diagram is generated rather than drawn. Don't reach for it to chart a proportional bar either, that has always been an SVG. ## The data-viz scaffold (copy this, don't freehand) Every data-viz SVG starts from this exact skeleton. The palette lives **once**, as CSS custom properties on the `` root; every shape and label references a token via `style="…:var(--x)"`. Change a color in one place and the whole figure re-skins. No hardcoded hex below the root. ```html Figure title The single payoff line. ``` ### The tokens (the palette, single source) | Token | Value | Role | |---|---|---| | `--paper` | `#faf7f1` | warm background | | `--edge` | `#e6ddd0` | hairline frame | | `--ink` | `#2b2b2b` | primary bars + emphatic labels | | `--muted` | `#6b6259` | titles, secondary labels, values | | `--bar` | `#cbc1b3` | the *lesser* bar (the thing being out-measured) | | `--accent` | `#d97757` | coral, **used exactly once**, on the payoff line | ### The type scale Serif always (Georgia / Times, set once on the root and inherited). Sizes: **title 15**, **label 14**, **value 12.5**, **payoff note 13**. Nothing else. ### Non-negotiables - **Canvas is `0 0 620 H`**, `width="100%"`, `max-width:560px`. Vary only the height `H`. This keeps every figure the same measure down the page and responsive by default. - **`role="img"` + an `aria-label` that states the data in words.** The figure is decorative to a screen reader without it; the label *is* the accessible figure. (AI-legible ≈ agent-affordance ≈ a11y, same coin.) - **One accent, one payoff line.** The coral appears once. If two things are "the point," neither is. - **Self-contained.** No external assets, no ``, no web fonts. It must survive the static export. - **No `