Diagram export
Diagram export turns a reviewed, self-contained HTML diagram into a final hand-off artifact. The /diagram-design:export-diagram command is manual and follows the export contract to deliver a diagram-only SVG, a transparent PNG, or an explicit metadata registry without changing the HTML source. This page is a child of Diagram import and export workflows and relates to Mermaid import, draw.io import, and Excalidraw import.
Export boundary
Export starts only after the diagram has been generated and reviewed, and after the user requests an export. The HTML file remains the source of truth because it holds the complete page, the inline SVG, the accessibility name, and the font setup; export creates delivery files from that source and never silently adds them during diagram creation.
The command needs one specific diagram HTML file. It does not accept the gallery as a source because the gallery contains several diagrams, and it does not guess which diagram to use when the source path is missing.
Delivery flow
The export flow preserves the reviewed HTML while selecting only the outputs requested by the user. This diagram shows how the source becomes one or more final hand-off files.
flowchart LR
A[Reviewed diagram HTML] --> B{Requested output}
B -->|SVG| C[Standalone diagram SVG]
B -->|PNG| D[Transparent diagram PNG]
B -->|Registry| E[Block metadata JSON]
B -->|SVG and PNG| C
B -->|SVG or PNG plus registry| E
C --> F[Report paths and sizes]
D --> F
E --> G[Report registry path and size]
References: commands/export-diagram.md• L12-20 commands/export-diagram.md• L30-40 skills/…/export.md• L1-27
Format selection
The requested destination determines the useful hand-off format. HTML is the authored artifact, SVG supports later vector editing, PNG supports fixed visual placement, and the registry supports machine-readable traceability for a special diagram pattern.
| Destination | Recommended output | Key property |
|---|---|---|
| Browser page or documentation site | HTML or PNG | Keeps the full page when HTML is used; PNG is diagram-only |
| Figma, Illustrator, or vector editing | SVG | Keeps vector shapes and text |
| Slides, social cards, wiki pages, or print | PNG | Captures a fixed visual result with transparency |
| Traceability or block metadata hand-off | Registry JSON | Projects authored block attributes into structured data |
The canvas size is chosen before export. The size preset sets the SVG viewBox, and the PNG dimensions come from that viewBox multiplied by the selected scale. Export does not crop, pad, or repair a canvas whose aspect ratio does not match its destination; that requires a redraw with a better size preset.
Image formats
SVG and PNG contain the diagram only. They drop page headers, summary cards, and footers so the result can be placed inside another page or presentation without carrying the HTML wrapper with it.
SVG keeps the diagram's accessible title and description. It also carries the diagram styles and font setup needed for a standalone file. The export gives the root a source-based scope and prefixes referenceable definition IDs, then updates local references. This lets several exported figures share one host document without marker, gradient, filter, clip, mask, symbol, or reusable-shape collisions. CSS rules remain inside their media, support, layer, and container groups. Keyframe names and their bindings receive the same local scope; unsupported nested or unresolved animation bindings fail instead of being changed silently.
The SVG export converts the HTML fragment into well-formed XML. It preserves live diagram content, accessible title and description nodes, and valid comments while ignoring diagrams and styles inside page text, scripts, or comments. It also refuses an invalid or missing viewBox, an incompatible root namespace, and class-based shapes that have no carried diagram CSS. A system-font option omits the remote font import while retaining the diagram CSS.
PNG renders the original HTML and captures only the SVG bounds on a transparent background. This keeps the source page's font loading active and avoids a white rectangle around the diagram. For a motion-enabled source, export requests and verifies the complete static frame after fonts load. Wide diagrams also release page clipping around the SVG before capture so the final image does not lose its right edge.
References: skills/…/export.md• L19-27 skills/…/export.md• L29-71 skills/…/export.md• L278-284 skills/…/export.md• L286-327 skills/…/export_svg.py• L1525-1556 scripts/test-export-svg-standalone.py• L71-80 scripts/test-export-svg-standalone.py• L717-771
Scale selection
The PNG scale controls pixel density, not the diagram's layout. The command defaults to scale 2 and supports finite values from 1 through 4, including fractional values for exact pixel sizes. Use 1 for compact inline assets, 2 for normal documentation and slides, and 3 for print-oriented output.
For an exact pixel target, compare the target aspect ratio with the source viewBox before choosing a scale. A fractional scale can meet an exact width when it stays within the supported range. A scale below 1 makes text soft, and a scale above 4 over-enlarges a layout; either case calls for a redraw at a more suitable preset rather than a forced export.
References: commands/export-diagram.md• L16-28 skills/…/export.md• L329-353
Registry export
The registry is an optional JSON sidecar for a Traceable block decomposition diagram. It copies the data-block-* values already authored on diagram nodes, preserves their document order, and provides structured traceability without trying to infer meaning from labels, geometry, or parent relationships.
The command treats registry generation as a separate procedure from image rasterization. --registry is explicit and independent from image export. When it is the only output flag, the command writes only <basename>.registry.json and does not require Playwright. When combined with --svg-only or --png-only, it adds the registry to the requested image output. A source without any data-block-id attributes is refused rather than producing an empty or partial file.
The registry is a projection, not a validation report. Duplicate IDs, missing parents, and parent cycles remain in the exported data for the separate block-registry verifier to detect; export must not rewrite the source's metadata or silently correct it.
References: commands/export-diagram.md• L18-28 commands/export-diagram.md• L37-40 skills/…/export-registry.md• L1-18 skills/…/export-registry.md• L47-78
Artifact delivery
The command reports every output path and its size after a successful export. By default, image files use the source HTML basename and sit beside it; --output=<path> changes the output base path, after which the selected format extensions are added.
The default image request produces both SVG and PNG. --svg-only skips PNG rendering and therefore skips the browser dependency, while --png-only produces only the raster image. The two image-only flags cannot be used together. The registry follows its own opt-in rule and never appears unless the user requests it.
The delivery contract rejects unsafe or incomplete requests instead of creating guessed artifacts:
- Missing source path requires the user to name an HTML file.
- The gallery file assets/index.html is not a valid export source.
- HTML without an SVG block produces no output.
- PNG export stops with the documented Playwright installation instruction when Playwright is unavailable; the command does not install it.
- A requested output must keep the source's viewBox, accessibility metadata, font setup, and transparent-image behavior intact.
References: commands/export-diagram.md• L16-40 prompts/export-diagram.md• L10-35 skills/…/export.md• L286-327 skills/…/export_svg.py• L1559-1606
Change checklist
When these files or sections are changed, remember to consider these:
- Keep command defaults, prompt defaults, and export reference behavior aligned for image and registry requests.
- Keep output naming consistent for default paths and explicit
--outputbases across SVG, PNG, and registry files. - Keep the HTML-only source boundary intact; export must not modify HTML or emit files without an explicit request.
- Keep SVG accessibility metadata, XML validity, font requests, color normalization, carried diagram CSS, animation bindings, and namespaced definition IDs aligned with the standalone-file contract.
- Keep CSS grouping and animation refusal rules aligned between the packaged SVG helper and its export reference.
- Keep PNG capture tied to the original HTML, loaded fonts, SVG bounds, transparent background, motion state, ancestor clipping, and supported scale values.
- Keep registry field presence, document order, and verbatim attribute values aligned with the Traceable block pattern.
- Keep registry export separate from structural validation; changes to block metadata should also be checked by the block-registry verifier.
- Keep exact-size requests within the source aspect ratio and supported scale range; redraw instead of cropping or forcing a poor fit.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| The source path is missing or points to assets/index.html | Export cannot identify one diagram safely | Ask for the specific generated HTML file |
The source HTML has no SVG, no valid viewBox, or an invalid root namespace | The result cannot be a reliable standalone image | Refuse or warn instead of guessing |
| The exported SVG keeps class-based shapes but loses diagram CSS | The standalone figure can render as black boxes | Carry and scope the diagram styles before writing the SVG |
| Several exported SVGs reuse definition or keyframe names | Markers, gradients, filters, clips, or motion can affect the wrong figure | Namespace local definitions and animation bindings |
| CSS contains an unresolved, ambiguous, or unsupported nested animation binding | The exported file could show the wrong motion | Refuse before writing output and fix the source CSS |
| PNG export runs without Playwright | No reliable browser render is available | Show the install instruction and stop; do not auto-install |
| The source HTML does not load its fonts | PNG text may use substitute fonts and look different | Fix the source font setup before exporting |
The requested aspect ratio does not match the SVG viewBox | Cropping or padding can break safe margins | Redraw at a matching size preset |
--registry is used without data-block-id attributes | The sidecar cannot represent a traceable block tree | Refuse and write no empty registry |
| Registry metadata contains duplicate or broken parent links | The JSON can misrepresent the intended tree | Run the separate block-registry verifier; export preserves source values |
Both --svg-only and --png-only are supplied | The image request is contradictory | Reject the conflicting flags |
Key files
| File | Why to read it |
|---|---|
| commands/export-diagram.md | Defines the user-facing command, defaults, flags, refusal rules, and delivery report. |
| prompts/export-diagram.md | Defines the host prompt path and keeps command invocation aligned with the skill location. |
| skills/…/export.md | Defines diagram-only SVG and PNG behavior, font handling, sizing, CSS grouping, animation handling, definition scoping, and safety boundaries. |
| skills/…/export_svg.py | Provides the packaged standalone SVG transform and its refusal rules. |
| scripts/test-export-svg-standalone.py | Shows the regression contract for CSS carry-over, XML safety, scoped definitions, animation bindings, colors, and output handling. |
| skills/…/export-registry.md | Defines the explicit block metadata sidecar and its projection rules. |
| skills/…/output-spec.md | Defines how destination, canvas size, and pixel scale shape the final artifact. |
| skills/…/SKILL.md | Places export after HTML generation and defines the shared HTML and accessible SVG contract. |
| docs/diagram-import-export.md | Explains how imported source diagrams reach the reviewed HTML artifact that export consumes. |