The visual system behind every explainer, shown with itself
An explainer is a page you can skim in a minute and still get the point: the answer comes first, colour has one meaning, every chapter has a picture, and the page remembers so you do not have to.
Take: the picture comes before the chapters, so the first screen already says what kind of page this is.
Chapter 1 of 7, about 2 minutes
Before this: the answer at the top said the page remembers things so you do not have to. This chapter shows how.
Reading a long document means holding earlier facts while you take in new ones. With a short working memory, the earlier facts fall out as you scroll. Then you scroll back, lose your place, and give up.
An explainer breaks that loop by restating context exactly where it is needed. Four devices do this, and the ones that hold something for you are yellow, so you learn them once.
Working memory research puts the practical span at three to four items for most adults, lower under stress or with ADHD. Three is the safe number. One colour for all memory devices means one association to learn instead of four.
Remember: anything yellow is something the page is holding for you; you can stop holding it.
Chapter 2 of 7, about 2 minutes
Before this: yellow is the page holding something for you. Five more colours carry meaning the same way.
Attention goes to the brightest thing on screen. If bright colour is spent on decoration, attention is spent on nothing. So the page is calm fog and navy, and colour appears only when it says something.
Each dot also carries a symbol, so colour never works alone.
Callouts use the same three meaning colours, and only when they change what you should do next.
A tip is something that makes the next step easier. If it does not change what you do, it is not a tip and it is not on the page.
Amber marks a thing that is probably fine but has not been verified. The page says what would verify it.
Red marks a step that breaks something. It says what breaks and what to do instead.
A research page says how sure it is in words and three bars, never in a colour. Only the weak row gets a tint, because that is the one to look at.
Take from this: three findings stand firm. The weak one, storage cost, is the one the choice turns on.
Remember: if a colour shows up, it is telling you something; if nothing is coloured, nothing needs you.
Chapter 3 of 7, about 2 minutes
Before this: colour is used only for meaning. Diagrams use the same six colours, and the same rule.
A paragraph that describes a branch makes you hold both branches in your head. A diagram puts them on the screen side by side. That is the whole reason to draw one.
Most relationships do not need a drawn diagram. A sequence is a flow. Two states of one thing are a split.
A product walkthrough is the same idea with real screens. Each step is one screenshot, one numbered pin, and one line.
1The list shows every account you can open. The picked row is the one the next screen works on.
2Only the amount is yours to fill in. The destination is already chosen.
3One last look at the amount and the destination. Then you send it.
Take from this: a tour shows the real screen first, then says in one line where to look.
A tour page opens with its steps as thumbnails. The page builds the strip from the steps above, so nothing is typed twice.
Take: pick an account, type an amount, then review it. Tap a screen to jump to its step.
A plan for a risky change shows each audience what it will notice. A frame is a small browser window, or a phone, holding a plain mockup and one take-away line. A row lays out two to four of them, and stacks them on a phone.
A playbook may open with a small drawing of the outcome beside its title, and under it on a phone.
A plan for one risky change
Remember: when you see a diagram, read its caption first; the caption is the point, the drawing is the proof.
Chapter 4 of 7, about 2 minutes
Before this: purple means "you must choose". This chapter shows what a purple card contains.
A decision buried in prose costs a reread per option. A decision card puts the options side by side, marks the one the writer recommends, and says what happens if you decide nothing. You can choose in a minute.
The page must read well offline. Fonts change how it reads online.
If you do nothing: the template already loads them with a fallback. Nothing breaks.
A decision page can end in tap-to-answer fields. Each card is followed by its field, and one collect bar sits after the recap. A chip such as ⚠ Heavy pages names a cost in words.
When the decision leads to action, the actions are a ladder. Each rung is one verb and one line.
When each rung is a command, a runbook adds what a person needs at the keyboard: how to know it worked, and what to do if it did not.
node scripts/check.mjs docs/explainers/2026-10-13-checkout.htmlCheck: the first line says PASS and the exit code is 0.
If it fails: fix every line that starts with FAIL, then run the checker again.
git tag -a v1.2.0 -m "html-explainer 1.2.0"Check: git ls-remote --tags origin lists v1.2.0.
If it fails: the tag exists already; delete it locally and tag again.
claude plugin update html-explainer@html-explainer-skillCheck: the plugin list shows version 1.2.0.
If it fails: restart Claude Code and run the command again.
Take from this: every step ends in a check the reader can run, and a way out if the check fails.
A runbook opens with every step as one row, grouped by chapter. Tick a row and its step ticks too. The first step still open is marked Next.
Take: the page builds this list from the steps themselves, and remembers what you ticked.
A decision page opens with one row per card: the question, the recommended option and where it stands. The board builds itself from the cards and their answer fields. Tap an answer to watch it change.
Take: the first ruling still waiting gets the one tint. Nothing else on the board is coloured.
A phone plan can charge for the data a sync uses.
If you do nothing: sync stays on Wi-Fi only.
People ask for both. Building one well takes a week.
If you do nothing: export waits until the next planning round.
Remember: a purple card always tells you the recommended option and what happens if you ignore it.
Chapter 5 of 7, about 2 minutes
Before this: colour has one meaning. Status shapes reuse green, amber, red and cobalt and add nothing new.
"Where are we" questions have three answers: where we are in time, how each piece is doing, and the few numbers that decide what happens next. Each has its own shape.
Two more shapes answer "which one?" and "in what order?". A grid sets options against the same criteria. Lanes sort work into now, next and later, and each lane says how sure it is.
| Criterion | Plugin from GitHub | Folder link | Copy by hand |
|---|---|---|---|
| Keeping it current | |||
| Picks up updates | One command | After a git pull | Never |
| Works on a second machine | Same command | Breaks if the path differs | Copy again |
| Setting it up | |||
| Needs admin rights | No | Sometimes, on Windows | No |
| Which version you run | You pick: latest or pinned | Whatever is checked out | Whatever you copied |
Take from this: the plugin wins on three of four criteria, and the fourth is your call.
A plan, not a promise. Items move as we learn.
Next 4 weeks. Committed. Top item first.
1 to 3 months. Likely. Not in order.
3 months or more. Exploring. Not in order.
Take from this: each lane says how sure it is, each card says its state in a word, and the count on a card is worked out from the After links.
The top five are ranked and numbered. Under the cut line nothing is ranked or promised. A theme folds away and shows its count and its top idea.
Take from this: the line between ranked and unranked is drawn, and what is parked says why.
A playbook gathers these shapes into one plan for one decision-maker. Its strip shows every phase in a row. Each segment links to its phase, names the owner in a letter badge, shows how much work it is as a bar, and marks the phases the audience will notice. The grid above groups its rows with a quiet band in the same way.
Team notices: nothing.
Team notices: the new address, and one extra sign-in.
Team notices: nothing new.
Take from this: every phase says what the audience notices, and the two they notice are outlined.
Roles say who does what, and rules say what never bends. The undo box is the way back from the one risky moment. Each risk has a level, in words and a glyph, and what keeps it small.
It still holds everything. Left alone, it turns into the weak spot.
Kept small by: a reminder to switch it off after a month.
They open the old address and wonder where it went.
Kept small by: the old address forwards to the new one.
A few pages use a feature that works in its own way.
Kept small by: checking the most-read pages before and after.
Take from this: a playbook shows the risky moment with its way back, and each risk with what keeps it small.
A field guide is a reference to read once and come back to. The map places each family in a stage and shows how much of it matters now. The list says what cannot wait. The index holds every entry as one line that opens to show an example.
Take from this: the counts, the bars and the key are worked out from the entries below, so they cannot drift. The stage you are in says so.
Can wait: sync and conflicts. They matter once people use two devices.
Talking to real people to learn what they need.
In the notes app: Five short calls with students showed that finding old notes is the main pain.
The words on screen: labels, messages and tone.
In the notes app: Error messages say what happened and what to do next.
How the interface is split into parts that can be reused.
In the notes app: The editor, the note list and the sidebar are separate components.
See also: Frontend testing
Automated checks that the screens work as people expect.
In the notes app: One test opens a note, edits it and checks that the change shows.
How information is shaped and stored so that it stays correct.
In the notes app: A note belongs to one notebook and can have many tags.
Keeping two devices the same when both change.
In the notes app: If a phone and a laptop edit one note, the app keeps both versions.
Take from this: the filter starts on Now and always says how many entries it hides. A link to an entry opens it, even when the filter or a search would hide it.
A status page puts its health rows beside a short timeline. On a phone they stack.
Take: every part is fine except the one only you can decide.
A handover sorts what it knows by how it was checked. Each column is one state, with its own glyph and word.
Checked today with a command.
A note says so. Nobody re-ran it.
Three steps, in order.
Take: only the first column was checked today. Re-run a claimed row before you build on it.
Remember: the cobalt dot on a timeline is today; the colour of a status dot is the whole status.
Chapter 6 of 7, about 2 minutes
Before this: every device so far reduces what you must hold. Words are the last place that load hides.
The reading path is written the way you would say it out loud: short sentences, one idea each, the verb near the front. A technical word gets a plain definition the first time it appears, like idempotent below.
Everything exact lives in a fold: commands, file paths, hashes, tables. The page must make sense with every fold closed, so opening one is always optional.
One fact, at three depths.
The page remembers what you typed.
Each answer is stored in this browser, under the page address.
localStorage["explainer:/page:answers"]
node <plugin folder>/skills/html-explainer/scripts/check.mjs docs/explainers/2026-10-07-topic.htmlExit code 0 means every hard rule passed. It fails a page for a missing answer, a chapter without a visual, a paragraph over forty words, an external script, or an SVG without a title.
When the reader is a customer, the same rule becomes a promise: what it does for you, in your words. The proof sits in a fold, one piece for each promise.
server/app/retention.py:14 deletes every upload after 24 hours.docs/privacy.md:22 states that uploads are never shared or sold.https://status.example.com/uptime publishes the daily uptime record.A teaching page shows its subject as layers. Each layer lists the words it brings. One layer says where you are.
Take from this: each layer builds on the one before it. The chips are its new words.
The exact commands live here, out of the reading path. They number on from the steps in chapter 4.
gh pr create --fillCheck: the command prints a pull request address.
If it fails: run git push -u origin HEAD first, then try again.
gh pr merge --merge --delete-branchCheck: git branch -r lists only main.
If it fails: pull main into your branch, fix the conflicts and push again.
Remember: if you hit a hard word or a wall of detail in the reading path, the page is wrong, not you.
Chapter 7 of 7, about 1 minute
Before this: purple means you must choose. A question field is where you do it.
Some pages ask you things. Answer, and the page saves it on this device. A bar at the bottom then offers to copy or download.
One sentence is enough.
When the writer has a favourite, its option wears a star chip with the writer's own words: "Recommended", or "My pick" when one person is speaking to another. A playbook or a decision page ends with its decisions this way.
A buckets field gives each item one row of labelled buttons. The writer's pick is already set and marked ★, so the reader changes only what they disagree with. The first bucket then gets an order.
A plain rank field is the same control without the buckets. Moving an item, or tapping "This order is right", makes the order an answer.
When one person must rule on several open decisions, a ballot page shows each as a card. Every option is a picture, or a label and one line when there is nothing to draw. One tap picks it, and one button copies every pick.
If you skip this: A, the ★ option.
If you skip this: A, the ★ option.
Set data-mode="ballot" beside data-type="gather" on the html element. There is no rail, keep cards or recap: a column of cards and one tray. Every option needs a picture in .vis or, with no picture, a .detail line. Each single-choice card needs exactly one data-rec. The finished example is skills/explainer-gather/examples/ballot.html.
<p class="ballot-source">Rules on: the plan name, the date, the commit</p> <!-- optional, under the h1 -->
<p class="answer">4 decisions. Anything you skip goes with ★.</p>
<ol class="ballot-steps"><li><span><b>Compare</b> the pictures.</span></li> … the third step shows <span class="ballot-keycap">Copy picks</span></ol>
<section class="ballot-group" aria-labelledby="g1"><h2 id="g1">Shapes the build</h2><p>One line on why these come first.</p>
<article class="ballot-card" id="card-q1" data-q="q1" data-short="When a note saves">
<header><span class="num" aria-hidden="true">1</span><h3 id="q-q1">When should a note save?</h3>
<p class="why">One line on why it matters.</p><span class="state">Not picked</span></header>
<div class="ballot-opts" role="radiogroup" aria-labelledby="q-q1">
<button type="button" class="ballot-opt" role="radio" aria-checked="false" data-k="A" data-rec="Recommended">
<span class="vis" aria-hidden="true"><!-- a mockup in spans (see .mock-*), or an img --></span>
<span class="name"><b>A</b> As you type</span>
<span class="effect">One line on what happens.</span>
</button>
<!-- B, C: the same; only one option carries data-rec. Put the recommended option first. -->
<!-- a text option: no .vis, one plain .detail line; data-warn adds a chip that names the cost -->
<button type="button" class="ballot-opt" role="radio" aria-checked="false" data-k="B" data-warn="Can't undo">
<span class="name"><b>B</b> Delete at once</span>
<span class="detail">One plain line on what happens.</span>
</button>
</div>
<p class="skip"><b>If you skip this:</b> A, the ★ option.</p>
</article>
</section>
<!-- multi-select card: data-kind="multi"; each option is a div with its own toggle, then one Ship none -->
<div class="ballot-opts" role="group" aria-labelledby="q-q4">
<div class="ballot-opt" data-k="A" data-rec="Recommended"><span class="vis" aria-hidden="true">…</span><span class="name"><b>A</b> Word count</span><span class="effect">…</span>
<button type="button" class="ballot-ship" aria-pressed="false">Ship this</button></div>
</div>
<div class="ballot-none"><button type="button" data-none aria-pressed="false">Ship none</button></div>
<!-- reference cards: <section class="ballot-group"><h2>Already decided</h2><p>…</p><div class="ballot-dones"><article class="ballot-done"><h3>…</h3><p>…</p></article></div></section> -->
<!-- the tray, last in main. The script fills the jump dots and the review rows; Copy picks is the only primary button. -->
<div class="ballot-tray" role="region" aria-label="Your picks">
<div class="ballot-bar"><p class="ballot-tally">0 of 4 picked</p><ol class="ballot-pips" aria-label="Jump to a decision"></ol>
<div class="ballot-actions"><button type="button" data-copy>Copy picks</button></div></div>
<div class="ballot-tools"><button type="button" data-pick-rec>Pick all ★</button>
<details class="ballot-review"><summary>Review picks</summary><ol class="ballot-rows"></ol>
<label class="ballot-note"><span>Anything else?</span><input type="text" maxlength="300" autocomplete="off"></label></details></div>
<div class="ballot-meta"><p class="ballot-status" aria-live="polite">Tap an option on any card. Your picks collect here.</p>
<span class="ballot-save">Saved in this browser</span><button type="button" data-json>Copy JSON</button></div>
<div class="ballot-fallback" hidden><label for="ballot-fallback-text">The text is selected. Press Ctrl+C (⌘C on a Mac), then paste it into the chat.</label>
<textarea id="ballot-fallback-text" readonly></textarea><button type="button" data-close>Close</button></div>
</div>The default kind is text. Set data-kind for the rest. Every field needs a stable data-q.
<!-- multi: checkboxes, several answers; the textarea is an optional reason -->
<fieldset class="answer-field" data-q="q3" data-kind="multi">
<legend>Which parts need work?</legend>
<label><input type="checkbox" value="Intro"> Intro</label>
<label><input type="checkbox" value="Method"> Method</label>
<textarea id="q3-why" rows="2" aria-label="Why"></textarea>
</fieldset>
<!-- scale: radios 1 to 5 -->
<fieldset class="answer-field" data-q="q4" data-kind="scale">
<legend>How clear is this page?</legend>
<p class="hint">1 is unclear, 5 is clear.</p>
<label><input type="radio" name="q4" value="1"> 1</label>
<label><input type="radio" name="q4" value="2"> 2</label>
<label><input type="radio" name="q4" value="3"> 3</label>
<label><input type="radio" name="q4" value="4"> 4</label>
<label><input type="radio" name="q4" value="5"> 5</label>
</fieldset>
<!-- rank: the reader moves items, the order is the answer. Every item has a data-id and one span. The script adds
Move up, Move down, Move to top, "This order is right" and the spoken status. The optional textarea is the reason. -->
<fieldset class="answer-field" data-q="q5" data-kind="rank">
<legend>Put these in order, most important first.</legend>
<ol>
<li data-id="speed"><span>Speed</span></li>
<li data-id="cost"><span>Cost</span></li>
<li data-id="safety"><span>Safety</span></li>
</ol>
<textarea id="q5-why" rows="2" aria-label="Why"></textarea>
</fieldset>
<!-- buckets: 2 to 5 labels in data-buckets, split by |. Every item has a unique data-id and a data-rec that names one of the
labels (the writer's pick, marked ★). Each item is a b (the title) and a span (one line). Up to 15 items. -->
<fieldset class="answer-field" data-q="q7" data-kind="buckets" data-buckets="Now|Next|Later|Not now">
<legend>Which of these should we build first?</legend>
<p class="hint">Tap a bucket for each item. My pick is set and marked ★.</p>
<ol>
<li data-id="search" data-rec="Now"><b>Fix the slow search</b><span>Search takes four seconds on a phone.</span></li>
<li data-id="logo" data-rec="Later"><b>Change the logo</b><span>A new logo on the sign-in page.</span></li>
</ol>
</fieldset>
<!-- confirm: understood, agree or concern, plus a comment -->
<fieldset class="answer-field" data-q="q6" data-kind="confirm">
<legend>Is this chapter clear and acceptable?</legend>
<label><input type="radio" name="q6" value="understood"> Understood</label>
<label><input type="radio" name="q6" value="agree"> Agree</label>
<label><input type="radio" name="q6" value="concern"> Concern</label>
<textarea id="q6-why" rows="2" aria-label="Comment"></textarea>
</fieldset>A questionnaire's first screen shows one dot per question. A dot links to its question and fills in once you answer it.
Take: answer in any order. The count and the dots keep up with you.
Remember: your answers stay on your device until you copy or download them.
Should every new explainer start from this system?
If you do nothing: the skill is installed and will be used the next time you ask for an html explainer.