draw-io-diagram-generator

What this skill does

# Draw.io Diagram Generator

This skill enables you to generate, edit, and validate draw.io (`.drawio`) diagram files with
correct mxGraph XML structure. All generated files open immediately in the
[Draw.io VS Code extension](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio)
(`hediet.vscode-drawio`) without any manual fixes required. You can also open the files in the draw.io web app or desktop app if you prefer.

---

## 1. When to Use This Skill

**Trigger phrases (load this skill when you see these)**

- "create a diagram", "draw a flowchart", "generate an architecture diagram"
- "design a sequence diagram", "make a UML class diagram", "build an ER diagram"
- "add a .drawio file", "update the diagram", "visualise the flow"
- "document the architecture", "show the data model", "diagram the service interactions"
- Any request to produce or modify a `.drawio`, `.drawio.svg`, or `.drawio.png` file

**Supported diagram types**

| Diagram Type | Template Available | Description |
|---|---|---|
| Flowchart | `assets/templates/flowchart.drawio` | Process flows with decisions and branches |
| System Architecture | `assets/templates/architecture.drawio` | Multi-tier / layered service architecture |
| Sequence Diagram | `assets/templates/sequence.drawio` | Actor lifelines and timed message flows |
| ER Diagram | `assets/templates/er-diagram.drawio` | Database tables with relationships |
| UML Class Diagram | `assets/templates/uml-class.drawio` | Classes, interfaces, enums, relationships |
| Network Topology | (use shape library) | Routers, servers, firewalls, subnets |
| BPMN Workflow | (use shape library) | Business process events, tasks, gateways |
| Mind Map | (manual) | Central topic with radiating branches |

---

## 2. Prerequisites

- If running with VS Code integration enabled, Install the drawio extension: **draw.io VS Code extension** — `hediet.vscode-drawio` (extension id). Install with:
  ```
  ext install hediet.vscode-drawio
  ```
- **Supported file extensions**: `.drawio`, `.drawio.svg`, `.drawio.png`
- **Python 3.8+** (optional) — for the validation and shape-insertion scripts in `scripts/`

---

## 3. Step-by-Step Agent Workflow

Follow these steps in order for every diagram generation task.

### Step 1 — Understand the Request

Ask or infer:
1. **Diagram type** — What kind of diagram? (flowchart, architecture, UML, ER, sequence, network...)
2. **Entities / actors** — What are the main components, actors, classes, or tables?
3. **Relationships** — How are they connected? What direction? What cardinality?
4. **Output path** — Where should the `.drawio` file be saved?
5. **Existing file** — Are we creating new or editing an existing file?

If the request is ambiguous, infer the most sensible diagram type from context (e.g. "show the tables" → ER diagram, "show how the API call flows" → sequence diagram).

### Step 2 — Select a Template or Start Fresh

- **Use a template** when the diagram type matches one in `assets/templates/`. Copy the template structure and replace placeholder values.
- **Start fresh** for novel layouts. Begin with the minimal valid skeleton:

```xml
<!-- Set modified="" to the current ISO 8601 timestamp when generating a new file -->
<mxfile host="Electron" modified="" version="26.0.0">
  <diagram id="page-1" name="Page-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="1169" pageHeight="827"
                  math="0" shadow="0">
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <!-- Your cells go here -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>
```

> **Rule**: ids `0` and `1` are ALWAYS required and must be the first two cells. Never reuse them.

### Step 3 — Plan the Layout

Before generating XML, sketch the logical placement:
- Organise into **rows** or **tiers** (use swimlanes for layers)
- **Horizontal spacing**: 40–60px between same-row shapes
- **Vertical spacing**: 80–120px between tier rows
- Standard shape size: `120x60` px for process boxes, `160x80` px for swimlanes
- Default canvas: A4 landscape = `1169 x 827` px

### Step 4 — Generate the mxGraph XML

**Vertex cell** (every shape):
```xml
<mxCell id="unique-id" value="Label"
        style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;"
        vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="120" height="60" as="geometry" />
</mxCell>
```

**Edge cell** (every connector):
```xml
<mxCell id="edge-id" value="Label (optional)"
        style="edgeStyle=orthogonalEdgeStyle;html=1;"
        edge="1" source="source-id" target="target-id" parent="1">
  <mxGeometry relative="1" as="geometry" />
</mxCell>
```

**Critical rules**:
- Every cell id must be **globally unique** within the file
- Every vertex must have an `mxGeometry` child with `x`, `y`, `width`, `height`, `as="geometry"`
- Every edge must have `source` and `target` matching existing vertex ids — **exception**: floating edges (e.g. sequence diagram lifelines) use `sourcePoint`/`targetPoint` inside `<mxGeometry>` instead; see §4 Sequence Diagram
- Every cell's `parent` must reference an existing cell id
- Use `html=1` in style when the label contains HTML (`<b>`, `<i>`, `<br>`)
- Escape XML special characters in labels: `&` => `&amp;`, `<` => `&lt;`, `>` => `&gt;`

### Step 5 — Apply Correct Styles

Use the standard semantic color palette for consistency:

| Purpose | fillColor | strokeColor |
|---|---|---|
| Primary / Info | `#dae8fc` | `#6c8ebf` |
| Success / Start | `#d5e8d4` | `#82b366` |
| Warning / Decision | `#fff2cc` | `#d6b656` |
| Error / End | `#f8cecc` | `#b85450` |
| Neutral | `#f5f5f5` | `#666666` |
| External / Partner | `#e1d5e7` | `#9673a6` |

Common style strings by diagram type:

```
# Rounded process box (flowchart)
rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;

# Decision diamond
rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;

# Start/End terminal
ellipse;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;

# Database cylinder
shape=mxgraph.flowchart.database;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;

# Swimlane container (tier)
swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;fontStyle=1;

# UML class box
swimlane;fontStyle=1;align=center;startSize=40;fillColor=#dae8fc;strokeColor=#6c8ebf;

# Interface / stereotype box
swimlane;fontStyle=3;align=center;startSize=40;fillColor=#f5f5f5;strokeColor=#666666;

# ER table container
shape=table;startSize=30;container=1;collapsible=1;childLayout=tableLayout;

# Orthogonal connector
edgeStyle=orthogonalEdgeStyle;html=1;

# ER relationship (crow's foot)
edgeStyle=entityRelationEdgeStyle;html=1;endArrow=ERmany;startArrow=ERone;
```

> See `references/style-reference.md` for the complete style key catalog and `references/shape-libraries.md` for all shape library names.

### Step 6 — Save and Validate

1. **Write the file** to the requested path with `.drawio` extension
2. **Run the validator** (optional but recommended):
   ```bash
   python .github/skills/draw-io-diagram-generator/scripts/validate-drawio.py <path-to-file.drawio>
   ```
3. **Tell the user** how to open the file:
   > "Open `<filename>` in VS Code — it will render automatically with the draw.io extension. You can use draw.io's web app or desktop app as well if you prefer."
4. **Provide a brief description** of what is in the diagram so the user knows what to expect.

---

## 4. Diagram-Type Recipes

### Flowchart

Key elements: Start (ellipse) => Process (rounded rectangle) => Decision (diamond) => End (ellipse)

```xml
<!-- Start node -->
<mxCell id="start" value="Start"
        style="ellipse;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;"
        vertex="1" parent="1">
  <mxGeometry x="500" y="80" width="120" height="60" as="g