xml-generation

What this skill does

# draw.io XML Generation Reference

## XML Document Structure

### Full Format (mxfile wrapper)

```xml
<?xml version="1.0" encoding="UTF-8"?>
<mxfile host="app.diagrams.net" modified="2026-03-14T00:00:00.000Z"
        agent="Claude" version="24.0.0" type="device">
  <diagram id="page-1" name="Page 1">
    <mxGraphModel dx="1422" dy="762" grid="1" gridSize="10"
                  guides="1" tooltips="1" connect="1" arrows="1"
                  fold="1" page="1" pageScale="1"
                  pageWidth="1169" pageHeight="827"
                  math="0" shadow="0">
      <root>
        <mxCell id="0"/>
        <mxCell id="1" parent="0"/>
        <!-- diagram content here -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>
```

### Simplified Format (IMPORT ONLY — do NOT use for .drawio files)

The `mxGraphModel`-only format works for clipboard import but **causes blank files**
when saved directly as `.drawio`. The draw.io desktop app and web editor both expect
the full `<mxfile>` wrapper to render the diagram. Always use the full format above.

```xml
<!-- DO NOT save this as a .drawio file — it will appear blank -->
<mxGraphModel>
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <!-- only works for import/paste, not for .drawio files -->
  </root>
</mxGraphModel>
```

### mxGraphModel Attributes

| Attribute | Default | Description |
|-----------|---------|-------------|
| `dx` | 0 | Horizontal scroll offset |
| `dy` | 0 | Vertical scroll offset |
| `grid` | 1 | Show grid (0/1) |
| `gridSize` | 10 | Grid spacing in px |
| `guides` | 1 | Enable alignment guides |
| `tooltips` | 1 | Show tooltips |
| `connect` | 1 | Enable connection points |
| `arrows` | 1 | Show arrows on edges |
| `fold` | 1 | Enable container folding |
| `page` | 1 | Show page boundaries |
| `pageScale` | 1 | Page zoom scale |
| `pageWidth` | 1169 | Page width (A4 landscape) |
| `pageHeight` | 827 | Page height (A4 landscape) |
| `math` | 0 | Enable LaTeX math rendering |
| `shadow` | 0 | Default shadow on shapes |
| `background` | `none` | Background color — **always use `none` (transparent)** for clean embedding |

**IMPORTANT**: Always set `background="none"` on the `<mxGraphModel>` element. Transparent backgrounds ensure diagrams embed cleanly in any context (dark mode, light mode, wiki pages, PRs). Never use a solid white background unless explicitly requested.

## Mandatory Structural Cells

Every diagram MUST begin with these two cells. They are never rendered but form the cell hierarchy root.

```xml
<mxCell id="0"/>                    <!-- Root cell (invisible) -->
<mxCell id="1" parent="0"/>         <!-- Default layer -->
```

- `id="0"` is the absolute root. It has no parent.
- `id="1"` is the default layer. All visible shapes/edges use `parent="1"` unless placed on a custom layer.
- Omitting either cell causes diagram corruption.

## Vertex Cells (Shapes)

Vertices represent boxes, circles, and all other shapes. They require `vertex="1"` and an `mxGeometry` child.

```xml
<mxCell id="2" value="My Shape" style="rounded=1;whiteSpace=wrap;html=1;"
        vertex="1" parent="1">
  <mxGeometry x="100" y="50" width="120" height="60" as="geometry"/>
</mxCell>
```

### Vertex Attributes

| Attribute | Required | Description |
|-----------|----------|-------------|
| `id` | Yes | Unique identifier (string) |
| `value` | No | Label text (plain or HTML) |
| `style` | No | Semicolon-delimited style string |
| `vertex` | Yes | Must be `"1"` |
| `parent` | Yes | Parent cell ID (usually `"1"`) |
| `connectable` | No | `"0"` to disable connections |

### mxGeometry for Vertices

```xml
<mxGeometry x="100" y="50" width="120" height="60" as="geometry"/>
```

| Attribute | Description |
|-----------|-------------|
| `x` | Left edge position (px from canvas origin) |
| `y` | Top edge position (px from canvas origin) |
| `width` | Shape width in px |
| `height` | Shape height in px |
| `as` | Must be `"geometry"` |
| `relative` | `"1"` for relative positioning inside parent |

## Edge Cells (Connectors)

Edges connect vertices. They require `edge="1"` and typically `source`/`target` attributes.

```xml
<mxCell id="3" value="connects to" style="edgeStyle=orthogonalEdgeStyle;"
        edge="1" source="2" target="4" parent="1">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>
```

### Edge Attributes

| Attribute | Required | Description |
|-----------|----------|-------------|
| `id` | Yes | Unique identifier |
| `value` | No | Edge label |
| `style` | No | Style string |
| `edge` | Yes | Must be `"1"` |
| `source` | No | Source vertex ID |
| `target` | No | Target vertex ID |
| `parent` | Yes | Parent cell ID |

### mxGeometry for Edges

Edge geometry uses `relative="1"` and may contain waypoints:

```xml
<mxGeometry relative="1" as="geometry">
  <Array as="points">
    <mxPoint x="200" y="150"/>
    <mxPoint x="300" y="150"/>
  </Array>
  <mxPoint x="100" y="100" as="sourcePoint"/>
  <mxPoint x="400" y="200" as="targetPoint"/>
</mxGeometry>
```

- `sourcePoint` / `targetPoint`: fallback when source/target cells are not set.
- `Array as="points"`: intermediate waypoints for routing.

### Edge Labels

Position labels along edge using `mxGeometry` inside a child cell:

```xml
<mxCell id="label1" value="0..*" style="edgeLabel;align=left;" vertex="1"
        connectable="0" parent="3">
  <mxGeometry x="-0.5" y="0" relative="1" as="geometry">
    <mxPoint x="-10" y="-10" as="offset"/>
  </mxGeometry>
</mxCell>
```

- `x` in [-1, 1]: position along edge (-1=source, 0=middle, 1=target).
- `y`: perpendicular offset.

## Style String Format

Styles are semicolon-separated `key=value` pairs. Order does not matter. A trailing semicolon is conventional.

```
rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=14;
```

Named styles can appear as the first token without `=`:

```
shape=hexagon;perimeter=hexagonPerimeter2;size=0.25;
```

### Fill Properties

| Property | Values | Description |
|----------|--------|-------------|
| `fillColor` | `#hex`, `none` | Shape fill color |
| `gradientColor` | `#hex`, `none` | Gradient end color |
| `gradientDirection` | `south`, `north`, `east`, `west` | Gradient direction |
| `opacity` | 0-100 | Overall opacity |
| `fillOpacity` | 0-100 | Fill-only opacity |
| `glass` | 0/1 | Glass/gloss effect |
| `shadow` | 0/1 | Drop shadow |
| `swimlaneFillColor` | `#hex` | Swimlane body fill |

### Stroke Properties

| Property | Values | Description |
|----------|--------|-------------|
| `strokeColor` | `#hex`, `none` | Border/line color |
| `strokeWidth` | number | Border width in px |
| `dashed` | 0/1 | Dashed line |
| `dashPattern` | string | Dash pattern (e.g., `"8 4"`) |
| `strokeOpacity` | 0-100 | Stroke-only opacity |
| `fixDash` | 0/1 | Keep dash pattern on zoom |

### Shape Properties

| Property | Values | Description |
|----------|--------|-------------|
| `shape` | shape name | Shape type (see Shape Types below) |
| `rounded` | 0/1 | Round corners on rectangles |
| `arcSize` | number | Corner radius (0-50) |
| `perimeter` | perimeter name | Connection point calculation |
| `aspect` | `fixed` | Lock aspect ratio |
| `direction` | `south`, `north`, `east`, `west` | Shape rotation direction |
| `rotation` | degrees | Rotation angle |
| `flipH` | 0/1 | Flip horizontal |
| `flipV` | 0/1 | Flip vertical |
| `size` | number | Shape-specific size parameter |
| `imageWidth`, `imageHeight` | number | Embedded image dimensions |
| `image` | URL | Image source |

### Text Properties

| Property | Values | Description |
|----------|--------|-------------|
| `fontSize` | number | Font size in pt |
| `fontFamily` | string | Font name (e.g., `"Helvetica"`) |
| `fontColor` | `#hex` | Text color |
| `fontStyle` | bitmask | 0=normal, 1=bold, 2=italic, 4=underline (combine with +) |
| `align` | `left`, `center`, `right` | Horizontal text alignment |
| `verticalAlign` | `top`, `middle`, `bottom` | Vertical text alignment |
|