# How draw.io Import Converts and Redraws Diagrams at Different Detail Levels in Diagram Design

> Discover how draw.io import in Diagram Design converts *.drawio files into high mid or low abstraction level diagrams using a three-phase pipeline without losing fidelity.

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

---

**The draw.io import process in Diagram Design uses a three-phase pipeline—extraction, detail-level mapping, and rendering—to transform raw *.drawio files into diagrams that display at high, mid, or low abstraction levels without losing fidelity.**

The Diagram Design repository provides a sophisticated workflow for importing draw.io diagrams and rendering them at varying levels of detail. This capability allows technical documentation to present architectural overviews to executives while preserving granular implementation details for engineering teams, all from a single source file.

---

## The Three-Phase Import Pipeline

The `import-drawio` command orchestrates a complete transformation workflow that separates concerns across extraction, hierarchical mapping, and final rendering.

### Phase 1: Extraction and Normalization

The helper script [`skills/diagram-design/scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py) handles the initial parsing of draw.io files. This script:

- Parses XML representations of *.drawio* files, including embedded PNG/SVG variants
- Extracts shapes, connectors, styling attributes, and custom data
- Normalizes the XML structure and resolves embedded resources
- Outputs a clean JSON model capturing **hierarchy**, **geometry**, and **metadata** for every node

```bash
python3 drawio_extract.py sample-architecture.drawio --page 1 --json

```

The extraction layer implements several security and integrity safeguards:

- **Entity-DTD verification** ensures extracted XML adheres to the draw.io DTD
- **Compressed-entity handling** automatically expands compressed draw.io files before parsing
- **Decoy-SVG detection** prevents malicious SVG payloads from injection

### Phase 2: Detail-Level Mapping

After extraction, the core Diagram Design engine processes the JSON model. It applies **container node** identification and **marker-first resolution** (documented in ADR [0001] and ADR [0006]) to assign elements to abstraction tiers.

| Detail Level | Rendering Behavior |
|-------------|------------------|
| **High-level view** | Retains only top-level containers and immediate children; internal groups collapse into placeholder shapes |
| **Mid-level view** | Displays container boundaries with logical groupings preserved; sub-components remain hidden |
| **Low-level view** | Renders all leaf nodes and precise connector routes; reproduces exact original layout |

The marker-first resolution strategy determines which elements survive at each tier, ensuring consistent semantics across abstraction levels.

### Phase 3: Rendering and Export

The processed model feeds into the rendering pipeline, which generates output in multiple formats:

- Markdown with embedded Mermaid
- Standalone HTML
- Static PNG/SVG

The pipeline applies styling rules from [`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md) and respects the selected detail level throughout.

---

## Command-Line Usage Examples

Generate a high-level architectural overview suitable for stakeholder presentations:

```bash
python3 drawio_extract.py sample-architecture.drawio --page 1 --json |
diagram-design --detail high --format mermaid > architecture-high.mmd

```

Produce a low-level implementation diagram with complete fidelity:

```bash
python3 drawio_extract.py sample-architecture.drawio --page 1 --json |
diagram-design --detail low --format mermaid > architecture-low.mmd

```

---

## Programmatic API Access

The Python API provides fine-grained control over the import and rendering pipeline:

```python
from diagram_design.drawio import DrawioExtractor, DiagramRenderer

# Load and normalize the draw.io file

extractor = DrawioExtractor("sample-architecture.drawio")
model = extractor.to_json(page=1)

# Render a mid-level diagram as Mermaid

renderer = DiagramRenderer(model)
mid_mermaid = renderer.render(detail="mid", fmt="mermaid")
print(mid_mermaid)

```

The `DrawioExtractor` class handles file parsing and normalization, while `DiagramRenderer` manages abstraction-level selection and format conversion.

---

## Key Implementation Files

Understanding the source structure helps when extending or debugging the import workflow:

- **[`skills/diagram-design/scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py)** — Core extractor parsing draw.io XML and producing normalized JSON models
- **[`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md)** — CLI reference documenting flags, detail levels, and output formats
- **[`scripts/verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-drawio-import.py)** — Test harness validating the pipeline against fixture diagrams
- **[`docs/adr/0001-static-by-default-single-pinned-controller.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0001-static-by-default-single-pinned-controller.md)** — ADR explaining default static rendering strategy
- **[`docs/adr/0006-client-profiles-and-marker-first-resolution.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0006-client-profiles-and-marker-first-resolution.md)** — ADR detailing marker-first resolution for multi-detail abstraction

---

## Summary

- The draw.io import workflow separates **extraction**, **hierarchical mapping**, and **rendering** into distinct phases
- **[`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py)** normalizes raw draw.io XML into a structured JSON model
- **Three detail levels** (high, mid, low) control abstraction through container node detection and marker-first resolution
- **Security safeguards** include DTD verification, compressed entity handling, and decoy-SVG detection
- Output formats include Mermaid-embedded Markdown, HTML, and static images

---

## Frequently Asked Questions

### How does the draw.io import handle compressed files?

The extraction pipeline automatically detects and expands compressed draw.io files before XML parsing. This happens transparently in [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) during the normalization phase, requiring no user intervention.

### What is marker-first resolution in detail-level mapping?

Marker-first resolution is the strategy documented in ADR [0006] that prioritizes semantic markers (container boundaries, group labels) over individual elements when determining what renders at each abstraction tier. This ensures logical groupings remain visible even when internal details collapse.

### Can I import specific pages from multi-page draw.io files?

Yes. Both the CLI (`--page 1`) and Python API (`to_json(page=1)`) accept page indices to target specific diagrams within a single *.drawio* file.

### Is the low-level view pixel-perfect with the original draw.io rendering?

The low-level view reproduces exact connector routes and leaf node positions from the original file. Minor rendering differences may appear due to styling engine variations between draw.io and Diagram Design's output formats.