Draw.io Diagram Generator#

Workflow#

text

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

<?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#

xml

<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#

xml

<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#

TypeDirectionPrimary axisSpacing (between edges)AlignmentFlowchartTop-to-bottomY increases100px verticalCenter xArchitectureLayered block (preferred)Y increases20px between layersLeft label + container rowsUML SequenceLeft-to-right participantsX increases200px horizontalTop-alignedUML ClassGrid / top-to-bottomY increases100px vertical, 80px horizontalLeft-aligned columnsER DiagramSpread / gridBoth axes120px bothGrid-alignedMindmapCenter-outward radialBoth axes150px from center per levelRadial symmetricNetworkHierarchical layersY increases100px vertical, 120px horizontalCenter each layer

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:

text

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:

text

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

If gap is much larger than the item width, or side padding is much larger than gap, adjust one of:

• 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#

ElementWidthHeightStandard node16060Decision (rhombus)16080Database (cylinder)14080Actor (UML)4060Start/End (rounded)16060Mindmap center18080Mindmap branch14050Mindmap leaf12040ER table header200variesGroup/containerautoauto

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:

bash

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

bash

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

Windows (bash/MSYS2):

bash

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

bash

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:

PlatformInstall CommandmacOSbrew install --cask drawioWindowswinget install JGraph.DrawLinuxsnap install drawioAllDownload from https://github.com/jgraph/drawio-desktop/releases

Do NOT auto-install without user confirmation.

5c. Export#

Use the detected path (stored as $DRAWIO) to export:

bash

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

Export flags#

FlagPurpose-xExport mode (no GUI)-f png/svg/pdfOutput format-o pathOutput file path--scale 22x resolution for crisp PNG--border 20Add border padding (px)--width 1600Constrain output width-p 0Export specific page (0-indexed)--cropCrop to diagram content

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 for full templates and layout constants. This is the preferred style: structured block layout with no arrows, horizontal layers, left label column, and optional cross-cutting sidebar.

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 contains:

• 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.