Visual explainer

Contents

• 1. Settle the request
• 2. Understand it properly
• 3. Plan before writing HTML
• 4. Write in plain language
• 5. Build the page
• 6. Render, look, fix
• 7. Deliver
• Design rules (Nocturne)
• Building another explainer skill on this one

Reference files (open one when a step points to it):

• references/diagrams.md: Diagram catalog
• references/interactive.md: Full visual mode: interactions
• references/layout.md: Page layout and visual hierarchy
• references/research.md: Why the rules are what they are
• references/showme.md: Show me: animated walkthroughs
• references/writing.md: Writing in plain language

The goal: a reader who stops after one minute already knows the answer; one who reads for five minutes understands how it works; one who wants to see it happen can watch it; the curious get the details. Every rule below comes from research on reading, learning and attention. references/research.md has the evidence when someone asks why.

Paths below are relative to this skill's directory. Run scripts with python on Windows (python3 is the Microsoft Store stub there) and python3 elsewhere.

1. Settle the request

• Topic and sources. What to explain, and from what: the user's words, files, a codebase, URLs, or your own research. Ask only if the topic itself is unclear.
• Mode. baseline (default): calm and quick to read. full when the user passes --full or asks for "full visual", "interactive", "turn it up" or similar.
• Pace. normal (default), slow or fast for the animations, when the user passes --tempo or says the animations should be slower or quicker. Choose slow yourself for complex step-by-step builds or audiences new to the field. Readers can still change it on the page.
• Scope. Words like "simple", "short", "quick", "one-pager" or "they have a minute" are a request for less, not just shorter sentences. Then build the short version plus at most three sections on "How it works", leave out the deep dive, and add Show me only if demonstrating is what was asked. Aim for under about 700 words in total. Cut whole sections, never the definitions of the terms you keep. When the topic is something to do, keep a short ordered list of the steps or commands, even without a Show me page. Without such words, use the full four-page shape where the topic needs it.
• Audience. Assume a smart reader who doesn't know the field, unless told otherwise. Managers read page 1; everyone can read page 2.
• Language. Write in the language of the request.
• Output. One .html file named after the topic (oauth-sign-in.html) in the current directory, unless the user names a place. Work in a scratch folder (<tmp>/visual-explainer-<slug>/).

2. Understand it properly

Read the sources, and research what's missing. Keep notes.md in the work folder: every claim, number, step and user-interface label with where it came from.

• Never invent numbers, quotes, button labels or steps. If the docs don't say, leave it out or mark it as uncertain on the page.
• Procedures ("how do I…"): check every step against current official documentation, because menus get renamed. Note the product version or date.
• Codebases: read the code that does the work, not just its README.

3. Plan before writing HTML

Write plan.md in the work folder. It is short and decides everything:

1. The answer in one sentence. A statement, not a topic name. Not "OAuth explained" but "Sign in with Google tells an app who you are. It never sees your password." This becomes the headline.
2. A one-sentence summary that adds the how.
3. Three takeaways: what the reader should still know in a week.
4. What this means for the reader: the decision, action or consequence.
5. One key number, if there is one that matters.
6. Words you'll meet: every technical term and abbreviation the page uses, each with a plain one-line definition.
7. How it works: up to five questions the reader would ask, in the order they'd ask them. For each: the shape of the idea (sequence? comparison? parts of a whole? layers? change over time?), the diagram that shows that shape (references/diagrams.md), an everyday comparison if it helps, and a quick check.
8. Show me: is there something to demonstrate? Clicks in an app become drawn screens with a moving cursor; messages between systems or people become a sequence; when the real screen's look matters, a screenshot tour. Commands become a terminal. If nothing moves or happens, there's no Show me page.
9. Deep dive: edge cases, trade-offs, numbers, tables, sources. Skip the page if there's nothing worth adding, or if the request asked for something short.
10. Full mode only: the interactions, at most one per section, chosen from references/interactive.md. Each one must make the reader think: guess, decide, change one thing, or put things in order.

4. Write in plain language

Read references/writing.md before writing. The rules the build script checks:

• Abbreviations: spell out at first use, "Proof Key for Code Exchange (PKCE)", and use few of them.
• Short sentences: most under 20 words, none over 28.
• Terms: every technical term is in "Words you'll meet", or explained in the sentence where it first appears.
• Headings on "How it works" are questions the reader would ask.
• Every diagram gets a "What to notice" line saying what to look at.

5. Build the page

Write body.html: two to four <section class="page"> elements and nothing else. references/layout.md gives the skeleton of each page and the hierarchy rules. Take components from references/diagrams.md, references/showme.md and (full mode) references/interactive.md. assets/example-body.html is a complete full-mode page. Open it when you need to see how everything fits together.

• Icons: <svg class="ic"><use href="#i-NAME"/></svg>, where NAME is a file in assets/icons/ (Lucide line icons; list them with ls). An icon labels a word; it never replaces one. No emoji.
• Images: <img src="shots/x.png" alt="…">, relative to body.html; the build inlines them.
• Custom CSS only when no component fits (diagrams.md ends with how to build one). Write it in custom.css, and use the colour variables (var(--accent), var(--muted), var(--line), var(--on-accent) for text on orange…), never raw colours.

python "<skill-dir>/scripts/build_page.py" --body "<work>/body.html" --topic "Sign in with Google" \
    [--mode full] [--tempo slow] [--css "<work>/custom.css"] -o "<work>/page.html"

The build adds the navigation, icons, images and all behaviour, then checks the page. Fix every ERROR and every WARNING. The warnings are the rules: abbreviations, three takeaways, at most five sections, a figure and a quick check in every section, full-mode parts in a baseline page, long sentences, missing alt text. Re-run after each edit.

6. Render, look, fix

python "<skill-dir>/scripts/render_check.py" "<work>/page.html" --out "<work>/render" --dark --figures

It renders every page at desktop and phone width, in light and dark, in the finished state (reduced motion: diagrams complete, players on step 1, plus a second render with every player on its last step). It reports overflow, overlapping and clipped text, and broken images, and saves slices plus one image per figure (render/index.txt maps them).

Read the images, the figure crops above all. Look for labels colliding with lines, arrows pointing the wrong way, bars that don't match their numbers, cramped phone layouts, and anything unreadable in dark mode. Fix and re-run.

The renders can't show motion or clicks. If a browser tool is available (Playwright or Claude in Chrome), open the page through a local server (python -m http.server in the work folder) and check: the players step correctly, the cursor lands on its targets, quick checks open, and full-mode interactions respond. Otherwise, say in your reply that you didn't test them live. Browser tools may save snapshots and screenshots into the current repository (for example .playwright-mcp/): move what you need into the work folder and delete the rest before you finish.

7. Deliver

Copy page.html to the output path. Tell the user, in a few lines:

• where the file is,
• which pages it has, and what each one covers,
• what moves or responds, and anything they should double-check (for example, "the steps follow Atlassian's docs as of November 2026").

Then delete the work folder's scratch files (keep the output if the user put it there), or say where they are if they hold screenshots the user may want.

Design rules (Nocturne)

The template already carries the look. Keep it intact:

• One orange thing per screen. Orange marks the single most important item. Everything else is charcoal, grey and white.
• Quiet type. Light headline weight, no bold headlines, no all-caps headings.
• Lines, not boxes. Use a card only when it groups something.
• Nothing decorative. No stock images, no ornamental illustrations, no emoji. Pictures that only decorate measurably lower learning. The "wow" comes from the explanation moving.
• Motion means something: order, change, size or cause. The template plays each animation once when it comes into view, offers replay, and respects reduced motion. Don't add loops.
• Motion is paced for reading, not for snappiness: one beat (0.65 s) per labelled item, all scaled by the pace. Custom animations use --beat, --stagger and --tempo (layout.md, Motion); the build warns when they don't.

Building another explainer skill on this one

Other skills that explain things (a video, a codebase, a process) can reuse this one. They gather their material their own way, then follow steps 3 to 7 here: the same plan, writing rules, components and scripts. From a sibling skill, the scripts are at <that-skill-dir>/../visual-explainer/scripts/. Pass --mode through unchanged, so users get the same baseline and full experience everywhere.