Drawio Diagram Forge

Draw.io Diagram Forge

Generate draw.io editable diagrams using AI-powered workflow.

When to Use

• Creating architecture diagrams (Azure, AWS)
• Converting flowcharts from text descriptions
• Transforming images/screenshots into editable format
• Generating swimlane, sequence diagrams
• Editing Azure/AWS icons in existing .drawio files

Choose this skill when the result will need later GUI editing in draw.io, cloud icons, or documentation-facing diagram assets.

When NOT to Use

• Quick inline diagrams that are easier to keep as Mermaid in README or Markdown
• One-off text-native diagrams where manual GUI adjustment is not expected

Prerequisites

Quick Start

Create a login flow diagram

Generate an Azure Hub-Spoke architecture diagram

From inputs/requirements.md, create a system diagram

Output Formats

Output: outputs/

Recommended Delivery Pattern

For documentation-facing diagrams, generate outputs as a pair:

• name.drawio for editing in VS Code Draw.io
• name.drawio.svg for README / web embedding

Reserve *.drawio.svg for SVG files that actually contain draw.io metadata. If you hand-author or post-process a plain SVG without embedded draw.io metadata, name it *.svg instead of *.drawio.svg.

If the visible asset started from manual SVG cleanup or hand-authored layout tweaks, still keep a matching name.drawio as the editable SSOT. Do not leave documentation diagrams as SVG-only when future edits are expected.

Recommended markdown pattern:

Use `outputs/name.drawio.svg` as the embedded image path.

- outputs/name.drawio.svg
- outputs/name.drawio

If multilingual variants are needed, keep parallel filenames instead of overwriting a single asset:

• name.drawio / name.drawio.svg
• name-ja.drawio / name-ja.drawio.svg

This keeps the editable source, the embeddable image, and the language variants aligned.

For local article drafting, if the Markdown preview surface does not reliably render the SVG variant, it is acceptable to:

• keep .drawio as the editable source
• keep .drawio.svg as the web / embeddable artifact
• temporarily reference a generated *.png from the draft article for local preview stability

At publish time, replace local relative preview paths with the final hosted asset URL.

For Qiita articles, do not leave non-trivial diagrams as Mermaid blocks in the article body. Qiita rendering can be inconsistent. Create a .drawio source, export PNG for Qiita image upload, keep .drawio.svg as the web artifact, and replace the draft-local path with the hosted Qiita image URL before publish.

Workflow

USER INPUT → ORCHESTRATOR → MANIFEST GATEWAY → SVG FORGE → COMPLETED

Quality Gates

Limits

Cloud Icons

→ [references/cloud-icons.md](references/cloud-icons.md)

For Azure-centric diagrams, proactively use the official Azure icon set when a verified Azure2 icon exists. Prefer icon + short label over plain rounded boxes for first-class Azure services. Fall back to generic boxes only when the icon is missing, misleading, or would hurt readability.

Enable in VS Code

1. Open .drawio file 2. Click "+ More Shapes" (bottom-left) 3. Enable: Azure, AWS 4. Apply

Azure Format (Critical)

This format applies to both new diagrams and edits to existing .drawio files. When fixing or replacing Azure icons, always use this format.

<!-- WRONG -->
<mxCell style="shape=mxgraph.azure.front_door;..." />

<!-- CORRECT -->
<mxCell style="aspect=fixed;image=img/lib/azure2/networking/Front_Doors.svg;..." />

Azure Icon Preference

• Use Azure service icons aggressively for Azure architecture diagrams when the service has a verified Azure2 path.
• Keep the service name as a short text label even when the icon is obvious.
• Do not mix verified Azure2 icons with generic blue boxes for the same diagram layer unless there is a clear reason.
• If only some services have official icons, use icons for those services and use neutral fallback boxes for the rest.

References

Scripts

Troubleshooting

Done Criteria

• [ ] .drawio or .drawio.svg file generated
• [ ] Diagram opens correctly in VS Code Draw.io extension
• [ ] All nodes and edges visible
• [ ] Quality gate score ≥ 85
• [ ] If diagram is referenced from documentation, both editable source and embeddable image are provided
• [ ] Render review completed at the target embed width with no text overlap, clipping, or border collisions

Cloud Icons Reference

⚠️ Critical: Azure Icon Format

*VS Code Draw.io Integration では `mxgraph.azure.` 形式が正しく表示されない。**

必ず img/lib/azure2/**/*.svg 形式を使用すること。

Icon Selection Policy

Azure 中心の構成図では、使える Azure アイコンは積極的に使う。

• Azure サービスに verified な Azure2 アイコンがあるなら、まずアイコン利用を検討する
• アイコンを使っても、サービス名の短いラベルは残す
• 同じ図の同じレイヤーでは、Azure アイコンと generic box を無秩序に混在させない
• アイコンが存在しない、誤解を招く、または図が読みにくくなる場合だけ generic box に落とす
• 初回レビューでは「この図で icon 化できるノードを box のまま放置していないか」を確認する

目安: Azure Architecture / Hub-Spoke / Landing Zone / Service topology のような図では、主要な Azure サービスは box より icon を優先する。

🔧 Initial Setup (Required)

Azure/AWS アイコンを使うには、事前にシェイプライブラリを有効化する必要がある。

手順

1. .drawio ファイルを VS Code で開く 2. 左下の 「+ その他の図形」 (+ More Shapes) をクリック 3. 「図形」ダイアログが開く 4. 「ネットワーク」カテゴリで以下にチェック：

• ✅ Azure - Azure アイコン
• ✅ AWS17 / AWS18 / AWS 2026 - AWS アイコン（用途に応じて）
• ✅ AWS 3D - 3D 表現が必要な場合

5. 「設定を保存」 にチェック（次回以降も有効） 6. 「適用」 をクリック

推奨設定

Note: 設定は .drawio ファイルごとではなく、VS Code 全体で保存される。一度設定すれば他のファイルでも有効。

Azure Icons (Azure2 形式)

Common Azure Icons

Azure Icon Style (✅ Correct)

<mxCell id="vm1" value="VM-01"
        style="aspect=fixed;html=1;points=[];align=center;image;fontSize=12;image=img/lib/azure2/compute/Virtual_Machine.svg;verticalLabelPosition=bottom;verticalAlign=top;"
        vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="68" height="68" as="geometry"/>
</mxCell>

Azure2 Library Structure

img/lib/azure2/
├── ai_machine_learning/    # Azure ML, Cognitive Services
├── analytics/              # Synapse, Event Hubs
├── compute/                # VM, App Service, Functions, AKS
├── containers/             # Container Instances
├── databases/              # SQL, Cosmos DB, Redis
├── devops/                 # Azure DevOps
├── identity/               # Azure AD / Entra ID
├── integration/            # API Management, Logic Apps, Service Bus
├── iot/                    # IoT Hub
├── management_governance/  # Monitor, Log Analytics, Recovery Services, Policy
├── networking/             # VNet, Load Balancer, Front Door, VPN (Virtual_Network_Gateways)
├── security/               # Key Vault, Defender, Sentinel
├── storage/                # Storage Accounts, Data Lake
└── web/                    # App Service Plans

⚠️ Common Mistakes (Verified against GitHub)

🚫 Non-Existent Icons & Alternatives

以下のアイコンは draw.io の azure2 ライブラリに存在しない、またはパスが異なる。代替案を使用すること。

🔍 other/ カテゴリに注目

多くの新しい Azure サービスは other/ カテゴリに配置されている。見つからない場合は other/ を確認：

• other/Azure_Cloud_Shell.svg
• other/Azure_Communication_Services.svg
• other/Container_App_Environments.svg
• other/Worker_Container_App.svg
• other/Grafana.svg
• other/Azure_Load_Testing.svg
• other/MS_Dev_Box.svg
• other/Private_Endpoints.svg
• other/Local_Network_Gateways.svg
• other/ExpressRoute_Direct.svg

代替スタイル例

角丸ボックス + テキスト（GitHub 向け）:

<mxCell value="Cloud Shell"
        style="rounded=1;whiteSpace=wrap;html=1;fillColor=#0078D4;strokeColor=#005A9E;fontColor=#FFFFFF;fontSize=12;fontStyle=1;"
        vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="100" height="40" as="geometry"/>
</mxCell>

雲形状（Internet 向け）:

<mxCell value="Internet"
        style="ellipse;shape=cloud;whiteSpace=wrap;html=1;fillColor=#F5F5F5;strokeColor=#666666;"
        vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="120" height="80" as="geometry"/>
</mxCell>

💡 Tip: 新しい Azure サービスはアイコンがライブラリに追加されるまで時間がかかる。テキストボックスで対応し、将来のアップデートで置換可能にする。

AWS Icons (AWS4 形式)

Setup

1. Open .drawio file in VS Code 2. Click "+ More Shapes" (bottom-left) 3. Check AWS 4. Click Apply

Common AWS Icons

AWS Icon Style

<mxCell id="ec2" value="EC2"
        style="sketch=0;outlineConnect=0;fontColor=#232F3E;gradientColor=none;strokeColor=#ffffff;fillColor=#232F3E;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.ec2;"
        vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="50" height="50" as="geometry"/>
</mxCell>

Style Comparison

Best Practices

1. Azure は必ず `img/lib/azure2/` 形式を使用 2. Consistency: Use icons from the same provider in one diagram 3. Labeling: Always add text labels below icons 4. Sizing: Keep icon sizes consistent (68x68 for Azure, 50x50 for AWS) 5. Grouping: Use containers/swimlanes to group related services

Validation Checklist

生成後に確認：

• [ ] Azure アイコンが img/lib/azure2/ パスを使用している
• [ ] shape=mxgraph.azure.* が含まれていない
• [ ] VS Code Draw.io Integration で正しく表示される

Icon Detection Keywords

When the input mentions these keywords, use corresponding cloud icons:

Azure Keywords

• Azure, Microsoft Cloud
• VM, Virtual Machine (in Azure context)
• App Service, Function App, Logic App
• VNET, Virtual Network
• AAD, Azure AD, Entra ID

AWS Keywords

• AWS, Amazon Web Services
• EC2, Lambda, ECS, EKS
• S3, RDS, DynamoDB
• VPC, CloudFront, Route 53

Reference

• Draw.io Azure2 Icons
• Draw.io AWS4 Icons

AWS → Azure Migration Patterns

AWS 図を Azure 化する際のサービス対応表：

Migration Tips

1. NAT Gateway → Azure Firewall: Azure では Firewall が SNAT 機能を持つため、NAT Gateway を別途配置せず Firewall 直結構成が可能 2. Service Endpoint → Private Endpoint: Azure では Private Endpoint が推奨。より安全なプライベート接続を提供 3. 形式変換: mxgraph.aws4.* や mxgraph.azure.* は img/lib/azure2/**/*.svg 形式に置換

Conversion Commands

# sed での一括置換例（旧形式 → 新形式は手動対応推奨）
sed -i 's/mxgraph\.azure3\./mxgraph.azure./g' diagram.drawio

# ID重複チェック（編集時に発生しやすい）
import re, collections, pathlib
p = pathlib.Path('diagram.drawio')
text = p.read_text(encoding='utf-8')
ids = re.findall(r'\bid="([^"]+)"', text)
ctr = collections.Counter(ids)
dups = [i for i,c in ctr.items() if c > 1]
if dups:
    print(f'⚠️ Duplicate IDs: {dups}')

Azure Architecture Patterns

Hub-Spoke Topology Icons

典型的な Hub-Spoke アーキテクチャで使用するアイコン：

Example: Hub VNet Components

<!-- Firewall -->
<mxCell value="Azure Firewall"
        style="aspect=fixed;image=img/lib/azure2/networking/Firewalls.svg;..."
        .../>

<!-- Bastion -->
<mxCell value="Bastion"
        style="aspect=fixed;image=img/lib/azure2/networking/Bastions.svg;..."
        .../>

<!-- Monitor -->
<mxCell value="Azure Monitor"
        style="aspect=fixed;image=img/lib/azure2/management_governance/Monitor.svg;..."
        .../>

<!-- Backup (Recovery Services) -->
<mxCell value="Backup"
        style="aspect=fixed;image=img/lib/azure2/management_governance/Recovery_Services_Vaults.svg;..."
        .../>

mxCell Structure Reference

mxfile Structure

<mxfile host="app.diagrams.net" generator="diagram-forge">
  <diagram id="..." name="Page-1">
    <mxGraphModel dx="..." dy="..." grid="1" gridSize="10">
      <root>
        <mxCell id="0" />
        <mxCell id="1" parent="0" />
        <!-- Nodes and edges here -->
      </root>
    </mxGraphModel>
  </diagram>
</mxfile>

Required Elements

Node Examples

Rectangle

<mxCell id="node1" value="Node Name"
        style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;"
        vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="120" height="60" as="geometry"/>
</mxCell>

Ellipse (Start/End)

<mxCell id="start" value="Start"
        style="ellipse;whiteSpace=wrap;html=1;fillColor=#d5e8d4;strokeColor=#82b366;"
        vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="80" height="50" as="geometry"/>
</mxCell>

Diamond (Decision)

<mxCell id="decision1" value="Condition?"
        style="rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;"
        vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="100" height="80" as="geometry"/>
</mxCell>

Edge Examples

Arrow

<mxCell id="edge1" value=""
        style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;"
        edge="1" parent="1" source="node1" target="node2">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>

Labeled Edge

<mxCell id="edge2" value="Yes"
        style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;"
        edge="1" parent="1" source="decision1" target="node3">
  <mxGeometry relative="1" as="geometry"/>
</mxCell>

Group (Container)

<!-- Container -->
<mxCell id="group1" value="Group Name"
        style="swimlane;horizontal=1;startSize=30;fillColor=#f5f5f5;strokeColor=#666666;"
        vertex="1" parent="1">
  <mxGeometry x="50" y="50" width="300" height="200" as="geometry"/>
</mxCell>

<!-- Child node (parent="group1") -->
<mxCell id="child1" value="Child Node"
        style="rounded=1;whiteSpace=wrap;html=1;"
        vertex="1" parent="group1">
  <mxGeometry x="20" y="40" width="100" height="50" as="geometry"/>
</mxCell>

HTML Encoding

Content attribute requires HTML encoding:

Validation Checklist

• [ ] mxCell id="0" and id="1" exist
• [ ] All nodes have vertex="1"
• [ ] All edges have edge="1"
• [ ] Edge source/target reference valid node IDs
• [ ] mxGeometry defined for each mxCell
• [ ] Content attribute properly HTML encoded
• [ ] mxCell count >= 2 + nodes + edges

Style Guide

Node Colors

Edge Styles

Orthogonal (Recommended)

edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;

Curved

edgeStyle=elbowEdgeStyle;elbow=horizontal;rounded=1;

Straight

endArrow=classic;html=1;

Shape Styles

Rounded Rectangle

rounded=1;whiteSpace=wrap;html=1;

Ellipse

ellipse;whiteSpace=wrap;html=1;

Diamond

rhombus;whiteSpace=wrap;html=1;

Swimlane/Container

swimlane;horizontal=1;startSize=30;

Layout Recommendations

Title / Caption

• Do NOT embed title text in the diagram (e.g., "図1-1 ..."). Captions belong in the document layer (Markdown ![caption](...), Re:VIEW //image[id][caption], etc.).
• Embedding titles causes duplication when the document already renders a figure caption.
• If the exported image is likely to circulate standalone (chat, slide, ticket, SNS, pasted image), use the diagram title/subtitle to identify the feature or topic name directly. Avoid generic headings like before / after alone.
• Good: Summarized Gateway Prefixes の before / after
• Weak: ExpressRoute の広告ルート数を before / after でみる when the feature name is missing from the image itself.

Spacing

Top Callouts / Note Boxes

For explanatory note boxes placed near the top of a panel or container:

• Inset from the outer frame by at least 16-24px. Do not let the note box kiss or visually merge with the panel border.
• Prefer 3-4 short lines over 2 long lines. If Japanese text feels tight, reduce line length before reducing font size.
• Increase note box height first when text feels crowded. Do not solve crowding only by shrinking fonts.
• Keep arrow labels on a separate Y band from the note box. Labels that sit at the same height tend to look overlapped in exports.
• Review at actual embed width after export. A diagram that looks fine at full canvas size can still collide when embedded in Markdown or docs.

Article Concept / Lifecycle Diagrams

For article-facing concept diagrams that explain a repeated workflow:

• Use a single visible start point. If the flow begins from multiple places, readers often cannot tell what to follow first.
• For metric diagrams such as usage rate, show denominator and numerator explicitly, then summarize the formula in one final node. Avoid long dashed aggregation lines that make the diagram feel like a wiring diagram.
• Keep the main cycle to 3-4 primary nodes. Support tools, marketplaces, and implementation aids should be a footer note or side callout, not peer nodes in the main loop.
• Use outcome-oriented node titles such as Skill を改善, not implementation-detail titles such as Gotchas に戻す. Highlight the important detail (Gotchas) inside the node body instead.
• Split long slash-separated phrases into separate short lines. If a line like description / Gotchas / references feels tight at embed width, rewrite it as description を整える + Gotchas / references に分ける.
• Shrink-wrap the canvas after layout changes. If footer notes move up, reduce page height so exported assets do not carry large dead whitespace.
• Validate both source and delivery artifacts after wording tweaks: .drawio is the editable SSOT, and .drawio.svg is the Markdown/web artifact.

Edge Crossing Prevention

For complex diagrams (>15 nodes) with many-to-one or fan-out edges:

• Align source and target y — place each agent/processor at the same y as its output node. Lines stay horizontal, crossing drops to near zero.
• Reorder sibling nodes before drawing detours — if a connector from one item in a stacked group must jump around another item, first swap or move the related item closer to its target/callout. A short straight connector is usually clearer than a routed line that skirts sibling boxes.
• Avoid swimlane-relative coordinates — when edges cross swimlane boundaries, exitX/entryY resolve to group-relative positions that are hard to predict. Use absolute positioning (parent="1") for all nodes instead.
• Spread entryY on shared targets — when multiple edges enter the same node, enlarge the node height and assign distinct entryY values (e.g., 0.1 / 0.5 / 0.9) so lines arrive at different vertical points.
• Collapse fan-out into one edge — instead of N individual arrows from an orchestrator to N children, draw a single dashed arrow to a group outline and label it (e.g., "delegates").
• Separate auxiliary elements — legends, data stores, and footnotes must sit below the main flow with ≥40px vertical gap from the lowest flow node. Never place them at the same y as flow outputs.

Nested Containers (Hierarchy Diagrams)

When using nested rectangles to show hierarchy (e.g., Enterprise > Org > Team > Repo):

• Container height = content bottom edge + 15–20px padding. Do not use large fixed heights when children are few.
• Legend placement = always outside the outermost container. Never inside a child container — it reads as part of that group.
• Page size = tightest bounding box of all elements + 20px margin. Avoid "generous" pages that create dead whitespace.
• Edges are optional — spatial containment already conveys hierarchy. Only add arrows when showing data/control flow across containers.

Flow Diagrams (Branch/Merge Lines)

When combining diagonal branch/merge lines with annotation boxes (e.g., GitHub Flow step labels):

• Place step boxes below the diagonal endpoints — if a diagonal goes from (x1,y1) to (x2,y2), boxes must have y > max(y1, y2) to avoid crossing.
• Dashed connectors starting from a box edge should begin at y - 2px (not exactly at the top edge) to avoid false overlap in validators.
• Keep horizontal feature branch and step row on separate Y bands — minimum 40px gap between the branch line Y and the top of step boxes.

Icons On Connectors

When a small service icon sits close to a busy connector or arrow:

• Prefer icon-only and let the nearby node / edge label carry the meaning. Do not force a second label under the icon if it creates collisions.
• Move the icon 10-20px away from the connector centerline before shrinking it further.
• Keep the icon above the connector in z-order / draw order so the arrow does not cut through the symbol.
• If the connector already has a readable label, avoid repeating the same service name under the icon.

Alignment

• Align nodes in grid (gridSize=10)
• Center labels in nodes
• Use consistent node sizes
• Container with children → verticalAlign=top;spacingTop=5; to keep the label above child nodes
• Standalone box (no children) → verticalAlign=middle; to center text and avoid lopsided whitespace

Public-safe Labels

• For diagrams that may be published externally, avoid customer-specific or vendor-internal acronyms unless the acronym itself is the subject of the diagram.
• Prefer generic labels such as On-premises gateway, On-premises router, or Edge network over terms that only make sense in one customer's environment.
• If an internal acronym must appear somewhere, keep it in the surrounding article text, not as the primary label inside the figure.

Diagram Size

Always shrink-wrap: set page width/height to tightest bounding box + 20px margin.

Editable Source Policy

• Treat .drawio as the editable source of truth for documentation diagrams.
• Treat .drawio.svg as the delivery/render artifact for Markdown and web embedding.
• Do not label a plain SVG as .drawio.svg. That suffix is reserved for metadata-embedded SVG exports that Draw.io can reopen.
• If a diagram required manual SVG-level cleanup, recreate or preserve the equivalent .drawio source before calling it done.
• Do not leave a documentation diagram as SVG-only unless the user explicitly asked for a disposable one-off artifact.
• If the editor keeps resolving a stale path or refuses to open a file that exists, it is acceptable to create short alias filenames such as current-understanding.drawio and current-understanding.svg, then repoint local links to the alias pair.

Font Settings

fontSize=12;fontStyle=0;fontFamily=Helvetica;

For book/PDF diagrams that are scaled down by the publishing pipeline, raise the floor before export:

• Use at least 13px for minor labels, 15-17px for edge/action labels, and 17-23px for primary state or step nodes.
• Delete legend, tips, and sentence-like explanations from the figure when the surrounding text already explains them. Extra text shrinks the real teaching labels.
• Use dead whitespace to enlarge boxes and labels, then shrink-wrap the canvas. A wide empty margin makes every label smaller in the final PDF.
• Put arrow labels on their own lane, or remove labels already implied by nearby text. Never let a label hide the arrow shaft or arrowhead.
• For hierarchy diagrams, stack sparse sibling groups vertically when that lets labels and child boxes grow.
• For workflow diagrams, move trigger/source groups above the main workflow when side-by-side placement creates wasted width.

Export for PDF Pipelines

When diagrams are embedded in PDF (via Re:VIEW, LaTeX, Pandoc, etc.):

• Export directly from `.drawio` to PNG using the draw.io desktop CLI:

  draw.io --export --format png --scale 2 --output out.png source.drawio

• Do NOT use browser/Edge `--screenshot` on SVG — this produces a fixed-viewport capture (e.g., 756×488) regardless of diagram size, causing blurriness and cropping.
• --scale 2 produces 2× resolution for crisp text at print DPI.
• The exported SVG from draw.io CLI is "plain SVG" (not re-editable in the VS Code Draw.io extension). Keep the .drawio as the editable source.
• For Markdown preview, reference *.drawio.svg. For PDF build, use the PNG export.
• Render the final PDF page, not only the exported PNG. The publishing layer may scale, float, or move the image.
• If changing a wrapper macro does not affect image size, inspect generated TeX for per-image options such as width=\maxwidth. In that case, enlarge the diagram content and shrink-wrap the canvas instead of assuming the global width rule applies.