Reladraw is an open-source diagram-as-code language where you decide where each node goes: you write “the database goes to the right of the app” and Reladraw calculates the coordinates. Mermaid and Graphviz choose the layout for you; Draw.io and Excalidraw make you drag every box by hand. Reladraw sits in the middle, and the source is a plain text file that you version in Git alongside your code.
It launched as a Show HN on September 26, 2026, drew 119 comments, and is released under the Apache-2.0 license. It is very young: the README itself describes it as an early-stage project that already works, and warns that the syntax will change.
What is Reladraw?
Reladraw is a diagram as code language based on relative positioning. You declare nodes, say where each one goes relative to the others, and connect them with edges. A CLI turns the file into a self-contained SVG.
The author built it out of a frustration anyone who draws architecture diagrams will recognize:
- Tools with auto-layout (Mermaid, Graphviz, D2): you declare boxes and connections, and the engine decides the positions. If you have a specific picture in mind, you end up fighting it.
- Canvas tools (Draw.io, Excalidraw): full control, but every change means dragging. For an AI agent, editing them means recalculating coordinates in verbose XML.
Reladraw’s bet is that most diagrams don’t need absolute coordinates. They need phrases like “to the right of”, “below” and “level with”.
How do you write a diagram in Reladraw?
With relative positioning instructions instead of coordinates. This is the example from the project’s README:
node app "Web app"
node app.ui "Interface"
node app.api "API" below app.ui
node store "Database" right of app level with app
edge app.api -> store "queries" from: right to: left
There isn’t a single coordinate. A few rules from the syntax reference explain how it works:
- Containment is a dotted name.
app.uigoes insideapp. - A container sizes itself to fit its children.
- Gaps are minimums, not exact distances. If you place a node between two others, they move apart to make room. If you delete it, they close up again.
from:andto:set which side of the node an edge leaves from and which side it arrives at.- Contradictions are errors. If you put a node both to the left and to the right of the same target, the tool refuses and names the conflicting instructions. As the author summed it up on HN: nothing wins silently.
The full reference is in SYNTAX.md, inside the repo. It changes from version to version, so treat any snippet, including the one above, as illustrative.
Reladraw or Mermaid.js?
Choose Mermaid.js when the diagram has a fixed shape. Sequence diagrams and Gantt charts are the clearest cases, and Mermaid wins on scope. Several HN commenters agreed: when the structure is fixed, Mermaid’s automatic layout is an advantage, not a problem.
Choose Reladraw when position carries meaning. The typical cases are architecture diagrams, flowcharts and layouts of the “client on the left, cloud on the right” kind. That is where Mermaid tends to arrange things its own way as soon as the diagram grows. That is the gap Reladraw wants to fill.
Does Reladraw work on GitHub like Mermaid?
No, at least not at the time of publishing this article (October 3, 2026). GitHub renders Mermaid code blocks natively, and Reladraw has no equivalent. The author confirmed on HN that the alternative is to export to SVG and link the image.
Editors are another story, because they accept extensions. A community developer has already published a VS Code extension that renders Reladraw inside Markdown. It is not official and is not maintained by the Reladraw project.
Reladraw or D2 with TALA?
It depends on how much control you want, and it is the comparison most worth making carefully. The README groups D2 with Mermaid and Graphviz, as tools that decide positions for you. An HN commenter objected that D2’s TALA layout engine offers quite a lot of manual control, including per-container direction and the option to keep shapes close to one another. They also pointed out that TALA used to be commercial and is now open source.
The author’s reply draws the real distinction. TALA keeps automatic layout and gives you ways to nudge it, such as “keep this pinned here” or “keep these together”. Reladraw has no automatic layout to nudge: you declare the relationships and it calculates the positions from them.
If you already use D2, we cover it here: How to make an architecture diagram with D2 and TALA
How do you install Reladraw?
The quickest option requires no installation at all: the playground runs in the browser.
For the CLI, the README says:
npm install -g reladraw
reladraw diagram.reladraw -o diagram.svg
The npm package declares Node 18 or later. The syntax reference also documents a --theme flag, which renders the same file with a different theme without editing it:
reladraw arch.reladraw --theme light
For a web page, load a script and write the diagram inside the HTML:
<script type="module" src="https://cdn.jsdelivr.net/npm/reladraw/dist/element.js"></script>
<reladraw-diagram>
node a "Parser"
node b "Renderer" right of a
edge a -> b
</reladraw-diagram>
How do you make diagrams with AI using Reladraw?
With your coding agent and the skill that ships with the repo itself. It is half the point of the project:
npx skills add reladraw/reladraw -g
According to the README, -g installs the skill for every agent you use, including Claude Code, Codex, Cursor and Copilot. Without -g, it installs only in the current project. For a single agent, add -a:
npx skills add reladraw/reladraw -g -a claude-code
The skill is a snapshot from the moment you install it, so run the command again when new versions come out.
The author’s argument, self-reported and without a benchmark, is this: an agent that draws with Graphviz cannot predict the final layout, so it falls into cycles of rendering, looking and correcting. An agent that edits Draw.io XML spends tokens recalculating coordinates. With Reladraw, the agent declares the intent (“this goes to the right of that”) and the tool does the arithmetic. The author himself describes the agent integration as basic for now.
If you are looking for agent-generated architecture diagrams today, also check out Archify: how to make architecture diagrams with Claude Code and compare two versions.
Is Reladraw ready for production?
It is ready to try, not to standardize on. The project published 24 versions on npm in its first 24 days. At the time of publishing this article, the GitHub README already mentioned a newer version than the latest one available on npm, and the changelog records breaking changes between minor versions.
For a team, the practical move is to pin the version in the project and regenerate diagrams in CI. That way, a syntax change shows up as a failed build rather than as a silently broken diagram.
What about you? When a diagram really matters, do you draw it by hand or write it as code?
- Mermaid
- D2 or Graphviz
- Draw.io or Excalidraw
- I prefer another option (tell us which)
Comment below or, if this article reached you by email, reply directly to the email: your reply is published here.
Related: How to make an architecture diagram with D2 and TALA