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

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

Extraction Phase

The [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.

# 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, 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):

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 treatments

Per Step 5—Redraw and Step 6—Deliver in 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

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	Parses draw.io formats, outputs IR
skills/diagram-design/references/import-drawio.md	Complete import specification with redraw rules
skills/diagram-design/references/output-spec.md	Four-dial framework (format, size, detail, audience)
skills/diagram-design/references/style-guide.md	Design system palette and typography rules
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 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 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). 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 with the skill's import_drawio function to generate diagram assets automatically during build processes.

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