Draw.io Diagrams

---
name: drawio
description: Generate draw.io diagrams as .drawio files, optionally export to PNG/SVG/PDF with embedded XML
allowed-tools: Bash, Write
---

# Draw.io Diagram Skill

Generate draw.io diagrams as native `.drawio` files. Optionally export to PNG, SVG, or PDF with the diagram XML embedded (so the exported file remains editable in draw.io).

## Save Location

All diagrams save to the **active topic folder** when one exists:
- Marketing team context: `{{CONTENT_DIR}}/[TOPIC_SLUG]/`
- If no topic folder exists, save to `{{CONTENT_DIR}}/visuals/`
- Never save to `/tmp/` or the home directory

## How to create a diagram

1. **Generate draw.io XML** in mxGraphModel format for the requested diagram
2. **Write the XML** to a `.drawio` file in the save location using the Write tool
3. **Open the .drawio file** so the user can review it visually in draw.io
4. **Ask the user**: "Does this look right? Approve / Edit / Regenerate?"
5. **Once approved**, export to PNG at **1080x1350** (LinkedIn default) using the draw.io CLI with `--embed-diagram`
6. **Keep both files** - the `.drawio` source AND the exported `.drawio.png`

## DESIGN RULES (NON-NEGOTIABLE)

### Background
- **ALWAYS use a dark grid-lined background.** Set the mxGraphModel attributes: `background="#1a1a1a"` and `grid="1"` and `gridColor="#333333"`
- The grid gives the diagram a professional, technical feel - never skip it

### Color Palette (ONLY these 4 colors)
| Color | Hex | Use for |
|-------|-----|---------|
| **Black** | `#1a1a1a` | Background, dark fills |
| **Orange** | `#FD4F03` | Primary shapes, highlights, H1 background |
| **Green** | `#2ECC40` | Success states, positive flows, confirmations |
| **Red** | `#FF4136` | Error states, warnings, negative flows |

- **White** (`#FFFFFF`) is allowed ONLY for text labels on dark backgrounds
- **No other colors.** No blues, no grays for shapes, no purples. Stick to the 4-color palette.
- Shape strokes: use orange for primary, white for secondary outlines
- Arrows/connectors: white (`#FFFFFF`) stroke so they're visible on dark bg

### H1 Title Bar
- Every diagram MUST have a title bar at the very top
- The title bar is a full-width rectangle with **orange background** (`fillColor=#FD4F03`)
- White bold text (`fontColor=#FFFFFF;fontStyle=1;fontSize=24`)
- This makes the title pop against the dark background
- Width should match the full diagram width

### Centering (CRITICAL)
- **All diagram content MUST be horizontally centered on the canvas.**
- Calculate total content width, then offset x positions so the content block is centered within the target dimensions (1080px wide)
- Center formula: `x_offset = (1080 - content_width) / 2`
- The title bar spans full width, content below it is centered
- Verify centering visually before presenting to user
- Common mistake: elements bunched to the left side. Prevent this by calculating positions from center outward, not from x=0

### Layout
- Use generous spacing between elements (minimum 40px gaps)
- Vertical flow preferred (top to bottom) for process/flow diagrams
- Group related elements visually with consistent spacing
- Ensure no elements overlap or crowd each other

## Choosing the output format

Check the user's request for a format preference. Examples:

- `/drawio create a flowchart` -> `flowchart.drawio` (then PNG on approval)
- `/drawio png flowchart for login` -> `login-flow.drawio.png`
- `/drawio svg: ER diagram` -> `er-diagram.drawio.svg`

**Default behavior**: Always produce the `.drawio` file first for review, then export PNG at 1080x1350 once the user approves.

### Supported export formats

| Format | Embed XML | Notes |
|--------|-----------|-------|
| `png` | Yes (`-e`) | Viewable everywhere, editable in draw.io |
| `svg` | Yes (`-e`) | Scalable, editable in draw.io |
| `pdf` | Yes (`-e`) | Printable, editable in draw.io |
| `jpg` | No | Lossy, no embedded XML support |

PNG, SVG, and PDF all support `--embed-diagram` - the exported file contains the full diagram XML, so opening it in draw.io recovers the editable diagram.

## draw.io CLI

The draw.io desktop app includes a command-line interface for exporting.

### Locating the CLI

Try `drawio` first (works if on PATH), then fall back to the platform-specific path:

- **macOS**: `/Applications/draw.io.app/Contents/MacOS/draw.io`
- **Linux**: `drawio` (typically on PATH via snap/apt/flatpak)
- **Windows**: `"C:\Program Files\draw.io\draw.io.exe"`

Use `which drawio` (or `where drawio` on Windows) to check if it's on PATH before falling back.

### Export command (default PNG at 1080x1350)

```bash
drawio -x -f png -e --width 1080 --height 1350 -b 10 -o <output.drawio.png> <input.drawio>
```

Key flags:
- `-x` / `--export`: export mode
- `-f` / `--format`: output format (png, svg, pdf, jpg)
- `-e` / `--embed-diagram`: embed diagram XML in the output (PNG, SVG, PDF only)
- `-o` / `--output`: output file path
- `-b` / `--border`: border width around diagram (default: 0)
- `--width` / `--height`: fit into specified dimensions (preserves aspect ratio)
- `-s` / `--scale`: scale the diagram size
- `-a` / `--all-pages`: export all pages (PDF only)
- `-p` / `--page-index`: select a specific page (1-based)

### Opening the result

- **macOS**: `open <file>`

## File naming

- Use a descriptive filename based on the diagram content (e.g., `login-flow`, `database-schema`)
- Use lowercase with hyphens for multi-word names
- For export, use double extensions: `name.drawio.png`, `name.drawio.svg`, `name.drawio.pdf` - this signals the file contains embedded diagram XML
- **Keep the .drawio source file** alongside the export for future edits

## XML format

A `.drawio` file is native mxGraphModel XML. Always generate XML directly.

### Basic structure (with dark grid background)

Every diagram must have this structure:

```xml
<mxGraphModel background="#1a1a1a" grid="1" gridSize="10" gridColor="#333333">
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <!-- Title bar: full-width orange rectangle at top -->
    <mxCell id="2" value="DIAGRAM TITLE" style="rounded=0;whiteSpace=wrap;fillColor=#FD4F03;fontColor=#FFFFFF;fontStyle=1;fontSize=24;strokeColor=none;align=center;verticalAlign=middle;" vertex="1" parent="1">
      <mxGeometry x="0" y="0" width="1080" height="70" as="geometry"/>
    </mxCell>
    <!-- Diagram cells go here, centered horizontally -->
  </root>
</mxGraphModel>
```

- Cell `id="0"` is the root layer
- Cell `id="1"` is the default parent layer
- Cell `id="2"` is ALWAYS the orange title bar
- All diagram elements use `parent="1"` unless using multiple layers
- `background="#1a1a1a"` and `grid="1"` are REQUIRED on the mxGraphModel

### Common styles (using the 4-color palette)

**Primary shape (orange stroke):**
```xml
<mxCell id="3" value="Label" style="rounded=1;whiteSpace=wrap;fillColor=#1a1a1a;strokeColor=#FD4F03;fontColor=#FFFFFF;strokeWidth=2;" vertex="1" parent="1">
  <mxGeometry x="430" y="100" width="220" height="60" as="geometry"/>
</mxCell>
```

**Success state (green):**
```xml
<mxCell id="4" value="Success" style="rounded=1;whiteSpace=wrap;fillColor=#2ECC40;strokeColor=#2ECC40;fontColor=#FFFFFF;fontStyle=1;" vertex="1" parent="1">
  <mxGeometry x="430" y="200" width="220" height="60" as="geometry"/>
</mxCell>
```

**Error/warning state (red):**
```xml
<mxCell id="5" value="Error" style="rounded=1;whiteSpace=wrap;fillColor=#FF4136;strokeColor=#FF4136;fontColor=#FFFFFF;fontStyle=1;" vertex="1" parent="1">
  <mxGeometry x="430" y="300" width="220" height="60" as="geometry"/>
</mxCell>
```

**Diamond (decision):**
```xml
<mxCell id="6" value="Condition?" style="rhombus;whiteSpace=wrap;fillColor=#1a1a1a;strokeColor=#FD4F03;fontColor=#FFFFFF;strokeWidth=2;" vertex="1" parent="1">
  <mxGeometry x="430" y="400" width="220" height="120" as="geometry"/>
</mxCell>
```

**Arrow (white on dark bg):**
```xml
<mxCell id="7" value="" style="edgeStyle=orthogonalEdgeStyle;strokeColor=#FFFFFF;fontColor=#FFFFFF;" edge="1" source="3" target="4" parent="1">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>
```

### Useful style properties

| Property | Values | Use for |
|----------|--------|---------|
| `rounded=1` | 0 or 1 | Rounded corners |
| `whiteSpace=wrap` | wrap | Text wrapping |
| `fillColor=#1a1a1a` | Hex color | Dark background fill |
| `strokeColor=#FD4F03` | Hex color | Orange border |
| `fontColor=#FFFFFF` | Hex color | White text |
| `strokeWidth=2` | Number | Thicker borders for visibility |
| `shape=cylinder3` | shape name | Database cylinders |
| `ellipse` | style keyword | Circles/ovals |
| `rhombus` | style keyword | Diamonds |
| `edgeStyle=orthogonalEdgeStyle` | style keyword | Right-angle connectors |
| `dashed=1` | 0 or 1 | Dashed lines |
| `swimlane` | style keyword | Swimlane containers |

## CRITICAL: XML well-formedness

- **NEVER use double hyphens (`--`) inside XML comments.** `--` is illegal inside `<!-- -->` per the XML spec and causes parse errors. Use single hyphens or rephrase.
- Escape special characters in attribute values: `&amp;`, `&lt;`, `&gt;`, `&quot;`
- Always use unique `id` values for each `mxCell`

## Approval and Export Workflow

1. Generate `.drawio` file with dark grid bg, 4-color palette, orange title bar, centered layout
2. Open in draw.io for user review
3. Ask: **"Does this look right? Approve / Edit / Regenerate?"**
4. On approval: export PNG at 1080x1350 with embedded diagram XML
5. Confirm export path to user