name

visual-explainer

description

Generate beautiful, self-contained HTML pages that visually explain systems, code changes, plans, and data. Use when the user asks for a diagram, architecture overview, diff review, plan review, project recap, comparison table, or any visual explanation of technical concepts. Also use proactively when you are about to render a complex ASCII table (4+ rows or 3+ columns) — present it as a styled HTML page instead.

license

MIT

compatibility

Requires a browser to view generated HTML files. Optional surf-cli for AI image generation.

metadata

author	version
nicobailon	0.2.0

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.

Technology Stack

Every page uses:

Tailwind CSS v4 (browser CDN) — all styling via utility classes, no hand-rolled CSS
shadcn/ui design tokens (OKLCH) — neutral zinc base, semantic color pairs, automatic dark mode
Settings panel — floating gear button with theme toggle (Auto/Light/Dark) and font scale slider (80%-130%)

Optional per page:

ApexCharts v5 — bar, line, area, donut, radar, treemap, heatmap charts
Mermaid 11 — flowcharts, sequence, ER, state, mind map diagrams
PivotTable.js — interactive drag-and-drop pivot tables for data exploration
anime.js 3 — orchestrated animations for 10+ element sequences

See ./references/libraries.md for CDN URLs and usage patterns. See ./references/design-system.md for the complete token set, boilerplate, and component patterns.

Workflow

1. Think (5 seconds, not 5 minutes)

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 diagram? Architecture, flowchart, sequence, data flow, schema/ER, state machine, mind map, data table, timeline, or dashboard. Each has distinct rendering approaches (see Diagram Types below).

What personality? The design system provides the neutral foundation. Add personality through:

Font pairing: Pick from ./references/libraries.md. Legibility is paramount — the reader needs to gain understanding at a glance. Default to clean sans-serifs (DM Sans, Inter, Geist, Outfit). Only use display/serif fonts for headings when the content is light and editorial, never for data-dense pages.
Accent color: Override --chart-1 through --chart-5 and optionally --primary to set the page's accent. See Accent Color Customization in ./references/design-system.md.
Background atmosphere: Dot grid, subtle gradient, or radial glow. See Background Atmosphere in ./references/design-system.md.
Mermaid look: handDrawn for informal/whiteboard feel, classic for precise technical docs.

Vary accent colors and backgrounds between pages. Font choice should favor readability over novelty.

2. Read References

Read the reference template before generating. Don't memorize — read each time to absorb patterns.

For text-heavy architecture overviews: read ./templates/architecture.html
For flowcharts, sequence diagrams, ER, state machines, mind maps: read ./templates/mermaid-flowchart.html
For data tables, comparisons, audits, feature matrices: read ./templates/data-table.html

Always read ./references/design-system.md for the head boilerplate, token set, settings panel, and component patterns.

For pages with 4+ sections, also read ./references/responsive-nav.md for the sidebar TOC.

3. Build

Start with the head boilerplate from ./references/design-system.md. This gives you Tailwind v4, the full token set, anti-FOUC script, and CSP. Customize: title, Google Fonts link, accent colors.

Use Tailwind utility classes exclusively. No custom CSS properties for layout, spacing, colors, borders, shadows, or typography. The design system tokens (bg-background, text-foreground, border-border, etc.) handle all theming. The only CSS you write goes inside <style type="text/tailwindcss">:

The token definitions (from boilerplate)
Mermaid SVG overrides (from design-system.md)
PivotTable.js styling overrides (from design-system.md)
@apply rules for third-party elements

Card hierarchy signals importance. Use three depth levels from ./references/design-system.md:

L0 Flush for default content
L1 Raised for grouped sections
L2 Overlay for hero areas and popovers

Not every card should be elevated. When everything pops, nothing does.

Add the settings panel before </body>. Copy from ./references/design-system.md → Settings Panel section. This is mandatory on every page.

Stagger animations. Use animate-fade-up with style="--i:N" on sequential elements. Use animate-scale-in for KPI badges. Always respect prefers-reduced-motion (handled by the boilerplate).

Rendering Approach

Diagram type	Approach	Why
Architecture (text-heavy)	Tailwind Grid cards	Rich card content needs layout control
Architecture (topology)	Mermaid	Connections need automatic edge routing
Flowchart / pipeline	Mermaid	Auto node positioning and edge routing
Sequence diagram	Mermaid	Lifelines, messages, activation boxes
Data flow	Mermaid with edge labels	Connections + data descriptions
ER / schema	Mermaid	Relationship lines need auto-routing
State machine	Mermaid	Labeled transitions need auto layout
Mind map	Mermaid	Hierarchical branching
Data table	HTML `<table>` + Tailwind	Semantic markup, accessibility, copy-paste
Data exploration	PivotTable.js	Interactive pivot/group/filter
Timeline	Tailwind (central line + cards)	Simple linear layout
Dashboard	Tailwind Grid + ApexCharts	Card grid with embedded charts

Data Visualization

ApexCharts v5 for all charts. SVG-based, retina-crisp, built-in dark mode, live theme switching via the settings panel. Register charts with window.veCharts so theme toggles update them automatically. See ./references/design-system.md → ApexCharts Integration and ./references/libraries.md for chart type examples.

PivotTable.js for interactive data exploration. Drag-and-drop pivot UI with built-in aggregators. Style with @apply to match the design system. See ./references/design-system.md → Pivot Tables.

Mermaid 11 for diagrams. Always use theme: 'base' with themeVariables matched to the design tokens. Read theme from data-theme attribute (not prefers-color-scheme). Zoom controls on every diagram. See ./references/design-system.md → Mermaid Theme Integration and ./references/libraries.md for the full Mermaid guide.

AI-Generated Illustrations (optional)

If surf-cli is available, generate images via Gemini and embed as base64. Check with which surf.

surf gemini "descriptive prompt" --generate-image /tmp/ve-img.png --aspect-ratio 16:9
IMG=$(base64 -i /tmp/ve-img.png)   # macOS
# <img src="data:image/png;base64,${IMG}" alt="alt text" class="w-full rounded-xl">
rm /tmp/ve-img.png

Use for hero banners, conceptual illustrations, decorative accents. Skip when Mermaid or Tailwind handles it. Always degrade gracefully — pages must stand alone without images.

4. Deliver

Output location: Write to ~/.agent/diagrams/. Use descriptive filenames: modem-architecture.html, pipeline-flow.html, schema-overview.html.

Open in browser:

macOS: open ~/.agent/diagrams/filename.html
Linux: xdg-open ~/.agent/diagrams/filename.html

Tell the user the file path.

Diagram Types

Architecture / System Diagrams

Text-heavy overviews (card content matters more than connections): Tailwind Grid with cards. The reference template at ./templates/architecture.html demonstrates this pattern. Use when cards need descriptions, code references, tool lists.

Topology-focused (connections matter more than card content): Use Mermaid. graph TD or graph LR with themeVariables. Use when the point is showing how components connect.

Flowcharts / Pipelines

Use Mermaid. graph TD for top-down, graph LR for left-right. look: 'handDrawn' for sketch aesthetic.

Sequence Diagrams

Use Mermaid. sequenceDiagram syntax. Style via CSS overrides on .actor, .messageText.

Data Flow Diagrams

Use Mermaid. graph LR/TD with edge labels. Thicker edges for primary flows via classDef.

Schema / ER Diagrams

Use Mermaid. erDiagram syntax with entity attributes.

State Machines / Decision Trees

Use Mermaid. stateDiagram-v2 for states with labeled transitions.

Label caveat: Transition labels have a strict parser — colons, parentheses, <br/>, HTML entities cause silent failures. Use flowchart LR with quoted edge labels for complex labels.

Mind Maps

Use Mermaid. mindmap syntax for hierarchical branching.

Data Tables / Comparisons / Audits

HTML <table> with Tailwind classes. See ./templates/data-table.html.

Use proactively. Any time you'd render an ASCII table, generate HTML instead.

Patterns:

Sticky <thead> with sticky top-0
Alternating rows: even:bg-muted/30
Row hover: hover:bg-accent/50 transition-colors
Numeric columns: text-right tabular-nums
Status indicators: colored dot badges (see design-system.md → Status Badges), never emoji
<code> for technical refs: text-xs font-mono bg-muted px-1.5 py-0.5 rounded

Data Exploration

PivotTable.js for interactive pivot/group/filter. See ./templates/data-table.html for integration.

Timeline / Roadmap Views

Tailwind flexbox with a central line (border). Cards alternating left/right. Date labels on the line.

Dashboard / Metrics Overview

Tailwind Grid card layout. KPI cards with hero numbers (see design-system.md → KPI Cards). ApexCharts for charts. Sparklines via ApexCharts sparkline mode.

File Structure

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- Copy head boilerplate from design-system.md -->
  <!-- Customize: title, Google Fonts, accent colors -->
</head>
<body class="bg-background text-foreground min-h-screen p-10 max-md:p-4">
  <div class="max-w-5xl mx-auto space-y-8">
    <!-- Content with Tailwind utility classes -->
  </div>

  <!-- Settings panel (mandatory) — copy from design-system.md -->

  <!-- Optional: Mermaid, ApexCharts, anime.js scripts -->
</body>
</html>

Security

HTML Escaping

All dynamic content (commit messages, file contents, user input) must be HTML-escaped:

function escapeHtml(str) {
  return str.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;')
    .replace(/"/g,'&quot;').replace(/'/g,'&#039;');
}

Apply to: commit messages, file contents, Mermaid labels with user input, table cells with dynamic data, file paths and git output.

Exception: hardcoded labels, CSS values, numeric data from trusted sources.

Path Sanitization

function sanitizeFilename(name) {
  return name.replace(/[^a-zA-Z0-9-_]/g,'-').replace(/\.\.+/g,'')
    .replace(/^-+|-+$/g,'').substring(0,100) + '.html';
}

Always validate the final path stays within ~/.agent/diagrams/.

Content Security Policy

Included in the head boilerplate. Allows scripts from self, jsDelivr CDN, and inline. Allows styles from self, Google Fonts, and inline. Allows fonts from Google Fonts. Allows images from self and data: URIs.

Quality Checks

Before delivering:

Settings panel works: Theme toggle switches light/dark/auto. Scale slider scales all text. Settings persist on reload.
Both themes look intentional: Toggle between light and dark. Neither should feel broken or like an afterthought.
Information completeness: Does the diagram convey what the user asked for? Pretty but incomplete is a failure.
No overflow: Resize to different widths. Cards need min-w-0. Tables need overflow-x-auto wrappers.
Mermaid zoom controls: Every diagram has +/−/reset buttons and Ctrl/Cmd+scroll zoom.
Charts respond to theme: Toggle theme and verify ApexCharts update.
Animations: Elements stagger in on load. Reduced motion is respected.
File opens cleanly: No console errors, no broken font loads, no layout shifts.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Visual Explainer

Technology Stack

Workflow

1. Think (5 seconds, not 5 minutes)

2. Read References

3. Build

Rendering Approach

Data Visualization

AI-Generated Illustrations (optional)

4. Deliver

Diagram Types

Architecture / System Diagrams

Flowcharts / Pipelines

Sequence Diagrams

Data Flow Diagrams

Schema / ER Diagrams

State Machines / Decision Trees

Mind Maps

Data Tables / Comparisons / Audits

Data Exploration

Timeline / Roadmap Views

Dashboard / Metrics Overview

File Structure

Security

HTML Escaping

Path Sanitization

Content Security Policy

Quality Checks

FilesExpand file tree

SKILL.md

Latest commit

History

SKILL.md

File metadata and controls

Visual Explainer

Technology Stack

Workflow

1. Think (5 seconds, not 5 minutes)

2. Read References

3. Build

Rendering Approach

Data Visualization

AI-Generated Illustrations (optional)

4. Deliver

Diagram Types

Architecture / System Diagrams

Flowcharts / Pipelines

Sequence Diagrams

Data Flow Diagrams

Schema / ER Diagrams

State Machines / Decision Trees

Mind Maps

Data Tables / Comparisons / Audits

Data Exploration

Timeline / Roadmap Views

Dashboard / Metrics Overview

File Structure

Security

HTML Escaping

Path Sanitization

Content Security Policy

Quality Checks