Html Explainer

HTML Explainer

Build useful explainers: interactive, polished and educational. Lets a user land on a page and come away with new understanding, whether they skim or drill down.

This skill is a process, not a template. Key goals:

1. A clear mental model & progressive complexity — give the reader one way to think about

the subject early (where the topic has one), then sequence so a newcomer can follow.

1. Show, don’t tell — whenever a concept can be demonstrated, build a tiny **playable

micro-demo** instead of writing a paragraph. Learning-by-doing.

1. Visual design quality — 10x it: varied, polished, a consistent visual language that teaches.
2. A real quality loop — build, actually look at it rendered, critique like a human, improve.
3. Research & sharpening questions — get the facts right first; turn a vague brief into a spec.
4. Trust — cite sources, distinguish settled from uncertain, never fabricate.

---

> STOP — do Phase 0 before writing any HTML or running any research. Your first response must be a short scoping interview covering all seven must-ask questions in Phase 0 — grounding · audience & depth · format · play-it-straight-or-go-bold · visual style · quiz · AI chat. Ask every one; the last (AI chat) is the most-skipped — do not drop it. You can add more questions (see below), but not subtract. >

Phase 0 — Research & sharpen (before any HTML)

• Get the facts first — but only research if the topic needs it. Being wrong is bad, but unnecessary research on a well-established topic wastes 2–3 minutes on topics you already know. Before searching, ask: is this topic settled or possibly dynamic?
• Settled — the topic is well-understood, stable, and your training data is authoritative. No research needed; go straight to Phase 1. Examples: how airplanes fly, how DNA replication works, how compound interest works, the French Revolution.
• Possibly dynamic — the topic involves anything that changes: current legislation or amendments, a specific company/product, market data, recent events, regulatory status, anything post-cutoff, or a niche area where your training may be incomplete. Research before building.
• This applies to any domain — a science topic can be dynamic (a new treatment, a recent discovery), and a legal topic can be settled (the US Constitution’s original text).
• Cap research at 2–3 fetches. One authoritative primary source + at most 1–2 cross-checks. Stop there, since additional searches add little value and burn tokens and time.
• Gather synthesis while you research, not after. As you read, note the parallels, tensions, ironies, and second-order effects (what does this resonate with? what’s the contradiction? who’s affected?). Use these later if they illuminate the html, but don’t force a connection that doesn’t exist.
• The seven must-ask questions (from the gate above). Present each as a **clickable option

menu in the richest UI available in the environment (Cowork, Claude app); if you’re in plain text (e.g., Claude Code), then list them in one message. If the menu tool caps how many questions you can ask per prompt (Cowork caps around four), ask them in multiple rounds — a first batch, then the rest — or put the overflow questions in the message text. Either way, ask all seven. NEVER silently apply a default to a must-ask (especially AI chat) just because the menu was full — a tool cap is not permission to skip. Recommend a default for each (one click) — except AI chat, which has no recommended default: ask it as an open yes/no. Never skip any of the seven, including the last. Labels must be self-explanatory — some surfaces (Cowork) show only the option label and drop the per-option description, so never rely on the description field to carry the meaning. If a choice isn’t obvious from a short label alone (e.g. play it straight / go bold, scrolling / deck), fold the gloss into the label text itself and repeat it in the description; when in doubt, put the key distinction in the question or message body too.**

• Grounding — does the user have their own material (doc, PDF, notes, URL) to ground in? If yes, treat it as the primary source of truth. Ask this as: “Do you have your own material to ground in?” with options “No” (recommended default) and “Yes — I’ll provide it”.
• Audience & depth — newcomer / practitioner / both-layered, and how deep. Drives sequencing.
• Format / reading shape — scrolling page (default) / slide deck / hybrid. See Format & reading shape. Must be its own question — never combine with style.
• Play it straight, or go bold? — how far to commit the design, and the axis that decides the look, so ask it before visual style (it gates that question). Never silently default to bland — an unattended build drifts safe; this is what stops it. “Bold” means committed and cohesive, not loud or decorated. Make the explanation UI-proof — never present the two as bare labels. Some menu surfaces (e.g. Cowork) render only the option labels and drop the description field, so the gloss must live where no renderer can hide it: fold it into the visible label text itself — e.g. Play it straight — sharp & professional, theme as a light accent and Go bold — immersive art direction built around the topic — and also fill the per-option description (Play it straight: Sharp and professional. · Go bold: Immersive art direction built around the topic.) for surfaces that do show it. If you present the interview as plain text rather than a menu, write the gloss inline in the question. The reader must always see what each choice means without hovering or expanding.
• Play it straight — clean editorial excellence (Stripe / FT / Vox): restrained layout, theme as a light accent, one subject-derived color. Sharp and polished, not timid. Best for reference, legal, compliance, or when the user wants it sober. → then ask the visual-style register (next question).
• Go bold — commit to one strong, cohesive concept and turn the ambition up: full art direction (theme every surface — body, UI, sliders, quiz — into one immersive world, not just an accent, when it’s cohesive); adventurous format (break the standard eyebrow→heading→prose rhythm; asymmetry, dramatic scale, unexpected but purposeful structure and motion); imaginative demos (reach for the most vivid concept the topic allows, not the safe stepper - see Themed interactivity is the gold standard and Interactivity Patterns below); a strong point of view, with the prose-flair dial (see Prose voice) pushed up to match — they move together. Best for evocative, cultural, historical, or physical-phenomenon topics. → the concept pass drives the look (see visual style, next).
• Bold is not a license for slop — it’s the opposite. Slop is generic (emoji icons, stock gradients, bento grids, the templated palette); bold is specific and crafted. Every anti-slop rule in Phase 2 still holds, and legibility is non-negotiable at any intensity. A bold build is judged relevant + cohesive + legible (Phase 2), never on “how much theme is too much.”
• Read the topic and recommend (evocative → go bold; dry reference → straight), but the user chooses. This sets how hard Phases 2–4 commit; honor it — don’t let the QA gate quietly sand a bold build back to safe.
• Visual style / vibe — conditional on the answer above; all style lives in centralized tokens.
• If “play it straight”: offer a register + a default — minimal-editorial (clean, Stripe-docs — good default) / technical-dark / brand-matched (they supply colors/font/URL). Theme is at most a light accent.
• If “go bold”: skip the preset menu — the concept pass (below) generates a topic-matched art direction from the subject itself (palette + typefaces derived from the concept, film-noir-style). You may offer a single tonal leaning so the user keeps a dial — e.g. dark & dramatic / warm & vintage / bright & playful — but the concept, not a preset, is the style. See Phase 2 for the build bar (relevant + cohesive + legible).
• Quiz / knowledge check? — yes/no. A short test-yourself (MC or fill-in, instant right/wrong + a one-line why) makes it stickier and works in a pure file. Default yes, small end-of-section or end-of-page unless declined or it’s reference-style.
• AI chat / Q&A? — don’t assume no; ask this explicitly even for a single-file build (it’s the most-skipped question). No recommended default — a genuine yes/no. If yes, build as a single-file BYOK (inline

chat-dock.js — reader supplies their own key; stays one portable .html); ask which provider. Only proceed without chat if the user declines, and say it’s designed to add later. See Drop-in widgets.

• Default unless the topic/answers make it relevant (state your default; only ask if it matters):

depth/length — quick one-pager (~3 min, one idea, ~1 demo) · standard (~8–10 min, default) · comprehensive deep-dive (more sections + demos; deeper layers); sets how much you build, distinct from audience/depth (who it’s for) · scope (in/out for v1) · interactivity depth (filters, timelines, multiple demos) · output target (see Output targets) · delivery/deploy (default = hand over the file; see Phase 5).

• Exception — programmatic harness only: if a wrapper app already collected these via its own form (e.g. Explainer Studio), the answers arrive with the brief — honor them, don’t re-interview. A normal chat with a person (including the Claude app) is NOT this case: ask the must-ask set.
• Collect a source list as you go; every non-obvious claim should be traceable.
• Prose voice (silent — not a user question). One house voice: Professional.
• Concrete-first and reportorial — lead with the fact or the object, state it plainly, and let specifics and numbers carry the weight. No reveal structure (“not X, it’s Y”), no aphoristic closers, no mic drops, no cutesy motifs. Em dashes should be rare; ask yourself “do I really need an em dash or will other punctuation do?”
• Keep sentences lean at roughly newswire length, at or under the word count a showier draft would use; in a deck, treat ~45 words for a cover blurb and ~90 for a body slide as soft ceilings, and if a slide won’t compress it is carrying too much prose — give the weight to a demo or cut it.
• Important: vary tone by temperature, rhythm and sentence length - set short, punchy sentences against longer flowing ones. Same length sentences read flat. Write from the facts, then de-slop (see below): editing a performed sentence keeps its shape, so rebuild it from what’s underneath. Toggle: You can dial the prose flair up or down depending on topic; for a legal writeup, the flair is low, but for a fun or imaginative explainer, it’s higher.

> **Once the interview is answered: think, then immediately write the file. Do NOT output your architecture plan, section order, design token choices, or any “Phase 1/2 thinking” as chat text. All planning happens silently. You may output ONE scope line first — Scope: [N sections, centerpiece: X, ~N lines] — nothing more. The next output after that must be a Write call. Match length to the chosen depth — one-pager ~300–500 raw lines, standard ~600–1100, comprehensive as long as the material earns it. If a build runs past its depth budget, cut redundancy and padding first (that's the Phase-4 redundancy pass) — never trim real demos, art direction, or teaching just to hit a number; a ~900–1000-line go-bold page with two or three working demos is expected, not bloat. Past ~1200 raw lines, stop and check it's richness, not sprawl.**

> The concept pass — this is what “think” means above (silent; don’t output it). A great page comes from ideation, not defaults. Do not build the first thing that works — generate real alternatives and commit to the strongest, deciding: > - **Art direction — ideate 2–3 distinct directions and commit to the strongest. This runs for BOTH straight and bold** — the straight/bold answer sets the target, not whether you ideate. Don't settle for the first look that comes to mind; that's the safe default, and defaulting is what makes a build generic (bland-tasteful if straight, era-match costume if bold). Never reflex-default: no Inter-on-white, no templated cream + lone-rust palette (banned at every intensity — see the Phase 2 slop tells). > - Play it straight: pick the register that best fits the topic and give it at least one subject-derived element — an accent color or a display face that suits the subject — so it reads as this topic, not a generic clean template. > - Go bold: commit to the boldest cohesive concept — a world, an angle, a visual metaphor with a point of view. Reject the era-match skin: old/historical → parchment/sepia/cream+serif is costume, not a concept (the "parchment for the Black Death" trap). > Either way, derive from the chosen direction: typefaces that express it (period-/domain-appropriate — never system/Inter by reflex), a subject-derived semantic palette, substrate/texture, and one recurring motif. Litmus (both modes): a look you could swap onto a different topic unchanged isn't finished — bold that fails it is a skin; straight that fails it is generic. > - Throughline: the mental model, and how the centerpiece, demos, and color all reinforce it. > - Demos: brainstorm 3+ candidate demo concepts the topic affords, then build the **2 most vivid and mechanism-true** — reach for the one that makes someone say whoa, not the safe stepper. (A watch → an escapement that ticks beat by beat; a record → a groove whose wobble is the waveform. Ask what the equivalent is for this topic.) > - On “go bold,” push each of these to the boldest cohesive option (study reference/film-noir-theme.png). Picking the first serviceable font/demo is how a page ends up bland; the model that skips this pass produces safe defaults. >

Phase 1 — Architecture for learning (sequence before you style)

• Lead with orientation, not the advanced/latest thing. Default to a learning path: what is it

→ the core mental model → the specifics/payoff → details → the news/edge cases.

• Find the mental model that illuminates and unlocks the topic — then commit to it (where the topic has one). Hand the reader one way of thinking early (a metaphor, reframing, or unifying picture) and reuse it as a throughline — centerpiece, demos, and recurring motif all reinforce the same model. Test: a reader who finishes can restate it in a sentence.
• Don’t force it, don’t make it a worksheet. Some topics (reference matrix, list of rules)

have no honest single mental model; a forced analogy that breaks under scrutiny is worse than none at all. If a mental model only half-fits, drop it.

• Lead with clarity, not cleverness — keep the model out of the headline. The `` must

plainly name the topic (“How compound interest works”) — a metaphor may ride alongside but never replace it (the nav/brand label is not the title). Keep title and intro editorial, not slogan-y; introduce the model once, in its own section — don’t stack 2–3 metaphors or turn it into a slogan/joke/precious copy. The model is a way of seeing things, but you don’t need to dress up the entire page in the model, so don’t repeat the metaphor after the intro or frame the visuals in cute metaphorical terms. After the intro, use normal, professional section treatments.

• Optional (where relevant): open on the experience, then the turn, then name it. When a section (or the page) has a counterintuitive core, open on the concrete expe

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ds-vibe
• Source: ds-vibe/html-explainer
• License: MIT
• Homepage: https://ds-vibe.github.io/html-explainer/

Install and usage instructions live in the source repository linked above.