Tldraw

tldraw Whiteboard Diagrams

Overview

Generate hand-drawn whiteboard-style diagrams as .tldr JSON files and export to PNG/SVG using @kitschpatrol/tldraw-cli. tldraw produces a hand-drawn aesthetic with rich shape libraries and smooth arrow routing — well-suited for casual, sketch-style visualizations rather than polished business diagrams.

Format: .tldr JSON Export: PNG, SVG (via @kitschpatrol/tldraw-cli) Aesthetic: Hand-drawn whiteboard style by default; switchable to clean fonts via font prop.

When to Use

Proactive triggers: explaining a system with 3+ interacting components, describing a multi-step process or data flow, showing relationships between services/modules, decision trees, or ML model layers.

Skip when: a simple list or table suffices, or the user is in a quick Q&A flow.

Known constraints (route elsewhere or set expectations if these matter):

• No opaque fill — solid renders as a light tint, so white-on-dark artwork can't be reproduced.
• Manual coordinates only — no automatic layout of many nodes.
• Arrowheads are filled triangles/diamonds, not the hollow heads strict UML notation uses.
• PDF export isn't supported by tldraw-cli (PNG/SVG only).

Prerequisites

Uses @kitschpatrol/tldraw-cli — a third-party, MIT-licensed export tool maintained independently of the tldraw.dev project. It is not the official create-tldraw project-scaffolding CLI; don't confuse the two. It renders .tldr files to PNG/SVG via a headless Chrome instance (puppeteer).

# Install tldraw-cli
npm install -g @kitschpatrol/tldraw-cli

# Verify
tldraw --version

Works identically on macOS, Windows, and Linux.

First-export note: tldraw export renders through a pinned Chrome build via puppeteer. The first export can fail with Could not find Chrome (ver. <x>). The error names the exact version it needs — install it once, then exports work:

# The error message names the version; substitute it here
npx puppeteer browsers install chrome@<version-from-error>

(Installs to ~/.cache/puppeteer; only needed once per CLI version.)

Workflow

Before starting, assess whether the user's request is specific enough. If key details are missing, ask 1-3 focused questions:

• Diagram type — which preset? (Architecture, Flowchart, Sequence, ML/DL, ERD, UML, or general)
• Output format — PNG (default), SVG?
• Output location — default is the user's working dir; honor any explicit path the user gives (e.g. "put it in ./artifacts/"). Don't ask if they didn't mention one.
• Scope/fidelity — how many components? Any specific technologies or labels?

Skip clarification if the request already specifies these details or is clearly simple (e.g., "draw a flowchart of X").

1. Check deps — verify tldraw --version succeeds; if missing, run npm install -g @kitschpatrol/tldraw-cli.
2. Plan — identify shapes (geo type per node), connections (arrows with source/target), and layout (TB or LR, group by tier/role). Sketch a coordinate grid before writing JSON. See references/diagram-presets.md for layout rules, index ordering, and per-diagram-type shape/color conventions.
3. Generate — write the .tldr JSON file using the record formats in references/tldr-format.md (shapes) and references/arrows-and-containers.md (arrows, frames, notes). Default output dir is the user's working dir; if the user specified a path or directory (e.g. ./artifacts/), mkdir -p it first and write there. Apply the same dir choice to PNG/SVG exports in steps 4 and 7.
4. Export draft — run CLI to produce a PNG for preview. See references/troubleshooting.md for export command syntax.
5. Self-check — use the agent's built-in vision capability to read the exported PNG, catch obvious issues, auto-fix before showing the user (requires a vision-enabled model such as Claude Sonnet/Opus). If vision is unavailable, skip this step.
6. Review loop — show image to user, collect feedback, apply targeted JSON edits, re-export, repeat until approved.
7. Final export — export the approved version to all requested formats; report file paths for both the .tldr source and exported image(s).