draw.io Diagram Standards

March 27, 2026 · View on GitHub

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:

Identify the diagram type (flowchart / architecture / sequence / ER / UML / network / BPMN)
Select the matching template from .github/skills/draw-io/templates/ and adapt it, or start from the minimal skeleton
Plan the layout on paper before writing XML — define tiers, actors, or entities first
Generate valid mxGraph XML following the rules below
Validate using python .github/skills/draw-io/scripts/validate-drawio.py <file>
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=none;fontSize=18;fontStyle=1;align=center;"

File and Naming Conventions

Extension: .drawio for version-controlled diagrams, .drawio.svg for files embedded in Markdown
Naming: kebab-case — e.g. order-flow.drawio, database-schema.drawio
Location: docs/ or architecture/ alongside the code they document
Multi-page: use one <diagram> element per logical view within the same <mxfile>

Validation Checklist (run before every commit)

<mxCell id="0" /> and <mxCell id="1" parent="0" /> are the first two cells
All cell ids are unique within their diagram
All edge source/target ids resolve to existing vertices
All vertex cells have <mxGeometry as="geometry">
All cells (except id=0) have a valid parent
XML is well-formed — no unclosed tags, no bare &, <, > in attribute values
Semantic color palette used consistently
Title cell present on every page

# Run automated validation
python .github/skills/draw-io/scripts/validate-drawio.py <file.drawio>

Reference Files

File	Use For
`.github/skills/draw-io/SKILL.md`	Full agent workflow, recipes, troubleshooting
`.github/skills/draw-io/references/drawio-xml-schema.md`	Complete mxCell attribute reference
`.github/skills/draw-io/references/style-reference.md`	All style keys, shape names, edge types
`.github/skills/draw-io/references/shape-libraries.md`	Shape library catalog with style strings
`.github/skills/draw-io/templates/`	Ready-to-use `.drawio` templates per diagram type
`.github/skills/draw-io/scripts/validate-drawio.py`	XML structure validator
`.github/skills/draw-io/scripts/add-shape.py`	CLI: add a shape to an existing diagram