# draw.io XML Reference Detailed reference for styles, edge routing, containers, layers, tags, metadata, and dark mode. Consult this when generating draw.io XML diagrams. ## Reasoning budget (read this first) Your job is to declare the **logical structure** of the diagram — what nodes exist, what edges connect them, what labels they carry, what lane/container groups them. draw.io's edge router and (when available) a post-layout pass handle routing and placement; you do **not** need to do layout math. **Do NOT** in your reasoning: - Do NOT debate the topic. The user asked for a flowchart / architecture / sequence / etc. — pick one concrete scenario on your first impulse and commit. Never write "Actually, let me think of something else…" or pitch alternatives. - Do NOT debate flat-lanes vs nested-pools, horizontal vs vertical orientation, one vs multiple variations. Pick the first reasonable option (almost always: flat swimlanes, top-down or left-right based on what fits the content). Do not flip-flop. - Do NOT compute x/y coordinates in prose. No "column spacings of 160px totaling 1840px width — that's too wide, let me tighten to 1700…" loops. Use the rigid grid below; do the arithmetic in your head and write the XML. - Do NOT re-derive drawio mechanics (`horizontal=0`, `startSize=110`, nested-lane coordinates). Use the templates below as-is. - Do NOT enumerate columns ("customer lane columns 0-10, web app 1-7"). Place a node, move on. - Do NOT add `` waypoints. Edges are routed automatically. - Do NOT set `exitX` / `exitY` / `entryX` / `entryY` connection-point overrides unless you have specific geometric intent. - Do NOT verify, re-check, or adjust coordinates after placing a node. - Do NOT narrate "building the diagram / finalizing the XML / now let me…". Just emit XML. - Do NOT write out lists of node positions as planning text. Emit them as `` elements directly. **Do** in your reasoning: - Identify the diagram type + actors/stages (1-2 short sentences). - Identify any grouping (swimlanes? containers? none?). - Go straight to XML. **Rigid grid — use for every XML diagram:** - Column x = `col_index * 180 + 40` (col 0 = 40, col 1 = 220, col 2 = 400, …) - Row y = `row_index * 120 + 40` (row 0 = 40, row 1 = 160, row 2 = 280, …) - Node size: rectangles `140×60`, diamonds `140×80`, circles `60×60`, documents `120×80`, cylinders `100×70` Pick a `(col, row)` for each node. Don't think about centers, gaps, or overlap — ELK handles routing between rough positions. Slight misalignment is invisible in the result. ## General principles - **Use proper draw.io shapes and connectors** — choose the semantically correct shape for each element (e.g., `shape=cylinder3` for databases and tanks, `rhombus` for decisions, `shape=mxgraph.pid2valves.*` for valves in P&IDs). draw.io has extensive shape libraries; prefer domain-appropriate shapes over generic rectangles. - **Decide whether to search for shapes** — before generating a diagram, decide if it needs domain-specific shapes from draw.io's extended libraries. **Skip `search_shapes`** for standard diagram types that use basic geometric shapes: flowcharts, UML (class, sequence, state, activity), ERD, org charts, mind maps, Venn diagrams, timelines, wireframes, and any diagram using only rectangles, diamonds, circles, cylinders, and arrows. Also skip if the user explicitly asks to use basic/simple shapes or says not to search. **Use `search_shapes`** when the diagram requires industry-specific or branded icons: cloud architecture (AWS, Azure, GCP), network topology (Cisco, rack equipment), P&ID (valves, instruments, vessels), electrical/circuit diagrams, Kubernetes, BPMN with specific task types, or any domain where the user expects realistic/standardized symbols rather than labeled boxes. - **Match the language of labels to the user's language** — if the user writes in German, French, Japanese, etc., all diagram labels, titles, and annotations should be in that same language. ## Common styles **Rounded rectangle:** ```xml ``` **Diamond (decision):** ```xml ``` **Arrow (edge):** ```xml ``` **Labeled arrow:** ```xml ``` ## Style properties | Property | Values | Use for | |----------|--------|---------| | `rounded=1` | 0 or 1 | Rounded corners | | `whiteSpace=wrap` | wrap | Text wrapping | | `fillColor=#dae8fc` | Hex color | Background color | | `strokeColor=#6c8ebf` | Hex color | Border color | | `fontColor=#333333` | Hex color | Text color | | `shape=cylinder3` | shape name | Database cylinders | | `shape=mxgraph.flowchart.document` | shape name | Document shapes | | `ellipse` | style keyword | Circles/ovals | | `rhombus` | style keyword | Diamonds | | `edgeStyle=orthogonalEdgeStyle` | style keyword | Right-angle connectors | | `edgeStyle=elbowEdgeStyle` | style keyword | Elbow connectors | | `dashed=1` | 0 or 1 | Dashed lines | | `swimlane` | style keyword | Swimlane containers | | `group` | style keyword | Invisible container (pointerEvents=0) | | `container=1` | 0 or 1 | Enable container behavior on any shape | | `pointerEvents=0` | 0 or 1 | Prevent container from capturing child connections | | `html=1` | 0 or 1 | Enable HTML rendering in labels (required for ``, `
`, ``, etc.) | | `shape=umlLifeline;perimeter=lifelinePerimeter;size=16` | shape | UML sequence diagram lifeline (size = header height) | ## HTML labels **Always include `html=1` in the style** when the `value` attribute contains any HTML tags (``, `
`, ``, ``, ``, `
`, `
`, ``, etc.). Without `html=1`, HTML tags are displayed as literal text instead of being rendered. HTML in attribute values must be **XML-escaped**: `<` → `<`, `>` → `>`, `&` → `&`, `"` → `"` ```xml ``` **Line breaks:** Use ` ` (works with both `html=1` and `html=0`) or `<br>` (requires `html=1`) for line breaks — never use `\n`, which renders as literal backslash-n text instead of a newline. **Best practice:** Always include `html=1` in every cell style. This ensures labels render correctly whether they contain HTML or plain text — plain text is unaffected by the flag. **Bold/italic/underline:** Use `fontStyle` in the style string when the entire label should be bold (`fontStyle=1`), italic (`fontStyle=2`), or underline (`fontStyle=4`). Values can be combined via bitwise OR (e.g., `fontStyle=3` = bold+italic). Use HTML tags (``, ``, ``) only when formatting part of the label (e.g., bold title with normal description). Never combine `fontStyle` with HTML tags for the same effect — this is redundant and causes visible raw tags if `html=1` is missing. ## Edges **CRITICAL: Every edge `mxCell` must contain a `` child element.** Self-closing edge cells (e.g. ``) are invalid and will not render correctly. Always use the expanded form: ```xml ``` **Edge routing is automatic.** After the diagram renders, the viewer runs an ELK edge-routing pass that pins vertices and recomputes bend points + connection points. You do **not** need to: - Add `` waypoints - Set `exitX` / `exitY` / `entryX` / `entryY` - Route around obstacles - Worry about edge-vertex collisions or parallel edge spacing Just declare `source` and `target` and let ELK do the routing. The ELK pass also reverts itself if it made routing worse — so your edges are at worst unchanged, never worse. **What you still choose: the edge style.** The style determines the overall look (orthogonal angles, curves, straight lines) — ELK honors the style family when routing. | Style | Syntax | Best for | |-------|--------|---------| | **Orthogonal** | `edgeStyle=orthogonalEdgeStyle` | Flowcharts, architecture, network diagrams, BPMN — any diagram with right-angle connectors | | **Straight** | no `edgeStyle` | UML class/sequence diagrams, direct point-to-point connections. For sequence diagram messages use `endSize=6;startSize=6;` to keep arrowheads small | | **Entity Relation** | `edgeStyle=entityRelationEdgeStyle` | ER diagrams — creates perpendicular stubs at both ends | | **Curved** | `curved=1` | Mind maps, informal diagrams | | **Elbow** | `edgeStyle=elbowEdgeStyle;elbow=vertical;` | Rarely needed — `orthogonalEdgeStyle` handles almost all cases; use this only for simple 1-bend linear flows | **Use a consistent edge style within each diagram.** Pick one based on diagram type and apply it to all edges: ER → `entityRelationEdgeStyle`; UML class → straight; mind maps → curved; flowcharts/architecture/network → `orthogonalEdgeStyle`. **Useful edge style attributes** that apply regardless of routing: - `rounded=1` — rounded corners at bend points (recommended for orthogonal) - `endArrow=classic` / `endArrow=none` — arrow heads - `dashed=1` — dashed line - `strokeColor=#...`, `strokeWidth=2` — color/width - Edge labels: set `value` directly on the edge cell ## Containers and groups For architecture diagrams or any diagram with nested elements, use draw.io's proper parent-child containment — do **not** just place shapes on top of larger shapes. ### How containment works Set `parent="containerId"` on child cells. Children use **relative coordinates** within the container. ### Container types | Type | Style | When to use | |------|-------|-------------| | **Group** (invisible) | `group;` | No visual border needed, container has no connections. Includes `pointerEvents=0` so child connections are not captured | | **Swimlane** (titled) | `swimlane;startSize=30;` | Container needs a visible title bar/header, or the container itself has connections | | **Custom container** | Add `container=1;pointerEvents=0;` to any shape style | Any shape acting as a container without its own connections | ### Key rules - **Edges to children inside containers naturally cross the container boundary** — this is correct and expected. Do not add extra waypoints or complex routing to avoid a parent container when connecting to shapes inside it. - **Always add `pointerEvents=0;`** to container styles that should not capture connections being rewired between children - Only omit `pointerEvents=0` when the container itself needs to be connectable — in that case, use `swimlane` style which handles this correctly (the client area is transparent for mouse events while the header remains connectable) - Children must set `parent="containerId"` and use coordinates **relative to the container** ### Example: Architecture container with swimlane ```xml ``` ### Example: Invisible group container ```xml ``` ### Swimlanes for grouped actors (BPMN-style flowcharts) Use **flat swimlanes** at `parent="1"`, stacked vertically. One row of nodes per lane. **Fixed values — do not compute or debate:** - Lane size: `x=0, y=lane_index*150, width=CANVAS_W, height=150` - Lane style: `swimlane;horizontal=0;startSize=110;fillColor=;html=1;` - Child nodes inside a lane: `parent=""`, `x = 120 + col*180`, `y = 45` (always 45), size 140×60 (or 140×80 for diamonds) - Cross-lane edges: `parent="1"` (not inside a lane) Pick `CANVAS_W = max_col * 180 + 300`. Choose lane colors from `#f5f5f5, #e8f4f8, #fff0e6, #e8f5e9, #fff9e6, #fce4ec` in that order. ```xml ``` Do NOT nest lanes inside a pool. Do NOT vary lane heights. Do NOT compute title-area offset — it is always 110, children start at x=120 to clear it. ### Nested architecture containers (cloud, infra, network topologies) For diagrams with **nested groupings** — VPC → Availability Zone → EC2 instance, Datacenter → Rack → Server, Region → Environment → Service — use nested swimlanes. This is where the AI most often flattens hierarchy that should be nested. Treat each level as a swimlane container. **Rules:** - Every container is a `swimlane` with `startSize=24` (title area at the top). - Child cells set `parent=""` and use coordinates **relative to their parent** (origin 0,0 is the parent's top-left, below the title). - Edges between cells in **different** containers must have `parent="1"` (not a container) — otherwise they render inside the container and get clipped. - For industry-specific icons (AWS/Azure/GCP logos, Cisco equipment, etc.), call `search_shapes` to get the exact `style` string and substitute it into a regular vertex — the container structure stays the same. ```xml ``` ### Cross-functional flowcharts (actor × phase grid, as a table) Cross-functional flowcharts show a process across **two axes at once** — actors (rows) and phases (columns). Use drawio's `table` shape, which auto-arranges cells into a grid via `childLayout=tableLayout`. This is the canonical draw.io pattern and is distinct from plain swimlanes (which only group on one axis). **Structure:** - Outer container: `shape=table;childLayout=tableLayout;startSize=0;collapsible=0;fillColor=none;` - Rows are children of the table: `shape=tableRow;horizontal=0;startSize=0;collapsible=0;` - Cells are children of rows — regular vertices, one per (actor, phase) intersection - Row heights and cell widths are set via `mxGeometry`; they tile automatically - First row = phase headers; first cell of every other row = actor label - Process nodes go INSIDE the appropriate cell (parent = cell id) at coordinates relative to the cell - Cross-cell edges must use `parent="1"` (same rule as containers) ```xml ``` **When to use cross-functional tables vs flat swimlanes:** - Flat swimlanes — one-dimensional (actors only, or phases only). Simpler. Use this when you just need to show who does what in sequence. - Cross-functional table — two-dimensional (actors AND phases). Use this when **both** the actor and the process stage matter, and every step belongs to a specific (actor, phase) cell. **Do NOT** nest swimlanes inside a table row, do NOT set `startSize` on rows or cells (columns tile from `x=0`), and do NOT rely on the AI to produce exact widths that sum to the table width — close-enough totals are fine, the `tableLayout` normalizes them. ## Layers Layers control visibility and z-order. Every cell belongs to exactly one layer. Use layers to manage diagram complexity — viewers can toggle layer visibility to show or hide groups of elements (e.g., "Physical Infrastructure" vs "Logical Network" vs "Security Zones"). Cell `id="0"` is the root and cell `id="1"` is the default layer — both always exist. Additional layers are `mxCell` elements with `parent="0"`: ```xml ``` - A layer is an `mxCell` with `parent="0"` and no `vertex` or `edge` attribute - Assign shapes to a layer by setting `parent` to the layer's id - Later layers render on top of earlier layers (higher z-order) - Add `visible="0"` as an attribute on the layer cell to hide it by default - Use layers when the diagram has distinct conceptual groupings that viewers may want to toggle independently ## Tags Tags are visual filters that let viewers show or hide elements by category. Unlike layers, a single element can have multiple tags, making tags ideal for cross-cutting concerns (e.g., tagging shapes as "critical", "v2", or "backend"). Tags require wrapping `mxCell` in an `