Visual Explainer Generate self-contained HTML files for technical diagrams, 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, 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 Pi, these are slash commands ( /diff-review ). In Claude Code, namespaced ( /visual-explainer: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 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 PM seeing the big picture? A team reviewing a proposal? 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, 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) — see websocket-implementation-plan.html for reference Editorial (serif headlines like Instrument Serif or Crimson Pro, generous whitespace, muted earth tones or deep navy + gold) Paper/ink (warm cream

faf7f5

background, terracotta/sage accents, informal feel) 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 (small type, tight spacing, maximum information, muted colors) 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: 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 HTML

.
It renders but has no zoom/pan controls — diagrams become tiny and unusable. Always use the full
diagram-shell
pattern from
templates/mermaid-flowchart.html
: the HTML structure (
.diagram-shell
>
.mermaid-wrap
>
.zoom-controls
+
.mermaid-viewport
>
.mermaid-canvas
), the CSS, and the ~200-line JS module for zoom/pan/fit. Copy it wholesale.
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


inside quoted labels. Never use escaped newlines like
\n
(Mermaid renders them as literal text in HTML output). Example:
A["Copilot Backend
/api + /api/voicebot"]
.
Mermaid CSS class collision constraint:
Never define
.node
as a page-level CSS class. Mermaid.js uses
.node
internally on SVG

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
# 
rm
/tmp/ve-img.png
See
./references/css-patterns.md
for image container styles (hero banners, inline illustrations, captions).
When to use:
Hero banners that establish the page's visual tone. Conceptual illustrations for abstract systems that Mermaid can't express (physical infrastructure, user journeys, mental models). Educational diagrams that benefit from artistic or photorealistic rendering. Decorative accents that reinforce the aesthetic.
When to skip:
Anything Mermaid or CSS handles well. Generic decoration that doesn't convey meaning. Data-heavy pages where images would distract. Always degrade gracefully — if surf isn't available, skip images without erroring. The page should stand on its own with CSS and typography alone.
Prompt craft:
Match the image to the page's palette and aesthetic direction. Specify the style (3D render, technical illustration, watercolor, isometric, flat vector, etc.) and mention dominant colors from your CSS variables. Use
--aspect-ratio 16:9
for hero banners,
--aspect-ratio 1:1
for inline illustrations. Keep prompts specific — "isometric illustration of a message queue with cyan nodes on dark navy background" beats "a diagram of a queue."
3. Style
Apply these principles to every diagram:
Typography is the diagram.
Pick a distinctive font pairing from the list in
./references/libraries.md
. Every page should use a different pairing from recent generations.
Forbidden as
--font-body
:
Inter, Roboto, Arial, Helvetica, system-ui alone. These are AI slop signals.
Good pairings (use these):
DM Sans + Fira Code (technical, precise)
Instrument Serif + JetBrains Mono (editorial, refined)
IBM Plex Sans + IBM Plex Mono (reliable, readable)
Bricolage Grotesque + Fragment Mono (bold, characterful)
Plus Jakarta Sans + Azeret Mono (rounded, approachable)
Load via

in

. Include a system font fallback in the
font-family
stack for offline resilience.
Color tells a story.
Use CSS custom properties for the full palette. Define at minimum:
--bg
,
--surface
,
--border
,
--text
,
--text-dim
, and 3-5 accent colors. Each accent should have a full and a dim variant (for backgrounds). Name variables semantically when possible (
--pipeline-step
not
--blue-3
). Support both themes.
Forbidden accent colors:
#8b5cf6
#7c3aed
#a78bfa
(indigo/violet),
#d946ef
(fuchsia), the cyan-magenta-pink combination. These are Tailwind defaults that signal zero design intent.
Good accent palettes (use these):
Terracotta + sage (
#c2410c
,
#65a30d
) — warm, earthy
Teal + slate (
#0891b2
,
#0369a1
) — technical, precise
Rose + cranberry (
#be123c
,
#881337
) — editorial, refined
Amber + emerald (
#d97706
,
#059669
) — data-focused
Deep blue + gold (
#1e3a5f
,
#d4a73a
) — premium, sophisticated
Put your primary aesthetic in
:root
and the alternate in the media query:
/* Light-first (editorial, paper/ink, blueprint): */
:root
{
/* light values */
}
@media
(
prefers-color-scheme
:
dark
)
{
:root
{
/* dark values */
}
}
/* Dark-first (neon, IDE-inspired, terminal): */
:root
{
/* dark values */
}
@media
(
prefers-color-scheme
:
light
)
{
:root
{
/* light values */
}
}
Surfaces whisper, they don't shout.
Build depth through subtle lightness shifts (2-4% between levels), not dramatic color changes. Borders should be low-opacity rgba (
rgba(255,255,255,0.08)
in dark mode,
rgba(0,0,0,0.08)
in light) — visible when you look, invisible when you don't.
Backgrounds create atmosphere.
Don't use flat solid colors for the page background. Subtle gradients, faint grid patterns via CSS, or gentle radial glows behind focal areas. The background should feel like a space, not a void.
Visual weight signals importance.
Not every section deserves equal visual treatment. Executive summaries and key metrics should dominate the viewport on load (larger type, more padding, subtle accent-tinted background zone). Reference sections (file maps, dependency lists, decision logs) should be compact and stay out of the way. Use
/

for sections that are useful but not primary — the collapsible pattern is in
./references/css-patterns.md
.
Surface depth creates hierarchy.
Vary card depth to signal what matters. Hero sections get elevated shadows and accent-tinted backgrounds (
ve-card--hero
pattern). Body content stays flat (default
.ve-card
). Code blocks and secondary content feel recessed (
ve-card--recessed
). See the depth tiers in
./references/css-patterns.md
. Don't make everything elevated — when everything pops, nothing does.
Animation earns its place.
Staggered fade-ins on page load are almost always worth it — they guide the eye through the diagram's hierarchy. Mix animation types by role:
fadeUp
for cards,
fadeScale
for KPIs and badges,
drawIn
for SVG connectors,
countUp
for hero numbers. Hover transitions on interactive-feeling elements make the diagram feel alive. Always respect
prefers-reduced-motion
. CSS transitions and keyframes handle most cases. For orchestrated multi-element sequences, anime.js via CDN is available (see
./references/libraries.md
).
Forbidden animations:
Animated glowing box-shadows (
@keyframes glow { box-shadow: 0 0 20px... }
) — this is AI slop
Pulsing/breathing effects on static content
Continuous animations that run after page load (except for progress indicators)
Keep animations purposeful: entrance reveals, hover feedback, and user-initiated interactions. Nothing should glow or pulse on its own.
4. Deliver
Output location:
Write to
~/.agent/diagrams/
. Use a descriptive filename based on content:
modem-architecture.html
,
pipeline-flow.html
,
schema-overview.html
. The directory persists across sessions.
Open in browser:
macOS:
open ~/.agent/diagrams/filename.html
Linux:
xdg-open ~/.agent/diagrams/filename.html
Tell the user
the file path so they can re-open or share it.
Diagram Types
Architecture / System Diagrams
Three approaches depending on complexity:
Simple topology (under 10 elements):
Use Mermaid. A
graph TD
with custom
themeVariables
produces readable diagrams with automatic edge routing.
Text-heavy overviews (under 15 elements):
CSS Grid with explicit row/column placement. Sections as rounded cards with colored borders and monospace labels. Vertical flow arrows between sections. The reference template at
./templates/architecture.html
demonstrates this pattern. Use when cards need descriptions, code references, tool lists, or other rich content that Mermaid nodes can't hold.
Complex architectures (15+ elements):
Use the
hybrid pattern
— a simple Mermaid overview (5-8 nodes showing module relationships) followed by detailed CSS Grid cards for each module's internals. This gives you visual topology AND readable details. The overview diagram uses module names with

tags for key function names. The cards below show full function lists with new/modified badges. Never try to cram 15+ elements into a single Mermaid diagram — it will render unreadably small even with zoom controls.
Flowcharts / Pipelines
Use Mermaid.
Automatic node positioning and edge routing produces proper diagrams with connecting lines, decision diamonds, and parallel branches — dramatically better than CSS flexbox with arrow characters. Prefer
graph TD
(top-down); use
graph LR
only for simple 3-4 node linear flows. Color-code node types with Mermaid's
classDef
or rely on
themeVariables
for automatic styling.
Sequence Diagrams
Use Mermaid.
Lifelines, messages, activation boxes, notes, and loops all need automatic layout. Use Mermaid's
sequenceDiagram
syntax. Style actors and messages via CSS overrides on
.actor
,
.messageText
,
.activation
classes.
Data Flow Diagrams
Use Mermaid.
Data flow diagrams emphasize connections over boxes — exactly what Mermaid excels at. Use
graph TD
(or
graph LR
for simple linear flows) with edge labels for data descriptions. Thicker, colored edges for primary flows. Source/sink nodes styled differently from transform nodes via Mermaid's
classDef
.
Schema / ER Diagrams
Use Mermaid.
Relationship lines between entities need automatic routing. Use Mermaid's
erDiagram
syntax with entity attributes. Style via
themeVariables
and CSS overrides on
.er.entityBox
and
.er.relationshipLine
.
State Machines / Decision Trees
Use Mermaid.
Use
stateDiagram-v2
for states with labeled transitions. Supports nested states, forks, joins, and notes. Decision trees can use
graph TD
with diamond decision nodes.
stateDiagram-v2
label caveat:
Transition labels have a strict parser — colons, parentheses,


, HTML entities, and most special characters cause silent parse failures ("Syntax error in text"). If your labels need any of these (e.g.,
cancel()
,
curate: true
, multi-line labels), use
flowchart TD
instead with rounded nodes and quoted edge labels (
|"label text"|
). Flowcharts handle all special characters and support


for line breaks. Reserve
stateDiagram-v2
for simple single-word or plain-text labels.
Mind Maps / Hierarchical Breakdowns
Use Mermaid.
Use
mindmap
syntax for hierarchical branching from a root node. Mermaid handles the radial layout automatically. Style with
themeVariables
to control node colors at each depth level.
Class Diagrams
Use Mermaid.
Use
classDiagram
syntax for domain modeling, OOP design, and entity relationships with typed properties and methods. Supports relationships: association (
-->
), composition (
*--
), aggregation (
o--
), and inheritance (
<|--
). Add multiplicity labels (e.g.,
"1" --> "*"
) and abstract/interface markers (
<>
,
<>
). For simple entity boxes without OOP semantics (no methods, no inheritance), prefer
erDiagram
instead — it produces cleaner output for pure data modeling.
C4 Architecture Diagrams
Use Mermaid flowchart syntax — NOT native C4.
Use
graph TD
with
subgraph
blocks for C4 boundaries. Native
C4Context
hardcodes sharp corners, its own font, blue icons, and inline SVG colors that ignore
themeVariables
— it always clashes with custom palettes.
Flowchart-as-C4 pattern:
Persons → rounded nodes
(("Name"))
, systems → rectangles
["Name"]
, databases → cylinders
[("Name")]
, boundaries →
subgraph
blocks, relationships → labeled arrows
-->|"protocol"|
. Use
classDef
+
:::className
to visually differentiate external systems (e.g., dashed borders). This inherits
themeVariables
,
fontFamily
, and CSS overrides like every other Mermaid diagram.
Data Tables / Comparisons / Audits
Use a real