drawio-ai-kit: a layout engine and validator for AI-generated draw.io diagrams
Teach your AI to draw correct, beautiful draw.io diagrams — declarative layout engine, ground-truth stencils, structural validator, vision self-check. AWS · Azure · GCP · Databricks · BPMN. Zero dependencies.
At a glance
- What is it?
- The kit replaces freehand XML generation with a declarative tree, a stencil catalog and a static validator, so an agent can produce diagrams whose shape IDs actually resolve. It is a narrow tool with a real failure mode: it only helps if your agent calls it.
- Who is it for?
- Adopt drawio-ai-kit if your agent already writes draw.io XML and you are tired of empty shapes from invented stencil IDs, and if you can run Node 18 or newer and accept a GitHub-based install because the package is not on the npm registry. Do not adopt it if you want a hosted diagramming service, if your diagrams are hand-drawn rather than generated, or if you cannot install the Domain Skills, since the README states the agent will not pick the kit up on its own without them.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 6 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The failure mode this kit was built around
Ask a language model to produce a draw.io file and you get XML that parses. It often does not render. The README names the specific cause: agents generate non-existent stencil IDs, and draw.io responds by drawing an empty shape rather than raising an error. Nothing in the file is malformed, so nothing in a normal XML linter catches it. You discover the problem by opening the diagram and counting rectangles.
The kit targets that gap. It is for engineers who already delegate diagram production to an agent and want the output to be structurally checkable before a human looks at it. The audience is narrow by design: AWS, Azure, GCP, Databricks and BPMN architectures, per the five Domain Skills. If your diagrams are network racks or UML sequence charts, the catalog is not aimed at you.
Three components, and the order they run in
The README describes three pieces. A Declarative Catalog maps draw.io stencil IDs such as mxgraph.aws4.* to taxonomies and canonical color palettes. Design Principles live in rules/principles.md as codified layout rules. A Structural Validator is described as a static analysis engine that audits diagram XML so stencil references are valid and the principles are satisfied before serialization.
The data flow is tree-first. You build a Diagram, attach a nested tree of group and icon nodes with a direction hint such as dir: "row" or dir: "col", and call renderTree. The layout engine then computes x, y, width and height for every node, auto-sizing frames to their children and spacing rows and columns. Edges are declared by node id, and the README states a router picks between a straight line and a corridor path. Coordinates never appear in your source.
The important detail is ordering. Validation runs on the in-memory Diagram object (d.validate() in the example), before d.mxfile() writes the .drawio file. That means a bad stencil name fails at build time, not at review time. It is the difference between a compiler error and a blank box in a screenshot.
Getting it on PATH and into your agent
The README gives a two-command install. The first puts the binary on PATH and the second registers the skills:
npm i -g github:sparklabx/drawio-ai-kit && npx skills add sparklabx/drawio-ai-kit
The install comes straight from GitHub. The README states the package is not yet on the npm registry, so a plain npm i -g drawio-ai-kit will not work. To pin a release, the documented form is github:sparklabx/drawio-ai-kit#v1.0.1. A single domain can be added with --skill drawio-aws, and --list previews all five.
Two optional dependencies unlock features rather than being required. The draw.io desktop app enables drawio-ai render, which produces a PNG for the vision self-check. Graphviz enables vendor/autolayout.py for large graphs. Neither ships with the kit.
Updating is split across two channels. npm i -g github:sparklabx/drawio-ai-kit refreshes the engine, and npx skills update refreshes the SKILL.md text. The README's reasoning is that the skills are thin frontends calling drawio-ai at runtime, so engine fixes arrive with the CLI update alone. Uninstall is symmetric: npm uninstall -g drawio-ai-kit plus npx skills remove drawio-aws for each skill.
The zero-dependency claim, and what it does not cover
The repository states there are no runtime dependencies, no postinstall or other lifecycle hooks, and no sudo, curl piping or remote code execution. It also states the single dependency, @modelcontextprotocol/sdk, was removed at 1.0.0. The CLI reads and writes local files and ships no telemetry.
One outbound call exists. The README describes icon-logo fetching from public CDNs (lobe-icons) and says it is opt-in. That is the only network path the documentation admits to, and it is worth confirming in your own environment if the machine building diagrams is not allowed egress.
The 1.0.0 release was a breaking change, not a feature release. The MCP server and the bespoke installer were removed, and the migration notes tell users to move from claude mcp add ... mcp-server.mjs to the npm install, and to replace the old drawio-cloud-architect skill with the five Domain Skills. Anyone on a pre-1.0 checkout has real work to do. The inline image step in the old vision check was replaced by drawio-ai render writing a PNG that the agent then Reads.
Where the design pushes work back onto you
The validator is static analysis over XML and the in-memory model. It checks whether stencil references resolve and whether the rules in rules/principles.md hold. It cannot tell you that the architecture is wrong. A VPC containing a single subnet in one availability zone passes every structural check the kit advertises, because the rules concern names, colors, nesting and labels, not whether the topology is sensible.
The vision self-check is the second layer, and it is optional. It requires the draw.io desktop app and a render step that produces a PNG for the agent to read. Skip that and you lose the render-analyze-rectify loop the README describes, keeping only the static pass. On a headless build box, that is the realistic configuration, and it means aesthetic problems survive to the human reviewer.
There is also a coupling cost. The README is explicit that without the skills registration the agent never picks the kit up on its own. The engine being correct does not help if the agent ignores it, and skill registration is a separate command against separate tooling (the skills CLI, which the README says auto-detects Claude Code, Codex, Gemini CLI and others). Two update channels means two things that can drift, even if the README argues the thin-frontend design limits the damage.
How this differs from a general diagram-as-code tool
The obvious comparison is a diagram-as-code tool such as Graphviz or Mermaid, where you write a text description and the tool lays it out. Those tools own the whole pipeline: their renderer, their node set, their styling. You get consistency because you give up control of the visual vocabulary.
drawio-ai-kit takes the opposite position. It does not render anything itself. It emits .drawio XML, which means the output stays editable in draw.io by a human who has never heard of this project, and the styling vocabulary is draw.io's own stencil set rather than a private one. The cost of that choice is that correctness depends on stencil IDs matching draw.io's catalog, which is exactly why the catalog and validator exist. Graphviz has no equivalent failure mode because there are no external stencil IDs to get wrong. The kit trades that safety for output that a draw.io user can open, move a box in, and save.
The examples directory follows the same logic. Each file under examples/ builds one architecture with zero hardcoded coordinates and writes to out/*.drawio, organized into domain subfolders with an index in examples/README.md. The README points to examples/aws/build_mesh.mjs as a zero-manual-coordinate example. Copying a working file is the documented starting path, which is a reasonable admission that the API surface is easier to read from an example than from prose.
Licence, maintenance and what the release history shows
The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive licence with no copyleft obligation on your own code. This is not legal advice; check your own policy on vendored or globally installed tooling if that matters to you.
The release history is short and recent. v1.0.0 (CLI-only) landed 2026-07-10, v1.0.1 (search and workflow fixes) on 2026-07-15, and v1.0.2 (compact layouts and cleaner edges) on 2026-08-04. The last push to the default branch is dated 2026-09-10. Two of the three releases are described as fixes to search, workflow and layout output, which suggests the 1.0.0 rewrite was still settling. The 1.0.0 notes confirm it was a removal release, so anyone evaluating the project should treat 1.0.x as the real starting line rather than a mature line.
Maintenance cost on your side is low in one respect and non-zero in another. Zero runtime dependencies means no transitive package updates to track and no supply-chain surface beyond the install itself. The two-channel update model means you either script both commands or accept that the skills text and the engine can be at different versions. The install-from-GitHub requirement adds a step to any air-gapped or registry-mirrored build, since the README documents no registry path.
Editorial conclusion
Adopt drawio-ai-kit if your agent already writes draw.io XML and you are tired of empty shapes from invented stencil IDs, and if you can run Node 18 or newer and accept a GitHub-based install because the package is not on the npm registry. Do not adopt it if you want a hosted diagramming service, if your diagrams are hand-drawn rather than generated, or if you cannot install the Domain Skills, since the README states the agent will not pick the kit up on its own without them. Before committing, run npx skills add sparklabx/drawio-ai-kit --list to confirm the five skills register with your agent, then build one example from examples/aws/ and run drawio-ai render to check that the vision self-check path works on your machine.
Community notes