bruce-drawio

name

bruce-drawio

description

**Use this skill** when the user wants to create any diagram: flowchart, architecture, UML (sequence/class), ER, mindmap, network topology, or any visual diagram. Trigger words: "draw", "diagram", "flowchart", "architecture", "UML", "sequence diagram", "mindmap", "ER diagram", "network topology", "visualize", "draw.io", "drawio". Workflow: understand requirements -> generate drawio XML directly -> self-review -> CLI export PNG/SVG/PDF.

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

Type	Direction	Primary axis	Spacing (between edges)	Alignment
Flowchart	Top-to-bottom	Y increases	100px vertical	Center x
Architecture	Layered block (preferred)	Y increases	20px between layers	Left label + container rows
UML Sequence	Left-to-right participants	X increases	200px horizontal	Top-aligned
UML Class	Grid / top-to-bottom	Y increases	100px vertical, 80px horizontal	Left-aligned columns
ER Diagram	Spread / grid	Both axes	120px both	Grid-aligned
Mindmap	Center-outward radial	Both axes	150px from center per level	Radial symmetric
Network	Hierarchical layers	Y increases	100px vertical, 120px horizontal	Center 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:

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

Element	Width	Height
Standard node	160	60
Decision (rhombus)	160	80
Database (cylinder)	140	80
Actor (UML)	40	60
Start/End (rounded)	160	60
Mindmap center	180	80
Mindmap branch	140	50
Mindmap leaf	120	40
ER table header	200	varies
Group/container	auto	auto

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:

Platform	Install Command
macOS	brew install --cask drawio
Windows	winget install JGraph.Draw
Linux	snap install drawio
All	Download 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:

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

Export flags

Flag	Purpose
-x	Export mode (no GUI)
-f png/svg/pdf	Output format
-o path	Output file path
--scale 2	2x resolution for crisp PNG
--border 20	Add border padding (px)
--width 1600	Constrain output width
-p 0	Export specific page (0-indexed)
--crop	Crop 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.