Drawio AI Kit is an orchestration and validation layer that lets an AI agent produce draw.io diagrams with real stencils and consistent layout, aimed at AWS, Azure, GCP, Databricks, and BPMN architecture drawings. It targets a specific failure mode: an agent inventing stencil IDs such as mxgraph.aws4.* that render as empty shapes.
Three parts carry the work. A declarative catalog maps draw.io stencil IDs to their taxonomies and canonical color palettes, a set of codified design principles states the architectural and layout rules, and a structural validator statically audits diagram XML so stencil references and design rules are checked before serialization. All three are reached through the drawio-ai command-line interface, which has no runtime dependencies and runs on Node 18 or newer; a separate Python 3.11 pipeline generates the catalog and the icon packs.
Diagrams are declared rather than positioned. You pick a topology — pipeline, hierarchy, network, hubspoke, hybrid, mesh, or sequence — and describe the nested structure, and the layout engine computes coordinates, auto-sizes frames to fit their children, spaces rows and columns, and routes edges. Icon names come from drawio-ai search so they are not fabricated, and the agent iterates through a render-analyze-rectify loop: drawio-ai render writes a PNG that the agent reads back for a vision self-check, which requires the draw.io desktop application.
The kit ships as a command-line interface plus five domain skills — one each for AWS, Azure, GCP, Databricks, and BPMN — installed through the standard skills tooling, which detects hosts such as Claude Code, Codex, and Gemini CLI. Any host that can run shell commands can drive it directly. The bundled catalog holds 2,106 icons: 983 AWS, 626 Azure, 216 GCP, and 281 across eight open-source packs covering databases, big data, CI/CD, AI/ML, containers, observability, Databricks, and networking.
Features
- Declarative layout engine: you declare topology and nesting, and the engine computes x/y/w/h, frame sizing, row and column spacing, and edge routing
- Ground-truth stencil catalog: stencil names, official per-icon colors, connection points, and aspect=fixed are generated from a 10,446-shape index rather than hand-written
- Structural validator: drawio-ai validate flags unknown stencils, dangling edges, missing aspect=fixed, recoloured AWS icons, broken group nesting, and geometry problems such as overlap or a child spilling its frame
- Aesthetic audit: drawio-ai audit checks font, palette, fan-out, and icon size separately from structural linting
- Vision self-check: drawio-ai render exports the diagram to PNG so the agent can inspect and correct its own output
- Five domain skills: drawio-aws, drawio-azure, drawio-gcp, drawio-databricks, and drawio-bpmn wrap the build, validate, render, and export workflow per domain
- Template library: example scripts cover VPC multi-AZ, landing zones, event-driven and serverless architectures, Databricks medallion and MLOps, multicloud, and BPMN swimlanes
- Icon packs: 281 additional brand and tech icons across database, bigdata, cicd, aiml, containers, observability, databricks, and network packs
- Local operation: the command-line interface reads and writes local files, with an opt-in outbound call for icon-logo fetching
