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

> Easily import draw.io diagrams into diagram-design. Learn how diagram-design reinterprets your draw.io files, redrawing them to fit your project's style guide and grid for seamless integration.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-17

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/.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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.

```bash
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.

```bash
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.

```bash

# 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.

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md) — Defines the slash-command interface and user-visible flags.
- [`skills/diagram-design/references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py) — Core extractor that produces the intermediate representation.
- [`assets/example-import-drawio.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) script accepts `.drawio`, [`.drawio.xml`](https://github.com/cathrynlavery/diagram-design/blob/main/.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.