Reladraw: A Diagram Description Language That Puts You in Control of Layout

The Dilemma with Diagram Tools

Using diagrams to clarify thinking and plan projects is a daily routine for most developers. But when it's time to actually sit down and draw, you often face an uncomfortable tradeoff: existing tools either hand full layout control over to an algorithm, or dump all the work onto you.

The author of the new open-source project Reladraw laid out this frustration plainly on Hacker News. He splits existing solutions into two camps: tools like Mermaid and Graphviz, where you write code to describe nodes and relationships and the tool handles the layout automatically; and visual editors like Draw.io, which are powerful but extremely time-consuming. Neither approach is ideal, he argues — the first strips away your say over how the diagram looks, while the second's manual workflow is inefficient and especially ill-suited for AI agents.

The project earned 172 points and 52 comments on Hacker News, a sign that it's touching on a widely felt problem with few elegant solutions.

Mermaid is one of the most popular text-based diagramming tools today. Users describe nodes and edges using Markdown-like syntax, and the tool automatically generates flowcharts, sequence diagrams, class diagrams, and more. Much of its widespread adoption stems from native rendering support on GitHub and integrations with platforms like Notion, GitLab, and Obsidian. Graphviz has an even longer history, using the DOT language and excelling at handling large graph structures — it's the underlying engine behind much academic and engineering visualization. The shared limitation of both tools is this: their layout algorithms (such as Graphviz's Sugiyama hierarchical layout or force-directed layout) optimize for a global "best" result, but that definition of "best" often diverges from the information architecture the author has in mind. Users have almost no way to intervene — it's all or nothing.

Reladraw's "Have It Both Ways" Ambition

Reladraw's core design goal is to combine the strengths of both tool types: define diagrams in a diagram language like code, while retaining a high degree of control over the final presentation.

This is fundamentally an exploration of the middle ground between "declarative" and "hand-crafted layout." The problem with fully automatic layout is that algorithm-generated results often don't match the author's sense of information hierarchy — you know which node should be at the center and which should sit side by side, but the tool may have other ideas. Fully manual drawing tools give you that freedom, but every small tweak becomes physical labor, and maintenance costs skyrocket as diagrams grow complex.

Reladraw's very name hints at its orientation: built on "relations," with "you decide where to place things" as its core selling point. The author repeatedly emphasizes this phrase — "a diagram language where you decide where to place things." This means it preserves the engineering benefits of text-based description — version control, diffability, reusability — while returning final layout authority to the user.

Designed for the Age of AI Agents

One noteworthy aspect of this project is that it explicitly targets both human users and AI agents.

The author specifically points out that visual tools like Draw.io are "inefficient for agents to operate." This is a grounded observation: more and more workflows are being handed off to AI, and drag-and-drop graphical interfaces are nearly impossible for LLMs to drive directly. Text-based description languages are their native format. Reladraw's readable, writable language naturally suits the needs of agents generating and modifying diagrams.

On the practical side, the author offers three ways to get started:

• A built-in playground on the GitHub page — no installation required, try it online;
• Support for integrating into your own projects via a simple npm install;
• An installable skill designed to work with AI agents like Claude.

That last point makes the use case explicit — you can have Claude generate diagrams directly in the Reladraw language, with humans stepping in when needed to adjust the layout, creating a human-AI collaborative diagram workflow.

When LLM-powered AI agents interact with graphical interfaces, they typically rely on indirect methods like screenshot recognition or Accessibility Tree parsing — approaches with high latency, high error rates, and poor stability in automated pipelines. By contrast, text protocols (JSON, DSLs, Markdown) are the natural input/output format for LLMs, requiring no additional UI perception layer. This is exactly why Mermaid sees heavy use in AI-assisted writing contexts — models like ChatGPT and Claude can output valid Mermaid code directly, with predictable rendering results. Reladraw's skill integration follows this same paradigm while attempting to solve Mermaid's uncontrollable layout problem, so that agent-generated diagrams also meet human visual expectations.

What Gap Does It Fill?

Situating Reladraw in the broader landscape, it targets a long-standing but often overlooked gap.

Mermaid has become widely popular through integrations with GitHub, Notion, and similar platforms, but anyone who's used it extensively has experienced the frustration of losing control over layout — the more nodes you add, the uglier the auto-layout gets, and there's almost nothing you can do about it. Professional drawing software, meanwhile, carries a learning curve and maintenance burden that makes it hard to embed in automated workflows. Reladraw aims to find a balance between these two extremes: use declarative language to ensure maintainability and automation-friendliness, while using explicit position control to ensure the output matches your intent.

Of course, the success of any such "compromise solution" ultimately depends on whether the language design itself is sufficiently clean and concise. If controlling position requires verbose syntax, it loses its efficiency advantage over Draw.io. If the control granularity isn't fine enough, it degrades into just another Mermaid. What the author offers right now is an early-stage open-source project and a playable playground — how it performs in practice and whether its syntax is elegant enough will require validation through real-world use.

For developers who regularly work with diagrams and want to bring diagramming into version control or AI workflows, Reladraw at least offers a fresh approach worth trying.