# How to Import and Redraw draw.io Diagrams Using Diagram-Design

> Easily import and redraw draw.io diagrams with Diagram-Design. Extract semantic content and rebuild layouts, ignoring original geometry and styling. Learn how today!

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

---

**To import and redraw draw.io diagrams, extract the semantic content using [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py), configure the four dials (format, size, detail, audience), and rebuild a fresh layout that ignores all original geometry and styling.**

The `cathrynlavery/diagram-design` repository provides a specialized pipeline for importing draw.io files that prioritizes semantic fidelity over visual replication. Unlike standard converters that preserve layouts and colors, this workflow decodes the source file into a normalized intermediate representation, then reconstructs an editorial-quality diagram conforming to the skill's design system.

## The Seven-Stage Import Pipeline

The complete workflow treats your `.drawio` file strictly as a source of **semantic content**—nodes, edges, containers, and hierarchy—while deliberately discarding all layout, color, and shape details from the original file.

### Stage 1: Extract the Intermediate Representation

Run the draw.io extractor to decode any compressed payload and produce a normalized intermediate representation (IR) in Markdown digest form.

The extractor located at [`skills/diagram-design/scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py) handles multiple input formats including `.drawio`, [`.drawio.xml`](https://github.com/cathrynlavery/diagram-design/blob/main/.drawio.xml), `.png`, and `.svg`. It outputs tables containing nodes and edges, geometry metadata, shape classes, hub degrees, container structure, cycle detection, budget flags, and collapsible groups that inform simplification decisions.

```bash
python3 skills/diagram-design/scripts/drawio_extract.py \
    path/to/example.drawio \
    --page all \
    --max-rows 50 \
    --out digest.md

```

For programmatic inspection, convert the digest to JSON:

```bash
python3 skills/diagram-design/scripts/drawio_extract.py \
    path/to/example.drawio \
    --json \
    --out diagram.json

```

### Stage 2: Configure the Four Dials

Before redrawing, you must set four parameters defined in [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md): **format**, **size**, **detail level**, and **audience**.

The digest's "budget" line indicates whether the requested detail level is feasible. When a source exceeds the node budget, you must implement an overview-plus-detail approach rather than attempting to render everything at once.

### Stage 3: Select the Diagram Type

The digest supplies a ranked list of **type candidates** (e.g., sequence, flowchart, architecture). Consult the reference table in [`skills/diagram-design/references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-drawio.md) to map these signals to concrete diagram types, overriding the suggestion only when the content explicitly contradicts it.

### Stage 4: Build the Semantic Model

Transform the extracted data into a narrative structure by completing five specific tasks:

- **Compose the story**: Write a concise statement the diagram will convey.
- **Apply detail constraints**: Collapse groups using the "collapsible groups" section to match your selected detail level.
- **Identify focal nodes**: Select 1–2 focal nodes, typically the highest-degree hubs.
- **Rewrite labels**: Adapt every label for your chosen audience (e.g., transform `svc-auth-prod-v2` into *Auth Service*).
- **Prune edges**: Retain only labeled edges, cross-zone edges, or those that run against the dominant flow; remove decorative connectors.

### Stage 5: Execute the Fresh Redraw

Generate the diagram on a **4-px grid**, ignoring all source geometry. Map source colors to semantic roles using the color-to-role table in the reference documentation, and convert shapes to appropriate visual treatments (cylinders become store boxes, icons become monochrome glyphs).

Route all connectors with orthogonal elbows; never reuse source waypoints. This step ensures the output conforms to the diagram-design style guide rather than mirroring the original visual chaos.

### Stage 6: Deliver the Output

Write the final `.html` file and execute the [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) taste-gate along with the output-spec checklist. For static assets, generate SVG or PNG via the [`export.md`](https://github.com/cathrynlavery/diagram-design/blob/main/export.md) workflow.

Always provide a **fidelity ledger** documenting what content was merged, collapsed, or dropped during the transformation process.

### Stage 7: Slash Command Automation

Coordinate the entire pipeline using the integrated slash command:

```bash
diagram-design import-drawio path/to/example.drawio \
    --format html \
    --size doc-inline \
    --detail balanced \
    --audience mixed

```

This command invokes the extractor and handles the complete user interaction flow defined in [`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md).

## Core Implementation Files

Understanding the repository structure helps troubleshoot specific import scenarios:

- **[`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 decodes draw.io payloads, builds the IR, and emits the markdown digest or JSON.
- **[`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md)** — Defines the slash command interface and workflow orchestration.
- **[`skills/diagram-design/references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-drawio.md)** — High-level procedural guide mapping digest signals to diagram types and documenting edge cases.
- **[`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md)** — Specifications for the four dials (format, size, detail, audience) used throughout the import process.
- **[`skills/diagram-design/README.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/README.md)** — General overview of design-system conventions and editorial standards.

## Summary

- **Never preserve original layouts**: The pipeline explicitly ignores all source geometry, colors, and styling to enforce design-system compliance.
- **Extract first**: Use [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) to generate a semantic digest containing nodes, edges, containers, and budget flags before attempting any visual reconstruction.
- **Configure constraints**: Set the four dials (format, size, detail, audience) based on the digest's feasibility indicators and the [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md) guidelines.
- **Rebuild semantically**: Construct a new narrative with collapsed groups, rewritten labels, and pruned edges rather than translating the original literally.
- **Document changes**: Always deliver a fidelity ledger recording what was merged, collapsed, or dropped during the import process.

## Frequently Asked Questions

### Why does the pipeline discard the original draw.io layout?

The diagram-design skill enforces a strict editorial style guide that requires all diagrams to use consistent 4-px grids, semantic color roles, and orthogonal connectors. Preserving original layouts would introduce visual inconsistency and violate accessibility standards. According to the `cathrynlavery/diagram-design` source code, the extractor treats geometry data as diagnostic input only, not as output constraints.

### How do I handle large diagrams that exceed the node budget?

When the digest's "budget" flag indicates the source exceeds feasible rendering limits, you must implement an overview-plus-detail strategy. Collapse groups identified in the "collapsible groups" section of the digest, focus on the 1–2 highest-degree hubs as focal nodes, and prune edges that lack semantic labels. The [`import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-drawio.md) reference provides specific thresholds and mapping tables for determining appropriate detail levels.

### Can I preserve specific colors or shapes from my original draw.io file?

No. The pipeline maps all source colors to predefined semantic roles (e.g., customer-facing vs. internal services) using the color-to-role table in [`import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-drawio.md). Similarly, cylinders automatically convert to store boxes and icons become monochrome glyphs. This ensures brand consistency across all diagrams generated by the skill.

### What input formats does the extractor support?

The [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) script processes `.drawio`, [`.drawio.xml`](https://github.com/cathrynlavery/diagram-design/blob/main/.drawio.xml), `.png`, and `.svg` files. For PNG and SVG inputs, the extractor decodes embedded compressed payloads to access the underlying graph data structure. Use the `--page` flag to select specific pages from multi-page diagrams or extract all pages simultaneously.