drawio-diagram

Files (15)

• SKILL.md
• openai.yaml · agents/
• evals.json · evals/
• aws4-icons.md · references/
• aws4-shapes.txt · references/
• example-aws.drawio · references/examples/
• example-generic.drawio · references/examples/
• export.md · references/
• style-guide.md · references/
• verification.md · references/
• .gitignore · scripts/
• export-png.mjs · scripts/
• export-png.test.mjs · scripts/
• package-lock.json · scripts/
• package.json · scripts/

SKILL.md (first lines)

# Draw.io Diagram Skill

Work with .drawio architecture diagrams — create, clean up, analyze, and fix.

## Input

The user provides a path to a `.drawio` file (or it can be inferred from the current project context).

## Style Reference

Read [references/style-guide.md](references/style-guide.md) for shape conventions, color scheme, arrow semantics, and label formatting. Load it when creating diagrams, checking visual consistency, or adding new elements.

## Examples (for creating from scratch)

When creating a new diagram, read the appropriate example and reuse its exact style strings:

- **Generic architecture**: [references/examples/example-generic.drawio](references/examples/example-generic.drawio) — all common shapes (rounded rect, cylinder, hexagon, parallelogram, cloud, swimlane, queue), color roles, and arrow styles (solid, dashed, dotted)
- **AWS architecture**: [references/examples/example-aws.drawio](references/examples/example-aws.drawio) — `mxfile` wrapper, `mxgraph.aws4` icon shapes (ECS, Fargate, Lambda, Aurora, OpenSearch, S3, Secrets Manager, Bedrock, ECR) using both `resourceIcon` and `productIcon` patterns, containment hierarchy (AWS Cloud → VPC → AZ → Public/Private Subnet), NAT Gateway, external actors (Users, Internet cloud), 3 arrow types (solid network, dashed internal, `dashPattern=8 8` service integration with service-colored strokes), and legend box

Copy style strings character-for-character from examples — the `mxgraph.aws4` styles are complex and must be exact.

**AWS icon lookup**: Grep [references/aws4-shapes.txt](references/aws4-shapes.txt) to find the exact shape name for any AWS service (1032 shapes, Jan 2026). Convert spaces to underscores for `resIcon`/`prIcon` values. See [references/aws4-icons.md](references/aws4-icons.md) for category colors and group container shapes.

## Approach

**Edit the XML directly.** Parse it, compute positions mathematically, identify violations, and write corrected XML. For PNG export and visual verification, use the bundled [scripts/export-png.mjs](scripts/export-png.mjs): it renders locally with Draw.io's viewer and an existing Chromium, without Electron. See [references/export.md](references/export.md) for setup, options, and limitations.

**Analysis-first workflow**: Complete Phase 1 (position computation) and identify ALL violations across Phases 2-4 BEFORE making any changes. This prevents cascading surprises (e.g., nudging a node for label clearance on one edge may shrink the gap on an adjacent labeled edge).

**Applying changes**: When fewer than 5 edits are needed, use the Edit tool. When 5+ edits are needed (common for a full cleanup pass), use the Write tool to output the entire corrected file in one shot — this avoids uniqueness conflicts with repeated patterns like `x="15"`.

**Cascade principle**: After any node position change, immediately re-check: (1) all edges to/from the moved node for label clearance and gap violations, (2) container padding if inside a group, (3) proportional spacing with siblings. Moving a node to fix one issue can create violations elsewhere — compute the full cascade chain before applying.

## Triage

Before diving into the workflow, assess the diagram and clarify scope with the user if needed.

**Ask the user when:**
- The diagram has **3+ distinct arrow styles** — ask: "This diagram uses semantic arrow styles (solid=sync, dashed=async, dotted=scheduled, thick-red=critical path). Should I preserve these conventions, or normalize to a simpler scheme?"
- The diagram has **no legend** but uses 4+ shape/color types — ask: "This diagram uses N distinct visual styles but has no legend. Should I add one?"
- The task is ambiguous between **cleanup vs. creation** — ask: "Should I clean up the existing layout, or restructure/rebuild the diagram?"
- The diagram uses **`page=0`** (infinite canvas) — note this in analysis; spacing rules still apply but there are no page bounds to check against.

**Do NOT ask when:**
- The user gave a specific task ("fix alignment", "add a legend", "clean up connectors")
- The diagram is simple (<15 nodes) with a single arrow style
- You're running the full cleanup workflow (just execute it)

**Creation triage** (when building a diagram from scratch):

1. **Diagram type** — ask which focus:
   - Architecture overview (services, databases, integrations, data flow)
   - Network topology (VPCs, subnets, security groups, NACLs, routing tables)
   - Deployment / infrastructure (containers, Fargate, ALBs, auto-scaling groups)
   - Data flow / ETL pipeline (S3, Kinesis, Lambda, Glue, Redshift)
   - Security (IAM, WAF, KMS, encryption, GuardDuty)
   - CI/CD pipeline (build → test → deploy stages)
   - Process / sequence flow (step-by-step workflow, state machines, decisions)

2. **External actors** — what connects from outside? (users, Internet, third-party APIs, other AWS accounts, on-premises)

3. **Backing services** — any databases, caches, storage, queues, or AI/ML services?

4. **Connection patterns** — main data flows? (request path, async events, scheduled jobs, replication)

**Mermaid fast-path assessment** — after gathering the above, assess whether native XML or Mermaid-then-convert is better. Tell the user your recommendation and why:

| Signal | Recommendation |
|--------|---------------|
| Simple flowchart, sequence, or state diagram with <15 nodes | **Mermaid** — faster, auto-layout handles it well |
| Org chart or tree hierarchy | **Mermaid** — `graph TD` or CSV import handles this naturally |
| Needs AWS/cloud icons, custom shapes, or `mxgraph.*` stencils | **XML** — Mermaid has no icon library support |
| Needs precise positioning (subnet containment, AZ grouping) | **XML** — Mermaid auto-layout can't do nested containers |
| Needs specific colors, line styles, or legend | **XML** — Mermaid styling is limited |
| >20 nodes with complex cross-connections | **XML** — Mermaid auto-layout gets messy at scale |
| Mixed: simple flow + a few custom shapes | **XML** — partial Mermaid doesn't save effort |

Example recommendation: "This is a 3-AZ AWS architecture with subnets, Fargate, and ALB — I'd recommend native XML because we need AWS icon shapes and nested containment groups. Mermaid can't do that."

Example recommendation: "This is a straightforward CI/CD pipeline with 6 sequential stages — Mermaid would be faster here and auto-layout will handle it cleanly. Want me to use Mermaid?"

**When using Mermaid**: Write a `.mmd` file with the Mermaid source code. Tell the user to import it into draw.io via **Extras > Edit Diagram**, paste the Mermaid code, and click OK — draw.io converts it to native shapes. After import, the diagram becomes editable draw.io XML (the original Mermaid source is not preserved). Note: there is no reliable way to embed Mermaid in a `.drawio` XML file that auto-renders on open.

## Phase 1: Parse & Compute

### 1. Read and Parse the XML

Read the `.drawio` file. Identify:
- **File wrapper**: The file may be bare `<mxGraphModel>` or wrapped in `<mxfile><diagram>...<mxGraphModel>`. The `<mxfile>` wrapper is standard for draw.io desktop (includes `host`, `agent`, `version` metadata) and is required for multi-diagram files. When creating files, use the `<mxfile>` wrapper for compatibility. When editing, preserve whichever wrapper the file already uses.
- `page` attribute from `<mxGraphModel>`: `page=1` (fixed page, check bounds) vs `page=0` (infinite canvas, skip page bounds)
- `pageWidth` / `pageHeight` from `<mxGraphModel>`: choose based on diagram complexity. Common sizes: 1169x827 (A4 landscape, simple), 1400x1000 (medium), 1600x1200 (complex with detail panels). When creating, pick the smallest size that fits with comfortable margins.
- `gridSize` from the `<mxGraphModel>` attributes (typically 10)
- All vertex cells (`vertex="1"`) — extract id, value (label), parent, style, and geometry (x, y, width, height)
- All edge cells (`edge="1"`) — extract id, value (label), parent, source, target, style, and any waypoints (`<mxPoint>` inside `<Array as="points">`)
- **Edge label child cells**: draw.io's interactive editor creates labels as separate `edgeLabel` cells with `connectable="0"` and `parent` set to the edge ID, rather than setting `value` on the edge itself. Detect both patterns. See Label Formatting in style-guide.md for the full XML structure.
- Parent hierarchy: cells with `parent="1"` are top-level; cells whose parent is another vertex are children of that container/group
- **Visual-only groups** (`container=0`): Some group cells use `container=0;connectable=0` — these are visual boundary boxes only. Their "children" are NOT parented to the group in XML (they use `parent="1"`). These groups affect visual appearance but NOT the coordinate system. During position computation, do NOT recurse into `container=0` groups for child offsets — treat their enclosed nodes as top-level.

### 2. Compute Absolute Positions

Build an absolute position table for every node. Children of groups/containers have positions **relative to the parent**, so add the parent's absolute position:

```
absolute_x = parent_abs_x + child_relative_x
absolute_y = parent_abs_y + child_relative_y
center_x   = absolute_x + width / 2
center_y   = absolute_y + height / 2
```

For nested groups, recurse up the parent chain. Top-level nodes (parent="1") use their geometry directly.

**Output the positions as a table** grouped by parent, showing: ID, Label, Absolute (x,y), Size (w*h), Center (cx,cy), Shape type. This table is the foundation for all subsequent analysis.

**Also compute edge endpoints**: For each edge, determine the absolute positions of source and target, then compute `dx = |target_center_x - source_center_x|` and `dy = |target_center_y - source_center_y|`.

---

## Phase 2: Spacing & Layout

From DimmKirr/skills, MIT.

More from DimmKirr/skills