Html Explainer

html-explainer

Produce a single, self-contained HTML file that explains, compares, or visualizes something — using a curated stack of CDN-loaded UI libraries. Inspired by https://claude.com/blog/using-claude-code-the-unreasonable-effectiveness-of-html — HTML beats markdown for density, interactivity, and staying in the loop.

Aesthetic (read this first)

The look is editorial magazine, not SaaS dashboard. If your output feels like Stripe's docs, you've overshot toward "tech-y." If it feels like a Notion page, you've undershot toward "default." Aim for The Pudding, Quanta Magazine, a Stripe Press book page, or a tasteful personal blog.

• Warm cream background (#FBF7F1), deep ink text (#1A1A1A), generous whitespace.
• Instrument Serif for headlines (large, expressive, occasionally italic).
• Inter for body, with leading-[1.75] and ~65ch max line length.
• Caveat (handwritten) for marginalia, dividers, arrows, eyebrows — sparingly, like ink in the margin.
• Coral / butter / sky / blush accents — not blue-purple SaaS gradients.
• No grid of cards for its own sake. Cards are for actual comparisons; prose is for prose.
• Hand-drawn touches via rough-notation: underline 2-4 key phrases, never more.
• Soft shadows, big rounded corners, paper-grain background gradients.

When in doubt: would a designer at a magazine make this? If not, simplify.

When to use this skill

Default to this skill for any substantive explanation. The bar is low: if the chat answer would be more than ~3 short paragraphs, or would have a diagram, comparison, list of options, or any visual structure — make an HTML artifact instead.

Fire on phrases like:

• "explain X", "walk me through X", "how does X work", "teach me X", "tell me about X"
• "what's the difference between X and Y", "compare X and Y", "X vs Y"
• "deep dive on X", "break down X", "overview of X"
• "diagram X", "visualize X", "mock up X", "sketch X"
• "write a spec / report / cheatsheet / explainer for X"

Also fire when no phrase matches but the answer wants:

• side-by-side comparison or tradeoffs
• a flowchart / sequence / state / ERD diagram
• an interactive node graph (React Flow style via Drawflow)
• a step-by-step walkthrough with annotated prose
• mockups or multiple variants in one view
• a dense reference table or cheatsheet
• anything that would otherwise become a wall of markdown

Don't fire for: one-line answers, single short code snippets, yes/no questions, quick lookups, simple commands, or follow-up clarifications. When in doubt: would the user enjoy opening this in a browser tab and keeping it? If yes, use the skill.

Output protocol (always — copy-then-edit, never write from scratch)

Never regenerate the boilerplate. Doing so is slow and unnecessary — the whole template (CDN stack, Tailwind config, custom CSS, explain-on-select widget) is identical for every artifact. Always start by copying base.html, then make small edits to the content sections only.

1. Copy the template first with a single Bash call:

`` cp ~/.claude/skills/html-explainer/base.html ./.html ` Use a descriptive filename — e.g. how-react-fiber-works.html, auth-approaches.html`.

1. Plan the visual pieces alongside the prose. A complete artifact has, by default:

• 1-3 baked illustrations (` with data-prompt`)
• 1 Lottie animation chosen for the topic (see the "Lottie animation" section below — this is a default, not optional)
• 0-2 Mermaid diagrams if the content benefits
• 2-4 rough-notation annotations on key phrases

For the Lottie, do the search + curl-verify step BEFORE writing the body. Picking it later breaks flow.

1. Edit only the content sections using the Edit tool (NOT Write). The placeholders in base.html are clearly marked with HTML comments and are the only things you should touch:

• Untitled explainer → real title
• `` block → category label ("An explainer", "A comparison", "A spec"…)
• `` block → h1 + lead paragraph
• `` block → the gist (one sentence)
• ` block → replace with your real sections (multiple `s, diagrams, comparison grids, illustrations, the Lottie, etc.)
• Keep the hand-drawn divider; reuse it between sections

Never edit: the CDN includes, the tailwind.config script, the `` block, the Mermaid init script, the rough-notation auto-wiring, the explain-on-select widget HTML/CSS/JS. Those are part of the runtime — leave them alone.

1. Open the file so the user sees it immediately:

`` open .html ``

1. Reply in one or two sentences. The file is the answer; don't restate it in chat. If you skipped the Lottie, name it: "(couldn't find a fitting free Lottie for X; skipped)."

If a brand-new section type doesn't exist in base.html (e.g. a Drawflow node graph), add it via Edit in the body — don't rewrite the file.

What's already in base.html (reference only — don't retype it)

base.html already includes the full runtime. You inherit all of this by copying the file:

• Tailwind (utilities only — no DaisyUI; too dashboardy) + custom config: font-display, font-hand, the cream/ink/coral palette, shadow-soft/shadow-lift
• Fonts: Instrument Serif (display), Inter (body), JetBrains Mono (code), Caveat (handwritten)
• Mermaid 11 + custom cream/butter/sky theme — drop in … anywhere
• rough-notation — auto-wires every [data-annotate] element on load
• Alpine.js 3 — x-data, x-show, @click work out of the box
• Lucide icons — `` auto-rendered on load
• Paper-grain background gradient (coral top-left, sky top-right)
• Explain-on-select widget (#ex-menu, #ex-popover, the IIFE script) — highlight → ✦ Explain
• Baked-image runtime — .ex-img-frame[data-prompt] divs auto-fill from gpt-image-2 after load
• Font-aware annotations — rough-notation waits for document.fonts.ready and re-renders on resize, with mix-blend-mode: multiply so highlights blend with text instead of covering it

Adding optional libraries

If a specific artifact needs them, add via Edit to the existing ``:

(There are commented-out lines for both already inside base.html's `` — uncommenting them is a small Edit.)

Explain-on-select widget (included by default)

Every artifact ships with an interactive widget: the reader highlights any text → a small ✦ Explain pill appears next to the selection → click → gemini-3.1-flash-lite streams an inline explanation into a popover anchored below the selection.

• Calls Google's Gemini API directly from the browser (streamGenerateContent?alt=sse)
• Text model: gemini-3.1-flash-lite (single TEXT_MODEL constant at the top of the widget script — change to swap models)
• API key (Gemini, starts with AIza…) prompted once on first click; stored in localStorage under html-explain-gemini-key; popover has a ⚙ reset key button. Same key is reused by the image baker.
• Free key: https://aistudio.google.com/apikey
• Rich context sent to the model: document title, subtitle, nearest section heading, AND the containing paragraph — not just the immediate sentence. This is what makes explanations grounded in the actual document.
• Selections inside .mermaid, svg, canvas, inputs/textareas are skipped to avoid garbage prompts
• ESC / click-outside / × dismisses; popover position is viewport-clamped

Do not strip this widget when generating new artifacts. It is part of the default reading experience. The HTML markup lives at the bottom of ` (#ex-menu, #ex-popover), the CSS lives in the main block, and the JS is an IIFE in its own tag. Copy all three together from base.html`.

Illustrations (baked images via gemini-3.1-flash-image)

The runtime ships an image generator: drop a ` with a data-prompt, and after page load the script calls Google's gemini-3.1-flash-image` (using the same Gemini key the explain widget holds) and slots the result into the frame. The reader sees a "drawing…" placeholder until it arrives.

Use illustrations the way an article would — sometimes informative (the actual thing being explained, a process), sometimes light decoration tying to nearby context. Never AI-bloat with random images for the sake of it. Cap: 1-3 per artifact, max.

Pattern:

  
  tiny caveat-font caption tying it to the prose

Prompt-writing rules (the runtime auto-appends a style suffix; you only describe the scene):

• Describe subject + action + 2-3 concrete props/elements. Keep prose-light.
• Always wide composition. The frame is 16:10.
• Anchor to the surrounding paragraph: if the section talks about caches, illustrate caches — not generic "abstract data flow."
• Don't ask for text/labels/numbers in the image (the model can't render them cleanly).
• Don't ask for specific colors — the suffix locks the palette to cream/coral/butter/sky.

Good prompt examples:

• "A whimsical filing cabinet overflowing with paper notes spilling onto the floor, a tiny stick figure sorting one into a drawer."
• "A desk from above: an open laptop showing a wide rectangular document, two curved arrows leaving the screen toward thumbnail doodles of a flowchart and a chart, a steaming coffee mug."
• "A paper airplane mid-flight over a winding dotted line, dropping tiny envelopes at three stops along the path."

Bad prompts: "AI explaining things", "data flowing", "complex concept" — too abstract, will produce generic slop.

Lottie animation (default: 1 per artifact — only if topic-relevant)

Aim for 1 Lottie per artifact, but the bar is topic relevance, not just "a verified URL." A generic "developer at laptop" animation on a DuckDB explainer is worse than no animation. The reader should glance at the Lottie and feel "ah, that is about the topic." If a fitting one can't be verified, skip and say so — don't fill the slot with filler.

Selection workflow

Perform this BEFORE writing the body, alongside picking baked illustrations:

1. Name the anchor noun — the literal subject of the artifact, or its central metaphor. For DuckDB → "duck." For React Fiber → "linked list" or "thread." For OAuth → "passport" or "handshake." Write it down before searching.
2. Search:

• WebSearch for free lottie animation lottiefiles lf20 json
• If that fails, search GitHub for sample lottie JSON URLs with the noun in their filename / path

1. Curl-verify before embedding — every candidate URL must:

• Return HTTP 200 on curl -s -o /dev/null -w "%{http_code}" --max-time 4
• Have an nm field in the JSON that plausibly matches your anchor noun (nm is the animation's internal name — read it with python3 -c "import sys,json; print(json.load(sys.stdin)['nm'])" ))

1. Embed with the small-size pattern below.

Hard rules

• No filler. If no URL passes both the 200 check AND the anchor-noun-match check, skip the Lottie. Don't substitute a generic "loading" or "developer" animation.
• No hero usage. Lotties sit beside a section, not above the headline. The baked illustration is the hero slot.
• Small. Default 160px square. Hard ceiling 200px. They're punctuation, not centerpieces.
• One per artifact. Two competes for attention; three is busy.
• Cute is fine (a swimming duck, a bouncing rocket, a tipping coffee cup) — but cute and relevant. Cute and generic is still filler.

Embed pattern

  .json"
    background="transparent"
    speed="1"
    style="width: 160px; height: 160px;"
    loop autoplay>
  

When you skip, name it

In your end-of-turn reply add a short line: "couldn't verify a fitting Lottie for <anchor noun>; skipped." The user explicitly asked for honesty about this — silently omitting reads as forgetting.

Type ramp

font-display text-6xl md:text-7xl   → page headline (Instrument Serif)
font-display text-4xl                → section headline
font-hand text-2xl text-coral        → marginalia, eyebrows, "the gist", dividers
text-xl leading-relaxed              → subtitle / lead paragraph
text-lg leading-[1.75]               → body
text-sm text-ink-mute                → metadata
font-mono                            → code

Palette (Tailwind tokens, set in base.html)

cream      #FBF7F1   background
cream-deep #F4EFE6   panels
cream-edge #E8E2D5   borders / dividers
ink        #1A1A1A   primary text
ink-soft   #3A3A3A   secondary text
ink-mute   #6B6B6B   metadata / captions
coral      #FF8B6B   primary accent (annotations, eyebrow flourishes)
butter     #FFE889   highlight accent
plum       #3B2F5C   deep accent for emphasis
sky        #A8D5E2   diagram accent
blush      #F4B5C8   diagram accent

Never hard-code other grays/colors. Use these tokens.

Library cookbook

Mermaid — declarative diagrams

Drop a … anywhere. Use:

• flowchart LR / flowchart TD — process / architecture
• sequenceDiagram — request/response, protocols
• stateDiagram-v2 — state machines, lifecycles
• erDiagram — schemas
• mindmap — concept maps

flowchart LR
  A([User clicks]) --> B{Logged in?}
  B -->|yes| C[Fetch data]
  B -->|no|  D[Redirect to login]
  C --> E([Render])

Keep node labels ≤4 words. Long descriptions go in prose next to the diagram, not inside nodes. The base template's Mermaid theme is already coral/butter/sky on cream — don't override it.

Drawflow — React Flow–style interactive nodes

Only when nodes must be draggable / connectable. For static, use Mermaid.

  const editor = new Drawflow(document.getElementById('drawflow'));
  editor.start();
  const n1 = editor.addNode('Input',  0, 1,  60, 100, 'card', {}, 'Inputuser query');
  const n2 = editor.addNode('LLM',    1, 1, 320, 100, 'card', {}, 'LLMgpt-4o');
  const n3 = editor.addNode('Output', 1, 0, 580, 100, 'card', {}, 'Output');
  editor.addConnection(n1, n2, 'output_1', 'input_1');
  editor.addConnection(n2, n3, 'output_1', 'input_1');

  .drawflow .drawflow-node { background:#fff; border:1px solid #E8E2D5; border-radius:16px; box-shadow:0 1px 2px rgba(20,14,4,0.04),0 8px 24px rgba(20,14,4,0.04); }
  .drawflow .connection .main-path { stroke:#1A1A1A; stroke-width:2px; }

rough-notation — hand-drawn annotations (the fun layer)

Animate underlines, circles, highlights, boxes on any element. 2-4 per page max. Annotate the prose that explains a thing, never the thing itself.

  React Fiber is a
  linked-list re-implementation
  of the virtual DOM that makes rendering
  interruptible.

Types: underline, box, circle, highlight, strike-through, crossed-off, bracket. base.html wires up [data-annotate] automatically — just add the attributes.

Alpine.js — tiny interactivity

Tabs, toggles, accordions, copy buttons. No build, no JSX, just attributes.

  
    Before
    After
  
  // old
  // new

Lucide — icons

`. Use sparingly; this is an editorial document, not a control panel. Common: arrow-right, quote, book-open, feather, sparkles`.

Composition patterns

Hero header (editorial)

  ✦
  An explainer

  How React Fiber works

  Why React rewrote its reconciler in 2017 and what it bought us.

TL;DR aside (margin-note style)

  
    ↳
    
      the gist
      One-sentence key insight.
    
  

Comparison (2-up or 3-up) — only when actually comparing

  
    
      Option A
      recommended
    
    One-line pitch.
    
      +pro
      −con
    
  
  

Diagram + caption

  
flowchart LR
  A([request]) --> B[middleware] --> C[handler] --> D([response])
  
  
    every request walks this path
  

Hand-drawn divider

  ~
  

Stat callout (big number, label)

  42%
  of queries return from cache — the rest hit Postgres.

Pu

…

Source & license

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

• Author: adaminspaceship
• Source: adaminspaceship/html-explainer
• License: MIT

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