---

name: visual-explainer description: HTML explainers, diagrams, architecture, timelines, source maps, slide decks, comparison tables, recaps, plan and diff reviews. license: MIT compatibility: Requires a browser to view generated HTML files. Optional surf-cli for AI image generation. metadata: author: nicobailon (upstream); journalism adaptations by jamditis version: "0.7.4" upstream: https://github.com/nicobailon/visual-explainer

Visual explainer

Generate self-contained HTML files for technical diagrams, editorial visualizations, and data tables. Always open the result in the browser. Never fall back to ASCII art when this skill is loaded.

Proactive table rendering. When you're about to present tabular data as an ASCII box-drawing table in the terminal (comparisons, audits, feature matrices, status reports, source verification grids, any structured rows/columns), generate an HTML page instead. The threshold: if the table has 4+ rows or 3+ columns, it belongs in the browser. Don't wait for the user to ask, render it as HTML automatically and tell them the file path. You can still include a brief text summary in the chat, but the table itself should be the HTML page.

Available commands

Detailed prompt templates in ./commands/. In Claude Code, namespaced (/visual-explainer:diff-review). In Pi, these are slash commands (/diff-review). In Codex, use /prompts:diff-review (if installed to ~/.codex/prompts/) or invoke $visual-explainer and describe the workflow.

| Command | What it does | |---------|-------------| | generate-web-diagram | Generate an HTML diagram for any topic | | generate-visual-plan | Generate a visual implementation plan for a feature | | generate-slides | Generate a magazine-quality slide deck | | diff-review | Visual diff review with architecture comparison and code review | | plan-review | Compare a plan against the codebase with risk assessment | | project-recap | Mental model snapshot for context-switching back to a project | | fact-check | Verify accuracy of a document against actual code | | share-page | Deploy an HTML page to Vercel and get a live URL |

Workflow

1. Think (5 seconds, not 5 minutes)

Before writing HTML, commit to a direction. Don't default to "dark theme with blue accents" every time.

Visual is always default. Even essays, blog posts, and articles get visual treatment, extract structure into cards, diagrams, grids, tables.

Prose patterns (lead paragraphs, pull quotes, callout boxes) are accent elements within visual pages, not a separate mode. Use them to highlight key points or provide breathing room, but the page structure remains visual.

For prose accents, see "Prose Page Elements" in ./references/css-patterns.md. For everything else, use the standard freeform approach with aesthetic directions below.

Who is looking? A developer understanding a system? A reporter revisiting an investigation? An editor reviewing a story? A PM seeing the big picture? An academic auditing methodology? This shapes information density and visual complexity.

What type of content? Architecture, flowchart, sequence, data flow, schema/ER, state machine, mind map, class diagram, C4 architecture, data table, timeline, dashboard, source network, investigation map, editorial workflow, story structure, or prose-first page. Each has distinct layout needs and rendering approaches (see Diagram types below).

What aesthetic? Pick one and commit. The constrained aesthetics (Blueprint, Editorial, Paper/ink) are safer, they have specific requirements that prevent generic output. The flexible ones (IDE-inspired) require more discipline.

Constrained aesthetics (prefer these):

• Blueprint (technical drawing feel, subtle grid background, deep slate/blue palette, monospace labels, precise borders)
• Editorial broadsheet (serif headlines like Playfair Display or Crimson Pro, generous whitespace, muted earth tones or deep navy + gold)
• Paper and ink (warm cream #faf7f5 background, terracotta/sage accents, informal feel, good for newsroom features)
• Magazine feature (large display serif, off-axis composition, rich pull quotes, photo-led)
• Academic / research paper (Libre Baskerville or Source Serif, restrained palette, footnotes-style detail, generous margins)
• Newsroom board (cork/pushpin texture, handwritten-style notes, pinned-card layouts, for editorial planning, story maps)
• Investigation wall (red string aesthetic, connected entities, graph-paper background, monochrome with red accents, for relationship maps)
• Monochrome terminal (green/amber on near-black, monospace everything, CRT glow optional)

Flexible aesthetics (use with caution):

• IDE-inspired (borrow a real, named color scheme: Dracula, Nord, Catppuccin Mocha/Latte, Solarized Dark/Light, Gruvbox, One Dark, Rosé Pine), commit to the actual palette, don't approximate
• Data-dense / wire service (small type, tight spacing, maximum information, muted colors)
• Hand-drawn sketch (Mermaid look: 'handDrawn', casual annotations, for whiteboard/early-stage thinking)

Explicitly forbidden:

• Neon dashboard (cyan + magenta + purple on dark), always produces AI slop
• Gradient mesh (pink/purple/cyan blobs), too generic
• Any combination of Inter font + violet/indigo accents + gradient text

Vary the choice each time. If the last diagram was dark and technical, make the next one light and editorial. The swap test: if you replaced your styling with a generic dark theme and nobody would notice the difference, you haven't designed anything.

2. Structure

Read the reference material before generating. Don't memorize it, read it each time to absorb the patterns.

• For text-heavy architecture overviews (card content matters more than topology): read ./templates/architecture.html
• For flowcharts, sequence diagrams, ER, state machines, mind maps, class diagrams, C4: read ./templates/mermaid-flowchart.html
• For data tables, comparisons, audits, feature matrices, source verification grids: read ./templates/data-table.html
• For slide deck presentations (when --slides flag is present or /generate-slides is invoked): read ./templates/slide-deck.html and ./references/slide-patterns.md
• For prose-heavy publishable pages (READMEs, articles, blog posts, essays): read the "Prose Page Elements" section in ./references/css-patterns.md and "Typography by Content Voice" in ./references/libraries.md

For CSS/layout patterns and SVG connectors, read ./references/css-patterns.md.

For pages with 4+ sections (reviews, recaps, dashboards), also read ./references/responsive-nav.md for section navigation with sticky sidebar TOC on desktop and horizontal scrollable bar on mobile.

Choosing a rendering approach:

| Content type | Approach | Why | |---|---|---| | Architecture (text-heavy) | CSS Grid cards + flow arrows | Rich card content (descriptions, code, tool lists) needs CSS control | | Architecture (topology-focused) | Mermaid | Visible connections between components need automatic edge routing | | Flowchart / pipeline | Mermaid | Automatic node positioning and edge routing | | Sequence diagram | Mermaid | Lifelines, messages, and activation boxes need automatic layout | | Data flow | Mermaid with edge labels | Connections and data descriptions need automatic edge routing | | ER / schema diagram | Mermaid | Relationship lines between many entities need auto-routing | | State machine | Mermaid | State transitions with labeled edges need automatic layout | | Mind map | Mermaid | Hierarchical branching needs automatic positioning | | Class diagram | Mermaid | Inheritance, composition, aggregation lines with automatic routing | | C4 architecture | Mermaid | Use graph TD + subgraph for C4 (not native C4Context, it ignores themes) | | Data table / comparison / audit | HTML <table> | Semantic markup, accessibility, copy-paste behavior | | Timeline / chronology | CSS (central line + cards) | Simple linear layout doesn't need a layout engine | | Dashboard / metrics | CSS Grid + Chart.js | Card grid with embedded charts | | Source network | Mermaid or CSS Grid cards | Map relationships between sources in an investigation or story | | Editorial workflow | Mermaid flowchart | Story lifecycle from pitch through publish/distribute | | Investigation map | CSS Grid cards + Mermaid | Connect entities, documents, and events in investigative work | | Story structure | CSS Grid | Visualize narrative arc, sections, sourcing distribution before publication |

Mermaid theming. Always use theme: 'base' with custom themeVariables so colors match your page palette. Use layout: 'elk' for complex graphs (requires the locally bundled @mermaid-js/layout-elk package, see ./references/libraries.md). Override Mermaid's SVG classes with CSS for pixel-perfect control. See ./references/libraries.md for the full theming guide.

Mermaid containers. Always center Mermaid diagrams with display: flex; justify-content: center;. Add zoom controls (+/−/reset/expand) to every .mermaid-wrap container. Include the click-to-expand JavaScript so clicking the diagram (or the ⛶ button) opens it full-size in a new tab.

Never use bare <pre class="mermaid">. It renders but has no zoom/pan controls, diagrams become tiny and unusable. Always use the journalism mermaid-flowchart.html pattern: a .mermaid-wrap container with .zoom-controls (+/−/reset/expand buttons) wrapping a .mermaid element. The container's CSS handles overflow and pan affordances; the bundled JS wires zoom buttons, ctrl+scroll wheel zoom, click-and-drag panning, and click-to-expand into a new tab. Copy the template wholesale rather than reconstructing the pattern, and copy its sibling templates/vendor/ directory so the pinned Mermaid import remains resolvable.

Mermaid scaling. Diagrams with 10+ nodes render too small by default. For 10–12 nodes, increase fontSize in themeVariables to 18–20px and set INITIAL_ZOOM to 1.5–1.6. For 15+ elements, don't try to scale, use the hybrid pattern instead (simple Mermaid overview + CSS Grid cards). See "Architecture / system diagrams" below.

Mermaid layout direction. Prefer flowchart TD (top-down) over flowchart LR (left-to-right) for complex diagrams. LR spreads horizontally and makes labels unreadable when there are many nodes. Use LR only for simple 3–4 node linear flows. See ./references/libraries.md "Layout direction: TD vs LR".

Mermaid line breaks in flowchart labels. Use <br/> inside quoted labels. Never use escaped newlines like \n (Mermaid renders them as literal text in HTML output). Example: A["Pitch desk<br/>weekly intake"].

Mermaid CSS class collision constraint. Never define .node as a page-level CSS class. Mermaid.js uses .node internally on SVG <g> elements with transform: translate(x, y) for positioning. Page-level .node styles (hover transforms, box-shadows) leak into diagrams and break layout. Use the namespaced .ve-card class for card components instead. The only safe way to style Mermaid's .node is scoped under .mermaid (e.g., .mermaid .node rect).

AI-generated illustrations (optional). If surf-cli is available, you can generate images via Gemini and embed them in the page for creative, illustrative, explanatory, educational, or decorative purposes. Check availability with which surf. If available:

# Generate to a temp file (use --aspect-ratio for control)
surf gemini "descriptive prompt" --generate-image /tmp/ve-img.png --aspect-ratio 16:9

# Base64 encode for self-containment (macOS)
IMG=$(base64 -i /tmp/ve-img.png)
# Linux: IMG=$(base64 -w 0 /tmp/ve-img.png)

# Embed in HTML and clean up
# <img src="data:image/png;base64,${IMG}" alt="descriptive alt text">
rm /tmp/ve-img.png

See ./references/css-patterns.md for imag