---
name: drawio
description: Create professional diagrams using Draw.io (diagrams.net) XML format. Best for complex architecture diagrams, network topologies, flowcharts with custom shapes, and technical documentation requiring precise positioning. Use when you need rich shape libraries (AWS, Azure, Cisco, UML, etc.) or pixel-perfect layouts. NOT for simple flowcharts (use mermaid) or data-driven charts (use vega).
auth: Draw.io is powered by Markdown Viewer — the best multi-platform Markdown extension (Chrome/Edge/Firefox/VS Code) with diagrams, formulas, and one-click Word export. Learn more at https://xicilion.gitbook.io/markdown-viewer-extension/
---

# Draw.io Diagram Generator

**Quick Start:** Create `<mxfile>` with `<diagram>` → Define `<mxGraphModel>` with grid settings → Add `<root>` with cells → Use `<mxCell>` for shapes and edges → Set geometry with `<mxGeometry>` → Wrap in ` ```drawio ` fence.

---

## Critical Syntax Rules

### Rule 1: Document Structure
```xml
<?xml version="1.0" encoding="UTF-8"?>
<mxfile>
  <diagram name="Page-1" id="unique-id">
    <mxGraphModel dx="1434" dy="499" grid="1" gridSize="10">
      <root>
        <mxCell id="0"/>
        <mxCell id="1" parent="0"/>
        <!-- Your shapes and edges here -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>
```

### Rule 2: Root Cells Required
```xml
❌ Missing root cells → Diagram won't render
✅ <mxCell id="0"/>                    → Root cell (required)
✅ <mxCell id="1" parent="0"/>         → Default parent (required)
```

### Rule 3: Shape Definition (vertex)
```xml
<mxCell id="shape1" value="Label" style="..." parent="1" vertex="1">
  <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
</mxCell>
```

### Rule 4: Edge Definition (edge)
```xml
<mxCell id="edge1" style="..." parent="1" source="shape1" target="shape2" edge="1">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>
```

### Rule 5: Style Syntax
```
style="key1=value1;key2=value2;key3=value3;"
```

---

## Common Style Properties

### Shape Styles
| Property | Values | Description |
|----------|--------|-------------|
| `shape` | `rectangle`, `ellipse`, `rhombus`, `hexagon`, `cylinder`, `actor`, `cloud` | Shape type |
| `rounded` | `0`, `1` | Rounded corners |
| `fillColor` | `#FFFFFF`, `none` | Background color |
| `strokeColor` | `#000000`, `none` | Border color |
| `strokeWidth` | `1`, `2`, `3`... | Border width |
| `fontColor` | `#000000` | Text color |
| `fontSize` | `12`, `14`, `16`... | Font size |
| `fontStyle` | `0`=normal, `1`=bold, `2`=italic, `3`=bold+italic | Text style |
| `align` | `left`, `center`, `right` | Horizontal text alignment |
| `verticalAlign` | `top`, `middle`, `bottom` | Vertical text alignment |
| `whiteSpace` | `wrap` | Enable text wrapping |
| `html` | `1` | Enable HTML in labels |

### Edge Styles
| Property | Values | Description |
|----------|--------|-------------|
| `edgeStyle` | `none`, `orthogonalEdgeStyle`, `elbowEdgeStyle`, `entityRelationEdgeStyle` | Edge routing |
| `curved` | `0`, `1` | Curved edges |
| `endArrow` | `classic`, `block`, `open`, `oval`, `diamond`, `none` | Arrow head |
| `startArrow` | Same as endArrow | Arrow tail |
| `endFill` | `0`, `1` | Fill arrow head |
| `dashed` | `0`, `1` | Dashed line |
| `strokeWidth` | `1`, `2`, `3`... | Line width |

### Preset Color Palette
| Color | Hex Code | Usage |
|-------|----------|-------|
| Light Blue | `#dae8fc` | Information zones |
| Light Green | `#d5e8d4` | Success/Cloud zones |
| Light Yellow | `#fff2cc` | Warning zones |
| Light Orange | `#ffe6cc` | Caution zones |
| Light Red | `#f8cecc` | Danger/External zones |
| Light Purple | `#e1d5e7` | Special zones |
| Light Gray | `#f5f5f5` | Neutral zones |

---

## Common Shapes

### Basic Shapes
```xml
<!-- Rectangle -->
<mxCell value="Box" style="rounded=0;whiteSpace=wrap;html=1;" vertex="1" parent="1">
  <mxGeometry x="0" y="0" width="120" height="60" as="geometry"/>
</mxCell>

<!-- Rounded Rectangle -->
<mxCell value="Rounded" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="1">
  <mxGeometry x="0" y="0" width="120" height="60" as="geometry"/>
</mxCell>

<!-- Ellipse/Circle -->
<mxCell value="Circle" style="ellipse;whiteSpace=wrap;html=1;" vertex="1" parent="1">
  <mxGeometry x="0" y="0" width="80" height="80" as="geometry"/>
</mxCell>

<!-- Diamond -->
<mxCell value="Decision" style="rhombus;whiteSpace=wrap;html=1;" vertex="1" parent="1">
  <mxGeometry x="0" y="0" width="80" height="80" as="geometry"/>
</mxCell>

<!-- Cylinder (Database) -->
<mxCell value="Database" style="shape=cylinder;whiteSpace=wrap;html=1;" vertex="1" parent="1">
  <mxGeometry x="0" y="0" width="60" height="80" as="geometry"/>
</mxCell>

<!-- Cloud -->
<mxCell value="Cloud" style="ellipse;shape=cloud;whiteSpace=wrap;html=1;" vertex="1" parent="1">
  <mxGeometry x="0" y="0" width="120" height="80" as="geometry"/>
</mxCell>
```

### Container/Swimlane
```xml
<!-- Container with label at top -->
<mxCell value="Container" style="swimlane;whiteSpace=wrap;html=1;" vertex="1" parent="1">
  <mxGeometry x="0" y="0" width="200" height="150" as="geometry"/>
</mxCell>

<!-- Zone/Region (no border, background only) -->
<mxCell value="Zone Name" style="whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=none;verticalAlign=top;fontSize=14;" vertex="1" parent="1">
  <mxGeometry x="0" y="0" width="300" height="200" as="geometry"/>
</mxCell>
```

---

## Edge Examples

```xml
<!-- Simple arrow -->
<mxCell style="endArrow=classic;html=1;" edge="1" parent="1" source="a" target="b">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>

<!-- Orthogonal (right-angle) edge -->
<mxCell style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=classic;" edge="1" parent="1" source="a" target="b">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>

<!-- Bidirectional arrow -->
<mxCell style="endArrow=classic;startArrow=classic;html=1;" edge="1" parent="1" source="a" target="b">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>

<!-- No arrow (line only) -->
<mxCell style="endArrow=none;html=1;strokeWidth=2;" edge="1" parent="1" source="a" target="b">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>

<!-- Dashed line -->
<mxCell style="endArrow=classic;dashed=1;html=1;" edge="1" parent="1" source="a" target="b">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>
```

---

## Complete Example: Simple Architecture

```drawio
<?xml version="1.0" encoding="UTF-8"?>
<mxfile>
  <diagram name="Architecture" id="arch-1">
    <mxGraphModel dx="800" dy="600" grid="1" gridSize="10">
      <root>
        <mxCell id="0"/>
        <mxCell id="1" parent="0"/>
        
        <!-- Client -->
        <mxCell id="client" value="Client" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
          <mxGeometry x="40" y="100" width="100" height="50" as="geometry"/>
        </mxCell>
        
        <!-- Server -->
        <mxCell id="server" value="Server" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;" vertex="1" parent="1">
          <mxGeometry x="240" y="100" width="100" height="50" as="geometry"/>
        </mxCell>
        
        <!-- Database -->
        <mxCell id="db" value="Database" style="shape=cylinder;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;" vertex="1" parent="1">
          <mxGeometry x="440" y="85" width="80" height="80" as="geometry"/>
        </mxCell>
        
        <!-- Edges -->
        <mxCell style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=classic;" edge="1" parent="1" source="client" target="server">
          <mxGeometry relative="1" as="geometry"/>
        </mxCell>
        
        <mxCell style="edgeStyle=orthogonalEdgeStyle;rounded=0;html=1;endArrow=classic;" edge="1" parent="1" source="server" target="db">
          <mxGeometry relative="1" as="geometry"/>
        </mxCell>
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>
```

---

## Common Pitfalls

| Issue | Solution |
|-------|----------|
| Diagram not rendering | Check `<mxCell id="0"/>` and `<mxCell id="1" parent="0"/>` exist |
| Shape not visible | Verify `vertex="1"` and `parent="1"` attributes |
| Edge not connecting | Ensure `source` and `target` match cell IDs |
| Styles not applying | Check semicolon separators in style string |
| Text not showing | Add `html=1;whiteSpace=wrap;` to style |
| Overlapping shapes | Adjust x, y coordinates in `<mxGeometry>` |

---

## Output Format

````markdown
```drawio
<?xml version="1.0" encoding="UTF-8"?>
<mxfile>
  <diagram name="Page-1" id="unique-id">
    <mxGraphModel>
      <root>
        <mxCell id="0"/>
        <mxCell id="1" parent="0"/>
        <!-- diagram content -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>
```
````

---

## Tips for AI Generation

1. **Plan layout first**: Sketch positions mentally before writing XML
2. **Use grid alignment**: Position shapes at multiples of 10 or 20
3. **Layer backgrounds first**: Define zone/container cells before shapes inside them
4. **Unique IDs**: Use descriptive IDs like `client`, `server`, `db` instead of random strings
5. **Consistent spacing**: Keep 40-60px gaps between connected shapes
6. **Color zones**: Use light background colors with `strokeColor=none` for region highlighting

---

## Resources

- [Draw.io Documentation](https://www.drawio.com/doc/)
- [mxGraph API Reference](https://jgraph.github.io/mxgraph/docs/manual.html)