Drawio Skill

Draw.io Diagrams

Overview

Generate .drawio XML files and export to PNG/SVG/PDF/JPG locally using the native draw.io desktop app CLI.

Supported formats: PNG, SVG, PDF, JPG — no browser automation needed.

PNG, SVG, and PDF exports support --embed-diagram (-e) — the exported file contains the full diagram XML, so opening it in draw.io recovers the editable diagram. Use double extensions (name.drawio.png) to signal embedded XML.

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, exported as editable PNG/SVG/PDF.

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 format — PNG (default), SVG, PDF, or JPG?
• 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 the Applying a preset subsection below 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 export 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). 2. Plan — identify shapes, relationships, layout (LR or TB), group by tier/layer 3. Generate — write .drawio XML file to disk. Hand-place coordinates for small/styled diagrams. 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). 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. After generating any .drawio, run python3 <this-skill-dir>/scripts/validate.py <name>.drawio for a fast structural lint (dangling edges, dup ids, overlaps) before exporting. 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. Apply the same dir choice to PNG/SVG/PDF exports in steps 4 and 7. 4. Export draft — run CLI to produce a preview PNG. Do NOT pass `-e` at this step — the embedded zTXt mxGraphModel chunk it adds causes vision APIs (Claude included) to return 400 "Could not process image" in step 5. Cap the preview width with `--width 2000` (not `-s 2`) — Claude's vision API rejects images larger than 2576×2576px with "Unable to resize image — dimensions exceed the 2576x2576px limit", and -s 2 on a medium-or-larger diagram easily overshoots that ceiling. Save the clean preview as <name>.png (single extension). Embedding and full-resolution scale are for the final export only (step 7). 5. Self-check — use the agent's built-in vision capability to read the exported PNG, catch obvious issues, auto-fix before showing user (requires a vision-enabled model such as Claude Sonnet/Opus). If reading the PNG returns a 400 / "Could not process image" error, you almost certainly exported with -e by mistake — re-export without -e and retry once. If it still fails, skip self-check and continue to step 6. 6. Review loop — show image to user, collect feedback, apply targeted XML edits, re-export, repeat until approved 7. Final export — re-export the approved version to all requested formats. Use -e here (PNG/SVG/PDF) so the deliverable stays editable in draw.io; save as <name>.drawio.png to signal embedded XML. For PNG with `-e`, run `python3 <this-skill-dir>/scripts/repair_png.py <name>.drawio.png` immediately after — draw.io's CLI truncates the IEND chunk in -e PNG output (8 bytes missing), producing a corrupt file that vision APIs and strict PNG decoders reject (issue #8). Report file paths.

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.
• Skip steps 4, 5, 6, and 7 (CLI export + PNG-based review) and use Browser fallback (scripts/encode_drawio_url.py) or deliver the .drawio XML only.
• If the user needs PNG/SVG/PDF outputs, ask them to run the export commands in a non-sandboxed host environment (outside sandbox isolation) and share the resulting files.

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 5: Self-Check

After exporting the draft PNG, use the agent's vision capability (e.g., Claude's image input) to read the image and check for these issues before showing the user. If the agent does not support vision, skip self-check and show the PNG directly.

Important: the draft PNG read here must have been exported without -e. Draw.io's -e flag emits a PNG with a truncated IEND chunk (8 bytes of type+CRC missing) that the Anthropic vision API rejects with 400 "Could not process image" (issue #8). The simplest fix for the preview step is to skip -e entirely; the final export in step 7 keeps -e and runs the repair snippet. If you see the 400 error here, re-export without -e and retry once; if it still fails (any other reason), skip self-check and proceed to step 6.

• Max 2 self-check rounds — if issues remain after 2 fixes, show the user anyway
• Re-export after each fix and re-read the new PNG

Step 6: Review Loop

After self-check, show the exported image and ask the user for feedback.

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
• Overwrite the same {name}.png (no -e) each iteration — do not create v1, v2, v3 files. -e is reserved for the final export in step 7.
• After applying edits, re-export and show the updated image
• 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

Step 7: Final Export

Once the user approves:

• Export to all requested formats (PNG, SVG, PDF, JPG) — default to PNG if not specified
• Report file paths for both the .drawio source file and exported image(s)
• Auto-launch: offer to open the .drawio file in draw.io desktop for fine-tuning — open diagram.drawio (macOS), xdg-open (Linux), start (Windows)
• Confirm files are saved and ready to use

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)

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.

Draw.io XML Structure

File skeleton

<?xml version="1.0" encoding="UTF-8"?>
<mxfile host="drawio" version="26.0.0">
  <diagram name="Page-1">
    <mxGraphModel>
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <!-- user shapes start at id="2" -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

Rules:

• id="0" and id="1" are required root cells — never omit them
• User shapes start at id="2" and increment sequentially
• All shapes have parent="1" (unless inside a container — then use container's id)
• All text uses html=1 in style for proper rendering
• Never use `--` inside XML comments — it's illegal per XML spec and causes parse errors
• Escape special characters in attribute values: &, <, >, "
• Multi-line text in labels: use 
 for line breaks inside value attributes (not literal \n). Example: value="Line 1
Line 2"

Shape types (vertex)

For vendor/branded icons (AWS/Azure/GCP/Cisco/Kubernetes) and any non-trivial shape, don't guess the shape=mxgraph.* name — a wrong name renders as a blank box. Run python3 <this-skill-dir>/scripts/shapesearch.py "<keywords>" to get the exact official style + size, or see references/shapes.md for the hand-writable cheatsheet. For AI/LLM brand logos (OpenAI, Claude, Gemini, …), which draw.io has none of, use python3 <this-skill-dir>/scripts/aiicons.py "<brand>".

Required properties

<!-- Rectangle / rounded box -->
<mxCell id="2" value="Label" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="160" height="60" as="geometry" />
</mxCell>

<!-- Cylinder (database) -->
<mxCell id="3" value="DB" style="shape=cylinder3;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;" vertex="1" parent="1">
  <mxGeometry x="350" y="100" width="120" height="80" as="geometry" />
</mxCell>

<!-- Diamond (decision) -->
<mxCell id="4" value="Check?" style="rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;" vertex="1" parent="1">
  <mxGeometry x="100" y="220" width="160" height="80" as="geometry" />
</mxCell>

Containers and groups

For architecture diagrams with nested elements, use draw.io's parent-child containment — do not just place shapes on top of larger shapes.

Key rules:

• Add pointerEvents=0; to container styles that should not capture connections between children
• Children set parent="containerId" and use coordinates relative to the container

<!-- Swimlane container -->
<mxCell id="svc1" value="User Service" style="swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="300" height="200" as="geometry"/>
</mxCell>
<!-- Child inside container — coordinates relative to parent -->
<mxCell id="api1" value="REST API" style="rounded=1;whiteSpace=wrap;html=1;" vertex="1" parent="svc1">
  <mxGeometry x="20" y="40" width="120" height="60" as="geometry"/>
</mxCell>
<mxCell id="db1" value="Database" style="shape=cylinder3;whiteSpace=wrap;html=1;" vertex="1" parent="svc1">
  <mxGeometry x="160" y="40" width="120" height="60" as="geometry"/>
</mxCell>

Connector (edge)

CRITICAL: Every edge mxCell must contain a <mxGeometry relative="1" as="geometry" /> child element. Self-closing edge cells (<mxCell ... edge="1" ... />) are invalid and will not render. Always use the expanded form.

<!-- Directed arrow — always include rounded, orthogonalLoop, jettySize for clean routing -->
<mxCell id="10" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="2" target="3">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

<!-- Arrow with label + explicit entry/exit points to control direction -->
<mxCell id="11" value="HTTP/REST" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;" edge="1" parent="1" source="2" target="4">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

<!-- Arrow with waypoints — use when edge must route around other shapes -->
<mxCell id="12" value="" style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;" edge="1" parent="1" source="3" target="5">
  <mxGeometry relative="1" as="geometry">
    <Array as="points">
      <mxPoint x="500" y="50" />
    </Array>
  </mxGeometry>
</mxCell>

Edge style rules:

• Animated connectors: add flowAnimation=1; to any edge style to show a moving dot animation along the arrow. Works in SVG export and draw.io desktop — ideal for data-flow and pipeline diagrams. Example: style="edgeStyle=orthogonalEdgeStyle;flowAnimation=1;rounded=1;..."
• Always include rounded=1;orthogonalLoop=1;jettySize=auto — these enable smart routing that avoids overlaps
• Pin exitX/exitY/entryX/entryY on every edge when a node has 2+ connections — distributes lines across the shape perimeter
• Add <Array as="points"> waypoints when an edge must detour around an intermediate shape
• Leave room for arrowheads: the final straight segment between the last bend and the target shape must be ≥20px long. If too short, the arrowhead overlaps the bend and looks broken. Fix by increasing node spacing or adding explicit waypoints

Distributing connections on a shape

When multiple edges connect to the same shape, assign different entry/exit points to prevent stacking:

Rule: if a shape has N connections on one side, space them evenly (e.g., 3 connections on bottom → exitX = 0.25, 0.5, 0.75)

Color palette (fillColor / strokeColor)

Used only when no preset is active (see "Applying a preset" above).

Layout tips

Spacing — scale with complexity:

Routing corridors: between shape rows/columns, leave an extra ~80px empty corridor where edges can route without crossing shapes. Never place a shape in a gap that edges need to traverse.

Grid alignment: snap all x, y, width, height values to multiples of 10 — this ensures shapes align cleanly on draw.io's default grid and makes manual editing easier.

General rules:

• Plan a grid before assigning x/y coordinates — sketch node positions on paper/mentally first
• Group related nodes in the same horizontal or vertical band
• Use swimlane cells for logical grouping with visible borders
• Place heavily-connected "hub" nodes centrally so edges radiate outward instead of crossing
• To force straight vertical connections, pin entry/exit points explicitly on edges:

exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0

• Always center-align a child node under its parent (same center x) to avoid diagonal routing
• Event bus pattern: place Kafka/bus nodes in the center of the service row, not below — services on either side can reach it with short horizontal arrows (exitX=1 left side, exitX=0 right side), eliminating all line crossings
• Horizontal connections (exitX=1 or exitX=0) never cross vertical nodes in the same row; use them for peer-to-peer and publish connections

Avoiding edge-shape overlap:

• Before finalizing coordinates, trace each edge path mentally — if it must cross an unrelated shape, either move the shape or add waypoints
• For tree/hierarchical layouts: assign nodes to layers (rows), connect only between adjacent layers to minimize crossings
• For star/hub layouts: place the hub center, satellites around it — edges stay short and radial
• When an edge must span multiple rows/columns, route it along the outer corridor, not through the middle of the diagram

Export

Commands

There are two export modes:

• Preview / self-check (step 4 of the workflow) — no -e. Output diagram.png. Required for vision self-check; using -e here triggers a 400 "Could not process image" error from the vision API (issue #8).
• Final / deliverable (step 7) — pass -e. Output diagram.drawio.png. The embedded XML keeps the file editable in draw.io.

All commands below write drawio as a placeholder for the binary you resolved in Step 1. If your binary is on PATH as draw.io (with dot — some older or distro-packaged installs), substitute draw.io throughout. If only the macOS .app or Windows .exe is available, use the full path variant shown a few lines down.

# Preview PNG (use this in step 4, before self-check) — NO -e, width-capped to stay under vision's 2576px ceiling
drawio -x -f png --width 2000 -o diagram.png input.drawio

# Final PNG (step 7, after user approval) — WITH -e, double extension
drawio -x -f png -e -s 2 -o diagram.drawio.png input.drawio

# macOS — full path (if not in PATH); preview / final variants
/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png --width 2000 -o diagram.png input.drawio
/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png -e -s 2 -o diagram.drawio.png input.drawio

# Windows
"C:\Program Files\draw.io\draw.io.exe" -x -f png -e -s 2 -o diagram.drawio.png input.drawio

# Linux (headless — requires xvfb-run; on servers add HOME and --disable-gpu)
export HOME=${HOME:-/tmp}
xvfb-run -a --server-args="-screen 0 1280x1024x24" \
  drawio -x -f png -e -s 2 -o diagram.drawio.png input.drawio --disable-gpu
# Running as root (CI / Docker)? Append --no-sandbox AT THE END (placing it earlier makes drawio treat it as the input filename)

# SVG export (final — -e is safe; SVG is text)
drawio -x -f svg -e -o diagram.svg input.drawio

# PDF export (final)
drawio -x -f pdf -e -o diagram.pdf input.drawio

# Custom output directory (e.g. CI artifacts dir) — create if missing, then export there
mkdir -p ./artifacts && drawio -x -f png -e -s 2 -o ./artifacts/diagram.drawio.png input.drawio

Post-export PNG repair (required after -e PNG export)

draw.io CLI truncates the IEND chunk when emitting -e PNGs — the file ends with the 4-byte IEND length field but the IEND type + CRC (8 bytes) are missing. Result: vision APIs return 400 "Could not process image" and strict PNG decoders error out. SVG/PDF are unaffected.

Run this immediately after every -e PNG export:

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. Skip for the preview PNG used in step 5 self-check — -e PNGs have a truncated IEND chunk that vision APIs reject (issue #8). 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; do NOT use for the step-4 preview — see --width)
• --width <px> — target width in pixels (no short form; -w does not exist and silently breaks the input-file parser). Use --width 2000 for the step-4 preview to keep the PNG under Claude's 2576×2576 vision ceiling. There's also a --height <px> flag for tall-narrow diagrams. 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.
• -b — border width around diagram (default: 0, recommend 10)
• -t — transparent background (PNG only)
• --page-index 0 — export specific page (default: all)

Browser fallback (no CLI needed)

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

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:

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.

Shape index attribution

shape-index.json.gz is a gzipped copy of the shape search index from jgraph/drawio-mcp (shape-search/search-index.json), which is generated from the official draw.io / diagrams.net client shape libraries. Both upstream sources are licensed under the Apache License 2.0.

• Each entry is {style, w, h, title, tags, type} for one palette shape.
• 10,446 shapes spanning AWS, Azure, GCP, Cisco, Kubernetes, UML, BPMN, P&ID,

electrical, flowchart, network, and the general shape sets.

• Used read-only by scripts/shapesearch.py to resolve exact official style

strings instead of hand-guessing them.

To refresh against a newer draw.io release, regenerate upstream with shape-search/generate-index.js in the drawio-mcp repo, then re-gzip:

gzip -9 -c search-index.json > data/shape-index.json.gz

Auto-layout (Graphviz)

Read this when a diagram is large or layout-heavy — dependency/call graphs, code/module structure, or roughly more than ~15 nodes — where hand-placing x/y coordinates is slow, error-prone, and overlap-prone.

Instead of computing coordinates by hand in the Generate step, describe the graph as JSON and let scripts/autolayout.py place the nodes and route the edges with Graphviz, then continue the normal workflow (Export draft → Self-check → …) on the produced .drawio.

For small or carefully-styled diagrams, keep hand-placing — auto-layout trades fine control for scale.

Dependency

Requires Graphviz dot on PATH:

# macOS
brew install graphviz
# Debian/Ubuntu
sudo apt install graphviz

The script exits with a clear message if dot is missing — fall back to hand-placed coordinates in that case.

Usage

python3 <this-skill-dir>/scripts/autolayout.py graph.json -o diagram.drawio

It prints wrote diagram.drawio (N nodes, M edges) to stderr and writes a normal .drawio file. From there, continue at the Export draft step of the main workflow (preview PNG with --width 2000, self-check, review loop, final export with -e + repair_png.py).

Input format

{
  "direction": "TB",
  "nodes": [
    {"id": "client", "label": "Web Client", "style": "rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;"},
    {"id": "gw", "label": "API Gateway", "group": "edge", "groupLabel": "Edge tier"},
    {"id": "db", "label": "User DB", "style": "shape=cylinder3;whiteSpace=wrap;html=1;", "width": 120, "height": 80, "group": "data"}
  ],
  "edges": [
    {"source": "client", "target": "gw", "label": "HTTPS"},
    {"source": "gw", "target": "db"}
  ]
}

Fields

How it places things

• Node positions come from dot (hierarchical layered layout), converted to draw.io pixels and snapped to the grid (multiples of 10).
• Edges use splines=ortho: dot's orthogonal route is replayed as draw.io waypoints, so edges go around nodes instead of through them.
• Apply the active style preset by setting each node's style to the preset's role/shape values before calling the script — the script does not know about presets.

Containers / grouping

Give nodes a group key and the script wraps each group in a labeled container (a dashed box with the group title at top) and tells dot to keep that group's nodes together via a Graphviz cluster. Grouped nodes become children of their container (parent="<container>", relative coordinates); ungrouped nodes stay at the top level. This turns a flat hairball into a "boxes of related modules" architecture view.

Nesting. A group value with / separators builds nested containers: "core/db" puts the node inside a db box that itself sits inside a core box. Every path prefix becomes a container, so an arbitrarily deep package tree maps to nested boxes. A node can also sit directly in a parent box (group: "core") alongside a sibling sub-box (group: "core/db").

• Colour by group. Each top-level group is assigned a colour from the skill's own palette (styles/built-in/default.json, cycled in role order: blue → green → orange → purple → yellow → red → grey). A node with no style of its own is tinted with its group's colour, and the container's border + title match — so related modules read as a coloured cluster instead of monochrome boxes. A node that carries its own style (e.g. from an applied preset) is left untouched. Pass --mono to turn colouring off (dashed grey boxes, default-blue nodes — the previous look). Ungrouped graphs are unaffected.
• Each container box is the bounding box of its members and child boxes plus a uniform padding. The dot cluster margin is set to that same padding, so each box equals dot's cluster box — which dot keeps non-overlapping at any nesting depth.
• The title sits in the top padding (verticalAlign=top); the box title is the path's last segment, or a member's groupLabel.
• Containers are visual only (no edges of their own). Edges still connect node→node and route across containers normally.
• If a container's top padding would cross the page origin, the whole diagram is shifted so nothing lands at a negative coordinate.

Validate before previewing

scripts/validate.py is a deterministic structural linter — run it on the produced .drawio before the (slower, vision-based) self-check:

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

It catches dangling edge endpoints, duplicate/reserved ids, broken parent references (errors), plus off-grid/negative geometry and overlapping sibling nodes (warnings) — without launching draw.io. Exit status is non-zero on any error (or any warning with --strict), so it can gate the workflow. Auto-layout output should always pass clean; a failure means a malformed input graph (e.g. an edge referencing a missing node id).

Importers — visualize code structure

Bundled importers turn a codebase into a graph JSON ready for autolayout, so "visualize this project" is a two-step pipeline:

python3 <this-skill-dir>/scripts/pyimports.py myproject -o graph.json
python3 <this-skill-dir>/scripts/autolayout.py graph.json -o diagram.drawio

Each keeps only intra-project edges (third-party/stdlib imports are ignored), shortens node labels (drops the shared package/module/directory prefix; ids stay fully qualified), and shares the same flags: --direction TB|LR (default TB), --group, --no-reduce.

• Python (pyimports.py): if the directory is itself a package (__init__.py present), module names are package-qualified so the project's own absolute imports resolve; nested subpackages (pkg.sub.mod) are handled.
• JS/TS (jsimports.py): resolution is path-based (tries the source extensions and directory index files); node_modules and bare specifiers are skipped. Scanning is regex-based, not a full parser.
• Go (goimports.py): reads the module path from go.mod; each directory of .go files is one package; *_test.go and vendor/ are skipped.
• Rust (rustimports.py): each .rs file is a module (mod.rs/main.rs/lib.rs name the enclosing module); edges come from use paths rooted at crate::/super::/self:: (brace groups expanded). std/external crates and target/ are skipped. Regex-based — inline mod { … } blocks aren't split out, and 2015-edition bare intra-crate paths aren't resolved.
• Python classes (pyclasses.py): a finer granularity — one node per class, edges from each subclass to the project base classes it extends, so the result is an auto-generated class hierarchy. Bases are matched by name (preferring the same module); external bases (object, third-party) are ignored. With --group, classes are boxed by their module, so a deep package tree nests naturally. Inheritance only — function-level call graphs are out of scope (static call resolution in Python is unreliable).

Density reduction is on by default — this is the key to a readable result. Real import graphs are dense (asyncio: 33 modules / ~149 edges); without reduction they render as a hairball. Every importer applies transitive reduction (Graphviz tred — drops edges already implied by a longer path), which on asyncio cuts ~149 edges to ~46 and turns the hairball into a clean, traceable diagram. Pass --no-reduce to keep every edge.

`--group` assigns each node a container by its sub-package / directory path, so autolayout boxes related modules together — nested when the path has depth (see Containers / grouping). The fastest way to turn a large code graph into a tiered architecture view.

For any other language, produce the same graph JSON from any analyzer (e.g. dependency-cruiser for richer JS/TS resolution, go-callvis for Go call graphs) and feed it to autolayout the same way.

Limitations

• Placement is topological, not semantic — dot minimises edge crossings, which may put a node in a different column than you'd choose by hand. Re-export with the other direction, or hand-tune the produced XML afterwards (it's a normal .drawio).
• Import edges are static — pyimports/jsimports/goimports read static import statements (not dynamic importlib, runtime require, or reflection); pyclasses resolves inheritance only, not method-level calls.
• Parallel edges between the same (source, target) pair share one route.
• Containers don't add edges — group/nesting only boxes nodes for layout; edges remain node→node. For hand-built swimlane/architecture containers with their own connections, see SKILL.md "Containers and groups".

Diagram Type Presets

When the user requests a specific diagram type, apply the matching preset below for shapes, styles, and layout conventions. These presets set structural style keywords (e.g. ERD's shape=table;childLayout=tableLayout); a user style preset (see references/style-presets.md) layers color/font/edge/extras on top.

Read this file when:

• The user names one of these diagram types (ERD, UML class, sequence, architecture, ML/DL model, flowchart)
• You're choosing shape vocabulary or layout direction for a new diagram

ERD (Entity-Relationship Diagram)

UML Class Diagram

Sequence Diagram

Architecture Diagram

ML / Deep Learning Model Diagram

For neural network architecture diagrams — ideal for papers targeting NeurIPS, ICML, ICLR.

Tensor shape convention: annotate each layer with input/output tensor dimensions in (B, C, H, W) or (B, T, D) format. Place dimensions as the second line of the label using 
.

Flowchart (enhanced)

Shape vocabulary & search

Read this when a diagram needs a specific shape — a cloud-provider icon (AWS/Azure/GCP), a network/Cisco/Kubernetes symbol, a UML/BPMN/ER element, an electrical or P&ID part — or any time you'd otherwise guess a style= string.

There are two ways to get a style:

1. Search the official shape index (scripts/shapesearch.py) — 10,446 real draw.io palette shapes with their exact style, w, h. Use this for branded/vendor icons and anything non-trivial. *Always prefer a searched style over a hand-written `shape=mxgraph.` guess — guessed stencil names silently render as a blank box if the name is wrong. 2. The cheatsheet below** — the common built-in shapes whose style strings are short and stable enough to write by hand (rectangles, flowchart symbols, UML primitives, containers, edges).

Searching shapes

python3 <this-skill-dir>/scripts/shapesearch.py "aws lambda" --limit 5
python3 <this-skill-dir>/scripts/shapesearch.py "uml actor" --json

• Query is space-separated keywords; matching is tag-based with Soundex

fuzziness and camelCase/digit splitting ("pid2valve" → pid valve).

• Prints each match as Title (WxH) followed by its full style= string. With

--json, emits [{style,w,h,title}] for programmatic use.

• Copy the style verbatim into an mxCell, and use the reported w/h as the

mxGeometry width/height (vendor icons are drawn at a fixed aspect ratio).

• Results are ranked by tag relevance, with shapes whose title contains the

query terms bubbled to the top of each score tier. Ranking is still a heuristic, though, and many shapes share a title (three Lambda variants: aws3/aws4/aws3d) — so run with --limit 5 and pick the row whose title and size match what you actually want rather than blindly taking #1.

<mxCell id="2" value="Lambda" style="<paste the searched style here>" vertex="1" parent="1">
  <mxGeometry x="40" y="40" width="78" height="78" as="geometry"/>
</mxCell>

Covered libraries: AWS (aws3/aws4), Azure, GCP, Cisco, Kubernetes, UML, BPMN, ER, electrical, P&ID, mockup/wireframe, flowchart, network, and the general/basic sets. The bundled index (data/shape-index.json.gz) is the upstream draw.io shape data — see data/SHAPE-INDEX-NOTICE.md for attribution.

AI / LLM brand logos

draw.io's bundled libraries have no modern AI/LLM brand logos, so an "LLM app architecture" otherwise renders as generic boxes. scripts/aiicons.py resolves a brand name (OpenAI, Claude, Gemini, Mistral, Llama, HuggingFace, Ollama, LangChain, …321 brands) to a draw.io image style backed by the lobe-icons set (MIT).

python3 <this-skill-dir>/scripts/aiicons.py "claude" --json        # CDN reference
python3 <this-skill-dir>/scripts/aiicons.py "openai" --embed        # self-contained
python3 <this-skill-dir>/scripts/aiicons.py --list                  # all brands

• Picks the -color variant when it exists, else the mono logo (e.g. OpenAI is

mono-only). Returns a square image style; use the reported --size (default 48) for both width and height.

• Default references the icon by CDN URL — the SVG lives on unpkg, not in

this repo, so draw.io needs network access when the diagram is rendered or opened; an offline export draws a blank box. Pass --embed to fetch the SVG once and inline it as a data URI (portable, renders offline, larger XML).

• Logos are trademarks of their respective owners, referenced for identification

only — the same basis on which draw.io ships AWS/Azure icons.

• Data stores common in RAG/LLM apps that lobe lacks (Qdrant, Redis,

Postgres, Mongo, Elasticsearch, Milvus, Supabase, Neo4j, ClickHouse, Kafka, Snowflake, Databricks, …) resolve via the simple-icons CDN (CC0) as an automatic fallback — same command, same output shape. A brand in neither set has no logo; use a cylinder (shape=cylinder3;, see below) or scripts/shapesearch.py "<name> database".

Cheatsheet — hand-writable styles

These are stable enough to write without searching. Combine with whiteSpace=wrap;html=1;.

Common shapes (shape= keyword)

UML primitives

Containers (parent-child; children use relative coords)

Edges

Useful property knobs

• fontStyle is a bitmask: 1=bold, 2=italic, 4=underline (add to combine: 3=bold+italic).
• direction=north|south|east|west rotates a shape in 90° steps; rotation=<deg> for free rotation.
• gradientColor=#RRGGBB; + gradientDirection=north; for a gradient fill.
• sketch=1; gives a hand-drawn look (set globally via a style preset instead when possible).

For richer per-shape detail, the upstream source is jgraph/drawio-mcp's shared/style-reference.md (Apache-2.0).

Style Extraction — agent reference

Loaded on demand by SKILL.md when the user asks to learn a style ("learn my style from <path> as <name>") or when the agent needs to render a sample after extraction.

Sample diagram (for approval render)

After extracting a candidate preset, render this seven-node sample using the candidate's palette/shapes/fonts/edges. Each role appears exactly once; six edges, one dashed, exercise edges.arrow, edges.style, and edges.dashedFor.

Layout (TB):

• Row 1 (y=40): gateway centered at x=340
• Row 2 (y=180): security (x=80), service (x=340), queue (x=600)
• Row 3 (y=340): database (x=80), external (x=340), error (x=600)

Template — substitute `{{...}}` placeholders from the candidate preset.

The vertex style for role R is built as: <shapes[R]>;whiteSpace=wrap;html=1;fillColor=<palette[roles[R]].fillColor>;strokeColor=<palette[roles[R]].strokeColor>;fontFamily=<font.fontFamily>;fontSize=<font.fontSize>

• If extras.sketch=true, append ;sketch=1 to every vertex style AND every edge style.
• If extras.globalStrokeWidth !== 1 (i.e., any value other than the drawio default of 1, including 0.5), append ;strokeWidth=<n> to every vertex style AND every edge style.

The edge style is built as: <edges.style>;<edges.arrow>

• Per-edge routing keys (exitX/entryX/...) are added as literals below.
• Edge 15 exercises edges.dashedFor:
• If edges.dashedFor is non-empty, use its first entry as the edge's value (label) AND append ;dashed=1 to the edge style.
• If edges.dashedFor is empty ([]), use the label cross-call and do NOT append ;dashed=1 — the preset has no dashed convention, so the sample must not fake one.

Placeholder expansion (applied when filling the XML):

• {{VSTYLE:<role>}} expands to the vertex-style formula above with R = <role>. Write the result as a literal string; do not URL-encode.
• {{ESTYLE}} expands to the edge-style formula above.
• {{EDGE15_LABEL}} and {{EDGE15_DASH}} follow the Edge-15 rule above.

<?xml version="1.0" encoding="UTF-8"?>
<mxfile host="drawio" version="26.0.0">
  <diagram name="Preset Sample">
    <mxGraphModel>
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />

        <!-- Row 1: gateway -->
        <mxCell id="2" value="Gateway" style="{{VSTYLE:gateway}}" vertex="1" parent="1">
          <mxGeometry x="340" y="40" width="160" height="60" as="geometry" />
        </mxCell>

        <!-- Row 2: security | service | queue -->
        <mxCell id="3" value="Auth" style="{{VSTYLE:security}}" vertex="1" parent="1">
          <mxGeometry x="80" y="180" width="160" height="60" as="geometry" />
        </mxCell>
        <mxCell id="4" value="Service" style="{{VSTYLE:service}}" vertex="1" parent="1">
          <mxGeometry x="340" y="180" width="160" height="60" as="geometry" />
        </mxCell>
        <mxCell id="5" value="Queue" style="{{VSTYLE:queue}}" vertex="1" parent="1">
          <mxGeometry x="600" y="180" width="160" height="60" as="geometry" />
        </mxCell>

        <!-- Row 3: database | external | error -->
        <mxCell id="6" value="Database" style="{{VSTYLE:database}}" vertex="1" parent="1">
          <mxGeometry x="80" y="340" width="160" height="70" as="geometry" />
        </mxCell>
        <mxCell id="7" value="External API" style="{{VSTYLE:external}}" vertex="1" parent="1">
          <mxGeometry x="340" y="340" width="160" height="60" as="geometry" />
        </mxCell>
        <mxCell id="8" value="Error Sink" style="{{VSTYLE:error}}" vertex="1" parent="1">
          <mxGeometry x="600" y="340" width="160" height="60" as="geometry" />
        </mxCell>

        <!-- Edges -->
        <mxCell id="10" value="" style="{{ESTYLE}};exitX=0.25;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0" edge="1" parent="1" source="2" target="3">
          <mxGeometry relative="1" as="geometry" />
        </mxCell>
        <mxCell id="11" value="" style="{{ESTYLE}};exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0" edge="1" parent="1" source="2" target="4">
          <mxGeometry relative="1" as="geometry" />
        </mxCell>
        <mxCell id="12" value="" style="{{ESTYLE}};exitX=0.75;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0" edge="1" parent="1" source="2" target="5">
          <mxGeometry relative="1" as="geometry" />
        </mxCell>
        <mxCell id="13" value="" style="{{ESTYLE}};exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0" edge="1" parent="1" source="4" target="7">
          <mxGeometry relative="1" as="geometry" />
        </mxCell>
        <mxCell id="14" value="" style="{{ESTYLE}};exitX=0;exitY=0.5;exitDx=0;exitDy=0;entryX=1;entryY=0.5;entryDx=0;entryDy=0" edge="1" parent="1" source="4" target="6">
          <mxGeometry relative="1" as="geometry" />
        </mxCell>
        <mxCell id="15" value="{{EDGE15_LABEL}}" style="{{ESTYLE}}{{EDGE15_DASH}};exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0" edge="1" parent="1" source="4" target="8">
          <mxGeometry relative="1" as="geometry" />
        </mxCell>

      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

Rendering the sample

1. Write the filled XML to /tmp/drawio-preset-<name>.drawio. 2. Run the same drawio -x -f png -e -s 2 -o <preset-name>-sample.png <tmp>.drawio command the main workflow uses (substitute the binary name you resolved in SKILL.md Step 1 if it isn't drawio). 3. Repair the IEND chunk: python3 <this-skill-dir>/scripts/repair_png.py <preset-name>-sample.png — the -e flag truncates the PNG the same way the main workflow's step 7 does, so the sample needs the same fix to be readable. 4. Save the PNG as ./preset-<name>-sample.png (the user's working directory). 5. Show the user: preset summary table + PNG path + provenance/confidence line.

Approval loop

• "save" / "looks good" → write candidate to ~/.drawio-skill/styles/<name>.json; delete tempfile and sample PNG.
• "change <field> to <value>" → edit the in-memory candidate; re-render; re-ask.
• "cancel" → delete tempfile and sample PNG; no save.

If sample render fails (draw.io CLI missing / export error)

Still show the summary table and the provenance line. Note: "Could not render sample PNG (CLI unavailable). Save anyway on your OK." Do not block.

XML extraction path

Input: a .drawio file path. Output: candidate preset JSON. Deterministic, no LLM inference.

Steps

1. Parse the file. Read the XML, collect every <mxCell> with a style= attribute, split into vertices (vertex="1") and edges (edge="1"). 2. Tokenize each `style=` string on ;. Each element is either key=value or a bare keyword (e.g., rhombus, ellipse, rounded=1). 3. Extract palette. For every vertex, take the (fillColor, strokeColor) pair (skip vertices with neither). Count frequency. Keep the top ≤7 pairs. 4. Extract shape vocabulary + role mapping. For each vertex determine a shape class by precedence: cylinder3 > ellipse > rhombus > swimlane > rounded=1 > rounded=0. Then infer the semantic role from the vertex's shape class and its value (label) attribute. Evaluate the rules below in order; first match wins.

• cylinder3 → database
• rhombus → decision
• swimlane → container
• dashed=1 present + grey-family fill (hex where the R, G, and B channels all fall within ±16 of each other, i.e., near-achromatic) → external
• label matches /queue|bus|kafka|rabbit/i → queue
• label matches /gateway|api|lb|load/i → gateway
• label matches /auth|login|jwt|oauth/i → security
• label matches /error|fail|alert/i → error
• everything else → service

For each role that has a canonical palette slot — service, database, queue, gateway, error, external, security — the most frequent (role, color-pair) mapping wins. The pair goes into the role's canonical palette slot: service→primary, database→success, queue→warning, gateway→accent, error→danger, external→neutral, security→secondary. Set roles[role] to that slot name.

Decision and container shapes do not get a `roles[...]` entry — they are recorded only in shapes.decision and shapes.container. Any color pairs observed on decision/container vertices still participate in the palette (they can fill leftover slots) but are not tied to a semantic role.

Leftover color pairs (not claimed by any role-slot mapping) fill remaining empty palette slots in descending-frequency order.

Record the shape class string used per role in shapes[role]. The six named shape keys are service, database, queue, decision, external, container — gateway, error, and security roles inherit shapes.service and do not get their own shapes[...] entry. Example: shapes.database = "shape=cylinder3".

5. Extract fonts. Compute modal fontFamily and fontSize across vertices; emit them as font.fontFamily and font.fontSize. Also track fontStyle per vertex as a working variable (not an output field — the schema has no top-level font.fontStyle). If a distinguishable subset of vertices uses a larger fontSize combined with fontStyle=1 (bold), treat that subset as titles: set font.titleFontSize to their modal size and font.titleBold: true. Otherwise omit both title fields.

6. Extract edge defaults. Take the modal edge style string, but strip these per-edge coordinate keys before counting: entryX, entryY, exitX, exitY, entryDx, entryDy, exitDx, exitDy. Record arrow style from endArrow/endFill separately in edges.arrow. If any edges have dashed=1, collect their value (label) attributes. If ≥2 share a common token (e.g., all are labeled "async" or "optional"), add that token to edges.dashedFor.

7. Extract extras. sketch=1 seen on any vertex or edge → extras.sketch = true. Modal strokeWidth across vertices → extras.globalStrokeWidth (default 1).

8. Set provenance.

   {
     "source": { "type": "xml", "path": "<input absolute path>", "extracted_at": "YYYY-MM-DD" },
     "confidence": "high"
   }

XML edge cases

Image extraction path

Input: path to a PNG/JPG (or any vision-readable image format). Output: candidate preset JSON. Inference-based; confidence: "medium" at best.

Prerequisite: the agent's vision capability must be available (same mechanism the main workflow's self-check uses). If vision is not available, stop and tell the user: "Image-based learning needs a vision-enabled model (Claude Sonnet or Opus). Re-run on such a model, or provide the `.drawio` source file instead."

Steps

1. Read the image. Use the agent's vision input — the same path the main workflow's step 5 uses to read exported PNGs during self-check.

2. Extract palette by visual inspection. Identify distinct fill-color regions on shape bodies.

For each distinct fill:

• fillColor — quantize each RGB channel to the nearest multiple of 16. If the resulting HSL lightness is below 0.75, raise it to 0.85 (keep hue and saturation; set L=0.85; HSL→RGB round-trip). Emit as #RRGGBB. Drawio-standard pastels occupy L≈0.85–0.96; below 0.75 reads as "too dark for a fill color" and this step lifts it back into that range.
• strokeColor — read the matching border. If unreadable, derive from fill by darkening ~25% (match HSL, drop L by 0.25).

Map each (fillColor, strokeColor) pair to a named slot using this decision order:

1. Grey check first. If the fill has R, G, and B channels all within ±16 of each other (same definition as the XML path's grey-family rule), OR HSL saturation < 0.20, classify as neutral. This check wins regardless of hue angle. 2. Hue band otherwise. Use these explicit HSL hue ranges:

• 180°–260° → primary (blue)
• 80°–170° → success (green)
• 45°–65° → warning (yellow)
• 20°–44° → accent (orange)
• 0°–19° or 320°–360° → danger (red/pink)
• 260°–320° → secondary (purple)

3. No band matched (gap regions at 65°–80° or 170°–180°) → spill to the nearest band by angular distance.

Collision rule. If ≥2 distinct fills land in the same slot, sort them by total pixel area covered in the image (descending). The largest keeps the canonical slot. Remaining fills spill to the nearest empty slot measured by hue-band angular distance — first to adjacent bands on either side, then farther out. If every slot is already filled, drop the extras and warn in the summary.

3. Extract shape vocabulary. Classify every visible shape by silhouette:

• rounded rectangle → rounded=1
• sharp rectangle → rounded=0
• circle / oval → ellipse
• diamond → rhombus
• cylinder (rectangle with curved top/bottom) → shape=cylinder3
• titled container (header bar + nested children inside) → swimlane;startSize=30
• dashed-bordered rectangle → rounded=1;dashed=1

Role assignment uses the same label-text + shape rules as the XML path step 4. Visible labels are read via vision.

4. Extract fonts. Best-effort. Distinguishable categories:

• clearly serif → fontFamily: "Georgia"
• clearly monospaced → fontFamily: "Courier New"
• otherwise → fontFamily: "Helvetica"

Size by relative appearance:

• small → fontSize: 11
• medium → fontSize: 12
• large → fontSize: 14

If titles/container headers are distinctly larger or bolder → set titleFontSize accordingly and titleBold: true.

5. Extract edge defaults.

• Right-angle orthogonal arrows → edges.style = "edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1".
• Curved arrows → append ;curved=1 to edges.style.
• Filled triangle arrowheads → edges.arrow = "endArrow=classic;endFill=1".
• Open V-shaped arrowheads → edges.arrow = "endArrow=open;endFill=0".
• Any dashed arrows near labels like "optional", "async", "fallback", "secondary" → add those label tokens to edges.dashedFor.

6. Extract extras.

• Visibly hand-drawn / rough / sketch look (wavy strokes, uneven fills) → extras.sketch = true.
• Heavy strokes (clearly >1.5× normal) → extras.globalStrokeWidth = 2.
• Otherwise default: extras = { "sketch": false, "globalStrokeWidth": 1 }.

7. Set provenance and confidence.

   {
     "source": { "type": "image", "path": "<input absolute path>", "extracted_at": "YYYY-MM-DD" },
     "confidence": "medium"
   }

Adjustments:

• <3 distinct shapes identifiable → confidence: "low".
• Image path stays at "medium" by default. The only path to "high" is a strictly-verifiable signal: the source image was exported from drawio itself (recognizable drawio default chrome, grid, or a visible drawio watermark), and all seven palette slots are filled, and all seven roles are labeled. This preserves the semantic gap between inference-based (image) and parse-based (XML) provenance.

Image edge cases

Style Presets — Learn, Apply, Manage

A style preset is a named JSON file capturing a user's visual preferences — palette, shape vocabulary, fonts, edge style. When a preset is active, it fully replaces the built-in conventions in SKILL.md's color/shape/edge tables.

Read this file when:

• The user asks to "learn", "save", "remember", or "extract" a style from a file
• The user wants to manage existing presets (list, set default, delete, rename)
• You've resolved an active preset in Step 0 and need the application rules
• You need to validate a preset file before loading it

Locations and lookup order

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

A user preset shadows a built-in of the same name.

Only user presets can have "default": true. When the user says "make `<built-in-name>` my default", copy the built-in JSON to ~/.drawio-skill/styles/<name>.json first, then set default: true on the copy — leave the shipped built-in untouched.

Name normalisation: always lowercase the user-provided name before writing or looking up files (the preset schema enforces lowercase; uppercase names will fail validation).

Applying a preset

When SKILL.md's Step 0 identified a preset, it fully replaces the built-in palette, shape keywords, edge defaults, and font for this diagram — do not mix values from the built-in color table.

Color lookup. For each role a shape plays (service / database / queue / gateway / error / external / security), resolve preset.roles[role] to a slot name, then preset.palette[<slot>] to the (fillColor, strokeColor) pair. If roles[role] is unset or the resolved slot is null, follow this fallback ladder:

1. Try the role's canonical slot (service→primary, database→success, queue→warning, gateway→accent, error→danger, external→neutral, security→secondary). 2. If that slot is also empty, pick the most-populated non-null slot in the preset. 3. Never reach into the built-in color table — the preset is authoritative.

Decision and container shapes are not in preset.roles — they have shape vocabulary (preset.shapes.decision, preset.shapes.container) but no role-to-slot mapping. Pick their colors as follows:

• Decision (rhombus) → use preset.palette.warning (the canonical yellow slot in the built-in conventions). If warning is empty, apply the slot-fallback ladder above starting from warning.
• Container (swimlane) → use the palette slot matching the tier/grouping the container represents (e.g. a "Services" tier container uses primary; a "Data" tier uses success). If no tier signal is available, default to primary.

Shape keywords. Use preset.shapes[role] as the prefix of the vertex style string (before whiteSpace=wrap;html=1;...). Example: for a database role, if preset.shapes.database = "shape=cylinder3", the vertex style starts shape=cylinder3;whiteSpace=wrap;html=1;fillColor=.... The six named shape keys are service, database, queue, decision, external, container. Roles gateway, error, and security reuse preset.shapes.service unless the preset explicitly populates a key with their name.

Edges. Use preset.edges.style as the base edge style string. Append preset.edges.arrow. Per-edge routing keys (exitX/exitY/entryX/entryY/...) are still added by the usual routing rules in SKILL.md. If the flow between two shapes matches a token from preset.edges.dashedFor (either because the user's prompt used that word, or because one end of the edge plays a role whose typical relation is "optional"), append ;dashed=1 to the edge style.

Fonts. Append fontFamily=<preset.font.fontFamily>;fontSize=<preset.font.fontSize> to every vertex style. Container headers and swimlane titles additionally get fontSize=<preset.font.titleFontSize>;fontStyle=1 when preset.font.titleBold is true.

Extras.

• preset.extras.sketch === true → append sketch=1 to every vertex style and every edge style.
• preset.extras.globalStrokeWidth !== 1 (any value other than the drawio default of 1, including 0.5) → append strokeWidth=<n> to every vertex style and every edge style.

Interaction with diagram-type presets (ERD / UML / Sequence / ML / Flowchart). Diagram-type presets set structural style keywords that the user preset must preserve (e.g. ERD tables rely on shape=table;startSize=30;container=1;childLayout=tableLayout;...). The rule: keep the diagram-type preset's structural keywords, then layer the user preset's color / font / edge / extras on top. When a diagram-type preset hardcodes a color (fillColor=#dae8fc, etc.) that conflicts with the user preset, the user preset's color wins. Exception: fillColor=none is structural — do not replace it with a palette color.

Learn flow

Triggers: "learn my style from <path> as <name>", "save this as <name> style", "remember this style as <name>".

Dispatch by file extension:

• .drawio, .xml → XML path
• .png, .jpg, .jpeg, .svg (rasterized flat image) → image path

Steps:

1. Load the extraction reference. Read references/style-extraction.md into context. 2. Extract following the XML path or image path procedure in the reference. 3. Normalize and build candidate. Convert the user-provided preset name to lowercase. Use this normalized name for ALL file paths in this flow. Build the candidate preset JSON and write it to /tmp/drawio-preset-<name>.json (where <name> is the already-normalized name). Do not save to ~/.drawio-skill/styles/<name>.json yet. 4. Render a sample using the sample-diagram skeleton in references/style-extraction.md, parameterized by the candidate preset. Export PNG to ./preset-<name>-sample.png using the same drawio -x -f png -e -s 2 -o ./preset-<name>-sample.png /tmp/drawio-preset-<name>.drawio command the main workflow uses, then run repair_png.py on it (see the Rendering the sample steps in style-extraction.md). 5. Show the user:

• Preset summary table (palette hex values, shapes per role, font, edge style, extras).
• The sample PNG path (and embed the image if the environment supports it).
• Provenance line: source.type, source.path, extracted_at, confidence.

6. Wait for approval:

• "save" / "looks good" → write candidate to ~/.drawio-skill/styles/<name>.json. Create ~/.drawio-skill/styles/ if it doesn't exist. Delete tempfile and sample PNG.
• "change <field> to <value>" → edit the in-memory candidate, re-render, re-ask.
• "cancel" / "abort" / "no" → delete tempfile and sample PNG; nothing saved.

Error behavior:

Management operations

All operations are natural language — no slash commands.

Apply name normalisation (lowercase) to all `<name>`, `<a>`, `<b>` arguments before any file operation.

Preset file validation

When loading any preset (for generation or management), do a lightweight structural check:

• Required top-level fields present (name, version, palette, roles, shapes, font, edges).
• version === 1.
• Every populated palette slot has both fillColor and strokeColor as #RRGGBB.
• confidence ∈ {"low", "medium", "high"} if present.

On validation failure:

• During generation: warn the user, fall back to built-in conventions for this one diagram, do not mutate the file.
• During learn: refuse to save the candidate; report which field failed.

Troubleshooting — Common Mistakes

Read this when something looks wrong in the output (rendering, export, layout, edges) or when a CLI invocation fails. Most rows have a one-line fix.

WSL2 / Windows specifics

Locate the CLI. Detect WSL2 with grep -qi microsoft /proc/version. On WSL2 the export CLI is the Windows desktop exe, reached through /mnt/c (quote the path — it contains a space):

"/mnt/c/Program Files/draw.io/draw.io.exe" --version
# per-user install fallback:
"/mnt/c/Users/$USER/AppData/Local/Programs/draw.io/draw.io.exe" --version

Open a file. Convert the WSL path to a Windows path first; cmd.exe cannot follow /mnt/c/...:

cmd.exe /c start "" "$(wslpath -w diagram.drawio.png)"

Open a browser-fallback URL. cmd.exe /c start strips the URL fragment (& ends the command, #… is dropped) — and the fragment carries the entire diagram. Write a .url shortcut and open it instead, so the URL survives intact:

URL=$(python3 <this-skill-dir>/scripts/encode_drawio_url.py --edit diagram.drawio)
TMP=$(mktemp --suffix=.url)
printf '[InternetShortcut]\r\nURL=%s\r\n' "$URL" > "$TMP"
cmd.exe /c start "" "$(wslpath -w "$TMP")"

On native Windows the same .url-file trick applies (start "" "%TEMP%\d.url"). On macOS/Linux just open "$URL" / xdg-open "$URL" — no workaround needed.