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

> Learn how the diagram-design export command generates SVG from HTML and PNG using Playwright headless Chromium. Create custom diagram assets easily.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-15

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/export.md), this extraction targets the primary diagram while explicitly excluding gallery files like [`assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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 `&amp;`; 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/prompts/export-diagram.md), which instructs the system to load [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) followed by [`references/export.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

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

```

Generate a high‑resolution PNG at 3× scale:

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

```

Create both formats simultaneously with default settings:

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

```

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

```bash
/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md), invoked by [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) and [`prompts/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.