reladraw · a diagram language where you say where every box goes
reladraw
Reladraw drew this diagram from a text file with zero coordinates in it. Every box got its spot from a sentence, like above-left of the cloud sync hub. Reladraw is a free diagram language, and it sits between two tools you may know. In Mermaid, you type a list of boxes and arrows, and the tool places every box for you. In draw.io, you drag every box yourself.
The same diagram, drawn by hand and written as text
Joe Walsh drew this diagram by hand, then rewrote it as 44 statements with no coordinates
You get a text language plus a command-line tool, a program you run by typing a command. You write lines like API below app, and the tool draws the picture. On the left is an architecture diagram that Joe Walsh, the one developer behind Reladraw, drew by hand in draw.io. On the right, Reladraw drew the same diagram from a text file of forty-four statements, with zero coordinates in it. I love this pair, because the right side came out of plain text you can edit like any other file.
What you’ll learn, and the catch
By the end, you'll know how a word like below turns into arithmetic a computer solves without trial and error. You'll know what Reladraw does when two boxes land on top of each other and your file never said which one goes where. You'll also know the catch. Any arrow you don't steer runs in a straight line, so it can cut right through a box in its way. And I'll tell you who I think should try Reladraw this weekend.
Between Mermaid and draw.io
Mermaid decides where boxes go, draw.io makes you drag each one, and reladraw sits between
There are two ways to make a diagram today. The first is the Mermaid side. Mermaid, D2 and Graphviz are all text languages, and the tool decides where every box goes. This diagram labels that side auto-layout. That approach breaks once you want one module over on the right, because those languages have no way to say it. The second is the draw.io side. draw.io, Excalidraw and Figma are drawing apps. The diagram labels that side absolute, because every box sits at a fixed spot you set. You get total control, and every edit is hand work. For an AI agent, a program like Claude Code that edits your files for you, that hand work gets expensive. The agent has to work the picture out from raw coordinates before it knows which numbers to change. I think that agent problem is the real pitch. Reladraw aims at the middle. Every position in a Reladraw file is stated relative to another box.
Five statements, three boxes, one arrow
Five statements make three boxes, place them, and draw one arrow
I'll read you the example from the README, the project's front page on GitHub. It's five statements. The first line makes a box called Web app. The next two put an Interface box and an API box inside it, with the API below the Interface. Then a Database box goes right of the app, and level with the app, so the two share a center line. The last line draws an arrow labelled queries, from the API to the Database. It leaves the API's right side and lands on the Database's left side. Your whole vocabulary is words like below, right of, above-left of and level with, and you never type a number for a position.
Every placement becomes one rule
Every placement becomes one rule: this box sits at least so far from that one
And this is the part I find clever. Reladraw turns each placement into one rule on one axis, across or down. API below Interface becomes a single rule: the API sits at least one gap further down the page than the Interface. Right of becomes the same kind of rule on the horizontal axis. Reladraw works out the horizontal and the vertical as two separate problems. Level with is the one placement that pins an exact spot. Reladraw writes it as two rules pointing opposite ways, at least this far and at most this far, so only one answer fits. Every word in the language comes down to that same kind of rule.
The longest chain sets the layout
The tightest layout comes from following the longest chain of rules
Now the solve. Every box starts at position zero. Reladraw walks through every rule, and whenever a rule says a box has to sit further along, the box moves up to that spot. Reladraw repeats that walk once for each box, and by then every box has settled. Follow a chain of rules and the distances add up. A box at the end of two chains lands at the end of the longer one, because that's the only spot that satisfies both. The code calls this longest paths. The result is the tightest layout that keeps every rule, and Reladraw never tries a layout and throws it away. So the same file gives you the same picture, every time. When a diagram lives in a repo next to your code, that's exactly what I want from it.
Add a box and its neighbours move apart
Add a box between two others and they move apart; delete it and they close up
Because every gap is a minimum, adding or deleting a box moves the other boxes only as far as they have to go. Here's the two-sides diagram from a minute ago, with the Reladraw box in the middle deleted. The Mermaid side and the draw.io side sit right next to each other. Add one line back. That line puts the Reladraw box right of the Mermaid side, left of the draw.io side, and level with the Mermaid side. The draw.io side moves right by just enough room for that box and its gaps. Delete the line again and the two sides close back up. This is the demo that sold me, because one line of text moved the whole draw.io side, and deleting the line put it back.
When your rules fight
When your rules fight, reladraw quotes the fighting lines back to you
Your rules can also fight. Take a small file with three boxes, A, B and C. B sits right of A, and C sits right of B, so C has to end up right of A. The same file also says C sits left of A. In the solve, a loop like that never settles, and C's position keeps growing on every walk. Reladraw notices when positions are still moving after one walk per box. Then Reladraw traces the loop back and quotes your own words: right of B, left of A, and right of A cannot all hold, because they leave no room horizontally. The error hands you the three lines to fix.
Overlaps move only where your file points
Colliding boxes move only in a direction your file already implies
Reladraw keeps boxes from overlapping, and you never write that rule. When two boxes collide, Reladraw reads the chains of placements your file already wrote. If those chains let one box move away from the other in only one direction, Reladraw uses that direction. Reladraw adds one more minimum distance and solves the whole layout again from scratch. In this file, a wide box sits under the small box in the middle, and the wide box's top edge overlaps the bottom of the tall box on the left. Sliding the wide box sideways would clear the overlap in sixty-one and a half pixels. Pushing it down takes fourteen pixels, so Reladraw pushes it down. The README calls picking the smaller move the one decision the tool makes on its own. In the next file, Queue and Worker both sit below Hub, Worker with a tighter gap, and the two boxes land on each other. The file never says which one goes where, so Reladraw stops and names both boxes. The README puts the rule in one line: the engine's freedom may affect distances and never relationships.
Thirteen preset themes
Thirteen preset themes shipped about ninety minutes after a Hacker News reader asked for them
Same five statements, two new looks. On the left is Solarized Light, and on the right is Dracula, two of thirteen preset themes in today's build. I like the backstory on the themes. On Hacker News, the tech forum where Joe Walsh launched Reladraw, one reader wrote that they wished it had different themes. Joe Walsh answered that preset themes would be a priority, and pushed them about an hour and a half after the request.
The catch: arrows run straight
Any arrow you don’t steer runs straight through whatever box is in the way
The limit I'd weigh most is line routing, meaning steering an arrow around the boxes in its way. Reladraw leaves line routing to you. An arrow with no instructions runs straight from the center of one box to the center of the other. Here, the arrow from Client to Database runs right through Gateway, and the arrow's label covers Gateway's name. You steer an arrow yourself. You can name the side it leaves from, the side it lands on, the gap between two boxes it should run down, and the boxes it passes above or below. The README gives the reason. Which side of a box a line passes is a relationship, so the tool won't pick that side for you. Reladraw also draws a line that crosses a box without a warning, and the README calls that warning an open question. The README also says the language is not stable, so expect the syntax to change.
What the 44 statements hold
The 44 statements hold zero coordinates, and many of them still steer the layout by hand
Back to those forty-four statements with zero coordinates. The count holds up. That's twenty-seven boxes, twelve arrows, and five style lines that set colours and shapes. Eleven of the twelve arrows name the side they leave from and the side they land on. Ten of the box lines ask for a tight gap. Those hints do some of the steering that coordinates used to do, and the arrow hints are how this diagram dodges the straight-line catch. I don't count those hints against Reladraw. You still decide every relationship yourself, and Reladraw takes the arithmetic off your hands.
The pushback: tikz, D2 and Graphviz
D2 treats a position as a hint, and reladraw treats it as a fact
The sharpest pushback came from a Hacker News reader, who said Reladraw works a lot like tikz, a drawing package scientists use in their papers. The reader added: with tikz it was never the nodes that hurt me, it was the edges. Nodes and edges mean the boxes and the lines. Other readers brought up D2 and Graphviz, which already let you nudge a layout. D2 has a keyword called near, for one box near another, and D2's own docs call it a hint to the layout engine. Graphviz can pin a set of boxes to the same row. Reladraw treats a position as a fact. You decide where every box goes, and the engine only works out the distances. I think the edges complaint still lands, because it's the straight-line catch again.
Where reladraw fits today
reladraw fits diagrams where position means something and arrows stay short
In practice, I'd use Reladraw today for diagrams where position carries meaning. Think of layers stacked top to bottom, or a flow that runs left to right, with arrows between neighbours. The architecture diagram from the start is that kind of diagram, and it's the kind I'd rewrite first. A web of cross-links is the kind that will hurt. Every arrow you don't steer crosses whatever sits between its two ends.
Four ways to lay out a diagram
Four ways to lay out a diagram, and where reladraw sits
Here's where I'd put Reladraw next to the others. In Mermaid and D2 you describe what's connected, and the tool decides the picture. Pikchr is an older diagram language with a cursor that drops a shape and steps along, so you steer every step. In draw.io you drag every box by hand. In Reladraw you say which side of what each box sits on, and the tool works out the distances. On Hacker News, Joe Walsh put the difference from pikchr this way. In Reladraw, adding or resizing one box adjusts the rest, without spelling the positions out again.
Who should try reladraw
Who should try reladraw this weekend, and who should wait
Should you try it? If you keep architecture diagrams in a repo, and you're tired of re-dragging boxes, I'd try Reladraw this weekend. The browser playground needs no install, so your first half hour costs you nothing. I'd wait if your diagrams are mostly crossing arrows, or if you need the syntax to hold still. Reladraw is under three weeks old, from one developer, and I'd expect a few of my files to break along the way. And if Mermaid's automatic layout already looks fine to you, you don't need Reladraw.
Try reladraw
Try reladraw in the browser, or install it from npm
The fastest way in is the browser playground, with your text on the left and the diagram redrawing on the right. You can also install Reladraw from npm, the package installer that comes with Node, the program that runs JavaScript outside a browser. Reladraw is free under the Apache 2.0 licence, so you can use it, change it and ship it, even at work. Which diagram in your repo would you rewrite first, and would it survive straight lines? Tell me in the comments. It's Reladraw slash Reladraw, on GitHub. New repo tomorrow.
