Visual Explainer

Look

Aim for the standard of the best research and engineering pages: exact, calm, visual, and specific to the subject. The reader should feel that someone who understands the system drew every line on purpose, for this topic and no other.

Always read references/style-guide.md before HTML. Precedence: the user's words → the project's design system → the style guide.

content ──► register ──────────► subject ──► topic motif (2–3 touches)
reviews, metrics   Instrument    Geist · near-black · amber        accent hue from the subject
architecture       Blueprint     IBM Plex · blue-black grid        stage texture · glyphs
concepts, reading  Paper         Newsreader + Atkinson · ink blue  one type habit of the domain
recaps, decks      Editorial     Instrument Serif + Sans           the domain's diagram convention

• Set it like a good magazine. A 12-column grid with one flush-left axis. Few type sizes with big jumps. Real typographic characters. Charts labeled directly, each with one annotation. The style guide's Typography, Layout, and Figures sections hold the rules.
• Quiet ground, one signal. Neutrals carry the page. The accent marks only what the reader must look at now.
• Craft is part of the meaning. Raised nodes on a dot-grid stage, shapes that say what a thing is, a halo on the focal element, a glow on the hot path, the number leading the headline. Each effect points at something.
• The figure is the interface. Prose terms and figure elements light up together. Overview first, detail on demand.
• Motion shows change or flow. Blocks rise in once, numbers count up, dots move along edges at the real rate. No parallax, scroll-jacking, or decorative loops. Under reduced motion, show the final state.
• Stay on the scale. No sizes, gaps, radii, or colors outside the style guide.
• Two schemes: tokens on :root, and prefers-color-scheme redefines tokens only.
• Never: Inter, Roboto, Arial, or system-ui as the only font; violet or fuchsia Tailwind accents; neon; glassmorphism; gradient text, backgrounds, or blobs; clip-art, mascots, or emoji markers; centered everything; an accent bar on a rounded card; 01/02/03 when order does not matter.
• Reading comfort: html{font-size:17px}, rem elsewhere. Body ≥ 16px, labels ≥ 12px, SVG labels ≥ 12px as rendered. 45–68ch, left-aligned. Text ≥ 4.5:1, lines ≥ 3:1. Italics and uppercase only for a few words. One focal point per viewport. Show position (2 / 5, section nav). Slides keep their clamp() px scale.
• Themes: switchable themes or fonts, or a named palette (Dracula, Nord…) → references/themes.md.

Known traps

• Set min-width:0 on grid/flex children, grid-template-columns:minmax(0,1fr) on single-column grids, and overflow-wrap:anywhere on paths. Put wide tables, code, and SVG in a scroll container.
• Do not put display:flex on <li> when its markers matter.
• If the user asks for Mermaid: theme:'base' with themeVariables read from getComputedStyle (Mermaid cannot read CSS variables), re-rendered on a theme or font switch. Quote labels that hold punctuation; <br/>, not \n. Natural size in a scroll box, never shrunk to fit. No page class named .node, .label, .nodeLabel, .edgeLabel, .cluster, .marker, .note, .actor, or .commit; Mermaid uses them. For zoom and pan, copy templates/mermaid-flowchart.html from Older recipes.
• Wrap history.replaceState in try/catch. It throws on file:// pages.
• Add section navigation (sticky TOC with scroll-spy) only for 4+ sections.
• Respect prefers-reduced-motion: copy the template's .js-motion pattern, so the final state shows without JS, in print, and under reduced motion.

Animate

When the user asks for an animated explainer or a video:

• Default: an HTML scene player. SVG scenes with play, pause, scrub, and captions, all in one file. See references/diagrams.md.
• Video file (/generate-video, MP4, "make a video"): read references/video.md. Build a video deck and render it with visual-explainer-video (or npx -y -p visual-explainer -p playwright-core visual-explainer-video when it or playwright-core is not installed). Narrate only when a speech API key is set; otherwise the video is silent with captions. To record a live web app, follow its tutorial section.
• Script first. One claim per scene, a sentence or two of narration, and the picture changes with every sentence.

Slides and PPTX

Make slides only when asked (/generate-slides, --slides). Read references/slides.md. Export PPTX only on request or with --pptx: build the HTML deck first, then run visual-explainer-pptx deck.html deck.pptx (or node ./pptx/export.mjs from a checkout). Tell the user that HTML stays the source of truth. The PPTX has no animation, navigation, responsive layout, custom fonts, live diagrams, or JS.

Images

Optional. If surf or another image tool is available, you can embed generated images as base64 for a hero or concept art. Never use images for data or structure. The page must work without them.

Older recipes (optional)

Longer how-to files from v0.11.0, outside this skill. Fetch one only when you need its mechanics: https://raw.githubusercontent.com/nicobailon/visual-explainer/v0.11.0/plugins/visual-explainer/ + references/css-patterns.md (layout and CSS animation recipes) · references/libraries.md (Chart.js, anime.js, font pairs) · references/responsive-nav.md (sticky TOC with scroll-spy) · references/slide-patterns.md (slide layouts, transitions) · templates/architecture.html · templates/data-table.html · templates/mermaid-flowchart.html. They predate this guide: take the mechanics, keep this guide's look and rules.

Before delivery

□ one complete HTML file at the path; opens with no console errors
□ first viewport: main idea as a picture + one sentence
□ figures outnumber prose paragraphs; the lead and prose are short enough that the pictures carry the page
□ every number has a picture; scenarios are small multiples, not a sentence table
□ topic motif: 2–3 touches taken from the subject; page still reads without them
□ each figure: <figure> + "Fig. N" claim figcaption; role="img" + aria-label on the drawing
□ key terms linked with data-ref where hovering helps
□ no horizontal overflow at 1280px or 390px wide
□ both color schemes work (or one theme was deliberate)
□ type in rem; body ≥16px, labels ≥12px; all text ≥4.5:1 in both schemes; visible keyboard focus
□ headings state takeaways; paragraphs stay short
□ every size, gap, and radius is on the style-guide scale; polish pass done
□ typography: real dashes, minus, ×, curly quotes; no-break space before units; tabular figures in data
□ layout: one flush-left axis, consistent section openers, varied rhythm; blurred, each screen still shows one dominant element
□ register fonts and neutrals used exactly; would not pass for a generic dark/violet template
□ slides: each fits, nav chrome works, all source items covered, delivery check passes