Visual Explainer HTML Pages
Have Claude Code explain architectures, diffs and plans as self-contained HTML pages with labeled Mermaid diagrams and a deliberate design pass, instead of walls of chat text, terminal ASCII or generic AI-looking pages.
A 4-row comparison table or a system diagram dumped as chat text or bare ASCII forces the reader to reconstruct the visual structure in their head — and the fix isn't more words, it's recognizing when content is inherently visual and rendering it as a real, self-contained HTML page instead, with the same design discipline you'd apply to a real deliverable.
Who it's for: developers who want architecture diagrams, diff reviews, or project recaps rendered as real pages instead of chat walls, teams that want explanatory HTML output to avoid generic AI-generated design clichés (gradient heroes, violet accents, centered layouts), anyone building a Mermaid-heavy explanation who wants labeled, mechanism-showing diagrams instead of decorative boxes-and-arrows, engineers who need a light/dark-mode-correct token system for one-off explanatory pages
Example
"Explain this system architecture visually" → A content-appropriate representation chosen first (a Mermaid diagram for a data-flow-heavy architecture, CSS grid cards for a text-heavy module breakdown), a written design plan (named hex values, type roles, one-sentence layout concept) audited against generic AI-page tells before any HTML is written, and a self-contained page with labeled diagram arrows, a real light/dark token system, and zero gradient-hero or violet-accent clichés
CLAUDE.md Template
New here? 3-minute setup guide → | Already set up? Copy the template below.
npx ccplaybooks add visual-explainer-html# Visual Explainer (Self-Contained HTML)
Generate self-contained HTML pages that explain systems, code changes, plans, data, and technical concepts visually. Use for diagram requests, architecture overviews, diff/plan reviews, project recaps, comparison tables, slide decks, and any explanation that's inherently visual rather than a wall of prose.
## When to Prefer a Page Over Chat
Prefer an HTML page over terminal ASCII or a long chat message when the output is inherently visual. If a table would have 4+ rows or 3+ columns, render it as HTML and give only a short chat summary. The final page must be a complete, self-contained HTML document — embedded CSS, a self-contained favicon, and any needed JS, no external dependencies that could go missing later.
## Design Judgment (Before Writing Any HTML)
- **Calibrate treatment to the content.** Diff reviews, memos, audits, and recaps get polished-utilitarian: real hierarchy, considered spacing, no flashy hero. Showcases and narrative decks get editorial. A well-composed page is never wrong; an over-designed one sometimes is.
- **Precedence order:** the user's explicit words, then the project's existing design system (theme/token files, component styles) if one exists, then your own judgment last.Get new playbooks like this one
One email a week with new Claude Code workflows. Free, like everything here.
No spam. Unsubscribe anytime.
What This Does
A design-first workflow for generating self-contained HTML pages to explain systems, code changes, plans, and data — triggered specifically when content is inherently visual (a comparison table with four-plus rows, an architecture with real structure, a multi-step process) rather than defaulting to chat prose or terminal ASCII for everything. Before any HTML gets written, it forces an explicit design pass: pick 4–6 named hex values, type roles, and a one-sentence layout concept, then audit that plan against the question "would I produce this same plan for any similar page?" — catching and revising the generic parts (slate-and-indigo, Inter, a hero-plus-three-cards layout) in favor of something that actually fits the content's domain (a CLI recap gets a terminal-inspired amber-on-near-black treatment instead).
For diagrams specifically, it enforces Mermaid invariants that separate a genuinely informative diagram from decoration: depict the actual mechanism rather than a labeled box, put a real label on every arrow instead of an unlabeled line that only says "related somehow," and match complexity to what the decision or explanation actually turns on. A full set of layout and style invariants covers a correct CSS-custom-property token system for pages that need to support both light and dark mode, a rem-based type scale with one root-level knob, and — notably — an explicit list of the generic AI-generated-page tells to avoid entirely: gradient-mesh blobs, violet/fuchsia default accents, centered-everything layouts, and emoji section markers among them.
Quick Start
Step 1: Create a Project Folder
mkdir visual-explainer && cd visual-explainer
Step 2: Download the Template
Click Download above, then:
mv ~/Downloads/CLAUDE.md ./
Step 3: Generate a Visual Explanation
claude
Ask Claude to explain a system, review a diff or plan visually, or turn a comparison into a proper page instead of a chat table. It will pick the right representation (Mermaid, CSS cards, a timeline), write and self-audit a design plan first, then produce a complete, self-contained HTML file.
A Worked Example: Explaining a Cache Layer
Say you ask: "Explain how requests flow through our API's caching layer." Without this template you'd typically get a few paragraphs and maybe an ASCII box diagram. With it, Claude works through three decisions before writing any HTML:
- Representation. Request flow is mechanism-heavy, so it picks a Mermaid sequence or flow diagram, not a grid of cards.
- Design plan. A short written plan: four to six named hex colors, which typeface does what, and one sentence on layout. For an infrastructure topic that might be a dark, terminal-flavored palette with one warm accent for the cache-hit path. Claude then asks itself whether it would write the same plan for any other page, and revises whatever's generic.
- Diagram rules. Every arrow gets a label saying what happens along it, such as
GET /users/42,cache miss,read-through (TTL 300s)orinvalidate on write, so the diagram shows how the system behaves, not just which boxes connect.
The result is one .html file that you open in a browser, attach to a pull request, or drop into a design doc. Because it's self-contained, it renders the same on a reviewer's machine as on yours.
Good Prompts to Start With
- "Review this diff visually: what changed, what it affects, and what to test."
- "Compare these four queue libraries as a page, not a chat table."
- "Give me a one-page recap of what we built this week for the team."
If the answer is a sentence or two, the template should not produce a page. Its trigger is content that's inherently visual, so short answers stay in chat.
Tips & Best Practices
- Let the content's domain drive the aesthetic direction deliberately — a CLI/infra explanation calling for a terminal-inspired palette is a stronger choice than reaching for the same generic blue-and-slate treatment on every page regardless of subject.
- Label every Mermaid arrow with what actually happens along it (
writes,polls every 30s) — an unlabeled arrow is close to useless for someone trying to understand the actual mechanism, not just the topology. - Check the generic-defaults avoid-list explicitly before finalizing a page — violet/fuchsia accents, gradient-mesh blobs, and centered-everything layouts are specifically called out because they're the most common way an otherwise-good explanation ends up looking like every other AI-generated page.
Limitations
- A design methodology and set of invariants, not a rendering engine itself — actually building the referenced templates (architecture cards, slide-deck layouts, themed pickers) requires writing the HTML/CSS/JS by hand each time rather than pulling from a bundled template library.
- Best suited to a one-off or occasional explanatory page; a page meant to be maintained and updated repeatedly may be better served by a proper documentation site than a hand-composed self-contained HTML file.
- The Mermaid invariants assume Mermaid.js is an acceptable dependency for the page; an environment that can't load it needs the CSS-grid-cards fallback representation instead.
Related Playbooks
- Diagram & Flowchart Creator — when you need the diagram alone (Mermaid, PlantUML) to embed in existing docs
- HTML Presentation Builder — when the explanation should be a slide deck with speaker notes
- Artifacts Builder — for interactive, multi-component pages built with React and Tailwind