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.

Visuals are required. When this skill is loaded, the output must contain at least one primary visual artifact that carries real information, not just decorative styling around prose. Valid primary visuals include:

• an architecture, flow, sequence, state, ER, or dependency diagram
• a timeline, roadmap, or execution path visual
• a dashboard or KPI band with charts, bars, or status visual encoding
• a semantic HTML table for comparisons, audits, or inventories
• a walkthrough strip, stepper, or before/after comparison layout

If the page is a report, review, recap, audit, or plan analysis, include at least two visual forms:

• one structural visual: diagram, flow, architecture map, timeline, or dependency view
• one evidence visual: table, KPI dashboard, comparison panel, heatmap-style status grid, or other compact evidence display

Pure prose sections, even if well-designed, do not satisfy this requirement.

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.

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.

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, execution flow, code flow, sequence, data flow, schema/ER, state machine, mind map, data table, walkthrough, timeline, or dashboard. Each has distinct layout needs and rendering approaches (see Diagram Types below).

What aesthetic? Pick one and commit:

• Monochrome terminal (green/amber on black, monospace everything)
• Editorial (serif headlines, generous whitespace, muted palette)
• Blueprint (technical drawing feel, grid lines, precise)
• Neon dashboard (saturated accents on deep dark, glowing edges)
• Paper/ink (warm cream background, hand-drawn feel, sketchy borders)
• Hand-drawn / sketch (Mermaid handDrawn mode, wiggly lines, informal whiteboard feel)
• IDE-inspired (borrow a real color scheme: Dracula, Nord, Catppuccin, Solarized, Gruvbox, One Dark)
• Data-dense (small type, tight spacing, maximum information)
• Gradient mesh (bold gradients, glassmorphism, modern SaaS feel)

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 template before generating. Don't memorize it — read it each time to absorb the patterns.

• 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
• For interactive step-through walkthroughs, tutorials, concept explanations: read ./templates/walkthrough.html
• For dashboards, KPI summaries, metrics overviews: read ./templates/dashboard.html
• For timelines, roadmaps, milestone tracking: read ./templates/timeline.html
• For text-heavy architecture diagrams, or hybrid pattern (Mermaid overview + detail cards): read ./templates/architecture.html
• For non-editorial aesthetics, also read ./references/aesthetic-palettes.md for ready-made palettes.

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

For pages with 4+ sections (reviews, recaps, dashboards), also read the "Section Navigation" section in ./references/css-patterns.md for sticky sidebar TOC on desktop and horizontal scrollable bar on mobile.

Choosing a rendering approach:

Report composition rule. For reports, reviews, recaps, audits, and plan explainers, do not build a page that is mostly stacked text cards. Start by choosing the visual anchor first, then add supporting sections around it. The default shape is:

1. one hero visual near the top
2. one compact evidence section near the top half of the page
3. prose only after the visual model is established

Visual anchor rule. Put the main diagram, timeline, walkthrough, or dashboard in the first screenful when possible. If the most important thing on load is a paragraph, the page is under-visualized.

Visual fallback ladder. If the ideal diagram type is blocked by missing data or rendering limits, downgrade to the next best visual form instead of dropping to prose:

1. Excalidraw flowchart or Mermaid diagram
2. CSS architecture map / walkthrough / timeline
3. KPI dashboard plus semantic table
4. before/after comparison panels

Never skip the visual entirely.

For code-heavy pages (reviews, architecture docs), add Prism.js for syntax highlighting (see libraries.md).

Mermaid theming (fallback path): Use theme: 'base' with custom themeVariables so colors match your page palette. Use look: 'classic' unless the user asks for sketch style. Use layout: 'elk' for complex graphs (requires @mermaid-js/layout-elk — see ./references/libraries.md). Override Mermaid SVG classes with CSS for pixel-perfect control.

Mermaid zoom controls: Always add zoom controls (+/−/reset buttons) to every .mermaid-wrap container. Complex diagrams render at small sizes and need zoom to be readable. Include Ctrl/Cmd+scroll zoom on the container. Prefer CSS zoom over transform: scale() for static base scaling — see CSS Zoom section in css-patterns.md. See the zoom controls pattern in ./references/css-patterns.md and the reference template at ./templates/mermaid-flowchart.html.

AI-generated illustrations (optional). If surf-cli is available, generate images via surf gemini "prompt" --generate-image /tmp/ve-img.png --aspect-ratio 16:9, base64 encode, and embed as data URIs. Check with which surf; skip gracefully if unavailable. See ./references/css-patterns.md for image container styles.

3. Style

Apply these principles to every diagram:

Typography is the diagram. Pick a font pairing from the 5 named pairings in libraries.md and commit to it for the page:

1. DM Sans + Fira Code — clean, modern, distinctive (recommended default)
2. Instrument Serif + JetBrains Mono — refined editorial
3. IBM Plex Sans + IBM Plex Mono — technical, professional
4. Bricolage Grotesque + Fragment Mono — bold, characterful
5. Plus Jakarta Sans + Azeret Mono — rounded, approachable

Editorial default (Threaded/Medium-style): When the request asks for Medium/editorial aesthetics, default to Merriweather (content/heading) + Inter (UI/meta), slate-heavy palette, generous line-height, and restrained borders.

Forbidden as generic primary body font: Roboto, Arial, Helvetica. These are invisible defaults — they say "no design decision was made." Use only as system fallbacks in the font-family stack.

Load via <link> in <head>. Include a system font fallback in the font-family stack for offline resilience. The heading font should always have character — if you swapped it for Arial and nobody noticed, you haven't designed anything.

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. 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. The editorial default is flat white (#ffffff) — whitespace IS the atmosphere. For dark-first aesthetics, use subtle gradients or faint grid patterns. The background should feel intentional, not accidental.

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 <details>/<summary> 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.

Links are explicit. Never rely on browser default link colors. Style all <a> elements with color: var(--accent) and keep underlines. See the Link Styling section in css-patterns.md.

Animation earns its place. Use staggered fadeUp for cards, fadeScale for KPIs and badges, countUp for hero numbers. Always respect prefers-reduced-motion. CSS transitions and keyframes handle all cases.

Forbidden visual defaults — these make every AI-generated page look the same:

• Colors (as accent/primary in Mermaid themeVariables or CSS): #8b5cf6, #7c3aed, #6366f1 (indigo/violet — the Tailwind "AI purple"); #06b6d4, #22d3ee (cyan — overused in dark-mode AI dashboards); #ec4899, #f472b6 (magenta/pink — the gradient mesh cliche)
• Effects: Animated glowing shadows on cards; emoji as section headers or bullet points; three-dot code chrome (... buttons at the top of fake code windows); gradient text for headings
• Layouts: Uniform card grids where every card is the same size and weight — vary depth tiers; symmetric everything — visual weight should follow information hierarchy; identical spacing between all sections — hero sections get more breathing room

Prose quality — prose in generated pages must not read like AI wrote it:

• Forbidden vocabulary: delve, crucial, pivotal, landscape (abstract), tapestry, testament, intricate, interplay, leverage, utilize, facilitate, showcase, underscore, foster, Additionally. Replace with plain equivalents.
• No promotional language ("boasts", "renowned", "groundbreaking"), significance inflation, pseudo-profound flourishes, or generic conclusions ("The future looks bright").
• No filler phrases ("It's important to note", "In order to"), rule of three, inline-header bold lists as the only structural element, em dash overuse (>1 per paragraph), or contrastive negation ("Not just X, but Y").
• Be specific: numbers, file paths, function names — not "various components." Use short words: "use" not "utilize." Vary sentence rhythm. State what happened, not what it "represents."