draw-io-diagram-generator

name draw-io-diagram-generator description Use when creating, editing, or generating draw.io diagram files (.drawio, .drawio.svg, .drawio.png). Covers mxGraph XML authoring, shape libraries, style strings, flowcharts, system architecture, sequence diagrams, ER diagrams, UML class diagrams, network topology, layout strategy, the hediet.vscode-drawio VS Code extension, and the full agent workflow from request to a ready-to-open file. Draw.io Diagram Generator This skill enables you to generate, edit, and validate draw.io ( .drawio ) diagram files with correct mxGraph XML structure. All generated files open immediately in the Draw.io VS Code extension ( hediet.vscode-drawio ) without any manual fixes required. You can also open the files in the draw.io web app or desktop app if you prefer. 1. When to Use This Skill Trigger phrases (load this skill when you see these) "create a diagram", "draw a flowchart", "generate an architecture diagram" "design a sequence diagram", "make a UML class diagram", "build an ER diagram" "add a .drawio file", "update the diagram", "visualise the flow" "document the architecture", "show the data model", "diagram the service interactions" Any request to produce or modify a .drawio , .drawio.svg , or .drawio.png file Supported diagram types Diagram Type Template Available Description Flowchart assets/templates/flowchart.drawio Process flows with decisions and branches System Architecture assets/templates/architecture.drawio Multi-tier / layered service architecture Sequence Diagram assets/templates/sequence.drawio Actor lifelines and timed message flows ER Diagram assets/templates/er-diagram.drawio Database tables with relationships UML Class Diagram assets/templates/uml-class.drawio Classes, interfaces, enums, relationships Network Topology (use shape library) Routers, servers, firewalls, subnets BPMN Workflow (use shape library) Business process events, tasks, gateways Mind Map (manual) Central topic with radiating branches 2. Prerequisites If running with VS Code integration enabled, Install the drawio extension: draw.io VS Code extension — hediet.vscode-drawio (extension id). Install with: ext install hediet.vscode-drawio Supported file extensions : .drawio , .drawio.svg , .drawio.png Python 3.8+ (optional) — for the validation and shape-insertion scripts in scripts/ 3. Step-by-Step Agent Workflow Follow these steps in order for every diagram generation task. Step 1 — Understand the Request Ask or infer: Diagram type — What kind of diagram? (flowchart, architecture, UML, ER, sequence, network...) Entities / actors — What are the main components, actors, classes, or tables? Relationships — How are they connected? What direction? What cardinality? Output path — Where should the .drawio file be saved? Existing file — Are we creating new or editing an existing file? If the request is ambiguous, infer the most sensible diagram type from context (e.g. "show the tables" → ER diagram, "show how the API call flows" → sequence diagram). Step 2 — Select a Template or Start Fresh Use a template when the diagram type matches one in assets/templates/ . Copy the template structure and replace placeholder values. Start fresh for novel layouts. Begin with the minimal valid skeleton: <!-- Set modified="" to the current ISO 8601 timestamp when generating a new file --> < mxfile host = "Electron" modified = "" version = "26.0.0" > < 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" /> <!-- Your cells go here --> </ root > </ mxGraphModel > </ diagram > </ mxfile > Rule : ids 0 and 1 are ALWAYS required and must be the first two cells. Never reuse them. Step 3 — Plan the Layout Before generating XML, sketch the logical placement: Organise into rows or tiers (use swimlanes for layers) Horizontal spacing : 40–60px between same-row shapes Vertical spacing : 80–120px between tier rows Standard shape size: 120x60 px for process boxes, 160x80 px for swimlanes Default canvas: A4 landscape = 1169 x 827 px Step 4 — Generate the mxGraph XML Vertex cell (every shape): < mxCell id = "unique-id" value = "Label" style = "rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex = "1" parent = "1" > < mxGeometry x = "100" y = "100" width = "120" height = "60" as = "geometry" /> </ mxCell > Edge cell (every connector): < mxCell id = "edge-id" value = "Label (optional)" style = "edgeStyle=orthogonalEdgeStyle;html=1;" edge = "1" source = "source-id" target = "target-id" parent = "1" > < mxGeometry relative = "1" as = "geometry" /> </ mxCell > Critical rules : Every cell id must be globally unique within the file Every vertex must have an mxGeometry child with x , y , width , height , as="geometry" Every edge must have source and target matching existing vertex ids — exception : floating edges (e.g. sequence diagram lifelines) use sourcePoint / targetPoint inside <mxGeometry> instead; see §4 Sequence Diagram Every cell's parent must reference an existing cell id Use html=1 in style when the label contains HTML ( <b> , <i> , <br> ) Escape XML special characters in labels: & => &amp; , < => &lt; , > => &gt; Step 5 — Apply Correct Styles Use the standard semantic color palette for consistency: Purpose fillColor strokeColor Primary / Info #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 <filename> 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) <!-- Start node --> < 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 > <!-- Process --> < 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 > <!-- Decision --> < 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 > <!-- Arrow: start to p1 --> < 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. <!-- Tier 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 > <!-- Service inside tier (parent="tier1", coords are relative to tier) --> < 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: <!-- Actor (stick figure) --> < 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 > <!-- Service box --> < 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 > <!-- Lifeline — floating edge: uses sourcePoint/targetPoint, NOT source/target attributes --> < 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 > <!-- Activation box (thin rectangle on lifeline) --> < mxCell id = "actA1" value = "" style = "fillColor=#dae8fc;strokeColor=#6c8ebf;"