Use when user requests diagrams, flowcharts, architecture charts, or visualizations. Also use proactively when explaining systems with 3+ components, complex data flows, or relationships that benefit from visual representation. Generates .tldr JSON files and exports to PNG/SVG locally using @kitschpatrol/tldraw-cli.
Use when user requests diagrams, flowcharts, architecture charts, or visualizations. Also use proactively when explaining systems with 3+ components, complex data flows, or relationships that benefit from visual representation. Generates .tldr JSON files and exports to PNG/SVG locally using @kitschpatrol/tldraw-cli.
license
MIT
homepage
https://github.com/Agents365-ai/tldraw-skill
compatibility
Requires Node.js + @kitschpatrol/tldraw-cli on PATH (macOS/Linux/Windows). Self-check step requires a vision-enabled model (e.g., Claude Sonnet/Opus); gracefully skipped if unavailable.
Generate modern whiteboard-style diagrams as .tldr JSON files and export to PNG/SVG using @kitschpatrol/tldraw-cli. tldraw produces clean hand-drawn aesthetic diagrams with rich shape libraries and smooth arrow routing — well-suited for casual or whiteboard-style visualizations.
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
Explicit triggers: user says "diagram", "flowchart", "draw", "visualize", "whiteboard diagram", "tldraw diagram", "architecture diagram", "sketch this out".
Proactive triggers:
Explaining a system with 3+ interacting components
Describing a multi-step process, data flow, or pipeline
Showing relationships between services/modules
Architecture overviews, sequence flows, decision trees, ML model layers
Skip when: a simple list or table suffices, the user wants a polished business-presentation diagram (prefer drawio-skill), or the user is in a quick Q&A flow.
When NOT to use it — route elsewhere:
Logos / solid-color graphics / filled icons: tldraw has no opaque fill (solid = light tint; white-on-dark can't be reproduced) → use the drawio skill or the original vector file.
Precise vector geometry or strict (hollow-arrow) UML → drawio (or plantuml for UML).
Auto-layout of many nodes → mermaid (tldraw needs manual coordinates).
A pixel-faithful copy of an existing image → not a diagram-skill task.
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").
Check deps — verify tldraw --version succeeds; if missing, run npm install -g @kitschpatrol/tldraw-cli.
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.
Generate — write the .tldr JSON file. 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.
Export draft — run CLI to produce a PNG for preview.
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.
Review loop — show image to user, collect feedback, apply targeted JSON edits, re-export, repeat until approved.
Final export — export the approved version to all requested formats; report file paths for both the .tldr source and exported image(s).
Step 5: Self-Check
After exporting the draft PNG, use the agent's vision capability (e.g., Claude's image input) to read the image and check for these issues before showing the user. If the agent does not support vision, skip self-check and show the PNG directly.
tldraw's own AI agent flags exactly three structural defects — text overflow (a box too small for its label), overlapping text, and friendless arrows (an arrow with an unbound end). The first three rows below target those; size boxes correctly up front (see "Sizing boxes to fit labels") and they rarely occur.
Check
What to look for
Auto-fix action
Text overflow
Label spills past the shape's border, or the box looks taller than you set (tldraw auto-grows an undersized box)
Increase w/h to fit the label — see the sizing formula below
Overlapping text
Two text-bearing shapes' labels touch or overlap, hurting legibility
Shift shapes apart by ≥200px
Friendless arrow
An arrow with one end not connected to a shape (floats loose)
Bind both ends: every arrow's start and end need a boundShapeId matching an existing shape
Off-canvas shapes
Shapes at negative coordinates or far from the main group
Move to positive coordinates near the cluster
Arrow-shape overlap
An arrow visually crosses through an unrelated shape
Adjust bend value or move endpoints to a different normalizedAnchor side
Stacked arrows
Multiple arrows overlap each other on the same path
Distribute normalizedAnchor across the shape perimeter (use different x/y values)
Max 2 self-check rounds — if issues remain after 2 fixes, show the user anyway.
Re-export after each fix and re-read the new PNG.
Step 6: Review Loop
After self-check, show the exported image and ask the user for feedback.
Targeted edit rules — for each type of feedback, apply the minimal JSON change:
User request
JSON edit action
Change color of X
Find shape by props.text matching X, update props.color
Add a new node
Append a new shape record with next available index, position near related nodes
Remove a node
Delete the shape record and any arrow records bound to it
Move shape X
Update the shape's x/y fields
Resize shape X
Update props.w/props.h
Add arrow from A to B
Append a new arrow record binding to A and B's shape ids
Change label text
Update props.text on the matching shape or arrow
Change layout direction
Full regeneration — replan the grid and rebuild
Rules:
For single-element changes: edit the existing JSON in place — preserves layout tuning from prior iterations.
For layout-wide changes (e.g., swap LR↔TB, "start over"): regenerate full JSON.
Overwrite the same {name}.png each iteration — do not create v1, v2, v3 files.
After applying edits, re-export and show the updated image.
Loop continues until user says approved / done / LGTM.
Safety valve: after 5 iteration rounds, suggest the user open the .tldr file in tldraw.com or the desktop app for fine-grained adjustments.
File Format
Complete .tldr Skeleton
{"tldrawFileFormatVersion":1,"schema":{"schemaVersion":1,"storeVersion":4,"recordVersions":{"asset":{"version":1,"subTypeKey":"type","subTypeVersions":{"image":2,"video":2,"bookmark":0}},"camera":{"version":1},"document":{"version":2},"instance":{"version":17},"instance_page_state":{"version":3},"page":{"version":1},"shape":{"version":3,"subTypeKey":"type","subTypeVersions":{"group":0,"embed":4,"bookmark":1,"image":2,"text":1,"draw":1,"geo":7,"line":0,"note":4,"frame":0,"arrow":1,"highlight":0,"video":1}},"instance_presence":{"version":4},"pointer":{"version":1}}},"records":[{"id":"document:document","typeName":"document","gridSize":10,"name":"","meta":{}},{"id":"page:page1","typeName":"page","name":"Page 1","index":"a1","meta":{}}/* shapes and arrows go here */]}
Critical rules:
document:document and page:page1 records are ALWAYS required.
All shapes go in the records array after the page record.
All shapes have "parentId": "page:page1".
Shape IDs use format "shape:xxx" with unique suffix (e.g., "shape:s1", "shape:a1").
index values are fractional-index keys. Use "a" + one base-62 character, in order: "a0"–"a9", then "aA"–"aZ", then "aa"–"az" (62 ordered keys — enough for any normal diagram).
Do not append a second character: "a10" is invalid. And never use a leading "b"/"c" ("b1", "c1", "b0") — those encode a longer integer part, so they are malformed fractional keys and trigger invalidRecords. Stick to the single-character "a*" keys above.
Use "type": "binding" with boundShapeId to connect to a specific shape.
normalizedAnchor specifies WHERE on the target shape the arrow connects (0–1 range):
{x: 0.5, y: 0} = top center
{x: 0.5, y: 1} = bottom center
{x: 0, y: 0.5} = left center
{x: 1, y: 0.5} = right center
{x: 0.5, y: 0.5} = center
Add "text": "label" in arrow props for labeled connections.
Use "bend": 20 (or -20) for slight curves to avoid overlap with other arrows.
For dashed/dotted arrows (e.g., async flows, optional links), set "dash": "dashed" or "dotted".
Set "spline": "cubic" for a smooth curved arrow (default "line" is straight/elbow). Useful for skip connections and back-edges.
Arrowheads
arrowheadStart and arrowheadEnd each accept any of these 9 values (all render in @kitschpatrol/tldraw-cli):
Value
Looks like
Use for
none
(no head)
start of a one-way arrow
arrow
open V
default flow direction
triangle
filled ▶
UML inheritance / "is-a"
diamond
filled ◆
UML composition / aggregation (on the owner end)
dot
●
sequence-diagram message endpoints
square
■
terminal / fixed endpoint
bar
|
"stop" / boundary marker
pipe
||
alternative boundary marker
inverted
hollow V
de-emphasized direction
Default arrows use "arrowheadStart": "none", "arrowheadEnd": "arrow". For bidirectional links set both ends to "arrow".
Distributing Arrows on a Shape
When multiple arrows connect to the same shape, assign different normalizedAnchor points to prevent stacking:
Position
x
y
Use when
Top center
0.5
0
connecting to node above
Top-left
0.25
0
2nd connection from top
Top-right
0.75
0
3rd connection from top
Right center
1
0.5
connecting to node on right
Bottom center
0.5
1
connecting to node below
Left center
0
0.5
connecting to node on left
Rule: if a shape has N connections on one side, space them evenly (e.g., 3 connections on bottom → x = 0.25, 0.5, 0.75).
Multiple Arrows Between the Same Two Nodes
The anchor-distribution rule above spreads arrows going to different nodes. When N arrows connect the same pair (e.g., bidirectional request/response, or several relationships A↔B), anchors can't separate them — instead spread the bend values symmetrically so the arrows fan out into distinct arcs:
Pick a max bend amount (≈ 30–60; larger for nodes that are far apart).
Assign the N arrows bends evenly spaced from −amount to +amount:
2 arrows → bend: -amount, bend: +amount
3 arrows → bend: -amount, 0, +amount
General: bend[i] = -amount + i * (2*amount / (N-1)) for i = 0..N-1
A straight arrow plus a single curved one (bend: 0 and bend: 40) reads cleanly for a request/response pair.
Container & Annotation Shapes
Beyond geo and arrow, two more shape types are useful for technical diagrams.
A frame is a native rectangular container with a title. Use it to group a tier or subsystem with a visible boundary; stack several frames to approximate swimlanes.
props.name is the title shown at the frame's top-left.
Child shapes set "parentId": "shape:frame1" (not page:page1), and their x/y are relative to the frame's top-left corner, not the page. A child at x: 40, y: 60 sits 40px in and 60px down from the frame's origin.
Frames render as a clean (non-hand-drawn) rectangle — good for structural grouping. Arrows can still bind across frames normally.
Note (sticky-note annotation / callout)
A note is a sticky note — ideal for TODOs, callouts, and comments layered onto a diagram.
A note has no w/h — it's a fixed square (~200px) that auto-grows for longer text. Don't add w/h.
yellow is the classic sticky color; any palette color works.
Use notes sparingly — for annotations about the diagram, not as primary nodes (use geo for those).
Index Ordering Rules
Indices control z-order (stacking). Use this sequence:
a1, a2, a3, a4, a5, a6, a7, a8, a9,
aA, aB, aC, aD, aE, aF, aG, aH, aI, aJ, aK, aL, aM,
aN, aO, aP, aQ, aR, aS, aT, aU, aV, aW, aX, aY, aZ,
aa, ab, ac, ... az ← continue here past aZ; never "a10"
Geo shapes first: a1 through aF (or as many as needed).
Arrow shapes after: aG, aH, etc.
Every shape must have a unique index.
Layout Tips
Spacing — scale with complexity:
Diagram complexity
Nodes
Horizontal gap
Vertical gap
Simple
≤5
200px
150px
Medium
6–10
280px
200px
Complex
>10
350px
250px
Sizing boxes to fit labels (do this up front, not in self-check): the draw font is wide. Compute w/h from the label so text never clips. Approximate per-character width and line height for the default draw font:
size
char width (px)
line height (px)
s
11
18
m (default)
15
28
l
22
40
xl
32
56
With padding = 16 on each side:
w = ceil(longest_line_chars * char_width + 2*padding), then round up to the next multiple of 10.
h = ceil(num_lines * line_height + 2*padding), rounded up to a multiple of 10.
Example: a size-m box labeled "API Gateway" (11 chars, 1 line) → w ≈ 11*15 + 32 = 197 → 200, h ≈ 28 + 32 = 60. Multi-line labels (with \n) count the longest line for w and the line count for h. Err slightly large — extra padding looks fine, a too-narrow box hard-wraps a word mid-letters.
Why this matters: if a box is too short for its text, tldraw silently grows it taller on render (it sets the shape's growY) — so the box ends up bigger than the h you wrote and collides with whatever you placed below it. Sizing correctly up front keeps growY at 0 and your layout intact. This is the single most common cause of "the diagram looks cramped / boxes overlap" after export.
Routing corridors: between shape rows/columns, leave an extra ~80px empty corridor where arrows can route without crossing other shapes. Never place a shape in a gap that arrows need to traverse.
Grid alignment: snap all x, y, w, h values to multiples of 10 — this matches tldraw's default gridSize: 10 and makes manual editing easier.
General rules:
Plan the grid before assigning x/y coordinates — sketch node positions mentally first.
Group related nodes in the same horizontal or vertical band.
Place heavily-connected "hub" nodes centrally so arrows radiate outward instead of crossing.
For wide shapes (like an API Gateway spanning multiple downstream services), set w to cover the full span.
Center-align a child node under its parent (same center x) to avoid diagonal routing.
Event bus pattern: place the bus (hexagon) in the center of the service row, not below — services on either side reach it with short horizontal arrows (normalizedAnchor.x = 1 left side, 0 right side), eliminating crossings.
Horizontal connections never cross vertical nodes in the same row; use them for peer-to-peer and publish connections.
Avoiding arrow-shape overlap:
Before finalizing coordinates, trace each arrow path mentally — if it must cross an unrelated shape, either move the shape or use bend to curve around.
For tree/hierarchical layouts: assign nodes to layers (rows), connect only between adjacent layers to minimize crossings.
For star/hub layouts: place the hub center, satellites around it — arrows stay short and radial.
Diagram Type Presets
When the user requests a specific diagram type, apply the matching preset below for shapes, colors, and layout conventions.
Architecture Diagram
Element
geo
color
Notes
Client (web/mobile)
rectangle
blue
Top row, label by client type
Service / module
rectangle
blue
Mid rows, group by tier
Database
ellipse
green
Bottom row, one per service
Cache
ellipse
yellow
Sits beside its owning service
Queue / event bus
hexagon
orange
Center of service row for hub pattern
Gateway / load balancer
triangle
violet
Above services
External API
cloud
red
Edge of canvas, dashed arrows in
Auth / security
rectangle
violet
Often near gateway
Layout: TB or LR by tier count; ≥4 tiers → TB. Hub nodes centered. Spacing scales with complexity (see table above).
Flowchart
Element
geo
color
Notes
Start / End
ellipse
green
Always at top and bottom
Process step
rectangle
blue
Default action box
Decision
diamond
yellow
Always label outgoing arrows (Yes / No)
I/O
rectangle (with dash: dashed)
orange
Distinguish from process via dashed border
Subprocess
rectangle
violet
Indicates a callable sub-flow
Layout: TB, ~200px vertical gap. Decisions branch left/right, then merge back to center. Always label decision branches in the arrow's props.text.
Sequence Diagram
tldraw doesn't have native lifeline shapes. Approximate with:
Element
geo
color
Notes
Actor / object header
rectangle
blue
Top of column
Lifeline
rectangle (w: 2, fill: solid, color: grey)
grey
Thin vertical line under each actor header
Sync message
arrow with arrowheadEnd: arrow
black
Solid horizontal arrow
Async message
arrow with dash: dashed
black
Dashed horizontal arrow
Return message
arrow with dash: dashed, color: grey
grey
Grey dashed
Layout: LR for actors (200–280px apart), TB for time. Each message is a horizontal arrow between two lifelines at increasing y.
ML / Deep Learning Model Diagram
For neural network architecture diagrams — useful for paper figures and explainers.
Element
geo
color
Notes
Input / Output
rectangle
green
Top and bottom of stack
Conv / Pooling
rectangle
blue
Standard layer block
Attention / Transformer
rectangle
violet
Distinct color for self-attention blocks
RNN / LSTM / GRU
rectangle
yellow
Recurrent layers
FC / Linear
rectangle
orange
Dense projection layers
Loss / Activation
rectangle
red
Final loss / softmax / activation
Skip connection
arrow with bend: 30, dash: dashed
grey
Curved dashed bypass
Tensor shape annotation: include the dimensions in props.text on a second line. tldraw renders \n literally inside JSON strings, so use a real newline (the JSON encoder will write \n):
"text": "Conv2D\n(B, 64, 32, 32)"
Layout: TB (data flows top → bottom), layers ~150px apart. Skip connections curve around the main stack.
ER Diagram (ERD)
tldraw lacks native table/row shapes. Approximate each entity as a tall rectangle with multi-line text.
Element
geo
color
Notes
Entity
rectangle (fill: solid, color: light-blue)
light-blue
Title + columns as one multi-line text label
Column list
embedded in props.text with \n between rows
—
Mark PK with * prefix, FK with >
Relationship
arrow with arrowheadStart: arrow, arrowheadEnd: arrow
black
Both ends arrowed for many-to-many
Optional / weak relationship
arrow with dash: dashed
grey
Dashed for optional FK
Label the arrow with cardinality (e.g., 1..*, 0..1) via props.text.
Layout: TB or grid; entities spaced ≥300px apart to leave room for column lists.
UML Class Diagram
Element
geo
color
Notes
Class
rectangle (fill: solid, color: light-blue)
light-blue
Title + attributes + methods as one multi-line text
Inheritance
arrow with arrowheadEnd: triangle
black
tldraw renders a filled triangle arrowhead — point it at the parent class
Composition
arrow with arrowheadStart: diamond, arrowheadEnd: none
black
tldraw renders a filled diamond head — put it on the owner (whole) end
Aggregation
arrow with arrowheadStart: diamond
black
Same diamond head; distinguish from composition via a label or note
Association
arrow with arrowheadEnd: arrow
black
Standard arrow
Note: tldraw's triangle/diamond arrowheads are filled, whereas strict UML uses hollow triangles (inheritance) and either filled/hollow diamonds (composition/aggregation). The shapes read correctly for sketches and explainers; for publication-grade UML with hollow heads, drawio-skill (separate skill) is a better fit.
