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 / drawio-import

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:

ChoiceDefaultPurpose
FormathtmlCreates a self-contained diagram file
Sizedoc-inlineFits a body-width document canvas
DetailbalancedKeeps the parts needed for the main story
AudiencemixedUses clear technical wording for a broad audience
VariantlightUses 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.

ChoiceAvailable intentEffect on the result
FormatHTML, SVG, PNG, or HTML plus PNGSelects the delivery artifact
SizeDocument, slide, social, print, or content-fit presetSets the canvas and type scale
Detailfaithful, balanced, or simplifiedSets how much source content survives
Audienceengineer, mixed, or executiveSets 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 --out destinations 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 --out behavior.
  • When the worked redraw changes, preserve its direct focal route and update the regression check if that visual contract changes.

Important failure modes

TriggerConsequenceGuard
Import reads raw draw.io XML instead of the extractor digestCompressed payloads become unreadable and source noise can drive bad design choicesRun drawio_extract.py first and stop on a non-zero exit
Multi-page source has no selected pageThe wrong page can be redrawn or several page types can be mixedList pages and ask, or use --page all for separate outputs
Source exceeds 100 pages or 10,000 direct cells on one pageExtraction stops before the graph can be analyzedSplit the source into smaller draw.io files and retry
Source contains duplicate cell identifiers, a parent cycle, or invalid geometryThe digest cannot safely describe the graphStop on the extractor's exit-2 diagnostic and correct the source
Hidden draft cells are treated as visible source contentUnpublished nodes or edges can appear in the imported artifactExclude hidden cells and descendants during extraction
Source has zero readable nodesThe redraw would invent content from an image or encrypted payloadAsk for the original editable source or a description
Detail level exceeds the canvas budgetLabels and connectors become unreadableReduce detail or split into an overview and per-zone diagrams
The focal gateway-to-orders path gains an elbow in the worked artifactThe main request path no longer matches the expected readable redrawKeep the focal route direct and run the draw.io verifier
Source labels or metadata are treated as instructionsUntrusted diagram content can alter the workflow or the digestTreat source fields as data and escape them in the digest
Reference command name drifts from the slash commandUsers reach a path that verification no longer recognizesRun the draw.io verifier and its regression wrapper
--out points to a missing or invalid destinationThe digest is not written and a false success message can mislead the callerReturn exit 2 with a clear write error and no stdout success line

Key files

FileWhy to read it
commands/import-drawio.mdDefines the user-facing command, defaults, flags, extraction gate, and required import behavior
skills/…/import-drawio.mdDefines the redraw contract, type signals, simplification rules, edge cases, and fidelity ledger
skills/…/drawio_extract.pyProvides the normalized source digest used before design decisions
skills/…/output-spec.mdDefines output formats, canvas presets, detail levels, audience wording, and export constraints
scripts/verify-drawio-import.pyRuns the end-to-end structural, documentation, and output-write checks for the import path
scripts/test-verify-drawio-import.pyProtects the verifier against stale command names and visual route regressions
scripts/fixtures/sample-architecture.drawioSupplies the representative source graph used by the verification path
skills/…/example-import-drawio.htmlShows the expected editorial redraw and accessible HTML/SVG artifact shape
docs/…/import-drawio.pngShows the rendered worked artifact used as the visual reference