visual-explainer

# Visual explainer Generate self-contained HTML files for technical diagrams, editorial 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, source verification grids, 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 `./commands/`. In Claude Code, namespaced (`/visual-explainer:diff-review`). In Pi, these are slash commands (`/diff-review`). In Codex, use `/prompts:diff-review` (if installed to `~/.codex/prompts/`) or invoke `$visual-explainer` and describe the workflow. | Command | What it does | |---------|-------------| | `generate-web-diagram` | Generate an HTML diagram for any topic | | `generate-visual-plan` | Generate a visual implementation plan for a feature | | `generate-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 | | `share-page` | Deploy an HTML page to Vercel and get a live URL | ## 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 reporter revisiting an investigation? An editor reviewing a story? A PM seeing the big picture? An academic auditing methodology? 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, source network, investigation map, editorial workflow, story structure, 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) - Editorial broadsheet (serif headlines like Playfair Display or Crimson Pro, generous whitespace, muted earth tones or deep navy + gold) - Paper and ink (warm cream `#faf7f5` background, terracotta/sage accents, informal feel, good for newsroom features) - Magazine feature (large display serif, off-axis composition, rich pull quotes, photo-led) - Academic / research paper (Libre Baskerville or Source Serif, restrained palette, footnotes-style detail, generous margins) - Newsroom board (cork/pushpin texture, handwritten-style notes, pinned-card layouts, for editorial planning, story maps) - Investigation wall (red string aesthetic, connected entities, graph-paper background, monochrome with red accents, for relationship maps) - 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 / wire service (small type, tight spacing, maximum information, muted colors) - Hand-drawn sketch (Mermaid `look: 'handDrawn'`, casual annotations, for whiteboard/early-stage thinking) **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, source verification grids: 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:** | Content type | Approach | Why | |---|---|---| | Architecture (text-heavy) | CSS Grid cards + flow arrows | Rich card content (descriptions, code, tool lists) needs CSS control | | Architecture (topology-focused) | **Mermaid** | Visible connections between components need automatic edge routing | | Flowchart / pipeline | **Mermaid** | Automatic node positioning and edge routing | | Sequence diagram | **Mermaid** | Lifelines, messages, and activation boxes need automatic layout | | Data flow | **Mermaid** with edge labels | Connections and data descriptions need automatic edge routing | | ER / schema diagram | **Mermaid** | Relationship lines between many entities need auto-routing | | State machine | **Mermaid** | State transitions with labeled edges need automatic layout | | Mind map | **Mermaid** | Hierarchical branching needs automatic positioning | | Class diagram | **Mermaid** | Inheritance, composition, aggregation lines with automatic routing | | C4 architecture | **Mermaid** | Use `graph TD` + `subgraph` for C4 (not native `C4Context`, it ignores themes) | | Data table / comparison / audit | HTML `<table>` | Semantic markup, accessibility, copy-paste behavior | | Timeline / chronology | CSS (central line + cards) | Simple linear layout doesn't need a layout engine | | Dashboard / metrics | CSS Grid + Chart.js | Card grid with embedded charts | | Source network | Mermaid or CSS Grid cards | Map relationships between sources in an investigation or story | | Editorial workflow | Mermaid flowchart | Story lifecycle from pitch through publish/distribute | | Investigation map | CSS Grid cards + Mermaid | Connect entities, documents, and events in investigative work | | Story structure | CSS Grid | Visualize narrative arc, sections, sourcing distribution before publication | **Mermaid theming.** Always use `theme: 'base'` with custom `themeVariables` so colors match your page palette. Use `layout: 'elk'` for complex graphs (requires the locally bundled `@mermaid-js/layout-elk` package, see `./references/libraries.md`). Override Mermaid's SVG classes with CSS for pixel-perfect control. See `./references/libraries.md` for the 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 journalism `mermaid-flowchart.html` pattern: a `.mermaid-wrap` container with `.zoom-controls` (+/−/reset/expand buttons) wrapping a `.mermaid` element. The container's CSS handles overflow and pan affordances; the bundled JS wires zoom buttons, ctrl+scroll wheel zoom, click-and-drag panning, and click-to-expand into a new tab. Copy the template wholesale rather than reconstructing the pattern, and copy its sibling `templates/vendor/` directory so the pinned Mermaid import remains resolvable. **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["Pitch desk<br/>weekly intake"]`. **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](https://github.com/nicobailon/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: ```bash # 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. The journalism font pairings (Playfair Display + Source Serif Pro for editorial broadsheet, Libre Baskerville + Fira Code for academic, Bitter + Inconsolata for newsroom) are listed alongside the upstream technical pairings. **Forbidden as `--font-body`:** Inter, Roboto, Arial, Helvetica, system-ui alone. These are AI slop signals. **Good upstream 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) **Good journalism pairings (use these for editorial / academic / newsroom contexts):** - Playfair Display + Source Serif Pro (classic newspaper) - DM Serif Display + DM Sans (contemporary magazine) - Libre Baskerville + Fira Code (research paper) - Bitter + Inconsolata (working newsroom document) - Instrument Serif + JetBrains Mono (wire service / data) 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. **Forbidden accent colors:** `#8b5cf6` `#7c3aed` `#a78bfa` (indigo/violet), `#d946ef` (fuchsia), the cyan-magenta-pink combination. These are Tailwind defaults that signal zero design intent. **Good accent palettes (use these):** - Terracotta + sage (`#c2410c`, `#65a30d`), warm, earthy (newsroom, paper-and-ink) - Teal + slate (`#0891b2`, `#0369a1`), technical, precise (architecture, blueprint) - Rose + cranberry (`#be123c`, `#881337`), editorial, refined (verification audits) - Amber + emerald (`#d97706`, `#059669`), data-focused (dashboards) - Deep blue + gold (`#1e3a5f`, `#d4a73a`), premium, sophisticated (academic, executive) Put your primary aesthetic in `:root` and the alternate in the media query: ```css /* Light-first (editorial, paper/ink, blueprint, academic): */ :root { /* light values */ } @media (prefers-color-scheme: dark) { :root { /* dark values */ } } /* Dark-first (terminal, IDE-inspired): */ :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.** 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. 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, source lists) 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. **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, use the locally vendored anime.js asset in `./references/libraries.md`. **Forbidden animations:** - Animated glowing box-shadows (`@keyframes glow { box-shadow: 0 0 20px... }`), this is AI slop - Pulsing/breathing effects on static content - Continuous animations that run after page load (except for progress indicators) Keep animations purposeful: entrance reveals, hover feedback, and user-initiated interactions. Nothing should glow or pulse on its own. **Accessibility.** All generated pages must meet WCAG 2.1 AA minimum. This means: - Color contrast ratios: 4.5:1 for text, 3:1 for large text and UI components - Status indicators use shape/text alongside color (never color alone) - Tables have proper `<thead>`, `<th scope>`, and `<caption>` elements - Charts include data table alternatives - Focus indicators visible for keyboard navigation - Language declared in `<html lang="en">` ### 4. Deliver