Mermaid vs draw.io vs Reladraw: When AI Agents Draw Architecture Diagrams

When a coding agent like Claude Code or Cursor has to produce an architecture diagram, the realistic candidates are an auto-layout text format like Mermaid or a coordinate-storing XML format like draw.io, and each fails in a characteristic way: a layout solver that picks the positions, or absolute coordinates the agent must recalculate. Reladraw, a v0.8.0 tool, proposes a third option: relative placement declarations an agent can write. The decision for teams standardizing on agent-generated diagrams turns on who controls layout, where the output can live, and how much maturity risk a v0.8.0 syntax carries.

The real decision: who controls layout when the agent holds the pen

Diagram tools split into three camps by how they answer one question: who decides where a node goes. The first camp, which includes Mermaid, Graphviz and D2, hands that decision to a layout solver. The second, draw.io and Excalidraw, stores absolute coordinates that the author (human or agent) must maintain. Reladraw stakes out a third position: the author declares placement relative to other nodes, and the tool resolves the geometry from those declarations.

That framing comes with a disclosure. The characterization of the two established camps appears in Reladraw’s own README, which states that “Mermaid, Graphviz and D2 let you declare boxes and connections, then determine positions for you. If you have a particular picture in mind, these aren’t the right tool.” Of draw.io and Excalidraw, the README says absolute placement means “much more effort, whether for humans clicking and dragging nodes around or agents recalculating coordinates and editing verbose XML source code files.” This is a competitor’s framing, not a benchmark, and the article treats it accordingly. Every Reladraw capability described below is likewise author-reported, from its own repository and playground. No independent evaluation compares agent-generated diagram quality across these tools. What follows is an argument from syntax design and adjacent research, flagged as inference where it is inference.

Axis 1: auto-layout, absolute coordinates, or relative placement

The auto-layout camp optimizes for declaration speed. You write nodes and edges; the solver positions everything. For flowcharts and sequence diagrams where the picture matters less than the topology, this is the right trade: the syntax is short, and the agent never has to reason about geometry.

The cost shows up when layout carries meaning. Architecture diagrams often encode a mental picture: the UI above the API, the database to the right, the cache between them. When the solver picks positions, communicating that picture means nudging the solver rather than stating the picture; how much steering Mermaid, Graphviz or D2 actually allow is a question their own documentation has to answer, since Reladraw’s README says only that they “determine positions for you.” An agent writing the text never sees the render unless one is fed back to it, so it cannot even attempt that negotiation. It emits a topology and hopes.

Absolute placement inverts the burden. Draw.io’s XML gives full control, but every move or resize requires recalculating every affected coordinate, and the source is verbose enough that edits are expensive in tokens and error-prone in practice. The README puts the cost as “much more effort, whether for humans clicking and dragging nodes around or agents recalculating coordinates and editing verbose XML source code files.” For an agent, that effort lands as coordinate arithmetic inside a verbose document.

Relative placement splits the difference:

node app "Web app"
node app.ui "Interface"
node app.api "API" below app.ui

Positions are declared relative to other nodes, so nobody picks coordinates manually, according to the Reladraw repository. The interesting property for agents is that the declaration is also the documentation of intent: “below app.ui” survives edits to neighboring nodes, while a hardcoded y-coordinate does not.

Axis 2: what an agent can reliably write

Writability is the axis the agent workflow actually stresses, and it is worth being precise about what Reladraw asks an LLM to learn. The playground documentation describes a nine-position placement grid: top-left, top-center, top-right, left-center, center, right-center, bottom-left, bottom-center, bottom-right. A node “takes as many placements as it needs,” and a single placement on its own binds both axes. Grouping works through dotted names: declaring server.docker makes it a child of server, provided the parent is declared first.

This is a small vocabulary. Nine positions, a handful of directional relations, one containment convention. The claim that this is more agent-writable than draw.io XML is plausible on its face: a short, regular grammar beats coordinate arithmetic in a verbose document.

There is one piece of independent evidence that bears on the absolute-coordinate side of the argument. The EchoPath study on GUI agents deliberately shifted screen resolution between passes, from 1920×1080 to 1600×900, “to ensure that direct success must come from actions with corrected coordinates from visual re-aiming or bounded step-local grounding repair.” The experiments ran coding-agent clients including Codex, Claude Code and Kimi Code. The finding cuts both ways: coordinate fragility is real enough that researchers build entire test dimensions around it, but agents can also recover from coordinate errors when the current screen is fed back into the loop, through visual re-aiming or bounded grounding repair. EchoPath measures GUI clicks on live screenshots, not diagram XML, so it should not be cited as a diagram-tool result. Its design premise is still telling for the coordinate question: the paper treats stored coordinates as “evidence about a visual target, not as the portable target itself,” which is the same fragility that makes hardcoded positions a shaky thing for an agent to own.

Axis 3: output format and where diagrams can live

The ecosystem question is where Reladraw’s case is weakest. Mermaid’s text renders in free browser editors with “no signup, no install, no proprietary file formats,” as one Mermaid editor puts it, and the syntax’s text-in/diagram-out nature means it diffs cleanly in pull requests and lives happily inside Markdown. Confirm your documentation platform’s current Mermaid rendering support before a pipeline depends on it.

Reladraw, at v0.8.0, documents two surfaces: a command-line tool that turns a .reladraw file into an SVG, and a browser playground. The parser, layout engine and SVG renderer are written in TypeScript with zero runtime dependencies, per the README. SVG files can be committed, embedded and served, but the project documents no Markdown fence support and no documentation-platform plugin, so a diagram reaches readers as a generated artifact rather than as text that renders wherever the documentation lives. Standardizing on Reladraw today means adding a compile step to your docs pipeline and storing generated artifacts alongside source. On a platform that renders Mermaid natively, that is a cost the auto-layout text route avoids; where your platform lacks native Mermaid rendering, a render step appears on that side of the comparison too.

The comparison in compact form:

Axis 4: the agent-skill setup path

Reladraw ships an installable skill targeting the major coding agents, and the installation mechanics matter because they determine how the tool spreads through a team. Per the repository:

npx skills add reladraw/reladraw -g

The -g flag “installs it for every agent you use (Claude Code, Codex, Cursor, Copilot and others), each in its own skills directory.” Omitting -g installs into the current project only, and -a claude-code scopes the install to a single agent. That project-scoped option is the right default for a pilot: the skill lands inside the project, so it can travel with the repo if the skills directory is committed.

Two operational catches. First, the install is a snapshot: the README states you “need to re-run that command to get the latest skill when there is a new release,” so a team that standardizes on it also inherits an update chore. Second, the skill is one more entry in a fragmented landscape. As our earlier comparison of Claude Code skills, Cursor rules and MCP documented, these runtimes cannot exchange skill definitions between them; Reladraw works around this by writing into each agent’s own skills directory, which is pragmatic but means four artifacts to keep in sync rather than one. For broader context on how the agent tools themselves differ, see our 2026 coding assistant comparison.

The maturity bill arrives with the invoice

Reladraw’s README is unusually honest about its stage: “Version 0.8.0. Early stage, but works,” followed by “The language isn’t stable yet, so expect the syntax to change.” Every .reladraw file a team commits is a bet on a grammar that its author warns will break.

This does not make the tool a non-starter. It makes it a pilot. A v0.8.0 syntax with an explicit instability warning belongs in exactly one place: a scoped trial where the cost of rewriting diagrams is low and the value of controllable layout is being tested against real agent workflows.

The decision, with its asterisk

The practical verdict follows the axes. Default to Mermaid (or Graphviz/D2 where their strengths apply) for agent-written diagrams whenever auto-layout is acceptable: the text format is agent-writable and diff-friendly, and it renders wherever your documentation platform supports Mermaid, which is worth confirming for your stack. Pilot Reladraw through its npx skill, project-scoped, when the diagram’s layout carries meaning the solver keeps losing, and budget for a compile step plus syntax churn at v0.8.0. Reserve draw.io and Excalidraw for human editing; their absolute-coordinate sources are a poor target for generation even if agents can, per EchoPath’s framing, sometimes repair coordinate errors.

One caveat carries through from the framing section: nothing here is independently measured, and the writability argument rests on syntax design plus adjacent GUI-agent research. If your team’s decision is expensive, the right next step is the one the evidence cannot do for you: give the same three architecture prompts to your agent in Mermaid and in Reladraw, and compare what comes back.

Frequently Asked Questions

How do I install the Reladraw skill for a specific project?

Omitting -g installs into the current project only, and -a claude-code scopes the install to a single agent. That project-scoped option is the right default for a pilot: the skill lands inside the project, so it can travel with the repo if the skills directory is committed.

What is the current stability status of the Reladraw syntax?

Reladraw’s README is unusually honest about its stage: “Version 0.8.0. Early stage, but works,” followed by “The language isn’t stable yet, so expect the syntax to change.” Every .reladraw file a team commits is a bet on a grammar that its author warns will break.

What output formats does Reladraw currently support?

Reladraw, at v0.8.0, documents two surfaces: a command-line tool that turns a .reladraw file into an SVG, and a browser playground. The parser, layout engine and SVG renderer are written in TypeScript with zero runtime dependencies, per the README.