Reladraw is a text diagram language where you state the layout instead of coordinates

A third approach to diagram placement

Reladraw, an open-source project that reached the Hacker News front page in a Show HN post, is a text language for diagrams in which the author explicitly states where every element goes. According to the project's README on GitHub, positions are written as relations — right of, below, between — and no coordinate appears anywhere in the file. A typical statement reads node store "Database" right of app level with app, and the repository's worked example reproduces a diagram originally drawn by hand in draw.io using 44 statements.

The README frames the language as a middle ground between two existing camps. Declarative tools such as Mermaid, Graphviz and D2 accept entities and connections and compute the arrangement automatically — effective for most diagrams, but unable to express that a particular module should sit to the right with its links placed a certain way. Editors such as draw.io, Excalidraw and Figma offer total placement control at the cost of making every change to a complex diagram slow manual work. Reladraw keeps the text-file workflow while putting placement in the source itself. Statements are flat rather than nested, so no line depends on another line's position or indentation. A browser-based playground lets you edit the source and watch the layout re-solve without installing anything.

Deterministic constraint solving

Gaps in Reladraw are minimum distances, not exact ones. Place a third node between two others and the outer two are pushed apart by exactly the space the newcomer needs; remove it and they close back up. According to the README, the resolver treats each axis as a set of minimum-distance constraints and finds the tightest arrangement satisfying all of them through a longest-paths computation — a single deterministic answer, with no arrangements tried and rejected.

Non-overlap holds by default for every pair of nodes without anyone writing it down. The direction of separation is derived from what the file already states: where the stated arrangement orders two nodes on one axis, that axis decides; where it orders them on both, the tie breaks toward the axis of least overlap, which the README calls the one decision the tool makes that nobody wrote. Pairs the file does not order at all are named by the tool rather than guessed. Each solving round re-derives the implied separations and solves the whole system from scratch instead of patching a previously solved layout.

Built with AI agents in mind

A large part of the README argues for the language from the perspective of coding agents. The common task is changing a diagram rather than drawing one: with pixel coordinates, an agent must reconstruct the picture before it can work out which numbers to change, and with auto-layout the arrangement was never written down, leaving nothing to read. With stated placement, changing the picture means changing the sentence that places the element.

The README is also precise about the limits. An agent can re-read its own file and confirm intent — that the database sits under the API — but cannot detect emergent outcomes such as overlapping clusters, overflowing text or crossing edges, because those are resolved by the solver rather than stated. That gap motivates planned machine-readable diagnostics computed from the solved geometry.

Because the language is too new to appear in any model's training data, the repository ships an agent skill that teaches the syntax to tools such as Claude Code, Codex, Cursor and Copilot, installed with a single npx command. The skill is a copy taken at install time rather than a live link, so it must be reinstalled after any release that changes the syntax.

Early status, known gaps

Reladraw is at version 0.4.0, with a parser, resolver and SVG renderer written in dependency-free TypeScript, plus a command-line tool that turns a text file into a standalone SVG. Not yet built, listed roughly in the order the author expects to miss them: the diagnostics report — today the tool either renders or fails, and will not critique a picture it drew successfully — edge routing around nodes, since an edge that specifies no sides is a straight line between centres that cuts through whatever stands in the way, and a wider set of icons and shapes, which currently form a closed set inside the tool. The README acknowledges that the visible roughness in its example is typography rather than placement, warns that the language is not stable, and says the syntax should be expected to change.

Why it matters

Diagramming has long been split between auto-layout, which is fast but takes placement out of your hands, and freehand canvas editors, which offer control but produce slow edits and opaque files. Reladraw's bet is that relative statements are a workable middle: diffable like text, controllable like a drawing. The agent argument may matter more. As more diagrams are produced and edited by AI, a format whose layout intent lives in inspectable sentences — with diagnostics planned that report overlaps and crossings as data rather than pixels — could make machine-edited diagrams verifiable in a way neither camp manages today. At version 0.4.0 with an unstable syntax it is an experiment rather than a migration target, but the design is a genuine alternative worth watching.