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

To import and redraw draw.io diagrams, extract the semantic content using 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 handles multiple input formats including .drawio, .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.

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:

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: 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 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 taste-gate along with the output-spec checklist. For static assets, generate SVG or PNG via the 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:

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.

Core Implementation Files

Understanding the repository structure helps troubleshoot specific import scenarios:

• 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 — Defines the slash command interface and workflow orchestration.
• 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 — Specifications for the four dials (format, size, detail, audience) used throughout the import process.
• 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 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 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 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. 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 script processes .drawio, .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.

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