How to Import draw.io Diagrams into diagram-design: A Complete Guide

diagram-design imports draw.io files by treating them as source content rather than literal layouts, extracting structural data into an intermediate representation, and redrawing diagrams from scratch to conform to the project's strict style guide and 4 px grid.

The cathrynlavery/diagram-design repository provides a specialized pipeline for importing .drawio, .drawio.xml, .drawio.png, and .drawio.svg files. When you import draw.io diagrams into diagram-design, the system decodes deflate-plus-base64 payloads, discards original coordinates and fonts, and regenerates clean visualizations mapped to the skill's semantic color system and shape vocabularies.

The Three-Stage Import Pipeline

Stage 1: Extraction and Intermediate Representation

The process begins in skills/diagram-design/scripts/drawio_extract.py, which reads the supplied draw.io file and decodes any embedded payloads. The script produces a normalized intermediate representation (IR) that captures node hierarchies, edge connections, and shape types while stripping presentation details. By default, the extractor emits a compact Markdown digest to stdout, but you can output full JSON for custom processing or debugging by passing the --json flag.

Stage 2: Analysis and Planning

The IR feeds into the reference logic defined in skills/diagram-design/references/import-drawio.md. The system analyzes structural signals—including node count, container depth, cycle detection, and hub ranking—to select the appropriate diagram type (sequence, flowchart, architecture, etc.). From this analysis, the skill configures the four dials: format (html, svg, png, or html+png), size preset, detail level (faithful, balanced, or simplified), and audience (engineer, mixed, or executive).

Stage 3: Redraw and Layout Generation

In the final stage, diagram-design generates a fresh layout on a 4 px grid, completely discarding original positions, colors, and connector routes. Shape vocabularies map to the design system—cylinders become store boxes, rhombuses become decision diamonds (in flowcharts), and icons render monochrome. Connectors reroute to orthogonal elbows with unnecessary edges pruned. The pipeline outputs a self-contained HTML file; optional SVG or PNG exports are handled via the export.md pipeline. The process concludes with a fidelity ledger documenting merged, collapsed, or dropped elements.

Command-Line Usage and Options

Basic Import Commands

Use the diagram-design:import slash command to process a draw.io file. The default behavior generates an HTML diagram adjacent to the source file using automatic type detection and balanced detail settings.

diagram-design:import my-arch.drawio

Explicit Configuration

Override the automatic dials by specifying format, size, detail level, and audience explicitly. This ensures the output matches your publication requirements.

diagram-design:import my-arch.drawio \
  --format html \
  --size doc-inline \
  --detail balanced \
  --audience mixed

Handling Multi-Page Files

For multi-page draw.io files, specify a single page number or import all pages at once. Without the --page flag, the system lists available pages with node and edge counts and prompts for selection.

# Import a specific page

diagram-design:import my-multi.drawio --page 2

# Import all pages

diagram-design:import my-multi.drawio --page all

Extracting Raw Data for Debugging

Access the underlying Python script directly to generate the JSON IR or view the Markdown digest for inspection before redrawing.

# Generate raw JSON IR

python3 skills/diagram-design/scripts/drawio_extract.py my-arch.drawio --json > arch.json

# View the Markdown digest

python3 skills/diagram-design/scripts/drawio_extract.py my-arch.drawio | head -20

Handling Edge Cases and Fidelity Rules

When importing complex or unusual source files, diagram-design applies specific handling rules documented in skills/diagram-design/references/import-drawio.md:

• Zero-node detection: If the digest shows 0 nodes, the source is image-only or encrypted. The system requests the original .drawio file to proceed.
• Node budget limitations: If requested detail exceeds the practical node budget for the selected size, the pipeline offers an overview plus per-zone detail views rather than attempting a faithful but illegible redraw.
• Color mapping: Source colors are mapped to semantic roles (backend, external, accent) according to the color-mapping table in the reference file, ensuring palette consistency.
• Unknown shapes: Unrecognized shapes or custom icons render using generic primitive definitions from the design system rather than failing.

Key Implementation Files

The import functionality relies on four primary components:

• commands/import-drawio.md — Defines the slash-command interface and user-visible flags.
• skills/diagram-design/references/import-drawio.md — Contains the full import specification, type heuristics, and fidelity-ledger rules.
• skills/diagram-design/scripts/drawio_extract.py — Core extractor that produces the intermediate representation.
• assets/example-import-drawio.html — Sample output demonstrating a successful 12-node architecture import.

Summary

• diagram-design imports draw.io files through a three-stage pipeline: extraction, analysis, and redraw.
• The drawio_extract.py script decodes .drawio files and emits an intermediate representation used by the analysis logic.
• Users control output via the diagram-design:import command with flags for format, size, detail, audience, and page selection.
• The system always redraws from scratch on a 4 px grid, mapping shapes and colors to the project's design system rather than preserving original styling.
• Edge cases like multi-page files, encrypted content, and unknown shapes are handled with specific fallback strategies documented in the reference files.

Frequently Asked Questions

What file formats does diagram-design support for draw.io import?

The drawio_extract.py script accepts .drawio, .drawio.xml, .drawio.png, and .drawio.svg files. It automatically detects and decodes deflate-plus-base64 payloads within these formats to extract the underlying graph structure.

How does diagram-design handle multi-page draw.io files?

Without the --page flag, the system lists all pages with their node and edge counts and asks the user which to import. You can specify --page 2 for a single page or --page all to process every page in the file.

Why does diagram-design redraw diagrams instead of preserving the original layout?

The skill treats draw.io files as source content to be reinterpreted rather than copied. Redrawing ensures conformance to the editorial style guide, enforces the 4 px grid system, maps colors to semantic roles, and produces clean orthogonal connectors that remain editable within the diagram-design ecosystem.

What happens if the source file contains encrypted content or no extractable nodes?

When the extraction yields 0 nodes, indicating an image-only or encrypted source, the pipeline halts and requests the original .drawio file. This prevents the import of non-semantic bitmaps that cannot be analyzed or redrawn as structured diagrams.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}