Visual Explainer

Visual Explainer

Generate self-contained HTML files for technical diagrams, visualizations, and data tables. 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

Arguments

--style values. One flat namespace — the five design directions and the borrowed editor schemes are interchangeable values, no prefix:

An editor scheme sets the palette; it doesn't excuse skipping typography and layout decisions. --style nord still needs a font pairing and a considered structure.

--style never sets layout. Structure is the job of --slides and --handbook, and the two axes compose freely: --handbook --style nord is a document in the Nord palette. --style handbook is not a value — read it as --handbook, apply it as the mode, and say so.

Unknown --style value: don't silently fall back. Name the closest supported value, use it, and tell the user. neon and gradient-mesh are rejected outright (see Anti-Patterns) — substitute a constrained direction and say which.

With no flags, infer the aesthetic from audience and content, and vary it from the previous generation.

Style Picker

--picker selects a style; it does not generate a page. It short-circuits everything below — no reference files read, no HTML written.

Open ./assets/style-catalog.html, the prebuilt catalog that ships with the skill: one specimen card per --style value showing the palette at real hex values, the font pairing, and the flag to copy. Three tabs — Styles, Commands, Formats — landing on Styles, so name the other two when you hand it over or the user won't know they exist. Never regenerate or edit it to serve a picker request; open it where it lives. Its command cards mirror the Available Commands table above, and their section lists mirror each command's own "Diagram structure" block — so adding a command, or renumbering one's sections, means editing the catalog too.

Then print one line telling the user to reply with a style name or paste the copied flag. Done when the catalog is open and that line is printed — nothing else. A picker run ends at the selection: if a topic came with it, say it was ignored rather than generating once they answer.

The catalog is also the hex authority for the editor schemes. When honoring --style gruvbox and the rest, read its card rather than recalling the palette — that is a read of one file, not a picker run, and the Workflow proceeds normally.

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, read both halves: "Prose Accent Elements" in ./references/diagram-types.md for which accent a page has earned and when, and "Prose Page Elements" in ./references/css-patterns.md for the CSS that builds it. 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, implementation plan, longform documentation, or prose-first page. Each has distinct layout needs and rendering approaches — route via the table in §2, then read its section in ./references/diagram-types.md.

What aesthetic? Pick one value from the --style table in Arguments and commit. The constrained directions (blueprint, editorial, paper, terminal) carry visual requirements that crowd out generic output, so prefer them; the editor schemes are flexible and need more discipline to stay distinctive.

If --style / --palette / --font were passed, the choice is already made — honor the flags and skip this selection.

Neon dashboard and gradient mesh are slop — see Anti-Patterns for the full list before you commit.

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 — each time, not from memory. Name the files you read before you write any HTML; if you can't, you haven't done this step.

• 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 /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 documents (longform documentation, or --handbook): read ./templates/handbook.html — see Handbook Mode

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:

Is it even a chart? Ask before reaching for one. One to three numbers are KPI cards, not a bar chart with three bars. A two-point change is a sentence carrying the delta. A ranking of five things is a table with an inline bar column. A chart earns its space when the shape of the data — trend, distribution, part-to-whole, correlation — is the point.

Once you've picked the approach, read the matching section of ./references/diagram-types.md for the syntax, caveats, and CSS override classes for that type.

If the page contains any Mermaid diagram, read ./references/mermaid-rules.md first. It covers the two failures — the blow-up that renders a diagram unreadably small, and the drift that paints labels outside their own boxes — plus the container, config, theming, labels, and the .node collision.

3. Style

The forbidden half of every rule below lives in one place: Anti-Patterns. Read it before you write CSS.

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.

Good pairings (use these):

• DM Sans + Fira Code (technical, precise)
• Crimson Pro + Noto Sans Mono (editorial, refined — set headlines at 600)
• IBM Plex Sans + IBM Plex Mono (reliable, readable)
• Bricolage Grotesque + Fragment Mono (bold, characterful)
• Plus Jakarta Sans + Azeret Mono (rounded, approachable)

These five mirror the Rec rows of the pairing table in ./references/libraries.md, which holds eight more for when none of them fits the content. Its unmarked display faces — Instrument Serif, Playfair Display — earn a masthead, a pull quote, or a slide, where the type is large enough to carry them. Below roughly 16px they go limp, so a display face as --font-body on a scrollable page is the wrong call even though the pairing is listed.

Load via <link> in <head>. 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.

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

Color has a ceiling: eight categories, three when marks sit apart. Past eight distinguishable hues the reader stops decoding color and starts hunting the legend, so fold the tail into "Other" or facet into small multiples instead of minting a ninth. Scatter, bubble, and choropleth cap at three — their marks are separated in space, which is far less forgiving than the adjacent bars and stacked bands the eight are chosen for. The cap governs Mermaid node colors and diagram accents too, not just charts: a graph coloring nine kinds of node has no color story left.

Every page ships a theme toggle. This is not optional. Both modes are attribute-driven so the user can override the OS choice, and the choice persists across reloads. @media (prefers-color-scheme: ...) alone is not sufficient — it gives the viewer no control.

/* Light-first (editorial, paper/ink, blueprint): */
:root, :root[data-theme="light"] { /* light values */ }
:root[data-theme="dark"]         { /* dark values  */ }

/* Dark-first (IDE-inspired, terminal): */
:root, :root[data-theme="dark"]  { /* dark values  */ }
:root[data-theme="light"]        { /* light values */ }

One palette per mode, declared once — no media-query duplicate. A blocking inline script in <head> resolves the initial mode (localStorage → --theme flag → OS) and stamps data-theme before first paint, so there is no flash. Copy the "Theme Toggle" section from ./references/css-patterns.md wholesale: boot script, button markup, CSS, and the themechange event that Mermaid pages listen to in order to re-render with the new themeVariables.

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, and depth is how you say so. Executive summaries and key metrics dominate the viewport on load — larger type, more padding, elevated shadow, accent-tinted background (ve-card--hero). Body content stays flat (default .ve-card). Code blocks and secondary content feel recessed (ve-card--recessed). Reference sections (file maps, dependency lists, decision logs) stay compact and out of the way; use <details>/<summary> for what's useful but not primary. See the depth tiers and the collapsible pattern in ./references/css-patterns.md. 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).

Keep animations purposeful: entrance reveals, hover feedback, and user-initiated interactions. Nothing should glow or pulse on its own.