Most technical diagrams are created using one of two extremes: auto-layout engines or absolute-positioning tools. Auto-layout tools like Mermaid, Graphviz, and D2 allow you to declare entities and connections, but the software decides where they land [1]. Conversely, tools like Figma, Excalidraw, and draw.io offer total control over placement, but every edit to a complex diagram requires slow, manual movement of elements [1].
Reladraw introduces a middle ground. It is a text language for diagrams where you describe where things go using relative terms rather than coordinates [1]. Instead of guessing how an algorithm will render a flow or manually dragging boxes across a canvas, you state the arrangement in plain language [S1, S3].
Wie relative Platzierung funktioniert
In reladraw, every position is stated relative to another element [1]. There are no coordinates in the language in any form [3]. Instead, you use directional statements to bind nodes to one another [2].
For example, a node can be placed above, below, left of, or right of another node [2]. You can also use combined directions, such as above-left of, or use level with to ensure two elements share a center line [2]. To handle more complex groupings, you can place an element right of A and B, which aligns it against the box that bounds both elements [2].
Distances in reladraw are handled as minimum gaps rather than exact measurements [3]. A gap is never an exact number; instead, elements end up as close together as the statements allow [3]. If you place a node between two others, it pushes them apart by exactly what is needed to fit [3]. If that middle node is deleted, the remaining elements close back up automatically [3].
Verbesserung der Diagrammerstellung durch KI‑Agenten
Traditional diagramming tools create a “blind spot” for AI agents. When an agent emits Mermaid code, it is guessing at a layout that an algorithm settles later [1]. The agent cannot see the resulting SVG, meaning it must render the image and look at it to find errors, creating a slow round-trip process [3].
With pixel-based tools, the problem is different. An agent must rebuild the entire picture from a list of numbers before it can decide which coordinates to change to move a single service [1].
Reladraw solves this by putting the arrangement directly into the source file as sentences [1]. This allows an agent to:
- Confirm intent by re‑reading the source to verify a database is
underan API [S1, S3]. - Change the picture by simply editing the sentence that defines a position [1].
- Avoid the need to interpret complex coordinate systems [1].
However, because the tool resolves the final render from these statements, an agent cannot confirm certain outcomes through text alone [3]. It cannot tell if a long text string overflowed its node or if two independently anchored clusters overlapped without a visual render or a diagnostics report [3].
Syntax und Implementierung
Reladraw uses a simple, one‑statement‑per‑line format with no nesting or significant indentation [3]. This ensures that no single line depends on the position of another [1].
Key syntax elements include:
- Nodes: Defined as
node name "text"[2]. Dotted names (e.g.,server.docker) indicate a child node, provided the parent is declared first [2]. - Edges: Connections are defined using arrows, such as
edge a -> b[2]. You can specify the curve of the line usingfrom: right to: left[2]. - Styling: Appearance is handled via a
stylekeyword or within brackets after the text, allowing for custom colors, sizes, and shapes likerectangle,document, ordatabase[2].
To use reladraw, you can write a .reladraw file and render it to a standalone SVG using the command reladraw diagram.reladraw -o diagram.svg [3]. For those using AI assistants like Claude Code, Cursor, or Copilot, a specific agent skill can be installed via npx skills add reladraw/reladraw -g to teach the model the language syntax [1].
If you want to experiment with the language without installing anything, you can try the reladraw playground in your browser to watch layouts re‑solve in real‑time as you edit the source [S1, S2].
