tldraw-skill

name tldraw-skill description 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. platforms ["macos","linux","windows"] metadata {"openclaw":{"requires":{"bins":"[Truncated]"},"emoji":"📝","os":["darwin","linux","win32"],"install":["[Truncated]"]},"hermes":{"tags":["tldraw","diagram","flowchart","architecture","whiteboard","visualization"],"category":"design","requires_tools":["tldraw"],"related_skills":["drawio","mermaid","excalidraw","plantuml"]},"author":"Agents365-ai","version":"1.2.1"} tldraw Whiteboard Diagrams Overview 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. Prerequisites # 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"). 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. Geo Shape Record { "id" : "shape:s1" , "typeName" : "shape" , "type" : "geo" , "parentId" : "page:page1" , "index" : "a1" , "x" : 100 , "y" : 100 , "rotation" : 0 , "isLocked" : false , "opacity" : 1 , "meta" : { } , "props" : { "w" : 180 , "h" : 60 , "geo" : "rectangle" , "color" : "blue" , "labelColor" : "black" , "fill" : "semi" , "dash" : "draw" , "size" : "m" , "font" : "draw" , "text" : "API Gateway" , "align" : "middle" , "verticalAlign" : "middle" , "growY" : 0 , "url" : "" } } Geo Types geo value Use for rectangle services, modules, components ellipse databases, start/end nodes oval pill-shaped start/end terminators (flowcharts) diamond decision points cloud external services, infrastructure hexagon event hubs, message buses triangle gateways, load balancers star highlights, key features pentagon stages, milestones octagon stop / terminal / blocking states trapezoid manual operations, transforms rhombus / rhombus-2 parallelograms — I/O steps (left/right slant) arrow-right / arrow-left / arrow-up / arrow-down directional flow blocks, data movement x-box failed / invalid / rejected states (box with ✕) check-box passed / validated / done states (box with ✓) heart accents (rarely needed for technical diagrams) All 20 geo values are valid; the above are the useful subset for technical diagrams. Color Palette color Use for blue clients, core services green success, databases, storage orange queues, event buses, warnings red external APIs, errors, alerts light-red soft alerts, secondary warnings violet gateways, security, auth yellow decisions, caches grey neutral, background, legacy light-blue secondary services, metadata light-violet soft auth/security, secondary gateways light-green soft success, secondary storage white blank/empty nodes, placeholders (pair with fill: solid ) black titles, emphasis Full palette (13): black , grey , light-violet , violet , blue , light-blue , yellow , orange , green , light-green , light-red , red , white . Style Options Property Values Notes fill semi , solid , none , pattern semi = tinted fill (recommended) dash draw , solid , dashed , dotted draw = hand-drawn default size s , m , l , xl m = default font draw , sans , serif , mono draw = default whiteboard style