Reladraw: A Diagramming Language for Precise Placement

Reladraw is a text-based language designed for creating diagrams where the author—not an algorithm—determines the spatial arrangement of elements.

"I wanted to be able to create custom, expressive diagrams where I decided how to arrange the diagram, but without the inefficiency of manually drawing in draw.io."

The Problem Space

Most diagramming tools fall into two extreme categories. Reladraw aims to bridge this gap:

Tool Type	Examples	Placement Logic	Pros	Cons
Declarative	Mermaid, Graphviz, D2	Automated	Fast to write	$\text{Lack of control}$
Manual	draw.io, Excalidraw	Absolute	Total control	~~Highly inefficient~~
Reladraw	`reladraw`	Relative	Expressive & Fast	Syntax is evolving

Visualizing the Gap

The two ends of the spectrum, with reladraw between them

How it Works: Relative Positioning

Unlike absolute coordinates, Reladraw uses relative logic. Mathematically, the position of a node $N_2$ can be defined as a function of $N_1$ : $Pos(N_2) = Pos(N_1) + \text{offset}(\text{direction})$

Example Comparison

Manual Reference: Hand-drawn reference diagram

Reladraw Render: reference diagram via reladraw

The Source Code:

node app "Web app" 
node app.ui "Interface" 
node app.api "API" below app.ui 

node store "Database" right of app level with app 

edge app.api - store "queries" from: right to: left

Getting Started

Install the CLI
Create a .reladraw file
Render to SVG

Installation

To install globally via npm: npm install -g reladraw

To render a file: reladraw diagram.reladraw -o diagram.svg

Alternatively, you can build from a clone to access examples:

npm install
npm run build
node dist/cli.js examples/arch.reladraw -o out.svg

Integration with AI Agents

You can provide a "skill" to your AI agent (such as Claude Code, Cursor, Copilot, or Codex) so it understands how to write Reladraw:

Global installation for all agents: npx skills add reladraw/reladraw -g

Targeted installation for a specific agent (e.g., claude-code): npx skills add reladraw/reladraw -g -a claude-code

Note: Since this captures a snapshot of the skill, you must re-run the command to update to the latest release.

Technical Specifications & Project Status

Core: Written in TypeScript.
Dependencies: Zero runtime dependencies.
Output: Generates standard SVG files.
License: Apache-2.0.

[!WARNING] The language is ~~stable~~ not stable yet. Expect the syntax to change frequently.

Contribution Guidelines:

If you find a diagram that cannot be represented in Reladraw, please share it.
While the project is evolving, opening an issue is currently more helpful than submitting a pull request.
Legal Note: Use of the software grants no rights to the "reladraw" name, logo, or associated trademarks.