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 family | Accepted input | Selection rule | Child workflow |
|---|---|---|---|
| Mermaid | .mmd, .mermaid, or Markdown with fenced mermaid blocks | Select a block with --diagram=N or --diagram=all | Mermaid import |
| draw.io | .drawio, .drawio.xml, .xml, .drawio.png, or .drawio.svg | Select a page with --page=N, --page=NAME, or --page=all | draw.io import |
| Excalidraw | .excalidraw or .excalidraw.json scene files | One file contains one scene | Excalidraw import |
| PlantUML | .puml, .plantuml, .pu, or Markdown with fenced plantuml or puml blocks | Select a block with --diagram=N or --diagram=all | PlantUML 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.
| Decision | Question | Default |
|---|---|---|
| Format | What kind of file does the destination need? | html |
| Size | How large is the canvas and how will it be read? | doc-inline |
| Detail | How much source content should remain? | balanced |
| Audience | How 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.
| Destination | Recommended result |
|---|---|
| Blog, README, or documentation site | HTML embed or PNG at doc-inline |
| Slide deck | PNG at slide-16x9 with scale 2 |
| Figma, Illustrator, or later vector editing | SVG at fit |
| Social or link-preview card | PNG at social-og with scale 2 |
| Printed handout or PDF deck | PNG at a print size with scale 3 |
| Wiki page | PNG at doc-wide with scale 2 |
| Traceability or block metadata hand-off | Registry 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:
- Confirm the user supplied a specific HTML diagram file.
- Confirm that the file contains a usable SVG.
- Create the standalone SVG without changing the HTML source.
- If PNG is requested, render the original HTML after fonts load and capture the SVG bounds.
- 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
| Trigger | Consequence | Guard |
|---|---|---|
| A source contains several Mermaid or PlantUML blocks without a selection | The default block may not be the intended block | List 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 selection | The wrong page may be redrawn | List pages and ask for a number, name, or all |
| An Excalidraw input is a PNG or SVG export | Editable scene meaning is unavailable | Ask for the saved .excalidraw or .excalidraw.json scene |
| A draw.io digest has zero nodes | The source has no reliable editable structure | Ask for the original file or a clear description |
| PlantUML uses an unsupported kind or external include | The import cannot safely preserve its meaning | Report the extractor error and stop |
| Requested detail does not fit the selected size | Labels become unreadable or the diagram becomes a wiring dump | Reduce detail or split into overview and detail outputs |
| Export points to the gallery or a file without a usable SVG | No specific diagram deliverable can be identified | Ask for the generated HTML file for one diagram |
| PNG export lacks Playwright | PNG cannot be rendered through the required browser path | Show the install instruction and stop; do not auto-install |
--registry is requested without block metadata | No reliable registry exists | Refuse instead of writing an empty or partial registry |
Both --svg-only and --png-only are supplied | Image format requests conflict | Reject the flags as mutually exclusive |
The target pixel ratio does not match the SVG viewBox | Cropping or padding breaks the intended layout | Redraw at a matching size instead of forcing export |
Key files
| File | Why to read it |
|---|---|
| skills/…/SKILL.md | Defines the shared import model, output choices, and review boundary. |
| skills/…/import-mermaid.md | Defines Mermaid intake and semantic redraw behavior. |
| skills/…/import-drawio.md | Defines draw.io page selection and structural intake. |
| skills/…/import-excalidraw.md | Defines Excalidraw scene intake and source limits. |
| skills/…/import-plantuml.md | Defines PlantUML sequence and class diagram intake. |
| skills/…/output-spec.md | Defines format, size, detail, and audience choices. |
| skills/…/export.md | Defines diagram-only SVG and PNG output. |
| skills/…/export-registry.md | Defines explicit block metadata export. |
| commands/import-mermaid.md | Shows the Mermaid user-facing command and selectors. |
| commands/import-drawio.md | Shows the draw.io user-facing command and page controls. |
| commands/import-excalidraw.md | Shows the Excalidraw user-facing command and scene rules. |
| commands/import-plantuml.md | Shows the PlantUML user-facing command and selectors. |
| commands/export-diagram.md | Shows final artifact and registry controls. |