# How to Export Diagrams in SVG and PNG Formats in Diagram Design

> Easily export diagrams in SVG and PNG formats using the diagram-design export-diagram command. Get vector or rasterized images with optional scaling for your projects.

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

---

**Export diagrams as SVG and PNG files by running the `/diagram-design:export-diagram` command against any HTML diagram file, which extracts the embedded `<svg>` element for vector output and uses Playwright to rasterize the PNG with optional scaling.**

The `cathrynlavery/diagram-design` repository stores diagrams as self-contained HTML files that embed scalable vector graphics. When you need production-ready assets for documentation, presentations, or web publishing, the export system generates clean, diagram-only artifacts without surrounding HTML wrappers.

## Understanding the Export Architecture

Diagram Design treats each `.html` file as the canonical source. According to [[`skills/diagram-design/references/export.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md), the export command performs a deterministic transformation that respects accessibility metadata and visual fidelity. The system distinguishes between **vector extraction** (SVG) and **rasterization** (PNG), with the latter requiring a browser environment to resolve final visual states including loaded fonts and static motion frames.

## Prerequisites for PNG Export

PNG generation requires Playwright with Chromium support. As documented in [[`skills/diagram-design/references/doctor.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/doctor.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/doctor.md), install the runtime before your first export:

```bash
pip install playwright && playwright install chromium

```

SVG exports require no external dependencies—the `<svg>` node is extracted directly from the DOM without browser rendering.

## Basic Export Commands

The slash-command definition in [[`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md)](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) supports several invocation patterns. By default, the command produces both formats in the source file's directory.

### Export Both Formats

```markdown
/diagram-design:export-diagram path/to/diagram.html

```

This creates `path/to/diagram.svg` and `path/to/diagram.png` using the base name of the HTML source.

### Export SVG Only

```markdown
/diagram-design:export-diagram path/to/diagram.html --svg-only

```

The system extracts the `<svg>` element directly, preserving the `<title>` and `<desc>` elements for accessibility while omitting surrounding HTML wrappers.

### Export PNG Only

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

```

Playwright renders the page, waits for `document.fonts.ready`, and captures the SVG's bounding box.

## PNG Rasterization Details

When generating PNG files, the export routine loads the HTML in a headless browser to resolve the final visual state. The process documented in [[`skills/diagram-design/references/export.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md) includes:

- **Motion handling**: Applies `?motion=static` for motion-enabled diagrams to freeze animations
- **Font resolution**: Blocks until `document.fonts.ready` resolves, ensuring custom web fonts render correctly
- **Transparent backgrounds**: Uses `omit_background=True` for alpha-channel support
- **Output naming**: Saves to `diagram.png` in the same directory as the source HTML

### Scaling PNG Output

Control rasterization resolution with the `--scale` factor:

```markdown
/diagram-design:export-diagram path/to/diagram.html --png-only --scale=2

```

This generates a high-DPI PNG at double the native SVG resolution, suitable for retina displays or print media.

## Generating the Registry Sidecar

For downstream tooling that requires block-level metadata, add the `--registry` flag to emit a [`.registry.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.registry.json) file:

```markdown
/diagram-design:export-diagram path/to/diagram.html --registry

```

As specified in [[`skills/diagram-design/references/export-registry.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export-registry.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export-registry.md), this sidecar captures `data-block-*` attributes from the HTML. The command validates that `data-block-id` attributes exist before writing the registry; it refuses to emit empty metadata files and alerts the user accordingly. This operation does not require Playwright and executes independently of SVG or PNG generation.

## Validation and Safety

The export system enforces strict user consent. It will not infer source paths or export empty diagrams. If you supply the `--registry` flag without block identifiers present in the HTML, the command aborts with a descriptive error rather than creating an empty JSON file.

## Summary

- **SVG exports** extract the `<svg>` node directly from the DOM, preserving accessibility metadata (`<title>` and `<desc>`) and creating diagram-only artifacts without HTML wrappers.
- **PNG exports** require Playwright and Chromium to render fonts and static motion states, producing transparent-background images with configurable `--scale` factors.
- **Output locations** mirror the source HTML directory structure, using identical base filenames with appropriate extensions.
- **Registry sidecars** ([`.registry.json`](https://github.com/cathrynlavery/diagram-design/blob/main/.registry.json)) capture block-level metadata but only when `--registry` is explicitly requested and valid `data-block-id` attributes exist.

## Frequently Asked Questions

### Does the export command work offline?

SVG exports function entirely offline since they parse the local HTML file directly. PNG exports require an internet connection during the first run to download Chromium via Playwright, but subsequent exports cache the browser binaries and work offline unless the diagram references remote fonts that must load during rendering.

### Can I customize the background color of PNG exports?

The PNG export uses `omit_background=True` by default, producing transparent backgrounds. The repository documentation in [[`skills/diagram-design/references/export.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md) does not specify background color overrides; you would need to modify the SVG's own background properties or post-process the rasterized image.

### What happens if the HTML file contains no diagram?

The export command validates content before writing files. It refuses to export empty diagrams and will exit with an error message rather than creating zero-byte or placeholder SVG/PNG files. Similarly, requesting `--registry` output on files without block identifiers results in a refusal to emit empty metadata.

### Are animated diagrams supported?

Yes, but with limitations. The export process appends `?motion=static` to the URL when rendering PNGs, freezing animations at their static state. The SVG export captures the current state of the DOM as-is, preserving any SMIL or CSS animations within the markup itself, though the PNG will always show the motionless frame.