--- name: glance-explainer description: Use when asked for a "glance explainer" or an "html explainer", a visual explainer, a page that explains something "in simple plain english", "with lots of visuals and diagrams", or "for someone with ADHD / short working memory"; also when a spec, decision, status update, architecture, or release needs to be understood and approved by a reader who cannot hold a long document in their head. license: MIT argument-hint: "[topic or file to explain]" --- # Glance explainer A single-file HTML page that lets a reader with a short working memory understand one thing and, if needed, decide. Colour has meaning and nothing moves on its own. Paths are relative to this file. ## What you produce One `.html` file from `assets/template.html`, in this order: 1. **Answer bar**: the whole page in one sentence. It is the page's headline. 2. **Keep box**: at most three facts to carry, shown as three cards side by side. 3. **At a glance**: the type's own picture, on the first screen, with its take line. A roadmap, playbook or field guide has none, because its lanes, phase strip or territory already open the page. 4. **Chapter map**: 3 to 7 chapters, one line each. 5. **Chapters**: one idea each. Each opens by restating the fact it builds on, has a visual component, puts machinery in a fold, and closes with one remember line. 6. **Recap**: the remember lines. 7. **The ask**, only when a decision is needed: one question, 2 to 4 choices, the recommendation marked, and what happens if the reader does nothing. ## Page identity and conventions - Start with ``. `lang` is `en` or `ja`. `data-type` is `explainer` (default), `decision`, `status`, `spec`, `release`, `research`, `handover`, `portfolio`, `public`, `teach`, `incident`, `pr`, `runbook`, `compare`, `roadmap`, `tour`, `playbook` or `field-guide`, each defined in `references/types.md`. A playbook may run to 10 chapters. - Pages that collect answers (`gather`) or map a system (`atlas`) add rules. Also read `../explainer-gather/SKILL.md` or `../explainer-atlas/SKILL.md`. - Chapter kicker: "Chapter 2 of 6, about 1 minute" (200 words a minute, rounded up). Japanese: "第2章 / 全6章、約1分" (500 characters a minute). - Headings ask the question the chapter answers: "What changes for you?", not "Impact". - The default state of any interactive element already makes the point: the first step and the first tab carry it. Readers skip clicks. ## Process 1. **Write the answer line first**, then the three keep facts. Then pick the glance picture from the type's entry in `references/types.md`, and last the chapter headings. If any will not come, reread the source. 2. **Pick each chapter's visual from the relationship it holds** (sequence, branch, before and after, time, choice, health, parts) using `references/diagrams.md`. Prefer CSS components; draw an SVG only for branches or nesting. 3. **Copy the template, fill it, delete what you do not need.** Keep the tokens, base CSS and script. `references/design-system.md` explains the components; `assets/gallery.html` shows them. 4. **Write the prose last** under `references/writing.md`: paragraphs under forty words, one idea per sentence. 5. **Check:** `node scripts/check.mjs `. Fix every FAIL. 6. **Deliver:** save as `docs/explainers/YYYY-MM-DD-.html` in a repo, open it once in a browser, reply with the answer line and the link. ## Quick reference - Know the point: `p.answer` - Carry facts: `div.keep`, `p.from`, `p.remember`, `section.recap` - Open on the type's own picture: `section.glance` (after `div.keep`, not a chapter) with `div.glance-head`, the picture and a `p.take` - Put two pictures or three lists side by side: `div.duo`, `div.cols` (columns `.go .wait .here .decide .stop`) - Rank findings by trust: `ul.findings`, each `li` with `data-strength` of strong, moderate or weak - Teach in layers, easiest first: `ol.layers` with one `li.here` - Pictures the script draws from the page: an empty `div.runbook-overview`, `div.filmstrip`, `div.rulings` or `div.qprogress`. Each needs its source (`ol.runbook`, `ol.tour`, `.decision`, `.answer-field[data-q]`) or the checker fails - See a sequence: `ol.flow`, or SVG in `figure.figure` for branches - Compare two states: `div.split` - Choose: `div.decision`, then `section.ask`, or a `fieldset.answer-field` after each card and one `.collect` bar - Know where things stand: `ul.status`, `ol.timeline` with one `li.here` - Act: `ol.steps` - Verify or dig: `details.fold` - See change over time in one picture: `figure.stepper` - See several views of one thing: `div.views` - See where this chapter sits in the whole: `figure.minimap` - Compare options on the same criteria: `table.grid` in `div.grid-wrap` - Plan now, next and later, with dependencies: `.lanes` with three `.lane`, each with a `p.lane-note`, and `p.asof` under the answer bar - Follow a procedure with a check and a way out at each step: `ol.runbook` with `pre.cmd` - Walk through a product on its real screens: `ol.tour` with `figure.shot` and `span.pin` - Promise a customer something, with proof kept out of sight: `ul.promises` with `data-evidence` - Look things up in a reference, after one orientation read: `.territory` of `.stage` with `a.family` tiles (the script derives counts and bars), `ol.start-here`, and `.index` of `details.family-index` with `.entry` rows. A field guide has three chapters and no ask - Plan a risky change for one decision-maker: `ol.phase-strip` and `ol.phases` (each phase with a `p.impact`), `figure.frame` for what the audience sees, `div.roles` with `ul.rules`, `div.undo`, `div.risks` of `article.risk` ## Common mistakes - **The answer at the end.** It belongs right after the title. - **"As we saw above."** The reader scrolled. Restate it in `p.from`. - **Colour as decoration.** Six meaning colours, one meaning each, never colour alone. - **A diagram that repeats the paragraph.** Delete the paragraph, write the take-away caption. - **A picture with no take line.** A status board or a split proves something too: say what in a `p.take` straight under it. The glance needs one too. - **A chapter that repeats the glance.** The chapter that explains the glance picture builds on it. It adds the why, not the picture again. - **Editing an old page as it is.** Before you change an existing page, read its ``. If it is older than this plugin or missing, offer to run `scripts/upgrade.mjs` on the page first (`--dry-run` shows what changes). - **A diagram drawn only for a wide screen.** Keep the template's figure CSS so it scrolls on a phone, or add an `svg.narrow` twin. The checker fails labels under 9 px on a phone.