Illustrate

Published from docs/extensions/illustrate.md at 835522e. Edit the source in the repository, not this page.

Purpose: draw diagrams and charts as editable HTML with inline SVG, in your project's tracked color and font theme. It supports 44 diagram types and exports SVG and PNG on request, and an animated SVG or GIF for README images, with arrows that draw, flow, pulse or slide chevrons in their direction.

Lifecycle phase	Any; runs only when you ask
Hooks	Post-write diagram check, opt-in (illustrate.hooks.self_check: true in .specify/workflow.yml)
Commands	generate, export, theme, import (reference)
Requires	Nothing; Python 3.11 or later for export
Required by	Assure, PR, User Manual (Illustrate 2.x)
Standalone	Yes
License	MIT

The extension carries its own version-matched copy of the Illustrate skill under .specify/extensions/illustrate/skill/. It does not need a separately installed skill. The copy is vendored from sanduq-skills.

Setup

specify extension add illustrate

/speckit-illustrate-theme set cobalt light

The theme is stored in .github/illustration-theme.yml. Commit it so local runs and CI draw the same colors and fonts. Cobalt Porcelain, Emerald Mist and Sanduq Classic are built in, each with light and dark modes.

Example

/speckit-illustrate-generate Create a state diagram of refund request, approval, rejection and settlement from the real implementation.
/speckit-illustrate-export docs/refund-approval.html --svg-only
/speckit-illustrate-export docs/refund-approval-animated.html --animated
/speckit-illustrate-export docs/refund-approval.html --gif --arrows pulse
/speckit-illustrate-import docs/legacy/order-flow.mmd --size doc-wide --detail balanced

The process and theme gallery shows the presets and a custom theme.

How it runs

You choose the theme, ask for the diagram, and ask for exports. The agent resolves the theme tokens, applies the diagram type's rules, checks the HTML, and embeds the reviewed output. Editable source.

Post-write check

Set illustrate.hooks.self_check: true in .specify/workflow.yml and a PostToolUse hook checks every HTML file the agent writes or edits that contains an inline SVG (on Codex, every file an apply_patch adds, updates or moves): it runs the skill's self_check.py, verify-geometry.py and illustration_theme.py validate and hands the first failure back to the agent. Spec Kit does not register the hook. The Workflow installer adds it when the key is true and removes it when the key is false. Without Workflow, run python .specify/extensions/illustrate/hooks/self_check_hook.py install --host claude|codex --root . yourself, and uninstall before you remove the extension. On Codex, approve the hook in /hooks once.

Limits

• PNG and GIF export need Playwright and Chromium; GIF also needs Pillow. SVG and animated SVG export need Python.
• An animated SVG has no script or remote fonts and shows the complete figure to readers who prefer reduced motion. A GIF cannot follow that setting, so prefer the SVG where it is allowed.
• Every arrow ends on a straight lead at least its arrowhead long; verify-arrow-ends.py checks it.
• The hand-drawn generator needs Node.js and an npm install in the skill directory.
• Keep the editable HTML beside every export. Review the rendering before you embed it.
• Old Diagram Design installs must migrate: specify extension remove diagram-design, then add illustrate.

Package details: Illustrate README.