# Plannotator Visual Explainer

Generate self-contained HTML visualizations with Plannotator theming.

- Repository: https://github.com/backnotprop/plannotator (9810 stars)
- Category: Documents
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add backnotprop/plannotator --skill plannotator-visual-explainer -g -a claude-code -y`
Codex: `npx skills add backnotprop/plannotator --skill plannotator-visual-explainer -g -a codex -y`
Cursor: `npx skills add backnotprop/plannotator --skill plannotator-visual-explainer -g -a cursor -y`
Gemini CLI: `npx skills add backnotprop/plannotator --skill plannotator-visual-explainer -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add backnotprop/plannotator`

## Description

Generate self-contained HTML visualizations with Plannotator theming. Use for implementation plans, PR explainers, architecture diagrams, data tables, slide decks, and any visual explanation of technical concepts. Plans and PR explainers follow Plannotator's prescriptive approach; all other visual content delegates to nicobailon/visual-explainer.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Plannotator Visual Explainer

Three paths depending on content type. Each has its own references and structure.

## Route by content type

**Implementation plan, design doc, or proposal** → Follow the [Plan path](#plan-path). Read `references/design-system.md` and `references/svg-patterns.md`. Prescriptive structure.

**PR explainer, diff review, or code change walkthrough** → Follow the [PR path](#pr-path). Read `references/design-system.md` and `references/pr-components.md`. Prescriptive structure.

**Everything else** (architecture diagrams, data tables, slide decks, project recaps, general visual explanations) → Follow the [Visual explainer path](#visual-explainer-path). Delegates to nicobailon/visual-explainer with Plannotator theme tokens.

## Delivery

Always deliver via Plannotator's annotation UI. Do NOT use `open` or `xdg-open`.

For any deliverable that uses Mermaid, render every diagram with Mermaid 12 in both the light
and dark palettes before opening the annotation UI. Rendering is a hard gate: an exception,
empty SVG, or error output such as `aria-roledescription="error"` or `Syntax error in text`
means the explainer is not deliverable. Fix the diagram or theme configuration and rerun both
palettes until every SVG passes.

For zoomable diagram shells, additionally zoom to the maximum and pan to all extremes in both palettes before delivering: the figure caption must stay fully legible throughout (see `references/diagram-shell.md`).

**Plans/proposals** (user should approve/deny):
```bash
plannotator annotate <file> --gate
```

**Everything else** (informational):
```bash
plannotator annotate <file>
```

---

## Plan path

For implementation plans, design docs, feature specs, migration guides, and proposals.

**Before generating, read:**
1. `references/design-system.md`, Plannotator theme tokens, typography, component patterns
2. `references/svg-patterns.md`, inline SVG building blocks for architecture diagrams, flowcharts, data flow

The rest: https://github.com/backnotprop/plannotator/blob/HEAD/apps/skills/extra/plannotator-visual-explainer/SKILL.md