Draw.io Diagram Generator

Generate professional-grade Draw.io (mxGraph) XML diagrams from natural language. You ARE the LLM — generate the XML directly, validate it, fix issues, and deliver.

Critical Rules

Structure Rules

• S1: Check Stencil Names 🚨 NEVER guess stencil names. Check stencils/*.md for EXACT names. Wrong: mxgraph.cisco.router → Correct: mxgraph.cisco.routers.router
• S2: Stencils Require fillColor Many stencils have no default color. Always add fillColor/strokeColor. Exception: edge/link stencils are connectors, not devices.
• S3: Root Cells Required Must include <mxCell id="0"/> and <mxCell id="1" parent="0"/> or diagram won't render.
• S4: Labels Below Stencils Use verticalLabelPosition=bottom;verticalAlign=top;labelPosition=center;align=center; for device/icon labels.
• S5: mxCell Must Be Siblings ALL mxCell elements must be siblings under <root> — NEVER nest mxCell inside another mxCell.
• S6: Container Transparency For container shapes, use fillColor=none; to make background transparent and prevent covering child elements.
• S7: No Array Elements ⚠️ NEVER use <Array> elements in mxGeometry — this CRASHES draw.io! Let draw.io auto-route edges. Use exitX/exitY/entryX/entryY style params instead.
• S8: No XML Comments NEVER include <!-- ... --> in generated XML — breaks editing.

Layout Rules

• L1: Starting Margin Begin positioning from x=40, y=40.
• L2: Element Spacing Keep 40-60px gaps between connected shapes; 150-200px for routing channels between groups.
• L3: Compact Layouts Use vertical stacking or grid layouts. Keep within x: 0-800, y: 0-600 viewport. Avoid spreading elements too far apart.

Edge Routing Rules — CRITICAL for Clean Diagrams

• E1: No Shared Paths Multiple edges between same nodes must use DIFFERENT exit/entry positions (exitY=0.3 and exitY=0.7, NOT both 0.5).
• E2: Bidirectional Use Opposite Sides A→B: exitX=1, entryX=0. B→A: exitX=0, entryX=1.
• E3: Explicit Exit/Entry Points Every edge should specify: exitX, exitY, entryX, entryY in style.
• E4: Route Around Obstacles If any shape is between source and target, let draw.io auto-route with edgeStyle=orthogonalEdgeStyle. Do NOT use <Array> waypoints.
• E5: Plan Layout First Organize shapes into columns/rows. Trace each edge mentally: "What shapes are between source and target?"
• E6: Natural Connection Points NEVER use corners (entryX=1,entryY=1). Top-to-bottom: exitY=1, entryY=0. Left-to-right: exitX=1, entryX=0.
• E7: Diagonal Routing Principle When connecting distant nodes diagonally, route along the PERIMETER of the diagram, NOT through the middle where other shapes exist.

Pre-Generation Checklist

1. Do any edges cross over non-source/target shapes? → Rearrange layout
2. Do any two edges share the same path? → Adjust exit/entry points
3. Are any connections at corners? → Use edge centers instead
4. Could rearranging shapes reduce crossings? → Revise layout

Workflow

1. Understand the Request

Determine:

• Diagram type: Cloud architecture, microservices, network, UML, ERD, etc.
• Components: Systems, services, databases, actors involved
• Relationships: Connections (sync/async, data flow, dependencies)

If the user provides a file (PDF, DOCX, TXT, MD), read it and extract entities, relationships, and processes.

2. Read the Prompt References

Before generating, read these files for rules and styling guidance:

• references/drawio_system_prompt.txt — the master system prompt with all XML rules
• references/color_palette.md — professional colors by component type
• references/drawio_xml_rules.md — quick-reference for mxGraph syntax

Also study assets/example_simple.drawio as a structural reference.

3. Select Stencils (if applicable)

If the diagram involves vendor-specific icons (AWS, Azure, GCP, Cisco, Kubernetes, etc.):

1. Identify which stencil library to use from the table below
2. Read the corresponding stencils/<category>.md file for EXACT shape names
3. Note the required fillColor and recommended dimensions for each shape

NEVER guess stencil names — always verify against the stencil file.

4. Plan the Layout (Multi-Phase for Complex Diagrams)

For diagrams with >15 components, use this phased approach:

• P1: Plan — Identify diagram type, choose canvas size, select stencil libraries. Plan element positions first, then derive zone boundaries.
• P2: Zones — Write zone/container cells FIRST in XML (drawio renders by document order). Solid fill: rounded=1;fillColor=#BAC8D3;strokeColor=none;opacity=60. Dashed border: rounded=1;dashed=1;dashPattern=8 8;fillColor=none;strokeColor=#0BA5C4.
• P3: Elements — Position shapes on grid (multiples of 10/20). Keep consistent device style per stencil family.
• P4: Connections — Add edges last. Network links: endArrow=none;endFill=0. Data flow: endArrow=classic. Dashed for logical/VPN: dashed=1.
• P5: Labels — Add floating text, legends. Verify every element has a value or adjacent label.
• P6: Chunking — When a diagram exceeds ~30 elements, split XML output into chunks.

5. Generate the Draw.io XML

Following the system prompt rules, generate the complete mxFile XML. Key rules:

• Use the exact root skeleton: <mxfile> → <diagram> → <mxGraphModel> → <root>
• Always include <mxCell id="0"/> and <mxCell id="1" parent="0"/>
• Shapes: vertex="1" parent="1" with unique descriptive IDs
• Edges: edge="1" parent="1" with valid source and target
• NEVER use <Array> elements — crashes draw.io
• Use color palette by component type
• Position shapes at grid multiples of 10 or 20
• Labels match the user's language

Save the XML to a .drawio file using write_to_file.

6. Validate (ReAct Loop)

Run the validator script on the saved file:

python .agent/skills/drawio-generator/scripts/validate_drawio.py <output_file.drawio>

• If ✅ valid → proceed to step 7
• If ❌ errors → read the error messages, fix the XML, save again, re-validate
• Repeat until all checks pass

Common fixes:

• Duplicate IDs: Renumber cells sequentially
• Broken edges: Ensure source/target IDs exist as vertex cells
• Array elements: Remove <Array> children from edge geometries
• Malformed XML: Fix unclosed tags, unescape & or < in labels

7. Deliver

Tell the user:

• Where the .drawio file was saved
• Brief design concept (what architectural decisions you made)
• How to open: draw.io desktop, app.diagrams.net, or VS Code Draw.io extension

8. Iterative Refinement

If the user wants changes to an existing diagram:

1. Read the current .drawio file
2. Modify the XML preserving existing IDs where possible
3. Save, validate, and deliver the updated file

Stencil Libraries

drawio provides 8900+ pre-built stencils across 48 categories. Full stencil reference: See stencils/*.md files.

Stencil Usage Example

<!-- Cisco router with label below -->
<mxCell id="router1" value="Core Router" style="shape=mxgraph.cisco.routers.router;html=1;fillColor=#036897;strokeColor=#ffffff;strokeWidth=2;verticalLabelPosition=bottom;verticalAlign=top;labelPosition=center;align=center;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="78" height="53" as="geometry"/>
</mxCell>

<!-- AWS Lambda -->
<mxCell id="lambda1" value="Lambda" style="shape=mxgraph.aws4.lambda;html=1;fillColor=#ED7100;strokeColor=none;verticalLabelPosition=bottom;verticalAlign=top;" vertex="1" parent="1">
  <mxGeometry x="200" y="100" width="54" height="56" as="geometry"/>
</mxCell>

<!-- Kubernetes pod -->
<mxCell id="pod1" value="API Pod" style="shape=mxgraph.kubernetes.pod;html=1;fillColor=#326CE5;strokeColor=#ffffff;strokeWidth=2;verticalLabelPosition=bottom;verticalAlign=top;" vertex="1" parent="1">
  <mxGeometry x="300" y="100" width="50" height="50" as="geometry"/>
</mxCell>

Common Shapes Reference

Basic Shapes

<mxCell id="rect" value="Box" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
  <mxGeometry x="20" y="20" width="100" height="50" as="geometry"/></mxCell>
<mxCell id="rounded" value="Rounded" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
  <mxGeometry x="140" y="20" width="100" height="50" as="geometry"/></mxCell>
<mxCell id="circle" value="Circle" style="ellipse;whiteSpace=wrap;html=1;" vertex="1" parent="1">
  <mxGeometry x="260" y="10" width="70" height="70" as="geometry"/></mxCell>
<mxCell id="db" value="Database" style="shape=cylinder;whiteSpace=wrap;html=1;" vertex="1" parent="1">
  <mxGeometry x="350" y="5" width="60" height="80" as="geometry"/></mxCell>
<mxCell id="cloud" value="Cloud" style="ellipse;shape=cloud;whiteSpace=wrap;html=1;" vertex="1" parent="1">
  <mxGeometry x="430" y="10" width="100" height="70" as="geometry"/></mxCell>

Container / Swimlane

<!-- Swimlane with child elements (relative positioning) -->
<mxCell id="lane1" value="Frontend" style="swimlane;" vertex="1" parent="1">
  <mxGeometry x="40" y="40" width="200" height="200" as="geometry"/></mxCell>
<mxCell id="step1" value="Step 1" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="lane1">
  <mxGeometry x="20" y="60" width="160" height="40" as="geometry"/></mxCell>

Note: Children use parent="lane1" with coordinates RELATIVE to the swimlane. Edges always use parent="1".

Edge Patterns

<!-- Basic directional edge -->
<mxCell style="edgeStyle=orthogonalEdgeStyle;endArrow=classic;html=1;" edge="1" parent="1" source="a" target="b">
  <mxGeometry relative="1" as="geometry"/></mxCell>

<!-- Bidirectional: use different exit/entry Y positions -->
<mxCell id="e1" value="Request" style="edgeStyle=orthogonalEdgeStyle;exitX=1;exitY=0.3;entryX=0;entryY=0.3;endArrow=classic;html=1;" edge="1" parent="1" source="nodeA" target="nodeB">
  <mxGeometry relative="1" as="geometry"/></mxCell>
<mxCell id="e2" value="Response" style="edgeStyle=orthogonalEdgeStyle;exitX=0;exitY=0.7;entryX=1;entryY=0.7;endArrow=classic;html=1;" edge="1" parent="1" source="nodeB" target="nodeA">
  <mxGeometry relative="1" as="geometry"/></mxCell>

Common Style Reference

• Arrow Types: Inheritance(endArrow=block;endFill=0) Implementation(endArrow=block;endFill=0;dashed=1) Association(endArrow=open;endFill=1) Dependency(endArrow=open;dashed=1) Aggregation(startArrow=diamondThin;startFill=0) Composition(startArrow=diamondThin;startFill=1)
• Shape Styles: rounded(0,1) fillColor(hex) strokeColor(hex) strokeWidth(num) dashed(0,1) opacity(0-100) fontColor(hex) fontSize(num) fontStyle(0=normal,1=bold,2=italic,3=both) align(left,center,right) verticalAlign(top,middle,bottom) shadow(0,1)
• Edge Styles: edgeStyle(orthogonalEdgeStyle,entityRelationEdgeStyle,elbowEdgeStyle) curved(0,1) endArrow/startArrow(classic,block,open,oval,diamond,none) endFill/startFill(0=hollow,1=filled)
• State Colors: Pending(#dae8fc,#6c8ebf) Success(#d5e8d4,#82b366) Error(#f8cecc,#b85450) Warning(#fff2cc,#d6b656) Complete(#e1d5e7,#9673a6)

Common Pitfalls

Tips for AI Generation

1. Plan layout first: Sketch positions mentally before writing XML — identify potential edge crossings
2. Use grid alignment: Position shapes at multiples of 10 or 20
3. Unique IDs: Use descriptive IDs like client, server, db instead of random strings
4. Consistent spacing: Keep 40-60px gaps between connected shapes; 150-200px for routing channels
5. Layer backgrounds first: Define zone/container cells before shapes inside them
6. Color zones: Use light background colors with strokeColor=none for region highlighting
7. Verify edges mentally: Before generating, trace each edge and ask "Does this cross any shape?"
8. Escape special characters: Use < for <, > for >, & for &, " for "

Files