@humanforest/slidev-theme 0.1.0

package/components/mermaidTheme.ts

@@ -0,0 +1,972 @@
+// Mermaid, in Forest colours and at room scale.
+//
+// ★★ WHY THIS IS CONFIG AND NOT CSS, which is the fact that shapes everything below. Slidev renders
+// a mermaid diagram into a SHADOW ROOT (@slidev/client/builtin/Mermaid.vue mounts the SVG through
+// internals/ShadowRoot.vue). A stylesheet in this theme cannot reach inside one. Custom properties
+// DO pierce the boundary, but that does not help either: mermaid writes literal colours into a
+// <style> block it generates itself, and derives about a hundred secondary values from the ones it
+// is handed using real colour arithmetic (khroma) — hand `var(--deck-accent)` to that and you get
+// NaN, not a green. So the only way in is mermaid's own `themeVariables`, in literal hex, per
+// register. components/deckPalette.ts is what makes that safe: the hex is derived from the same
+// generated tokens the stylesheet is, never typed.
+//
+// Out of the box the diagrams were unusable on this deck — lavender nodes, 10px labels on a 1920px
+// canvas, and on a dark slide an edge stroke a shade off the ground it was drawn on. Probed before
+// any of this was written.
+//
+// ── THE COLOUR ASSIGNMENT ──────────────────────────────────────────────────────────────────────
+//
+// A diagram is not a chart. Its job is to show a STRUCTURE, so the default node is a quiet surface
+// — the same `--deck-surface` a Card sits on — and colour is spent only where it means something:
+// the accent on the edges and arrowheads that carry the reading order, and the categorical series
+// only where a diagram genuinely encodes categories (pie slices, git branches). A flowchart whose
+// every node is a different colour has spent its whole palette on nothing.
+//
+// FIVE, AND THE DECK'S CEILING IS SIX — so this is a deliberate stop short of it, not a mirror of
+// it. The sixth vivid slot is `red`, and chartData.ts records it sitting dE00 3 from
+// --deck-status-danger-mark on the dark ground. In a chart that is a warning; here it is worse,
+// because the crit bar below is already that hue, so a six-colour pie would put a category and an
+// alarm side by side in the same red. pie6..pie12 cycle back through the five rather than inventing
+// hues nobody validated: mermaid will happily draw a twelve-slice pie, and it will do it in five
+// colours, which is the honest picture of a chart that has run out of palette.
+//
+// ── ROOM SCALE ────────────────────────────────────────────────────────────────────────────────
+//
+// `fontSize` is a NUMBER, in the SVG's own coordinate space, and mermaid lays every box out around
+// it — so it is the one lever that decides whether a diagram is legible. It is set from the deck's
+// own body-sm rung rather than from a taste-picked number, which means a diagram's labels and the
+// paragraph beside it are the same size by construction.
+import { DATAVIZ_CATEGORICAL } from '@humanforest/tokens/colourEngine';
+import { BACKGROUND_NAMES, derivedMix, mixOklab, palette, background, ramp, type Register } from './deckPalette';
+
+/**
+ * The categorical series, resolved — the PUBLISHED vivid set, sliced to five.
+ *
+ * ★★ THIS USED TO BE A BAND OF BRAND RAMPS (forest/river/amber/maple/acid at 600/400) under a
+ * comment claiming it mirrored deck.css's `--deck-series-N` aliases. It shared ZERO hex values with
+ * them, in either register, and nothing anywhere recorded a reason — the file has one commit and its
+ * message repeats the same false claim. So it was a transcription, not a decision.
+ *
+ * ★★ AND THE BRAND BAND WAS BROKEN AT THE ONE JOB THESE KEYS HAVE. Measured with colourEngine's own
+ * dE00cvd: brand amber against brand acid is worst-case-CVD dE00 3 on light and 1 on DARK — two pie
+ * slices that are the same colour to a dichromat, forever, with nothing on screen to say so. The
+ * published five hold 9 and 8. A categorical slot whose categories collapse is not a palette choice,
+ * it is a defect.
+ *
+ * Taken from DATAVIZ_CATEGORICAL directly, which is the same source scripts/dataviz.ts generates
+ * deck.css's aliases from, so there is no second copy to drift.
+ *
+ * ★ THE GAP THIS CANNOT CLOSE, stated because it is real: a `.deck-pairs` slide re-points
+ * --deck-series-* to the brand pairs at render time, and mermaid is baked per REGISTER at build
+ * time. A diagram on such a slide keeps the vivid five while the charts beside it turn to pairs.
+ * Mermaid takes hexes, not var() references; following a slide class would mean re-theming mermaid
+ * per slide, which is a bigger machine than the mismatch is worth.
+ */
+export const SERIES: Record<Register, string[]> = {
+  light: DATAVIZ_CATEGORICAL.light.slice(0, 5),
+  dark: DATAVIZ_CATEGORICAL.dark.slice(0, 5),
+};
+
+/** The label size every box is laid out around — the deck's body-sm rung, in px. */
+export const MERMAID_FONT_PX = 36;
+
+/*
+  THE DECK'S STRONG EDGE, in SVG USER UNITS so it scales with the drawing rather than standing still
+  while everything around it shrinks — see the long note in setup/mermaid-renderer.ts, which
+  re-exports this and is where most of the rules that read it live. It is declared HERE because
+  radar states its weights as theme variables, and theme variables are built in this file.
+*/
+export const DIAGRAM_STROKE_PX = 4;
+
+/*
+  A LEGEND ENTRY — the key beside a chart, on any family that draws one. Subordinate to the diagram's
+  own prose and read at a glance rather than across the room, which is what four fifths of the body
+  rung says. The pie's legend has taken this size since it was written; radar joins it, and the
+  renderer's swatch and row-spacing pass read the same number so the three cannot drift apart.
+*/
+export const MERMAID_LEGEND_FONT_PX = Math.round(MERMAID_FONT_PX * 0.8);
+
+/*
+  Mermaid's own numeric defaults are drawn for its default 16px type. Any of them that is a BOX and
+  not a font has to be scaled by hand when the font moves, because mermaid sizes the box from the
+  config and the text from `fontSize`, and never compares the two.
+*/
+const MERMAID_DEFAULT_FONT_PX = 16;
+
+/*
+  The sequence fragment's keyword — `opt`, `alt`, `loop` — is a structural marker rather than part
+  of the diagram's prose, and takes a step down from the body rung every label around it uses. The
+  renderer sets the TEXT from this same number — with `!important`, because mermaid writes the
+  keyword's size as an INLINE STYLE and no plain rule reaches it. The tab is the BOX it sits in, so both move
+  together or the word stops fitting again.
+*/
+export const MERMAID_TAG_FONT_PX = Math.round(MERMAID_FONT_PX * 0.5);
+
+/*
+  The autonumber index, which USED to share the tag rung and no longer does. Both are subordinate
+  to the diagram's prose, but they are subordinate to different things: a fragment keyword labels a
+  block and can afford to recede, while an index is read against the message it numbers and has
+  just enough glyph to be read at all. Tying them meant every step down for one was a step down for
+  the other.
+*/
+export const MERMAID_INDEX_FONT_PX = Math.round(MERMAID_FONT_PX * 0.7);
+
+/*
+  A transition name — the word ON an edge. Subordinate to the node labels it joins, which is the
+  argument that also mutes it to 75%, but it is PROSE and not a mark: it has to be read across a
+  room, where an index only has to be counted. So it steps down one rung and no further, where the
+  fragment keyword steps down two and the index sits between them. Three roles, three rungs, none
+  of them borrowing another's — tying any two means a change for one is a change for the other.
+*/
+export const MERMAID_EDGE_LABEL_FONT_PX = Math.round(MERMAID_FONT_PX * 0.8);
+
+/** A quadrant point's dot. Its label's clearance is derived from it — see `pointTextPadding`. */
+const QUADRANT_POINT_RADIUS = 12;
+
+const toTagScale = (mermaidDefault: number) =>
+  Math.round((mermaidDefault * MERMAID_TAG_FONT_PX) / MERMAID_DEFAULT_FONT_PX);
+
+/** The deck's sans, as a family string. @font-face is DOCUMENT-scoped, so the face a shadow root
+ *  names is the same one the slide loaded — no second copy, no second request. */
+export const MERMAID_FONT_FAMILY = "'GT Haptik', system-ui, sans-serif";
+
+/**
+ * Mermaid's `themeVariables`, for one register.
+ *
+ * Written as one flat table on purpose. Mermaid's variables are a per-diagram-type vocabulary with
+ * no shared spine — `mainBkg` is a flowchart node, `actorBkg` the same idea in a sequence diagram,
+ * `nodeBorder` and `actorBorder` likewise — and leaving any of them unset means mermaid DERIVES it
+ * from `primaryColor` with its own colour maths, which is exactly how a Forest-green flowchart ends
+ * up sitting next to a lavender sequence diagram. So every family is stated, and the grouping
+ * comments below say which diagram each block is actually steering.
+ */
+export function mermaidThemeVariables(register: Register): Record<string, string> {
+  const p = palette(register);
+  const series = SERIES[register];
+  const [s1, s2, s3, s4, s5] = series;
+
+  return {
+    // ★★ `darkMode` IS DELIBERATELY NOT SET, and setting it is a trap worth naming. Mermaid's base
+    // theme uses that flag to DERIVE a dark palette from a light one — it runs `invert()` over
+    // primaryColor and its relatives. Handed an already-dark `primaryColor` it inverts it back to
+    // light: measured, the dark register rendered cream nodes with near-black labels on a dark
+    // slide, which reads as the light theme leaking through rather than as a bug. Every value here
+    // is stated for both registers, so there is nothing left for mermaid to derive.
+    background: p.bg,
+    fontFamily: MERMAID_FONT_FAMILY,
+    fontSize: `${MERMAID_FONT_PX}px`,
+
+    // ── The spine every diagram type derives from ─────────────────────────────────────────────
+    // A node is a Card: the quiet surface one step off the page, with the deck's own border.
+    primaryColor: p.surface,
+    primaryTextColor: p.fg,
+    primaryBorderColor: p.borderStrong,
+    secondaryColor: p.surface,
+    secondaryTextColor: p.fg,
+    secondaryBorderColor: p.border,
+    /*
+      ⚠ THREE SLOTS ON THE DECK SURFACE, AND TWO OF THEM DO NOT DRAW. tertiary, labelBox and
+      activation all pointed at --deck-accent-soft, a role that has since been retired because
+      nothing in the theme rendered it: drawn on both registers, mermaid v11 leaves the opt/alt label
+      box and the activation bar OUTLINED, whatever these two variables say, and no diagram in the
+      deck reaches tertiary. They point at the derived surface now — a box on the page, in either
+      register — because a slot that does not render today is exactly where not to plant
+      --deck-bg-accent, which on the dark register IS the page.
+    */
+    tertiaryColor: p.surface,
+    tertiaryTextColor: p.fg,
+    tertiaryBorderColor: p.border,
+    // ★ THE EDGE CARRIES THE READING. It is the accent, at full strength, because the line between
+    // two boxes is the only part of a flowchart that says what the diagram MEANS — and on a dark
+    // slide the shipped default drew it a shade off the ground.
+    lineColor: p.accent,
+    textColor: p.fg,
+    mainBkg: p.surface,
+    nodeBorder: p.borderStrong,
+    nodeTextColor: p.fg,
+    titleColor: p.fg,
+
+    // ── Flowchart ─────────────────────────────────────────────────────────────────────────────
+    clusterBkg: p.surface,
+    clusterBorder: p.border,
+    // The label sitting ON an edge needs the PAGE behind it, not the node fill — it interrupts a
+    // line, it does not sit in a box.
+    edgeLabelBackground: p.bg,
+    defaultLinkColor: p.accent,
+    arrowheadColor: p.accent,
+
+    // ── Sequence ──────────────────────────────────────────────────────────────────────────────
+    actorBkg: p.surface,
+    actorBorder: p.borderStrong,
+    actorTextColor: p.fg,
+    actorLineColor: p.borderStrong,
+    signalColor: p.accent,
+    signalTextColor: p.fg,
+    labelBoxBkgColor: p.surface,
+    labelBoxBorderColor: p.accent,
+    labelTextColor: p.fg,
+    loopTextColor: p.fg,
+    /*
+      ★★ THE NOTE IS WARM WHERE THE FLOW IS ACCENT, and that is a semantic split rather than a
+      preference. Everything else in a sequence belongs TO the sequence — the signals, the actor
+      boxes, the activation bars, the opt/alt label boxes — and they are all the accent family. A
+      note is the one element that comments ON it from outside, so it takes the other family the
+      deck publishes. Give the annotation the same green as the thing it annotates and the reader
+      has to parse the shape to find the aside.
+
+      It is the warm PAIR, not a warm fill: --deck-bg-warm with --deck-on-bg-warm as both the ink and
+      the edge, so the box can never assemble an ink that was not measured against its own ground
+      (10.26:1 on light, 6.81:1 on dark). The border was `p.accent` — a green edge on a peach fill,
+      which is what borrowing a fill from one family and an edge from another looks like.
+
+      ★ IT ALSO SEPARATES BETTER FROM THE PAGE, which is the part I did not expect. Against the
+      deck's own grounds, warm measures 1.30:1 on cream and 2.21:1 on near-black, where accent-soft
+      manages 1.13 and 1.36. A note box is a filled box whose job is to be visibly a box.
+    */
+    noteBkgColor: background('warm', register).fill,
+    noteTextColor: background('warm', register).ink,
+    noteBorderColor: background('warm', register).ink,
+    activationBkgColor: p.surface,
+    activationBorderColor: p.accent,
+    sequenceNumberColor: p.onAccent,
+
+    // ── State ─────────────────────────────────────────────────────────────────────────────────
+    labelColor: p.fg,
+    transitionColor: p.accent,
+    transitionLabelColor: p.fg,
+    stateLabelColor: p.fg,
+    stateBkg: p.surface,
+    /*
+      ★★ ONE GROUND FOR THE WHOLE COMPOSITE, TITLE BAND INCLUDED. `compositeTitleBackground` was the
+      page and `compositeBackground` the surface, which drew the container as two stacked grounds
+      with a seam across it — a title strip in one colour over a body in another, inside a border
+      meant to hold ONE object. mermaid offers the pair so a title can be picked out; this deck
+      already picks a container's title out by its position and its weight, and a second fill is the
+      kind of decoration the diagram doctrine here spends colour to avoid.
+
+      Both the surface now, so a composite reads as what it is: a Card with a machine in it, the
+      same treatment `subgraph` gets in the flowchart.
+    */
+    altBackground: p.surface,
+    compositeBackground: p.surface,
+    compositeBorder: p.border,
+    compositeTitleBackground: p.surface,
+    /* ⚠ DEAD IN 11.17.2, KEPT FOR THE NAME. stateEnd fills the inner dot from `stateBorder ?? nodeBorder`
+       and never reads this; mermaid's own `.node circle.state-end { fill: innerEndBackground }` cannot
+       match either, because the group it targets is classed `outer`. Recorded rather than removed, so
+       the next reader does not re-derive it. */
+    /*
+      ★★ THE GANTT'S EXCLUDED BAND IS A LITERAL GREY WITH NO DERIVATION. The base theme defaults it
+      `this.excludeBkgColor = this.excludeBkgColor || "#eeeeee"` — a fixed light grey, not a step off
+      anything the deck sets, so `excludes weekends` painted #eeeeee on warm paper in the light
+      register and the same #eeeeee on near-black in the dark one. It takes the deck's own surface,
+      which is what every other quiet band in the family already uses.
+    */
+    excludeBkgColor: p.surface,
+    innerEndBackground: p.fg,
+    specialStateColor: p.fg,
+
+    // ── Class / ER ────────────────────────────────────────────────────────────────────────────
+    classText: p.fg,
+    /* Odd/even alternated surface against the 8% bg-subtle — 1.08:1, a stripe in name only. Now
+       surface against the page, which is the same alternation every other striped thing here uses
+       (gantt sections, quadrants) and one the eye can actually follow.
+
+       ⚠ AND BOTH OF THESE ARE DEAD IN 11.17.2, kept only because they cost nothing and name the
+       intent. `attributeBox` appears nowhere in mermaid's dist, and the ER stylesheet has no
+       `.attributeBoxOdd`/`.attributeBoxEven` rule to read them. The rows are drawn from `rowOdd`
+       and `rowEven` instead — see below. */
+    attributeBackgroundColorOdd: p.surface,
+    attributeBackgroundColorEven: p.bg,
+    /*
+      ★★ THE KEYS THE ATTRIBUTE TABLE ACTUALLY READS, and leaving them unset painted it WHITE on
+      both registers. shapes/erBox reads `rowEven`/`rowOdd` off themeVariables for every attribute
+      row; unset, theme-base derives them — and its light branch is `lighten(mainBkg, 75)`, which on
+      this deck's surface CLAMPS TO #ffffff. Worse on the dark register than the light one, because
+      `darkMode` is deliberately never set here (see above), so the light branch runs there too and
+      a near-white band lands on a near-black slide.
+
+      Same alternation the dead pair above names, now on the keys that read it.
+    */
+    rowOdd: p.surface,
+    rowEven: p.bg,
+
+    // ── Pie — CATEGORICAL, and this file stops at five though the deck allows six (see above) ──
+    // pie6..pie12 cycle the same five rather than inventing hues. A twelve-slice pie will repeat
+    // colours, which is the honest picture of a chart past its palette.
+    ...Object.fromEntries(
+      Array.from({ length: 12 }, (_, i) => [`pie${i + 1}`, series[i % series.length]]),
+    ),
+    /* ★ MERMAID DEFAULTS PIE SLICES TO 0.7 OPACITY, which is why the series came out washed. At 0.7
+       over paper they are five colours nobody measured; at full strength they are the five that
+       were. The separation between slices comes from the page-coloured stroke below instead.
+
+       ★★ THE OLD VERSION OF THIS NOTE WAS WRONG TWICE and is worth correcting rather than deleting.
+       It said the hex handed in "was the published categorical palette" — it was not, it was a band
+       of brand ramps (see SERIES above), which is the drift this file has now had fixed. And it
+       credited the gate to scripts/dataviz.ts, which contains no contrast code at all: colourEngine
+       exports validateDataViz and nothing in the repo calls it. Two claims of provenance, neither
+       true, sitting above a line whose actual behaviour was correct.
+
+       ★ THE REAL FLOOR, measured. pieSectionTextSize is the deck's body-sm rung x 0.8 = 29px, which
+       is large text, so the in-slice label is held to 3:1 rather than 4.5:1. White ink on the five
+       clears it on light at 3.20-6.46, and the dark register's onAccent ink clears it at 5.00-9.04.
+       The ceiling: mermaid exposes ONE pieSectionTextColor for every slice, so the ink cannot follow
+       the fill — and if a pie is ever shrunk below the large-text threshold the floor becomes 4.5:1,
+       where green, amber and sky fall under. A pie that small is the thing to fix, not the ink. */
+    pieOpacity: '1',
+    pieTitleTextColor: p.fg,
+    pieSectionTextColor: p.onAccent,
+    pieLegendTextColor: p.fg,
+    pieStrokeColor: p.bg,
+    pieOuterStrokeColor: p.bg,
+    pieTitleTextSize: `${MERMAID_FONT_PX}px`,
+    pieSectionTextSize: `${Math.round(MERMAID_FONT_PX * 0.8)}px`,
+    pieLegendTextSize: `${Math.round(MERMAID_FONT_PX * 0.8)}px`,
+
+    /* ── Git graph ─────────────────────────────────────────────────────────────────────────────
+       ★★ THESE ARE NOT PAINTED AS HANDED IN, and the comment here used to say they were ("categorical
+       again, same five"). mermaid darkens every git slot by 25 HSL points before it draws
+       (mermaid.js, `if (this.darkMode) { lighten(git0,25) } else { darken(git0,25) }`), and darkMode
+       is deliberately never set here, so the ELSE branch runs in BOTH registers — including the dark
+       one, where darkening is the wrong direction. The five below are therefore a starting point
+       mermaid transforms, not the palette that reaches the screen.
+       Left as the series anyway: it is still the right input, and the alternative is pre-lightening
+       by 25 to cancel a library behaviour, which breaks the moment mermaid changes it. Recorded
+       rather than worked around. */
+    ...Object.fromEntries(
+      Array.from({ length: 8 }, (_, i) => [`git${i}`, series[i % series.length]]),
+    ),
+    gitInv0: p.onAccent,
+    gitBranchLabel0: p.onAccent,
+
+    /*
+      ── THE TWELVE-SLOT CATEGORICAL, WHICH THE THEME HAD NEVER STATED ─────────────────────────
+
+      ★★ UNSET, THESE COLLAPSE TO ONE COLOUR. Every family that colours itself categorically —
+      timeline, mindmap, kanban, radar, treemap — reads `cScale0..11`, and mermaid's base theme
+      DERIVES them when they are absent: cScale0 = primaryColor, cScale1 = secondaryColor,
+      cScale2 = tertiaryColor, then 3..11 as hue rotations of primaryColor. This theme points all
+      three of those at `p.surface`, deliberately, because a NODE is a Card — so the first three
+      slots were byte-identical and the rest were hue rotations of one near-neutral. A timeline
+      drawn today would have been a row of barely separable greys.
+
+      Stated from the deck's own five, cycled, the way git0..git7 already are. Twelve slots against
+      five colours means a family that needs more than five repeats one rather than inventing a
+      sixth — which is the deck's published ceiling and the same rule the pie takes.
+
+      ⚠ AND EACH IS DARKENED BY 25 BEFORE IT REACHES THE PAGE, in BOTH registers, because mermaid
+      only lightens when `darkMode` is set and this theme deliberately never sets it. Same
+      transform the git slots take; the input is still right, and pre-lightening to cancel a
+      library behaviour breaks the moment that behaviour changes.
+    */
+    ...Object.fromEntries(
+      Array.from({ length: 12 }, (_, i) => [`cScale${i}`, series[i % series.length]]),
+    ),
+    /*
+      ★★ THE INK ON THOSE FILLS IS THE DARK ONE, AND THAT IS THE OPPOSITE OF THE DECK'S USUAL RULE.
+      A categorical fill normally takes `onAccent` — the deck pairs a saturated ground with light
+      ink. It is wrong here for one reason: mermaid DARKENS every cScale slot by 25 before painting
+      it, so the colour on the page is not the colour handed over, and the pairing has to be made
+      against what actually lands. MEASURED off the rendered timeline, white against dark ink on the
+      three bands a three-period timeline draws:
+
+          rgb(0,164,71)  green    white 3.28   dark 5.48
+          rgb(218,118,0) orange   white 3.20   dark 5.62
+          rgb(0,132,200) blue     white 4.09   dark 4.39
+
+      Dark wins on every one, and white only just clears the 3:1 large-text floor on two of them.
+
+      ⚠ THE LIMITATION IS WORTH NAMING: this is one ink for twelve slots, chosen from three measured
+      fills. It is right for the deck's five as mermaid darkens them, and it would need revisiting if
+      the categorical ever gained a genuinely dark member — there the pairing would flip back. The
+      honest fix is a per-slot choice made against the DARKENED value, which needs mermaid's own
+      darken() rather than the palette's.
+    */
+    ...Object.fromEntries(
+      Array.from({ length: 12 }, (_, i) => [`cScaleLabel${i}`, p.fg]),
+    ),
+    commitLabelColor: p.fg,
+    commitLabelBackground: p.bg,
+    /*
+      ★★ THE COMMIT ID IS SIZED HERE, NOT IN CSS. mermaid inserts its <style> BEFORE
+      renderer.draw(), so this variable is live for every getBBox() the renderer takes, and
+      setupGraphViewbox then sets the viewBox from that bbox plus padding. Re-pointed AFTERWARDS by
+      a stylesheet rule, the box was measured on 10px glyphs: rotateCommitLabel swings a label 2.9x
+      longer than the one measured up-and-right of its dot, and the two `main` commits reached
+      y -48.12 against a viewBox top of -34.5, where the svg viewport cut them — the audit saw
+      "fleet v1"/"fleet v2" 12% hidden, 11-12px off the top. Stated here, the bbox contains them.
+      This changes no type size — 29px either way — only when mermaid learns it. Commit spacing does
+      not move: COMMIT_STEP is a fixed 40.
+    */
+    commitLabelFontSize: `${MERMAID_EDGE_LABEL_FONT_PX}px`,
+
+    // ── Gantt ─────────────────────────────────────────────────────────────────────────────────
+    taskBkgColor: p.surface,
+    taskTextColor: p.fg,
+    taskTextOutsideColor: p.fg,
+    taskTextLightColor: p.onAccent,
+    taskBorderColor: p.borderStrong,
+    activeTaskBkgColor: p.accent,
+    activeTaskBorderColor: p.accent,
+    doneTaskBkgColor: p.surface,
+    doneTaskBorderColor: p.border,
+    /* ★★ A STATE, NOT A CATEGORY, and it only looked right by accident. This read `s4` — the fifth
+       series — which under the old brand band happened to be maple, the deck's DANGER family, so a
+       critical task came out red for the wrong reason. Re-pointing SERIES to the published palette
+       turns s4 into INDIGO, which would have made "critical" a calm blue and nothing would have
+       failed. Named against the semantic role instead, so the meaning is the source rather than the
+       ordering. Measured: on light this also lifts the task label from 3.42:1 to 4.60:1, because the
+       role is maple-500 where the old band took maple-600. */
+    critBkgColor: p.dangerMark,
+    critBorderColor: p.dangerMark,
+    gridColor: p.border,
+    todayLineColor: p.accent,
+    /* ★★ A SECTION IS A LANE, AND IT HAD NO GROUND TO SAY SO. mermaid bands the rows behind each
+       section and cycles THREE variables across four indices: section0 takes `sectionBkgColor`,
+       section2 takes `sectionBkgColor2`, and sections 1 and 3 take `altSectionBkgColor`. With the
+       page colour in the first and `altSectionBkgColor` left unset — mermaid's own white — both
+       bands on a two-section chart were invisible, so the section titles read as labels floating
+       beside the bars rather than as names for the rows they own.
+
+       Set so the cycle ALTERNATES: the tint on 0 and 2, the page on 1 and 3. The band is still the
+       quietest surface on the chart; it only has to be visible enough to bound a lane. */
+    sectionBkgColor: p.surface,
+    sectionBkgColor2: p.surface,
+    altSectionBkgColor: p.bg,
+
+    // ── Quadrant / journey / the odd ones out ─────────────────────────────────────────────────
+    quadrant1Fill: p.surface,
+    quadrant2Fill: p.bg,
+    quadrant3Fill: p.surface,
+    quadrant4Fill: p.bg,
+    quadrantPointFill: s1,
+    quadrantTitleFill: p.fg,
+
+    /*
+      ── RADAR ──────────────────────────────────────────────────────────────────────────────────
+      Every one of these is READ by the radar renderer; none of them is shared with another family,
+      which is the usual shape (see the note above about mermaid's per-family variables having no
+      spine).
+
+      ★★ THE LEGEND'S ROW PITCH IS A LITERAL 20 UNITS with no key and no selector behind it — the
+      row group is appended with no class at all — so nothing in this file can raise it and the size
+      below would be CAPPED at about 18 by a pitch it cannot move. It is not, because the renderer
+      re-pitches those rows after the fact: see spaceRadarLegend, which is also what centres the
+      block and seats each swatch against its own word. Stated here because the number below only
+      makes sense with that pass in place — set it larger with the pass removed and the rows collide.
+
+      ★ AND THE AXIS LABEL IS ANCHORED, NOT MEASURED: it is placed at `radius * axisLabelFactor` and
+      grows OUTWARD from there, so raising the size without raising the factor walks the words off
+      the viewBox. The two move together, and the margins below are what pays for it.
+    */
+    /*
+      ★★ AND IT IS A NESTED OBJECT OF NUMBERS, not the flat px strings the rest of this file uses.
+      Written flat first and every one of them was inert — mermaid reads `this.radar?.axisColor`
+      against a `radar` block it builds in theme-base, so a top-level `axisColor` is not a wrong
+      value, it is not a value at all. The sixth instance of this family of defect in this file,
+      and the only one whose tell was that NOTHING changed rather than that something changed wrong.
+    */
+    radar: {
+      axisColor: p.border,
+      axisStrokeWidth: DIAGRAM_STROKE_PX / 2,
+      axisLabelFontSize: MERMAID_EDGE_LABEL_FONT_PX,
+      graticuleColor: p.border,
+      graticuleOpacity: 1,
+      graticuleStrokeWidth: DIAGRAM_STROKE_PX / 2,
+      /*
+        ★ A WASH, NOT A FILL. The polygon's STROKE is what states the shape at the deck's full edge
+        weight, so the area under it only has to say which curve owns which region — and the less
+        it says, the better the graticule underneath it reads. mermaid's 0.5 mixes the deck's green
+        and its orange into an olive that is in neither series; 0.28 kept the hues but still buried
+        the scale rings. At this value both curves keep their colour, every ring stays legible
+        through them, and the overlap still reads as an overlap rather than as a third colour.
+      */
+      curveOpacity: 0.16,
+      curveStrokeWidth: DIAGRAM_STROKE_PX,
+      legendFontSize: MERMAID_LEGEND_FONT_PX,
+      legendBoxSize: Math.round(MERMAID_LEGEND_FONT_PX * 0.8),
+    },
+    fillType0: s1,
+    fillType1: s2,
+    fillType2: s3,
+    fillType3: s4,
+    fillType4: s5,
+    fillType5: s1,
+    fillType6: s2,
+    fillType7: s3,
+  };
+}
+
+/*
+  ── THE FILLED NODE ────────────────────────────────────────────────────────────────────────────
+
+  The deck's four panel grounds, published to mermaid as node classes. An author writes
+
+      A[Rider opens app]:::vivid
+
+  and the node takes the same fill and ink a `background: vivid` panel takes on that register.
+
+  ★ WHY CLASSES AND NOT `classDef`. mermaid's own `classDef` is authored per diagram, in literal
+  colour, inside the slide — four grounds x two registers x every diagram that wants one, restated
+  by hand. `:::name` only ATTACHES the class; what it means is decided here, once, from deck.json's
+  own panel table. So a node cannot drift from the panel it is named after, and a fifth ground
+  reaches every diagram without touching a slide.
+
+  ★★ AND THE PAIR IS WHY THIS IS SAFE. deck.json stores a ground and the ink measured against it
+  TOGETHER, and background() hands back both — so a filled node cannot end up with a light ink on a
+  dark ground the way it could if a slide named two colours by hand. That is the whole argument for
+  spending a class on this rather than letting authors reach for `style A fill:#...`.
+
+  The border is the fill carried toward its own ink by deck.json's own `border-strong` step — the
+  same mix `nodeBorder` takes for the default node, READ from the table rather than copied, so the
+  two cannot separate. That keeps a filled node's edge at the presence of a plain one; the alternative,
+  leaving the default border in place, puts a grey ring on a saturated green.
+
+  ★ `.node` IS TWO FAMILIES, measured. A state diagram's boxes are `g.node …statediagram-state`, so
+  `class Charged vivid` fills one exactly as `:::vivid` fills a flowchart node — the specimen draws
+  that on its dark slide. What is NOT matched is a subgraph (`g.cluster`), and the families that
+  have no node at all: a pie slice, a gantt bar and a quadrant point each carry their own meaning
+  and their own variables.
+*/
+export const NODE_BORDER_MIX = derivedMix('border-strong');
+
+export const MERMAID_BACKGROUNDS: readonly string[] = BACKGROUND_NAMES;
+
+export function mermaidBackgroundRules(register: Register): string[] {
+  return MERMAID_BACKGROUNDS.flatMap((name) => {
+    const { fill, ink } = background(name, register);
+    const stroke = mixOklab(fill, ink, NODE_BORDER_MIX);
+    return [
+      /* ★★ DESCENDANT, NOT `>`, and the shape vocabulary is why. Measured across the flowchart's
+         own shapes: `rect`, `round`, `subroutine`, `cylinder`, `circle`, `rhombus`, `hexagon`,
+         `parallelogram` and `trapezoid` hang their outline directly under `g.node` — but
+         `stadium`, the asymmetric flag and `doublecircle` wrap theirs in an inner
+         `g.label-container`, so a child combinator paints six of the nine and silently skips
+         three. This is the same selector shape mermaid's own node rule uses, deliberately: an
+         override that matches less than the rule it overrides is a background that works on most shapes.
+         The cost is the 0x0 measuring rect inside `g.label`, which mermaid's rule already fills
+         and which paints nothing at either size. */
+      `.node.${name} rect,.node.${name} polygon,.node.${name} path,`
+      + `.node.${name} circle,.node.${name} ellipse{fill:${fill};stroke:${stroke};}`,
+      // Both label forms — see the `htmlLabels` note in mermaidConfig. `color` carries to the <p>
+      // mermaid nests inside the span; `fill` is what an SVG <text> answers to.
+      `.node.${name} span,.node.${name} text{color:${ink};fill:${ink};}`,
+    ];
+  });
+}
+
+/*
+  ── REGISTER-DEPENDENT INK THAT IS NOT A BACKGROUND ─────────────────────────────────────────────────
+
+  ★★ A LABEL ON A CATEGORICAL FILL TAKES `onAccent`, NEVER `fg`, and the ramp level is the reason.
+  The published categorical is TW v4's 600 step on light (#00a447, #da7600, #0084c8 …) and its 400
+  step on dark. The house rule: at 500 and above a fill carries WHITE (or a -100/-50 tint); at 400
+  and below it can carry a dark ink. `p.onAccent` is exactly that pair already — #ffffff on light,
+  the deep green on dark — so naming it satisfies the rule in both registers by construction rather
+  than by two hand-picked colours that have to be re-checked whenever the palette moves.
+
+  A journey is the one family that got this wrong: its section and task labels inherited `fg`, so a
+  near-black sat on a 600-level green. The pie has always taken `pieSectionTextColor: p.onAccent`,
+  which is the same decision made in the one place mermaid gave it a variable.
+
+  These live apart from `mermaidBackgroundRules` because they are not backgrounds — no panel ground is involved,
+  and they apply whether or not an author names a class.
+*/
+export function mermaidInkRules(register: Register): string[] {
+  const p = palette(register);
+  return [
+    /*
+      The journey's own label hook: mermaid wraps the foreignObject text in a div carrying the
+      section/task class, so this reaches the label WITHOUT touching a flowchart's node labels,
+      which are the same foreignObject shape one family over.
+
+      ★ THE INNER `.label` MUST BE NAMED TOO. mermaid sets `#id .label { color: … }` directly on the
+      div that holds the text, and a colour set ON an element beats one inherited from its parent no
+      matter what the specificity of the parent's rule is. Naming only the section here loses to it
+      every time.
+    */
+    `.journey-section,.task,.journey-section .label,.task .label{color:${p.onAccent};}`,
+    // The satisfaction face is mermaid's own cornsilk on a mid grey, which is the one thing on this
+    // chart that belongs to no palette at all.
+    `.face{fill:${p.bg};stroke:${p.fg};}`,
+    // The guide the face slides along. mermaid writes its colour and dash INLINE, hence the hammer.
+    `.task-line{stroke:${p.fgSubtle} !important;}`,
+    /*
+      ★★ A GANTT LABEL INSIDE A DARK BAR NEEDS THE OTHER INK, AND NO THEME VARIABLE CAN SAY SO.
+      mermaid paints `.activeText*` and `.doneText*` from ONE variable — `taskTextDarkColor` — and
+      uses that same variable for `.taskTextOutsideLeft/Right`, which sit on the PAGE. One value for
+      a label on a dark bar and a label on cream: whatever it is set to, one of the two is wrong.
+
+      Measured before this rule: `#191617` on the active bar's `#046c4c` scored 2.60:1, under even
+      the 3:1 large-text floor, on a slide the audit cannot see because a diagram renders into a
+      shadow root.
+
+      So the ink is split by SELECTOR instead. An inside label carries `taskText`; an outside one
+      carries `taskTextOutsideLeft` and never `taskText`, so naming the former reaches exactly the
+      labels that sit on a fill and leaves the page ones alone. `!important` is required because
+      mermaid's own `.activeText*` rule carries it.
+
+      Both saturated bars take `onAccent`, the same pair the pie and the journey take: the active
+      bar is the accent and the critical one the danger mark, and on light both are 500-or-above
+      fills, which carry white. ⚠ Only the ACTIVE case is drawn inside today — the specimen's
+      critical bar has a label too long for it, so mermaid puts that one outside. The crit rule is
+      the same mechanism stated once rather than a second thing to remember later.
+    */
+    ...[0, 1, 2, 3].flatMap((i) => [
+      `.taskText.activeText${i}{fill:${p.onAccent} !important;}`,
+      `.taskText.critText${i}{fill:${p.onAccent} !important;}`,
+    ]),
+    // The lane band, at the strength it was given rather than at mermaid's blanket 0.2 — which
+    // washed every section ground back to the page it sits on.
+    `.section{opacity:1;}`,
+    /*
+      ★★ THE ACTOR DOT IS PAINTED FROM CSS BECAUSE ITS CONFIG KEY CANNOT WORK. `journey.actorColours`
+      is a real key on a real path (`getConfig().journey.actorColours`), and setting it changes
+      nothing — mermaid merges config with `assignWithDepth`, whose array branch is
+
+          if (Array.isArray(src) && Array.isArray(dst)) { src.forEach(s => { if (!dst.includes(s)) dst.push(s) }) }
+
+      i.e. it APPENDS to the default array rather than replacing it. Index 0 stays mermaid's
+      DarkSeaGreen and index 1 its LawnChartreuse, whatever is passed. Every other journey key here
+      is a scalar and lands normally, which is why this one looked like it had worked.
+
+      The dot's colour is a presentation ATTRIBUTE, and CSS outranks those, so the same five the pie
+      spends reach it from here instead. The dead key is not left in the config beside the live ones:
+      a setting that reads as configuration and does nothing is the more expensive kind of wrong.
+    */
+    ...Array.from({ length: 8 }, (_, i) => {
+      const fill = SERIES[register][i % SERIES[register].length];
+      return `circle.actor-${i}{fill:${fill};stroke:${mixOklab(fill, p.fg, NODE_BORDER_MIX)};}`;
+    }),
+    /*
+      The band's own edge, per categorical slot. It is derived the way a filled node's is — the fill
+      carried 26% toward an ink — but toward the PAGE's ink rather than the label's. A band sits ON
+      the page, so that is the relationship its edge has to hold; carried toward `onAccent` it would
+      go LIGHTER than the fill on light, and a band whose edge is paler than the band reads as a
+      glow rather than a border. Both registers come out right: darker on cream, lighter on the
+      dark ground, definition either way.
+
+      Indexed 0-7 because mermaid indexes the slots and cycles the five past the fifth, exactly as
+      the pie does.
+    */
+    ...Array.from({ length: 8 }, (_, i) => {
+      const fill = SERIES[register][i % SERIES[register].length];
+      return `.task-type-${i},.section-type-${i}{stroke:${mixOklab(fill, p.fg, NODE_BORDER_MIX)};}`;
+    }),
+    /*
+      ★★ A MINDMAP LABEL SITS DIRECTLY ON A CATEGORICAL FILL, so it takes `onAccent` — the same
+      answer the journey's does, and for the same reason. It is the one family that paints its slot
+      SOLID: everywhere else the categorical is a tint, a stroke or a band this theme has repainted,
+      and there the shared `cScaleLabel` (the page ink) is correct.
+
+      MEASURED against the five as they actually land — mermaid does not darken a slot the theme
+      states, so these are the deck's own colours:
+
+          #00a447 green    dark 5.48   white 3.28
+          #da7600 orange   dark 5.62   white 3.20
+          #0084c8 blue     dark 4.39   white 4.09
+          #4f39f6 indigo   dark 2.78   white 6.46
+          #e30076 magenta  dark 3.87   white 4.64
+
+      ★★ AND THIS IS THE CASE THE cScaleLabel NOTE PREDICTED. It said one ink for twelve slots was
+      right for the deck's five and "would need revisiting if the categorical ever gained a genuinely
+      dark member — there the pairing would flip back". Indigo is that member: at 2.78 the page ink
+      is under the 3:1 floor a 36px label is held to, and it was the audit on this slide that caught
+      it. White is over the floor on every one of the five, so the family takes one ink rather than
+      a per-slot mixture that would put two colours of label in one picture.
+
+      ⚠ SCOPED TO `.mindmap-node`, because `.section-N` is shared with kanban — whose columns this
+      theme paints the surface, where white would be invisible. Twelve, matching the slots: a mindmap
+      has as many sections as the author writes branches.
+    */
+    /* ★ THE ROOT IS `section--1`, NOT A SLOT — mermaid indexes the branches from 0 and gives the
+       node they hang off minus one. Left out, it was the one dark label in a picture of white ones,
+       which is the mixture this rule exists to avoid; it draws on the same green the journey and the
+       timeline already put white on. */
+    ...['-1', ...Array.from({ length: 12 }, (_, i) => String(i))].map((slot) => (
+      `.mindmap-node.section-${slot} text,.mindmap-node.section-${slot} span{fill:${p.onAccent};color:${p.onAccent};}`
+    )),
+  ];
+}
+
+/**
+ * The full mermaid config, ready for `mermaid.initialize()`.
+ *
+ * `theme: 'base'` is not a default — it is the ONLY theme that reads `themeVariables` at all.
+ * 'default', 'dark', 'neutral' and 'forest' (mermaid's own, unrelated to this brand) each ship a
+ * fixed palette and ignore the table above entirely, so naming any of them silently reverts every
+ * colour on this page.
+ */
+/*
+  ── WHY THE SPACING IS MERMAID'S OWN ───────────────────────────────────────────────────────────
+
+  `fitToColumn` does not refuse a diagram that outgrows its slide, it SHRINKS it, so a unit of gap
+  is paid for twice: once in width, and again in the type it costs when the drawing is scaled to
+  fit. That makes tightening the gaps look like free legibility. MEASURED on the specimen's
+  flowchart in an 872px column:
+
+    20/60/70   mermaid's own, shipped   natural 1603 units   shrink 0.544   labels at 19.6px
+    16/44/52   a third off              natural 1459 units   shrink 0.598   labels at 21.5px
+    10/24/28   packed                   natural 1255 units   shrink 0.695   labels at 25.0px
+
+  ★★ AND THE DECK SHIPS THE TOP ROW ANYWAY. The gain is real and it is not what a diagram is for:
+  packed nodes read as a denser object than the Card grid with the same content beside them, and a
+  deck whose diagrams are tuned for maximum ink stops looking like one deck. A diagram that will not
+  fit at mermaid's own spacing is a diagram that wants to be two slides.
+
+  ★ THE TYPE IS NOT THE LEVER EITHER, which is the trap under all of this. Dropping fontSize 36 to
+  30 measured 18.0px rendered — WORSE than leaving it alone. mermaid lays a box out around the text
+  it measures, but the gaps between boxes are config numbers that do not follow the font, so the cut
+  bought 9.4% of width for 16.7% of type.
+
+  ⚠ The fragment tab keys below are TYPE, not spacing. `labelBoxWidth`, `labelBoxHeight` and
+  `boxTextMargin` are scaled to the deck's rung because mermaid never measures the keyword against
+  the box it draws for it.
+*/
+
+export function mermaidConfig(register: Register) {
+  return {
+    startOnLoad: false,
+    theme: 'base' as const,
+    themeVariables: mermaidThemeVariables(register),
+    fontFamily: MERMAID_FONT_FAMILY,
+    /*
+      ★★ TOP-LEVEL `fontSize` IS THE ONE THAT WORKS, and mermaid's own documentation points the
+      other way. `sequence.actorFontSize`, `.messageFontSize` and `.noteFontSize` are all declared
+      in mermaid 11's config schema (dist/config.type.d.ts) and all THREE are ignored by the
+      renderer. Measured against mermaid 11.17.2 in a live page, same diagram, one variable changed:
+
+          sequence: { actorFontSize: 36, … }   ->  style="… font-size: 16px …"
+          fontSize: 36                          ->  style="… font-size: 36px …"
+
+      The visible symptom was not a wrong number, it was a SMALL DIAGRAM: mermaid lays every box out
+      around the text it measures, so at 16px the whole sequence diagram came out about a third of
+      the size of the flowchart beside it, and the fit-to-column step below faithfully preserved
+      that. It reads as "mermaid just draws sequence diagrams small", which is why the per-family
+      keys are not left in place as harmless belt-and-braces — they are a false explanation sitting
+      next to the real one.
+    */
+    fontSize: MERMAID_FONT_PX,
+    /*
+      ⚠ `htmlLabels: false` DOES NOT TAKE EFFECT, measured. Read in the rendered shadow root of the
+      specimen's flowchart against mermaid 11.17.2, a node label's ancestor chain is
+      `span.nodeLabel < div < foreignObject < g.label` — an HTML label, which is what this key asks
+      mermaid not to emit. Every node carries `data-look="classic"`, i.e. mermaid 11's unified
+      renderer, which reads the label mode from its own place and not from this section.
+
+      It is left set rather than deleted because it is the documented request and costs nothing, but
+      nothing downstream may assume SVG <text>: mermaidBackgroundRules() names `span` alongside `text` for
+      exactly this reason, and any rule written for one form has to cover the other.
+    */
+    flowchart: { htmlLabels: false, curve: 'basis', padding: 20, nodeSpacing: 60, rankSpacing: 70 },
+    /*
+      Spacing only. Every FONT key this section accepts is dead (see `fontSize` above), so listing
+      one here would be decoration that reads like configuration.
+
+      ★★ THE LAST THREE ARE THE FRAGMENT TAB, AND THEY ARE NOT OPTIONAL AT THIS TYPE SIZE. An
+      `alt`/`opt`/`loop` fragment hangs its keyword in a tab mermaid draws at a FIXED
+      `labelBoxWidth` x `labelBoxHeight` — 50x20 by default, with 5px of text margin, all sized for
+      its own 16px type. The deck runs at 36, and mermaid never measures the word against the box:
+      it draws a 50-wide tab and then paints a word wider than it. MEASURED in the exported PDF
+      before this: "opt" broke three of the tab's four edges, the descender falling 6px clear of the
+      bottom. Same failure class the gantt block below exists for, and the fix is the same — scale
+      the box with the type rather than reach for a stylesheet, which would only make the text in a
+      box drawn for smaller text larger still.
+    */
+    sequence: {
+      useMaxWidth: true,
+      diagramMarginX: 40,
+      diagramMarginY: 20,
+      boxMargin: 20,
+      actorMargin: 80,
+      labelBoxWidth: toTagScale(50),
+      labelBoxHeight: toTagScale(20),
+      boxTextMargin: toTagScale(5),
+      /*
+        ★★ AN `actor` LABEL IS DRAWN BELOW THE BAND THE LAYOUT RESERVES FOR IT. drawActorTypeActor
+        centres the name at actorY + 35 + figureBBox/2 = actorY + 67.5, while the bounds only ever
+        advance by the stick figure's own 65 — so the room under the last row is diagramMarginY +
+        bottomMarginAdj = 21. mermaid's own 14px label needs 8.5 of it; the deck's 36px needs 22.54,
+        and "Rider" fell through the floor of the viewBox (2px cut, 9% hidden). 6 buys 5 units back.
+        `sequence.height` is NOT the lever — an actor's label y comes from the figure bbox — and
+        `diagramMarginY` is worse, because viewBox y is -diagramMarginY, so raising it pads the TOP
+        by the same amount. Applied only when mirrorActors is set, which is the default and the only
+        case with a bottom row at all.
+      */
+      bottomMarginAdj: 6,
+    },
+    /*
+      ★★ THE GANTT KEYS ARE LIVE, WHICH IS THE OPPOSITE OF `sequence` ABOVE — so they are set here
+      rather than left to the top-level `fontSize`, which this family ignores. Measured, same
+      diagram, one key changed: task and section text went 11px -> 36px with `gantt.fontSize`, and
+      the bars re-laid out around it. That is the whole reason to reach for a per-family key: it
+      moves the LAYOUT, where a stylesheet rule would only enlarge text inside boxes drawn for a
+      smaller one.
+
+      `barHeight` and the paddings follow the type rather than being picked: a 36px label needs a
+      bar it fits inside, and the two left paddings are what stop a section title and an outside
+      task label from colliding at that size.
+
+      ⚠ TWO SIZES THIS SECTION CANNOT REACH — the chart title (18px) and the axis ticks (10px).
+      Neither has a config key, and both are pure text with no box laid out around them, so
+      ROOM_SCALE_RULES takes them instead. See the gantt rules there.
+    */
+    gantt: {
+      useMaxWidth: true,
+      fontSize: MERMAID_FONT_PX,
+      sectionFontSize: MERMAID_FONT_PX,
+      barHeight: 56,
+      barGap: 14,
+      topPadding: 60,
+      leftPadding: 220,
+      gridLineStartPadding: 40,
+      titleTopMargin: 40,
+    },
+    /*
+      ★ THE QUADRANT'S SIZES ARE ALL KEYS, unlike the gantt's title and ticks — every piece of text
+      on this chart has one, so none of it is left to a stylesheet. The point labels take the 0.8
+      step a caption takes; everything else is the body-sm rung the rest of the deck sets at.
+    */
+    quadrantChart: {
+      useMaxWidth: true,
+      chartWidth: 900,
+      chartHeight: 600,
+      titleFontSize: MERMAID_FONT_PX,
+      quadrantLabelFontSize: MERMAID_FONT_PX,
+      xAxisLabelFontSize: Math.round(MERMAID_FONT_PX * 0.8),
+      yAxisLabelFontSize: Math.round(MERMAID_FONT_PX * 0.8),
+      pointLabelFontSize: Math.round(MERMAID_FONT_PX * 0.8),
+      pointRadius: QUADRANT_POINT_RADIUS,
+      /*
+        ★★ THE LABEL'S GAP IS MEASURED FROM THE POINT'S CENTRE, NOT ITS EDGE, so a padding smaller
+        than the radius puts the word INSIDE the dot. mermaid ships `pointRadius: 5` beside
+        `pointTextPadding: 5` — equal, which is what keeps its own default just clear. This theme
+        raised the radius to ${QUADRANT_POINT_RADIUS} and left the padding at mermaid's 5, so the
+        label's hanging baseline landed 7px inside the dot and "Lambeth" sat across it.
+
+        Derived from the radius so the two cannot drift apart again, plus a quarter of the label's
+        own rung as the gap — the type is ${Math.round(MERMAID_FONT_PX * 0.8)}px here against the 16px
+        mermaid's 5 was drawn for, so a fixed number would be too tight the moment the deck's scale moved.
+      */
+      pointTextPadding: QUADRANT_POINT_RADIUS + Math.round(MERMAID_FONT_PX * 0.25),
+      quadrantPadding: 12,
+    },
+    /*
+      ★★ THE JOURNEY'S BOX IS THE CONFIG, NOT THE TYPE. `taskFontSize` is live — `byTspan` sets it
+      straight onto the text — but on its own it makes things worse, because the label is drawn into
+      a foreignObject of a FIXED `width` x `height` (150 x 50 by default). Raise the type without
+      raising the box and every label wraps and then clips at the box's own edge, which is what a
+      first pass at this family looks like: truncated words in boxes that look deliberate.
+
+      So the box is stated with the type it has to hold. Everything else here is the air around it.
+    */
+    journey: {
+      useMaxWidth: true,
+      taskFontSize: MERMAID_FONT_PX,
+      taskFontFamily: MERMAID_FONT_FAMILY,
+      width: 340,
+      height: 112,
+      boxMargin: 16,
+      boxTextMargin: 12,
+      taskMargin: 64,
+      leftMargin: 200,
+      diagramMarginX: 40,
+      diagramMarginY: 24,
+    },
+    er: { useMaxWidth: true },
+    state: { useMaxWidth: true, nodeSpacing: 60, rankSpacing: 70 },
+    /*
+      ⚠ THE COMMIT LABEL STAYS ROTATED, AND THAT IS mermaid's COLLISION AVOIDANCE rather than a
+      style. It tilts every commit id 45° so long ids can sit close together, and the spacing between
+      commits is laid out on the assumption that they do. Set straight — tried, and measured — the
+      ids at this deck's rung overlapped each other outright: `bay picker` and `battery check` ran
+      into one word. The layout is computed from mermaid's own 10px and does not re-run when the
+      theme re-points the size in CSS, which is the same seam the ER edge label and the sequence
+      fragment tab each sit on.
+
+      So the size moves and the angle does not.
+    */
+    /*
+      ── RADAR ──────────────────────────────────────────────────────────────────────────────────
+      ★★ THE MARGINS ARE NOT DECORATION HERE, THEY ARE THE ONLY ROOM THE LABELS HAVE. Radar's plot
+      box is fixed at `width` x `height` and everything outside it — the axis names and the legend —
+      is placed against the MARGIN rather than measured. mermaid's 50 was sized for its own ~12px
+      label; at the deck's 29px rung a five-letter axis name is more than twice as long, and the
+      legend's text starts at three quarters of the way into the right margin, so each unit of
+      `marginRight` buys the legend only a quarter unit of clear room. 170 is what the longest axis
+      name needs beside a plot of 600, and the left margin matches it so the plot stays centred.
+
+      ★ THE TOP AND BOTTOM ARE SMALLER ON PURPOSE, not by oversight. Nothing sits in them but the
+      diagram title, which this deck never draws — the heading above the frame is the title. A
+      margin is dead space inside the viewBox, fitToColumn caps against that viewBox, and every
+      unit of unused gutter is therefore drawn at the cost of the picture.
+
+      ★ `axisLabelFactor` rises with the label, for the reason stated beside `axisLabelFontSize`.
+    */
+    radar: {
+      useMaxWidth: true,
+      width: 600,
+      height: 600,
+      marginTop: 90,
+      marginRight: 170,
+      marginBottom: 90,
+      marginLeft: 170,
+      /*
+        ★★ THE SPOKE STOPS ON THE RING, NOT AT THE RADIUS — and those are not the same place once
+        the graticule is a polygon. mermaid fillets every vertex with a quadratic whose CONTROL is
+        the true corner, so the ring never reaches it: the curve's midpoint is (P0 + 2C + P2) / 4,
+        which on the outer ring puts the line at 297.06 against a nominal 300. An axis drawn to the
+        full radius therefore overshoots the ring it should meet by about 3 units, plus half its own
+        stroke — measured on the render, and visible as a spur past every corner.
+
+        297.06 / 300 is 0.9902. 0.99 lands the spoke six hundredths of a unit inside the ring, which
+        is closed. ★ The sagitta is a FIXED chord in user units, not a fraction of the radius (the
+        inner rings fillet by the same 8.09 either side), so this factor is right for the outermost
+        ring specifically — which is the only one an axis line has to meet.
+      */
+      axisScaleFactor: 0.99,
+      axisLabelFactor: 1.14,
+      /*
+        ⚠ NO `curveTension` HERE, DELIBERATELY. It is the control-point tension for the cubic mermaid
+        draws through the data points — and it is consulted ONLY on the circular graticule. This deck
+        draws the polygon one, where the curve is a straight-sided <polygon> and the key is never read.
+        Setting it would be a number that looks like configuration and configures nothing, which is the
+        shape of every dead key this file already records.
+      */
+    },
+    /*
+      ── TREEMAP ────────────────────────────────────────────────────────────────────────────────
+      ★★ THE LEAF TYPE LADDER IS CHOSEN BY LEAF COUNT, NOT BY CONFIG: 38px at twenty leaves or
+      fewer, 16px past that, then shrunk in a loop that MEASURES the fitted text and stops when it
+      fits. So the deck states no size here at all. `!important` would win the declaration and lose
+      the diagram — the shrink loop measures at mermaid's size, and a label forced larger than the
+      cell it was fitted to is culled outright by the family's own `display:none` guard.
+
+      38 against the deck's 36 rung is a coincidence worth naming rather than relying on: it holds
+      only while a treemap here stays under twenty leaves, which is also the point at which the
+      picture stops being readable from the back of a room.
+
+      The box is fixed at `nodeWidth × 10` by `nodeHeight × 10` before any data is read, so these
+      two are an ASPECT RATIO rather than a size — fitToColumn does the sizing.
+    */
+    treemap: { useMaxWidth: true, nodeWidth: 100, nodeHeight: 44 },
+    /*
+      ── MINDMAP ────────────────────────────────────────────────────────────────────────────────
+      ⚠ `padding` IS THE ONLY KEY THAT REACHES THE BOX, and it does not reach it evenly: a default
+      node is laid out at eight half-paddings wide and TWO high, a 4:1 ratio fixed in code. At the
+      deck's 36px rung mermaid's 10 leaves five units above and below the cap height, which is far
+      too tight, so this is raised to what the vertical half needs and the horizontal is simply
+      wider than it would otherwise be.
+    */
+    mindmap: { useMaxWidth: true, padding: 28 },
+    /*
+      ── KANBAN ─────────────────────────────────────────────────────────────────────────────────
+      `ticketBaseUrl` is deliberately unset: a ticket id renders as plain text rather than a link,
+      because a deck is not a place anyone can click.
+    */
+    kanban: { useMaxWidth: true, padding: 20, sectionWidth: 400 },
+    gitGraph: { rotateCommitLabel: true },
+    pie: { useMaxWidth: true },
+  };
+}