draw.io Diagram Generation Skill

Overview

This skill enables generation of high-quality draw.io diagrams—especially Azure architecture diagrams—by directly editing XML. It applies:

• Azure best practices: Service naming, color palette, layering patterns
• WAF (Well-Architected Framework) thinking: Visual cues for security, reliability, performance, cost, and operations
• Audience-aware design: Execs see boundaries and risk; engineers see dataflows and services

When to Choose draw.io vs Other Formats

Use draw.io when: Customer expects a professional diagram for slides/docs, or you need Azure icons and precise control.

Quick Start

When creating a draw.io diagram:

1. Use Azure icon library (

   img/lib/azure2/...

   ) for official Azure icons
2. Set

   defaultFontFamily="Segoe UI"

   in

   mxGraphModel

   (Azure-style)
3. Use container patterns: gray fill for logical groups, white for service plans
4. Use correct layering order to avoid “missing arrows”:

• Background containers FIRST (tiers/boundaries, especially anything with a fillColor)
• Edges NEXT (connectors)
• Foreground vertices LAST (service icons/boxes + text labels)

5. Edges need terminals or points to render predictably:

• Use

  source="id" target="id"

  attributes (auto-routing), OR
• Use

  <mxPoint as="sourcePoint"/>

  and

  <mxPoint as="targetPoint"/>

  when an edge is not connected to a vertex

6. Use solid blue edges for data flow, dashed edges for monitoring/auth
7. Use separate text elements for arrow labels - NOT edge labels (see "Arrow Label Placement Rules")
8. Set

   labelBackgroundColor=none;

   (or specific color if needed) to avoid default white background artifacts
9. Set

   page="0"

   to disable page view (useful for transparent exports)
10. Align components for straight lines (same center y for horizontal, same center x for vertical)
11. Set

    dx

    /

    dy

    to keep the diagram origin in the top-left viewport (these are editor offsets, not canvas size)
12. Verify with PNG export

Azure Icon Library

draw.io includes official Azure icons at

img/lib/azure2/

Using Azure Icons

<!-- Azure icon with label below -->
<mxCell id="app-service" value="Web App"
  style="aspect=fixed;html=1;points=[];align=center;image;fontSize=12;image=img/lib/azure2/compute/App_Services.svg;labelPosition=center;verticalLabelPosition=bottom;verticalAlign=top;labelBackgroundColor=none;"
  vertex="1" parent="1">
  <mxGeometry x="100" y="100" width="64" height="64" as="geometry" />
</mxCell>

Key Icon Paths

img/lib/azure2/compute/App_Services.svg

img/lib/azure2/compute/Function_Apps.svg

img/lib/azure2/compute/Container_Instances.svg

img/lib/azure2/compute/Kubernetes_Services.svg

img/lib/azure2/databases/SQL_Database.svg

img/lib/azure2/databases/Azure_Cosmos_DB.svg

img/lib/azure2/databases/Cache_Redis.svg

img/lib/azure2/networking/Front_Doors.svg

img/lib/azure2/app_services/API_Management_Services.svg

img/lib/azure2/app_services/Search_Services.svg

img/lib/azure2/ai_machine_learning/AI_Studio.svg

img/lib/azure2/ai_machine_learning/Azure_OpenAI.svg

img/lib/azure2/identity/Azure_Active_Directory.svg

img/lib/azure2/management_governance/Monitor.svg

img/lib/azure2/analytics/Log_Analytics_Workspaces.svg

img/lib/azure2/devops/Application_Insights.svg

img/lib/azure2/integration/Service_Bus.svg

See [[reference]] for complete icon library paths with XML examples.

Full icon catalog: [[azure-icons]] lists all 648 Azure icons by category (for discovery when you need an icon not listed above).

Azure Architecture Principles

Layering (Left-to-Right Flow)

Structure diagrams with clear horizontal layers:

Users/Clients → Edge/Gateway → Compute/App → Data → External/Dependencies
     ↓              ↓             ↓          ↓            ↓
  (left)     APIM/FrontDoor   App/AKS/ACA  Cosmos/SQL   3rd party

Trust Boundaries (Always Show)

Every Azure diagram should show:

• Internet / Untrusted: External clients, public endpoints
• Azure Subscription / VNet: Your private network boundary
• Data plane vs Control plane: Where management vs runtime traffic flows
• On-prem / Customer Network: If hybrid connectivity exists

Use dashed rectangles or grouped containers for boundaries:

<!-- Trust boundary container -->
<mxCell id="vnet-boundary" value="Azure VNet (Private)" 
  style="rounded=0;whiteSpace=wrap;html=1;dashed=1;dashPattern=8 4;fillColor=none;strokeColor=#0078D4;strokeWidth=2;verticalAlign=top;fontFamily=Segoe UI;fontSize=14;fontStyle=1;"
  vertex="1" parent="1">
  <mxGeometry x="200" y="80" width="400" height="300" as="geometry" />
</mxCell>

Non-Azure Entities (Generic Shapes)

CRITICAL: Don't use Azure icons for non-Azure things. Use generic shapes:

fillColor=#E6E6E6;strokeColor=#666666;

shape=actor;

shape=actor

shape=cloud;

<!-- On-Premises (generic gray box) -->
<mxCell id="onprem" value="On-Premises"
  style="rounded=1;whiteSpace=wrap;html=1;fillColor=#E6E6E6;strokeColor=#666666;fontFamily=Segoe UI;fontSize=12;fontStyle=1;labelBackgroundColor=none;"
  vertex="1" parent="1">
  <mxGeometry x="40" y="145" width="100" height="50" as="geometry" />
</mxCell>

<!-- External Users (Persona Icon) -->
<mxCell id="user-persona" value="Customer"
  style="shape=actor;whiteSpace=wrap;html=1;fillColor=#D4E1F5;strokeColor=#0078D4;fontFamily=Segoe UI;fontSize=12;labelPosition=center;verticalLabelPosition=bottom;verticalAlign=top;"
  vertex="1" parent="1">
  <mxGeometry x="40" y="160" width="30" height="60" as="geometry" />
</mxCell>

Avoid:

On_Premises_Data_Gateways.svg

Azure Color Palette

#E8F4FD

#0078D4

#E6F4EA

#107C10

#F3E8FF

#8661C5

#E0F7FA

#008272

#FFF4E5

#FF8C00

#E3F2FD

#1976D2

#FFF8E1

#FFC107

#FFEBEE

#D32F2F

Service Naming Convention

Name boxes by role first, then service:

• ✅ "API Gateway (APIM)"
• ✅ "App Backend (Container Apps)"
• ✅ "Vector Store (AI Search)"
• ❌ "Azure API Management" (too generic)
• ❌ "apim-prod-westeu-001" (too specific)

Flow Numbering

Number flows 1→N for readability. Label arrows with intent, not protocol:

• ✅ "1. User authenticates"
• ✅ "2. Query knowledge base"
• ✅ "3. Generate response"
• ❌ "HTTPS 443"
• ❌ "REST API call"

Edge Patterns (Arrows)

DECISION POINT: You are NOT required to use arrows for every relationship.

• Use Arrows for: Data flow, network connectivity, sequence of operations.
• skip Arrows when:
  • Containment implies relationship (e.g., App Service inside a VNet).
  • Proximity is clear enough (e.g., an "Identity" label next to Entra ID).
  • Clutter would result from too many lines (matrix of connections).
  • Grouping shows the association (e.g., all services in a "Management" box).

Be decisive: If the diagram is cleaner without an arrow, omit it.

Use consistent arrow styles to distinguish flow types:

Data Flow (Solid Blue)

Primary request/response flow through the architecture:

style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;labelBackgroundColor=none;"

Monitoring / Diagnostic Flow (Dashed)

Telemetry, logs, and metrics flowing to monitoring services:

style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;dashed=1;labelBackgroundColor=none;"

Authentication / External Service Flow (Dashed)

Calls to identity providers, DNS, external APIs. If you need a label, use a separate text element (see "Arrow Label Placement Rules").

style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;dashed=1;labelBackgroundColor=none;"

Cache / Return Flow (Directional)

Data retrieval from cache or return paths:

style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;endArrow=classic;endFill=0;fillColor=#dae8fc;strokeColor=#6c8ebf;labelBackgroundColor=none;"

Use a second edge in the opposite direction if you need an explicit return path.

Edge Label Positioning

⚠️ WARNING: Edge labels (

value="..."

on edges) have unreliable positioning. The offset values are inconsistent and labels often end up ON the line or in wrong positions. Use separate text elements instead - see "Arrow Label Placement Rules" section below for exact formulas.

Legacy approach (NOT RECOMMENDED):

<!-- Label BELOW the line (positive y offset) - UNRELIABLE -->
<mxCell id="flow1" value="1. Auth" edge="1" 
  style="edgeStyle=orthogonalEdgeStyle;rounded=0;...">
  <mxGeometry relative="1" x="-0.3" y="15" as="geometry">
    <mxPoint as="offset" />
  </mxGeometry>
</mxCell>

Recommended approach: Use separate text elements with calculated positions. See "Arrow Label Placement Rules" section.

Explicit Edge Endpoints

⚠️ CRITICAL: Edges should have connection information for predictable rendering. Use EITHER:

• source="vertex-id"

  and

  target="vertex-id"

  attributes (auto-connects to cell centers), OR

• <mxPoint x="..." y="..." as="sourcePoint" />

  and

  <mxPoint ... as="targetPoint" />

  elements (explicit coordinates)

Edges missing BOTH can render invisibly.

For precise control over where arrows start/end (instead of auto-connecting to cell centers):

<!-- Option 1: Reference vertex IDs (auto-routing) -->
<mxCell id="flow1" edge="1" source="apim" target="app"
  style="edgeStyle=orthogonalEdgeStyle;rounded=0;...">
  <mxGeometry relative="1" as="geometry" />
</mxCell>

<!-- Option 2: Explicit coordinates (precise control) -->
<mxCell id="flow4" edge="1"
  style="edgeStyle=orthogonalEdgeStyle;rounded=0;...">
  <mxGeometry relative="1" as="geometry">
    <mxPoint x="468" y="196" as="sourcePoint" />
    <mxPoint x="560" y="196" as="targetPoint" />
  </mxGeometry>
</mxCell>

<!-- Option 3: Mixed (source vertex, explicit target) -->
<mxCell id="flow3" edge="1" source="apim"
  style="edgeStyle=orthogonalEdgeStyle;rounded=0;...">
  <mxGeometry relative="1" as="geometry">
    <mxPoint x="400" y="196" as="targetPoint" />
  </mxGeometry>
</mxCell>

Use explicit sourcePoint/targetPoint when:

• Icons have inconsistent anchor points
• You need arrows to connect at specific spots (not center)
• Auto-routing creates awkward paths
• Edge has no source/target vertex to reference

Minimizing Edge Bends

Cleaner diagrams have fewer bends in edges. Apply these principles:

1. Align Components for Straight Lines

Position components so most connections are straight (0 bends) or have 1 bend max:

GOOD: Components aligned → straight arrow
┌──────┐         ┌──────┐
│  A   │────────▶│  B   │
└──────┘         └──────┘

BAD: Misaligned → multiple bends
┌──────┐
│  A   │──┐
└──────┘  │
          └──────▶┌──────┐
                  │  B   │
                  └──────┘

Pro tip: Match y-coordinates within 5px (e.g., source at y=118, target at y=115) → virtually straight horizontal arrow. Small differences are acceptable; large gaps create bends.

For vertical connections (exitX=0.5 → entryX=0.5 or entryY=0), align component centers exactly:

source_center_x = source.x + (source.width / 2)
target.x = source_center_x - (target.width / 2)

Example: Functions at x=400, width=68 → center=434. Monitor (width=64) should be at x=402 (402+32=434).

2. Use Grid-Based Layout

• Place components on a consistent grid (e.g., x increments of 150-200px)
• Align rows by center: same

  (y + height/2)

  for a clean horizontal line
• Align columns by center: same

  (x + width/2)

  for a clean vertical line

3. Edge Routing Style

Use

edgeStyle=orthogonalEdgeStyle

• Horizontal flow: Place source and target at the same center y → 0 bends
• Vertical flow: Place source and target at the same center x → 0 bends
• Diagonal relationship: Accept 1-2 bends, not more

4. When Bends Are Necessary

If a bend is unavoidable (e.g., routing around obstacles):

• Use consistent bend points (e.g., all horizontal segments at y=200)
• Avoid overlapping edges by staggering bend points (+10px offset each)
• Consider

  curved=1

  for softer appearance (but use sparingly)

<!-- Orthogonal edge with one clean bend -->
style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;"

<!-- Curved edge (softer, but can be harder to follow) -->
style="edgeStyle=orthogonalEdgeStyle;curved=1;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;"

5. Layout Validation

Before finalizing:

• Most edges have 0-1 bends
• No edges with 3+ bends (redesign component positions)
• No overlapping edge segments
• Flow direction is clear (left→right or top→bottom)

Arrow Label Placement Rules (MANDATORY)

CRITICAL: Do NOT use edge labels (

value="..."

Why Separate Text Elements?

Edge labels have unpredictable behavior:

• Position depends on edge routing (changes when components move)
• Offset values (

  x

  ,

  y

  in geometry) behave inconsistently
• Labels can end up ON the line, making them unreadable

Solution: Create

<mxCell style="text;...">

x

y

Horizontal Arrow Labels

Rule: ALL labels for horizontal arrows go ABOVE the line.

Calculation:

arrow_y = source_y + (source_height / 2)  // horizontal center of icons
label_y = arrow_y - 25                      // 25px above the arrow
label_x = ((source_x + source_width) + target_x) / 2 - (label_width / 2)  // centered

Example:

Source icon: x=240, width=65  → right edge = 305
Target icon: x=398            → left edge = 398
Arrow y ≈ 219 (icon centers)

label_x = (305 + 398) / 2 - (60 / 2) = 351.5 - 30 = 321
label_y = 219 - 25 = 194

<mxCell id="label3" value="3. Route"
  style="text;html=1;align=center;verticalAlign=middle;fontFamily=Segoe UI;fontSize=11;labelBackgroundColor=none;fontColor=#0078D4;"
  vertex="1" parent="1">
  <mxGeometry x="321" y="194" width="60" height="20" as="geometry" />
</mxCell>

Vertical Arrow Labels

Rule: ALL labels for vertical arrows go TO THE RIGHT of the line.

Calculation:

arrow_x = source_x + (source_width / 2)     // vertical center of icons
label_x = arrow_x + 20                        // 20px to the right
label_y = ((source_y + source_height) + target_y) / 2 - (label_height / 2)  // centered

Example:

Source icon: x=540, width=64, y=185, height=68  → center_x=572, bottom=253
Target icon: y=350                               → top=350

label_x = 572 + 20 = 592 (round to 595)
label_y = (253 + 350) / 2 - 10 = 301.5 - 10 = 291 (round to 290)

<mxCell id="label5" value="5. Search"
  style="text;html=1;align=left;verticalAlign=middle;fontFamily=Segoe UI;fontSize=11;labelBackgroundColor=none;fontColor=#107C10;"
  vertex="1" parent="1">
  <mxGeometry x="595" y="290" width="60" height="20" as="geometry" />
</mxCell>

Boundary Crossing Rules

When an arrow crosses a container boundary (e.g., VNet), place the label on the source side of the boundary with 5px clearance.

Rules:

• Left → Right into a boundary:

  label_right_edge < boundary_x - 5

• Right → Left into a boundary:

  label_left_edge > boundary_right + 5

• Top → Bottom into a boundary:

  label_bottom < boundary_y - 5

• Bottom → Top into a boundary:

  label_top > boundary_bottom + 5

Example: Arrow from Users (external) to APIM (inside VNet at x=200)

VNet boundary x = 200
label_width = 65
label_right_edge must be < 195

label_x = 195 - 65 = 130  ✓ (label ends at 195, 5px before VNet)

<!-- Label for arrow crossing INTO VNet - placed outside -->
<mxCell id="label2" value="2. Request"
  style="text;html=1;align=center;verticalAlign=middle;fontFamily=Segoe UI;fontSize=11;labelBackgroundColor=none;fontColor=#0078D4;"
  vertex="1" parent="1">
  <mxGeometry x="130" y="194" width="65" height="20" as="geometry" />
</mxCell>

Icon Label Clearance from Boundaries

Icon labels (below icons using

verticalLabelPosition=bottom

Rule:

icon_y + icon_height + 18 (label) + 40 (clearance) < container_bottom

Example:

VNet bottom = 460 (y=40, height=420)
Required clearance = 40px
Label height ≈ 18px

Maximum icon bottom = 460 - 40 - 18 = 402
If icon height = 52, max icon_y = 402 - 52 = 350

Component Alignment for Straight Lines

Horizontal flows: Align icon centers at the same y (

y + height/2

apim_y = 189      (height=60)  → center = 219
app_y = 185       (height=68)  → center = 219  ✓
foundry_y = 185   (height=68)  → center = 219  ✓
openai_y = 185    (height=68)  → center = 219  ✓

Vertical flows: Icons at same x-center.

source: x=540, width=64  → center = 572
target: x=536, width=72  → center = 572  ✓ (536 + 72/2 = 572)

Quick Reference Table

align=center

align=left

Validation Checklist

Before finalizing labels:

• All horizontal labels at consistent y (same row = same label_y)
• All vertical labels at consistent x offset (+20px from arrow)
• No labels crossing container boundaries
• No labels overlapping icons or other labels
• Icon labels have 40px clearance from container bottom

Container & Grouping Patterns

Enterprise diagrams use containers for logical structure:

Resource Group Boundary (Outer Dashed)

Wraps entire diagram to show scope:

style="rounded=0;whiteSpace=wrap;html=1;fillColor=none;dashed=1;labelBackgroundColor=none;"

Logical Tier Container (Gray Fill, No Stroke)

Groups related services (App Tier, Data Tier, Monitoring):

style="rounded=0;whiteSpace=wrap;html=1;dashed=1;labelBackgroundColor=none;fillColor=#E6E6E6;strokeColor=none;"

Service Plan Group (White Container)

Groups service with its hosting plan (e.g., App Service in App Service Plan):

<!-- Parent group (connectable="0") -->
style="group;labelBackgroundColor=none;strokeColor=none;"

<!-- White inner container with label -->
style="rounded=0;whiteSpace=wrap;html=1;dashed=1;labelBackgroundColor=none;fillColor=#FFFFFF;labelPosition=center;verticalLabelPosition=top;align=center;verticalAlign=bottom;spacingBottom=-35;strokeColor=none;"
value="App Service Plan"

See [[reference]] for complete grouping patterns with XML examples.

Comparison Diagrams (Current vs Target)

When showing "before and after" or "current vs target" architectures:

Layout Pattern

• Use two side-by-side containers of equal width
• Left = Current State (use orange/red border:

  strokeColor=#E65100;

  )
• Right = Target State (use green border:

  strokeColor=#2E7D32;

  )
• Add clear title labels at top of each container
• Maintain consistent vertical alignment between sides

Color Psychology

#E65100

#FFF3E0

#2E7D32

#E8F5E9

#666666

#F5F5F5

#0078D4

#E8F4FD

Annotations (Warnings, Checkmarks, Benefits)

DON'T: Float warning text loosely next to boxes DO: Use styled annotation boxes or embed in the component

<!-- Warning annotation (red box, attached to component) -->
<mxCell id="warning1" value="⚠ No OCR&#xa;⚠ Images skipped"
  style="rounded=1;whiteSpace=wrap;html=1;fontFamily=Segoe UI;fontSize=11;fillColor=#FFEBEE;strokeColor=#D32F2F;fontColor=#C62828;align=left;spacingLeft=5;"
  vertex="1" parent="1">
  <mxGeometry x="200" y="150" width="100" height="40" as="geometry" />
</mxCell>

<!-- Benefit annotation (green box, attached to component) -->
<mxCell id="benefit1" value="✓ Full OCR + images&#xa;✓ Table extraction"
  style="rounded=1;whiteSpace=wrap;html=1;fontFamily=Segoe UI;fontSize=11;fillColor=#E8F5E9;strokeColor=#2E7D32;fontColor=#1B5E20;align=left;spacingLeft=5;"
  vertex="1" parent="1">
  <mxGeometry x="500" y="150" width="120" height="40" as="geometry" />
</mxCell>

Text & Box Sizing Rules

Avoid text overflow and cramped layouts:

Calculate Box Width

• English text: ~7-8px per character for

  fontSize=12

• Minimum width: 80px for any labeled box
• Multi-line: Use

  whiteSpace=wrap;

  and set a fixed width
• Rule of thumb: Width = (longest line chars × 8) + 20px padding

Example: Fitting "Python Library (No OCR, No Images)"

• 35 characters × 8px = 280px + 20px padding = ~300px minimum width
• Or split to 2 lines: "Python Library" + "(No OCR, No Images)" → width ~150px

Nested Container Spacing

• Minimum padding: 15px between parent container edge and child boxes
• Minimum gap: 10px between sibling boxes
• Label clearance: 25px from top of container to first child (for title)

<!-- Container with proper padding -->
<mxCell id="container" value="Document Processing"
  style="rounded=0;whiteSpace=wrap;html=1;fillColor=#E8F5E9;strokeColor=#2E7D32;verticalAlign=top;fontFamily=Segoe UI;fontSize=14;fontStyle=1;spacingTop=5;"
  vertex="1" parent="1">
  <mxGeometry x="400" y="60" width="280" height="200" as="geometry" />
</mxCell>

<!-- First child 15px from edges, 25px from top (after label) -->
<mxCell id="child1" ...>
  <mxGeometry x="415" y="95" width="100" height="60" as="geometry" />
</mxCell>

Title & Subtitle Pattern

Don't cram metadata into the title. Use a separate subtitle text element:

<!-- Main title -->
<mxCell id="title" value="CZ AI Platform: Current vs Target Architecture"
  style="text;html=1;align=center;fontFamily=Segoe UI;fontSize=20;fontStyle=1;labelBackgroundColor=none;"
  vertex="1" parent="1">
  <mxGeometry x="200" y="10" width="500" height="30" as="geometry" />
</mxCell>

<!-- Subtitle (audience, date) -->
<mxCell id="subtitle" value="Audience: D&amp;A Leadership | Jan 28, 2026"
  style="text;html=1;align=center;fontFamily=Segoe UI;fontSize=12;fontColor=#666666;labelBackgroundColor=none;"
  vertex="1" parent="1">
  <mxGeometry x="200" y="38" width="500" height="20" as="geometry" />
</mxCell>

WAF-Aligned Design

When relevant, highlight 1-3 WAF pillars that are in scope for the audience and design:

Security (Show These)

• Trust boundaries (VNet, private endpoints)
• Identity flow (Entra ID → Managed Identity → services)
• Data encryption indicators (lock icons or labels)
• Private endpoints for PaaS services (if required by the security design)

Reliability (Show These)

• Multi-region or zone redundancy (if in scope)
• Failover paths (if in scope)
• Health probes / monitoring connections
• Circuit breaker patterns

Performance (Show These)

• Caching layers (Redis, CDN) when performance is a goal
• Async patterns (queues, events) when decoupling is in scope
• Regional distribution (if in scope)
• Autoscaling indicators (if known)

Cost Optimization (Show These)

• Reserved vs on-demand annotations (if decided)
• Spot VM indicators (if decided)
• Tier choices (Premium vs Standard) when known
• Shared services when relevant

Operational Excellence (Show These)

• Monitoring/logging connections (dotted lines to Azure Monitor)
• Deployment pipelines (if in scope)
• Alert paths (if in scope)

Audience-Focused Diagrams

For Executives

• Emphasize: Trust boundaries, data residency, compliance zones, business flows
• Minimize: Technical details, specific service names, internal connections
• Style: Larger boxes, fewer elements (5-8 max), clear "in/out" boundaries

For Architects

• Emphasize: Relevant WAF pillars, service interactions, scaling hints
• Minimize: Implementation details, exact configurations
• Style: Medium detail (8-14 elements), numbered flows, boundary labels

For Engineers

• Emphasize: Exact services, APIs, data flows, connection strings, ports
• Add: Schema hints, retry policies, timeout values
• Style: High detail, service-specific icons, subnet/NSG visibility

Core Rules

Font Settings

<!-- In mxGraphModel -->
<mxGraphModel defaultFontFamily="Segoe UI" page="0" ...>

<!-- In EVERY text element's style -->
<mxCell style="text;fontFamily=Segoe UI;fontSize=14;..." />

Element Ordering (Z-Order)

Note: The Quick Start section above has the authoritative z-order rule. This section provides additional context.

Elements render in XML declaration order (first = bottom layer). For diagrams with filled containers (like gray tier backgrounds), the correct order is:

1. Background containers (boundaries, tiers with

   fillColor

   )
2. Edges (arrows/connectors)
3. Foreground vertices (service icons, text labels)

This prevents arrows from being hidden behind filled containers.

<root>
  <mxCell id="0" />
  <mxCell id="1" parent="0" />

  <!-- 1. CONTAINERS FIRST (filled backgrounds) -->
  <mxCell id="tier1" style="fillColor=#E6E6E6;..." vertex="1" ... />

  <!-- 2. EDGES NEXT (render above containers) -->
  <mxCell id="arrow1" edge="1" ... />

  <!-- 3. VERTICES LAST (render on top) -->
  <mxCell id="icon1" vertex="1" ... />
</root>

Label-Arrow Spacing

Labels must be at least 20px away from arrow lines:

<!-- Arrow at Y=220 -->
<mxCell id="arrow">
  <mxGeometry>
    <mxPoint y="220" as="sourcePoint"/>
  </mxGeometry>
</mxCell>

<!-- Label at Y=180 (40px above arrow) - CORRECT -->
<mxCell id="label" value="Process">
  <mxGeometry y="180" width="60" height="20" />
</mxCell>

Multi-byte Text Width

Allocate sufficient width to prevent unwanted line breaks:

<!-- 8 Japanese characters × 35px = 280px minimum -->
<mxCell id="title" value="システム構成図">
  <mxGeometry width="300" height="40" />
</mxCell>

Instruction Template

When asked to create a draw.io diagram:

1. Clarify audience: Exec overview vs architect detail vs engineer spec?
2. Identify scope: Context (high-level) vs Container (services) vs Component (internal)?
3. Gather components: Which Azure services? What trust boundaries?
4. Plan WAF elements: Which pillars to emphasize (if applicable)?
5. Generate XML with all rules applied
6. Verify with PNG export

PNG Verification

Always recommend PNG export for visual verification:

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

# Linux
drawio -x -f png -s 2 -t -o output.png input.drawio
xdg-open output.png

# Windows (PowerShell)
& "$env:ProgramFiles\draw.io\draw.io.exe" -x -f png -s 2 -t -o output.png input.drawio
Start-Process output.png

Supporting Files

• [[reference]] - Complete XML structure reference with Azure shapes
• [[examples]] - Production-ready Azure architecture examples
• [[checklist]] - Pre-commit validation checklist (including WAF)
• [[azure-icons]] - Full Azure icon catalog (by category)

MCP Tool Integration

When draw.io MCP tools are available, use them with these exact parameter formats:

mcp_drawio_create_new_diagram

Create a new diagram from scratch. Provide complete

mxGraphModel

{
  "xml": "<mxGraphModel dx=\"800\" dy=\"600\" ...><root>...</root></mxGraphModel>"
}

mcp_drawio_edit_diagram

Edit existing diagram by operations. Always call

mcp_drawio_get_diagram

{
  "operations": [
    {
      "operation": "add",
      "cell_id": "new-cell-1",
      "new_xml": "<mxCell id=\"new-cell-1\" value=\"Label\" ... />"
    },
    {
      "operation": "update",
      "cell_id": "existing-id",
      "new_xml": "<mxCell id=\"existing-id\" value=\"New Label\" ... />"
    },
    {
      "operation": "delete",
      "cell_id": "cell-to-remove"
    }
  ]
}

Common mistake: Using

changes

operations

op

operation

• Top-level array:

  operations

• Each item:

  operation

  (enum: "add", "update", "delete"),

  cell_id

  ,

  new_xml

  (except delete)

Workflow

1. mcp_drawio_start_session

   - Opens browser preview

2. mcp_drawio_create_new_diagram

   - Create initial diagram

3. mcp_drawio_get_diagram

   - Fetch current state (before edits)

4. mcp_drawio_edit_diagram

   - Apply changes

5. mcp_drawio_export_diagram

   - Save to .drawio file