nicobailon/visual-explainer
v0.15.0MIT
Generate beautiful HTML pages for diagrams, diff reviews, plan reviews, slides, and data tables
Changelog
[0.15.0] - 2026-11-04
Highlights
- State machines drawn from your own code. Point a page at a reducer or transition function and it walks every state the code can reach: states you forgot to draw, events that never fire, dead ends, and broken rules you can replay step by step. A new
/state-machinecommand does the whole job. - Questions you skip stay skipped. A suggested answer no longer reaches the agent as your choice unless you pick it.
- Pages read well without any styling of their own, and long pages get a section menu that stays at the top.
- In Pi, you choose where pages are saved, including a folder inside each project.
- The Pi extension now loads in Pi builds that ship as a single Bun binary, such as Pi-Bolt.
Added
- Pages read well without any page CSS. Paragraphs and lists keep a comfortable line length, code blocks get a framed, scrollable style, plain lists get proper indents, and the blocks of a section get even spacing, so a figure's caption no longer sits on the paragraph after it.
- A section menu for long pages. One
<nav>line gives a bar that stays at the top, scrolls sideways on a phone, and marks the section you are reading. - Rendering a page flags drawing labels that have no color, which show as black text on a dark background.
- State machines drawn from the code itself. Point a page at the reducer or transition function in your repo, and the page walks every state the code can reach. It shows the states you forgot to draw, the events that never fire, the dead ends, and each rule the code breaks as the shortest path there, which you can replay step by step. A machine too big to place by hand is laid out for you, and a machine with independent parts, like playback and volume, draws each part in its own box. A new
/state-machinecommand runs the whole workflow, from finding the code to a test you can keep for each broken rule. The MCP server runs your code this way only when it starts withVISUAL_EXPLAINER_RUN_MODELS=1. Inspired by the/statechartskill in cursor/plugins (pstack), which walks a machine with TLA+; this kit walks the code directly and needs nothing installed. - In Pi, choose where pages are saved with a
visualExplainer.outputDirsetting, in your own settings or a project's. Set it to"project"to keep each repository's pages in its own.agent/diagrams/, or give any path. Thanks to @IdrisGit for #128.
Changed
- Diff reviews and comparisons walk a state machine read from the code on each side, so they show a rule a change newly breaks or a state it makes unreachable.
Fixed
- Sending a reply no longer answers the questions you left alone. A question with a suggested answer used to go into the reply as that answer, marked "(default)", so an agent could read an untouched "Approve" as approval and start work. It now goes in as "no answer" until you pick an option. Thanks to @IdrisGit for #129 and @mplibunao for reporting #127.
- The Pi extension loads in a Pi built as a single Bun binary, such as Pi-Bolt. It used to stop Pi from starting with
ENOENT: no such file or directory, lstat '/$bunfs/root/pi'. Thanks to @crisboarna for #126. - A question whose suggested answer was written on the question instead of on the option showed nothing pre-selected and gave no warning. Rendering now stops with an error that shows where it belongs.
- Values that change during a step-through, like a counter, showed as black, unreadable text in dark mode unless the page styled them itself.
- An arrow's label no longer crosses the arrow beside it; the drawing widens to hold it.
[0.14.0] - 2026-10-18
Highlights
- Pages check themselves. Every render opens the page in a browser, lists real layout problems like overlapping text, labels a line runs through, or text too small to read on a phone, and gives the agent one contact sheet to look at. Agents no longer write their own browser scripts, and a page takes about 23% fewer turns.
- Explainers move when motion helps. A process, a flow, or a change of state gets a step-through or a replay without you asking for it.
- Mermaid works offline and matches the page. A diagram written in Mermaid is drawn when the page is built, in the page's colors and fonts, with its own phone layout and nothing to load.
- Less to read. An agent reads about 16% less guidance for a page without motion, and the main skill file is about 15% shorter.
Added
- Rendering a page now looks at it in a browser when Chrome and
playwright-coreare available. It reports script errors, sideways scrolling, labels under 12 px, text that overlaps other text or runs past its drawing, labels a border or line runs through, and headings that sit on the figure below, at every step of a step-through too. It also saves a contact sheet with the first screen, each figure, and each step. Pi and MCP show the sheet to the agent; elsewhere the render prints its path. Without a browser, or when a page is slow or offline, the check is skipped with one line and the render still succeeds. - Kit classes for a dashed boundary, queue and worker slots, chart axes, and tables, which pages used to style by hand.
Changed
- Explainers animate wherever motion helps the reader understand a process, a flow, or a change of state, without being asked. Step-throughs, replays, flow dots, and live figures are the default there; a slide deck, a video, and PPTX still need a request.
- Agents read about 16% less for a page without motion, and no longer open the kit's source to look things up. Step-throughs, replays, live figures, and 3D have their own guide that agents read only when a figure moves.
- The main skill file is about 15% shorter. Images, Mermaid, PPTX, and the older recipes moved to the guides that need them, and checks the renderer now does left the delivery checklist.
- Mermaid diagrams are drawn when the page is built, by Pele from Obsidian, instead of by Mermaid.js from a CDN when the page opens. The diagram works offline, follows theme switches, gets its own phone layout, and is checked like any other figure. A Mermaid syntax error or a missing
aria-labelstops the render and names the line. Pele ships inside the skill, so there is nothing to install. Mermaid is still used only when you ask for it; hand-drawn figures stay the default. - Wide drawings keep their labels readable on a phone without the agent working out the scale. Every drawing gets
role="img", and a drawing without anaria-labelstops the render.
Fixed
- A section that opens with a small label above its heading no longer sits flush on the figure below.
- Running
kit/render.mjsorplan/render.mjsthrough a symlinked skill folder no longer exits without writing anything.
Removed
kit/check.mjs. Rendering a page runs the same checks and more.
[0.13.0] - 2026-10-17
Highlights
- Talk back to any page. Select words or click part of a diagram to comment or ask, then send one reply. In Pi it goes straight into the chat; elsewhere it is copied for you to paste.
- Plans you answer in the page.
/generate-visual-plandraws the change, lets you pick options and mark the agent's guesses, and sends back one response. After the build, the same page shows what was built. - Narrated videos.
/generate-videoturns an explainer into a 1080p MP4 with voice-over, or records a walkthrough of a live web app. - Animated state machines. An explainer about a job queue, a workflow, or anything else with states can replay it one event at a time: the route each event takes lights up, a dot travels along it, queues fill and drain, and each step's caption says why it happened. Inspired by the animated state-machine diagrams in hapsland by Igor Loskutov (@dearlordylord).
- About 60% fewer tokens. An agent reads about 60% less guidance for a diagram and writes about 60% less per page, the always-on tool descriptions in Pi and MCP are shorter, and revisions are small edits instead of rewrites.
Added
/generate-videomakes a narrated MP4. The agent writes a video deck whose scenes carry their narration, andvisual-explainer-videorecords it at 1080p on a virtual clock, so motion never stutters and each picture appears with its sentence. Narration comes from ElevenLabs, Seed Audio, OpenAI, or xAI when a key is set; without one, the video is silent with captions.--stillssaves one picture per scene to check first. The same command can record a walkthrough of a live web app. It needs ffmpeg andplaywright-core, which you install separately so everyone else's install stays small./generate-visual-planmakes a plan you answer in the page instead of a page you only read. It opens on the change as a drawing whose numbered parts match a short list of claims. You pick options for the decisions the agent cannot make alone, mark its guesses right or wrong, comment on any words you select, then approve or request changes. Changing an option redraws the figure. Keyboard shortcuts and saved answers make long plans quick to get through.- After the build, the same plan becomes a receipt: each claim shows whether it was built, changed, or dropped, next to the check that proves it.
- Plans are written with a few short tags. The renderer reads the cited code from your repository and stops on file paths or line numbers that do not exist. Boxes-and-arrows diagrams (
<ve-flow>) are laid out for the agent, so it no longer places coordinates by hand. /comparedraws two or more options side by side, recommends one, and lets you pick in the page; your pick comes back to the agent in the reply.- Any page can be answered, not only plans. Select words or click part of a figure to comment or ask, and a quiet Reply button gathers your notes into one reply.
<ve-ask>puts a question with options on any page, and your answer joins the reply. In Pi, a page opened in a Glimpse window sends the reply straight into the chat when you press Send to agent; elsewhere it is copied for you to paste. - Diagrams carry their numbers and notes on the drawing. A wait, a size, or a time window is drawn as a dimension line on the span it measures. Numbered callouts match the steps of a step-through. A finding that lives in one small part, such as file permission bits, gets a close-up of that part.
- A step-through can replay a state machine one event at a time. The whole machine stays drawn while each event lights the route it took and dots run along it. Queues fill and drain, worker slots fill and free up, and counts change in place. Each caption says why the event happened and cites the code behind it.
examples/replay-job-queue.htmlshows all of it. <ve-bars>,<ve-waffle>, and<ve-stack>turn a few numbers into a chart, with units on every label and one scale across charts that share amax.<ve-flow>works on any page too. Hand-drawn diagrams stay the default.- Pages are written as a short source,
<name>.src.html, with one kit line in its head; the renderer adds the shared styles, fonts, diagram parts, and script. The reference page takes 64% fewer tokens to write, and renders the same. Pirenderand MCPvisual_explainer_render_htmltake the source aspath; elsewhere, runnode kit/render.mjs <name>.src.html. - Revisions, including
/fact-checkcorrections, are small edits to the kept source and a new render; the agent never writes the whole page again. - One kit carries all four looks.
data-registeron<html>picks Instrument, Blueprint, Paper, or Editorial, with its fonts and light and dark colors. - Every render reports its figures, uncaptioned figures, tags, and prose words in one line, and a mistake in a tag stops the render and names its line.
node kit/check.mjs page.htmlopens the page in Chrome at phone and desktop widths and reports script errors, sideways scrolling, and labels under 12 px. - The MCP server serves the skill's reference docs as resources, so a client that cannot read files can follow them.
Changed
/plan-reviewwrites its review as a plan page: each finding comes with evidence from the code and a suggested fix you accept or reject, and your answers come back as one response./diff-reviewasks about each risk worth fixing, so your reply comes back as the list of fixes to make. On someone else's PR it drafts review comments and never posts them./project-recapends by asking where to start. Both chart sizes and churn with the new data tags.- The guidance an agent reads for a diagram is about 60% shorter, and the always-on tool descriptions in Pi and MCP are shorter too.
- A page opened in a Pi Glimpse window now closes when the session ends, as plan windows do.
- A printed page uses its own look's colors on white, not the default amber.
Removed
--quickmode, along with Piaction: "render_quick"and MCPvisual_explainer_render_quick. A full page now costs about as little to write, and it gets replies, the four looks, and the page checks that quick pages lacked. Drop--quickfrom any saved prompts.
Fixed
- Section navigation on narrow screens no longer shows a grey scrollbar under the links. The links scroll with a faded edge, and buttons such as a skim toggle stay in place.
- Sources at the end of a page are always visible, in their own section at full size, instead of hidden behind a small grey toggle.
- In Pi, pressing Send to agent in a Glimpse plan window after
/new,/resume,/fork, or/reloadno longer crashes pi. Thanks to @masonc15 for #112. - A
VISUAL_EXPLAINER_OUTPUT_DIRthat passes through a symlink is now rejected before the directory is created, and the error shows where the path really leads, such as/private/tmpfor/tmpon macOS. The default~/.agent/diagrams/still follows a symlinked~/.agent. Thanks to @tharanee-bit for #115. - Pages that use
$$outside math, such as a$$query helper in a script or prices like$$5, no longer break on render. Thanks to @tharanee-bit for #115. - The reference page's small failure-mode diagrams drew their lower labels at 11.4 px on wide screens; they are now 12.3 px or more at every width.
[0.12.0] - 2026-10-02
Highlights
- Pages now lead with the answer as a picture and one sentence, and every section is built around a figure instead of paragraphs.
- Diagrams are hand-drawn to match the page. They can step through a process, show traffic flowing along edges, and light up when you hover a term in the text. Mermaid is used only when you ask for it.
- Live figures let readers drag a slider or flip a toggle and watch the diagram, numbers, and headline update.
- Four built-in looks (Instrument, Blueprint, Paper, Editorial) with magazine-grade type and layout, readable contrast in light and dark, and a subtle touch of each page's topic.
- The skill is about 60% smaller, so agents read less and follow it more closely.
Added
- Live figures: one to three controls recompute the diagram, numbers, and headline from one model. A policy toggle can show how a bad rule produces an attractive wrong answer. Thanks to @zanzipanzi for #96.
- Step-by-step and animated explainers: a stepper and scene player that build a diagram one part at a time, plus guidance for a narrated video when you ask for one.
- Linked highlighting: hovering or focusing a term in the text lights up the matching parts of the figure and table rows.
- Small multiples, waffle charts, bars, and sparklines, so every number and every set of cases gets a picture.
- three.js figures for data where depth carries meaning, such as embeddings, spatial layouts, and geometry.
- The Pi
visual_explainertool now saves toVISUAL_EXPLAINER_OUTPUT_DIRwhen it is set, like the MCP server. The default stays~/.agent/diagrams/, and/fact-checklooks in the same place. Thanks to @eaxeax for #99. - The repository works as an Agent Plugins 1.0.0 plugin, so compatible clients can discover the skill without a client-specific install. Thanks to @gunzip for #100.
Changed
- The skill is rewritten to be figure-first and about 61% smaller. The first screen shows the answer, figures lead every section, and the writing is short and plain.
- Every diagram is hand-drawn SVG, including sequence and schema diagrams. The skill no longer chooses Mermaid on its own. When you ask for Mermaid, a short rule covers theming, labels, and sizing.
- A new style guide defines four looks (Instrument, Blueprint, Paper, Editorial), each with its own fonts and a light and dark palette where all text meets 4.5:1 contrast. Typography, layout, and chart rules draw on Bringhurst, Butterick, Müller-Brockmann, Tufte, Datawrapper, and the FT Visual Vocabulary.
- Pages pick up a subtle motif from their subject, such as an accent color, a texture, or a diagram convention.
- Figures look crafted rather than flat: raised nodes, shapes that show what a thing is (a cylinder for a database), a highlight on the key element, and gentle entrance motion. Reduced motion, print, and no-JS show the final state.
- Page structure is flexible: concept explainers, visual plans, reviews, comparisons, essays, and single-diagram pages each get a suggested shape.
- Theme palettes raise dim text wherever it was below 4.5:1 contrast.
Removed
- The old reference files (
css-patterns.md,libraries.md,responsive-nav.md,slide-patterns.md,mermaid.md) and the architecture, Mermaid, and data-table templates. One reference page replaces the templates. The old files stay available as optional links pinned to v0.11.0.
Fixed
- Page styles no longer shrink or restyle Mermaid diagram labels. Thanks to @vnakhate for #98.
- Slide resume no longer stops between slides and works on local
file://pages. The outline and help dialog has an accessible name again.
Security
- Pi renders are written to a temporary file and moved into place, like MCP renders, so a file swapped for a symlink cannot redirect the write. Re-rendering a file keeps its permissions.
[0.11.0] - 2026-08-28
Highlights
- MCP users can choose where local HTML renders are saved without losing the default safe output directory.
- Install instructions are clearer across Cursor, Antigravity, Codex, and OpenCode, including safer Windows copy commands.
- Release metadata now has a guardrail so package and plugin versions stay in sync.
- Slide decks make over-budget content easier to spot during reduced-motion review.
- Local
file://previews are quieter and more reliable when using the responsive table of contents.
Added
- Added optional
VISUAL_EXPLAINER_OUTPUT_DIRsupport for MCP renders. The default remains~/.agent/diagrams/, and custom directories still stay inside a local output jail. Requested by @bertheto in #88. - Added rem-based type-scale guidance for non-slide, scrollable pages, with copyable role selectors and readable minimums. Based on PR #95 by @ZanziPanzi.
Compatibility
- Documented native Cursor global and workspace skill paths, plus staged PowerShell install commands with rollback for Antigravity, Codex, and OpenCode. Credit: @bertheto for #86/#90.
Fixed
- Fixed the stale nested Claude plugin version that made Claude Code report the wrong latest version after
0.10.0, and added a version check across package, marketplace, plugin, and skill metadata. Reported by @proxet-p35 in #93. - Added a reduced-motion slide budget check that marks vertical overflow and
autoFit()fallbacks instead of silently clipping or shrinking over-budget content. Reported by @bertheto in #92. - Guarded the responsive-nav table-of-contents history update for
file://pages so local scrolling still works without console errors. Based on PR #94 by @ZanziPanzi.
[0.10.0] - 2026-08-20
Highlights
- Visual explanations now choose a calmer or more expressive treatment based on the request instead of defaulting to the same look every time.
- Repo-aware pages now prefer the project's own design language before falling back to built-in visual directions.
- Diagrams now get stronger guidance on what to show, not just how to render Mermaid.
- The skill now includes a clearer accessibility and dual-theme baseline for generated pages.
Added
- Added design-judgment guidance for matching the visual treatment to the request, planning a specific design before writing HTML, and avoiding generic generated-page patterns.
- Added project design-system precedence so repo-anchored pages can follow existing theme tokens, component styles, and visual vocabulary.
- Added content-anchored aesthetic directions for CLI, infrastructure, metrics, architecture, recap, and prose-heavy pages.
- Added diagram rhetoric guidance that asks diagrams to show the mechanism, label arrows, compare differences directly, and make one clear claim per figure.
- Added craft guidance for dual color schemes, type setting, neutrals, spacing, microcopy, dashboard readability, keyboard focus states, and diagram captions.
Fixed
- Synchronized Claude Code marketplace and skill metadata versions after the mismatch reported by @romkazor in #83.
[0.9.0] - 2026-08-13
Added
- Added a best-effort static PPTX export utility for simple HTML slide decks. It extracts slide text, bullets, simple tables, code blocks, and diagram placeholders while keeping HTML as the source of truth. Requested by @romkazor in #50.
- Added a local stdio MCP server that exposes render tools, bundled prompt templates, and read-only skill resources without HTTP, auth, remote storage, or LLM calls. Requested by @luketych in #33.
- Added VS Code Copilot and Copilot CLI custom-instruction guidance that points to the canonical skill without claiming native Copilot support. Reported in #8 by @Tal94NICE, with ideas from @davida26 and @jcespinoza.
- Added optional Markdown companion guidance for explicitly requested AI-readable output or source briefs. Companions sit beside HTML output and never become its source. Requested by @mrns in #34.
- Added opt-in
--quickrendering for web diagrams, diff reviews, plan reviews, and project recaps. Agents emit a compact validated JSON spec, and the bundled renderer creates complete HTML through the existing Pi tool or a local script fallback. Based on the original RFC idea and PR #12 by @mikeyobrien. - Added Antigravity CLI install guidance using its native Agent Skills paths, replacing the blocked consumer Gemini CLI support path. Reported by @chadbr in #6.
- Added an optional Glimpse viewer for Pi renders through
visual_explainerwithviewer: "glimpse"orviewer: "auto". Requested by @bjesuiter in #55 and prototyped in PR #56. - Added a standard self-contained favicon to rendered pages and reference templates. Based on PR #62 by @zereraz.
- Added reader-first slide deck navigation with an expandable side rail, outline/help overlays, deep links, reading percent, and resume state. Based on PR #65 and PR #67 by @zereraz.
- Added an optional runtime theme and font picker with eleven prebuilt palettes in
references/themes.md, deriving all MermaidthemeVariablesand the diagram label font from the active selection so diagrams stay consistent with the page. Font pairs are drawn from the families the skill already recommends. Rebuilt smaller from PR #42 by @turkycat.
Fixed
- Fixed expanded-diagram exports painting a fixed background color rather than the live page palette, so an exported diagram matches the page it came from.
- Kept slide-deck content visible in no-JS previews such as QuickLook by gating entrance-hidden states on JavaScript availability. Reported by @bradleyy in #68.
- Hardened Pi render output with missing
html lang, missing viewport metadata, and display-math escaping for raw</>inside$$...$$. Based on PR #65 and PR #67 by @zereraz. - Added font-weight guidance so copied Google Fonts examples load each rendered weight, including mono labels. Based on PR #60 by @jowcy.
- Added small maintenance fixes for
node_modules/ignores, slide-deck button types, output-directory symlink checks, and older changelog ordering. Based on PR #66 by @fix2015.
[0.8.2] - 2026-08-13
Added
- Added Pi package gallery image metadata using
banner.png.
[0.8.1] - 2026-06-25
Fixed
- Removed the invalid Claude Code plugin
skills: ["./"]manifest entry so the marketplace plugin no longer trips thePath escapes plugin directoryloader error. Reported by @aidansommers in #49, @fessygaspard-cpu in #51, @frntman in #58, and @syxc in #59, with confirmations and follow-up from @MauricioCorzo, @umar-s, @marcuslannister, and @NikiforovAll. - Added the required
descriptionfrontmatter to the canonicalvisual-explainerskill so Agent Skills loaders can discover it without metadata warnings. - Added explicit
namefrontmatter to bundled command templates for loaders that do not infer command names from filenames. Based on the NLPM audit reports #46 and #48 and PR #43 from @xiaolai. - Updated the canonical Mermaid SVG insertion pattern to parse rendered SVG through the lenient HTML parser instead of assigning
innerHTML, preserving Mermaid 10+/11foreignObjectlabels while avoiding common scanner warnings. Based on issue #37 and PR #54 from @thomnico.
[0.8.0] - 2026-06-24
Added
- Added one Pi extension tool,
visual_explainer, withpreparefor permission-aware visual explanation planning and optional subagent scouting, plusrenderfor writing and opening generated HTML pages while keeping/generate-web-diagramas a prompt template.
Changed
- Compressed the visual-explainer skill and command prompts from 10,824 words to 2,131 words, an 80%+ reduction in prompt tokens, while preserving the hard rendering, Mermaid, table, slide, and review-section requirements.
[0.7.1] - 2026-04-27
Compatibility
- Added first-class Pi package metadata so
pi installcan load the canonicalplugins/visual-explainer/skill and command templates directly from the repo. - Preserved the Claude Code marketplace layout while synchronizing package and plugin manifest versions to
0.7.1. - Added lightweight harness guidance for Pi, Codex CLI, OpenCode/opencode, Cursor, and OpenClaw without duplicating skill directories or adding runtime adapters.
- Documented migration cleanup for older manual Pi installs, which can otherwise shadow package resources with copied user-level skill and prompt files.
Changed
- Made
pi installthe primary Pi installation path while keeping the legacy installer documented as an explicit copied-file alternative.
[0.6.3] - 2026-03-09
Documentation
- Added explicit warning against using bare
<pre class="mermaid">tags — they render but produce tiny unusable diagrams without zoom/pan controls. Updated SKILL.md to point to the fulldiagram-shellpattern fromtemplates/mermaid-flowchart.html.
[0.6.2] - 2026-03-08
Bug Fixes
- Fixed fullscreen diagram export using wrong background color — now uses the same dark/light mode that was used to render the Mermaid theme
[0.6.1] - 2026-03-08
Pi Install Script
- New
install-pi.shfor one-command installation - Automatically patches
{{skill_dir}}to actual install path - Usage:
curl -fsSL https://raw.githubusercontent.com/nicobailon/visual-explainer/main/install-pi.sh | bash
[0.6.0] - 2026-03-08
Based on PR #25 by @peak-flow, with additional multi-diagram architecture and bug fixes.
Multi-Diagram Support
- New vector-based zoom/pan engine replacing CSS
zoomwith direct SVG sizing - Closure-based
initDiagram(shell)pattern — per-diagram state in closures, shared drag listeners at module scope - Unlimited diagrams per page with no ID collisions (each diagram gets a unique generated ID)
- New HTML structure:
.diagram-shell>.mermaid-wrap>.mermaid-viewport>.mermaid-canvas - Source Mermaid code lives in
<script type="text/plain" class="diagram-source">to avoid parsing issues - Adaptive viewport height based on diagram aspect ratio
- Smart fit algorithm with readability floor (prevents tiny unreadable diagrams)
- New zoom controls: 1:1 button, zoom percentage label
- Touch pinch-to-zoom support with proper pan transition
- Double-click to fit diagram
Bug Fixes
- Fixed touch pinch→pan transition (reset start coords after pinch ends)
- Removed dead
fitZoomvariable from previous implementation - Removed 12 lines of dead scrollbar CSS (no longer needed with new viewport approach)
Documentation
- Updated
css-patterns.mdwith new multi-diagram structure and JavaScript pattern - Simplified Mermaid section to reference
mermaid-flowchart.htmlas canonical source
[0.5.1] - 2026-03-05
Claude Code Marketplace Structure
- Restructured repo to follow Claude Code's official plugin marketplace spec
- Moved all skill files into
plugins/visual-explainer/subdirectory - Added
.claude-plugin/marketplace.jsoncatalog for marketplace discovery - Plugin manifest now at
plugins/visual-explainer/.claude-plugin/plugin.json - Install via marketplace:
/plugin marketplace add nicobailon/visual-explainerthen/plugin install visual-explainer@visual-explainer-marketplace
Pi Manual Install
- Replaced
pi installone-liner with manual installation instructions - Pi users now clone repo and copy skill + prompts to
~/.pi/agent/skills/and~/.pi/agent/prompts/ - Removed stale
pifield frompackage.json(was pointing to non-existent root paths)
OpenAI Codex Install Fix
- Fixed prompts path:
~/.codex/prompts/(was incorrectly~/.agents/commands/) - Prompts are optional (deprecated feature) — skill works without them via
$visual-explainer - With prompts installed, invoke as
/prompts:diff-review,/prompts:plan-review, etc.
Breaking Changes
- Direct Claude Code plugin install (
/plugin install https://...) no longer works — use marketplace flow instead pi install https://github.com/nicobailon/visual-explainerno longer works — use manual install
[0.5.0] - 2026-03-04
Class Diagram and C4 Architecture Support
- Added
classDiagramguidance for OOP design and domain modeling - Documented relationships: association, composition, aggregation, inheritance
- Added C4 architecture support using
graph TD+subgraph(not nativeC4Contextwhich ignores themes) - Added
.dir-treeCSS pattern for file structures with tree connectors - Added quick-reference table for choosing Mermaid diagram types
Claude Code Plugin Support
- Added
.claude-plugin/plugin.jsonmanifest for Claude Code plugin installation - Renamed
prompts/tocommands/(compatible with both pi and Claude Code) - Claude Code:
claude /plugin install https://github.com/nicobailon/visual-explainer - Note: Claude Code namespaces commands as
/visual-explainer:command-name
OpenAI Codex Support
- Added install instructions for OpenAI Codex to README
- Uses
~/.agents/skillsand~/.agents/commandspaths
Bug Fixes
- Fixed pi skill loading: scoped
pi.skillsto./SKILL.mdinstead of./(was trying to load README.md and CHANGELOG.md as skills) - Fixed Mermaid line breaks: use
<br/>instead of\nin flowchart labels (renders as literal text otherwise) - Fixed
mermaid-flowchart.htmlto match documented pattern: moved flex centering from.mermaid-wrap .mermaidto.mermaid-wrap, addedmin-height: 400px
[0.4.5] - 2026-03-04
Click-to-Expand Mermaid Diagrams
- Clicking anywhere on a Mermaid diagram (without dragging) opens it full-size in a new browser tab
- Added expand button (⛶) to zoom controls for discoverability
- New
openMermaidInNewTab()andopenDiagramFullscreen()functions in the Mermaid JavaScript pattern - Click detection distinguishes quick clicks from drag-to-pan (5px movement threshold, 300ms time threshold)
- Full-size view preserves the page's background color for visual consistency
- Updated all templates (
mermaid-flowchart.html,slide-deck.html) with new pattern - Updated
css-patterns.mdandslide-patterns.mddocumentation
Bug Fixes
- Removed unused
textvariable inopenMermaidInNewTab()function - Removed unused
eparameter in mouseup handlers - Fixed inconsistent zoom range limits (standardized to 0.5x–5x across all files)
- Removed dead CSS
.mermaid-wrap.is-zoomedrule (class was never applied by JavaScript) - Removed dead CSS
transition: transformon.mermaid(zoom property is not animatable) - Added missing
cursor: grabto base.mermaid-wrapselector in templates - Added missing flex centering (
display: flex; justify-content: center; align-items: center) to.mermaid-wrapinslide-deck.html - Updated
SKILL.mdto explicitly mention the click-to-expand feature and expand button so agents include it when generating pages - Updated all prompt templates (
diff-review.md,plan-review.md,project-recap.md,generate-visual-plan.md) to specify the expand button and click-to-expand functionality for Mermaid diagrams
[0.4.4] - 2026-03-02
Hybrid Architecture Pattern
- New pattern for complex architectures (15+ elements): simple Mermaid overview (5-8 nodes) + CSS Grid cards for details
- Updated "Architecture / System Diagrams" section in SKILL.md with three-tier approach based on complexity
- Reduced max Mermaid node count from 15-20 to 10-12 in
libraries.md - Updated Mermaid scaling guidance to recommend hybrid pattern over scaling tricks for complex diagrams
[0.4.3] - 2026-03-01
Mermaid Zoom and Positioning Fixes
- Fixed zoom clipping: Replaced
transform: scale()with CSSzoomproperty. Transform only changes visual appearance — content expanding upward/leftward goes into negative space which can't be scrolled to. Zoom changes actual layout size, so overflow scrolls normally in all directions. - Fixed vertical centering: Changed
align-items: flex-starttoalign-items: centerso diagrams are centered both horizontally and vertically in their container. - Added initial zoom: Complex diagrams can start at zoom > 1 (e.g., 1.4x) for better readability while keeping zoom controls functional.
- Added min-height: Containers now have
min-height: 400pxto prevent vertical flowcharts from compressing into unreadable thumbnails. - Removed unnecessary
.mermaid-innerwrapper — no longer needed with zoom-based approach. - Updated JavaScript to use
INITIAL_ZOOMconstant for consistent reset behavior. - Updated "Scaling Small Diagrams" section to use
zoominstead oftransform: scale()for consistency.
[0.4.2] - 2026-03-01
Link Styling
- New "Link Styling" section in
css-patterns.md— never rely on browser default link colors; use accent colors with sufficient contrast
[0.4.1] - 2026-03-01
Mermaid Layout Direction
- New "Layout Direction: TD vs LR" section in
libraries.md - Prefer
flowchart TD(top-down) overflowchart LR(left-to-right) for complex diagrams - LR spreads horizontally and makes labels unreadable with many nodes
- Rule: use TD for 5+ nodes or any branching; LR only for simple 3-4 node linear flows
Documentation
- Simplified README: trimmed Usage section, consolidated Install, added Slide Deck Mode section
- Added
/generate-visual-planto command table
[0.4.0] - 2026-02-28
New Prompt Template
/generate-visual-plan— generate visual implementation plans for features and extensions. Produces editorial/blueprint-style HTML pages with problem comparison panels, state machine diagrams, code snippets, edge case tables, and implementation notes. Designed for documenting feature specs before implementation.
Prose Accent Patterns
Added patterns for use as accent elements within visual pages.
css-patterns.md — New "Prose Page Elements" section:
- Body text settings (font-size, line-height, max-width for comfortable reading)
- Lead paragraph patterns (larger size, drop cap variants)
- Pull quotes (border-left, centered with quotation mark)
- Section dividers (horizontal rule, ornamental)
- Article hero patterns (centered, editorial)
- Author byline pattern
- Prose-specific anti-patterns
libraries.md — New "Typography by Content Voice" section:
- Font recommendations by content type (literary, technical, bold, minimal)
- Special mention of Literata for screen reading
SKILL.md — New sections:
- "Prose Accent Elements" — when to use lead paragraphs, pull quotes, callouts
- "Documentation" — content-to-visual mapping (features→cards, steps→flows, APIs→tables)
Overflow Fix: List Markers in Bordered Containers
css-patterns.md: New section "List markers overlapping container borders" with three solutions- Rule of thumb: use
list-style-position: insideorpadding-left: 2emfor lists in bordered containers
Mermaid Fixes
- Centering: narrow vertical flowcharts must be centered, not left-aligned
- Scaling: complex diagrams with 10+ nodes render too small — increase fontSize to 18-20px or use CSS scale transform
- Special characters: node labels starting with
/,\,(,{must be quoted to avoid shape syntax conflicts - New "Scaling Small Diagrams" section in css-patterns.md
- New "Node Label Special Characters" section in libraries.md
Code Block Patterns
css-patterns.md: New "Code Blocks" section with:- Basic pattern with
white-space: pre-wrap(critical for preserving line breaks) - File header pattern for displaying code with filename
- Implementation plan guidance: don't dump full files, show structure instead
- Basic pattern with
SKILL.md: New "Implementation Plans" section with structure guidance
[0.3.0] - 2026-02-26
Anti-Slop Guardrails
- Added explicit "Anti-Patterns (AI Slop)" section to SKILL.md with forbidden patterns
- Removed "Neon dashboard" and "Gradient mesh" from allowed aesthetics — they always produce generic output
- Categorized aesthetics as "Constrained" (safer) vs "Flexible" (use with caution)
- Explicit forbidden fonts: Inter, Roboto, Arial, Helvetica, system-ui as primary
- Explicit forbidden colors: indigo/violet range (
#8b5cf6,#7c3aed,#a78bfa), cyan-magenta-pink combination - Explicit forbidden effects: gradient text on headings, animated glowing box-shadows, emoji section headers
- Added "The Slop Test" — 7-point checklist to catch AI-generated patterns before delivery
- Strengthened typography guidance with 5 explicit good pairings to use
- Strengthened color guidance with 5 explicit good palettes to use
- Referenced
websocket-implementation-plan.htmlas positive example of Blueprint aesthetic
Template Fixes
- Replaced violet secondary colors in
mermaid-flowchart.htmlwith sky blue to match anti-slop guidelines - Updated Mermaid themeVariables example in
libraries.mdto use teal/slate palette instead of violet
[0.2.0] - 2026-02-25
Slide Deck Mode
- New output format: magazine-quality slide deck presentations as self-contained HTML files
- 10 slide types: Title, Section Divider, Content, Split, Diagram, Dashboard, Table, Code, Quote, Full-Bleed
- SlideEngine JS: keyboard/touch/wheel navigation, progress bar, nav dots, slide counter, keyboard hints with auto-fade
- Cinematic transitions: fade + translateY + scale on slide entrance, staggered child reveals via IntersectionObserver
- 4 curated presets: Midnight Editorial, Warm Signal, Terminal Mono, Swiss Clean (each with full light/dark palette)
- Event delegation: Mermaid zoom, scrollable code/tables don't trigger slide navigation
- Responsive height breakpoints (700px, 600px, 500px) for projection and small viewports
- Typography scale 2–3× larger than scrollable pages (80–120px display, 28–48px headings, 16–24px body)
- Per-slide background variation, SVG decorative accents, compositional variety rules
- Proactive imagery: surf-cli integration for title/full-bleed backgrounds, inline sparklines, mini-charts
- New
/generate-slidesprompt template; existing prompts support--slidesflag via SKILL.md workflow - Unified
autoFit()post-render function: auto-scales Mermaid SVGs, KPI values, and long blockquotes to fit their containers - Fix Mermaid diagrams rendering tiny in slide containers (flex shrink-wrap + inline max-width)
- Fix KPI card overflow for text values (white-space + transform scale)
- Fix quote slides with long text (proportional font-size reduction)
Files
references/slide-patterns.md— slide engine CSS, all 10 type layouts, transitions, nav chrome, content density limits, presetstemplates/slide-deck.html— reference template demonstrating all 10 types in Midnight Editorial presetprompts/generate-slides.md— slash command for generating slide decksSKILL.md— new "Slide Deck Mode" section with slide routing,--slidesflag detection, visual richness guidance
[0.1.4] - 2026-02-24
- Removed Mermaid
handDrawnmode — Rough.js hachure fills are hardcoded and render unreadable diagonal scribbles inside nodes with no user-facing override. All diagrams now uselook: 'classic'with customthemeVariablesfor visual distinction. - Added
package.jsonforpi installsupport — installs the skill and all slash commands in one step instead ofgit clone+ manualcp
[0.1.3] - 2026-02-24
- Extended
classDefcolor warning to also cover per-nodestyledirectives — both hardcode text color that breaks in the opposite color scheme - Renamed
.nodecard classes to.ve-cardto fix CSS collision with Mermaid's internal.nodeclass that broke diagram layout (PR #7)
[0.1.2] - 2026-02-19
- Added sequence diagram syntax guidance to "Writing Valid Mermaid" — curly braces, brackets, and ampersands in message labels silently break rendering
[0.1.1] - 2026-02-19
- Prompts no longer require the
pi-prompt-template-modelextension — each prompt now explicitly loads the skill itself - Added "Writing Valid Mermaid" section to
libraries.md(quoting special chars, simple IDs, max node count, arrow styles, pipe escaping) - Fixed mobile scroll offset in
responsive-nav.md— section headings now clear the sticky nav bar viascroll-margin-top - Added video preview to README
[0.1.0] - 2026-02-16
Initial release.
Skill
- Core workflow: Think (pick aesthetic) → Structure (read template) → Style (apply design) → Deliver (write + open)
- 11 diagram types with rendering approach routing (Mermaid, CSS Grid, HTML tables, Chart.js)
- 9 aesthetic directions (monochrome terminal, editorial, blueprint, neon, paper/ink, sketch, IDE-inspired, data-dense, gradient mesh)
- Mermaid deep theming with
theme: 'base'+themeVariables, hand-drawn mode, ELK layout - Zoom controls (buttons, scroll-to-zoom, drag-to-pan) required on all Mermaid containers
- Proactive table rendering — agent generates HTML instead of ASCII for complex tables
- Optional AI-generated illustrations via surf-cli + Gemini Nano Banana Pro
- Both light and dark themes via CSS custom properties and
prefers-color-scheme - Quality checks: squint test, swap test, overflow protection, zoom controls verification
References
css-patterns.md— theme setup, depth tiers, node cards, grid layouts, data tables, status badges, KPI cards, before/after panels, connectors, animations (fadeUp, fadeScale, drawIn, countUp), collapsible sections, overflow protection, generated image containerslibraries.md— Mermaid (CDN, ELK, deep theming, hand-drawn mode, CSS overrides, diagram examples), Chart.js, anime.js, Google Fonts with 13 font pairingsresponsive-nav.md— sticky sidebar TOC on desktop, horizontal scrollable bar on mobile, scroll spy
Templates
architecture.html— CSS Grid card layout, terracotta/sage palette, depth tiers, flow arrows, pipeline with parallel branchesmermaid-flowchart.html— Mermaid flowchart with ELK + handDrawn mode, teal/cyan palette, zoom controlsdata-table.html— HTML table with KPI cards, status badges, collapsible details, rose/cranberry palette
Prompt Templates
/generate-web-diagram— generate a diagram for any topic/diff-review— visual diff review with architecture comparison, KPI dashboard, code review, decision log/plan-review— plan vs. codebase with current/planned architecture, risk assessment, understanding gaps/project-recap— project mental model snapshot for context-switching/fact-check— verify factual accuracy of review pages and plan docs against actual code