Draw-Io

# draw.io Diagram Standards

> **Skill**: Load `.github/skills/draw-io/SKILL.md` for full workflow, XML recipes, and troubleshooting before generating or editing any `.drawio` file.

---

Required Workflow

Follow these steps for every draw.io task:

1. **Identify** the diagram type (flowchart / architecture / sequence / ER / UML / network / BPMN)

2. **Select** the matching template from `.github/skills/draw-io/templates/` and adapt it, or start from the minimal skeleton

3. **Plan** the layout on paper before writing XML — define tiers, actors, or entities first

4. **Generate** valid mxGraph XML following the rules below

5. **Validate** using `python .github/skills/draw-io/scripts/validate-drawio.py <file>`

6. **Confirm** the file renders by opening it in VS Code with the draw.io extension (`hediet.vscode-drawio`)

---

XML Structure Rules (Non-Negotiable)

<!-- Set modified to the current ISO 8601 timestamp when generating a new file -->
<mxfile host="Electron" modified="" version="26.0.0">
  <diagram id="unique-id" name="Page Name">
    <mxGraphModel ...>
      <root>
        <mxCell id="0" />                          <!-- REQUIRED: always first -->
        <mxCell id="1" parent="0" />               <!-- REQUIRED: always second -->
        <!-- all other cells go here -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

- `id="0"` and `id="1"` **must** be present and must be the first two cells — no exceptions

- Every cell `id` must be **unique** within the diagram

- Every vertex (`vertex="1"`) must have a child `<mxGeometry x y width height as="geometry">`

- Every edge (`edge="1"`) must have `source`/`target` pointing to existing vertex ids — **exception**: floating edges (sequence diagram lifelines) use `<mxPoint as="sourcePoint">` and `<mxPoint as="targetPoint">` inside `<mxGeometry>` instead of `source`/`target` attributes

- Every cell except id=0 must have `parent` pointing to an existing id

- Children of a container (swimlane) use **coordinates relative to their parent**, not the canvas

---

Mandatory Style Conventions

Semantic Color Palette — Use consistently across the project

| Role | fillColor | strokeColor |

|---|---|---|

| Primary / Info (default) | `#dae8fc` | `#6c8ebf` |

| Success / Start / Positive | `#d5e8d4` | `#82b366` |

| Warning / Decision | `#fff2cc` | `#d6b656` |

| Error / End / Danger | `#f8cecc` | `#b85450` |

| Neutral / Interface | `#f5f5f5` | `#666666` |

| External / Partner | `#e1d5e7` | `#9673a6` |

Always include on vertex shapes

whiteSpace=wrap;html=1;

Use `html=1` whenever a label contains HTML tags (`<b>`, `<i>`, `<br>`)

Standard connectors

edgeStyle=orthogonalEdgeStyle;html=1;

---

Diagram-Type Quick Reference

| Type | Container | Key shapes | Connector style |

|---|---|---|---|

| Flowchart | None | `ellipse` (start/end), `rounded=1` (process), `rhombus` (decision) | `orthogonalEdgeStyle` |

| Architecture | `swimlane` per tier | `rounded=1` services, cloud/DB shapes | `orthogonalEdgeStyle` with labels |

| Sequence | None | `mxgraph.uml.actor`, dashed lifeline edges | `endArrow=block` (sync), `endArrow=open;dashed=1` (return) |

| ER Diagram | `shape=table;childLayout=tableLayout` | `shape=tableRow`, `shape=partialRectangle` | `entityRelationEdgeStyle;endArrow=ERmany;startArrow=ERone` |

| UML Class | `swimlane` per class | text rows for attributes/methods | `endArrow=block;endFill=0` (inherit), `dashed=1` (realize) |

---

Layout Best Practices

- Align all coordinates to the **10 px grid** (values divisible by 10)

- **Horizontal**: 40–60 px gap between same-row shapes

- **Vertical**: 80–120 px gap between tier rows

- Standard shape size: `120 × 60` px (process), `200 × 100` px (decision diamond)

- Default canvas: A4 landscape `1169 × 827` px

- Maximum **40 cells per page** — split into multiple pages for larger diagrams

- Add a **title text cell** at top of every page:

```

style="text;strokeColor=none;fillColor=non