luanmorenommaciel/agentspec/visual-explainer

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 ${CLAUDE_PLUGIN_ROOT}/commands/visual-explainer/. 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.

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:

Mermaid theming: Always use theme: 'base' with custom themeVariables so colors match your page palette. Use layout: 'elk' for complex graphs (requires the @mermaid-js/layout-elk package — see ./references/libraries.md for the CDN import). Override Mermaid's SVG classes with CSS for pixel-perfect control. See ./references/libraries.md for 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 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 <br/> inside quoted labels. Never use escaped newlines like \n (Mermaid renders them as literal text in HTML output). Example: A["Copilot Backend<br/>/api + /api/voicebot"].

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 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)