drawspec

# <img src="https://raw.githubusercontent.com/nuncaeslupus/drawspec/main/docs/logo.png" width="40" height="40" alt="" align="top"> drawspec

<!-- mcp-name: io.github.nuncaeslupus/drawspec -->

<!-- claude-arsenal:attribution: added by claude-arsenal's /init. Delete this block to drop it (it is not put back), or set `attribution = false` in the arsenal config.toml. -->
[![Built with claude-arsenal](https://img.shields.io/badge/built%20with-claude--arsenal-d97756)](https://github.com/nuncaeslupus/claude-arsenal)
<!-- /claude-arsenal:attribution -->

<p align="center">
  <img src="https://raw.githubusercontent.com/nuncaeslupus/drawspec/main/docs/hero.png" width="100%" alt="drawspec: a blueprint sheet with the wordmark, a JSON flow spec and the flow chart drawspec renders from it, with large faint venn and pie drawings behind the wordmark, a mind map and a project file tree drawn by drawspec, and beside them a small sequence diagram as drawspec's text output, once in box drawing and once in ASCII">
</p>

Declarative diagram spec → clean, themeable SVG. Writable by an LLM with no
coordinates to get wrong.

For anyone — person or language model — who puts diagrams in docs, specs and
READMEs and is tired of arrows that miss their boxes:

```bash
pip install drawspec && drawspec render diagram.json -o diagram.svg
```

**[See every kind drawn in the gallery →](https://nuncaeslupus.github.io/drawspec/docs/gallery/)**

> **Status: it draws.** All thirty-six kinds render — `flow`, `tree`, `cycle`,
> `stack`, `timeline`, `columns`, `matrix`, `pyramid`, `rings`, `funnel`,
> `chart`, `quadrant`, `scatter`, `curve`, `files`, `states`, `sequence`, `lanes`,
> `entities`, `gantt`, `board`, `fishbone`, `venn`, `journey`, `treemap`, `sankey`, `numberline`, `barmodel`, `waterfall`, `pie`, `mindmap`, `argument`, `familytree`, `meter`, `rag` and `clock` — and each of
> the eleven failure families below has a test asserting it cannot be expressed.
> The vocabulary opened from nine to thirteen on evidence: see `docs/kinds-wanted.md`, which
> sorts all 89 hand-drawn originals by the kind that would have to draw them.
> `scatter` is the fourteenth, added on a different kind of evidence: a real
> consumer's need for two continuous, ticked axes, which `quadrant` refuses.
> `files` is the fifteenth: a directory listing drawn from its paths, as
> pictures or as the `tree`-style text a code block wants. `states` is the
> sixteenth: a state machine, with its initial and final dots, labelled
> transitions, self-loops, and a refusal for any state nothing reaches.
> `sequence` is the seventeenth: messages between participants, in order,
> with activation bars inferred from each call and its reply. `lanes` is the
> eighteenth: a `flow` document whose actors are drawn as swimlanes, so every
> hand-off between parties is an arrow crossing a lane. `entities` is the
> nineteenth: ER models, database schemas and class diagrams as one kind — boxes
> of fields, relations that can land on one row, crow's feet or multiplicities at
> the ends, and inheritance with a hollow triangle. `gantt` is the twentieth: a
> plan, one row per task, with phases, milestones, finish-to-start dependencies
> and marks such as *today* — on a numbered axis in a unit you name, never dates.
> `board` is the twenty-first: cards sorted into columns — a kanban board with
> work-in-progress limits drawspec counts, a retrospective, or a story map whose
> releases are slices across the columns with a heavy cut under the first.
> `fishbone` is the twenty-second: one effect and the causes investigated,
> grouped by category on bones slanting into a spine — the root cause drawn heavy.
> `venn` is the twenty-third: two or three equal circles (four equal ellipses), each region's words
> named by the sets it is in and placed inside it — no coordinates, no sizes.
> `journey` is the twenty-fourth: one person's feeling, a named level per stage,
> drawn as a line through every stage over what they do there — no scores.
> `treemap` is the twenty-fifth: the parts of one known total, each a rectangle
> by its area with its label inside it — a few proportions stated, not explored.
> `sankey` is the twenty-sixth: where a known quantity goes, each flow a band as
> thick as its amount, columns derived from the flows — a few flows stated, not explored.
> `numberline` is the twenty-seventh: values and ranges on one scale, each end of a
> range in or out of it — an inequality, the pH scale, a spectrum; not *when*, which is `timeline`.
> `barmodel` is the twenty-eighth: a word problem as bars of parts in proportion,
> braced with their checked totals — the bar model, or tape diagram, of primary maths.
> `waterfall` is the twenty-ninth: how one total became another, step by step, every
> subtotal checked against the running sum — the bridge chart of a budget paper.
> `pie` is the thirtieth: the shares of one known total as labelled sectors — a few
> proportions stated, as on a `treemap`, with a donut as a theme's choice.
> `mindmap` is the thirty-first: a topic in the middle and its branches round it as
> peers, nested three deep and balanced on two sides — where a `tree` would rank them.
> `argument` is the thirty-second: a claim and the points for and against it, tagged and
> hatched by stance, co-premises under one bracket — the argument map of a law or
> critical-thinking course.
> `familytree` is the thirty-third: people, the couples they form and their children,
> a generation to a row and numbered for you (II-3), in the standard's symbols — the
> pedigree of a genetics clinic, and the family tree of a history lesson.
> `meter` is the thirty-fourth: one amount against its scale — a progress bar, a
> fundraising thermometer, a dial or a bullet graph, alone or a few to a panel, every
> band named in words.
> `rag` is the thirty-fifth: workstreams or risks rated red, amber or green — a
> highlight report, a risk register — each rating a word and a shape, never colour alone,
> with its trend written in words.
> `clock` is the thirty-sixth: analogue clock faces showing a time, for teaching it — the
> hour hand moving on with the minutes, the time in words under each face or hidden for a
> worksheet, and how long since an earlier time shaded round the face.
> A `flow` also draws a causal loop diagram: a sign on every arrow, delay marks,
> and named loops marked R or B, the type derived from the signs, never written.

## The problem

Language models draw diagrams by emitting SVG with absolute `x`/`y`
coordinates, and they fail at the same things every time: arrows with a head
but no shaft, text that escapes its box, lines that stop short of the shape
they point at, a different font size in every element.

These are not failures of judgement. In a corpus of 87 LLM-written diagrams
reviewed by a human, **63 drew a complaint, and every one was about placement,
not content** — nobody disputed what the diagram said, only where things ended
up. See `docs/brief.md` for the measured breakdown.

Placement failures cannot be reviewed away: a cheap mechanical check over
finished SVG catches 17 of those 63 and misses 46. They have to be made
impossible to express.

## The approach

The author writes what the diagram *means* — nodes, edges, labels, and a
semantic role for each. Everything that can be got wrong without seeing the
result is not in the format at all:

| The author writes | The tool decides |
|---|---|
| Nodes, edges, labels | Coordinates, box sizes, canvas size |
| A semantic role per node | Font family and size, colour, stroke weight |
| Grouping and diagram type | Edge routing, anchor points, arrowheads |
| An optional size budget | Overlap resolution, label placement |

Output is SVG that can be pasted inline into a Markdown document: colour
inherited from the surrounding page, no global `<style>`, no ids that collide
when two diagrams share a page, and no information carried by colour alone —
so it survives dark mode and greyscale printing. For anywhere an SVG cannot go —
a chat, a slide, an attachment — the same drawing comes out as a PNG on a light,
dark or transparent background (`pip install 'drawspec[png]'`, one self-contained
wheel; no PDF, no JPEG). And for where no picture draws — a terminal, a commit
message, a code block — twelve kinds, flows and state machines among them, come out
as plain text, box-drawing or ASCII: 80 columns, 100 for swimlanes and sequences,
or whatever `--width` you give.

A small sequence, [`sequence-terminal.json`](docs/reference/sequence-terminal.json), as
`drawspec render docs/reference/sequence-terminal.json --format text` draws it, and
with `--charset ascii` added:

<table>
<tr><th><code>--format text</code></th><th><code>--charset ascii</code></th></tr>
<tr>
<td>

```text
┌───────┐     ┏━━━━━━━━━━┓
│ Shell │     ┃ drawspec ┃
└───┬───┘     ┗━━━━┯━━━━━┛
    │ flow.json    │
    ├─────────────▶┃
    │ the drawing  ┃
    │◁┄┄┄┄┄┄┄┄┄┄┄┄┄┤
    │              │
```

</td>
<td>

```text
+-------+     #==========#
| Shell |     # drawspec #
+---+---+     #====#=====#
    | flow.json    |
    +------------->#
    | the drawing  #
    |<<............+
    |              |
```

</td>
</tr>
</table>

## What it looks like

Three documents and the drawings they produced. Nothing was positioned by hand,
and every one of these is a file in [`docs/reference/`](docs/reference) that
`make gallery` renders — so the picture is always the render of the spec beside
it.

### A flow

```json
{
  "version": 1,
  "kind": "flow",
  "title": "Triaging a report",
  "nodes": [
    {"id": "arrive", "text": "A report arrives", "role": "start"},
    {"id": "repro", "text": "Does it reproduce?", "role": "decision"},
    {"id": "fix", "text": "Schedule a fix", "role": "step"},
    {"id": "ask", "text": "Ask for the document", "role": "terminal"}
  ],
  "edges": [
    {"from": "arrive", "to": "repro"},
    {"from": "repro", "to": "fix", "label": "yes"},
    {"from": "repro", "to": "ask", "label": "n