How to Export Diagrams to PNG and SVG with Proper Font Handling in Diagram-Design

Export diagrams to PNG and SVG with proper font handling by using the /export-diagram command, which extracts vector graphics with injected Google Font links for SVG outputs and uses Playwright to rasterize HTML only after document.fonts.ready resolves for PNG outputs.

Diagram-Design stores every diagram as a self-contained HTML file, making the export process inherently tied to the original rendering context. To export diagrams to PNG and SVG with proper font handling in Diagram-Design, you must understand how the system preserves typography through distinct vector and raster pipelines defined in the skill references.

Understanding the Export Workflow in Diagram-Design

The export workflow follows a strict routing path from command invocation to file generation, ensuring that both SVG and PNG outputs reflect the exact visual state of the source HTML.

Command Invocation and Routing

Exporting begins when you invoke the slash command /export-diagram (or the fully qualified /diagram-design:export-diagram for agent contexts). According to [commands/export-diagram.md](https://github.com/cathrynlavery/diagram-design/blob/main/commands/export-diagram.md), this command immediately forwards all arguments to [skills/diagram-design/references/export.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md), which serves as the single source of truth for all export logic.

SVG Extraction and Font Injection

For SVG generation, the exporter extracts the <svg> element directly from the HTML source. Before writing the file, it injects Google Font <link> tags into the SVG document (see lines 27-63 in export.md). This ensures that when the SVG opens in browsers, Figma, or Adobe Illustrator, it loads the exact web fonts—such as Instrument Serif and Geist—used in the original diagram. No rasterization occurs during this process; the output remains a pure vector graphic with embedded font references.

PNG Rasterization with Playwright

PNG export utilizes Playwright to launch headless Chromium and render the original HTML. Critically, the renderer waits for document.fonts.ready (line 67 in export.md) before capturing the screenshot. This guarantees that all remote Google Fonts have fully loaded, preventing fallback font substitution in the final image. The system then screenshots only the <svg> element's bounding box, producing a transparent-background PNG that matches the on-screen rendering pixel-for-pixel.

Handling Motion and Animation States

If the source HTML contains motion parameters (e.g., ?motion=static or specific animation steps), the exporter forces the diagram into its static final state before capture (lines 83-84 in export.md). This deterministic approach ensures that animated diagrams produce consistent, predictable images regardless of when the export command executes.

Font Handling Mechanisms for Vector and Raster Outputs

Proper font handling requires different strategies for SVG vector outputs versus PNG raster outputs, each addressing the unique constraints of the target format.

SVG Font Embedding

The SVG exporter adds a <style> block containing the same Google Font URLs present in the source HTML (<link href="https://fonts.googleapis.com/css2?...">). Because the SVG functions as a standalone document, any viewer with internet access can fetch these URLs and render text using the precise typefaces defined in the original diagram. This approach maintains editability and scalability without bundling font files directly into the SVG.

PNG Font Rendering Guarantees

For PNG outputs, font fidelity depends entirely on the rendering pipeline's timing. By waiting for the document.fonts.ready Promise to resolve, the Playwright-based renderer ensures that the rasterized image reflects real font metrics rather than system fallbacks. If the source HTML lacks the Google Font <link> tag, the exporter warns that the PNG may use substitute fonts. Always use the latest template*.html files provided in the repository, which include the necessary font links by default.

Command-Line Options and Usage Examples

The export-diagram command supports multiple flags to control output formats, resolution, and metadata generation.

Basic Export Commands

Generate both formats simultaneously:

export-diagram path/to/diagram.html

Export only SVG for vector editing workflows:

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

Generate high-resolution PNG at 3× scaling:

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

Registry and Metadata Export

Emit a side-car JSON file containing all data-block-* attributes alongside your images:

export-diagram path/to/diagram.html --registry

Combine flags to export PNG with registry data but skip SVG generation:

export-diagram path/to/diagram.html --png-only --registry

Agent-Specific Syntax

For Claude Code, use the fully qualified command:

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

For Pi, Codex, or Factory Droid, use the standard slash command:

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

Common Pitfalls and Troubleshooting

Avoid these frequent issues when exporting diagrams to ensure proper font handling and visual fidelity.

• Missing Font Links: Verify that your source HTML contains the Google Font <link> tag present in all template*.html files. Manual edits that remove this tag cause font fallback warnings.
• Motion Artifacts: Always append ?motion=static to the HTML filename or specify a named step before exporting animated diagrams. Exporting without this parameter captures the current animation frame, resulting in inconsistent outputs.
• Gallery Misrouting: Do not attempt to export assets/index.html (the gallery file), as it contains multiple diagrams. Point the command at individual diagram HTML files only.

Summary

• Diagram-Design exports originate from self-contained HTML files, ensuring visual consistency between the source and output.
• SVG exports inject Google Font <link> tags to maintain typography across different viewers and editing software.
• PNG exports rely on Playwright rendering with document.fonts.ready verification to prevent font substitution during rasterization.
• The --scale parameter controls PNG resolution, while --registry generates JSON metadata side-cars.
• Always use provided HTML templates to ensure proper font links, and append ?motion=static for deterministic animated diagram exports.

Frequently Asked Questions

Why does my exported PNG show different fonts than the original diagram?

Your PNG likely rendered before the Google Fonts loaded completely. The Diagram-Design exporter waits for document.fonts.ready to resolve before capturing the screenshot (see line 67 in skills/diagram-design/references/export.md), but if the HTML lacks the Google Font <link> tag entirely, the system has no remote fonts to fetch and falls back to system defaults. Ensure your HTML includes the font links present in the official template*.html files.

Can I edit the text in exported SVG files after generation?

Yes. The SVG exporter embeds <style> blocks referencing the original Google Font URLs, allowing you to edit text in vector graphics editors like Adobe Illustrator or Figma. Because the SVG references live font URLs rather than embedding font files, you must have internet connectivity for the fonts to render correctly in your editing software.

How do I export a specific frame of an animated diagram?

Append ?motion=static to your HTML filename before running the export command, or specify a particular animation step in your motion parameters. According to export.md (lines 83-84), the exporter automatically forces the diagram into its static final state when these parameters are present, ensuring deterministic image capture regardless of animation timing.

What is the registry JSON file used for?

The --registry flag generates a side-car JSON file containing all data-block-* attributes from the diagram's HTML elements, as defined in [references/export-registry.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export-registry.md). This metadata facilitates programmatic analysis and third-party integrations by exposing the structured data behind the visual representation without affecting the image generation process itself.

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