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
• Charts or infographics that require exact axes, data binding, typography, or scripted regeneration
• Large multilingual label sets whose font rendering must be identical across platforms
• Interactive or animated HTML diagrams, or Mermaid beautification (out of scope)

Prerequisites

Tool	Required
VS Code	Yes
Draw.io Integration	Yes
GitHub Copilot	Yes

Quick Start

Create a login flow diagram

Generate an Azure Hub-Spoke architecture diagram

From inputs/requirements.md, create a system diagram

Output Formats

Extension	Description	When to Use
*.drawio	Native format	Recommended
*.drawio.svg	SVG + metadata	Markdown/Web
*.drawio.png	PNG + metadata	Image with edit

Output: outputs/

If the user asks for an editable diagram, make *.drawio the primary deliverable. Do not let a plain SVG or preview artifact become the file the user is expected to edit.

Recommended Delivery Pattern

ドキュメント向けは name.drawio (editable) + name.drawio.svg (embed) を対で出す。多言語変体・Qiita への掲載・ローカル preview 脱出手順は → references/delivery-patterns.md。

Workflow

Treat generated images as optional layout references, not requirement evidence. Resolve labels, nodes, groups and edge directions in the manifest; flag ambiguity instead of inventing content. Rebuild native mxCells and connectors; wrapping a raster image in draw.io metadata does not make its elements editable.

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

Quality Gates

Score	Action
85-100	Proceed
70-84	Fix and retry
50-69	Simplify
0-49	Ask user

When the deliverable is headed for print, gate it on the Monochrome Print Profile and the Pre-delivery Geometry Sweep in style-guide.md before any visual review.

Limits

Limit	Value
Manifest revision	2
SVG revision	2
Total timeout	45min

Cloud Icons

Use Cloud Icons Reference. Azure diagrams must use verified img/lib/azure2/**/*.svg image paths, retain short service labels, and fall back to neutral boxes only when an icon is missing or misleading.

References

File	Description
mxcell-structure.md	mxCell XML structure
cloud-icons.md	Azure/AWS icon guide
style-guide.md	Node colors, edge styles
delivery-patterns.md	Editable + embed pair, Qiita, multilingual
troubleshooting.md	Full troubleshooting (24 items)

Scripts

Script	Description
scripts/validate_drawio.py	Validate mxCell structure

Troubleshooting

頻度高トップ 4 件を下記に掲載。全一覧（フレーム/エッジ/余白/PDF 出力、レジェンド位置、エスケープ層、CLI の export オプション 等 24 項目）は references/troubleshooting.md。

Issue	Solution
Blank in draw.io	Check content attribute
Edges not visible	Verify node IDs
Icons missing	Enable Azure/AWS shapes (+ More Shapes → Azure / AWS)
Text overlaps near outer frame	Inset top callout 16–24px, increase height, wrap to 3–4 lines; review at actual embed width

Done Criteria

• .drawio or .drawio.svg file generated
• Diagram opens correctly in VS Code Draw.io extension
• If an editable .drawio.svg is part of the delivery, it was exported with --embed-diagram and contains mxfile
• All nodes and edges visible
• User-facing links point to the editable .drawio when editability is expected
• Decision flows avoid long return/merge lines that bundle branch outputs back into one sink
• 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: no text overlap, clipping, or border collisions, no edges overlapping on one line, no edge endpoint buried inside a filled box, no label riding on a box or another label, no node outside the page
• After any edge or label layout change, re-export the delivery asset for the target medium (SVG for web, PNG or the final PDF for print) and inspect it; structural validation alone does not prove visual routing quality