draw.io ダイアグラム スキル

1. 基本ルール

• .drawio ファイルのみを編集する
• .drawio.png ファイルを直接編集しない
• Quarto スライドでは pre-commit hook により自動生成された .drawio.png を使用する

2. フォント設定

Quarto スライドで使用されるダイアグラムについて、 mxGraphModel タグで defaultFontFamily を指定します:

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

また、各テキスト要素の style 属性で明示的に fontFamily を指定します:

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

3. 変換コマンド

変換スクリプトについては scripts/convert-drawio-to-png.sh を参照してください。

# すべての .drawio ファイルを変換
mise exec -- pre-commit run --all-files

# 特定の .drawio ファイルを変換
mise exec -- pre-commit run convert-drawio-to-png --files assets/my-diagram.drawio

# スクリプトを直接実行 (skill のスクリプトを使用)
bash ~/.claude/skills/draw-io/scripts/convert-drawio-to-png.sh assets/diagram1.drawio

内部で使用されるコマンド:

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

オプション	説明
-x	エクスポートモード
-f png	PNG 形式出力
-s 2	2倍スケール (高解像度)
-t	透明背景
-o	出力ファイルパス

4. レイアウト調整

4.1. 座標調整の手順

1. テキストエディタで .drawio ファイルを開く (プレーン XML 形式)
2. 調整対象要素の mxCell を検索 (value 属性のテキストで検索)
3. mxGeometry タグ内の座標を調整
   • x: 左からの位置
   • y: 上からの位置
   • width: 幅
   • height: 高さ
4. 変換を実行して確認

4.2. 座標計算

• 要素の中心座標 = y + (height / 2)
• 複数要素をアラインする場合、中心座標を計算して合わせる

5. デザイン原則

5.1. 基本原則

• 明確性: シンプルで視覚的にクリーンなダイアグラムを作成する
• 一貫性: 色、フォント、アイコンサイズ、線の太さを統一する
• 正確性: 正確性を簡潔さのために犠牲にしない

5.2. 要素ルール

• すべての要素にラベルを付ける
• 矢印で方向を示す (双方向矢印より 2 つの単方向矢印が好ましい)
• 最新の公式アイコンを使用する
• カスタムシンボルを説明するための凡例を追加する

5.3. アクセシビリティ

• 十分な色のコントラストを確保する
• 色に加えてパターンを使用する

5.4. 段階的な情報開示

複雑なシステムを段階的なダイアグラムに分離します:

ダイアグラムタイプ	目的
コンテキストダイアグラム	外部の視点からのシステム概要
システムダイアグラム	主要コンポーネントと関係
コンポーネントダイアグラム	技術詳細と統合ポイント
デプロイメントダイアグラム	インフラストラクチャ構成
データフロー図	データフローと変換
シーケンス図	時系列の相互作用

5.5. メタデータ

ダイアグラムにタイトル、説明、最終更新日、著者、バージョンを含める。

6. ベストプラクティス

6.1. 背景色

• background="#ffffff" を削除する
• 透明背景はさまざまなテーマに適応する

6.2. フォントサイズ

• PDF の可読性のため標準フォントサイズの 1.5 倍 (約 18px) を使用する

6.3. 日本語テキスト幅

• 1 文字あたり 30～40px を許容する
• 幅が不足すると意図しない行折れが発生する

<!-- 10 文字のテキストの場合、300～400px を許容 -->
<mxGeometry x="140" y="60" width="400" height="40" />

6.4. 矢印の配置

• 常に矢印を背面に配置 (XML で Title の直後に位置付ける)
• 矢印をラベルとの重なりを避けるように配置する
• 矢印の開始/終了をラベル下端から最低 20px 離す

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

<!-- Arrows (背面レイヤー) -->
<mxCell id="arrow1" style="edgeStyle=..." .../>

<!-- その他の要素 (前面レイヤー) -->
<mxCell id="box1" .../>

6.5. テキストラベルへの矢印接続

テキスト要素では exitX/exitY が機能しないため、明示的な座標を使用します:

<!-- 良い例: 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 属性を調整します:

<!-- 矢印の上に配置 (負の値で距離を置く) -->
<mxPoint x="0" y="-40" as="offset"/>

<!-- 矢印の下に配置 (正の値で距離を置く) -->
<mxPoint x="0" y="40" as="offset"/>

6.7. 不要な要素を削除する

• コンテキストに関係ない装飾的アイコンを削除する
• 例: ECR が存在する場合、別個の Docker アイコンは不要

6.8. ラベルと見出し

• サービス名のみ: 1 行
• サービス名 + 補足情報: 改行で 2 行
• 冗長な表記 (例: ECR Container Registry): 1 行に短縮
• 改行には <br> タグを使用

6.9. 背景フレームと内部要素の配置

背景フレーム (グループ化ボックス) 内に要素を配置する場合、 十分なマージンを確保します。

• 必須: 内部要素はフレーム境界から最低 30px のマージンを持つ必要がある
• 必須: 角の丸み (rounded=1) とストロークの幅を考慮する
• 必須: PNG 出力で常に視覚的にはみ出しを確認する

座標計算の確認:

背景フレーム: y=20, height=400 → 範囲は y=20～420
内部要素の上: フレーム y + 30 以上 (例: y=50)
内部要素の下: フレーム y + height - 30 以下 (例: y=390 まで)

悪い例 (はみ出す可能性):

<!-- 背景フレーム -->
<mxCell id="bg" style="rounded=1;strokeWidth=3;...">
  <mxGeometry x="500" y="20" width="560" height="400" />
</mxCell>
<!-- テキスト: y=30 はフレーム上端 (y=20) に近すぎる -->
<mxCell id="label" value="Title" style="text;...">
  <mxGeometry x="510" y="30" width="540" height="35" />
</mxCell>

良い例 (十分なマージン):

<!-- 背景フレーム -->
<mxCell id="bg" style="rounded=1;strokeWidth=3;...">
  <mxGeometry x="500" y="20" width="560" height="430" />
</mxCell>
<!-- テキスト: y=50 はフレーム上端 (y=20) から 30px 離れている -->
<mxCell id="label" value="Title" style="text;...">
  <mxGeometry x="510" y="50" width="540" height="35" />
</mxCell>

7. リファレンス

• レイアウトガイドライン
• AWS アイコン
• AWS アイコン検索スクリプト

AWS アイコン検索の例:

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

8. チェックリスト

• 背景色が設定されていない (page="0")
• フォントサイズが適切 (より大きいサイズが推奨)
• 矢印が背面レイヤーに配置されている
• 矢印がラベルと重なっていない (PNG で確認)
• 矢印の開始/終了がラベルから十分離れている (最低 20px)
• 矢印がボックスやアイコンを貫通していない (PNG で確認)
• 内部要素が背景フレームをはみ出していない (PNG で確認)
• 背景フレームと内部要素の間に 30px 以上のマージン
• AWS サービス名が公式名/正しい略語である
• AWS アイコンが最新版 (mxgraph.aws4.*)
• 不要な要素が残っていない
• PNG 変換を視覚的に確認

9. reveal.js スライドでの画像表示

YAML ヘッダーに auto-stretch: false を追加:

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

これによりモバイルデバイスでの正しい画像表示が確保されます。