Drawio

Draw.io Diagrams

Overview

Generate .drawio XML files and export to PNG/SVG/PDF/JPG locally using the native draw.io desktop app CLI.

Supported formats: PNG, SVG, PDF, JPG — no browser automation needed.

PNG, SVG, and PDF exports support --embed-diagram (-e) — the exported file contains the full diagram XML, so opening it in draw.io recovers the editable diagram. Use double extensions (name.drawio.png) to signal embedded XML.

When to Use

Explicit triggers: user says "画图", "diagram", "visualize", "flowchart", "draw", "架构图", "流程图"

Proactive triggers:

• Explaining a system with 3+ interacting components
• Describing a multi-step process or decision tree
• Comparing architectures or approaches side by side

Skip when: a simple list or table suffices, or user is in a quick Q&A flow

Prerequisites

The draw.io desktop app must be installed and the CLI accessible:

# macOS (Homebrew — recommended)
brew install --cask drawio
draw.io --version

# macOS (full path if not in PATH)
/Applications/draw.io.app/Contents/MacOS/draw.io --version

# Windows
"C:\Program Files\draw.io\draw.io.exe" --version

# Linux
draw.io --version

Install draw.io desktop if missing:

• macOS: brew install --cask drawio or download from https://github.com/jgraph/drawio-desktop/releases
• Windows: download installer from https://github.com/jgraph/drawio-desktop/releases
• Linux: download .deb/.rpm from https://github.com/jgraph/drawio-desktop/releases

Workflow

1. Check deps — verify draw.io --version succeeds; note platform for correct CLI path
2. Plan — identify shapes, relationships, layout (LR or TB), group by tier/layer
3. Generate — write .drawio XML file to disk (output dir same as user's working dir)
4. Export draft — run CLI to produce PNG for preview
5. Self-check — read the exported PNG, catch obvious issues, auto-fix before showing user
6. Review loop — show image to user, collect feedback, apply targeted XML edits, re-export, repeat until approved
7. Final export — export approved version to all requested formats, report file paths

Step 5: Self-Check

After exporting the draft PNG, read the image and check for these issues before showing the user:

• Max 2 self-check rounds — if issues remain after 2 fixes, show the user anyway
• Re-export after each fix and re-read the new PNG

Step 6: Review Loop

After self-check, show the exported image and ask the user for feedback.

Targeted edit rules — for each type of feedback, apply the minimal XML change:

Rules:

• For single-element changes: edit existing XML in place — preserves layout tuning from prior iterations
• For layout-wide changes (e.g., swap LR↔TB, "start over"): regenerate full XML
• Overwrite the same {name}.png each iteration — do not create v1, v2, v3 files
• After applying edits, re-export and show the updated image
• Loop continues until user says approved / done / LGTM / 完成
• Safety valve: after 5 iteration rounds, suggest the user open the .drawio file in draw.io desktop for fine-grained adjustments

Step 7: Final Export

Once the user approves:

• Export to all requested formats (PNG, SVG, PDF, JPG) — default to PNG if not specified
• Report file paths for both the .drawio source file and exported image(s)
• Confirm files are saved and ready to use

Draw.io XML Structure

File skeleton

<?xml version="1.0" encoding="UTF-8"?>
<mxfile host="drawio" version="26.0.0">
  <diagram name="Page-1">
    <mxGraphModel>
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <!-- user shapes start at id="2" -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

Rules:

• id="0" and id="1" are required root cells — never omit them
• User shapes start at id="2" and increment sequentially
• All shapes have parent="1" (unless inside a container — then use container's id)
• All text uses html=1 in style for proper rendering
• Never use -- inside XML comments — it's illegal per XML spec and causes parse errors
• Escape special characters in attribute values: &, <, >, "

Shape types (vertex)

Required properties

<!-- Rectangle / rounded box -->
<mxCell id="2" value="Label" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="160" height="60" as="geometry" />
</mxCell>

<!-- Cylinder (database) -->
<mxCell id="3" value="DB" style="shape=cylinder3;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;" vertex="1" parent="1">
  <mxGeometry x="350" y="100" width="120" height="80" as="geometry" />
</mxCell>

<!-- Diamond (decision) -->
<mxCell id="4" value="Check?" style="rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;" vertex="1" parent="1">
  <mxGeometry x="100" y="220" width="160" height="80" as="geometry" />
</mxCell>

Containers and groups

For architecture diagrams with nested elements, use draw.io's parent-child containment — do not just place shapes on top of larger shapes.

Key rules:

• Add pointerEvents=0; to container styles that should not capture connections between children
• Children set parent="containerId" and use coordinates relative to the container

<!-- Swimlane container -->
<mxCell id="svc1" value="User Service" style="swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="300" height="200" as="geometry"/>
</mxCell>
<!-- Child inside container — coordinates relative to parent -->
<mxCell id="api1" value="REST API" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="svc1">
  <mxGeometry x="20" y="40" width="120" height="60" as="geometry"/>
</mxCell>
<mxCell id="db1" value="Database" style="shape=cylinder3;whiteSpace=wrap;html=1;" vertex="1" parent="svc1">
  <mxGeometry x="160" y="40" width="120" height="60" as="geometry"/>
</mxCell>

Connector (edge)

CRITICAL: Every edge mxCell must contain a <mxGeometry relative="1" as="geometry" /> child element. Self-closing edge cells (<mxCell ... edge="1" ... />) are invalid and will not render. Always use the expanded form.

<!-- Directed arrow — always include rounded, orthogonalLoop, jettySize for clean routing -->
<mxCell id="10" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="2" target="3">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

<!-- Arrow with label + explicit entry/exit points to control direction -->
<mxCell id="11" value="HTTP/REST" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="1" source="2" target="4">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

<!-- Arrow with waypoints — use when edge must route around other shapes -->
<mxCell id="12" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="3" target="5">
  <mxGeometry relative="1" as="geometry">
    <Array as="points">
      <mxPoint x="500" y="50" />
    </Array>
  </mxGeometry>
</mxCell>

Edge style rules:

• Always include rounded=1;orthogonalLoop=1;jettySize=auto — these enable smart routing that avoids overlaps
• Pin exitX/exitY/entryX/entryY on every edge when a node has 2+ connections — distributes lines across the shape perimeter
• Add <Array as="points"> waypoints when an edge must detour around an intermediate shape
• Leave room for arrowheads: the final straight segment between the last bend and the target shape must be ≥20px long. If too short, the arrowhead overlaps the bend and looks broken. Fix by increasing node spacing or adding explicit waypoints

Distributing connections on a shape

When multiple edges connect to the same shape, assign different entry/exit points to prevent stacking:

Rule: if a shape has N connections on one side, space them evenly (e.g., 3 connections on bottom → exitX = 0.25, 0.5, 0.75)

Color palette (fillColor / strokeColor)

Layout tips

Spacing — scale with complexity:

Routing corridors: between shape rows/columns, leave an extra ~80px empty corridor where edges can route without crossing shapes. Never place a shape in a gap that edges need to traverse.

General rules:

• Plan a grid before assigning x/y coordinates — sketch node positions on paper/mentally first
• Group related nodes in the same horizontal or vertical band
• Use swimlane cells for logical grouping with visible borders
• Place heavily-connected "hub" nodes centrally so edges radiate outward instead of crossing
• To force straight vertical connections, pin entry/exit points explicitly on edges: exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0
• Always center-align a child node under its parent (same center x) to avoid diagonal routing
• Event bus pattern: place Kafka/bus nodes in the center of the service row, not below — services on either side can reach it with short horizontal arrows (exitX=1 left side, exitX=0 right side), eliminating all line crossings
• Horizontal connections (exitX=1 or exitX=0) never cross vertical nodes in the same row; use them for peer-to-peer and publish connections

Avoiding edge-shape overlap:

• Before finalizing coordinates, trace each edge path mentally — if it must cross an unrelated shape, either move the shape or add waypoints
• For tree/hierarchical layouts: assign nodes to layers (rows), connect only between adjacent layers to minimize crossings
• For star/hub layouts: place the hub center, satellites around it — edges stay short and radial
• When an edge must span multiple rows/columns, route it along the outer corridor, not through the middle of the diagram

Export

Commands

# macOS — Homebrew (draw.io in PATH)
draw.io -x -f png -e -s 2 -o diagram.drawio.png input.drawio

# macOS — full path (if not in PATH)
/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png -e -s 2 -o diagram.drawio.png input.drawio

# Windows
"C:\Program Files\draw.io\draw.io.exe" -x -f png -e -s 2 -o diagram.drawio.png input.drawio

# Linux (headless — requires xvfb-run)
xvfb-run -a draw.io -x -f png -e -s 2 -o diagram.drawio.png input.drawio

# SVG export
draw.io -x -f svg -o diagram.svg input.drawio

# PDF export
draw.io -x -f pdf -o diagram.pdf input.drawio

Key flags:

• -x — export mode (required)
• -f — format: png, svg, pdf, jpg
• -e — embed diagram XML in output (PNG, SVG, PDF only) — exported file remains editable in draw.io
• -s — scale: 1, 2, 3 (2 recommended for PNG)
• -o — output file path (use .drawio.png double extension when embedding)
• -b — border width around diagram (default: 0, recommend 10)
• -t — transparent background (PNG only)
• --page-index 0 — export specific page (default: all)

Checking if draw.io is in PATH

# Try short command first
if command -v draw.io &>/dev/null; then
  DRAWIO="draw.io"
elif [ -f "/Applications/draw.io.app/Contents/MacOS/draw.io" ]; then
  DRAWIO="/Applications/draw.io.app/Contents/MacOS/draw.io"
else
  echo "draw.io not found — install from https://github.com/jgraph/drawio-desktop/releases"
fi

Common Mistakes