Draw.io Diagram Builder

---
name: drawio-diagram-builder
description: Use when the user wants a draw.io diagram — architecture, network, ERD, UML, C4, BPMN, or swimlane — as an editable .drawio file or an exported PNG/SVG/PDF, especially with official cloud/vendor icons, or generated from a codebase, Terraform/Kubernetes config, or SQL schema. Triggers on "draw.io", "drawio", "diagram with AWS icons", "diagram from my terraform", "editable diagram".
---

# Draw.io Diagram Builder

Author `.drawio` XML and export it locally with the draw.io desktop CLI. Protocol distilled from Agents365-ai/drawio-skill (v2.1.0).

## Route the request first

draw.io is one of three diagram toolchains, and the wrong one wastes the whole pass:

| The diagram needs | Toolchain |
|---|---|
| Official vendor icons, solid fills, swimlanes, print/export quality | draw.io (this skill) |
| Inline rendering in Markdown, git-diffable source | Mermaid |
| A hand-drawn whiteboard look for informal review | Excalidraw |

If the request fits draw.io, confirm three things before authoring: the diagram type (architecture, ERD, UML class, sequence, C4, BPMN, network, swimlane, flowchart), the output format (editable `.drawio`, or exported PNG/SVG/PDF), and the source of truth (a description, or an artifact such as a repo, Terraform config, Kubernetes manifests, or SQL DDL).

## Prefer generation from artifacts over generation from memory

When the system being diagrammed exists as files, derive the diagram from the files. The source repo ships importers for exactly this reason: an import graph extracted from a Python/JS/Go/Rust project, a resource-reference graph from Terraform or Kubernetes manifests, service topology from docker-compose, and table/foreign-key structure from `CREATE TABLE` statements. Edges that come from actual references (role ARNs, selectors, volume mounts, foreign keys) are correct by construction; edges recalled from a description are guesses. Reserve hand-authored XML for systems that only exist in the user's head.

## Authoring rules for hand-written XML

- **Never guess a shape style string.** draw.io styles like `shape=mxgraph.aws4.lambda_function` are exact identifiers; a typo renders a blank box. Resolve every vendor icon (AWS, Azure, GCP, Cisco, Kubernetes, UML, BPMN) against the official shape libraries before use.
- **Grid-align everything.** Snap coordinates to a consistent grid, scale spacing with diagram size, and route connectors around nodes rather than through them.
- **One fill color per logical tier** (clients, services, data stores, external systems), at most four colors. Color that does not encode a group comes out.
- **Containers for grouping.** Swimlanes and parent containers express ownership; loose boxes floating near each other do not.
- **Spread edges at the shape boundary.** When several edges meet one side of a node, pin distinct exit/entry points so the lines stay separated instead of stacking into one stroke.

## C4 models get pages, not one giant canvas

For C4 requests, build the multi-page set: System Context, Container, Component, each on its own page with the official C4 shapes, and link parent elements to their child page so a click drills down. One page trying to show all three levels fails at every level.

## Validate before you deliver

1. **Structural lint on the XML:** no dangling edges, no duplicate or reserved ids, no broken parent references, no overlapping nodes.
2. **Render and look at the output.** Export a PNG and inspect it for clipped labels, stacked edges, and overlaps the XML did not reveal. Fix and re-export, at most two rounds. Geometry that looks plausible as numbers is frequently wrong as pixels.

## Export

Export through the draw.io desktop CLI (`drawio` on PATH; on macOS `brew install --cask drawio`). PNG is the default; SVG for docs that scale, PDF for print. Use embedded-diagram export with a double extension (`name.drawio.png`) so the delivered image reopens in draw.io as the editable diagram. If the CLI is unavailable, say so and deliver the `.drawio` XML with a diagrams.net link as the fallback; do not silently skip the rendered self-check.

## Deliverable

The `.drawio` file (or export), plus two sentences: what the diagram shows and where the reader should look first. For multi-page C4 sets, name each page and its intended audience.