Explainers

Build a standalone interactive page that teaches one concept by letting the reader play with it. Everything Igor calls an explainer follows the same shape — a single repo, a live URL, a research-doc beside a visualization, GitHub Pages or Surge for hosting.

Announce at start: "I'm using the explainers skill to build a new interactive explainer for <topic>."

When to use

• •"Build an explainer for X" / "make a page that demonstrates Y"
• •"Help me understand Z interactively" when the answer will be a live page
• •Simon Willison's interactive explanations pattern applied to a specific topic
• •Right after Claude generates something complex and it's clear the explanation should be an artifact, not a chat reply

The five archetypes

Each of the existing explainer repos is the reference implementation for one archetype. Read the reference repo live when building a new instance — do not extract templates from them (N=1 each; see the Wait-for-N=2 rule in ../../CLAUDE.md).

A sixth non-archetype — research-dense — uses plain HTML to present reproducible demos of something technical. dolt-explainer is the reference: prose + diagrams + embedded shell transcripts + scripts/ directory for self-serve replay. When in doubt, start here.

Two tiers of scaffolding

1. •

   Tier 1 — plain HTML (default). One index.html with inline CSS + inline JS (or no JS). No npm, no build step. GitHub Pages legacy mode serves from main branch root. .nojekyll keeps Pages from running Jekyll. Reference: dolt-explainer, larry-voice-samples. Template in templates/plain-html/.

2. •

   Tier 2 — Vite + TypeScript + React (upgrade path). Use ONLY when the interaction genuinely exceeds what ~50 lines of vanilla JS can hold: animation with a scrubber, D3 layouts, Canvas procedural art. Reference: monitor-explainer, religion-evolution-explorer, activation-energy-game. No template shipped here — read the reference repos when graduating.

The shape of an explainer repo (regardless of tier)

<name>-explainer/
  README.md              pointer to live URL + prereqs
  index.html             (Tier 1) OR src/ + package.json (Tier 2)
  docs/research/         the research notes that preceded the visualization
    findings.md          what you learned before you built
    mental-model.md      one-page cheat sheet for someone who knows a related concept
  scripts/               reproducible scenarios if the topic has runnable demos
  diagrams/              *.puml source + *.svg rendered output
  .github/workflows/     only if Tier 2 or using Surge; Tier 1 + legacy Pages needs none
  justfile               serve, build-diagrams, deploy-check, open-live
  .nojekyll              (Tier 1 only — disables Pages' Jekyll pass)
  .gitignore             runs/, _*, anything per-run

Workflow

See methodology.md for the full set of principles. High-level checklist:

1. •Research first. Do the scenarios, run the commands, read the docs, take notes. The explainer is the artifact that falls out of understanding — you cannot fake this step.
2. •Write docs/research/ before touching index.html. This becomes the source of the final prose and also a standalone artifact for readers who want depth.
3. •Pick the archetype by comparing against the reference repos. Most topics map to research-dense (dolt-explainer shape) on first pass.
4. •Scaffold Tier 1 by copying templates/plain-html/ and swapping the placeholders. Do not start Tier 2 without a concrete reason.
5. •Ship diagrams from day one. Every explainer includes at minimum one PlantUML diagram. Sometimes they're rendered to SVG and embedded; sometimes they animate or interact. Use just build-diagrams to regenerate.
6. •Embed scenarios if the topic has them. Pre-render transcripts into transcripts/*.txt and fetch them from index.html so the page stays small and the transcripts stay authoritative.
7. •Deploy to GitHub Pages (legacy, main branch root). Verify the live URL renders and every linked asset fetches.
8. •Link from the blog. Add a row to _d/explainers.md and _d/pet-projects.md.

Principles (one-liners; full reasoning in methodology.md)

• •Research first. The explainer grows out of the notes.
• •Pictures ≥ prose. Every argument at the top of the page has a diagram next to it.
• •Plain HTML unless proven otherwise. Ship something static before reaching for a build step.
• •One page, one URL, one repo. No npm unless you need it.
• •Scenarios are runnable. If you can't ./run-all.sh the demos, the explainer isn't self-sufficient.
• •Shared footer. Every explainer ends with a footer linking back to the source repo, this skill, and idvork.in/explainers. Baked into templates/plain-html/index.html — swap OWNER/REPO per project.
• •Respect N=2. Four archetype reference repos ≠ four sub-templates. Read the reference live; do not extract a framework.

Do not

• •Build a templating engine or framework layer above the scaffold. Copy, edit, ship. (Wait-for-N=2.)
• •Skip the research doc. An explainer without docs/research/ is a demo; they're not the same thing.
• •Assume Vite/React. Always check whether plain HTML suffices first.
• •Use Surge.sh by default. GitHub Pages legacy is simpler (zero secrets, zero workflow) and matches the plain-HTML default.

Pointers

• •methodology.md — principles and archetype details
• •templates/plain-html/ — the minimum starter
• •Reference repos: linked in the archetype table above
• •Blog context: Explainers: Interactive Understanding