Draw.io Diagrams

Overview

Generate .drawio XML files ready to open in draw.io desktop for further editing and export to PNG/SVG/PDF/JPG.

When to use / when NOT to use

Use this skill for: polished, precise diagrams (architecture, network, strict UML, ERD), anything needing solid opaque fills, 10,000+ stock/branded shapes, swimlanes, or custom geometry. Generates .drawio files ready to open in draw.io desktop.

Do NOT use it — route elsewhere — for:

• A casual hand-drawn / whiteboard look → excalidraw or tldraw.
• Diagrams-as-code that live in git / render in Markdown → mermaid (general) or plantuml (UML).
• Freeform infinite-canvas sketching or freehand strokes → tldraw.

Bundled resources

When the workflow references one of these, read it on demand — none of them need to be in context up front.

Prerequisites

The draw.io desktop app must be installed and the CLI accessible:

macOS sandbox / sandbox isolation note (e.g., codex.app): In some sandboxed macOS environments, invoking the draw.io desktop CLI (even drawio --version) can crash the draw.io process or produce no output. If that happens, treat the CLI as unavailable in this sandbox isolation — do not keep retrying inside the sandbox. Prefer a non-sandboxed host environment (outside sandbox isolation) for any CLI export work, or use the browser fallback / XML-only outputs.

# macOS (Homebrew — recommended; CLI binary is `drawio`, not `draw.io`)
brew install --cask drawio
drawio --version

# macOS (full path if not in PATH)
/Applications/draw.io.app/Contents/MacOS/draw.io --version

# Windows
"C:\Program Files\draw.io\draw.io.exe" --version

# Linux
drawio --version

Install draw.io desktop if missing:

• macOS: brew install --cask drawio or download from https://github.com/jgraph/drawio-desktop/releases
• Windows: download installer from https://github.com/jgraph/drawio-desktop/releases
• Linux: download .deb/.rpm from https://github.com/jgraph/drawio-desktop/releases — do not use snap (AppArmor sandbox denies secrets/keyring on servers, causes crash)

Workflow

Before starting the workflow, assess whether the user's request is specific enough. If key details are missing, ask 1-3 focused questions:

• Diagram type — which preset? (ERD, UML, Sequence, Architecture, ML/DL, Flowchart, or general)
• Output location — default is the user's working dir; honor any explicit path the user gives (e.g. "put it in ./artifacts/"). Don't ask if they didn't mention one.
• Scope/fidelity — how many components? Any specific technologies or labels?

Skip clarification if the request already specifies these details or is clearly simple (e.g., "draw a flowchart of X").

Step 0 — Resolve active preset. Determine which (if any) user-defined style preset applies to this generation.

• Scan the user's message for a phrase that clearly names a style preset: "use my <name> style", "with my <name> style", "in <name> mode", "in the style of <name>". A bare with <name> does not count — "draw a diagram with redis" names a component, not a style. If a clear match is found → active preset = <name>.
• Else, check ~/.drawio-skill/styles/ for any file with "default": true. If found → active preset = that one.
• Else → no preset active; fall through to the built-in color/shape/edge conventions for the rest of the workflow.

Load the preset JSON from ~/.drawio-skill/styles/<name>.json, falling back to <this-skill-dir>/styles/built-in/<name>.json. If the named preset exists in neither location, tell the user the name is unknown, list the available presets (user dir + built-in), and stop — do not silently fall back to defaults.

When a preset loads successfully, mention it in the first line of the reply: "Using preset <name> (confidence: <level>)." See references/style-presets.md → "Applying a preset" for how the preset changes color/shape/edge/font decisions.

1. Check deps — resolve which name the binary has on this system and use that name verbatim in every subsequent command in this workflow. Try in order: (a) drawio --version (the canonical name for Homebrew cask, jgraph .deb/.rpm, Arch AUR), (b) draw.io --version (older builds, some custom symlinks, some distro packages), (c) macOS .app direct: /Applications/draw.io.app/Contents/MacOS/draw.io --version, (d) Windows: "C:\Program Files\draw.io\draw.io.exe" --version. The first one that prints a version is your binary; remember the exact path/name and substitute it for drawio in every command below. Do not copy the example commands verbatim if your binary is named differently — the examples use drawio only because it's the most common. On macOS-Homebrew, drawio is just a thin wrapper script that execs /Applications/draw.io.app/Contents/MacOS/draw.io — they run the same engine, so candidate (c) is only needed when the drawio wrapper is absent (e.g. the app was installed by drag-and-drop without the cask). Note the major version for CLI flag compatibility.
2. Plan — identify shapes, relationships, layout (LR or TB), group by tier/layer
3. Generate — produce the .drawio file via hand-written XML or a bundled generator: (a) Hand-written XML for custom styling, vendor icons, swimlanes, precise geometry — read references/xml-authoring.md first (skeleton, cell forms, palette, spacing rules). (b) A bundled generator for the data-driven cases below. For large or layout-heavy diagrams (dependency/call graphs, code structure, >~15 nodes), don't hand-place — describe the graph as JSON and run python3 <this-skill-dir>/scripts/autolayout.py graph.json -o <name>.drawio to compute node positions + orthogonal edge routing via Graphviz (see references/autolayout.md; add --tune to auto-pick the more readable direction). For a Python / JS-TS / Go / Rust project, the matching importer (scripts/pyimports.py, jsimports.py, goimports.py, or rustimports.py) extracts the import graph (transitive-reduced; add --group to box modules by sub-package, nested for deep trees) ready for autolayout; for a Python class hierarchy, scripts/pyclasses.py extracts classes + inheritance instead; for Terraform / Kubernetes / docker-compose (scripts/tfimports.py, k8simports.py, composeimports.py), the importer extracts the resource/service reference graph — tf/k8s nodes resolve to their official cloud icons automatically; to draw what is actually running rather than the declared config, pipe terraform show -json into scripts/tfstate.py or docker inspect $(docker ps -q) into scripts/dockerimports.py (k8simports.py already accepts live kubectl get ... -o json) — see references/live-infra.md; for an ER diagram from SQL DDL, scripts/sqlerd.py parses CREATE TABLE into table nodes + crow's-foot FK edges; for an API diagram from an OpenAPI / Swagger spec, scripts/openapiimports.py maps operations (coloured by HTTP method) + component schemas into a graph for autolayout. To turn any generated .drawio into a metric heat map — recolour nodes by a CSV/JSON of cost/latency/traffic/errors — run python3 <this-skill-dir>/scripts/heatmap.py <name>.drawio -m metrics.csv (matches on cell id or label; --palette, --size, legend). For a sequence diagram, skip autolayout entirely — describe participants + messages as JSON and run python3 <this-skill-dir>/scripts/seqlayout.py seq.json -o <name>.drawio (deterministic lifeline/activation/arrow geometry; see the script docstring for the JSON schema). For a C4 model, python3 <this-skill-dir>/scripts/c4.py c4.json -o <name>.drawio emits the full multi-page Context→Container→Component set with drill-down links (schema in the script docstring). For complex architecture diagrams with many visible edge labels, give labels labelBackgroundColor=#ffffff;fontSize=11 and use edge geometry x/y offsets plus <mxPoint as="offset" /> to move long labels into nearby whitespace instead of relying on draw.io's default midpoint placement. After generating any .drawio, run python3 <this-skill-dir>/scripts/validate.py <name>.drawio for a fast structural lint (dangling edges, dup ids, overlaps), then generate a viewer URL via python3 <this-skill-dir>/scripts/encode_drawio_url.py <name>.drawio and open it with open_preview to show the diagram to the user. Default output dir is the user's working dir; if the user specified an output path or directory (e.g. ./artifacts/, docs/images/), use that instead — mkdir -p the target dir first.
4. Review loop — collect user feedback, apply targeted XML edits, re-run encode_drawio_url.py to update the preview, repeat until approved

If drawio --version crashes or prints nothing (common in restricted macOS sandbox isolation like codex.app):

• Do not keep retrying CLI invocations inside the sandbox.
• Use Browser fallback (scripts/encode_drawio_url.py) or deliver the .drawio XML only.

Escalation rule:

• If the binary exists on PATH (or known app path exists) but execution fails with abnormal exit, empty output, Electron startup failure, display/session error, or likely sandbox restriction, prefer one escalated retry before falling back.
• If the binary is missing entirely, do not escalate just to search more aggressively; go to install guidance or fallback.

Step 4: Review Loop

After preview opens, collect user feedback and apply targeted XML edits as needed.

Targeted edit rules — for each type of feedback, apply the minimal XML change:

Rules:

• For single-element changes: edit existing XML in place — preserves layout tuning from prior iterations
• For layout-wide changes (e.g., swap LR↔TB, "start over"): regenerate full XML
• After applying edits, re-generate viewer URL and re-open preview with open_preview
• Loop continues until user says approved / done / LGTM
• Safety valve: after 5 iteration rounds, suggest the user open the .drawio file in draw.io desktop for fine-grained adjustments

Style Presets

A style preset is a named JSON file capturing a user's visual preferences (palette, shapes, font, edges). When active, it fully replaces the built-in color/shape conventions in this skill.

Lookup order when SKILL.md's Step 0 resolves a preset name:

1. ~/.drawio-skill/styles/<name>.json — user presets (survive git pull)
2. <this-skill-dir>/styles/built-in/<name>.json — shipped built-ins (default, corporate, handdrawn, colorblind-safe, dark)

Always lowercase the user-provided name before any file operation — the schema enforces lowercase.

For everything else — Learn flow (extracting a preset from a file), management ops (list/default/delete/rename), application rules (color lookup, shape keywords, edges, fonts, extras, interaction with diagram-type presets), and validation — read references/style-presets.md. It's only needed when the user invokes those flows or when an active preset must be applied to the current generation.

Authoring .drawio XML

Before hand-writing any .drawio XML (step 3), read references/xml-authoring.md — file skeleton, shape/edge cell forms, containers, connection-point distribution, color palette, and spacing/grid rules all live there. Skip it only when a bundled generator writes the XML for you (autolayout.py + importers, seqlayout.py).

Two rules worth stating even here: never reuse ids 0/1 (reserved root cells), and every edge mxCell needs a <mxGeometry relative="1" as="geometry" /> child — self-closing edge cells do not render.

Browser fallback (no CLI needed)

python3 <this-skill-dir>/scripts/repair_png.py diagram.drawio.png

The script's `endswith(IEND)` guard makes it a no-op once draw.io fixes the bug upstream — safe to run unconditionally.

**Key flags:**
- `-x` — export mode (required)
- `-f` — format: `png`, `svg`, `pdf`, `jpg`
- `-e` — embed diagram XML in output (PNG, SVG, PDF) — exported file remains editable in draw.io. For final PNG export, keep `-e` and run `scripts/repair_png.py` (see Post-export PNG repair). SVG/PDF unaffected.
- `-s` — scale: `1`, `2`, `3` (2 recommended for final PNG)
- `--width <px>` — target width in pixels (no short form; `-w` does **not** exist and silently breaks the input-file parser). Don't combine `--width` with `-s`.
- `-o` — output file path; accepts any directory (e.g. `./artifacts/diagram.drawio.png`) — `mkdir -p` the target dir first. Use `.drawio.png` double extension when embedding.
- `--layout <preset|json>` — **CLI ≥ v30 only** — ELK auto-layout pass on XML input (`verticalFlow`, `horizontalFlow`, `verticalTree`, `horizontalTree`, `radialTree`, `organic`, or a custom ELK JSON array). Alternative to `autolayout.py` when Graphviz is missing. On ≤ 29 this flag breaks argument parsing — don't emit it.
- `-b` — border width around diagram (default: 0, recommend 10)
- `-t` — transparent background (PNG only)
- `--page-index <n>` — export one page of a multi-page file. **1-based** in current drawio-desktop (verified on 29.7.8: `--page-index 2` exports the second page; older docs claimed 0-based). Default: first page. `--page-range 2..3` also works

### Browser fallback (no CLI needed)

When the draw.io desktop CLI is unavailable, generate a client-side URL:

```bash
python3 <this-skill-dir>/scripts/encode_drawio_url.py input.drawio          # read-only viewer
python3 <this-skill-dir>/scripts/encode_drawio_url.py --edit input.drawio    # opens in the editor

Default prints a https://viewer.diagrams.net/...#R… viewer URL; --edit prints a https://app.diagrams.net/...#create=… URL that opens straight into the editable editor. Either way the diagram XML is encodeURIComponent-encoded, deflate-compressed, and base64'd into the URL fragment — the fragment (after #) is never sent to the server, so nothing is uploaded. The encodeURIComponent step is mandatory: without it, any diagram containing a literal % or non-ASCII (e.g. CJK) label makes the browser throw "URI malformed" and the diagram never opens.

Open the URL with open "$URL" (macOS) / xdg-open "$URL" (Linux). On WSL2 / Windows, cmd.exe drops the #fragment — write a .url shortcut file and open that instead (see references/troubleshooting.md → "WSL2 / Windows specifics").

Fallback chain

When tools are unavailable, degrade gracefully:

| Export fails (Chromium/display issues) | On Linux, retry with xvfb-run -a; if still failing, deliver .drawio XML and suggest manual export | | Export fails on Linux server (headless) | Try in order: (1) xvfb-run -a, (2) append --no-sandbox at the very end if root, (3) add --disable-gpu, (4) export HOME=/tmp, (5) install apt deps (libgtk-3-0 libnotify4 libnss3 libgbm1 libasound2t64 etc.), (6) fall back to tomkludy/drawio-renderer Docker (REST API for headless export) |

Checking if drawio is in PATH

# Prefer the Homebrew / Linux-package binary name (no dot)
if command -v drawio &>/dev/null; then
  DRAWIO="drawio"
# Fall back to the dot-named binary (older installs, manual symlinks)
elif command -v draw.io &>/dev/null; then
  DRAWIO="draw.io"
# macOS .app bundle (binary inside the bundle keeps the dot)
elif [ -f "/Applications/draw.io.app/Contents/MacOS/draw.io" ]; then
  DRAWIO="/Applications/draw.io.app/Contents/MacOS/draw.io"
# WSL2: the CLI is the Windows desktop exe, reached via /mnt/c (note the space)
elif grep -qi microsoft /proc/version 2>/dev/null && [ -f "/mnt/c/Program Files/draw.io/draw.io.exe" ]; then
  DRAWIO="/mnt/c/Program Files/draw.io/draw.io.exe"
else
  echo "drawio not found — install from https://github.com/jgraph/drawio-desktop/releases (Homebrew: brew install --cask drawio)"
fi

On WSL2 / native Windows, opening exported files and browser-fallback URLs needs path conversion + a .url-file workaround (cmd.exe drops URL #fragments) — see the "WSL2 / Windows specifics" section in references/troubleshooting.md.

Common Mistakes

When something looks wrong (export fails, vision rejects a PNG, layout broken, edges misroute), see references/troubleshooting.md for a row-by-row mistake → fix table.

Diagram Type Presets

When the user requests a specific diagram type, read references/diagram-types.md for the matching preset (shapes, edges, layout direction). Pick by user phrasing:

The diagram-type preset sets structural style keywords. If a user style preset is also active (see ## Style Presets), keep the structural keywords and layer color/font/edge/extras on top — read references/style-presets.md → "Interaction with diagram-type presets" for the merge rules.