Draw Io

draw.io Diagram Skill

1. Basic Rules

• Edit only .drawio files
• Do not directly edit .drawio.png files
• Use auto-generated .drawio.png by pre-commit hook in slides

2. Font Settings

For diagrams used in Quarto slides, specify defaultFontFamily in mxGraphModel tag:

<mxGraphModel defaultFontFamily="Noto Sans JP" ...>

Also explicitly specify fontFamily in each text element's style attribute:

style="text;html=1;fontSize=27;fontFamily=Noto Sans JP;"

3. Conversion Commands

See conversion script at scripts/convert-drawio-to-png.sh.

# Convert all .drawio files
mise exec -- pre-commit run --all-files

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

# Run script directly (using skill's script)
bash ~/.claude/skills/draw-io/scripts/convert-drawio-to-png.sh assets/diagram1.drawio

Internal command used:

drawio -x -f png -s 2 -t -o output.drawio.png input.drawio

4. Layout Adjustment

4.1. Coordinate Adjustment Steps

1. Open .drawio file in text editor (plain XML format) 2. Find mxCell for element to adjust (search by value attribute for text) 3. Adjust coordinates in mxGeometry tag

• x: Position from left
• y: Position from top
• width: Width
• height: Height

4. Run conversion and verify

4.2. Coordinate Calculation

• Element center coordinate = y + (height / 2)
• To align multiple elements, calculate and match center coordinates

5. Design Principles

5.1. Basic Principles

• Clarity: Create simple, visually clean diagrams
• Consistency: Unify colors, fonts, icon sizes, line thickness
• Accuracy: Do not sacrifice accuracy for simplification

5.2. Element Rules

• Label all elements
• Use arrows to indicate direction

(prefer 2 unidirectional arrows over bidirectional)

• Use latest official icons
• Add legend to explain custom symbols

5.3. Accessibility

• Ensure sufficient color contrast
• Use patterns in addition to colors

5.4. Progressive Disclosure

Separate complex systems into staged diagrams:

5.5. Metadata

Include title, description, last updated, author, and version in diagrams.

6. Best Practices

6.1. Background Color

• Remove background="#ffffff"
• Transparent background adapts to various themes

6.2. Font Size

• Use 1.5x standard font size (around 18px) for PDF readability

6.3. Japanese Text Width

• Allow 30-40px per character
• Insufficient width causes unintended line breaks

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

6.4. Arrow Placement

• Always place arrows at back (position in XML right after Title)
• Position arrows to avoid overlapping with labels
• Keep arrow start/end at least 20px from label bottom edge

<!-- Title -->
<mxCell id="title" value="..." .../>

<!-- Arrows (back layer) -->
<mxCell id="arrow1" style="edgeStyle=..." .../>

<!-- Other elements (front layer) -->
<mxCell id="box1" .../>

6.5. Arrow Connection to Text Labels

For text elements, exitX/exitY don't work, so use explicit coordinates:

<!-- Good: Explicit coordinates with sourcePoint/targetPoint -->
<mxCell id="arrow" style="..." edge="1" parent="1">
  <mxGeometry relative="1" as="geometry">
    <mxPoint x="1279" y="500" as="sourcePoint"/>
    <mxPoint x="119" y="500" as="targetPoint"/>
    <Array as="points">
      <mxPoint x="1279" y="560"/>
      <mxPoint x="119" y="560"/>
    </Array>
  </mxGeometry>
</mxCell>

6.6. edgeLabel Offset Adjustment

Adjust offset attribute to distance arrow labels from arrows:

<!-- Place above arrow (negative value to distance) -->
<mxPoint x="0" y="-40" as="offset"/>

<!-- Place below arrow (positive value to distance) -->
<mxPoint x="0" y="40" as="offset"/>

6.7. Remove Unnecessary Elements

• Remove decorative icons irrelevant to context
• Example: If ECR exists, separate Docker icon is unnecessary

6.8. Labels and Headings

• Service name only: 1 line
• Service name + supplementary info: 2 lines with line break
• Redundant notation (e.g., ECR Container Registry): shorten to 1 line
• Use <br> tag for line breaks

6.9. Background Frame and Internal Element Placement

When placing elements inside background frames (grouping boxes), ensure sufficient margin.

• YOU MUST: Internal elements must have at least 30px margin from frame boundary
• YOU MUST: Account for rounded corners (rounded=1) and stroke width
• YOU MUST: Always visually verify PNG output for overflow

Coordinate calculation verification:

Background frame: y=20, height=400 -> range is y=20-420
Internal element top: frame y + 30 or more (e.g., y=50)
Internal element bottom: frame y + height - 30 or less (e.g., up to y=390)

Bad example (may overflow):

<!-- Background frame -->
<mxCell id="bg" style="rounded=1;strokeWidth=3;...">
  <mxGeometry x="500" y="20" width="560" height="400" />
</mxCell>
<!-- Text: y=30 is too close to frame top (y=20) -->
<mxCell id="label" value="Title" style="text;...">
  <mxGeometry x="510" y="30" width="540" height="35" />
</mxCell>

Good example (sufficient margin):

<!-- Background frame -->
<mxCell id="bg" style="rounded=1;strokeWidth=3;...">
  <mxGeometry x="500" y="20" width="560" height="430" />
</mxCell>
<!-- Text: y=50 is 30px from frame top (y=20) -->
<mxCell id="label" value="Title" style="text;...">
  <mxGeometry x="510" y="50" width="540" height="35" />
</mxCell>

7. Reference

• Layout Guidelines
• AWS Icons
• AWS Icon Search Script

AWS icon search examples:

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

8. Checklist

• [ ] No background color set (page="0")
• [ ] Font size appropriate (larger recommended)
• [ ] Arrows placed at back layer
• [ ] Arrows not overlapping labels (verify in PNG)
• [ ] Arrow start/end sufficiently distant from labels (at least 20px)
• [ ] Arrows not penetrating boxes or icons (verify in PNG)
• [ ] Internal elements not overflowing background frame (verify in PNG)
• [ ] 30px+ margin between background frame and internal elements
• [ ] AWS service names are official names/correct abbreviations
• [ ] AWS icons are latest version (mxgraph.aws4.*)
• [ ] No unnecessary elements remaining
• [ ] Visually verified PNG conversion

9. Image Display in reveal.js Slides

Add auto-stretch: false to YAML header:

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

This ensures correct image display on mobile devices.

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

AWS アイコンとサービス名

1. 正しいサービス名の規則

• 略称のみの使用は避ける (ECS → Amazon ECS)
• 正式名称を使用する

2. アイコンスタイル

2.1. リソースアイコン (基本形式)

shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.{service_name};

2.2. プロダクトアイコン

shape=mxgraph.aws4.productIcon;prIcon=mxgraph.aws4.{service_name};

2.3. 注意事項

• mxgraph.aws4.* を使用 (aws3 は古いため非推奨)
• サービス名は snake_case で指定

3. カテゴリ別アイコン

3.1. Compute (コンピューティング)

3.2. Containers (コンテナ)

3.3. Storage (ストレージ)

3.4. Database (データベース)

3.5. Networking (ネットワーク)

3.6. Security, Identity & Compliance (セキュリティ)

3.7. Analytics (分析)

3.8. Machine Learning & AI (機械学習・AI)

3.9. Application Integration (アプリケーション統合)

3.10. Management & Governance (管理・ガバナンス)

3.11. Developer Tools (開発者ツール)

3.12. Front-end Web & Mobile (フロントエンド)

3.13. Customer Engagement (カスタマーエンゲージメント)

3.14. Business Applications (ビジネスアプリケーション)

3.15. End User Computing (エンドユーザーコンピューティング)

3.16. Internet of Things (IoT)

3.17. Migration & Transfer (移行・転送)

3.18. Media Services (メディアサービス)

3.19. Game Tech (ゲーム開発)

3.20. Cost Management (コスト管理)

3.21. Blockchain (ブロックチェーン)

3.22. Quantum Technologies (量子技術)

3.23. Satellite (衛星)

3.24. Robotics (ロボティクス)

3.25. General/Generic Icons (汎用アイコン)

4. グループアイコン

4.1. 基本構文

shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.{group_name};

4.2. グループアイコン一覧

4.3. 使用例

<!-- AWS Cloud -->
<mxCell style="shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_aws_cloud;..." />

<!-- VPC -->
<mxCell style="shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_vpc;..." />

<!-- Availability Zone -->
<mxCell style="shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_availability_zone;..." />

<!-- Public Subnet -->
<mxCell style="shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_public_subnet;fillColor=#E9F3E6;..." />

<!-- Private Subnet -->
<mxCell style="shape=mxgraph.aws4.group;grIcon=mxgraph.aws4.group_private_subnet;fillColor=#E6F2F8;..." />

5. アイコン検索スクリプト

scripts/find_aws_icon.py を使用して効率的に検索可能。

6. 参考リンク

• draw.io AWS Diagrams Blog
• AWS Architecture Icons
• jgraph/drawio GitHub
• awsicons.dev
• diagrams-aws-icons

レイアウトガイドライン

1. グループ化の原則

• AWS Cloud グループを最外層とする
• 機能単位でサブグループを作成
• グループは横並びを基本とし、データフローに沿って配置

1.1. グループの階層構造

AWS Cloud (最外層)
├── VPC
│   ├── Public Subnet
│   │   └── ALB, NAT Gateway など
│   └── Private Subnet
│       └── ECS, RDS など
├── S3
├── CloudWatch
└── その他のサービス

2. 接続線のルール

2.1. 線種の使い分け

2.2. 矢印の方向

• 矢印はデータの流れる方向に従う
• 双方向通信は双方向矢印を使用

3. 配置の原則

3.1. 左から右へのフロー

[データソース] → [処理] → [ストレージ] → [分析/可視化]

3.2. 上から下へのフロー (代替)

[ユーザー/クライアント]
        ↓
[ロードバランサー]
        ↓
[アプリケーション]
        ↓
[データベース]

4. 視認性の確保

• ラベルは要素の近くに配置
• 矢印が交差しないように配置を調整
• 関連する要素はグループ化して近くに配置
• 余白を適切に確保して見やすくする