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

> Easily export diagrams to PNG and SVG formats using Diagram Design's built-in slash commands for vector or high-resolution raster output. Learn how now.

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

---

**Diagram Design provides built-in slash commands that extract the embedded `<svg>` element for vector output or rasterize it via Playwright for high-resolution PNG assets.**

The `cathrynlavery/diagram-design` repository stores every diagram as a self-contained HTML file. To convert these web-based diagrams into portable image formats, the skill implements a robust export pipeline defined in [`skills/diagram-design/references/export.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md) and exposed through the [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) specification.

## Understanding the Export Architecture

Diagram Design persists diagrams as standalone HTML documents containing embedded SVG markup. When you initiate an export, the system loads the target file, locates the first `<svg>` node, and processes it according to your requested format.

For **SVG export**, the tool injects required Google Fonts directly into the markup, producing a standalone vector file that renders correctly without external dependencies. For **PNG export**, the system launches a Playwright-controlled Chromium instance, renders the SVG at your specified device-scale factor, and captures a raster bitmap.

This architecture ensures vector fidelity for print and scaling workflows while providing pixel-perfect raster assets for presentations and web previews.

## Available Export Commands

The skill exposes three distinct slash commands that invoke the same underlying export logic with different default behaviors.

### Standard Export

Run `/export-diagram` to generate both formats simultaneously.

```bash
/export-diagram path/to/diagram.html

```

This writes `diagram.svg` and `diagram.png` (at 2× scale) adjacent to the source file.

### Format-Specific Exports

Use flags to isolate specific output types:

```bash

# Vector only

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

# Raster only at 3× resolution

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

```

### Natural Language Interface

You can also invoke exports conversationally:

```

"Export this diagram as SVG and PNG."
"Save my-diagram.html as PNG with scale 2."

```

The skill parses these requests and applies sensible defaults before executing the export procedure documented in the reference files.

## Step-by-Step Export Workflows

### Exporting to SVG Format

SVG exports require no external browser dependencies. The workflow implemented in [`skills/diagram-design/references/export.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md) executes as follows:

1. Parses the HTML file to extract the first `<svg>` element
2. Injects Google Fonts CSS into the SVG `<defs>` section to ensure typography renders correctly offline
3. Writes the modified markup to `[filename].svg` or your specified `--output` path

The resulting file is a truly standalone vector graphic suitable for editing in Illustrator, Figma, or Inkscape.

### Exporting to PNG Format

PNG generation requires Playwright installation:

```bash
pip install playwright
playwright install chromium

```

The rasterization process follows these steps:

1. Launches headless Chromium via Playwright
2. Sets viewport to the SVG's native dimensions multiplied by the scale factor (default **2×**, supports **1×**, **2×**, or **3×**)
3. Renders the SVG with full font support
4. Captures screenshot and encodes as PNG

Higher scale factors produce sharper images for retina displays and print materials at 300+ DPI.

## Command Flags and Options

The [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) specification defines the following flags:

- **`--svg-only`** – Skip PNG generation, output vector file only
- **`--png-only`** – Skip SVG generation, output raster file only
- **`--scale={1,2,3}`** – Set PNG resolution multiplier (default: 2)
- **`--output=path/basename`** – Custom output path and base filename without extension

When both format flags are omitted, the command produces both files. When `--output` is specified, the system appends `.svg` or `.png` to your provided basename.

## Edge Cases and Validation

The export logic includes strict guards defined in the command specification and validated at runtime via [`skills/diagram-design/scripts/self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/self_check.py):

- **Missing source file** – Command refuses if no HTML path is supplied
- **Gallery exclusion** – Cannot export [`assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/index.html) because it contains multiple diagram canvases
- **Missing SVG element** – Fails gracefully if the HTML lacks an `<svg>` node
- **Playwright availability** – PNG requests trigger a dependency check; if Playwright is absent, the system displays installation instructions rather than crashing
- **Scale validation** – Rejects scale factors outside 1, 2, or 3

These safeguards ensure that CI pipelines using [`scripts/verify-export.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-export.py) receive deterministic results and clear error messages when constraints are violated.

## Summary

- Diagram Design stores diagrams as HTML files containing SVG markup in the `cathrynlavery/diagram-design` repository
- **SVG export** extracts and font-injects the vector element for standalone use without Playwright
- **PNG export** requires Playwright and Chromium to rasterize the diagram at scale factors of 1×, 2×, or 3×
- Use `/export-diagram` with `--svg-only`, `--png-only`, `--scale`, and `--output` flags to control output formats and destinations
- The system validates inputs against edge cases including missing files, gallery directories, and unsupported scale values

## Frequently Asked Questions

### What is the default PNG resolution?

PNG exports default to **2× scale**, producing images with twice the pixel density of the diagram's native SVG dimensions. You can override this with `--scale=1` for standard resolution or `--scale=3` for ultra-high DPI requirements.

### Why does PNG export require Playwright while SVG does not?

SVG files are pure markup extracted directly from the HTML source. PNG files require rasterization, which necessitates a browser engine to calculate CSS, execute font loading, and render the final pixel buffer. The [`skills/diagram-design/references/export.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md) implementation uses Playwright to automate Chromium for this headless rendering task.

### Can I export multiple diagrams at once?

No. The [`commands/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md) specification explicitly blocks the gallery file ([`assets/index.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/index.html)) and requires single HTML inputs. This design ensures accurate file size reporting and prevents ambiguity in output naming. Batch processing requires scripting multiple individual export commands.

### What happens if the HTML file contains no SVG element?

The command validates the DOM structure before processing and terminates with an error message if no `<svg>` node is detected. This validation occurs early in the workflow defined in the export reference file, preventing empty or corrupted output files.