Excalidraw

excalidraw

An .excalidraw file is JSON: { type: "excalidraw", version: 2, elements: [...], appState, files }. Elements are rectangles, ellipses, diamonds, text, arrows, lines, frames. The pane is Excalidraw's own editor in view mode; the same file opens in excalidraw.com and the VS Code extension.

Write with the helper, not by hand

scene.py is on PYTHONPATH ($EXCALIDRAW_TOOLCHAIN/scene.py). One script per diagram:

from scene import Scene
s = Scene()                                   # a whiteboard: light canvas, Excalidraw's palette
s.title("Order service", 0, -110)
api = s.box(0, 0, "API", color="blue")        # rectangle; shape="ellipse" | "diamond"
db  = s.box(320, 0, "Postgres", color="green", shape="ellipse")
q   = s.box(0, 180, "Queue", color="yellow", shape="diamond")
s.arrow(api, db, "SQL")                       # bound at both ends; dashed=True, both=True
s.arrow(api, q, "job", dashed=True)
s.note(660, 0, "Retries: 3, backoff 2s", color="yellow")
s.frame([api, db, q], "Backend")              # a named frame around members
s.save("diagram.excalidraw")

Then the verdict: python3 "$EXCALIDRAW_TOOLCHAIN/verdict.py" (or … verdict.py flows/x.excalidraw).

Colours: blue, green, yellow, red, purple, pink, orange, teal, gray, none — Excalidraw's palette. Fonts: font=1 hand-drawn (default), 2 sans, 3 mono (code, paths, hostnames).

Layout that reads

• A grid of 300 px columns and 180 px rows; boxes 160×72 unless a label needs more. Left to right for flow, top to bottom for hierarchy, never diagonal chains.
• One idea per box, two or three words. The verb goes on the arrow ("SQL", "publishes", "HTTPS").
• Frames for boundaries (a service, a network, a team); notes for the one fact that matters (a limit, a retry, a port). At most ~12 boxes per diagram — split otherwise.
• Name every frame: the pane's Present mode steps through frames in reading order (top to bottom, left to right) with the frame name as the step title, so frames double as the walkthrough.
• exports/ is where the pane saves PNG/SVG exports when the user asks for them; do not write diagrams there.
• Sequence diagrams: actors as boxes in a row at y=0, lifelines as s.arrow(a, b, "…") rows stepping down 100 px; sketches: the hand font, few colours.

Editing the JSON directly

For a tweak (move a box, rename a label) edit the file: change x/y, or the text AND originalText of a text element. Keep ids and boundElements as they are; the verdict flags a binding that points at nothing. Regenerate from the script for anything larger.