---
name: talk-to-me-in-html
description: Turn ANY complex topic into a single self-contained, interactive HTML explainer built for how ADHD / interest-based brains actually learn — hook-first, chunked, dual-coded, animated-with-meaning, theme derived from the topic itself (never a generic design system). Use this skill whenever the user says "talk to me in HTML", "explain X to me", "help me understand", "make this simple", "visualize how X works", "teach me", "break this down", "make an explainer / interactive page / diagram / animation about a concept", or pastes a dense doc/paper/codebase and wants to grok it. Covers charts, diagrams, sketches, simulations, real screenshots, and (rarely) recorded video embedded in HTML.
---

# Talk To Me In HTML

> One job: the user *understands* the topic and *remembers* it a week later.
> Output: a single self-contained HTML file (or small bundle) that explains the topic with whatever medium the moment needs — animation, diagram, chart, simulation, sketch, real screenshot, rarely video.
> This skill sits on top of the vendored taste-skill engine (`vendor/taste/taste-core.md`). Taste handles "does not look templated"; this skill handles "actually teaches."

---

## 0. THE TOPIC READ (before any code)

Like taste-skill's Design Read, but for cognition. State one line before generating:

**"Explaining: \<topic> as a \<concept shape> to someone with \<prior knowledge level>, anchored on the analogy of \<analogy>, themed as \<domain-derived theme>."**

Infer four things:

1. **Concept shape** — what *kind* of complexity is this? (drives the visual grammar, §3)
   - `FLOW` — sequence, pipeline, protocol, algorithm (e.g. TCP handshake, CI/CD, Krebs cycle)
   - `SYSTEM` — interacting parts, feedback loops (e.g. economy, immune system, event loop)
   - `HIERARCHY` — containment, taxonomy, scale (e.g. DNS, org of the cell, filesystem)
   - `CHANGE` — evolution over time, growth, decay (e.g. compound interest, entropy, model training)
   - `COMPARISON` — tradeoffs, X vs Y (e.g. SQL vs NoSQL, TCP vs UDP)
   - `SCALE` — orders of magnitude humans can't intuit (e.g. nanometers to lightyears, national debt)
   - `MECHANISM` — hidden internal machinery (e.g. how a transformer attends, how an engine fires)
   - `PROBABILITY` — uncertainty, distributions, risk (e.g. Bayes, false positives, Monte Carlo)
   Most real topics are 2 shapes composed. Name the dominant one.

2. **Prior knowledge** — what can the user already anchor to? Pull from conversation context and memory. The analogy MUST be built from what they already know (a backend engineer gets queues and caches; a cook gets mise en place and emulsions). Never explain unknown-in-terms-of-unknown.

3. **Emotional register** — is this topic neutral (how GPS works), anxiety-adjacent (a medical diagnosis, a loan rejection, tax law), or high-stakes-decision (should I take this drug/job/trade)? Anxiety-adjacent topics get calmer motion (MOTION dial −2), no playful loading gimmicks, no cutesy mascots, and honest uncertainty labeling.

4. **Domain theme** — derive the visual world from the topic, NOT from a house style. See §4.

If the topic is ambiguous between two very different reads, ask exactly ONE question. Otherwise declare the read and go.

---

## 1. THE COGNITIVE CONTRACT (hard rules — this is the ADHD layer)

These are non-negotiable. They come from the research digest in `references/adhd-cognition.md` (read it the first time you use this skill, and whenever a rule below feels wrong for the situation).

1. **Hook in the first viewport.** ADHD attention is front-loaded — engagement peaks in the first seconds. The first screen must contain the single most surprising/consequential fact or a live moving demonstration of the phenomenon. Never open with a definition, history, or table of contents. Open with the *"wait, what?"*.

2. **Chunk with visible endpoints.** Every section is one idea, consumable in ≤90 seconds, with a visible boundary and a progress rail showing "chunk 3 of 7". Finite beats open-ended: the brain needs to see the finish line. Never more than ~60 words of continuous prose per block. One idea per screen.

3. **Dual-code everything.** Every important idea appears as words AND picture simultaneously, spatially adjacent (label ON the diagram, not in a paragraph below it — Mayer's spatial contiguity). Prose that could be a diagram must become a diagram.

4. **Analogy before abstraction.** Sequence per chunk: concrete analogy from the user's world → the real mechanism mapped onto the analogy → where the analogy breaks (always state this — a taught analogy that silently breaks creates confident misunderstanding) → the precise term. Pre-train names of parts before explaining how parts interact.

5. **Motion means meaning.** Animation exists ONLY to show change, causality, flow, or to direct attention (signaling). If it loops decoratively, delete it. Every animation should be scrubbable or replayable — give the user control of time. `prefers-reduced-motion` collapses all of it to static end-states with step-through buttons. A mark travelling between nodes is one unit of work (a request, a message), its colour is that unit's state, and pulse/glow means nothing here: full grammar in `references/system-diagrams.md` §5.

6. **Interaction every 2–3 chunks.** A slider that changes an outcome, a toggle that flips a scenario, a one-tap prediction check ("what do you think happens if…?" → tap → immediate animated answer). Immediate feedback, never punitive. Mid-explainer checks are ungraded; the only scored moment is the end-of-page reality check in rule 9, and its score exists to point at a chunk to re-read, never to rank the reader.

7. **Novelty resets between chunks.** Vary the format: animation chunk → diagram chunk → interactive chunk → real-screenshot chunk. Two identical-format chunks back-to-back maximum. The format shift IS the attention reset.

8. **Coherence: cut ruthlessly.** Everything that doesn't serve the current chunk's one idea is extraneous cognitive load — the single highest-effect-size lever in multimedia learning research. No decorative stock imagery, no background music vibes, no filler transitions, no "fun facts" mid-mechanism (park them in a collapsible "rabbit holes" drawer at the end — ADHD readers love them but they derail mid-explanation).

9. **Memory anchors, engineered.** End with a recap card: the analogy in one line, one absurd/vivid image per key idea (weird sticks), a say-it-back prompt answered out loud with a `reveal the answer` button, a **reality check** (4–6 recall taps, ~one per chunk; each miss names the chunk to re-read, the tally names what to revisit), and the rabbit-holes drawer.

10. **Always show 'you are here.'** Working memory offload: the progress rail doubles as a mini-map of the ideas, current chunk highlighted. Returning after a distraction must cost zero reorientation effort.

11. **Size against the container, never the window.** Widths use `%`, `min(100%, …)`, `ch`, or grid tracks. No `vw` widths, no `100vw` bleeds, no `margin-left: 50%` + `translateX(-50%)`. Center with `grid-template-columns: 1fr min(100%, var(--col)) 1fr`; breakouts span the outer tracks. Media gets `max-width: 100%`. Wide SVG, tables, and `pre` scroll inside their own `overflow-x: auto` box, never `overflow: hidden`. The body never scrolls sideways. Check at 380px, in a ~700px panel, and at 1440px.

12. **No text inputs. No dead controls.** Zero `textarea` and text fields, whatever the label. Recall is checked with scored taps, `reveal the answer` buttons, sliders, toggles, and scrubbers, plus one copy-to-clipboard follow-up prompt. Never ship a submit, spinner, save, or login that does nothing, and never show an unwired input even as an illustration. Chat or streaming answers only if a backend was wired in this same request.

---

## 2. WORKFLOW

1. **Topic Read** (§0) — one line, stated to the user.
2. **Understand the topic yourself first.** If the topic is post-cutoff, niche, or the user pasted a source — research/read it before explaining. You cannot simplify what you haven't fully understood. Wrong-but-pretty is the worst failure mode of this skill; a confident animated falsehood is worse than a dry correct paragraph. Verify mechanism details you're <90% sure of.
3. **Storyboard** — list the chunks (5–9 for most topics): each chunk = one idea + its medium (from §3) + its interaction (if any). Check the novelty-reset rule across the sequence. The hook chunk comes first, the recap last.
4. **Set taste dials** — read `vendor/taste/taste-core.md` §0–§1 for the dial system. Explainer baseline: `VARIANCE 6 / MOTION 6 / DENSITY 3`. Adjust per emotional register and domain theme. Then apply taste-core's anti-default discipline, typography rules (§4 there), motion physics (§4 there), and AI-tells ban list (§9 there) to everything you build.
5. **Derive theme** (§4 below + `references/theming.md`).
6. **Build** from `assets/explainer-boilerplate.html` — it has the progress rail, chunk sections, reveal system, reduced-motion handling, checkpoint components, and recap card pre-wired. Extend it; don't rebuild scaffolding.
7. **Capture real media if needed** (§5 + `references/media-capture.md`) — screenshots via the capture script, video only when motion-of-a-real-interface IS the lesson.
8. **Pre-flight** (§6). Then ship the single HTML file.

Completeness rule: this skill inherits `vendor/taste/output-enforcement.md`. No `<!-- more chunks here -->`, no skeleton sections. Every storyboarded chunk ships fully built.

---

## 3. VISUAL GRAMMAR (concept shape → medium)

Full decision detail in `references/visual-grammar.md`. Fast map:

| Concept shape | Primary medium | Interaction pattern |
|---|---|---|
| FLOW | Animated SVG path / step-sequence with scrubber | Step-through buttons, scrub timeline |
| SYSTEM | Live canvas/SVG simulation with 1–3 knobs | Turn a knob, watch the loop respond |
| HIERARCHY | Zoomable nested boxes / indented tree with collapse | Click to descend a level |
| CHANGE | Animated chart (line/area) with time scrubber | Drag the time axis; toggle scenarios |
| COMPARISON | Side-by-side panels, synced interaction | One control drives both panels simultaneously |
| SCALE | Continuous zoom sequence / log-scale ladder | Scroll = zoom; familiar objects as rungs |
| MECHANISM | Cutaway diagram, layers toggle, x-ray slider | Drag an x-ray divider; fire one cycle on tap |
| PROBABILITY | Animated dot swarms (frequencies, not percentages) | Re-run the simulation button; adjust the prior |
| SYSTEM / FLOW above ~5 boxes | Computed-layout node diagram, static SVG | Lens switch, travelling marker along the path |

**Any diagram above ~5 boxes: read `references/system-diagrams.md` first.** Declare the graph as data, run the layered layout pass while authoring, paste the coordinates into static SVG. Never hand-type `x`/`y` for a real system, never ship a graph library, never use a force-directed layout. Budget 9 nodes per view (12 hard max) and split by altitude past that. Offer 3 to 5 lenses over the one layout, and a lens switch must never move a node.

Charts: hand-rolled SVG or Chart.js from CDN for anything beyond a sparkline. Sketch/artistic register (rough hand-drawn feel) is legitimate when the domain is human/organic — use SVG filters or rough.js from CDN, not when the domain is precision engineering. Dot swarms over pie charts, always, for probability — brains read frequencies, not percentages.

---

## 4. TOPIC-DERIVED THEMING (anti-generic mandate)

The user's explicit requirement: the explainer must feel like it belongs to *its topic*, not to a design system. Method (full palette/type recipes in `references/theming.md`):

1. **Extract the domain's native visual world**: ocean currents → deep blue-greens, fluid motion curves, caustic light. Compilers → monospace, terminal blacks, mechanical stepped motion. Baking → warm creams, rounded forms, rising/proving motion easing. Financial risk → ledger paper, restrained serifs, red/black conventions.
2. **One desaturated accent** drawn from that world (taste-core rule holds: no AI-purple, saturation < 80).
3. **Motion vocabulary from the domain's physics**: things in an ocean explainer drift and ease like water; things in an electronics explainer snap like switching. This is the strongest anti-generic lever — motion character, not color, is what makes it feel bespoke.
4. **Type pairing by register**: technical → grotesk + mono; organic/human → humanist sans or serif accent; historical → transitional serif display. Load from Google Fonts/Fontshare CDN.
5. Then run taste-core's AI-tells check (§9 there) against the result.

Emotional-register override: anxiety-adjacent topics (medical, financial distress, legal trouble) always get: calm neutral base, generous whitespace, no urgency-signaling reds except where semantically required, uncertainty explicitly labeled ("this varies — here's the range"), and zero gamification.

---

## 5. REAL MEDIA ESCALATION LADDER

Cheapest medium that teaches the idea wins. Escalate only when the previous rung genuinely can't carry the lesson:

1. **CSS/SVG animation** — default for flow, signaling, state change.
2. **Canvas simulation** — when the user should manipulate variables (SYSTEM/PROBABILITY shapes).
3. **Chart** — when the evidence IS the point.
4. **Real screenshots** — when the topic is a real interface/tool/website ("how OAuth consent screens work", "reading a Datadog flame graph"). Fabricated mock UI of a real product is a lie; capture the real thing with `scripts/capture-screenshot.mjs` (Playwright), then annotate ON the screenshot (numbered callouts, spotlight dimming) — annotation is what turns a screenshot into teaching.
5. **Recorded video** — RARE. Only when the lesson is literally temporal behavior of a real interface that stills + arrows can't convey (e.g. layout shift jank, a race condition flashing). Use `scripts/record-video.mjs`, keep it <15s, muted, looped, with a text caption of what to watch for. Embed as `<video>` with poster frame. If a 3-frame filmstrip of stills would teach the same thing — use the stills.

If capture tooling/network is unavailable in the environment, say so plainly and build the best rung below it. Never fake a "screenshot".

---

## 6. PRE-FLIGHT CHECK (all must pass before shipping)

**Truth**
- [ ] Every mechanism claim is one you'd defend; uncertain points are labeled, not smoothed over
- [ ] Every analogy's breaking point is stated

**Cognition**
- [ ] First viewport = hook (moving/surprising), not a definition
- [ ] No prose block > ~60 words; no chunk > one idea; progress rail present and honest
- [ ] Every key idea is dual-coded, labels spatially on the visual
- [ ] Interaction every 2–3 chunks; every animation user-controllable; no two same-format chunks adjacent
- [ ] Recap card: one-line analogy, vivid anchors, explain-it-back box, reality check, rabbit-holes drawer
- [ ] Zero text inputs; every control does something offline; nothing implies chat or a live answer unless a backend was actually wired (§1.12)

**Craft (taste-core inherited)**
- [ ] No AI-tells (taste-core §9); theme derived from topic, not template; dials declared
- [ ] `prefers-reduced-motion` fully handled; keyboard navigable; contrast AA
- [ ] Correct at 380px, in a ~700px panel, and at 1440px: no horizontal body scroll, nothing clipped or parked off-canvas, wide blocks scroll inside their own frame, no `vw` widths (§1.11)
- [ ] Single self-contained HTML file; CDN deps only; opens from disk with no build step

**Diagrams**
- [ ] Nothing above ~5 boxes was hand-placed; layout was computed and the coordinates baked in
- [ ] ≤9 nodes per view (12 hard max); every node has a role line; every edge shows protocol and sync vs async
- [ ] `title` + `desc` on every SVG; text-alternative table for anything above 6 nodes
- [ ] Lens switches move nothing; every non-obvious encoding has a legend in the same figure
- [ ] Every number asserted inside a figure was verified out of band

**Completeness**
- [ ] Every storyboarded chunk fully built (output-enforcement rules)
- [ ] `node scripts/lint-explainer.mjs <file.html>` passes (mechanical checks; it does not judge teaching)

---

## Reference files — when to read what

| File | Read when |
|---|---|
| `references/adhd-cognition.md` | First use of this skill; whenever tempted to violate a §1 rule |
| `references/explanation-patterns.md` | Structuring the storyboard; choosing analogy strategy; Feynman/pre-training/worked-example patterns |
| `references/visual-grammar.md` | Choosing/building the medium for a chunk; implementation recipes per concept shape |
| `references/system-diagrams.md` | Any diagram above ~5 boxes: layout algorithm, archetypes, lenses, node-to-node motion, budgets, diagram accessibility |
| `references/theming.md` | Deriving the topic theme; domain → palette/type/motion tables |
| `references/media-capture.md` | Any real screenshot or video work |
| `vendor/taste/taste-core.md` | Every build — dials, typography, motion physics, AI-tells, pre-flight |
| `vendor/taste/output-enforcement.md` | Every build — completeness rules |
| `vendor/taste/minimalist.md`, `soft.md`, `brutalist.md` | When the derived theme lands in that aesthetic family |
| `vendor/taste/brandkit.md`, `redesign.md` | When explaining inside an existing brand's world or reworking an existing explainer |