Workbuddy Visio — Visio-Compatible Architecture Diagrams

Overview

Generate professional architecture diagrams with a dual-format approach: .drawio as the editable master, then SVG for Visio import. This skill was learned from an existing Codex skill (visio-drawio-svg-diagrams) after failed attempts with raw SVG generators — Microsoft Visio is notoriously picky about SVG input, and the drawio_to_svg.py converter handles its specific requirements.

Core workflow:
1. Write a Python script to generate a .drawio file (uncompressed inline XML)
2. Run drawio_to_svg.py to produce a Visio-compatible SVG
3. Open the SVG in Visio — or open the .drawio in draw.io for further editing

Workflow

Step 1: Generate .drawio

Write a Python script using xml.etree.ElementTree. The draw.io format uses <mxCell> elements:
- vertex="1" for shapes/boxes
- edge="1" for connection lines

Key formatting rules:
- Use \n in Python string values for multi-line text (NOT <br> tags)
- In raw XML use 
 as newline character entity
- Every mxCell except id="0" and id="1" needs parent="1"
- For stable line placement, use fixed point edges with sourcePoint/targetPoint

Vertex (shape/box) example:

<mxCell id="100" parent="1" vertex="1"
  value="Title
Body line 1
Body line 2"
  style="rounded=1;whiteSpace=wrap;html=1;fillColor=#E8F4FC;strokeColor=#90C8E8;strokeWidth=1.5;fontSize=11;fontStyle=1">
  <mxGeometry x="50" y="100" width="240" height="80" as="geometry"/>
</mxCell>

Edge (connection line) example:

<mxCell id="200" parent="1" edge="1"
  value="EtherCAT"
  style="endArrow=block;html=1;strokeColor=#2E8B57;strokeWidth=2;fontSize=9;fontColor=#2E8B57">
  <mxGeometry relative="1" as="geometry">
    <mxPoint x="170" y="180" as="sourcePoint"/>
    <mxPoint x="170" y="240" as="targetPoint"/>
  </mxGeometry>
</mxCell>

Step 2: Convert to SVG

python <skill-dir>/scripts/drawio_to_svg.py input.drawio output.svg

The converter produces SVG with:
- Fixed point edges matching draw.io layout
- clipPath per box to contain text within bounds
- Responsive typography: height-based font sizing
- ≤52px → compact mode (11pt title, 10pt body)
- 52–70px → 13pt/11pt
- 70–90px → 15pt/12pt
- ≥90px → 18pt/13pt
- CJK/Latin-aware text wrapping
- Arrow markers and dashed line support

Step 3: Validate

Before delivery, verify:
- .drawio parses as valid XML and contains inline <mxGraphModel>
- Every <mxGeometry> uses as="geometry" (not as_="geometry")
- UTF-8 encoding preserved for Chinese labels
- SVG parses as valid XML
- No text overflows box boundaries in the rendered SVG
- Lines match the draw.io layout

Style Parameters Reference

Layer Pattern (3-Layer Architecture)

A proven layout pattern for industrial control system diagrams:

┌──────────────────────────────────────────────────────────┐
│ [Layer 1: Controller]   ┌─────┐ ┌─────┐ ┌──────────┐   │
│   ┌─────────────────┐   │HMI  │ │IOC  │ │ Database │   │
│   │ Main Controller  │   └─────┘ └─────┘ └──────────┘   │
│   └─────────────────┘                                    │
├──────────────────────────────────────────────────────────┤
│ [Layer 2: EtherCAT Bus]                                 │
│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐      │
│  │AX8206│ │AX8206│ │Safe │ │EL1808│ │EL3124│ │EL2808│  │
│  └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘      │
├──────────────────────────────────────────────────────────┤
│ [Layer 3: Field Devices]                                │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ [Notes] │
│  │Motor │ │Encoder│ │Safety│ │Limit │ │PT100 │         │
│  └──────┘ └──────┘ └──────┘ └──────┘ └──────┘         │
└──────────────────────────────────────────────────────────┘

1. Title bar — Centered text at top of canvas
2. Layer backgrounds — Light fill rounded rects with left-side labels
3. Device boxes — White/light fill rounded rects inside each layer
4. Bus bar — Thin bar across the bus layer representing the communication backbone
5. Connection lines — Vertical lines between layers with protocol labels
6. Notes box — Engineering annotations in a corner

Recommended Color Palette

Common Pitfalls

1. ❌ Using <br> for line breaks — Always use \n in Python strings (
 in raw XML). <br> displays as visible text in both draw.io and SVG.
2. ❌ Text overflow in small boxes — The converter clips text exceeding box bounds. Use taller boxes (≥90px) for multiline content, or keep text concise.
3. ❌ Missing parent="1" — Every mxCell except id="0" and id="1" needs parent="1", or draw.io won't display it.
4. ❌ Overlapping elements — Plan X/Y coordinates carefully. Draw.io renders in ID order; later elements stack on top.
5. ❌ Encoded/compressed drawio — The converter only works with uncompressed inline XML. If the drawio file is base64-encoded, open it in draw.io and export as uncompressed XML.
6. ❌ Visio SVG import failures — If Visio rejects the SVG, try opening the .drawio file in draw.io desktop instead, and use File → Export to export the desired format.

Scripts

scripts/drawio_to_svg.py

Core converter: draw.io XML → Visio-compatible SVG. This script is adapted from the Codex visio-drawio-svg-diagrams skill, which successfully resolves Visio SVG import issues that standard SVG generators cannot handle.

scripts/example_generator.py

Template script for generating draw.io diagrams programmatically. Modify coordinates, text, and styles to create new diagrams. Serves as both reference and boilerplate.