Draw.io Diagram Generator

Workflow

1. Understand requirements  -> determine diagram type, elements, relationships
2. Generate XML directly    -> write drawio XML (read only the relevant section from references/best-practices.md)
3. Self-review (DO NOT SKIP) -> re-read XML and fix any issues found
4. Save .drawio file        -> write to user's working directory
5. CLI export               -> call draw.io desktop CLI to export image
6. Deliver to user          -> show image + provide editable .drawio file

Step 1: Understand Requirements

Determine:

• Diagram type: flowchart / architecture / uml-sequence / uml-class / er / mindmap / network
• Key elements: nodes, components, participants, entities
• Relationships: connections, dependencies, flow direction
• Output format: PNG (default) / SVG / PDF
• Language: match the user's language for labels

Step 2: Generate XML

You MUST write the XML directly. Do not call any script to generate it.

Base XML Structure

<?xml version="1.0" encoding="UTF-8"?>
<mxfile host="app.diagrams.net" agent="drawio-skill" version="21.0.0" type="device">
  <diagram name="DiagramName" id="diagram-1">
    <mxGraphModel dx="1422" dy="762"
                   grid="1" gridSize="10"
                   guides="1" tooltips="1" connect="1"
                   arrows="1" fold="1"
                   page="1" pageScale="1"
                   pageWidth="1600" pageHeight="1200"
                   math="0" shadow="0">
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />

        <!-- nodes and edges here -->

      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

Node Template

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

Text Content Rules

• For multi-line labels, encode line breaks as

  


  inside

  value

  , for example

  value="API
Gateway"

• Do not write literal

  \n

  inside

  value

  ; draw.io will render it as backslash + n text
• Keep

  html=1

  on nodes, but still use

  


  as the default line-break form for predictable output

Edge Template

<mxCell id="edge-1" value=""
        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="node-1" target="node-2">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

Step 3: Layout Rules (CRITICAL for beautiful output)

General Principles

1. Grid alignment: all x, y coordinates must be multiples of 10 (snap to grid)
2. Generous spacing: minimum 80px gap between node edges (not centers)
3. Center alignment: nodes in the same column share the same x; nodes in the same row share the same y
4. Consistent sizing: same-type nodes use identical width and height
5. Page margins: keep at least 60px from the canvas edge (pageWidth/pageHeight)
6. Use

   whiteSpace=wrap;html=1;

   on all nodes so long text wraps instead of overflowing
7. Balanced gutters: outer padding around a row/column should visually match the internal gaps; avoid one oversized blank side
8. Symmetry first: centered groups should have roughly equal left/right and top/bottom whitespace
9. Dense fill: containers, sub-groups, and sidebars should fit content plus consistent padding; do not leave large dead zones just because the canvas is large

Layout by Diagram Type

Anti-Overlap Checklist

Before finalizing coordinates, verify:

• No two nodes' bounding boxes overlap (check x, y, width, height)
• Edge labels don't overlap with nodes
• Decision branches (Yes/No) go in clearly different directions
• For flowcharts with branches: main path goes down, alternate path goes right (or left)
• For wide diagrams: increase

  pageWidth

  in mxGraphModel; for tall ones increase

  pageHeight

Calculating Coordinates

Use this formula to center N items horizontally in a row:

total_width = N * node_width + (N - 1) * gap
start_x = (pageWidth - total_width) / 2
item[i].x = start_x + i * (node_width + gap)

For vertical centering in a column, apply the same logic to Y axis.

For rows inside a fixed-width container, also check fill density:

inner_width = container_width - 2 * side_pad
gap = (inner_width - N * item_width) / (N - 1)

If

gap

gap

• increase item width moderately
• increase item count per row only if still readable
• reduce container width
• split into multiple balanced rows

For incomplete last rows, center the remaining items instead of left-aligning them and leaving a large blank tail.

Standard Sizes

Step 4: Self-Review (DO NOT SKIP)

After generating XML, re-read your output and check each item below. If any check fails, fix the XML before proceeding. This step catches the most common rendering bugs — skipping it results in broken diagrams.

Structural checks:

• All

  id

  values are unique across the entire file
• Every

  mxCell

  with

  vertex="1"

  has correct

  parent

  (usually

  "1"

  , but container children use the container ID)
• Every edge's

  source

  and

  target

  reference existing node IDs
• XML is well-formed: all tags closed, all attribute values quoted

• mxGeometry

  always has

  as="geometry"

  attribute

Layout checks (these are the most common failures — actually verify the numbers):

• No two non-container nodes overlap: for each pair, confirm their bounding boxes (x, y, x+width, y+height) don't intersect
• All coordinates (x, y) are multiples of 10 — scan every

  mxGeometry

  element
• Page dimensions (pageWidth, pageHeight) are large enough for all content with margins
• Sibling items in the same row/column use equal sizes and equal gaps unless there is a clear reason not to
• Left/right padding and top/bottom padding inside each container are visually balanced; no obvious one-sided blank area
• Containers, sub-groups, and sidebars are sized to content plus padding; if a blank region is larger than a normal item gap or roughly a full item row, tighten the layout
• Incomplete last rows are centered or otherwise balanced; they are not stuck to one side with a large empty remainder

Style checks:

• All nodes include

  whiteSpace=wrap;html=1;

  in style
• Every multi-line label uses

  


  inside

  value

  , never literal

  \n

• fontSize=14

  or larger for readability
• Edges use

  edgeStyle=orthogonalEdgeStyle

  for clean routing (except mindmaps which use

  curved=1

  )
• Decision nodes use

  rhombus

  shape; database nodes use

  shape=cylinder3

Step 5: CLI Export (Cross-Platform)

5a. Detect draw.io

Run these commands in order, stop at the first one that succeeds:

# 1. Try PATH first (works if user installed globally)
which draw.io 2>/dev/null || which drawio 2>/dev/null

If that fails, check platform-specific default paths:

macOS:

ls /Applications/draw.io.app/Contents/MacOS/draw.io 2>/dev/null

Windows (bash/MSYS2):

# Check common install locations
ls "/c/Program Files/draw.io/draw.io.exe" 2>/dev/null || \
ls "$LOCALAPPDATA/Programs/draw.io/draw.io.exe" 2>/dev/null

Linux:

ls /usr/bin/drawio 2>/dev/null || ls /snap/bin/drawio 2>/dev/null

5b. If not found, guide installation

Tell the user draw.io is not installed and suggest:

brew install --cask drawio

winget install JGraph.Draw

snap install drawio

Do NOT auto-install without user confirmation.

5c. Export

Use the detected path (stored as

$DRAWIO

"$DRAWIO" -x -f png --scale 2 -o output.png diagram.drawio

Export flags

-x

-f png/svg/pdf

-o path

--scale 2

--border 20

--width 1600

-p 0

--crop

Step 6: Deliver to User

After export:

• Show the exported image
• Tell the user the .drawio file location (can be edited at https://app.diagrams.net)
• Mention the export format used

File Naming

• Lowercase + hyphens:

  ecommerce-order-flow.drawio

• No Chinese characters, spaces, or special characters in filenames
• Output image uses same base name:

  ecommerce-order-flow.png

Architecture Diagram: Layered Block Style

For architecture diagrams, use the Layered Block Style — see

references/best-practices.md

Modifying Existing Diagrams

When the user is not satisfied with the result and asks for modifications:

1. Read the existing .drawio file first to understand current structure
2. Edit based on the existing XML — do not regenerate from scratch
3. Apply the user's requested changes while preserving the overall layout and style
4. Run the same self-review and export steps

Reference

references/best-practices.md

• General Rules — ID management, style essentials, common mistakes
• Architecture Diagram Templates (Layered Block Style) — the preferred architecture style with full XML templates and layout constants

For other diagram types (flowchart, UML, ER, mindmap, network, etc.), generate appropriate draw.io XML directly based on your knowledge. Read the "General Rules" section for basic formatting guidance.