How to Import draw.io Diagrams into the Diagram Design Tool: A Complete Technical Guide

The Diagram Design tool imports draw.io diagrams by executing the drawio_extract.py script, which deterministically normalizes raw draw.io XML into a structured intermediate representation through a secure, three-pass parsing pipeline.

Importing draw.io diagrams into the Diagram Design tool requires understanding the deterministic extraction pipeline that transforms proprietary draw.io formats into a normalized intermediate representation. This guide explains the complete technical flow implemented in the cathrynlavery/diagram-design repository, from secure payload extraction to the final Markdown digest generation that drives the rendering pipeline.

Supported draw.io File Formats

The extractor in skills/diagram-design/scripts/drawio_extract.py accepts multiple draw.io variants to maximize compatibility. You can import diagrams using the following extensions:

• .drawio – Standard uncompressed XML format
• .xml – Raw XML exports from draw.io
• .drawio.png – PNG images with embedded draw.io XML metadata
• .drawio.svg – SVG files containing embedded diagram data

The script handles three distinct payload types: raw XML strings, compressed base‑64 encoded payloads, and XML embedded within image chunks. This multi-format support ensures that whether you export directly from the draw.io editor or save diagrams as images, the Diagram Design tool can extract the underlying structure.

The Extraction Pipeline in drawio_extract.py

The import process follows a deterministic pipeline that never makes design decisions—it only normalizes data. The core extractor implements security checks and multi-pass parsing to build a complete intermediate representation (IR).

Secure Payload Handling

Before parsing XML, the extractor determines how to extract the raw payload based on file headers:

• _png_embedded_xml – When the file starts with the PNG magic header, this function pulls the mxfile chunk from the PNG metadata.
• _svg_embedded_xml – For SVG files, it extracts the mxfile or mxGraphModel from a content= attribute within the SVG markup.
• _inflate – For compressed files, it decodes base‑64 and deflates the payload to reveal the underlying XML.
• MAX_XML_BYTES – All decompression respects a hard size limit to prevent resource-exhaustion attacks on the parsing stage.

XML Validation and Security

After extraction, the script validates the XML using _reject_unsafe_xml, which scans for DTD declarations and ENTITY tags to prevent XML external entity (XXE) attacks. The parser then uses xml.etree.ElementTree to parse the <mxfile> or bare <mxGraphModel> root element into a traversable DOM structure.

Three-Pass IR Construction

The parser walks the mxGraphModel in three sequential passes to build the IR:

• Pass 1 gathers raw cells, handling <object> and <UserObject> containers that group visual elements.
• Pass 2 creates Node objects for vertices, resolves absolute geometry coordinates, and builds a parent/child hierarchy to preserve diagram structure.
• Pass 3 creates Edge objects for connections, folds edge‑label vertices into the edge’s label property, and calculates node degrees (in/out counts) for topology analysis.

This three-pass approach ensures that all geometric relationships and connection metadata are fully resolved before the analysis phase begins.

Structural Analysis and Type Inference

Once the IR is constructed, the analyze(page) function computes structural signals that drive downstream design decisions. This analysis extracts:

• Node and edge counts
• Shape families (rectangles, circles, specific icon sets)
• Cycle detection and hub identification (high-degree nodes)
• Entry points and disconnected components
• Type candidates such as "flowchart," "architecture," or "tree"

These signals are crucial because the Diagram Design tool uses them during the "type inference" step to apply appropriate visual styles and layouts when rendering the final diagram according to output-spec.md.

How to Import: Three Methods

The repository provides three interfaces for importing draw.io files, ranging from CLI scripting to integrated slash commands.

Method 1: Command Line Interface

For automation and debugging, run the extractor directly:

# Basic CLI usage – extracts a digest from a draw.io file

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

# Get the full IR as JSON (useful for debugging)

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

Method 2: Programmatic Python API

For custom integrations, import the extractor functions directly:

from pathlib import Path
from skills.diagram-design.scripts.drawio_extract import parse_file, digest

path = Path("my-diagram.drawio")
pages = parse_file(path)                 # returns a list of Page objects

selected = pages[:1]                     # usually the first page

markdown = digest(path, pages, selected, max_rows=40)
print(markdown)

The parse_file function returns a list of Page objects, while digest generates a human-readable Markdown summary of the selected pages.

Method 3: Slash Command Integration

For end-users within the Diagram Design skill UI, the import-drawio slash command orchestrates the full pipeline:

import-drawio my-diagram.drawio --format=svg --size=slide-16x9 --detail=balanced

This command, defined in commands/import-drawio.md, supports extensive customization:

• --format – Output format: html, svg, png, or html+png
• --size – Target dimensions (e.g., slide-16x9)
• --detail – Rendering fidelity: faithful, balanced, or simplified
• --audience – Target reader: engineer, mixed, or executive
• --type – Force a specific diagram type classification
• --page – Select specific pages by number, name, or all
• --variant – Color scheme: light, dark, or full
• --output – Custom output path

The command invokes the extractor, verifies the exit code is zero, confirms the digest contains nodes, and then generates the final editorial diagram according to the output-spec.md configuration.

Key Files in the Import Architecture

Understanding the repository structure helps when debugging or extending import functionality:

• skills/diagram-design/scripts/drawio_extract.py – Core extractor that normalizes draw.io input into an IR and produces Markdown or JSON digests.
• scripts/verify-drawio-import.py – Test harness that validates the entire import pipeline against known fixtures, checking payload handling, geometry resolution, and shape classification.
• commands/import-drawio.md – Slash-command definition that orchestrates the extractor and rendering steps for end-users.
• skills/diagram-design/references/import-drawio.md – Human-readable reference explaining required behavior and defaults used by the command.
• skills/diagram-design/references/output-spec.md – Specification of final diagram formats, sizes, and detail levels rendered after extraction.
• skills/diagram-design/SKILL.md – Central skill documentation defining diagram types, taste gates, and visual style guidelines applied post-import.

Summary

• Deterministic extraction – The drawio_extract.py script never makes design decisions; it only normalizes raw draw.io data into a structured intermediate representation.
• Multi-format support – Handles .drawio, .xml, .drawio.png, and .drawio.svg files through specialized payload extraction functions.
• Security-first parsing – Implements MAX_XML_BYTES limits and _reject_unsafe_xml validation to prevent resource exhaustion and XXE attacks.
• Three-pass normalization – Builds the IR by first gathering cells, then resolving geometry and hierarchies, and finally processing edges and labels.
• Flexible integration – Supports direct CLI usage, Python API integration, and slash-command orchestration within the Diagram Design skill.

Frequently Asked Questions

What file formats can I import into the Diagram Design tool?

The tool accepts .drawio, .xml, .drawio.png, and .drawio.svg files. The extractor handles raw XML, compressed base‑64 payloads, and XML embedded within PNG or SVG image chunks, ensuring compatibility with any standard draw.io export method.

How does the tool handle compressed or embedded draw.io files?

The extractor detects file types by magic headers. For PNG files, it uses _png_embedded_xml to extract the mxfile chunk; for SVG files, _svg_embedded_xml pulls data from the content= attribute; for compressed XML, _inflate decodes base‑64 and decompresses the payload, respecting MAX_XML_BYTES limits to prevent memory exhaustion.

Can I import specific pages from multi-page draw.io diagrams?

Yes. When using the slash command, specify the --page flag with a page number, name, or all to import multiple pages. In the Python API, parse_file returns a list of Page objects, allowing you to slice or select specific indices (e.g., pages[:1] for the first page) before calling digest.

Is the import process secure against malicious files?

The implementation includes multiple security layers: _reject_unsafe_xml blocks DTD and ENTITY declarations to prevent XXE attacks, while MAX_XML_BYTES limits prevent decompression bombs from exhausting system resources. The scripts/verify-drawio-import.py test harness continuously validates these protections against malicious fixtures.

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