/draw-io-diagram-generator

name: draw-io-diagram-generator
description: Use when creating, editing, or generating draw.io diagram files (.drawio, .drawio.svg, .drawio.png). Covers mxGraph XML authoring, shape libraries, style strings, flowcharts, system architecture, sequence diagrams, ER diagrams, UML class diagrams, network topology, layout strategy, the hediet.vscode-drawio VS Code extension, and the full agent workflow from request to a ready-to-open file.

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:

<!-- 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):

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

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

|