dae8fc

6c8ebf

Success / Start

d5e8d4

82b366

Warning / Decision

fff2cc

d6b656

Error / End

f8cecc

b85450

Neutral

f5f5f5

666666

External / Partner

e1d5e7

9673a6

Common style strings by diagram type:

Rounded process box (flowchart)

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

Decision diamond

rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;

Start/End terminal

ellipse;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;

Database cylinder

shape=mxgraph.flowchart.database;whiteSpace=wrap;html=1;fillColor=#f8cecc;strokeColor=#b85450;

Swimlane container (tier)

swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;fontStyle=1;

UML class box

swimlane;fontStyle=1;align=center;startSize=40;fillColor=#dae8fc;strokeColor=#6c8ebf;

Interface / stereotype box

swimlane;fontStyle=3;align=center;startSize=40;fillColor=#f5f5f5;strokeColor=#666666;

ER table container

shape=table;startSize=30;container=1;collapsible=1;childLayout=tableLayout;

Orthogonal connector

edgeStyle=orthogonalEdgeStyle;html=1;

ER relationship (crow's foot)

edgeStyle=entityRelationEdgeStyle;html=1;endArrow=ERmany;startArrow=ERone; See references/style-reference.md for the complete style key catalog and references/shape-libraries.md for all shape library names. Step 6 — Save and Validate Write the file to the requested path with .drawio extension Run the validator (optional but recommended): python .github/skills/draw-io-diagram-generator/scripts/validate-drawio.py < path-to-file.drawio

Tell the user how to open the file: "Open in VS Code — it will render automatically with the draw.io extension. You can use draw.io's web app or desktop app as well if you prefer." Provide a brief description of what is in the diagram so the user knows what to expect. 4. Diagram-Type Recipes Flowchart Key elements: Start (ellipse) => Process (rounded rectangle) => Decision (diamond) => End (ellipse)

< mxCell id = " start " value = " Start " style = " ellipse;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366; " vertex = " 1 " parent = " 1 "

< mxGeometry x = " 500 " y = " 80 " width = " 120 " height = " 60 " as = " geometry " /> </ mxCell

< mxCell id = " p1 " value = " Process Step " style = " rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf; " vertex = " 1 " parent = " 1 "

< mxGeometry x = " 500 " y = " 200 " width = " 120 " height = " 60 " as = " geometry " /> </ mxCell

< mxCell id = " d1 " value = " Condition? " style = " rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656; " vertex = " 1 " parent = " 1 "

< mxGeometry x = " 460 " y = " 320 " width = " 200 " height = " 100 " as = " geometry " /> </ mxCell

< mxCell id = " e1 " value = " " style = " edgeStyle=orthogonalEdgeStyle;html=1; " edge = " 1 " source = " start " target = " p1 " parent = " 1 "

< mxGeometry relative = " 1 " as = " geometry " /> </ mxCell

Architecture Diagram (3-tier) Use swimlane containers for each tier. All service boxes are children of their swimlane.

< mxCell id = " tier1 " value = " Client Layer " style = " swimlane;startSize=30;fillColor=#dae8fc;strokeColor=#6c8ebf;fontStyle=1; " vertex = " 1 " parent = " 1 "

< mxGeometry x = " 60 " y = " 100 " width = " 1050 " height = " 130 " as = " geometry " /> </ mxCell

< mxCell id = " webapp " value = " Web App " style = " rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf; " vertex = " 1 " parent = " tier1 "

< mxGeometry x = " 80 " y = " 40 " width = " 120 " height = " 60 " as = " geometry " /> </ mxCell

Connectors between tiers use absolute coordinates with parent="1" . Sequence Diagram Key elements: Actors (top), Lifelines (dashed vertical lines), Activation boxes, Message arrows. Lifelines: edge="1" with endArrow=none and dashed=1 , no source/target — use sourcePoint / targetPoint in geometry Synchronous message: endArrow=block;endFill=1 Return message: endArrow=open;endFill=0;dashed=1 Self-call: loop the edge via two Array points to the right and back Minimal XML snippet:

< mxCell id = " actorA " value = " Client " style = " shape=mxgraph.uml.actor;pointerEvents=1;dashed=0;whiteSpace=wrap;html=1;aspect=fixed; " vertex = " 1 " parent = " 1 "

< mxGeometry x = " 110 " y = " 80 " width = " 60 " height = " 80 " as = " geometry " /> </ mxCell

< mxCell id = " actorB " value = " API Server " style = " rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656; " vertex = " 1 " parent = " 1 "

< mxGeometry x = " 480 " y = " 100 " width = " 160 " height = " 60 " as = " geometry " /> </ mxCell

< mxCell id = " lifA " value = " " style = " edgeStyle=none;dashed=1;endArrow=none; " edge = " 1 " parent = " 1 "

< mxGeometry relative = " 1 " as = " geometry "

< mxPoint x = " 140 " y = " 160 " as = " sourcePoint " /> < mxPoint x = " 140 " y = " 700 " as = " targetPoint " /> </ mxGeometry

</ mxCell

< mxCell id = " actA1 " value = " " style = " fillColor=#dae8fc;strokeColor=#6c8ebf; " vertex = " 1 " parent = " 1 "

< mxGeometry x = " 130 " y = " 220 " width = " 20 " height = " 180 " as = " geometry " /> </ mxCell

< mxCell id = " msg1 " value = " POST /orders " style = " edgeStyle=elbowEdgeStyle;elbow=vertical;html=1;endArrow=block;endFill=1; " edge = " 1 " source = " actA1 " target = " actorB " parent = " 1 "

< mxGeometry relative = " 1 " as = " geometry " /> </ mxCell

< mxCell id = " msg2 " value = " 201 Created " style = " edgeStyle=elbowEdgeStyle;elbow=vertical;dashed=1;html=1;endArrow=open;endFill=0; " edge = " 1 " source = " actorB " target = " actA1 " parent = " 1 "

< mxGeometry relative = " 1 " as = " geometry " /> </ mxCell

Note: Lifelines are floating edges that use sourcePoint / targetPoint in instead of source / target attributes. This is the standard draw.io pattern for sequence diagrams. ER Diagram Use shape=table containers with childLayout=tableLayout . Rows are shape=tableRow cells with portConstraint=eastwest . Columns inside each row are shape=partialRectangle . Relationship arrows use edgeStyle=entityRelationEdgeStyle : One-to-One: startArrow=ERone;endArrow=ERone One-to-Many: startArrow=ERone;endArrow=ERmany Many-to-Many: startArrow=ERmany;endArrow=ERmany Mandatory: ERmandOne , Optional: ERzeroToOne UML Class Diagram Class boxes are swimlane containers. Attributes and methods are plain text cells. Dividers are zero-height swimlane children. Arrow styles by relationship type: Relationship Style String Inheritance (extends) edgeStyle=orthogonalEdgeStyle;html=1;endArrow=block;endFill=0; Realization (implements) edgeStyle=orthogonalEdgeStyle;dashed=1;html=1;endArrow=block;endFill=0; Composition edgeStyle=orthogonalEdgeStyle;html=1;startArrow=diamond;startFill=1;endArrow=none; Aggregation edgeStyle=orthogonalEdgeStyle;html=1;startArrow=diamond;startFill=0;endArrow=none; Dependency edgeStyle=orthogonalEdgeStyle;dashed=1;html=1;endArrow=open;endFill=0; Association edgeStyle=orthogonalEdgeStyle;html=1;endArrow=open;endFill=0; 5. Multi-Page Diagrams Add multiple elements for complex systems: < mxfile host = " Electron " version = " 26.0.0 "

< diagram id = " overview " name = " Overview "

</ diagram

< diagram id = " detail " name = " Detail View "

</ diagram

</ mxfile

Each page has its own independent cell id namespace. The same id value can appear in different pages without conflict. 6. Editing Existing Diagrams When modifying an existing .drawio file: Read the file first to understand existing cell ids, positions, and parent hierarchy Identify the target diagram page — by index or name attribute Assign new unique ids that do not collide with existing ids Respect the container hierarchy — children of a swimlane use coordinates relative to their parent Verify edges — after repositioning nodes, confirm edge source/target ids remain valid Use scripts/add-shape.py to safely add a single shape without editing raw XML: python .github/skills/draw-io-diagram-generator/scripts/add-shape.py docs/arch.drawio "New Service" 700 380 7. Best Practices Layout Align shapes to the 10px grid (all coordinates divisible by 10) Group related shapes inside swimlane containers One diagram topic per page; use multi-page files for complex systems Aim for 40 or fewer cells per page for readability Labels Add a title text cell ( text;strokeColor=none;fillColor=none;fontSize=18;fontStyle=1 ) at top of every page Always set whiteSpace=wrap;html=1 on vertex shapes Keep labels concise — 3 words or fewer per shape where possible Style consistency Use the semantic color palette from Section 3 Step 5 consistently across a project Prefer edgeStyle=orthogonalEdgeStyle for clean right-angle connectors Do not inline arbitrary HTML in labels unless necessary File naming Use kebab-case: order-service-flow.drawio , database-schema.drawio Place diagrams alongside the code they document: docs/ or architecture/ 8. Troubleshooting Problem Likely Cause Fix File opens blank in VS Code Missing id=0 or id=1 cell Add both root cells before any other cells Shape at wrong position Child inside container — coords are relative Check parent ; adjust x/y relative to container Edge not visible source or target id does not match any vertex Verify both ids exist exactly as written Diagram shows "Compressed" mxGraphModel is base64-encoded Open in draw.io web, File > Export > XML (uncompressed) Shape style not rendering Typo in shape= name Check references/shape-libraries.md for exact style string Label shows escaped HTML html=0 on a cell with HTML label Add html=1; to the cell style Container children overlap container edge Container height too small Increase container height in mxGeometry 9. Validation Checklist Before delivering any generated .drawio file, verify: File starts with root element Every has a non-empty id attribute is the first cell in every diagram is the second cell in every diagram All cell id values are unique within each diagram Every vertex cell has vertex="1" and a child Every edge cell has edge="1" and either: (a) source / target pointing to existing vertex ids, or (b) and in its (floating edge — used for sequence diagram lifelines) Every cell (except id=0) has a parent pointing to an existing id html=1 is in the style for any label containing HTML tags XML is well-formed (no unclosed tags, no unescaped & , < ,

in attribute values) A title label cell exists at the top of each page Run the automated validator: python .github/skills/draw-io-diagram-generator/scripts/validate-drawio.py < file.drawio

1. Output Format When delivering a diagram, always provide: The .drawio file written to the requested path A one-sentence summary of what the diagram shows How to open it : "Open in VS Code — the draw.io extension will render it automatically. Or you can open it in the draw.io web app or desktop app if you prefer." How to edit it (if the user is likely to customise): "Click any shape to select it. Double-click to edit the label. Drag to reposition." Validation status — whether the validator script was run and passed
2. References All companion files are in .github/skills/draw-io-diagram-generator/ : File Contents references/drawio-xml-schema.md Complete mxfile / mxGraphModel / mxCell attribute reference, coordinate system, reserved cells, validation rules references/style-reference.md All style keys with allowed values, vertex and edge style keys, shape catalog, semantic color palette references/shape-libraries.md All shape library categories (General, Flowchart, UML, ER, Network, BPMN, Mockup, K8s) with style strings assets/templates/flowchart.drawio Ready-to-use flowchart template assets/templates/architecture.drawio 4-tier system architecture template assets/templates/sequence.drawio 3-actor sequence diagram template assets/templates/er-diagram.drawio 3-table ER diagram with crow's foot relationships assets/templates/uml-class.drawio Interface + 2 classes + enum with relationship arrows scripts/validate-drawio.py Python script to validate XML structure of any .drawio file scripts/add-shape.py Python CLI to add a new shape to an existing diagram scripts/README.md How to use the scripts with examples