Explainer Diagrams

Explainer diagrams

A diagram in this grammar is a scene: shapes, positions, and arrows that carry the meaning, with few words. The first attempt at this usually comes out as a table in nice colors. The verdict that produced this skill was "they're not visual, they look boring." Read examples/severance-week/ before your first diagram: index.html is the source of seven diagrams and out/ holds the PNGs they produced. That is the reference implementation.

The grammar

Type: Pixelify Sans (Google Fonts) for the title and the callout heading only; system mono for everything else; system sans bold only for card labels and node names. Cards are white, 1px stroke, border-radius: 3px. Arrows use a 6×6 triangle <marker>, one per diagram with a unique id.

Components (all in template.html): .shot (1100px white sheet, 40px padding; the PNG is this element) → .shot-head (blue mono index 01, Pixelify <h2>, one-line mono <p>) → .scene (1020px, #fbfbfb, 1px border; the picture) → optional .stat-row of .stat-tile (big blue mono number over a gray label) → optional .callout (blue left border, Pixelify one-liner + one mono sentence) → optional .footnote (11px mono caveat). Card variants: .tint-orange, .tint-blue, .solid, .dashed, .gray; inside a card: .tag (mono caps), .label (sans bold), .sub (mono body). components.md has copy-paste snippets for every piece.

Scene, not table

• One idea per diagram. The title says it, the scene shows it, the callout says what it means in one line. If it needs a paragraph, it is two diagrams.
• Shapes carry the meaning: a line that thickens day by day, a path that stops short of a box with an ×, a hollow node beside solid ones, a strike-through on the canned line, a bar split into scored segments. The reader should get it before reading a word.
• Words are receipts, not prose: quotes ≤ 14 words with an ellipsis, never reworded; ids and times in mono beside them; ≤ ~10 text objects per scene.
• Nothing smaller than 13px at the 1020px scene. Most newsletter and forum layouts show the PNG at ~700px wide. Stat numbers 24px, titles 27px.
• Every number and quote comes from a source file, verbatim. A caption or a callout is a factual claim; check it against the source before shooting.
• Footnotes carry method caveats. Never reference an unpublished URL or "see 01–06 above" inside a PNG that will travel on its own.

Scene catalogue (proven shapes)

New shapes are welcome inside the grammar above.

Workflow

1. Content sheet first. For each diagram: title, one-line subtitle, the ≤ 10 text objects with their source ids, the callout line, and the shape from the catalogue. If the diagrams are for something the user publishes, get their approval on the wording here; wording is taste, layout is plumbing.
2. Build in a copy of template.html: one <div id="shotN" class="shot"> per diagram. HTML cards for anything with text (native wrapping); SVG only for connectors, circles, bars, and baselines. Cards over SVG, never SVG <text> for sentences.
3. Shoot with shoot.mjs and a plan modeled on plan.example.json: viewport 1300×1000, deviceScaleFactor: 2, wait for document.fonts.status === 'loaded' and assert document.fonts.check('1em "Pixelify Sans"') before the first shot, one {type:"shot", selector:"#shotN", path} per diagram, absolute paths.
4. Look at every PNG (open it, or read it with a vision-capable tool). ok:true from the harness is not a pass. Run the checklist below, fix, re-shoot only the changed diagrams.
5. Show the PNGs, not the HTML. Expect one round on wording and one on a missing arrow; both are normal.

If you delegate, steps 2–4 are mechanical enough for a cheaper model given this file and the example; step 1 and the final look are not.

Commands

SK=~/.claude/skills/explainer-diagrams
mkdir -p ./diagrams && cp $SK/template.html ./diagrams/index.html
# edit index.html; write ./diagrams/plan.json from $SK/plan.example.json (absolute paths)
node $SK/shoot.mjs ./diagrams/plan.json     # one JSON line per eval step + a final {ok}

Requirements: Node 18+, puppeteer (npm i puppeteer anywhere the loader can find it: local node_modules, PUPPETEER_PATH, or the global npm root), and network access to Google Fonts for Pixelify Sans. If the plan's fonts.check eval returns false, the shot is in a fallback font and must be redone.

QA checklist (every PNG, by eye)

• Pixel font rendered in the title (blocky), not a fallback sans.
• Every arrow has a visible head. Heads vanish when a path ends inside its target box (the box fill paints over the marker): end paths at the box edge.
• No label crosses an arrow; no text touches a circle stroke; nothing is clipped at the scene edge; no column leaves a large void.
• Text ≥ 13px-equivalent; quotes ≤ 14 words; ids present where quotes are.
• Callout and captions match the source facts.
• The scene reads at a glance with the words covered.

Gotchas

• Adding text under rows grows row heights and moves anchored arrows; re-view after any content change.
• A return edge from "nowhere" reads as decoration; anchor both ends to elements.
• A label sitting on a dashed path reads as strike-through; stack the path (SVG) and the label (HTML) in normal flow instead.
• Marker ids collide across diagrams on one page; prefix them (d3-m1).
• The first row of a ladder needs its antecedent ("Theo's last call", not "His last call"): the PNG travels without the paragraph.

Files

template.html (shared CSS + two starter diagrams that render as-is) · components.md (snippets for every component and connector) · shoot.mjs (the screenshot harness) · plan.example.json (the plan shape) · examples/severance-week/ (seven finished diagrams: source, plan, PNGs).