# Can Diagram-Design Import Draw.io Files and Redraw Them with Custom Styling?

> Diagram-design imports draw.io files, extracts semantic structure, and redraws diagrams applying your custom design system for a fresh look.

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

---

**Yes—diagram-design ingests `.drawio` files, extracts their semantic structure, and renders fresh diagrams that apply the skill's design system while discarding original geometry, colors, and shapes.**

The *diagram-design* skill provides a complete import pipeline that transforms existing draw.io diagrams into clean, consistent visuals aligned with [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md). This workflow reinterprets content rather than converting pixels, ensuring every output meets the project's taste-gate standards.

## How the Import Pipeline Works

The process operates in three distinct phases defined in [[`skills/diagram-design/references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-drawio.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-drawio.md):

### Extraction Phase

The [[`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py) script parses source files in multiple formats:

- Raw XML draw.io files
- Compressed payloads
- Embedded PNG/SVG containers

It emits a **Markdown-formatted intermediate representation (IR)** containing nodes, edges, groups, and style metadata. This IR serves as the single source of truth for all subsequent processing.

```bash

# CLI extraction: convert a draw.io file to IR format

python3 skills/diagram-design/scripts/drawio_extract.py \
    path/to/architecture.drawio --page all --json > arch.digest.md

```

The command generates [`arch.digest.md`](https://github.com/cathrynlavery/diagram-design/blob/main/arch.digest.md), which the skill consumes to drive redraw decisions.

### Decision-Making Phase

The IR feeds into the **"four dials"** framework defined in [[`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md):

| Dial | Purpose | Signals Used |
|------|---------|--------------|
| **Format** | Output type (HTML/SVG/PNG) | User intent, embedding context |
| **Size** | Canvas dimensions | Container depth, node count |
| **Detail** | Information density | Shape vocabulary, edge complexity |
| **Audience** | Cognitive load target | Icon presence, label patterns |

The skill analyzes shape vocabulary, container depth, and specific icons to select an appropriate diagram type automatically.

### Redrawing Phase

A brand-new diagram built on a **4 px grid** replaces the source:

- Original coordinates are discarded
- Source colors are ignored in favor of the single-accent-plus-ink-ramp palette
- Embedded images are stripped and replaced with semantic equivalents
- All shapes follow [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) treatments

Per **Step 5—Redraw** and **Step 6—Deliver** in [`import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-drawio.md), only the semantic model from the IR drives output. A **fidelity ledger** documents which source elements were altered or omitted.

## Practical Usage Examples

### Example 1: Slash Command Import

Invoke the skill directly in chat:

```

/diagram-design:import path/to/architecture.drawio

```

The skill automatically:
- Runs the extractor
- Prompts for ambiguous parameters (page selection)
- Confirms format/size/detail targets
- Delivers HTML/SVG/PNG with enforced styling

### Example 2: Programmatic Python Integration

```python
import subprocess
import json
import pathlib

DRAWIO = pathlib.Path("sample.drawio")

# Extract intermediate representation

result = subprocess.run(
    ["python3", "skills/diagram-design/scripts/drawio_extract.py",
     str(DRAWIO), "--json"],
    capture_output=True,
    text=True,
    check=True
)
ir = json.loads(result.stdout)

# Pass IR to skill's import routine (pseudo-code)

from diagram_design.import_drawio import import_drawio

rendered = import_drawio(
    ir,
    format="html",
    size="doc-inline",
    detail="balanced",
    audience="mixed"
)

pathlib.Path("output.html").write_text(rendered)

```

This pattern embeds the pipeline within larger applications while preserving full styling enforcement.

## Key Source Files for Import Functionality

| File | Purpose |
|------|---------|
| [`skills/diagram-design/scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py) | Parses draw.io formats, outputs IR |
| [`skills/diagram-design/references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-drawio.md) | Complete import specification with redraw rules |
| [`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md) | Four-dial framework (format, size, detail, audience) |
| [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) | Design system palette and typography rules |
| [`scripts/verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-drawio-import.py) | Test harness validating extractor and pipeline |

## Summary

- **draw.io import is fully supported** via three-phase extraction, decision, and redraw pipeline
- **Original styling is always discarded**—only semantic structure survives
- **Four configurable dials** control format, size, detail, and audience targeting
- **4 px grid and single-accent palette** enforce visual consistency
- **Fidelity ledger** tracks deviations from source material
- **CLI, slash command, and Python APIs** support diverse integration patterns

## Frequently Asked Questions

### What draw.io file formats does diagram-design support?

The [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) parser handles raw XML, compressed payloads, and diagrams embedded within PNG or SVG containers. All variants produce the same intermediate representation for downstream processing.

### Does diagram-design preserve my original colors and fonts?

No. The redraw phase intentionally discards all source coordinates, colors, and embedded images. Only semantic relationships (nodes, edges, groups) persist, re-rendered through the [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) design system with its single-accent-plus-ink-ramp palette.

### How can I verify the import processed my file correctly?

Run the validation harness at [[`scripts/verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-drawio-import.py)](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-drawio-import.py). This script tests the extractor and full pipeline against fixture files, confirming IR generation and redraw fidelity.

### Can I automate draw.io import in a CI/CD pipeline?

Yes. The Python example above demonstrates headless extraction. Combine `subprocess` calls to [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) with the skill's `import_drawio` function to generate diagram assets automatically during build processes.