drawio

name

drawio

description

Generate draw.io diagrams (`.drawio` XML files) from detailed user prompts, in Jack's brand style. Use when the user asks to create, visualize, draw, or diagram architectures, workflows, pipelines, systems, or processes in draw.io / diagrams.net / XML form. Requires a description of what to diagram — does not analyze codebases automatically. Ask clarifying questions if diagram type, complexity, or subsystems are unclear. Every diagram is exported to PNG via the draw.io CLI and visually validated in a render-view-fix loop before delivery.

Draw.io Diagram Generator

Generate .drawio XML files in Jack's brand style (swimlane frames for grouping, 4-color semantic palette, rounded=1/arcSize=15 boxes, orthogonal edges, matching stroke+font colors). Every diagram is exported to PNG via the draw.io CLI (macOS: /Applications/draw.io.app/Contents/MacOS/draw.io) and you Read the PNG and check it before declaring done. Never pass -e / --embed-diagram — it breaks Claude Code's image reader.

File Index — READ ALL OF THESE BEFORE GENERATING

Before writing any XML, read every references/*.md file below. They are small, and the rules interact — edge exitX/entryX lives in connectors.md, but the whitespace and frame-padding rules in diagram-style.md determine where those connection points should land; the validation checklist in validation.md catches the silent-binding failures that cause invisible arrows and edges whose parent doesn't match their source box's parent. Round-1 agents who skipped files produced edges that rendered as straight lines through the wrong frame, legends outside the swimlane, and italic box text.

Path	Purpose
references/xml-format.md	mxfile structure, mxCell elements (vertices + edges), swimlanes, waypoints, loops, bidirectional edges. Read first — the skeleton must be correct before style matters.
references/diagram-style.md	Palette, roughness, Helvetica, layout patterns (vertical / feedback / fan-out), spacing grid, legend placement, box sizing. Read this to get the look right — every diagram follows these rules regardless of complexity.
references/connectors.md	Edge anatomy, exitX/entryX recipe, same-side feedback-loop rule, fan-out stagger, arrow types, edge-label placement. Read before placing any edge; same-side rule is the #1 source of "my loop looks weird" bugs.
references/brand-colors.md	4-color semantic palette (User/Det/Agentic/Mix) with BOTH strokeColor AND fontColor matched, plus the (rare) dashed-box recipe for optional/unknown components. Read when picking colors.
references/validation.md	Technical + style validation checklist (unique IDs, source/target valid, edge parent matches source parent, fontStyle=0 on boxes, etc). Run through before declaring the diagram done.
references/cli.md	draw.io CLI export reference: platform paths, flags, the -e flag is forbidden (breaks Claude Code's image reader), PNG vs SVG tradeoffs. Read before running any export.
references/examples/agent-sdk-harness.{drawio,png,svg}	Best example. Single-swimlane comparison diagram, feedback loops via same-side exit/entry, dashed retry edges, italic edge labels, 4-color semantic palette, legend top-right. Study the JSON and the PNG side by side — the PNG shows the visual, the XML shows the coordinates, parent bindings, and edge routing Jack uses. You cannot match Jack's style without seeing both.
references/examples/multi-container-3tier.{drawio,png,svg}	Multi-container pattern: 3 side-by-side swimlane frames with cross-frame edges at parent="1" (not inside any frame), local-to-frame edges at parent="frame-id". Study when the diagram has ≥ 2 subsystems that talk to each other.
references/examples/sample-input.md	Reference input document. Shows the shape of a well-structured source markdown — executive summary, subsystems, per-component fields (role, owner, color), data stores listed separately, cross-cutting placement, edge table with explicit return-vs-forward marking, prompt-vs-source caveats. Use as a checklist when the user's input is sparse: every section missing in their input is a candidate Step 0 interview question.

Quick Start

1. Run the Step 0 Interview for any decision the user didn't already specify — see Required Information (eight decisions, recommended defaults marked, only ask the missing ones).
2. Read every references/*.md file. Do not skip any. Rules interact across files.
3. Plan sections first (Step 0). Pick the visual pattern; sketch frame layout; verify no edge has to cross a third frame.
4. Generate XML. For multi-frame diagrams, build one frame per edit — place frame + its internal boxes + its internal edges, render + look, then add the next frame. Cross-frame edges come last.
5. Export to PNG via the CLI (-x -f png -b 10, no -e) using a -vN version suffix (diagram-v1.png, never overwrite), and Read the PNG.
6. Iterate 2–4 times — each pass increments the suffix (diagram-v2.drawio, diagram-v2.png, …). At session end, copy the winning version to the unsuffixed canonical filename and keep the -vN files as iteration history.

Required Information — Step 0 Interview

Diagram quality is bounded by input quality. Before generating XML, confirm the eight decisions below. Only ask the user about decisions that are genuinely missing or ambiguous in their input — if they already said "make me an architecture diagram of these 5 services with auth as cross-cutting," do not re-ask. For each decision they did not specify, present the options as multiple choice with the Recommended default marked, so the user can override only what they care about and accept defaults for the rest.

references/examples/sample-input.md is a worked example of input that answers all eight questions upfront. Use it as the checklist: every section absent from the user's input is a candidate interview question.

The Eight Decisions

1. Diagram type — process (workflow, timeline, ordered steps) or architecture (components, services, infrastructure)?
2. Complexity — simple (5–10 boxes) / medium (15–25, Recommended default if uncertain) / complex (30+)?
3. Subsystems / frames — single frame, or multiple swimlane frames? If multiple: what are the frames, and which talk to which?
4. Components per subsystem — name, role, owner (internal vs vendor), and how they connect.
5. Data stores — are there persistent stores (databases, queues, logs)? List each separately so the skill can render each as a cylinder. (Default: no stores unless mentioned.)
6. Cross-cutting concerns — auth, telemetry, HITL review, etc. For each, where does it render? (a) global bar above frames, (b) own swimlane (Recommended if it interacts with most components), (c) inside an existing frame, (d) omit and mention in caption.
7. Color axis — what semantic dimension drives color? (a) ownership (internal vs vendor), (b) determinism — blue/red/orange/black (Recommended default — matches brand palette), (c) lifecycle status (current/deprecated/planned), (d) none / monochrome.
8. Exception / noteworthy highlighting — how should exception paths or callouts be marked? (a) red stroke + italic edge label (Recommended), (b) inline ? in label, (c) dedicated callout box, (d) no exceptions in this diagram. Do not use dashed for this — dashed is reserved for return/response edges only.

Interview Template (use only for unanswered decisions)

A few quick choices to make sure the diagram matches what you have in mind. I've marked Recommended defaults — you can just say "defaults" to skip.

1. Diagram type: process or architecture?
2. Complexity: simple / medium [Recommended] / complex?
3. Cross-cutting infrastructure (auth, telemetry, HITL) — global bar above frames / own swimlane [Recommended if it touches most components] / inside an existing frame / omit?
4. Color axis — ownership / determinism [Recommended] / lifecycle / none?
5. Exceptions / noteworthy paths — red stroke + italic label [Recommended] / inline ? / callout box / none?

(Only asking the ones I couldn't infer from your input.)

The interview is not a gate. If the user says "just go" or "use defaults," accept the recommended defaults for every unanswered decision and proceed. The point of the interview is to flip the default: the skill prompts for the decisions that most influence quality so the user only overrides what they care about.

Workflow

Step 0: Plan Sections First

For any diagram with ≥ 8 boxes or 2+ subsystems. The single most important step — layout decisions made here determine whether the diagram will work.

1. Pick a flow direction (soft preference, not a rule):

   • Timelines, chronological sequences, phased rollouts usually read better left-to-right.
   • Technical request/response flows, pipelines, and data transforms often lean top-to-bottom.
   • Holding one direction per frame tends to look cleaner; mix only if there's a good reason (loops, callbacks, sidebars).

2. Pick a visual pattern that matches the argument the diagram makes: assembly line, fan-out, convergence, hub with spokes, side-by-side comparison, tree, loop. Jack's two canonical examples cover the two most common:

   • Single-frame feedback process → agent-sdk-harness.drawio.
   • Multi-container architecture with cross-frame flow → multi-container-3tier.drawio.

3. List subsystems — each becomes a swimlane frame (style="swimlane;..."). For each frame, note which other frames it exchanges edges with, and which edge each cross-frame arrow exits from.

4. Sketch the frame layout mentally or on paper. Every cross-frame edge should have a direct path (orthogonal, one or two bends) that does NOT cross a third frame's bounding box.

5. Check the signs the layout is wrong (references/diagram-style.md):

   • Two frames that exchange many edges are separated by a third frame.
   • Frames < 100px apart with edges squeezing between them.
   • An edge would need to jump over another frame to reach its target.
   • Dead whitespace > 300px between neighboring frames with no edges across.

6. Reconcile the prompt against the source. If the user provided both a prompt and a source document (markdown, design doc, spec), check that every grouping, ownership claim, and label in the prompt is supported by the source before encoding it in XML. When the prompt says "Platform X owns components A and B" but the source describes A and B as independent third-party vendors with no mention of Platform X, flag the discrepancy and ask the user which is correct — do not silently trust the prompt. Content errors propagate from Step 0 into the rendered diagram and are far more expensive to catch downstream than to confirm upfront.

Fix by moving frames, not by hand-routing waypoints. Edge XML is determined by layout.

Step 1: Read ALL References

Read every references/*.md listed in the File Index at the top of this document. Short files, interacting rules — skipping any one of them is the main cause of round-1 failures (edges whose parent doesn't match, legends outside swimlanes, italic box text, colors that don't match font).

Step 2: Study the canonical example(s) (MANDATORY)

Not optional. For the pattern you picked in Step 0, open both the .drawio XML and the .png side by side:

Example	Pattern	When to pick it
references/examples/agent-sdk-harness.{drawio,png}	Single swimlane, ~30 boxes, feedback loops via same-side exit/entry, dashed retry edges, italic HTML edge labels, 4-color legend top-right	Process/architecture that reads as one coherent subsystem. Most common default. Pick when the whole thing is "how one system works."
references/examples/multi-container-3tier.{drawio,png}	3 side-by-side swimlane frames, cross-frame edges at parent="1", per-frame internal edges at parent="frame-id", 1-color default with accent boxes	Architecture where 2–4 subsystems pass data between each other. Pick when the argument is "this container does X, this container does Y, and here's how they talk."

The PNG shows the visual target. The XML shows the exact attribute patterns — parent bindings, edge routing, exitX/entryX values, legend coordinates — that Jack's diagrams use. You cannot match Jack's style without seeing both.

Step 3: Generate XML

Standard defaults (see references/xml-format.md, diagram-style.md):

• Wrapper: mxfile > diagram > mxGraphModel > root with mxCell id="0" and mxCell id="1" parent="0" first
• Frame: style="swimlane;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#1e1e1e;strokeWidth=2;fontSize=14;fontStyle=0;fontColor=#1e1e1e;startSize=30;rounded=0;"
• Box: rounded=1;arcSize=15;fillColor=#ffffff;strokeWidth=2;whiteSpace=wrap;html=1;align=center;verticalAlign=middle;fontFamily=Helvetica;fontStyle=0 (default 160×60 — tighten before growing)
• Edge: edgeStyle=orthogonalEdgeStyle;rounded=0;strokeWidth=2;endArrow=classic;endFill=1
• Color rule: strokeColor AND fontColor must match for every color-coded element.

Key parent rules (easy to get wrong):

• Elements inside a frame → parent="frame-id" with coordinates relative to the frame's origin (NOT the page).
• Edges between two boxes in the same frame → parent="frame-id" (same as the boxes).
• Edges between two boxes in different frames → parent="1" (top-level).
• Legend items → same parent as the frame's content (inside the frame, top-right).

Build one frame per edit for multi-frame (≥ 2 frame) diagrams. Namespace box IDs per frame (s1-box-*, s2-box-*) so future edits don't accidentally collide. Add cross-frame edges last, after all frames are in place.

Write the .drawio file directly. Do not generate helper/build scripts (.py, .js, XSLT transforms) unless the user explicitly asks for a reusable generator.

Step 4: Export PNG via the CLI (with -vN version suffix)

Preserve every iteration. Never overwrite a previous .drawio or .png in place. Each render-view-fix pass burns real tokens; if iteration N+1 turns out worse than N (AI evals are not deterministic, and the human reviewer may disagree with your own assessment), the previous artifact must still exist.

Naming convention — write each iteration to a version-suffixed filename:

# Iteration 1
/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png -b 10 \
  -o path/to/diagram-v1.png path/to/diagram-v1.drawio

# Iteration 2 (after Step 6 fixes)
/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png -b 10 \
  -o path/to/diagram-v2.png path/to/diagram-v2.drawio

Treat all -vN.drawio and -vN.png files as deliverables, not temporaries. They are the iteration history the human reviewer will compare side-by-side at the end.

At session end, after the human picks the winning version (or if the model judges the latest is best and the user agrees), copy that version to the unsuffixed canonical filename so downstream consumers have a single stable target:

cp path/to/diagram-vN.drawio path/to/diagram.drawio
cp path/to/diagram-vN.png   path/to/diagram.png

The -vN files stay in place as iteration history.

Never pass -e / --embed-diagram — it embeds the full XML into the image and breaks Claude Code's Read tool for images. See references/cli.md for platform-specific paths (Linux, Windows, WSL2) and SVG fallback.

If the user wants both formats, run the export twice (-f png and -f svg) — both with the same -vN suffix. PNG is what you (the model) Read in Step 5; SVG is for the human to view with adaptive light/dark theming.

Step 5: View the PNG (MANDATORY)

Read the resulting .png and look at it. Check, in this order:

1. Edges don't cross non-endpoint boxes (HARD FAIL). Trace every edge with your eyes from source to target. If an edge's routed path passes through a box that is NOT its source and NOT its target, that is a hard fail — redo the layout. The draw.io auto-router is not smart enough to avoid non-endpoint boxes; you control this by where you place the boxes. Fixing this is Step 0 (move the offending box or frame), not adding waypoints.
2. Max 2 turns per edge. An orthogonal edge should have at most 2 elbow bends between source and target. If an edge looks like it makes a U-turn, snakes around, or zig-zags, either the layout is wrong (boxes are in the wrong order) or you're routing around something that shouldn't be in the way. Fix by moving boxes, not by accepting a 4-turn path.
3. Converging arrows merge into ONE bind point on the target. When 3+ edges end at the same target box, every edge enters at the exact same connection point — identical entryX AND identical entryY. The arrowheads visually stack at one spot; the tails fan out to reach their sources. Good: 4 arrows all entering the target at entryX=0;entryY=0.5 (left-middle), arrowheads overlapping. Bad: 4 arrows entering at staggered entryY positions (0.2, 0.4, 0.6, 0.8) — this looks like a spray array, not a convergence. Worse: 4 arrows coming in from N/S/E/W (octopus). Multiple edges sharing the same bind point is correct, not a bug. Don't stagger entries to give each arrow its own landing spot.
4. Edges land on the correct side. Bottom→top for vertical flow, right→left for horizontal, same-side for feedback loops.
5. Text: clipped, overflowing a box, or bleeding into the box border? Italic where it shouldn't be?
6. Alignment: same-row boxes share Y + height? same-column boxes share X + width? gridSize=10 respected (coordinates snap to multiples of 10)?
7. Spacing: < 30px cramps between boxes, or > 200px dead whitespace inside a frame?
8. Frames: subsystems read as visually distinct swimlanes (black border, 30px title header, clear internal layout)?
9. Legend: if 2+ semantic colors are used, is there a legend (top-right inside the frame for single-frame, top-left at the canvas level for multi-frame)?
10. Colors: every color-coded box has matching stroke AND font — no blue-box-with-black-text leaks?
11. Edge labels sit near their arrow body. A free-floating label 300px away from the arrow it annotates is visually orphaned; it should be within ~40px of the arrow's midpoint.

Do not ship a diagram you haven't looked at. Claiming "done" without Reading the PNG is the single biggest regression the eval caught. The first three checks above are the ones that were missing from iteration 1 and caused visually-wrong-but-XML-valid outputs.

Step 6: Fix & re-render (loop 2–4 times — increment the version suffix each pass)

If anything is wrong, copy diagram-vN.drawio to diagram-v(N+1).drawio, edit the new file, then re-export to diagram-v(N+1).png. Do not overwrite the previous version's .drawio or .png. Typical fixes:

• Edge crossing a third frame → Step 0 (re-plan the layout), not a new waypoint.
• Feedback loop looks weird → switch to same-side exit/entry (exitX=0;exitY=0.5;entryX=0;entryY=0.5).
• Edge drawn straight line through a box → edge parent doesn't match the connected boxes' parent; fix parent.
• Colors don't match → set BOTH strokeColor AND fontColor.
• Italic text on boxes → fontStyle=0 (not 2).

Re-Read the new -v(N+1).png after each fix. When the loop terminates, surface all -vN versions to the user so they can pick the winner before you copy it to the canonical unsuffixed filename (see Step 4).

Step 7: Technical validation

Run through the checklist in references/validation.md before declaring done:

• All IDs unique
• Every edge's source and target exist in the document
• Edge parent matches both endpoints' parent (or parent="1" for cross-frame)
• Every vertex has vertex="1" and a child <mxGeometry>; every edge has edge="1" and a child <mxGeometry relative="1">
• Edge labels (if any) have connectable="0" and parent="edge-id" (parent is the edge, not the frame)
• No diamonds (bindings break on diamond shapes — use rounded rectangles)

Critical Rules

1. Edges must not cross non-endpoint boxes. If you trace an edge with your eyes and it passes through a box that is neither its source nor its target, the diagram fails. The draw.io router won't help you — this is controlled by where you place boxes and frames. Fix is layout, not waypoints: move the offending box, widen a gap, or reorder so the routing space is clear. This is the most-missed quality gate and is checked first in Step 5.
2. Max 2 turns per edge. Converging arrows merge into ONE bind point. An orthogonal edge should have at most 2 elbow bends. If 3+ edges land at the same target, they all enter at the exact same connection point — identical entryX AND identical entryY, not staggered. The arrowheads visually stack at one spot on the target; the tails fan out to the sources. Multiple edges sharing one bind point is not a bug — it's the correct pattern. Good: 4 arrows all targeting entryX=0;entryY=0.5. Bad: 4 arrows at entryY 0.2/0.4/0.6/0.8 (spray array). Worse: 4 arrows arriving from N/S/E/W (octopus). Fix by using the same bind point on the target for every converging edge.
3. Plan sections first (Step 0). Everything downstream depends on frame placement; fixing layout afterward is 10× more work than fixing it upfront. Rules 1 and 2 are almost always caused by skipping Step 0.
4. Render and Read the PNG before shipping. No unlooked-at diagrams. The XML can validate as perfect and still look broken — rules 1 and 2 in particular can only be caught by looking.
5. Never pass -e to the CLI. It breaks Claude Code's image reader — a .png with embedded XML becomes unreadable by the Read tool. Keep the .drawio file as the editable source of truth alongside the exported image.
6. Build one frame per edit for 2+ frame diagrams. Place the frame + its internal boxes + its internal edges, render + look, then move to the next frame. Cross-frame edges come last, after all frames exist.
7. Edge parent must match context. Internal edge → same parent as its endpoints' frame. Cross-frame edge → parent="1". Getting this wrong causes edges that render as straight lines through the wrong part of the canvas.
8. Match strokeColor AND fontColor on every color-coded element. A blue box with black text is a bug, not a style choice.
9. Same-side exit/entry for feedback loops. Draw.io auto-routes correctly when both ends of a loop use the same side (exitX=0;entryX=0 for left, exitX=1;entryX=1 for right). No waypoints needed.
10. Never use diamond shapes. Edge bindings break on diamonds. Use rounded=1 rectangles for decisions too.
11. fontStyle=0 on boxes, fontStyle=2 (italic) only on edge labels. Boxes default to italic when omitted — this is the #1 text-style regression.
12. Legend inside the frame, top-right (single-frame diagrams); top-left at canvas level (multi-frame). Legend items 100×30, fontSize=12, 40px vertical spacing.
13. One box size per diagram. Pick a standard (usually 160×60 for one-line labels, 180×80 for two-line) and hold it. Legend swatches (100×30) are the one intentional exception.
14. Snap to 10px grid. gridSize=10 at the mxGraphModel level; every coordinate should be a multiple of 10.
15. Keep the .drawio file. Preserve every iteration with a -vN suffix; never overwrite. The .drawio file is the re-editable source of truth — never try to round-trip edits through the exported image. During the render-view-fix loop, each pass writes a new -vN.drawio and -vN.png; at session end, copy the winning version to the unsuffixed canonical filename and keep the -vN files as iteration history.
16. No helper-file detours. When the deliverable is a diagram, create the .drawio file itself. Do not create .py/.xslt/.js builder files unless the user explicitly asks for one.
17. Dashed only on edges, only for return/response/feedback. Never on boxes. dashed=1;dashPattern=8 8; carries exactly one meaning: the arrow flows back to a caller (response, reply, feedback, retry, async callback). For optional or unknown components, append ? to the box label — do not draw a dashed box. The "Dashed Box" recipes that still appear in references/xml-format.md and references/brand-colors.md are deprecated; this rule supersedes them.

Quick Reference

Brand Colors

Role	Hex	Usage
User/Default	#1e1e1e	Input, output, standard elements
Deterministic	#1971c2	Predictable logic, scripted flows
Agentic	#e03131	AI-driven, dynamic, unpredictable
Mix	#f08c00	Hybrid components

Standard Style Snippets

Box: rounded=1;arcSize=15;fillColor=#ffffff;strokeWidth=2;whiteSpace=wrap;html=1;align=center;verticalAlign=middle;fontFamily=Helvetica;fontStyle=0
Edge: edgeStyle=orthogonalEdgeStyle;rounded=0;strokeWidth=2;endArrow=classic;endFill=1
Frame: swimlane;whiteSpace=wrap;html=1;fillColor=#ffffff;strokeColor=#1e1e1e;strokeWidth=2;fontSize=14;fontStyle=0;fontColor=#1e1e1e;startSize=30;rounded=0
Dashed (return/response/feedback edges only): append dashed=1;dashPattern=8 8;
Feedback-left loop: append exitX=0;exitY=0.5;entryX=0;entryY=0.5;
Feedback-right loop: append exitX=1;exitY=0.5;entryX=1;entryY=0.5;

Page Defaults

<mxGraphModel dx="1908" dy="840" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="2200" pageHeight="1400" math="0" shadow="0">

Troubleshooting

Symptom	Likely cause	Fix
Edge draws as straight diagonal line	Edge parent doesn't match boxes' parent	Set edge parent="frame-id" for internal, parent="1" for cross-frame
Edge doesn't render at all	source or target ID doesn't exist	Verify both IDs; check for typos
Feedback loop routed around the whole frame	Exit/entry on different sides	Use same-side (both exitX=0;entryX=0 or both exitX=1;entryX=1)
Italic box text	fontStyle omitted or =2	Set fontStyle=0 on boxes
Colors don't match	Only strokeColor set	Set BOTH strokeColor AND fontColor
PNG is unreadable by Claude	-e / --embed-diagram flag passed	Re-export WITHOUT -e
Legend outside the frame	Legend items parent="1" instead of frame	Set parent="frame-id" on every legend item
Multi-frame diagram's cross-edge hidden	Cross-frame edge inside a frame	Move to parent="1"