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. Read references/design-system.md and references/svg-patterns.md. Prescriptive structure.

PR explainer, diff review, or code change walkthrough → Follow the 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. 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):

plannotator annotate <file> --gate

Everything else (informational):

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