Reladraw: a diagram language where the author decides placement, not an algorithm

An early-stage text language for diagrams is drawing attention on Hacker News: Reladraw, published on GitHub under the Apache-2.0 licence, reached 366 points and more than a hundred comments. It is written in TypeScript with no runtime dependencies and ships a parser, a resolver, an SVG renderer, a command-line tool and a browser playground.

The space between auto-layout and pixel-pushing

The author describes the problem as a choice between two families of tools. Mermaid, Graphviz and D2 let you declare boxes and connections and then place everything for you, which stops working the moment a specific picture is in mind. draw.io, Excalidraw and Figma give complete control, at the cost of slow manual work on every edit.

Reladraw sits between them. Every position is stated relative to something else and the file contains no coordinates: a real statement from the documentation reads node resolver right of parser. Gaps are minimum distances, never exact ones, so a third node placed between two others pushes them apart by exactly what it needs.

How the language reads

A file is one statement per line, with no blocks and indentation ignored, and a dotted name means containment: server.docker is drawn inside server. An edge can be told which side of a node to leave and arrive on, and which gap to travel down on the way.

The reference example arch.reladraw reproduces a hand-drawn draw.io diagram in 44 statements, using placements such as above-left of hub and between cluster.desktop1 and cluster.laptop1. The resolver derives distances rather than searching for a layout, and nodes do not overlap by default.

Why the design targets agents

The author argues that the common case is not drawing a diagram but changing one: with pixel coordinates an agent must reconstruct the picture from the numbers, and with automatic layout the arrangement was never written down. Where placement is stated, an edit is a change of sentence. An agent skill, installed with npx skills add reladraw/reladraw -g, teaches the syntax to coding agents.

What is still missing

The diagnostics report is next on the project's status list: the tool either renders or fails, and cannot yet say what is wrong with a picture it drew successfully. In the discussion, one commenter pointed to D2's TALA layout engine as an alternative with more manual control; the author replied that TALA keeps automatic layout and only adds ways to coax it. A reported bug with curved edges was fixed in the playground.