tldraw-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

tldraw Whiteboard Diagrams

tldraw 白板图表

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.

通过

@kitschpatrol/tldraw-cli

生成现代白板风格的.tldr JSON格式图表，并导出为PNG/SVG。tldraw可生成具有简洁手绘风格的图表，拥有丰富的形状库和流畅的箭头路由，非常适合非正式或白板风格的可视化需求。

格式： .tldr JSON 导出格式： PNG、SVG（通过

@kitschpatrol/tldraw-cli

） 风格： 默认手绘白板风格；可通过

font

属性切换为简洁字体。

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.

明确触发条件： 用户提及“图表”“流程图”“绘制”“可视化”“白板图表”“tldraw图表”“架构图”“把这个画出来”等词汇。

主动触发条件：

解释包含3个及以上交互组件的系统
描述多步骤流程、数据流或管道
展示服务/模块之间的关系
架构概览、序列流、决策树、ML模型层级

跳过场景： 简单列表或表格即可满足需求时，用户需要专业商务演示风格图表（推荐使用drawio-skill），或用户处于快速问答流程中。

Prerequisites

前置要求

bash

undefined

bash

undefined

Install tldraw-cli

安装tldraw-cli

npm install -g @kitschpatrol/tldraw-cli

Verify

验证版本

tldraw --version


Works identically on macOS, Windows, and Linux — no extra setup required.

tldraw --version


在macOS、Windows和Linux系统上运行方式完全一致，无需额外配置。

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").

Update check (notify, don't pull) — first use per conversation. Throttle to once per 24 h via
```
<this-skill-dir>/.last_update
```
; never mutate the skill directory without explicit user consent.
- If
```
.last_update
```
  exists and is <24 h old, skip this step entirely.
- Otherwise, fetch the latest tag from upstream:
  bash
```
git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
  | awk '{print $2}' | sed 's|refs/tags/||' | sort -V | tail -1
```
- Compare with this skill's
```
metadata.version
```
  from the frontmatter. If the upstream tag is strictly newer (semver), tell the user one line and ask:
  "A newer version of this skill is available: vX.Y.Z → vA.B.C. Want me to
  git pull
  ?"
  If they say yes, run
```
git -C <this-skill-dir> pull --ff-only
```
  . Refresh
```
.last_update
```
  either way so the prompt doesn't repeat for 24 hours.
- If upstream is the same or older, refresh
```
.last_update
```
  silently and continue.
- On any failure (offline, not a git checkout — e.g. ClawHub-installed copy, read-only path, no permission), swallow the error silently and continue with the user's task. Do not mention the failure.

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).

开始前，评估用户的请求是否足够明确。如果缺少关键细节，可提出1-3个针对性问题：

图表类型 — 使用哪种预设？（架构图、流程图、序列图、ML/DL图、ERD、UML或通用类型）
输出格式 — PNG（默认）还是SVG？
输出位置 — 默认是用户的工作目录；若用户指定了路径（如“放到
```
./artifacts/
```
”）则遵循其要求。用户未提及则无需询问。
范围/精细度 — 包含多少组件？是否有特定技术或标签？

如果请求已明确包含这些细节或明显简单（如“绘制X的流程图”），则跳过澄清步骤。

版本更新检查（仅通知，不自动拉取） — 每次对话首次使用时执行。通过
```
<this-skill-dir>/.last_update
```
限制为24小时一次；未经用户明确同意，绝不修改技能目录。
- 若
```
.last_update
```
  存在且距今不足24小时，直接跳过此步骤。
- 否则，从上游获取最新版本标签：
  bash
```
git -C <this-skill-dir> ls-remote --tags origin 'v*' 2>/dev/null \
  | awk '{print $2}' | sed 's|refs/tags/||' | sort -V | tail -1
```
- 将其与技能前导内容中的
```
metadata.version
```
  对比。若上游版本更新（遵循语义化版本规则），告知用户并询问：
  "此技能有新版本可用：vX.Y.Z → vA.B.C。是否需要执行
  git pull
  更新？"
  若用户同意，执行
```
git -C <this-skill-dir> pull --ff-only
```
  。无论用户是否同意，都刷新
```
.last_update
```
  ，确保24小时内不再重复提示。
- 若上游版本相同或更旧，静默刷新
```
.last_update
```
  并继续。
- 若出现任何失败（离线、非git检出版本——如ClawHub安装的副本、只读路径、无权限），静默忽略错误并继续执行用户任务，不提及失败情况。
依赖检查 — 验证
```
tldraw --version
```
执行成功；若未安装，运行
```
npm install -g @kitschpatrol/tldraw-cli
```
。
规划 — 确定形状（每个节点对应的几何类型）、连接（带源/目标的箭头）和布局（上下或左右方向，按层级/角色分组）。编写JSON前先构思坐标网格。
生成文件 — 编写.tldr JSON文件。默认输出目录为用户工作目录；若用户指定了路径或目录（如
```
./artifacts/
```
），先执行
```
mkdir -p
```
创建目录，再写入文件。步骤4和7中的PNG/SVG导出也使用相同目录。
导出草稿 — 运行CLI生成PNG预览图。
自我检查 — 使用Agent内置的视觉功能读取导出的PNG，发现明显问题后自动修复再展示给用户（需要支持视觉的模型，如Claude Sonnet/Opus）。若不支持视觉功能，跳过此步骤。
反馈循环 — 向用户展示图片，收集反馈，针对性修改JSON，重新导出，重复此过程直至用户认可。
最终导出 — 将认可的版本导出为所有请求的格式；告知用户.tldr源文件和导出图片的文件路径。

Step 5: Self-Check

步骤5：自我检查

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:

Check	What to look for	Auto-fix action
Overlapping shapes	Two or more shapes stacked on top of each other	Shift shapes apart by ≥200px
Clipped labels	Text cut off at shape boundaries	Increase shape `w` / `h` to fit label
Missing arrows	Arrows that don't visually connect to shapes	Verify `boundShapeId` matches an existing shape's id
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.

导出草稿PNG后，使用Agent的视觉功能（如Claude的图片输入）读取图片，在展示给用户前检查以下问题。若Agent不支持视觉功能，跳过自我检查直接展示PNG：

检查项	检查内容	自动修复操作
形状重叠	两个或多个形状堆叠在一起	将形状错开至少200px
标签截断	文本被形状边界截断	增大形状的 `w` / `h` 以容纳标签
箭头缺失	箭头未与形状视觉连接	验证 `boundShapeId` 是否匹配现有形状的id
形状超出画布	形状位于负坐标或远离主群组	将形状移至主群组附近的正坐标区域
箭头与形状重叠	箭头穿过无关形状	调整 `bend` 值或将端点移至不同的 `normalizedAnchor` 侧边
箭头堆叠	多个箭头在同一路径上重叠	在形状周边分配不同的 `normalizedAnchor` （使用不同的x/y值）

最多执行2轮自我检查 — 若2次修复后仍有问题，直接展示给用户。
每次修复后重新导出并读取新的PNG。

Step 6: Review Loop

步骤6：反馈循环

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.

自我检查完成后，向用户展示导出的图片并请求反馈。

针对性修改规则 — 根据反馈类型，进行最小化的JSON修改：

用户请求	JSON修改操作
修改X的颜色	通过 `props.text` 匹配X对应的形状，更新 `props.color`
添加新节点	添加新的形状记录，使用下一个可用索引，放置在相关节点附近
删除节点	删除形状记录以及所有绑定到该节点的箭头记录
移动形状X	更新形状的 `x` / `y` 字段
调整形状X大小	更新 `props.w` / `props.h`
添加从A到B的箭头	添加新的箭头记录，绑定到A和B的形状id
修改标签文本	更新匹配形状或箭头的 `props.text`
修改布局方向	完全重新生成 — 重新规划网格并重建JSON

规则：

单元素修改：直接编辑现有JSON — 保留之前迭代的布局调整。
全局布局修改（如切换上下/左右方向、“重新开始”）：重新生成完整JSON。
每次迭代覆盖同一个
```
{name}.png
```
文件 — 不创建
```
v1
```
、
```
v2
```
、
```
v3
```
等版本文件。
修改后重新导出并展示更新后的图片。
循环持续到用户表示认可/完成/LGTM。
安全机制： 经过5轮迭代后，建议用户在tldraw.com或桌面应用中打开.tldr文件进行精细调整。

File Format

文件格式

Complete .tldr Skeleton

完整.tldr骨架

json

{
  "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 MUST start with
```
"a"
```
followed by digits or uppercase letters:
```
"a1"
```
,
```
"a2"
```
, ...,
```
"a9"
```
,
```
"aA"
```
,
```
"aB"
```
, ...,
```
"aZ"
```
,
```
"a10"
```
, etc.
Never use
"b1"
,
"c1"
etc. as indices — only
```
"a*"
```
format is valid for shapes.

json

{
  "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": {}}
    /* 形状和箭头放在这里 */
  ]
}

关键规则：

```
document:document
```
和
```
page:page1
```
记录是必须的。
所有形状都放在页面记录之后的
```
records
```
数组中。
所有形状的
```
"parentId": "page:page1"
```
。
形状ID使用
```
"shape:xxx"
```
格式，后缀唯一（如
```
"shape:s1"
```
、
```
"shape:a1"
```
）。
```
index
```
值必须以
```
"a"
```
开头，后跟数字或大写字母：
```
"a1"
```
、
```
"a2"
```
……
```
"a9"
```
、
```
"aA"
```
、
```
"aB"
```
……
```
"aZ"
```
、
```
"a10"
```
等。
绝不能使用
"b1"
、
"c1"
等作为索引 — 只有
```
"a*"
```
格式对形状有效。

Geo Shape Record

几何形状记录

json

{
  "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": ""
  }
}

json

{
  "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
`diamond`	decision points
`cloud`	external services, infrastructure
`hexagon`	event hubs, message buses
`triangle`	gateways, load balancers
`star`	highlights, key features

`geo` 值	用途
`rectangle`	服务、模块、组件
`ellipse`	数据库、开始/结束节点
`diamond`	决策点
`cloud`	外部服务、基础设施
`hexagon`	事件中心、消息总线
`triangle`	网关、负载均衡器
`star`	高亮、关键特性

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
`black`	titles, emphasis

`color` 值	用途
`blue`	客户端、核心服务
`green`	成功状态、数据库、存储
`orange`	队列、事件总线、警告
`red`	外部API、错误、警报
`light-red`	轻度警报、次要警告
`violet`	网关、安全、认证
`yellow`	决策、缓存
`grey`	中性、背景、遗留系统
`light-blue`	次要服务、元数据
`black`	标题、强调内容

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

属性	可选值	说明
`fill`	`semi` 、 `solid` 、 `none` 、 `pattern`	`semi` = 半透明填充（推荐）
`dash`	`draw` 、 `solid` 、 `dashed` 、 `dotted`	`draw` = 默认手绘风格
`size`	`s` 、 `m` 、 `l` 、 `xl`	`m` = 默认大小
`font`	`draw` 、 `sans` 、 `serif` 、 `mono`	`draw` = 默认白板风格字体

Arrow Record

箭头记录

json

{
  "id": "shape:a1",
  "typeName": "shape",
  "type": "arrow",
  "parentId": "page:page1",
  "index": "aG",
  "x": 0,
  "y": 0,
  "rotation": 0,
  "isLocked": false,
  "opacity": 1,
  "meta": {},
  "props": {
    "dash": "draw",
    "size": "m",
    "fill": "none",
    "color": "black",
    "labelColor": "black",
    "bend": 0,
    "start": {
      "type": "binding",
      "boundShapeId": "shape:s1",
      "normalizedAnchor": {"x": 0.5, "y": 1},
      "isExact": false
    },
    "end": {
      "type": "binding",
      "boundShapeId": "shape:s2",
      "normalizedAnchor": {"x": 0.5, "y": 0},
      "isExact": false
    },
    "arrowheadStart": "none",
    "arrowheadEnd": "arrow",
    "text": "",
    "font": "draw"
  }
}

json

{
  "id": "shape:a1",
  "typeName": "shape",
  "type": "arrow",
  "parentId": "page:page1",
  "index": "aG",
  "x": 0,
  "y": 0,
  "rotation": 0,
  "isLocked": false,
  "opacity": 1,
  "meta": {},
  "props": {
    "dash": "draw",
    "size": "m",
    "fill": "none",
    "color": "black",
    "labelColor": "black",
    "bend": 0,
    "start": {
      "type": "binding",
      "boundShapeId": "shape:s1",
      "normalizedAnchor": {"x": 0.5, "y": 1},
      "isExact": false
    },
    "end": {
      "type": "binding",
      "boundShapeId": "shape:s2",
      "normalizedAnchor": {"x": 0.5, "y": 0},
      "isExact": false
    },
    "arrowheadStart": "none",
    "arrowheadEnd": "arrow",
    "text": "",
    "font": "draw"
  }
}

Arrow Connection Rules

箭头连接规则

Arrow record
```
x
```
and
```
y
```
are always
```
0, 0
```
.
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"
```
.

箭头记录的
```
x
```
和
```
y
```
始终为
```
0, 0
```
。
使用
```
"type": "binding"
```
和
```
boundShapeId
```
连接到特定形状。
```
normalizedAnchor
```
指定箭头连接到目标形状的位置（范围0–1）：
- ```
{x: 0.5, y: 0}
```
  = 顶部中心
- ```
{x: 0.5, y: 1}
```
  = 底部中心
- ```
{x: 0, y: 0.5}
```
  = 左侧中心
- ```
{x: 1, y: 0.5}
```
  = 右侧中心
- ```
{x: 0.5, y: 0.5}
```
  = 中心
在箭头属性中添加
```
"text": "label"
```
可为连接添加标签。
使用
```
"bend": 20
```
（或
```
-20
```
）实现轻微弯曲，避免与其他箭头重叠。
对于虚线/点线箭头（如异步流、可选链接），设置
```
"dash": "dashed"
```
或
```
"dotted"
```
。

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).

当多个箭头连接到同一个形状时，分配不同的

normalizedAnchor

点以避免堆叠：

位置	x	y	适用场景
顶部中心	0.5	0	连接上方节点
左上角	0.25	0	顶部第2个连接
右上角	0.75	0	顶部第3个连接
右侧中心	1	0.5	连接右侧节点
底部中心	0.5	1	连接下方节点
左侧中心	0	0.5	连接左侧节点

规则： 若形状某一侧有N个连接，均匀分布（如底部有3个连接 → x = 0.25, 0.5, 0.75）。

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

Geo shapes first:
```
a1
```
through
```
aF
```
(or as many as needed).
Arrow shapes after:
```
aG
```
,
```
aH
```
, etc.
Every shape must have a unique index.

索引控制层级顺序（堆叠）。使用以下序列：

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

几何形状优先：
```
a1
```
到
```
aF
```
（按需增加）。
箭头形状在后：
```
aG
```
、
```
aH
```
等。
每个形状必须有唯一的索引。

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

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

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.

间距 — 随复杂度调整：

图表复杂度	节点数量	水平间距	垂直间距
简单	≤5	200px	150px
中等	6–10	280px	200px
复杂	>10	350px	250px

路由通道： 在形状行/列之间，预留约80px的空白通道供箭头路由，避免穿过其他形状。绝不要在箭头需要经过的间隙放置形状。

网格对齐： 将所有

、

值对齐到10的倍数 — 这与tldraw默认的

gridSize: 10

匹配，便于手动编辑。

通用规则：

分配x/y坐标前先规划网格 — 先在脑海中勾勒节点位置。
将相关节点分组到同一水平或垂直区域。
将连接密集的“枢纽”节点放在中心位置，使箭头向外辐射而非交叉。
对于宽形状（如覆盖多个下游服务的API网关），设置
```
w
```
以覆盖整个跨度。
子节点与父节点居中对齐（x中心相同），避免对角线路由。
事件总线模式：将总线（六边形）放在服务行的中心，而非下方 — 两侧的服务通过短水平箭头连接（左侧
```
normalizedAnchor.x = 1
```
，右侧
```
0
```
），消除交叉。
水平连接绝不穿过同一行的垂直节点；用于对等连接和发布连接。

避免箭头与形状重叠：

确定坐标前，先在脑海中追踪每条箭头路径 — 若必须穿过无关形状，要么移动形状，要么使用
```
bend
```
绕开。
树形/层级布局：将节点分配到不同层（行），仅在相邻层之间连接，以最小化交叉。
星形/枢纽布局：将枢纽放在中心，卫星节点环绕 — 箭头短且呈放射状。

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).

元素	`geo` 类型	`color` 颜色	说明
客户端（Web/移动端）	`rectangle`	`blue`	顶部行，按客户端类型标注
服务/模块	`rectangle`	`blue`	中间行，按层级分组
数据库	`ellipse`	`green`	底部行，每个服务对应一个
缓存	`ellipse`	`yellow`	位于所属服务旁边
队列/事件总线	`hexagon`	`orange`	枢纽模式下放在服务行中心
网关/负载均衡器	`triangle`	`violet`	位于服务上方
外部API	`cloud`	`red`	画布边缘，使用虚线箭头连接
认证/安全	`rectangle`	`violet`	通常靠近网关

布局： 根据层级数量选择上下（TB）或左右（LR）方向；≥4层 → 上下方向。枢纽节点居中。间距随复杂度调整（见上表）。

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

元素	`geo` 类型	`color` 颜色	说明
开始/结束	`ellipse`	`green`	始终位于顶部和底部
流程步骤	`rectangle`	`blue`	默认操作框
决策	`diamond`	`yellow`	必须标注 outgoing 箭头（是/否）
输入/输出	`rectangle` （设置 `dash: dashed` ）	`orange`	通过虚线边框与流程区分
子流程	`rectangle`	`violet`	表示可调用的子流程

布局： 上下方向，垂直间距约200px。决策分支向左/右，然后合并回中心。必须在箭头的

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

tldraw没有原生生命线形状，可通过以下方式模拟：

元素	`geo` 类型	`color` 颜色	说明
参与者/对象标题	`rectangle`	`blue`	列顶部
生命线	`rectangle` （ `w: 2` 、 `fill: solid` 、 `color: grey` ）	`grey`	每个参与者标题下方的细垂直线
同步消息	箭头设置 `arrowheadEnd: arrow`	`black`	实心水平箭头
异步消息	箭头设置 `dash: dashed`	`black`	虚线水平箭头
返回消息	箭头设置 `dash: dashed` 、 `color: grey`	`grey`	灰色虚线箭头

布局： 参与者左右排列（间距200–280px），时间上下推进。每条消息是两个生命线之间的水平箭头，

值递增。

ML / Deep Learning Model Diagram

ML/深度学习模型图

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.

用于神经网络架构图 — 适用于论文插图和讲解。

元素	`geo` 类型	`color` 颜色	说明
输入/输出	`rectangle`	`green`	堆叠的顶部和底部
卷积/池化层	`rectangle`	`blue`	标准层块
注意力/Transformer层	`rectangle`	`violet`	自注意力块使用独特颜色
RNN/LSTM/GRU层	`rectangle`	`yellow`	循环层
全连接/线性层	`rectangle`	`orange`	密集投影层
损失/激活层	`rectangle`	`red`	最终损失/softmax/激活层
跳跃连接	箭头设置 `bend: 30` 、 `dash: dashed`	`grey`	弯曲虚线旁路

张量形状标注： 在

props.text

的第二行包含维度信息。tldraw会在JSON字符串中按字面量渲染

\n

，因此使用真实换行（JSON编码器会写入

\n

）：

"text": "Conv2D\n(B, 64, 32, 32)"

布局： 上下方向（数据从上到下流动），层间距约150px。跳跃连接绕主堆叠弯曲。

ER Diagram (ERD)

ER图（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.

tldraw没有原生表格/行形状，可将每个实体近似为带多行文本的高矩形。

元素	`geo` 类型	`color` 颜色	说明
实体	`rectangle` （ `fill: solid` 、 `color: light-blue` ）	`light-blue`	标题+列作为单个多行文本标签
列列表	嵌入在 `props.text` 中，行之间用 `\n` 分隔	—	主键前缀 `*` ，外键前缀 `>`
关系	箭头设置 `arrowheadStart: arrow` 、 `arrowheadEnd: arrow`	`black`	多对多关系两端都带箭头
可选/弱关系	箭头设置 `dash: dashed`	`grey`	虚线表示可选外键

通过箭头的

props.text

标注基数（如

1..*

、

0..1

）。

布局： 上下或网格布局；实体间距≥300px，为列列表留出空间。

UML Class Diagram

UML类图

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` (open)	`black`	Use a single arrow shape; tldraw doesn't natively render hollow triangles, so suggest user open in editor for true UML notation if needed
Composition	arrow with `bend: 0` , label `◆` in `text`	`black`	Add diamond glyph in arrow text as a workaround
Association	arrow with `arrowheadEnd: arrow`	`black`	Standard arrow

Note: tldraw's arrowheads are limited compared to UML — for strict UML class diagrams, drawio-skill (separate skill) is a better fit. Use this preset for sketches and high-level explainers.

Layout: TB, classes ~250px apart, interfaces above implementations.

元素	`geo` 类型	`color` 颜色	说明
类	`rectangle` （ `fill: solid` 、 `color: light-blue` ）	`light-blue`	标题+属性+方法作为单个多行 `text`
继承	箭头设置 `arrowheadEnd: triangle` （空心）	`black`	使用单个箭头形状；tldraw不原生支持空心三角形，若需要严格UML符号，建议用户在编辑器中打开修改
组合	箭头设置 `bend: 0` ， `text` 中添加 `◆`	`black`	在箭头文本中添加菱形符号作为替代方案
关联	箭头设置 `arrowheadEnd: arrow`	`black`	标准箭头

注意： tldraw的箭头样式相比UML有限 — 若需要严格的UML类图，drawio-skill（独立技能）更合适。此预设适用于草图和高层讲解。

布局： 上下方向，类间距约250px，接口位于实现上方。

Export Commands

导出命令

bash

undefined

bash

undefined

Check CLI version

检查CLI版本

tldraw --version

PNG at 2x scale (recommended) — outputs diagram.png in ./

2倍缩放PNG（推荐） — 在当前目录输出diagram.png

tldraw export diagram.tldr -f png --scale 2 -o ./

SVG — outputs diagram.svg in ./

SVG格式 — 在当前目录输出diagram.svg

tldraw export diagram.tldr -f svg -o ./

Transparent background

透明背景

tldraw export diagram.tldr -f png --scale 2 --transparent -o ./

Dark theme

深色主题

tldraw export diagram.tldr -f png --scale 2 --dark -o ./

Custom output directory (e.g. CI artifacts dir) — create if missing, then export there

自定义输出目录（如CI artifacts目录） — 先创建目录（若不存在），再导出

mkdir -p ./artifacts && tldraw export diagram.tldr -f png --scale 2 -o ./artifacts/


**Note:** `-o` is an output **directory**, not a file path. The output file is named after the input file (`diagram.tldr` → `diagram.png`).

mkdir -p ./artifacts && tldraw export diagram.tldr -f png --scale 2 -o ./artifacts/


**注意：** `-o`指定的是输出**目录**，而非文件路径。输出文件名与输入文件名一致（`diagram.tldr` → `diagram.png`）。

Auto-launch after export

导出后自动打开

Offer to open the

.tldr

file in the user's default tldraw viewer/editor:

OS	Command
macOS	`open diagram.tldr`
Linux	`xdg-open diagram.tldr`
Windows	`start diagram.tldr`

Or upload to https://tldraw.com (drag-and-drop the

.tldr

file) for browser editing.

可提议在用户默认的tldraw查看器/编辑器中打开.tldr文件：

操作系统	命令
macOS	`open diagram.tldr`
Linux	`xdg-open diagram.tldr`
Windows	`start diagram.tldr`

也可上传到https://tldraw.com（拖放.tldr文件）进行浏览器端编辑。

Common Mistakes

常见错误

Mistake	Fix
`tldraw` command not found	Run `npm install -g @kitschpatrol/tldraw-cli`
`invalidRecords` on export	Check: index values must start with `a` (e.g., `a1` , `aA` ) — never `b1` , `c1`
Blank/empty export	Verify `document:document` and `page:page1` records are present
Output file not found	`-o` is a directory; file name matches input: `tldraw export foo.tldr -o ./` → `./foo.png`
Arrow doesn't appear	Use `"type": "binding"` with `boundShapeId` ; set arrow `x` / `y` to `0,0`
Shapes overlap	Plan a 200px+ grid before assigning x/y; scale spacing with complexity
Text not visible	Check `props.text` is set; if `fill: "none"` , ensure text color contrasts
Index collision	All shapes must have unique `index` values
Shape ID clash	Use unique IDs: `"shape:s1"` , `"shape:s2"` , `"shape:a1"` , etc.
Export fails	Ensure the `.tldr` file is valid JSON: `python3 -m json.tool file.tldr > /dev/null`
Multi-line label	Use a real newline character inside the JSON string ( `"text": "Line1\nLine2"` ); tldraw respects `\n`
Arrow crosses shape	Use `bend` to curve around, or move endpoint to a different `normalizedAnchor`
Iteration loop never ends	After 5 rounds, suggest the user open `.tldr` in tldraw.com for fine-tuning

错误	修复方法
`tldraw` 命令未找到	运行 `npm install -g @kitschpatrol/tldraw-cli`
导出时出现 `invalidRecords`	检查：索引值必须以 `a` 开头（如 `a1` 、 `aA` ） — 绝不能是 `b1` 、 `c1`
导出空白/空文件	确认 `document:document` 和 `page:page1` 记录存在
找不到输出文件	`-o` 是目录；文件名与输入文件一致： `tldraw export foo.tldr -o ./` → `./foo.png`
箭头不显示	使用 `"type": "binding"` 和 `boundShapeId` ；将箭头的 `x` / `y` 设置为 `0,0`
形状重叠	分配x/y前规划200px+的网格；随复杂度调整间距
文本不可见	检查 `props.text` 是否设置；若 `fill: "none"` ，确保文本颜色与背景对比明显
索引冲突	所有形状必须有唯一的 `index` 值
形状ID冲突	使用唯一ID： `"shape:s1"` 、 `"shape:s2"` 、 `"shape:a1"` 等
导出失败	确保.tldr文件是有效的JSON： `python3 -m json.tool file.tldr > /dev/null`
多行标签	在JSON字符串中使用真实换行符（ `"text": "Line1\nLine2"` ）；tldraw支持 `\n`
箭头穿过形状	使用 `bend` 绕开，或将端点移至不同的 `normalizedAnchor`
迭代循环无法结束	5轮迭代后，建议用户在tldraw.com中打开.tldr文件进行精细调整

Fallback Chain

降级方案

When tools are unavailable, degrade gracefully:

Scenario	Behavior
`tldraw-cli` missing	Generate `.tldr` JSON only; instruct user to drag-and-drop into https://tldraw.com or install the CLI
Vision unavailable for self-check	Skip self-check (step 5); proceed directly to showing user the exported PNG
Export fails	Validate JSON with `python3 -m json.tool` ; deliver the `.tldr` file and suggest opening in tldraw.com

当工具不可用时，优雅降级：

场景	行为
`tldraw-cli` 缺失	仅生成.tldr JSON文件；指导用户拖放到https://tldraw.com或安装CLI
自我检查无视觉功能支持	跳过自我检查（步骤5）；直接向用户展示导出的PNG
导出失败	使用 `python3 -m json.tool` 验证JSON；交付.tldr文件并建议在tldraw.com中打开