# How to Import and Redraw Existing draw.io Diagrams in the Diagram-Design Style

> Easily import and redraw draw.io diagrams into Diagram-Design using the import-drawio command. Convert .drawio, .xml, and image files to native diagrams with consistent styling.

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

---

**Use the `diagran-design:import-drawio` slash command to convert any `.drawio`, `.xml`, `.drawio.png`, or `.drawio.svg` file into a native Diagram-Design diagram with consistent styling.**

The Diagram-Design project provides a dedicated pipeline for importing and redrawing existing draw.io diagrams. Whether you're migrating legacy diagrams or collaborating with teams using draw.io, this workflow preserves your diagram structure while applying Diagran-Design's unified visual language—automatically handling colors, fonts, and line weights through the **style-guide** system.

## The Import Workflow Explained

The import process runs through five stages, from file parsing to final rendering. Each stage is backed by specific source files in the [cathrynlavery/diagram-design](https://github.com/cathrynlavery/diagram-design) repository.

### Step 1: Locate and Submit Your File

Provide either a local file path or a URL resolving to a draw.io-compatible format. Supported extensions include:
- `.drawio` (native format)
- `.xml` (draw.io XML export)
- `.drawio.png` or `.drawio.svg` (embedded diagram data)

### Step 2: Execute the Import Command

Run the slash command with optional flags for page selection or JSON output:

```bash
diagram-design:import-drawio <file.drawio> [--page N|NAME] [--json]

```

The command signature is defined in [[`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md)](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md), which serves as the canonical reference for the CLI and bot integrations.

### Step 3: Extract and Normalize Diagram Data

The Python extractor [[`skills/diagram-design/scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py) parses the source XML (including embedded data in PNG/SVG files) and emits a **canonical JSON schema**. This script performs **no network I/O** and normalizes all shapes, connectors, and styles into a version-stable format.

### Step 4: Convert to Diagram-Design Model

The JSON payload feeds into the Diagram-Design rendering engine, which constructs an internal **type-state** representation. The engine automatically applies the project's **style-guide**—controlling color palettes, typography, and line weights—ensuring visual consistency with native Diagram-Design outputs.

### Step 5: Render the Final Diagram

The engine returns a Markdown block containing either:
- A rendered SVG preview styled per the Diagram-Design specification
- Raw JSON (when `--json` is specified) for programmatic processing

See [[`skills/diagram-design/assets/example-import-drawio.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-import-drawio.html)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-import-drawio.html) for a live example of rendered output.

## Practical Code Examples

### Import Default First Page

```bash
diagram-design:import-drawio my-architecture.drawio

```

This produces a rendered Diagram-Design block in the chat interface, with styling applied automatically.

### Import Specific Page by Index

```bash
diagram-design:import-drawio my-architecture.drawio --page 2

```

Zero-based indexing applies; page 2 corresponds to the third page in multi-page draw.io files.

### Import Page by Name

```bash
diagram-design:import-drawio my-architecture.drawio --page "Data Layer"

```

Matches against the page name as defined in the draw.io editor.

### Extract Raw JSON for Pipeline Integration

```bash
diagram-design:import-drawio my-architecture.drawio --json

```

Useful for version control, diffing, or feeding into downstream automation.

```json
{
  "type": "diagram",
  "pages": [
    {
      "name": "Data Layer",
      "elements": [
        {"id":"n1","type":"rectangle","x":120,"y":80,"w":200,"h":100,"style":{...}},
        {"id":"n2","type":"ellipse","x":400,"y":80,"w":150,"h":80,"style":{...}},
        {"source":"n1","target":"n2","style":{...}}
      ]
    }
  ]
}

```

## Key Implementation Files

| File | Purpose | Location |
|------|---------|----------|
| **[`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py)** | Pure-Python XML/parser with no external dependencies; produces canonical JSON | [`skills/diagram-design/scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py) |
| **[`import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-drawio.md) (reference)** | User documentation: arguments, options, examples | [`skills/diagram-design/references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-drawio.md) |
| **[`import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-drawio.md) (command)** | Bot/CLI command definition | [`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md) |
| **[`verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-drawio-import.py)** | Continuous integration script ensuring command, docs, and extractor remain synchronized | [`scripts/verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-drawio-import.py) |
| **[`example-import-drawio.html`](https://github.com/cathrynlavery/diagram-design/blob/main/example-import-drawio.html)** | Demonstrates rendered output styling | [`skills/diagram-design/assets/example-import-drawio.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-import-drawio.html) |

## How the Style-Guide Applies During Import

The Diagram-Design engine does not preserve raw draw.io styling. Instead, it:

1. **Maps shape types** to Diagram-Design primitives (rectangle, ellipse, diamond, etc.)
2. **Normalizes connector routing** to consistent bezier or orthogonal paths
3. **Applies style-guide tokens** for fill colors, stroke widths, corner radii, and typography
4. **Maintains positional data** (x, y, width, height) for layout fidelity

This ensures imported diagrams visually integrate with newly created Diagram-Design content.

## Summary

- The **`diagram-design:import-drawio`** command converts draw.io files to native Diagram-Design diagrams
- **[`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py)** handles all XML parsing and JSON normalization without network calls
- Use **`--page`** to select specific pages by index or name
- Use **`--json`** to retrieve the canonical payload for programmatic workflows
- All styling is applied automatically through the **type-state** engine and **style-guide** system
- The **[`verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-drawio-import.py)** test harness prevents documentation drift

## Frequently Asked Questions

### What draw.io formats are supported?

The importer accepts `.drawio`, `.xml`, `.drawio.png`, and `.drawio.svg` files. Both PNG and SVG variants contain embedded XML data that [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) extracts and parses identically to standalone `.drawio` files.

### Does the import preserve original colors and fonts?

No—this is intentional. Diagram-Design replaces all visual styling with its **style-guide** to ensure consistency. Positional and structural data (shapes, connectors, page organization) are preserved exactly.

### Can I automate batch imports of multiple diagrams?

Yes. Combine the `--json` flag with shell scripting or CI pipelines to process files programmatically. The JSON output from [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) is stable and suitable for version control and bulk transformations.

### What happens if my draw.io file has multiple pages?

The importer defaults to the first page. Specify `--page N` for zero-based indexing or `--page "Exact Page Name"` to match draw.io's internal page labels. Each page is processed independently; there is no bulk multi-page export option in the current implementation.