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:

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: Title
• Line break: ``
• Small text: text
• Combined: TitleDescription

Standard element label pattern:

Component NameBrief description

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:

Capability" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;fontSize=10;verticalAlign=middle;fontStyle=2" vertex="1" parent="1">
  

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:

  
  DIAGRAM_TITLE
  
    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; }
  

  
    
  
  

To create the HTML:

1. Take the complete ... 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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dwmkerr
• Source: dwmkerr/claude-toolkit
• License: MIT
• Homepage: https://www.skills.sh/dwmkerr/claude-toolkit

Install and usage instructions live in the source repository linked above.