#explainers #interactive-articles #distill #html-canvas

Creating Explainers

Use when creating an interactive explainer - a single self-contained HTML page with hand-built Canvas figures. Handles source-file explainers, topic-driven r...

Akash Tandon@analyticalmonk

Install

openclaw skills install @analyticalmonk/creating-explainers

Creating Explainers

Overview

This skill produces a single self-contained interactive explainer in the style of distill.pub - serif typography, a sticky two-column layout, and hand-built Canvas figures the reader can interact with. The output is one index.html file that opens directly in a browser; no parent project, no build step, no shared infrastructure required.

Core constraints (non-negotiable):

Zero dependencies. No npm, no bundler, no React, no D3, no Three.js, no Tailwind. Vanilla HTML + inline CSS + vanilla JS only.
One file per article. All CSS in a single <style> block in <head>; all JS at the bottom of <body>. The only external network requests are Google Fonts.
Hand-coded Canvas figures, not SVG libraries or images. 3D uses custom projection + z-sorting + lighting (see references/figure-archetypes.md).
The voice matters as much as the visuals. Conversational, second-person, analogy-rich. Read references/voice-and-style.md before drafting prose.

If you find yourself reaching for a framework or asking "should I just use React for this", stop. The constraint is the point.

When to Use

Use whenever the user asks to:

Turn a paper, blog post, transcript, or research report into a walkthrough
Build a distill-style or interactive explainer on any topic
"Explain X" with figures the reader can interact with

Don't use for:

Static blog posts with no interactivity (just write HTML)
Slide decks or presentations
Documentation sites or landing pages
Anything that needs a build step or framework
Explaining a codebase or source files - use explaining-codebases

Intake: Gather Your Source Material

Intake is one phase: gather what the article is built from. The material can be given files, web research, or both. Pick the references that apply and read them when you reach this phase, not upfront.

You have	Read	Source of truth
Files (paper, URL, paste, transcript, report)	`references/intake-from-files.md`	The provided document(s)
Only a topic	`references/intake-from-research.md`	Web research, then synthesis
Files and a topic that needs more	both	Files as spine, research as supporting

Mixed intake. When the user provides files and the topic also needs material the files do not cover (recent developments, criticisms, corroboration), read both references and combine them via spine-vs-supporting. Synthesize across everything into one outline and one article.

If you only have a topic and web search is unavailable, ask the user to paste sources. Do not write a technical interactive explainer from training data alone.

Workflow

The interactive explainer is too rich to one-shot. Work in stages and check in with the user.

text

1. Intake                   -> gather material (files, research, or both)
2. Research-time fact-check -> if you researched, verify sources before drafting (REQUIRED)
3. Outline                  -> propose sections + figure list, get user approval
4. Scaffold                 -> copy template, fill metadata
5. Prose pass               -> write all sections with figure placeholders
6. Figures pass             -> implement each interactive figure
7. Post-draft fact-check    -> audit every claim against its source (REQUIRED, blocking)
8. Polish                   -> run the Quality Checklist to completion

Pause for user approval after the outline (step 3). This is the highest-leverage check-in - if the outline is wrong, everything after it is wasted work. Show the user: title, subtitle, section list with one-line summaries, and a numbered figure list with what each figure shows and how the reader interacts with it.

Steps 2 and 7 are gates, not suggestions. Use fact-checking-explainers. The interactive explainer is not done until the post-draft fact-check returns zero unresolved claims - every checkable claim is supported. See the Quality Checklist.

Step 8 is complete only when every Quality Checklist item passes. Fix any failing item before delivery.

Don't pause between the other steps unless something is genuinely ambiguous. Show progress, don't ask for permission to keep working.

The Article Skeleton

Every article has the same skeleton. Use assets/article-template.html as the starting point - copy it to the output path and fill in the marked {{PLACEHOLDERS}}. Don't try to rebuild this structure from scratch; it captures invariants (DPR-aware canvas init, sidebar scroll-tracking, responsive breakpoints) that are easy to get wrong.

The skeleton provides:

Two-column layout: 220px sticky sidebar + 720px max content column
Article header (overline, h1, italic subtitle, meta line, fade-in animations)
Section anchors and a sidebar TOC that highlights the section in view
A figure HTML pattern with label, canvas-wrap, controls, and caption
The initCanvas() utility (DPR-scaled, returns CSS dimensions)
Responsive collapse at 1060px (sidebar hides) and 600px (mobile)
An optional article footer for attribution / source links (delete if not needed)

See references/template-walkthrough.md for what every block in the template does and where to fill in your content.

Figures

Each interactive figure is a self-contained IIFE:

javascript

(function() {
  const { canvas, ctx, w, h } = initCanvas('canvas-myfig');
  let state = { /* ... */ };
  function draw() { /* render */ }
  function step() { /* advance state */ }
  document.getElementById('myfig-step').addEventListener('click', () => { step(); draw(); });
  draw();
})();

State lives in closure variables, not globals. There's exactly one shared utility: initCanvas(id), defined once near the top of the script block.

Most figures fall into one of a few archetypes. Pick the closest and adapt:

Stepped simulation (gravity, physics, agent rollout) - state advances on Step button or via setInterval Play
Continuous animation (flowing particles, pulsing nodes, rotating diagrams) - requestAnimationFrame loop with time accumulator
Tabbed comparison (side-by-side variants the reader switches between)
3D rotation (custom projection, z-sorted faces, mouse drag + wheel zoom + touch)
Parameter exploration (sliders or buttons that retune a model and re-render)

Code templates and the math for each are in references/figure-archetypes.md. Read it when implementing a figure - the 3D archetype in particular has subtle correctness issues (back-face culling sign, painter's algorithm tie-breaks) that the reference handles.

Aim for 3-5 figures per interactive explainer. Fewer feels under-baked; more diffuses focus. Each figure should pay off something the prose has just set up - no "decorative" figures.

Voice

Read references/voice-and-style.md before writing prose. Quick reminders:

Second person, conversational, technical-but-accessible
Short-to-medium paragraphs (80-180 words). No bullet lists in body prose - narrate instead
Open with a concrete scene or tension, not a definition
Every figure caption explains what to look for, not just what it is. Bold the key term the reader should track
Use .callout for "the key insight" moments (sparingly, 3-5 per article)
Use .epigraph for one or two quoted lines from the source
Never use em-dashes (—) - use regular hyphens or rewrite the sentence

Quality Checklist

Before declaring the article done, verify:

Fact-check passed (blocking). Ran fact-checking-explainers on the finished article; every checkable claim is supported by its cited source (or the real code), with zero unresolved unsupported or contradicted claims. This gate must pass before delivery.
index.html is fully self-contained (no external CSS/JS files in the new directory)
Every figure renders without console errors
Sidebar TOC entries match the <h2 id="..."> anchors and scroll-tracking highlights the section in view
On mobile widths (resize browser to ~500px), the sidebar hides and figures scroll horizontally rather than squashing
All interactive controls (buttons, sliders) have visible labels and respond to clicks
Captions name the moving parts the reader should watch
No em-dashes anywhere in the file

The "test it locally" step is python3 -m http.server 8000 from the directory containing the file, then open it in a browser. If you have browser tooling available, do this. If you don't, at minimum grep for common bugs: getElementById calls without matching IDs, canvas IDs referenced before declaration, initCanvas not defined.

Common Mistakes

Mistake	Why it happens	Fix
Reaches for React/Vue/D3	Default frontend habits	Re-read the constraint - vanilla only, IIFE pattern
Generates a single huge file in one shot	Trying to be efficient	Outline first, get approval, then build progressively
Figures are decorative, not load-bearing	Figures added "because explainers have figures"	Each figure must illustrate something the prose just set up. If it doesn't, cut it
Voice reads like documentation	Defaulting to neutral/expository tone	Read `voice-and-style.md`, rewrite for second-person and concrete scenes
Uses em-dashes	LLM default punctuation	Search the file for `—` and replace before delivering
Captions describe what the figure is	Easy to write, low value	Captions should tell the reader what to look for and bold the key term
Hard-codes canvas pixel sizes without DPR scaling	Skipping `initCanvas()`	Always use the shared utility - blurry canvases on retina is the symptom

Reference Files

Read these as needed during the workflow - don't load them all upfront.

assets/article-template.html - the starting skeleton, copy this into the new article directory
references/template-walkthrough.md - what every block in the template does
references/figure-archetypes.md - code patterns for the common figure types
references/voice-and-style.md - writing patterns, paragraph examples, callout/epigraph usage
references/color-palettes.md - accent color sets per article, how to pick a palette
references/intake-from-files.md - extracting structure from a provided paper, blog post, or transcript
references/intake-from-research.md - web research workflow when only a topic is given

Related skills:

fact-checking-explainers - REQUIRED gate at research-time and before delivery
explaining-codebases - use instead of this skill when the subject is a codebase or source files