Explainer

Explainer

A signature visual-first HTML format. Dense, dark-themed, diagram-driven reference documents that compress complex systems into scannable visual sections. Each section is a custom inline-SVG diagram with a one-line caption — never a paragraph.

The rule

If a section is mostly prose, the skill is being misused. Every section must have a visualization that carries the meaning. Prose is captions. Captions are one sentence. If the meaning needs three sentences, the diagram is wrong.

Canonical example

See examples/sample-explainer.html in the pack — a complete, self-contained explainer demonstrating sections, SVG diagrams, and the aesthetic. That is the bar.

Workflow Routing

| Workflow | Trigger | File | |----------|---------|------| | Generate | "make an explainer", "build a visual doc", "explainer for X" | Workflows/Generate.md | | Revise | "revise section N of the explainer", "update the X section in {path}", "fix section N in explainer" | Workflows/Revise.md |

Tools

• Tools/verify.ts — pre-open gate. Checks HTML5 shape, viewBox on every renderable `, no duplicate id`s, and prose-creep per section. Run before opening.
• Tools/render.ts — substitutes {{KEY}} placeholders in Boilerplate.html from a JSON object (HTML-escaped by default; raw_ prefix for raw HTML). Accepts --theme= to pick a theme from Themes/. Default: anthropic.

References

• References/Philosophy.md — visual-first rules, anti-patterns, when to use what
• References/Aesthetic.md — CSS tokens, typography, spacing, color semantics
• References/Components.md — catalog of 15 reusable diagram patterns with code
• References/Boilerplate.html — ready-to-clone base template; CSS is structure-only and references token names (var(--bg), var(--accent), etc.) supplied by the selected theme

Themes

Five baked-in themes, each a single CSS file in Themes/. The structural rules (single chrome accent, color is semantic and lives in the data layer only, chrome retreats, diagrams over prose) are universal — themes only change the surface, ink, accent, data palette, font stack, and a few component-level details.

| Theme | Identity | Sample | |---|---|---| | anthropic | Default. Warm-tinted near-black, clay accent. | examples/samples/anthropic.html | | fragapane | Soft organic dark. Dusty rose accent, sentence-case kickers, generous whitespace, un-italic captions. | examples/samples/fragapane.html | | ft | Light. FT salmon paper, brand-red accent, density-heavy. Print inverts to dark. | examples/samples/ft.html | | bloomberg | Terminal. Pure black, brand yellow, mono-everywhere (the only theme that intentionally breaks the "mono for code only" rule). | examples/samples/bloomberg.html | | riso-zine | Light. Off-cream paper, fluorescent riso red, geometric display sans (Space Grotesk). Optional .halftone texture utility. | examples/samples/riso-zine.html |

Pick at generation time with --theme= on render.ts, or pass the theme into the Generate workflow.

Output destination

Default: ./explainers/{slug}.html (relative to the current working directory). Slug is kebab-case.

To override the default, set the environment variable EXPLAINER_OUT_DIR to an absolute or ~/-prefixed path (e.g. ~/explainers, ~/Documents/explainers). The skill resolves this at write time.

After writing, the workflow opens the file with the OS-native opener (xdg-open on Linux, open on macOS, start on Windows) when available; otherwise it prints the absolute path.

Examples

Example 1: Architecture reference

User: "Make an explainer for our auth pipeline"
→ Invokes Generate workflow
→ Outlines 8 sections (pipeline DAG, schema, decision tree, etc.)
→ Writes ./explainers/auth-pipeline.html
→ Opens in browser

Example 2: Decision comparison

User: "Build a visual doc comparing Postgres / SQLite / DuckDB for our use case"
→ Invokes Generate workflow
→ Produces side-by-side comparison + 2×2 fit matrix + tier fan-out
→ Writes ./explainers/db-comparison.html

Gotchas

• Prose creep. The most common failure: a section sneaks in 3–4 sentences because the diagram felt thin. If the meaning needs prose, the diagram is wrong — redesign the diagram, don't expand the caption.
• Light theme drift. Reviewers sometimes ask for "a lighter version." Refuse. The aesthetic is fixed; deviation breaks the format's identity.
• External assets. No `, , `, or CDN fonts. The doc must work offline and self-contained forever. System monospace + sans-serif stacks only.
• Generic labelled rectangles. If your "diagram" is boxes with text inside connected by arrows, you've drawn a PowerPoint slide, not an explainer. Each diagram must carry a structural insight from geometry, color, spatial relationships — not from reading text inside boxes.
• Fewer than 6 sections. The format expects density. If you can't justify 6 sections each carrying a real diagram, the topic probably wants a markdown doc instead.

Source & license

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

• Author: Angelopvtac
• Source: Angelopvtac/explainer-pack
• License: MIT

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