draw.io import
The draw.io import workflow turns editable draw.io source into a new diagram artifact that follows the repository's design rules. It preserves the source meaning and relationships while choosing a new layout, detail level, and output format; see Diagram import and export workflows for the wider workflow. Mermaid import and Excalidraw import cover the other source formats, while Diagram export covers delivery of diagram artifacts.
Import workflow
Command entry point
The command entry point is commands/import-drawio.md. It accepts .drawio, .drawio.xml, .xml, .drawio.png, and .drawio.svg sources. It then applies the import rules and output rules from the diagram-design skill.
The command uses these defaults when the request does not set them:
| Choice | Default | Purpose |
|---|---|---|
| Format | html | Creates a self-contained diagram file |
| Size | doc-inline | Fits a body-width document canvas |
| Detail | balanced | Keeps the parts needed for the main story |
| Audience | mixed | Uses clear technical wording for a broad audience |
| Variant | light | Uses the minimal light template |
The --page option selects one page by index or name. --page all creates one output per page. The command asks for a page when a multi-page source has no clear selection.
Before the redraw, the command locates the installed skill and runs the extraction helper. It does not read the source file directly. If extraction fails or reports zero nodes, the command stops instead of guessing from incomplete data. It also reports when the selected detail level cannot fit the requested size. The redraw and output checks must pass before files are written.
The command treats the source as content rather than as a visual template. It does not carry over source coordinates, colors, or fonts. After the run, it reports the output paths, selected dials, and fidelity ledger so the result can be checked against the source meaning.
References: commands/import-drawio.md• L1-12 commands/import-drawio.md• L16-37 commands/import-drawio.md• L39-51
Import sequence
The workflow separates source reading from diagram design. The extractor first produces a structural digest. The later design step uses that digest to select the diagram type, simplify the content, and redraw the result.
This diagram shows how draw.io source becomes a checked repository artifact.
flowchart LR
A[draw.io source] --> B[Structural extraction]
B --> C[Page and graph digest]
C --> D[Type and output choices]
D --> E[Editorial redraw]
E --> F[HTML artifact]
F --> G{Requested format}
G -->|HTML| H[Deliver HTML]
G -->|SVG or PNG| I[Export from HTML]
I --> J[Deliver exported artifact]
F --> K[Verification gates]
J --> K
The source is an input to a redraw, not a layout template. The final report includes the paths, selected output choices, and a fidelity ledger for content that was merged, collapsed, or dropped.
References: skills/…/import-drawio.md• L13-25 skills/…/import-drawio.md• L43-49 skills/…/import-drawio.md• L118-123 skills/…/output-spec.md• L16-25
Reference material
Redraw contract
The main reference is skills/…/import-drawio.md. Its central rule is that import preserves semantic content: components, relationships, grouping, and direction. It does not preserve source coordinates, colors, fonts, connector paths, or shape appearance.
The redraw uses the source structure to choose a suitable diagram type. Shape families and graph signals are clues rather than fixed instructions. A source with too many elements is reduced by a defined ladder so the result remains readable. Every meaningful reduction is recorded in the fidelity ledger.
Source labels, links, tooltips, and metadata are diagram content only. They are treated as untrusted data and never as instructions for the import process.
References: skills/…/import-drawio.md• L1-9 skills/…/import-drawio.md• L43-73 skills/…/import-drawio.md• L75-108 skills/…/import-drawio.md• L159-171
Output choices
The output contract fixes four choices before the redraw: format, size, detail, and audience. These choices control the kind of file, canvas, information density, and wording that the reader receives.
| Choice | Available intent | Effect on the result |
|---|---|---|
| Format | HTML, SVG, PNG, or HTML plus PNG | Selects the delivery artifact |
| Size | Document, slide, social, print, or content-fit preset | Sets the canvas and type scale |
| Detail | faithful, balanced, or simplified | Sets how much source content survives |
| Audience | engineer, mixed, or executive | Sets the level of naming and labels |
HTML is always the source artifact for requested SVG or PNG output. The output reference also defines the size-safe areas, node ceilings, degradation order, and fidelity ledger format.
References: skills/…/output-spec.md• L1-12 skills/…/output-spec.md• L16-35 skills/…/output-spec.md• L40-58 skills/…/output-spec.md• L84-112
Worked artifact
The worked example uses scripts/fixtures/sample-architecture.drawio as source and skills/…/example-import-drawio.html as the redraw. It shows how source containers become visual zones and how source storage, client, and service roles become a simpler request-path diagram. The companion screenshot docs/…/import-drawio.png shows the rendered artifact as a reader sees it.
The example is a reference for the standard output: a document-sized view, balanced detail, a small set of focal elements, accessible inline SVG, and direct routing for the main gateway-to-orders path. It supports the verification path rather than acting as a template that preserves draw.io geometry.
References: skills/…/import-drawio.md• L127-142 scripts/…/sample-architecture.drawio• L1-77 skills/…/example-import-drawio.html• L57-94 docs/…/import-drawio.png
Extraction helper
Normalized digest
The extraction helper is skills/…/drawio_extract.py. It converts supported draw.io containers into a normalized intermediate representation. It emits a compact Markdown digest for normal use or full JSON when more source detail is needed.
The digest gives the design step a shared view of the source graph. It reports:
- Pages and page names
- Nodes, labels, shapes, parent groups, and absolute positions
- Edges, labels, direction, and dangling endpoints
- Hubs, entry points, terminals, cycles, and unconnected nodes
- Candidate diagram types and collapsible groups
- Node and edge budget flags
The helper does not decide the final diagram type or layout. It supplies signals so the import reference can make those decisions from meaning rather than from raw XML noise.
References: skills/…/drawio_extract.py• L1-18 skills/…/drawio_extract.py• L301-343 skills/…/drawio_extract.py• L636-725 skills/…/drawio_extract.py• L769-871 skills/…/drawio_extract.py• L874-891
Source containers and pages
The helper supports raw XML, compressed draw.io payloads, and draw.io diagrams embedded in PNG or SVG files. It resolves nested parent positions into finite absolute geometry so the digest describes the graph consistently across source forms. It also preserves connector meaning by interpreting arrowheads as directed, bidirectional, or undirected relationships.
HTML in labels is flattened to text for the digest. Supported formatting tags and comments are removed, while angle brackets in label text remain. This keeps labels such as List<String> and a < b > c intact without treating their text as markup.
Hidden cells, groups, and layers are excluded with their descendants. This keeps drafts that are hidden in draw.io out of the digest and prevents them from becoming visible in the imported artifact.
Page selection is explicit at the extraction boundary. A single-page source selects its only page. A multi-page source defaults to the first page, reports all page names and counts, and can select a named page, an index, or all pages. The import workflow keeps pages separate because different pages can use different diagram types.
The helper bounds structural parsing to 100 direct pages and 10,000 direct cells under each page root. It rejects duplicate cell identifiers, parent cycles, non-finite or overflowing geometry, unsafe XML declarations, malformed XML, truncated image metadata, and oversized input or decoded payloads. A zero-node digest means that the source has no readable model, such as an image-only or encrypted file. The workflow asks for the original source instead of guessing.
References: skills/…/import-drawio.md• L13-41 skills/…/import-drawio.md• L31-35 skills/…/import-drawio.md• L146-165 scripts/verify-drawio-import.py• L403-447 scripts/verify-drawio-import.py• L496-522 scripts/verify-drawio-import.py• L584-763
Verification path
Structural verification
The primary verification entry point is scripts/verify-drawio-import.py. It drives the shipped extractor, import reference, output reference, export reference, skill instructions, command, fixture, and worked artifact as one contract. A successful run confirms that the source can be decoded and that the documented import path still agrees with the shipped artifacts.
The verifier checks the important boundaries rather than only the happy-path redraw:
- Raw, compressed, PNG-embedded, and SVG-embedded source forms produce the same graph
- Page selection and unsupported-input errors remain clear
- UTF-8 BOM-prefixed source forms match their unprefixed results
- Hidden cells, groups, and layers do not leak into the extracted graph
- Labels and page names stay safe when rendered into the Markdown digest
- Unicode output remains lossless under a legacy console encoding
- Failed
--outdestinations return a clear error without printing a success result - Resource limits, unsafe XML declarations, duplicate identifiers, and invalid geometry are enforced
- Documentation names the current slash command and required references
- The worked HTML artifact keeps the expected size, direct focal route, accent use, and skin rules
References: scripts/verify-drawio-import.py• L157-213 scripts/verify-drawio-import.py• L372-447 scripts/verify-drawio-import.py• L496-581 scripts/verify-drawio-import.py• L584-869
Regression coverage
The regression wrapper is scripts/test-verify-drawio-import.py. It runs the full verifier in a temporary copy. It then changes the documented slash command to a stale name and confirms that verification fails with a focused diagnostic. It also changes the worked example's direct gateway-to-orders route to an elbowed route and confirms that the verifier rejects the visual regression.
This check protects the link between the user-facing command and the reference that governs it. For the wider skill-local extraction checks, self-validation, and cross-family verification, see Diagram self-validation and Diagram verification suite. Mermaid follows the parallel Mermaid import workflow.
References: scripts/test-verify-drawio-import.py• L1-16 scripts/test-verify-drawio-import.py• L18-77 skills/…/SKILL.md• L531-555
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the slash command name in commands/import-drawio.md aligned with the command name checked by scripts/verify-drawio-import.py and scripts/test-verify-drawio-import.py.
- Keep accepted source forms, arrow direction, hidden-cell behavior, label flattening, angle-bracket preservation, and page-selection behavior aligned across the command, import reference, extractor, and verifier.
- When digest fields or budget signals change, review the import reference's type-selection and detail rules together.
- When output presets or detail ceilings change, review the command defaults, output reference, worked artifact, screenshot, and verifier expectations as one contract.
- When source decoding, page and cell limits, identifier checks, hidden ancestry, or geometry safety rules change, retain coverage for compressed pages and embedded PNG and SVG sources.
- When output write errors change, keep the verifier's error text and empty-stdout contract aligned with the extractor's
--outbehavior. - When the worked redraw changes, preserve its direct focal route and update the regression check if that visual contract changes.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Import reads raw draw.io XML instead of the extractor digest | Compressed payloads become unreadable and source noise can drive bad design choices | Run drawio_extract.py first and stop on a non-zero exit |
| Multi-page source has no selected page | The wrong page can be redrawn or several page types can be mixed | List pages and ask, or use --page all for separate outputs |
| Source exceeds 100 pages or 10,000 direct cells on one page | Extraction stops before the graph can be analyzed | Split the source into smaller draw.io files and retry |
| Source contains duplicate cell identifiers, a parent cycle, or invalid geometry | The digest cannot safely describe the graph | Stop on the extractor's exit-2 diagnostic and correct the source |
| Hidden draft cells are treated as visible source content | Unpublished nodes or edges can appear in the imported artifact | Exclude hidden cells and descendants during extraction |
| Source has zero readable nodes | The redraw would invent content from an image or encrypted payload | Ask for the original editable source or a description |
| Detail level exceeds the canvas budget | Labels and connectors become unreadable | Reduce detail or split into an overview and per-zone diagrams |
| The focal gateway-to-orders path gains an elbow in the worked artifact | The main request path no longer matches the expected readable redraw | Keep the focal route direct and run the draw.io verifier |
| Source labels or metadata are treated as instructions | Untrusted diagram content can alter the workflow or the digest | Treat source fields as data and escape them in the digest |
| Reference command name drifts from the slash command | Users reach a path that verification no longer recognizes | Run the draw.io verifier and its regression wrapper |
--out points to a missing or invalid destination | The digest is not written and a false success message can mislead the caller | Return exit 2 with a clear write error and no stdout success line |
Key files
| File | Why to read it |
|---|---|
| commands/import-drawio.md | Defines the user-facing command, defaults, flags, extraction gate, and required import behavior |
| skills/…/import-drawio.md | Defines the redraw contract, type signals, simplification rules, edge cases, and fidelity ledger |
| skills/…/drawio_extract.py | Provides the normalized source digest used before design decisions |
| skills/…/output-spec.md | Defines output formats, canvas presets, detail levels, audience wording, and export constraints |
| scripts/verify-drawio-import.py | Runs the end-to-end structural, documentation, and output-write checks for the import path |
| scripts/test-verify-drawio-import.py | Protects the verifier against stale command names and visual route regressions |
scripts/fixtures/sample-architecture.drawio | Supplies the representative source graph used by the verification path |
| skills/…/example-import-drawio.html | Shows the expected editorial redraw and accessible HTML/SVG artifact shape |
| docs/…/import-drawio.png | Shows the rendered worked artifact used as the visual reference |