Draw.io Diagram Creation Guidelines

Overview

This skill provides proven best practices for creating high-quality draw.io diagrams that render correctly in PNG format with proper Japanese text support, correct layering, and professional appearance.

Core Guidelines

1. Font Configuration

Critical: Each text element must have explicit fontFamily attribute.

<mxCell ... style="text;...fontFamily=Noto Sans JP;..." />

Why: The defaultFontFamily in <mxGraphModel> does NOT affect PNG export. Only element-level fontFamily attributes are respected during image rendering.

Recommended fonts:

• Japanese text: Noto Sans JP or Hiragino Sans
• English text: Arial, Helvetica, or Roboto

2. Arrow and Connector Placement

Rule: Arrows must be written first in XML to render at the back layer.

Problem: If arrows are defined after labels/shapes, they will overlap text and make diagrams unreadable.

Solution:

<root>
  <mxCell id="0" />
  <mxCell id="1" parent="0" />
  <!-- ↓ Arrows FIRST -->
  <mxCell id="arrow1" edge="1" parent="1" ... />
  <mxCell id="arrow2" edge="1" parent="1" ... />
  <!-- ↓ Shapes and labels AFTER -->
  <mxCell id="shape1" vertex="1" parent="1" ... />
  <mxCell id="label1" vertex="1" parent="1" ... />
</root>

Spacing: Maintain minimum 20px clearance between arrows and labels to prevent visual overlap.

3. Text Size and Spacing

Font size: Use 1.5x standard size (18px recommended) for better readability.

Japanese text width estimation:

• Allocate 30-40px width per character
• Example: 5-character label → minimum 150-200px width

English text: Standard character width rules apply (~8-12px per character depending on font).

4. XML Structure Best Practices

Standard draw.io structure:

<mxfile host="app.diagrams.net">
  <diagram name="Page-1">
    <mxGraphModel dx="1422" dy="794" grid="1" ...>
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <!-- Elements here -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

5. Color and Shape Conventions

Shape: Rectangle をデフォルトとする。rounded=0 を基本に使用。

Color principle: 過剰な着色をしない。基本は 黒枠・無色塗り。

• デフォルトスタイル: fillColor=none;strokeColor=#333333;
• コンテナ（グルーピング枠）: fillColor=none;strokeColor=#333333; （破線も可）
• 例外: クラウドプラットフォーム境界のみ着色OK
  • Azure: fillColor=#dae8fc;strokeColor=#6c8ebf;
  • AWS: fillColor=#FFF8E1;strokeColor=#FFA000;
  • Snowflake: fillColor=#d5e8d4;strokeColor=#82b366;
  • GCP: fillColor=#FCE4EC;strokeColor=#C62828;
• 矢印: strokeColor=#333333; を基本とし、太さ（strokeWidth）で重要度を表現

6. Common Element Patterns

Rectangle with text:

<mxCell id="rect1" value="サービス名"
  style="rounded=0;whiteSpace=wrap;html=1;fillColor=none;strokeColor=#333333;fontFamily=Noto Sans JP;fontSize=18;"
  vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="200" height="80" as="geometry"/>
</mxCell>

Container (grouping boundary):

<mxCell id="group1" value="VNet"
  style="rounded=0;whiteSpace=wrap;html=1;fillColor=none;strokeColor=#333333;dashed=1;verticalAlign=top;fontFamily=Noto Sans JP;fontSize=18;container=1;collapsible=0;"
  vertex="1" parent="1">
  <mxGeometry x="50" y="50" width="600" height="400" as="geometry"/>
</mxCell>

Cloud platform boundary (colored exception):

<mxCell id="azure1" value="Azure"
  style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;verticalAlign=top;fontFamily=Noto Sans JP;fontSize=20;fontStyle=1;container=1;collapsible=0;strokeWidth=2;"
  vertex="1" parent="1">
  <mxGeometry x="10" y="10" width="800" height="600" as="geometry"/>
</mxCell>

Arrow connector:

<mxCell id="arrow1"
  style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeColor=#333333;exitX=1;exitY=0.5;"
  edge="1" parent="1" source="rect1" target="rect2">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>

Label (standalone text):

<mxCell id="label1" value="説明テキスト"
  style="text;html=1;strokeColor=none;fillColor=none;align=center;verticalAlign=middle;fontFamily=Noto Sans JP;fontSize=14;"
  vertex="1" parent="1">
  <mxGeometry x="150" y="200" width="100" height="30" as="geometry"/>
</mxCell>

Workflow

When creating draw.io diagrams:

1. Start with structure: Define all arrows/edges first
2. Add shapes: Create rectangles, circles, containers
3. Add labels: Place standalone text elements last
4. Verify fonts: Ensure every text element has fontFamily attribute
5. Check spacing: Verify 20px+ clearance between overlapping elements
6. Size Japanese text: Allocate 30-40px width per character

Quality Checklist

Before finalizing diagrams:

• All text elements have explicit fontFamily attribute
• Arrows are defined before shapes/labels in XML
• Japanese text has adequate width (30-40px per character)
• Font size is 18px or larger for readability
• Minimum 20px spacing between arrows and labels
• No overlapping text elements
• Default shapes are Rectangle (rounded=0)
• Default style is black border, no fill (fillColor=none;strokeColor=#333333;)
• Color is used ONLY for cloud platform boundaries (Azure, AWS, GCP, Snowflake)

References

For additional guidance, see:

• references/aws-icons.md - AWS icon usage patterns (if working with AWS diagrams)

Resources

references/

Contains supplementary documentation that can be loaded as needed:

• AWS service icon naming conventions
• Common diagram patterns for specific domains

scripts/

Reserved for helper scripts (e.g., icon search, validation tools)

assets/

Reserved for reusable templates or icon files