How the Export Command Generates SVG and PNG from HTML Diagrams in diagram-design

The export command extracts the first <svg> element from an HTML diagram file to produce standalone SVG assets, and leverages Playwright with headless Chromium to rasterize transparent PNGs with configurable device scale factors.

The cathrynlavery/diagram-design repository provides a specialized export pipeline that converts interactive HTML diagrams into production-ready static assets. This process is invoked via the /diagram-design:export slash command and follows the canonical procedure documented in skills/diagram-design/references/export.md. Both SVG and PNG generation pathways operate on the same source HTML but use fundamentally different extraction techniques to preserve vector fidelity or create rasterized outputs.

SVG Generation from HTML Source

The SVG export pathway creates a standalone, self-contained vector file suitable for embedding in documentation or web pages.

Extracting the Diagram Element

The command reads the source HTML file (for example, example-architecture.html) and locates the first <svg> block using a multiline regex anchored on <svg and </svg>. According to lines 29‑42 of export.md, this extraction targets the primary diagram while explicitly excluding gallery files like assets/index.html that contain multiple SVGs.

Making the SVG Standalone

Once extracted, the SVG undergoes sanitization to ensure it is a valid independent document:

• The opening <svg> tag must include the namespace declaration xmlns="http://www.w3.org/2000/svg"
• A viewBox attribute must be present; if missing, the command warns the user rather than inferring dimensions
• Accessibility attributes are preserved, including role="img", aria-labelledby, <title>, and <desc> elements
• Google Fonts injection occurs via a <defs> block containing a <style> element with an @import statement, XML‑escaping ampersands as &; if <defs> already exists, the style is merged into it

The command prepends the XML declaration <?xml version="1.0" encoding="UTF-8"?> and writes the file as example-architecture.svg adjacent to the source, or to a user‑specified path.

PNG Generation via Playwright Rasterization

PNG export requires a headless browser environment to render the HTML and capture a screenshot of the diagram's bounding box.

Playwright Environment Validation

Before rendering, the command validates that the Python Playwright package and Chromium driver are installed. As documented in lines 55‑68 of export.md, missing dependencies trigger an error message with exact installation instructions rather than a failed capture attempt.

Headless Rendering and Capture

The PNG generation process renders the original HTML file (not the extracted SVG) in a headless Chromium instance:

1. For motion‑enabled diagrams, the command appends ?motion=static to the URL and waits for document.fonts.ready
2. It verifies the root element contains data-frame="static" to ensure the animation has settled
3. It locates the first <svg> element using page.locator("svg").first
4. It captures a screenshot of the SVG's bounding box with omit_background=True to produce a transparent PNG

Device Scale Factor Configuration

The default device_scale_factor is 2, producing crisp output for high‑DPI displays. Users may specify 1, 2, or 3, or provide fractional values for exact pixel targets. The final PNG dimensions equal the SVG's viewBox dimensions multiplied by the scale factor, as implemented in lines 74‑90 of export.md.

Edge Case Handling and Guardrails

The export command includes specific validation logic to prevent ambiguous outputs:

Situation	Response
Gallery files (assets/index.html with multiple SVGs)	Export is refused; user must specify a single diagram file
Missing <svg> element	Command aborts with a message stating the source is not a diagram
Full‑page screenshot requests	Command explains it exports diagram‑only assets and suggests manual screenshot alternatives
Missing Google Fonts	Command warns that Playwright will substitute system fonts, recommending PNG export for pixel‑perfect fidelity

These guardrails are defined in the "Edge cases" section of skills/diagram-design/references/export.md.

Command Architecture and Invocation

The export logic is decoupled from the command interface to maintain single‑source‑of‑truth documentation.

Slash Command Definition

The user interface is defined in commands/export-diagram.md, which exposes the /diagram-design:export <html-file> slash command. This file acts as a router, forwarding the request to the procedural logic without duplicating implementation details.

Prompt Template Orchestration

The agent behavior is governed by prompts/export-diagram.md, which instructs the system to load SKILL.md followed by references/export.md. This ensures the export procedure follows the exact steps documented in the reference material rather than hallucinated alternatives.

Practical Usage Examples

Export a standalone SVG only:

/diagram-design:export path/to/example-architecture.html --svg-only

Generate a high‑resolution PNG at 3× scale:

/diagram-design:export path/to/example-architecture.html --png-only --scale=3

Create both formats simultaneously with default settings:

/diagram-design:export path/to/example-architecture.html

Handle motion‑enabled diagrams (automatically appends ?motion=static):

/diagram-design:export path/to/motion-diagram.html --png-only

Summary

• The export command generates SVG by regex‑extracting the first <svg> block, injecting Google Fonts via <defs>, and ensuring standalone XML compliance
• PNG generation relies on Playwright headless Chromium to screenshot the rendered HTML at configurable scale factors (default 2×)
• The canonical procedure lives exclusively in skills/diagram-design/references/export.md, invoked by commands/export-diagram.md and prompts/export-diagram.md
• Edge cases include gallery file rejection, missing viewBox warnings, and font substitution alerts
• All outputs maintain accessibility attributes (aria-labelledby, <title>) from the original HTML templates such as template-full.html

Frequently Asked Questions

Does the export command require external dependencies for PNG generation?

Yes. The command requires the Python Playwright package and a Chromium browser driver. If these are missing, the command surfaces installation instructions from lines 55‑68 of export.md and aborts rather than attempting a failed render.

Can I export a full HTML page including headers and cards, not just the diagram?

No. The command explicitly targets diagram‑only assets. If you request a full‑page screenshot, the command will explain its limitation and suggest using a manual screenshot tool instead, as documented in the edge cases section of export.md.

How does the command handle animated or motion‑enabled diagrams?

For PNG export of motion diagrams, the command automatically appends ?motion=static to the file URL, waits for document.fonts.ready, and verifies the data-frame="static" attribute before capturing. This ensures the animation is frozen at its static representation.

What happens if the source HTML file does not contain an SVG element?

The command checks for the presence of an <svg> block using regex extraction. If none is found, it reports that the source is not a valid diagram file and aborts the operation without creating empty output files.

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