dwmkerr/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:

<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:

<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

# 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:

<!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