How to Export Diagrams from Diagram Design: SVG and PNG Export Guide

Diagram Design exports diagrams as standalone SVG files or rasterized PNG images using slash commands like /export-diagram or natural language requests to your AI agent.

The export flow in cathrynlavery/diagram-design converts generated HTML diagram files into production-ready formats. According to the source code, this is a manual-only operation that never modifies source files or adds UI elements. The implementation lives in skills/diagram-design/references/export.md, with command definitions in commands/export-diagram.md.

Triggering the Diagram Design Export Flow

You have two ways to initiate an export:

• Slash commands: Use /export-diagram path/to/diagram.html in Pi, or /diagram-design:export-diagram in Claude Code and Codex
• Natural language: Simply ask "export this diagram as SVG" or "save my-diagram.html as PNG"

Both entry points delegate to the same procedure defined in the export reference file. According to the source code, if you omit the source path, the agent prompts you to specify a .html file.

Exporting Diagrams as SVG

The SVG export process in Diagram Design creates self-contained, web-ready vector files.

How SVG Export Works

1. The source HTML is read and the first <svg> element is extracted (the skill generates single SVGs except for gallery files)
2. Missing xmlns attributes are added, original viewBox is preserved, and accessibility attributes (role="img", aria-labelledby, <title>, <desc>) remain untouched
3. Google Fonts are injected via XML-escaped @import inside a <defs><style> block, merging with existing <defs> if present
4. An XML declaration is prefixed and the file writes as <basename>.svg

/export-diagram path/to/diagram.html --svg-only

The resulting SVG is fully self-contained and ready for embedding or direct use.

Exporting Diagrams as PNG

The PNG export requires Playwright for headless browser rasterization.

PNG Export Requirements

Before rasterizing, the command verifies that Python playwright is installed. If missing, the agent displays this exact message and aborts:

Playwright isn't installed. To enable PNG export, run:
pip install playwright
playwright install chromium
Then ask me to export again.

PNG Export Process

Once Playwright is available:

1. Chromium launches and loads the original HTML (not the extracted SVG)
2. Waits for network idle, then screenshots the first <svg> element with transparent background
3. Device scale factor defaults to 2 for crisp output; override with --scale=1|2|3
4. Writes <basename>.png beside source or to --output path

/export-diagram path/to/diagram.html --png-only --scale=3

Export both formats simultaneously by omitting format flags:

/export-diagram path/to/diagram.html --scale=2

Edge Cases and Validation

The Diagram Design exporter handles several edge cases explicitly:

• Gallery file rejection: Exporting assets/index.html is refused; the agent prompts for a specific diagram file
• Missing SVG detection: If HTML contains no <svg> element, export rejects with an error message
• Scale validation: Invalid --scale values outside {1,2,3} cause immediate rejection
• Path resolution: Output defaults to source directory unless --output specifies otherwise

After successful generation, the agent reports absolute paths and file sizes of created files.

Key Files in Diagram Design Export

File	Role
commands/export-diagram.md	Slash command syntax and required behavior
skills/diagram-design/references/export.md	Full SVG/PNG procedure, edge cases, Playwright detection
skills/diagram-design/assets/template.html	Example HTML scaffold that export commands operate on

Summary

• Trigger exports via /export-diagram slash commands or natural language requests to Pi, Claude Code, or Codex
• SVG export extracts, sanitizes, and self-containes the first <svg> with Google Fonts injected via <defs>
• PNG export requires Playwright; launches Chromium, screenshots at scale factor 2 by default (configurable 1-3)
• No automatic exports: The flow is manual-only, never adds buttons or scripts, never modifies source HTML
• Edge cases handled: Gallery files rejected, missing SVGs caught, invalid scales blocked

Frequently Asked Questions

Can I export diagrams from Diagram Design without Playwright installed?

Yes, but only to SVG format. PNG export requires Playwright. If you attempt PNG export without it, the agent shows the exact installation commands (pip install playwright && playwright install chromium) and aborts. SVG export has no external dependencies.

What scale factor should I use for PNG export from Diagram Design?

The default scale of 2 is recommended for most use cases. This provides crisp, retina-ready output. Use --scale=1 for smaller file sizes or --scale=3 for maximum resolution printing. The source code enforces only values 1, 2, or 3.

Why can't I export the gallery file from Diagram Design?

The gallery file (assets/index.html) is explicitly blocked from export. As implemented in skills/diagram-design/references/export.md, this prevents accidental export of multi-diagram compilations. The agent prompts you to specify an individual diagram HTML file instead.

Does Diagram Design modify my original HTML files during export?

No. The export flow is strictly read-only. According to the source code, it never modifies source HTML, never adds export buttons or scripts, and never performs full-page screenshots unless you explicitly request them with natural language.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}