/visual-explainer

name: visual-explainer
description: Generate self-contained HTML pages that visually explain technical material — systems, code changes, plans, data. Use when the user asks for any diagram or visual explanation, when they want a slide deck or a longform document (user guide, how-to, reference page), when another skill needs one rendered, or proactively in place of a terminal ASCII table (4+ rows or 3+ columns).
license: MIT
argument-hint: "[topic] [--style <name>] [--theme light|dark] [--slides|--handbook] [--picker]"
compatibility: Requires a browser to view generated HTML files.
metadata:
  attribution: "Based on https://github.com/nicobailon/visual-explainer by nicobailon (MIT)"

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

| Command | What it does | |---------|-------------| | `web-diagram` | Generate an HTML diagram for any topic | | `visual-plan` | Generate a visual implementation plan for a feature | | `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 |

Arguments

| Flag | Values | Effect | |---|---|---| | `--style <name>` | see the table below | Locks the aesthetic direction. Skips the "pick one and vary it" step in Workflow §1 — the choice is made, honor it exactly. | | `--picker` | — | **Selects a style instead of generating a page.** Short-circuits everything below — see Style Picker. | | `--theme <light\|dark>` | — | Forces the page's *initial* mode. With no flag the page follows the OS. The toggle is always present regardless — this flag only sets the starting state. | | `--slides` | — | Slide-deck output instead of a scrollable page. See Slide Deck Mode. | | `--handbook` | — | Document output instead of a freeform visual page. See Handbook Mode. Mutually exclusive with `--slides`. | | `--palette <hint>` | e.g. `terracotta+sage`, `deep-blue+gold`, or explicit hexes | Overrides accent selection. Forbidden colors are still forbidden — if the hint contains one, use the nearest allowed hue and say so. | | `--font <hint>` | e.g. `crimson-pro+noto-sans-mono` | Overrides the font pairing. Forbidden `--font-body` values still rejected. |

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

| Value | Direction | |---|---| | `blueprint` | Technical drawing — subtle grid background, deep slate/blue, monospace labels, precise borders | | `editorial` | Crimson Pro throughout — 600 headlines, 400 body, so the contrast is weight, not a second face. Set headings at 600 or a text serif goes limp at display size. Generous whitespace, muted earth tones or deep navy + gold | | `paper` | Warm cream `#faf7f5`, terracotta/sage accents, informal | | `terminal` | Monochrome — green/amber on near-black, monospace everything | | `data-dense` | Small type, tight spacing, maximum information, muted colors | | `dracula` `nord` `catppuccin-mocha` `catppuccin-latte` `solarized-dark` `solarized-light` `gruvbox` `one-dark` `rose-pine` | The real editor scheme, committed to exactly. Its hex values are in `./assets/style-catalog.html` — read the card, don't approximate from memory of the vibe |

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