drawio-diagram

# drawio-diagram Generate `.drawio` architecture diagrams with a consistent visual style. Always include a legend. Supports export to PNG, SVG, PDF, and self-contained HTML. ## Workflow 1. **Understand the subject** — read source material (repos, docs, README, user description) 2. **Plan the diagram** — identify containers, capabilities, external services, and connections 3. **Generate the `.drawio` file** — use the XML structure and style conventions below 4. **Add a legend** — always include a legend row at the top of the diagram 5. **Export** — offer to export to PNG/SVG/PDF via draw.io CLI, or to self-contained HTML ## XML Structure Every `.drawio` file must follow this structure: ```xml <mxfile host="Electron" version="28.0.6"> <diagram name="Page-1" id="unique-id"> <mxGraphModel dx="1100" dy="760" 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" /> <!-- All diagram cells use parent="1" --> </root> </mxGraphModel> </diagram> </mxfile> ``` For larger diagrams, increase `pageWidth` and `pageHeight` as needed (e.g., `1400x900` or `1600x1000`). ## Element Types and Styles ### Container (systems, layers, groupings) Blue, rounded, bold title top-aligned. ``` rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;verticalAlign=top;fontSize=10; ``` ### Capability (features, components, public) Green, rounded, bold title with description. ``` rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;fontSize=10;verticalAlign=top; ``` ### Existing / External (infrastructure, third-party) Grey, rounded. ``` rounded=1;whiteSpace=wrap;html=1;fillColor=#f5f5f5;fontColor=#333333;strokeColor=#666666;verticalAlign=top;fontSize=10; ``` ### Tech Preview (experimental, private, future) Purple, rounded. ``` rounded=1;whiteSpace=wrap;html=1;fillColor=#e1d5e7;strokeColor=#9673a6;fontSize=10;verticalAlign=top; ``` ### Process Step (automated actions, gates) Orange, sharp corners. ``` rounded=0;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;fontSize=10; ``` ### Use Case (domain applications, verticals) Yellow, italic, pill-shaped. ``` rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;fontSize=10;verticalAlign=middle;fontStyle=2 ``` ### Outcome (key deliverable, result) Dark green, white text. Use sparingly. ``` rounded=0;whiteSpace=wrap;html=1;fillColor=#008a00;strokeColor=#005700;fontColor=#ffffff;fontSize=10; ``` ### Protocol Indicator (interface type) Small circle, 8pt font. ``` ellipse;whiteSpace=wrap;html=1;aspect=fixed;fontSize=8;fontStyle=0 ``` Size: 25x25. ### Annotation (ideas, notes, questions) Sticky note shape, yellow. ``` shape=note;whiteSpace=wrap;html=1;backgroundOutline=1;fontColor=#000000;darkOpacity=0.05;fillColor=#FFF9B2;strokeColor=none;fillStyle=solid;direction=west;gradientDirection=north;gradientColor=#FFF2A1;shadow=1;size=20;pointerEvents=1; ``` ### Region (soft grouping) No fill, dashed border. ``` rounded=0;whiteSpace=wrap;html=1;dashed=1;fillColor=none;strokeColor=#999999; ``` ### Infrastructure Bar Full-width grey bar, typically at bottom. ``` rounded=1;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;fontSize=10; ``` ## HTML Labels Use HTML in `value` attributes for rich text: - Bold title: `<b>Title</b>` - Line break: `<br>` - Small text: `<font style="font-size: 9px;">text</font>` - Combined: `<font><b>Title</b><br>Description</font>` Standard element label pattern: ``` <font><b>Component Name</b><br>Brief description</font> ``` ## Connections Always use orthogonal edges: ``` edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1; ``` Add labels on edges where the relationship needs clarification. ## Legend Every diagram must include a legend row near the top. Use small pill-shaped elements (80x20) showing each element type used in the diagram: ```xml <mxCell id="key-1" value="<span>Capability</span>" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;fontSize=10;verticalAlign=middle;fontStyle=2" vertex="1" parent="1"> <mxGeometry x="20" y="40" width="80" height="20" as="geometry" /> </mxCell> ``` Space legend items 90px apart horizontally. Only include element types actually used in the diagram. ## Export ### draw.io CLI Export ```bash # macOS /Applications/draw.io.app/Contents/MacOS/draw.io -x -f png -e -b 10 -o output.drawio.png input.drawio # Linux drawio -x -f png -e -b 10 -o output.drawio.png input.drawio ``` Formats: `png`, `svg`, `pdf`, `jpg` Key flags: - `-x`: export mode - `-f`: format - `-e`: embed diagram XML in output - `-b 10`: border width - `-t`: transparent background (PNG only) After export, the `.drawio` source can be deleted since the export embeds the XML. ### Self-Contained HTML Export Generate a standalone HTML file that renders the diagram in a browser without draw.io installed: ```html <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <title>DIAGRAM_TITLE</title> <style> body { margin: 0; background: #f5f5f5; display: flex; justify-content: center; align-items: center; min-height: 100vh; } .container { background: white; border-radius: 8px; box-shadow: 0 2px 10px rgba(0,0,0,0.1); overflow: hidden; } </style> </head> <body> <div class="container"> <div class="mxgraph" style="max-width:100%;border:1px solid transparent;" data-mxgraph='{"highlight":"#0000ff","nav":true,"resize":true,"toolbar":"zoom layers lightbox","edit":"_blank","xml":"ESCAPED_XML_HERE"}'></div> </div> <script src="https://viewer.diagrams.net/js/viewer-static.min.js"></script> </body> </html> ``` To create the HTML: 1. Take the complete `<mxGraphModel>...</mxGraphModel>` XML from the `.drawio` file 2. XML-escape it for embedding in the `data-mxgraph` JSON attribute (escape `"`, `<`, `>`, `&`) 3. Replace `ESCAPED_XML_HERE` with the escaped XML 4. Replace `DIAGRAM_TITLE` with the diagram title Open with `open output.html` (macOS) or `xdg-open output.html` (Linux). ## File Naming - Source: `name.drawio` - Exports: `name.drawio.png`, `name.drawio.svg`, `name.drawio.pdf` - HTML: `name.drawio.html` ## Layout Guidelines - Place legend at top - Use containers to group related components - Infrastructure bar at bottom - External services on the right side - Process flows left-to-right - Annotations (sticky notes) in margins - Leave adequate spacing between elements (20-30px minimum) ## Reference See `references/` in this skill directory for: - `demo.drawio` — example output with all element types - `xml-and-export.md` — detailed XML structure and CLI reference