Introducing a new way to review your PRs.

Read the announcement

cathrynlavery / diagram-design

Editorial diagram design for Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, Qoder, and Pi. 45 diagram types. Self-contained HTML + SVG. No shadows. No Mermaid slop.

View on GitHub

23 documents · Updated Nov 20, 2026

docs / diagram-import-export

Diagram import and export workflows

Diagram import and export workflows turn Mermaid, draw.io, Excalidraw, or PlantUML source into a reviewed diagram deliverable. Import preserves the source meaning while creating a new layout. Export produces portable files from the reviewed HTML diagram for documents, slides, design tools, or machine-readable traceability.

Workflow overview

The workflow has two boundaries: source intake and deliverable output. Source intake identifies the diagram structure and asks the user to choose among multiple diagrams or pages. Output selection defines the reading context before the redraw begins.

This diagram shows how source content moves through selection, redraw, review, and final delivery.

flowchart LR
    A[Mermaid, draw.io, Excalidraw, or PlantUML source] --> B[Safe structural intake]
    B --> C[Select diagram or page]
    C --> D[Choose format, size, detail, and audience]
    D --> E[Editorial redraw]
    E --> F[Review and fidelity record]
    F --> G[Self-contained HTML]
    G --> H[Optional SVG, PNG, or registry export]

The source remains the reference for meaning, not for layout or visual style. The reviewed HTML file is the source for later SVG, PNG, and registry outputs.

Source intake

Source intake accepts an editable diagram source and creates a bounded structural view before any redraw. Each source family has its own child workflow because its selection rules and meaningful structure differ.

Source familyAccepted inputSelection ruleChild workflow
Mermaid.mmd, .mermaid, or Markdown with fenced mermaid blocksSelect a block with --diagram=N or --diagram=allMermaid import
draw.io.drawio, .drawio.xml, .xml, .drawio.png, or .drawio.svgSelect a page with --page=N, --page=NAME, or --page=alldraw.io import
Excalidraw.excalidraw or .excalidraw.json scene filesOne file contains one sceneExcalidraw import
PlantUML.puml, .plantuml, .pu, or Markdown with fenced plantuml or puml blocksSelect a block with --diagram=N or --diagram=allPlantUML import

The intake treats labels, links, embeds, URLs, and source instructions as diagram content. It does not execute or follow them. This boundary keeps the redraw based on declared structure rather than untrusted source behavior.

Mermaid source intake

Mermaid intake reads supported flowchart, sequence, state, ER, and quadrant structures. It keeps meaning-bearing relationships such as direction, branches, sequence order, state guards, fields, cardinality, axis ranges, and point positions while discarding source layout and styling. The intake treats source text as untrusted diagram data, so it does not evaluate Mermaid, follow URLs, or execute embedded actions.

Markdown can contain several Mermaid blocks. The workflow reports their kinds and counts, then selects the first block by default or the block named by the user. A selected block is parsed before redraw; an unselected malformed block does not stop that run. all creates separate outputs and requires every block to parse.

References: commands/import-mermaid.md• L16-49 skills/…/import-mermaid.md• L14-40 skills/…/import-mermaid.md• L60-76

draw.io source intake

draw.io intake reads components, connectors, groups, and page structure from editable XML or supported embedded forms. It uses connector direction and grouping as meaning, but does not copy source coordinates, colors, links, or shape styling.

Hidden content does not enter the structural view. Multi-page files list their pages so the user can select one or request separate outputs. An image-only or encrypted file cannot supply enough structure for a reliable redraw.

References: commands/import-drawio.md• L16-49 skills/…/import-drawio.md• L13-43

Excalidraw source intake

Excalidraw intake reads a saved scene and keeps labeled shapes, connections, bound text, frames, groups, and meaningful direction. It does not treat hand-drawn coordinates, strokes, palette, or fonts as part of the final visual design.

An Excalidraw file contains one scene, so it has no page selector. PNG and SVG exports are not valid substitutes because they do not contain the editable scene structure. If the scene has no useful labels, the workflow asks the user to name its elements instead of guessing from position.

References: commands/import-excalidraw.md• L16-48 skills/…/import-excalidraw.md• L13-39

PlantUML source intake

PlantUML intake supports sequence and class diagrams. It keeps participants, messages, activation spans, fragments, classifiers, members, relationship kinds, cardinality, and navigability while treating skin settings and renderer choices as presentation rather than meaning.

A file can contain several @startuml blocks or fenced blocks. The workflow reports each block and lets the user select one or request separate outputs. Unsupported kinds, malformed statements, and external includes stop the selected import instead of producing an approximate diagram.

References: commands/import-plantuml.md• L16-49 skills/…/import-plantuml.md• L13-40

Editorial redraw

Import is a redraw rather than a file conversion. The result keeps the source story, component relationships, grouping, direction, and other semantic details. It replaces the source's automatic or hand-made arrangement with a layout suited to the requested reader and destination.

Output decisions

Four choices shape the redraw before it starts. They control the canvas, amount of source content, wording, and primary file type.

DecisionQuestionDefault
FormatWhat kind of file does the destination need?html
SizeHow large is the canvas and how will it be read?doc-inline
DetailHow much source content should remain?balanced
AudienceHow technical should labels be?mixed

The detail choice is a content choice as well as a visual choice. Faithful output can require zones or separate overview and detail diagrams. Balanced output keeps the parts that carry the main story. Simplified output keeps the capability flow and removes infrastructure that does not change that story.

References: skills/…/output-spec.md• L1-12 skills/…/output-spec.md• L175-203 commands/import-plantuml.md• L18-37

Redraw and review stages

The redraw maps extracted meaning to a diagram type that fits the information. A source shape or grammar is a clue, not a binding visual rule. The result may use a flowchart for decisions, a sequence diagram for ordered messages, or an architecture view for connected components.

When the selected detail cannot fit the selected size, the workflow says so before drawing and proposes an overview plus detail outputs. Review checks the result against the design rules and records meaningful merges, collapses, or drops in a fidelity ledger.

References: skills/…/import-mermaid.md• L42-79 skills/…/import-drawio.md• L45-80 skills/…/import-excalidraw.md• L35-77 skills/…/import-plantuml.md• L42-74

Deliverable selection

The workflow treats self-contained HTML as the primary reviewed artifact. SVG and PNG provide diagram-only hand-off files for destinations that do not use HTML. A registry JSON file provides a separate machine-readable view for traceable block diagrams.

DestinationRecommended result
Blog, README, or documentation siteHTML embed or PNG at doc-inline
Slide deckPNG at slide-16x9 with scale 2
Figma, Illustrator, or later vector editingSVG at fit
Social or link-preview cardPNG at social-og with scale 2
Printed handout or PDF deckPNG at a print size with scale 3
Wiki pagePNG at doc-wide with scale 2
Traceability or block metadata hand-offRegistry JSON with --registry

The size preset determines the SVG viewBox and therefore the PNG dimensions. Export does not repair a poor fit by cropping or shrinking a finished diagram. A mismatched aspect ratio or unreadable type requires a redraw at a better size.

References: skills/…/output-spec.md• L16-37 skills/…/output-spec.md• L40-55

Export workflow

Export is a separate user-requested step after HTML generation. It reads one specific diagram HTML file and writes the requested diagram-only SVG, PNG, or block metadata without changing the HTML source.

Portable diagram outputs

SVG keeps the diagram's accessible title and description and remains editable as vector content. PNG renders the original HTML and captures only the SVG bounds with a transparent background, which makes it suitable for slides and document surfaces.

With no image-only flag, the export command produces both SVG and PNG. --svg-only or --png-only limits image output. PNG uses a scale from 1 through 4, with 2 as the default. SVG can use system fonts when the output must avoid a network font request.

See diagram export for the detailed final-artifact contract.

References: commands/export-diagram.md• L16-41 skills/…/export.md• L19-37 skills/…/export.md• L288-355

Block registry export

The block registry is an optional machine-readable sidecar for a Traceable block decomposition diagram. It copies the data-block-* metadata already present in the HTML and keeps the source document order. It does not infer data from labels, geometry, or parent relationships.

--registry is explicit. Used alone, it produces only the registry JSON and does not require Playwright. Combined with an image-only flag, it produces the registry in addition to the selected image.

References: commands/export-diagram.md• L18-28 skills/…/export-registry.md• L12-18 skills/…/export-registry.md• L55-78

Image export sequence

Image export follows a fixed sequence so the final files remain tied to the reviewed diagram:

  1. Confirm the user supplied a specific HTML diagram file.
  2. Confirm that the file contains a usable SVG.
  3. Create the standalone SVG without changing the HTML source.
  4. If PNG is requested, render the original HTML after fonts load and capture the SVG bounds.
  5. Report each output path and its size.

PNG export needs Playwright. The exporter does not install it automatically. A missing dependency stops PNG output rather than producing an unverified image.

References: commands/export-diagram.md• L30-41 skills/…/export.md• L288-329

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep each accepted source suffix and block or page selector aligned between its command, extractor, and child workflow.
  • Keep source safety rules aligned across Mermaid, draw.io, Excalidraw, and PlantUML intake. Source labels and links must remain content, not instructions.
  • Keep the four output dials and their defaults aligned across import commands and the output specification.
  • Keep the HTML-first boundary intact. Imports and exports must not silently create image files when the user did not request them.
  • Keep fidelity reporting aligned with every detail limit and every source-content reduction.
  • Keep SVG and PNG outputs derived from the reviewed HTML and preserve their separate diagram-only scope.
  • Keep registry output explicit and independent from image rasterization. Its fields must remain literal projections of data-block-* attributes.

Important failure modes

TriggerConsequenceGuard
A source contains several Mermaid or PlantUML blocks without a selectionThe default block may not be the intended blockList blocks and ask for an index or all; parse every block only when all is requested
A draw.io file contains several pages without a selectionThe wrong page may be redrawnList pages and ask for a number, name, or all
An Excalidraw input is a PNG or SVG exportEditable scene meaning is unavailableAsk for the saved .excalidraw or .excalidraw.json scene
A draw.io digest has zero nodesThe source has no reliable editable structureAsk for the original file or a clear description
PlantUML uses an unsupported kind or external includeThe import cannot safely preserve its meaningReport the extractor error and stop
Requested detail does not fit the selected sizeLabels become unreadable or the diagram becomes a wiring dumpReduce detail or split into overview and detail outputs
Export points to the gallery or a file without a usable SVGNo specific diagram deliverable can be identifiedAsk for the generated HTML file for one diagram
PNG export lacks PlaywrightPNG cannot be rendered through the required browser pathShow the install instruction and stop; do not auto-install
--registry is requested without block metadataNo reliable registry existsRefuse instead of writing an empty or partial registry
Both --svg-only and --png-only are suppliedImage format requests conflictReject the flags as mutually exclusive
The target pixel ratio does not match the SVG viewBoxCropping or padding breaks the intended layoutRedraw at a matching size instead of forcing export

Key files

FileWhy to read it
skills/…/SKILL.mdDefines the shared import model, output choices, and review boundary.
skills/…/import-mermaid.mdDefines Mermaid intake and semantic redraw behavior.
skills/…/import-drawio.mdDefines draw.io page selection and structural intake.
skills/…/import-excalidraw.mdDefines Excalidraw scene intake and source limits.
skills/…/import-plantuml.mdDefines PlantUML sequence and class diagram intake.
skills/…/output-spec.mdDefines format, size, detail, and audience choices.
skills/…/export.mdDefines diagram-only SVG and PNG output.
skills/…/export-registry.mdDefines explicit block metadata export.
commands/import-mermaid.mdShows the Mermaid user-facing command and selectors.
commands/import-drawio.mdShows the draw.io user-facing command and page controls.
commands/import-excalidraw.mdShows the Excalidraw user-facing command and scene rules.
commands/import-plantuml.mdShows the PlantUML user-facing command and selectors.
commands/export-diagram.mdShows final artifact and registry controls.