drawspec

[Image] drawspec

[PyPI] [License: MIT] [drawspec MCP server – quality and maintenance score on Glama] [drawspec on mcprush]

[Built with claude-arsenal]

[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]

Diagrams from a JSON description — no coordinates, so nothing to misplace. You say what the diagram means: the boxes, the arrows, the labels, and a role for each. drawspec decides every position, size, route and colour, and draws a clean SVG, PNG or plain-text diagram.

It is built for language models first. An LLM that writes SVG by hand gets the content right and the placement wrong — arrows that miss their boxes, text that spills out, lines that stop short. A drawspec document has no x, y or font size to get wrong: those fields are refused, and every mistake comes back as an error pointing at the exact field, so the model can fix it and try again.

pip install drawspecdrawspec render diagram.json -o diagram.svg

Browse the gallery: more than 30 kinds, drawn →

Example

You write this:

{  "$schema": "https://nuncaeslupus.github.io/drawspec/schema/drawspec-v1.schema.json",  "version": 1,  "kind": "flow",  "title": "The nightly import",  "description": "The vendor's export is fetched, checked and loaded into staging before it replaces the live table; a timeout and a deadlock are each retried in place.",  "nodes": [    {"id": "fetch", "text": "Fetch the vendor's export", "role": "start"},    {"id": "check", "text": "Do the row counts match?", "role": "decision"},    {"id": "load", "text": "Load into staging"},    {"id": "page", "text": "Page the data owner", "role": "terminal"},    {"id": "swap", "text": "Swap staging into live", "role": "terminal"}  ],  "edges": [    {"from": "fetch", "to": "fetch", "label": "timed out: retry"},    {"from": "fetch", "to": "check"},    {"from": "check", "to": "load", "label": "yes"},    {"from": "check", "to": "page", "label": "no"},    {"from": "load", "to": "load", "label": "deadlock: retry"},    {"from": "load", "to": "swap"}  ]}

drawspec draws this:

[A flow chart: fetch the vendor's export, retried on timeout; check the row counts; on a match load into staging, retried on deadlock, then swap into live; otherwise page the data owner]

The same document as text, for a terminal, a commit message or a code block (--format text --charset ascii):

             *---------------------------*             | Fetch the vendor's export +-+ timed out: retry             |                           |<+             *-------------+-------------*                           |                           v                       +--------------------------+                       < Do the row counts match? >                       ++-------------------+-----+                        | yes               | no                   +----+                   |                   v                        v+-------------------+                      .---------------------.| Load into staging +-+ deadlock: retry    ( Page the data owner )|                   |<+                    '---------------------'+---------+---------+          |          v       .------------------------.       ( Swap staging into live )       '------------------------'

A sequence diagram works the same way — participants and messages in order; activation bars, arrows and spacing are worked out for you:

{  "version": 1,  "kind": "sequence",  "title": "Resolving a name the first time",  "caption": "Nothing is cached yet, so the resolver walks the hierarchy from the top.",  "participants": [    {"id": "laptop", "text": "Laptop"},    {"id": "resolver", "text": "Recursive resolver", "role": "emphasis"},    {"id": "root", "text": "Root server"},    {"id": "tld", "text": "`.org` server"},    {"id": "auth", "text": "Authoritative server"}  ],  "messages": [    {"from": "laptop", "to": "resolver", "text": "where is `wiki.example.org`?"},    {"from": "resolver", "to": "root", "text": "where is `wiki.example.org`?"},    {"from": "root", "to": "resolver", "text": "ask the `.org` servers", "role": "weak"},    {"from": "resolver", "to": "tld", "text": "where is `wiki.example.org`?"},    {"from": "tld", "to": "resolver", "text": "ask `ns1.example.org`", "role": "weak"},    {"from": "resolver", "to": "auth", "text": "where is `wiki.example.org`?"},    {"from": "auth", "to": "resolver", "text": "`203.0.113.7`", "role": "weak"},    {"from": "resolver", "to": "resolver", "text": "cache it for the TTL", "note": "the next lookup stops here"},    {"from": "resolver", "to": "laptop", "text": "`203.0.113.7`", "role": "weak"}  ]}

[A sequence diagram: a laptop asks a recursive resolver, which asks the root, the .org server and the authoritative server in turn, caches the answer and replies]

More than 30 kinds of diagram

Flow charts, sequence diagrams, state machines, ER and class diagrams, Gantt charts, swimlanes, mind maps, timelines, Venn, Sankey, treemaps, pie and bar charts, kanban boards, fishbone, family trees, file trees, timing diagrams, network diagrams, tournament brackets, cladograms and more — one format for all of them. Click a drawing to open it full size, or a kind's name for its source — the code is all here.

The full list: 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 · clock · sunburst · timing · gitgraph · network · railroad · usecase · wardley · packet · pert · automaton · neuralnet. Each has an example in docs/reference, and the gallery (docs/gallery/index.html) draws every one.

Using it from an LLM

• MCP server — pip install 'drawspec[mcp]' adds drawspec-mcp, with the tools list_kinds, get_example, get_schema, validate_document and render_document. A mistake comes back as data the model can act on: {"pointer": "/edges/0/to", "message": …}. See the guide.
• AGENTS.md — the whole format on one page, written for a model to read in one pass: which kind fits, the size limits, the roles, worked examples, and what each error means. llms.txt indexes it.
• Agent Skill — copy skills/drawspec/ into your skills directory.
• JSON Schema — start a document with "$schema": "https://nuncaeslupus.github.io/drawspec/schema/drawspec-v1.schema.json" for completion and errors as you type, in an editor or a structured-output call.

A typical loop: the model picks a kind, writes the JSON, calls validate_document, fixes what is reported, and renders.

What you get

• SVG that pastes inline into Markdown or HTML: it takes the page's text colour, carries no global styles or colliding ids, and never relies on colour alone, so it works in dark mode and in greyscale print. --variant dark=<theme> adds a dark version that follows prefers-color-scheme.
• PNG on a light, dark or transparent background (pip install 'drawspec[png]').
• Plain text (box-drawing or ASCII) for many kinds, including flows, state machines, sequences, Gantt charts, syntax diagrams, file trees and packet headers (as an RFC draws them).
• Themes: change one TOML file and every diagram in a project follows. drawspec theme from site.css builds one from your CSS or design tokens.
• Readable by design: each kind has a size budget; past it, drawspec asks you to split the diagram rather than draw a dense one.

Command line

drawspec render diagram.json -o diagram.svg          # or to stdoutdrawspec render diagram.json -o diagram.png          # needs drawspec[png]; --background dark, --scale 3drawspec render diagram.json --theme blueprint -o sheet.pngdrawspec render diagram.json --format text           # 80 columns; --charset asciidrawspec validate diagram.json                       # every error, by JSON pointerdrawspec theme from site.css -o house.toml           # a theme from your CSSdrawspec schema --out drawspec-v1.schema.json        # for editor completion

What it is not

• Not a graph-layout engine. For a hundred-node graph, use Graphviz.
• Not a plotting library. chart states a few numbers you already know; it has no statistics, dates, log scales or interactivity.
• Not a drawing program. Anything whose point is where things are — a floor plan, a map — has no place in a format without coordinates.

Documentation

The references are generated from the code (make docs), and a test fails if they drift.

Development

make sync     # install with dev extrasmake lint     # ruff + strict mypymake test     # pytestmake gallery  # render every reference document into docs/gallerymake readme   # redraw the README's example images in docs/readmemake docs     # regenerate the format, CLI and theme referencesmake schema   # regenerate the published JSON Schema

The library is in src/drawspec/, the examples in docs/reference/, the tests in tests/. docs/brief.md and corpus/ hold the original design brief and the evidence it was based on. .claude/ and claude-arsenal/ are development tooling and do not affect the package.

Related projects

Built with claude-arsenal, a spec-driven Claude Code workflow whose skills draw their diagrams with drawspec. By the same author:

• integral-job-search — a candidate-centred job search run as a conversation in Claude Code.
• literary-critic — lets an LLM index, analyse and advise on a full novel manuscript the way a professional editor would.
• doc-control — a deterministic tool for AI agents to edit Word documents as tracked changes (in development).

License

MIT — see LICENSE.