| name | drawio-diagram |
| description | Generate draw.io (diagrams.net) diagrams using a grid cell coordinate system, catching left/right and top/bottom imbalance, arrow/text overlap via an MCP tool loop (create→export→verify→edit). Triggers — "draw draw.io", "make diagram", "drawio diagram", "architecture diagram", "draw flowchart/sequence", "mxGraph XML", "fix diagram alignment/overlap". |
| origin | harness |
| version | 1.0.0 |
| workloads | ["architecture","writing"] |
draw.io Diagram Generator
When LLMs improvise coordinates, left/right and top/bottom balance breaks, and arrows and text overlap.
This skill addresses the problem on two axes:
- Grid cell coordinate system — Positions are computed only via
row/col × constant formulas, eliminating guesswork.
- MCP verification loop — Iterate
create → export(PNG) → coordinate/image dual verification → edit to converge on actual results.
When to Activate
- draw.io / diagrams.net diagram generation requests
- Architecture diagrams, flowcharts, sequences, org charts, ER, network diagrams
- Requests to fix alignment, overlap, or balance in existing diagrams
- Direct mxGraphModel XML authoring requests
Core Principle (Why these rules)
Eliminate calculation; let coordinates fall out of rules automatically.
Qualitative instructions like "balance it" fail every time. Coordinates must be bound to arithmetic formulas to guarantee alignment.
1. Grid Cell Coordinate System (Most Important)
Cell Constants
CELL_W = 240 # Cell horizontal spacing
CELL_H = 160 # Cell vertical spacing
NODE_W = 200 # Default shape width (except special shapes)
NODE_H = 80 # Default shape height
MARGIN = 40 # Canvas top-left margin
Coordinate Formula (No arbitrary coordinates outside this formula)
x = MARGIN + col * CELL_W
y = MARGIN + row * CELL_H
- All nodes have only
(row, col) integer coordinates. Do not write pixels directly.
- Nodes at the same level (same row or same col) must share identical formula values → automatic alignment.
Left/Right Symmetry (Balance)
When a level has N nodes, center them symmetrically based on the total canvas column count MAX_COLS:
start_col = floor((MAX_COLS - N) / 2)
Each node col = start_col + i (i = 0..N-1)
- Fix
MAX_COLS as the maximum node count in any level across the entire diagram.
- All levels center-align against the same
MAX_COLS, so left/right balance is arithmetically correct.
Flow Direction
- Choose only one primary flow direction (top→bottom recommended, or left→right).
- Use reverse-direction edges only as exceptions.
2. Connection Point and Routing Rules (Prevent Arrow Overlap)
Fixed Connection Points (Pin by direction)
Vertical flow (top→bottom):
Source shape: exitX=0.5 exitY=1 (bottom center)
Target shape: entryX=0.5 entryY=0 (top center)
Horizontal flow (left→right):
Source shape: exitX=1 exitY=0.5 (right center)
Target shape: entryX=0 entryY=0.5 (left center)
Multi-branch — Distribute Connection Points
When multiple branches leave one shape, distribute exit points so lines do not overlap:
2 branches: exitX = 0.33 / 0.67
3 branches: exitX = 0.25 / 0.5 / 0.75
Distribute entryX on the target side identically. Never let two edges share the same path.
Edge Style (Always apply)
edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=classic;
- Orthogonal routing, 90-degree bends only, maximum 2 bends per edge.
- Bidirectional (A<->B) use opposite connection points.
3. Reserve Label Space in Advance (Half of all overlap is here)
Half of all overlap happens because shape spacing does not account for label space.
- If an edge has a label, widen the vertical spacing between the connected shapes to 1.5 cells
(row difference 1 → 1.5, i.e., +80px for that segment only).
- Edge label style must include labelBackgroundColor=#FFFFFF (readability).
- If label width exceeds NODE_W, wrap to two lines.
- Treat icon+caption as a single bounding box. Edges bypass the caption area by ~20px.
If the bottom is used for connection, place the caption on an empty side (left/right).
4. Text Containment (HARD CONSTRAINT)
- All shape styles must include whiteSpace=wrap;html=1;
- Text is 100% contained inside the box. Ensure minimum 8px padding on all sides.
- If text does not fit, enlarge the box — never shrink padding or clip text.
· Horizontal overflow: Increase NODE_W to 240/280 and shift all subsequent columns by one cell.
· Vertical overflow: Increase NODE_H to 100/120.
- Maintain consistent fontSize/color/style per category.
5. Color and Structure (Semantic-Based)
- Use color meaningfully based on state/type only (no arbitrary use).
- If colors carry 2+ meanings, place a small legend in the bottom-right corner.
- Group related shapes with containers/swimlanes to distinguish areas.
- Visual hierarchy: title > nodes > annotations (distinguish by size/weight).
6. Execution Workflow (MCP Loop)
1. start_session
→ Open browser live preview.
2. create_new_diagram(xml)
→ Generate XML with coordinates computed via §1~5 rules.
[WARNING] When modifying an existing diagram, never use create → get_diagram then edit_diagram.
3. export_diagram(path="./_drawio_check.png", format="png")
4. [Coordinate Verification] — Arithmetic first filter
Check rectangle overlap for all shape pairs (A,B):
overlap = (A.x < B.x+B.w) && (A.x+A.w > B.x)
&& (A.y < B.y+B.h) && (A.y+A.h > B.y)
If overlap, reposition via §1 formula.
Output verification table first: | Node | x | y | RightEdge | BottomEdge |
5. [Image Verification] — Open PNG via Read for visual inspection
· Do arrows pierce shapes?
· Do edges share paths?
· Do labels overlap shapes/lines?
· Is left/right and top/bottom balance correct (no skew)?
· Does text overflow boxes?
6. If issues found, get_diagram → edit_diagram(operations) to fix only that cell → repeat from step 3.
Termination condition: Coordinate verification passes AND image verification shows 0 defects.
7. Clean up _drawio_check.png after completion (if unnecessary).
Verification Checklist (Required before output)
- Edges do not pierce shapes — all anchored to defined connection points.
- No edge path sharing/duplication, minimize crossings.
- Text containment — all box text 100% inside with 8px padding.
- Labels do not overlap shapes/lines (background #FFFFFF).
- Edges/arrows do not touch icon captions.
- Uniform spacing/alignment, all elements within page bounds.
- Valid XML, all IDs unique (id=0,1 reserved, top-level parent=1).
- If AWS icons, no empty rectangles (color-only fill) — see §7.
7. AWS Architecture — Official Icons (mxgraph.aws4)
AWS architecture diagrams use draw.io's built-in mxgraph.aws4 official icons, not generic boxes.
Only non-AWS resources (NGINX, app microservices) use boxes.
resourceIcon Style Template
sketch=0;outlineConnect=0;fontColor=#232F3E;gradientColor=none;
fillColor={brand color};strokeColor=#ffffff;dashed=0;html=1;fontSize=12;aspect=fixed;
shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.{icon name};
- Icon size is 78×78 (resourceIcon standard).
- fillColor by category: Networking
#8C4FFF, Storage #7AA116, Security #DD344C,
Containers #ED7100, Database #C925D1, Analytics/Streaming #E7157B.
Empty Icon (empty box) Trap — Always Verify
If the stencil name in resIcon= is not in the installed aws4 library, draw.io
renders a color-only empty rectangle without error. Coordinate verification will never catch this;
only image verification (PNG) reveals it.
Do not trust names from memory. If in doubt, list candidate names in one diagram,
export → visually confirm which actually renders, then apply to the main diagram.
Verified correct names (often short abbreviations, not full names):
| Resource | [O] Correct resIcon | [X] Produces empty box |
|---|
| S3 | s3 | simple_storage_service |
| EKS | eks | elastic_kubernetes_service |
| MSK | managed_streaming_for_kafka | managed_streaming_for_apache_kafka |
| ElastiCache | elasticache | — |
| Aurora | aurora | — |
| Route 53 | route_53 | — |
| CloudFront | cloudfront | — |
| DynamoDB | dynamodb | — |
| WAF | waf | — |
| Users (crowd) | shape=mxgraph.aws4.users (not resIcon) | — |
Icon Caption vs Arrow (Apply §3 ICON LABELS)
- Icon captions are separate labels and easily overlap arrows.
- Spine icons with downward arrows → place caption on the side:
verticalLabelPosition=middle;verticalAlign=middle;labelPosition=right;align=left;spacingLeft=8;
- If another edge exits from that icon's side (e.g., right), place caption on the opposite side:
labelPosition=left;align=right;spacingRight=8;
- Leaf icons without downward arrows (S3, DB types) → caption below (standard):
verticalLabelPosition=bottom;verticalAlign=top;align=center;
Mini Template (Vertical Flow, 3-Node Level)
<mxGraphModel>
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
<mxCell id="n1" value="Client" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;"
vertex="1" parent="1">
<mxGeometry x="280" y="40" width="200" height="80" as="geometry"/>
</mxCell>
<mxCell id="n2" value="API Gateway" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;"
vertex="1" parent="1">
<mxGeometry x="40" y="200" width="200" height="80" as="geometry"/>
</mxCell>
<mxCell id="n3" value="Auth Service" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;"
vertex="1" parent="1">
<mxGeometry x="280" y="200" width="200" height="80" as="geometry"/>
</mxCell>
<mxCell id="n4" value="DB" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;"
vertex="1" parent="1">
<mxGeometry x="520" y="200" width="200" height="80" as="geometry"/>
</mxCell>
<mxCell id="e1" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=classic;exitX=0.25;exitY=1;entryX=0.5;entryY=0;"
edge="1" parent="1" source="n1" target="n2">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="e2" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=classic;exitX=0.5;exitY=1;entryX=0.5;entryY=0;"
edge="1" parent="1" source="n1" target="n3">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
<mxCell id="e3" style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=classic;exitX=0.75;exitY=1;entryX=0.5;entryY=0;"
edge="1" parent="1" source="n1" target="n4">
<mxGeometry relative="1" as="geometry"/>
</mxCell>
</root>
</mxGraphModel>
Anti-Patterns
