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

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 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:

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), 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) 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) for a live example of rendered output.

Practical Code Examples

Import Default First Page

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

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

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

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

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

{
  "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	Pure-Python XML/parser with no external dependencies; produces canonical JSON	skills/diagram-design/scripts/drawio_extract.py
import-drawio.md (reference)	User documentation: arguments, options, examples	skills/diagram-design/references/import-drawio.md
import-drawio.md (command)	Bot/CLI command definition	commands/import-drawio.md
verify-drawio-import.py	Continuous integration script ensuring command, docs, and extractor remain synchronized	scripts/verify-drawio-import.py
example-import-drawio.html	Demonstrates rendered output styling	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 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 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 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 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.

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