# Visual Explainer

> Use when the user asks for a self-contained HTML visual explanation, diagram, plan review, diff review, or recap.

- Skill: `anntnzrb/visual-explainer` (Agent Skill, multi-file: 17 files)
- Install (CLI): `npx skillmds@latest add anntnzrb/visual-explainer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/anntnzrb/visual-explainer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- License: AGPL-3.0-or-later
- Author: anntnzrb (https://skillmd.com/u/anntnzrb)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/anntnzrb/visual-explainer

---


# Visual Explainer

Generate self-contained HTML pages that explain systems, code changes, plans, data, and technical concepts visually. Use this skill for diagram requests, architecture overviews, diff/plan reviews, project recaps, comparison tables, slide decks, and any visual explanation.

## Trigger and delivery rules

- Prefer an HTML page over terminal ASCII when the output is inherently visual
- If a table would have 4+ rows or 3+ columns, render it as HTML and give only a short chat summary
- Write files to `~/.local/share/agents/visual-explainer/diagrams/` or the explicit eval output path. Use descriptive filenames
- Open generated pages in the browser when running normally. In Pi package installs, use `visual_explainer` with `prepare` for planning/context and `render` only after the complete HTML document exists
- The final page must be a complete self-contained HTML document, including embedded CSS and any needed JS

## Required follow-up reads

Read only the references needed for the current output:

|Need|Read|When|
|---|---|---|
|Text-heavy architecture/cards|`templates/architecture.html`|Building that page shape|
|Mermaid diagrams|`templates/mermaid-flowchart.html`, Mermaid sections in `references/libraries.md`|A graph is the chosen representation|
|Data tables, comparisons, audits|`templates/data-table.html`|Tabular HTML is chosen|
|Slide decks|`templates/slide-deck.html`, `references/slide-patterns.md`|Slides are explicitly requested|
|Layout, overflow, depth, connectors, images|`references/css-patterns.md`|The selected layout needs those patterns|
|4+ major page sections|`references/responsive-nav.md`|Adding responsive section navigation|
|Prose-heavy pages|Prose sections in `references/css-patterns.md` and `references/libraries.md`|Prose dominates the page|
|Command workflows|Matching file under `commands/`|Running that named command|

## Choose the representation

|Content|Default representation|
|---|---|
|Flowchart, pipeline, state machine, decision tree|Mermaid|
|Sequence, ER/schema, class, C4, topology-focused architecture|Mermaid|
|Text-heavy architecture, module internals, implementation plans|CSS grid cards, optionally with a Mermaid overview|
|15+ element architecture|Hybrid: small Mermaid overview + CSS detail cards|
|Comparison/audit/status matrix|Semantic HTML `<table>`|
|Timeline/roadmap|CSS timeline|
|Dashboard/metrics|CSS grid + charts/KPIs|
|Slide deck|`100dvh` slides using slide template patterns|

## Mermaid invariants

- Use `theme: 'base'` with custom `themeVariables` matching the page palette
- For complex diagrams use ELK layout when available
- Never use bare `<pre class="mermaid">`
- Use the canonical `diagram-shell` pattern from `templates/mermaid-flowchart.html`: `.diagram-shell` > `.mermaid-wrap` > `.zoom-controls` + `.mermaid-viewport` > `.mermaid-canvas`
- Every Mermaid diagram needs zoom in/out/reset/expand controls, Ctrl/Cmd+scroll zoom, drag panning, and click-to-expand
- Prefer `flowchart TD` for complex diagrams. Use `LR` only for simple 3-4 node linear flows
- Use `<br/>` in quoted flowchart labels. Do not use escaped `\n` labels
- Never define page-level `.node`; Mermaid uses it internally. Use namespaced page classes such as `.ve-card`
- For 15+ elements, do not cram everything into one Mermaid diagram. Use the hybrid overview + cards pattern

## Layout and style invariants

- Use semantic HTML where it helps accessibility and copy/paste: `<table>`, headings, lists, `<details>`, captions
- Use CSS custom properties for palette: `--bg`, `--surface`, `--border`, `--text`, `--text-dim`, and 3-5 accents
- Pick a clear aesthetic direction before writing: blueprint, editorial, paper/ink, terminal, IDE-inspired, or data-dense
- Avoid generic defaults: no body font that is only Inter, Roboto, Arial, Helvetica, or system-ui; no violet/fuchsia Tailwind-default accents as the main palette (`#8b5cf6`, `#7c3aed`, `#a78bfa`, `#d946ef`); no cyan+magenta+purple neon dashboard; no gradient-mesh blobs
- Good font pair families: DM Sans + Fira Code; Instrument Serif + JetBrains Mono; IBM Plex Sans + IBM Plex Mono; Bricolage Grotesque + Fragment Mono; Plus Jakarta Sans + Azeret Mono
- Good accent directions: terracotta+sage, teal+slate, rose+cranberry, amber+emerald, deep blue+gold
- Prevent overflow: `min-width: 0` on grid/flex children, `overflow-wrap: break-word` for long text, and scroll containers for wide tables/code
- Do not set `display: flex` directly on `<li>` when list markers matter
- Use depth sparingly: hero/elevated only for primary sections; flat/recessed for reference material
- Use entrance/hover animation only when it clarifies hierarchy. Respect `prefers-reduced-motion`. Do not use continuous glow, pulse, or breathing effects on static content

## Slide deck mode

Use slides only when explicitly requested or when a command asks for slides. Slides are a different medium, not a paginated article:

- Each slide is one viewport (`100dvh`) with no page-level scrolling
- Use larger type, fewer objects per slide, varied compositions, and visible navigation
- Include slide nav chrome from `slide-deck.html`: prev/next controls, slide count, keyboard navigation, and carousel dots/indicators
- Before writing HTML, inventory the source and map every source item to slides
- Do not drop content to fit a fixed slide count. Add slides instead
- Use the 10 slide types from `slide-patterns.md`: Title, Section Divider, Content, Split, Diagram, Dashboard, Table, Code, Quote, Full-Bleed

## Optional generated images

If `surf` is available, generated images may be embedded as base64 for hero banners, conceptual illustrations, or educational visuals. Skip images for data-heavy, structural, or Mermaid/CSS-suitable content. Pages must stand on CSS, typography, and diagrams without images.

## Final checklist

Before delivery, verify:

- complete HTML document;
- output written to the requested path;
- no console errors when opened;
- no horizontal overflow at normal desktop width;
- fonts load with fallbacks;
- tables preserve rows/columns and wrap long text;
- Mermaid diagrams use `diagram-shell` with zoom/pan/expand;
- slides fit one viewport, include carousel dots, and preserve source coverage;
- visual hierarchy makes the main idea obvious in the first viewport;
- styling would still be recognizable if compared against a generic dark/violet template