Interactive Explainer

---
name: interactive-explainer
description: Build single-file interactive HTML explainers/explorers that visually explain systems — cycles, workflows, pipelines, dependency graphs, state machines, architectures, timelines. Use when asked for an "interactive explainer", "HTML explorer", "explain this visually", "make an interactive diagram of how X works", or when a markdown explanation of structure (who calls what, what depends on what, what loops back) is getting long. Produces a self-contained, offline-safe .html with focus+context highlighting, step-through narration, and copy that passes the copy rules.
---

# Interactive Explainer

Turn "how does X work?" into a single HTML file the reader can *explore*: click a node to see what feeds it and what it feeds, step through the story, read details on demand. The picture carries the structure; the words carry only what the picture can't.

## When to use — and when not

| Situation | Verdict |
|---|---|
| Cycles, workflows, dependencies, state machines, lifecycles, request paths | **Yes** — this is the target case |
| A concept with real structure that markdown flattens into "and then… and then…" | **Yes** |
| Live data, dashboards, real metrics | **No** — that's an app; use the project's data/dashboard tooling |
| A list, a comparison table, three bullet points | **No** — markdown wins; don't build a page to say what a sentence says |

## The contract

1. **One self-contained `.html` file.** No build step, no CDN, no external requests. It must open from disk, offline, forever. (Embed a font via `@font-face` data-URI only if the file budget allows; otherwise pick a deliberate local stack and let weight/size/spacing do the typographic work.)
2. **Data-driven.** Nodes, edges, and steps live in one JS object at the top of the file. The rendering reads the data; nobody should ever edit SVG coordinates to fix a typo.
3. **The picture carries structure; words carry mechanism.** If the text restates what an arrow already shows, cut the text.
4. **Overview first, zoom and filter, details on demand.** The first screen is the whole shape, legible — with the interaction model *demonstrated*, never a blank slate a prose hint has to explain. Open on a worked example (a pre-lit focus via `opening:` or an active step 0) so the first screen shows what clicking does. The legend may not name a state the reader hasn't seen. Detail appears when asked — click, hover, step — never as a wall of prose beside the diagram.
5. **Accessible or unshipped.** Keyboard operable (Tab/Enter on nodes, ←/→ steps, Esc reset), `prefers-reduced-motion` honored, AA contrast, meaning never encoded in color alone, readable at 375px.
6. **A deliberate aesthetic.** Commit to a direction (editorial, technical-manual, blueprint, terminal…) with a dominant color and one sharp accent. No default-looking gradient-card slop.
7. **SVG, not canvas.** Crisp, inspectable, DOM events, screen-reader reachable. Canvas only past ~300 nodes — and past ~30 unclustered nodes you should be collapsing groups anyway.

## Workflow

### 1. Frame
Name **the one question the explainer answers** (it becomes the subtitle). Name the reader. If you can't state the question in one line, the scope is wrong — split it.

### 2. Pick the shape
| The content is… | Shape | Signature interaction |
|---|---|---|
| Steps with a direction, one actor | Workflow / pipeline | Step-through narration |
| Steps across actors/systems | Swimlanes | Step-through + lane highlight |
| A loop (lifecycle, feedback, retry) | Cycle ring | Token walking the loop |
| "What needs what" (imports, services, builds) | Dependency DAG | Two-color ancestry: click → upstream vs downstream |
| Modes and transitions | State machine | Simulate: fire events, watch state move |
| Containment / levels | Layered stack | Click layer to expand |
| Ordered events, causality over time | Timeline / sequence | Scrub / step |

Mixed shapes are normal — a workflow with a feedback loop is a flow plus a marked back-edge, not two diagrams. Full recipes and traps: [references/visual-grammar.md](references/visual-grammar.md).

### 3. Model the data
**Research before modeling — accuracy is the product.** Pull exact names, numbers, commands, and flows from the sources (fan out exploration subagents that return verbatim values, not summaries) into a digest first. One false claim discredits the whole page; if a fact can't be verified, say so rather than dress it up.

Write the `EXPLAINER` object first — nodes (id, label, group, detail), edges (from, to, kind), steps (title, body, focus). If the data model is muddy, the diagram will be too. Get the model reviewed against the source of truth (code, spec) before styling anything.

### 4. Build from the starter
Copy [assets/starter.html](assets/starter.html) and replace the data. It already has: layered DAG layout with cycle-aware back-edges, click-to-focus with upstream/downstream ancestry highlighting, a step-through narrator, detail panel, legend, keyboard map, reduced-motion handling, and a themable token block. Restyle the tokens to the chosen aesthetic; don't re-derive the machinery. Interaction and motion recipes beyond the starter: [references/interaction-and-motion.md](references/interaction-and-motion.md).

### 5. Copy pass — Sandy's bar
Every visible string obeys [references/copy-rules.md](references/copy-rules.md): title ≤ 8 words, node labels ≤ 3, details ≤ 3 sentences of mechanism, banned-word list enforced, cut lines moved to the graveyard comment. **If the `sandy` agent is installed, hand her the draft copy for the pass; the rules file is the fallback when she isn't.**

### 6. Quality gate
Open the file in a browser (use the `webapp-testing` or `chrome-devtools` skill if available). **If the `gary` agent is installed, hand him the artifact for a first-contact audit — his cold-open/walkthrough/severity method is this gate, run properly.** Verify:

- [ ] Cold open, ten seconds, no reading: it's evident that nodes are clickable and a tour exists
- [ ] The opening state demonstrates focus and the legend colors — a worked example, not a hint
- [ ] Clicking a node mid-tour pauses the tour — position preserved, resume offered
- [ ] The whole shape is legible on the first screen — no scroll to understand
- [ ] Click any node → upstream/downstream highlight correct (spot-check against the data)
- [ ] Step-through: ←/→ work, every step's focus matches its text
- [ ] Esc resets; Tab reaches every node; Enter activates
- [ ] OS reduced-motion set → nothing moves
- [ ] 375px wide → panel stacks, nothing clips
- [ ] Zero console errors; zero network requests
- [ ] Every visible string passed the copy rules
- [ ] File opens from `file://` with no server

**Verify headlessly, not by eye.** Screenshots miss empty containers and silent JS halts: load the file in a headless browser, assert zero console errors *and* the expected element count per section, and cache-bust (`?v=2`, `?v=3`) between reloads — a stale copy will send you chasing a bug you already fixed.

**Traps that silently break these pages:**

- **Duplicate ids — the number-one failure.** A `<section id="x">` and an inner `<div id="x">`: `getElementById` returns the section, a render's `innerHTML = ''` wipes its static controls, a later lookup returns null and throws, and everything below dies. Unique ids everywhere (`x` for the anchor, `xGrid` for the container).
- **Lint-hostile glyphs.** Write arrows/bullets/dots as HTML entities (`&rarr;`, `&middot;`) so the raw file stays ASCII-clean for prose/slop linters while the page still renders the symbol.
- **Hidden external references.** Before calling it portable, grep for `src=`, `<link`, `@import`, `url(`, `http` — expect none beyond an inline data-URI favicon (which also prevents a 404).
- **Making-of commentary.** No "about this page" box, provenance lines, or source-listing footer — show the subject, not how the page was built. Remove debugging leftovers.

## Files

- [references/visual-grammar.md](references/visual-grammar.md) — layout recipes per shape, and their traps
- [references/interaction-and-motion.md](references/interaction-and-motion.md) — focus+context, steppers, motion, a11y
- [references/copy-rules.md](references/copy-rules.md) — the clarity bar for every visible string
- [assets/starter.html](assets/starter.html) — working scaffold; copy it, replace the data, restyle the tokens