draw-io Diagram Skill

A Claude Code skill for creating, editing, and managing draw.io diagrams with professional quality standards.

Purpose

This skill enables AI-assisted creation and maintenance of draw.io architecture diagrams, flowcharts, and technical documentation visuals. It ensures consistent styling, proper layout, and automated PNG conversion for presentations and documentation.

When to Use This Skill

Use this skill when you need to:

• Create or edit .drawio XML diagram files
• Convert diagrams to PNG format with transparent backgrounds
• Adjust element positions and layouts programmatically
• Ensure consistent font families (especially for Quarto slides)
• Work with AWS architecture diagrams using official icons
• Maintain professional diagram quality with accessibility standards
• Debug layout issues or element overlaps

How It Works

The skill provides:

1. Direct XML Editing: Manipulates .drawio files as structured XML
2. Automated Conversion: Converts diagrams to high-resolution PNG via pre-commit hooks or scripts
3. Layout Calculations: Computes proper spacing, alignment, and margins
4. Icon Integration: Searches and integrates official AWS icons
5. Quality Assurance: Applies design principles and accessibility guidelines

Key Features

1. Font Management

Ensures consistent typography across diagrams:

• Sets defaultFontFamily in mxGraphModel
• Applies fontFamily to individual text elements
• Recommended: "Noto Sans JP" for Japanese text support

2. PNG Conversion

Multiple conversion methods:

# Via pre-commit hook (all files)
mise exec -- pre-commit run --all-files

# Specific file via pre-commit
mise exec -- pre-commit run convert-drawio-to-png --files assets/my-diagram.drawio

# Direct script execution
bash ~/.claude/skills/draw-io/scripts/convert-drawio-to-png.sh assets/diagram.drawio

Conversion produces:

• 2x scale (high resolution)
• Transparent background
• PNG format suitable for presentations

3. Layout Adjustment

Programmatic element positioning:

• Calculate element centers: y + (height / 2)
• Align multiple elements by matching center coordinates
• Maintain minimum 30px margins from container boundaries
• Position arrows to avoid label overlaps (20px+ clearance)

4. AWS Icon Integration

Search and integrate official AWS service icons:

python ~/.claude/skills/draw-io/scripts/find_aws_icon.py ec2
python ~/.claude/skills/draw-io/scripts/find_aws_icon.py lambda

Uses latest mxgraph.aws4.* icon set.

5. Design Principles

Enforces professional standards:

• Clarity: Simple, visually clean diagrams
• Consistency: Unified colors, fonts, icon sizes, line thickness
• Accuracy: Precise technical representation
• Accessibility: Sufficient color contrast, pattern usage
• Progressive Disclosure: Staged diagrams for complex systems

6. Quality Checklist

Automated validation ensures:

• No background color (transparent)
• Appropriate font sizes (1.5x standard for readability)
• Arrows on back layer (no overlaps)
• 30px+ margins from container boundaries
• Official AWS service names and latest icons
• Visual verification of PNG output

Usage Examples

Example 1: Create AWS Architecture Diagram

<!-- Set font family -->
<mxGraphModel defaultFontFamily="Noto Sans JP" ...>

  <!-- Background frame with proper margins -->
  <mxCell id="vpc" style="rounded=1;strokeWidth=3;...">
    <mxGeometry x="500" y="20" width="560" height="430" />
  </mxCell>

  <!-- Title with 30px margin from frame top -->
  <mxCell id="title" value="VPC" style="text;fontSize=18;fontFamily=Noto Sans JP;">
    <mxGeometry x="510" y="50" width="540" height="35" />
  </mxCell>

  <!-- Arrow with explicit coordinates -->
  <mxCell id="arrow1" style="edgeStyle=..." edge="1">
    <mxGeometry relative="1" as="geometry">
      <mxPoint x="100" y="200" as="sourcePoint"/>
      <mxPoint x="500" y="200" as="targetPoint"/>
    </mxGeometry>
  </mxCell>

  <!-- Arrow label with offset -->
  <mxCell id="label1" value="API Request" style="edgeLabel;fontSize=14;fontFamily=Noto Sans JP;">
    <mxGeometry relative="1" as="geometry">
      <mxPoint x="0" y="-20" as="offset"/>
    </mxGeometry>
  </mxCell>
</mxGraphModel>

Example 2: Convert Diagram to PNG

# Edit the diagram
vim architecture.drawio

# Convert to PNG (via pre-commit hook)
mise exec -- pre-commit run convert-drawio-to-png --files architecture.drawio

# Result: architecture.drawio.png (2x resolution, transparent)

Example 3: Find AWS Icon

# Search for EC2 icon
python ~/.claude/skills/draw-io/scripts/find_aws_icon.py ec2

# Output: mxgraph.aws4.compute.ec2_instance

Example 4: Progressive Disclosure Diagram Set

For complex systems, create staged diagrams:

1. Context Diagram: External perspective (users, external systems)
2. System Diagram: Main components (services, databases)
3. Component Diagram: Technical details (APIs, queues, caches)
4. Deployment Diagram: Infrastructure (VPCs, regions, availability zones)
5. Data Flow Diagram: Data transformations and flows
6. Sequence Diagram: Time-series interactions

Best Practices

Text Width Calculation

Japanese text requires 30-40px per character:

<!-- For 10-character text: 300-400px width -->
<mxGeometry x="140" y="60" width="400" height="40" />

Arrow Layering

Always place arrows immediately after title in XML:

<mxCell id="title" value="..." .../>
<mxCell id="arrow1" style="edgeStyle=..." .../> <!-- Back layer -->
<mxCell id="box1" .../> <!-- Front layer -->

Container Margins

Ensure sufficient spacing inside grouping boxes:

Frame: y=20, height=400 → range 20-420
Element top: y ≥ 50 (30px margin)
Element bottom: y ≤ 390 (30px margin)

Transparent Backgrounds

Remove background color for theme adaptability:

<!-- Remove this -->
<mxGraphModel background="#ffffff" ...>

<!-- Use this -->
<mxGraphModel page="0" ...>

File Structure

~/.claude/skills/draw-io/
├── SKILL.md                          # This documentation
├── README.md                         # User-facing guide
├── scripts/
│   ├── convert-drawio-to-png.sh     # PNG conversion script
│   └── find_aws_icon.py             # AWS icon search utility
└── references/
    ├── layout-guidelines.md         # Detailed layout rules
    └── aws-icons.md                 # AWS icon catalog

Integration with Presentations

For reveal.js slides (Quarto), add to YAML header:

---
title: "Your Presentation"
format:
  revealjs:
    auto-stretch: false
---

This ensures correct image sizing on mobile devices.

Quality Assurance Checklist

Before finalizing any diagram:

• No background color set (page="0")
• Font size appropriate (18px+ for readability)
• Arrows placed at back layer
• Arrows not overlapping labels (verified in PNG)
• Arrow endpoints 20px+ from labels
• Arrows not penetrating boxes/icons
• Internal elements have 30px+ margins from frames
• AWS service names are official/correct
• AWS icons use latest version (mxgraph.aws4.*)
• No unnecessary decorative elements
• PNG conversion visually verified

References

• Layout Guidelines - Detailed spacing and alignment rules
• AWS Icons - Complete AWS icon catalog
• draw.io Documentation - Official draw.io reference

Skill Metadata

• Name: draw-io
• Type: Diagram creation and editing
• Input: .drawio XML files
• Output: .drawio.png high-resolution images
• Dependencies: drawio CLI, Python 3.x, pre-commit hooks