excalidraw-diagram

Excalidraw 图表创建器

生成 .excalidraw JSON 文件，以视觉方式进行论证，而不只是展示信息。

**设置：**如果用户要求你设置此技能（渲染器、依赖项等），请参阅 README.md 中的说明。

自定义

所有颜色和品牌专属样式都集中在一个文件中：references/color-palette.md。生成任何图表前都要先阅读该文件，并将其作为所有颜色选择的唯一依据——包括形状填充色、描边色、文本颜色、证据素材背景色等。

要让此技能生成符合你自有品牌风格的图表，请编辑 color-palette.md。本文件中的其他内容都是通用的设计方法和 Excalidraw 最佳实践。

---

核心理念

图表应该进行论证，而不是展示。

图表不是经过排版的文本，而是一种视觉论证，能展示文字本身无法表达的关系、因果和流程。形状本身就应该传达含义。

同构测试：如果去掉所有文字，结构本身还能传达这个概念吗？如果不能，就重新设计。

教育测试：有人能从这张图表中学到具体知识吗，还是它只是在给方框贴标签？好的图表能教会人们东西——它会展示真实格式、实际事件名称和具体示例。

---

深度评估（首先执行）

开始设计前，先确定这张图表需要达到的详细程度：

简单／概念图表

在以下情况下使用抽象形状：

• 解释思维模型或理念
• 受众不需要了解技术细节
• 概念本身就是抽象内容（例如，“关注点分离”）

全面／技术图表

在以下情况下使用具体示例：

• 绘制真实系统、协议或架构的图表
• 图表将用于教学或讲解（例如，YouTube 视频）
• 受众需要了解实际内容
• 展示多种技术如何集成

对于技术图表，必须包含证据素材（见下文）。

---

研究要求（适用于技术图表）

绘制任何技术内容前，都要研究实际规范。

如果你要绘制协议、API 或框架的图表：

1. 查找实际的 JSON／数据格式
2. 找到真实的事件名称、方法名称或 API 端点
3. 了解各部分的实际连接方式
4. 使用真实术语，而不是通用占位符

不佳：“协议” → “前端”
良好：“AG-UI 流式传输事件（RUN_STARTED、STATE_DELTA、A2UI_UPDATE）” → “CopilotKit 通过 createA2UIMessageRenderer() 渲染”

研究能让图表既准确又有教育意义。

---

证据示例

证据示例是能够证明图表准确性并帮助读者理解的具体示例。请在技术图表中加入这些示例。

证据示例的类型（根据图表内容选择相关类型）：

示例类型	适用场景	呈现方式
代码片段	API、集成、实现细节	深色矩形 + 语法高亮文本（证据示例颜色请参见调色板）
数据/JSON 示例	数据格式、架构、负载	深色矩形 + 彩色文本（请参见调色板）
事件/步骤序列	协议、工作流、生命周期	时间线模式（线条 + 圆点 + 标签）
UI 模拟图	展示实际输出/结果	使用嵌套矩形模拟真实 UI
实际输入内容	展示输入系统的内容	使用矩形显示示例内容
API/方法名称	实际函数调用、端点	使用文档中的真实名称，而不是占位符

示例：对于流式协议图表，你可以展示：

• 规范中的实际事件名称（而不只是“事件 1”“事件 2”）
• 展示如何连接的代码片段
• 流式数据的实际形式

示例：对于数据转换流水线图表：

• 展示示例输入数据（实际格式，而不只是“输入”）
• 展示示例输出数据（实际格式，而不只是“输出”）
• 如有相关内容，展示中间状态

核心原则：展示事物的实际样子，而不只是它们的名称。

---

多层级缩放架构

全面的图表会同时呈现多个缩放层级。可以把它想象成一张既展示国界又标注街道名称的地图。

层级 1：概览流程

简化概览，一目了然地展示完整流水线或流程。通常放在图表顶部或底部。

示例：输入 → 处理 → 输出 或 客户端 → 服务端 → 数据库

层级 2：分区边界

将相关组件归为一组并标注名称的区域。这些区域形成视觉上的“房间”，帮助读者理解哪些内容属于一组。

示例：按职责分组（后端 / 前端）、按阶段分组（设置 / 执行 / 清理）或按团队分组（用户 / 系统 / 外部）

层级 3：分区内的细节

每个分区内的证据示例、代码片段和具体示例。这里是图表发挥教学价值的地方。

示例：在“后端”分区中，展示实际的 API 响应格式，而不只是一个标有“API 响应”的框。

**全面的图表应力求包含全部三个层级。**概览提供背景，分区梳理内容，细节帮助学习。

不佳与优秀

不佳（展示）	优秀（论证）
5 个带标签的等大方框	每个概念都使用与其行为相呼应的形状
卡片网格布局	视觉结构与概念结构相匹配
装饰文字的图标	形状本身就是含义
所有内容都使用相同的容器	针对不同概念使用各自独特的视觉元素
所有内容都放在方框里	仅在需要时使用容器，其余文字自由排布

简单图示与详尽图示（明确你需要哪一种）

简单图示	详尽图示
通用标签：“输入” → “处理” → “输出”	具体展示输入／输出的实际样貌
带名称的方框：“API”“数据库”“客户端”	带名称的方框 + 实际请求／响应示例
“事件”或“消息”标签	使用规范中的真实事件／消息名称的时间线
“UI”或“仪表盘”矩形框	展示实际 UI 元素和内容的模型图
约 30 秒即可讲解	约 2–3 分钟的教学内容
读者了解结构	读者了解结构和细节

简单图示适用于抽象概念、快速概览，或受众已经了解细节的情况。详尽图示适用于技术架构、教程、教育内容，或希望图示本身起到教学作用的情况。

---

容器与自由浮动文本

并非每段文字都需要放进形状框中。 默认使用自由浮动文本。只有在容器有实际作用时，才添加容器。

适合使用容器的情况……	适合使用自由浮动文本的情况……
它是某个部分的焦点	它是标签或描述
它需要与其他元素在视觉上分组	它是辅助细节或元数据
箭头需要与它相连	它描述附近的内容
形状本身承载含义（如决策菱形等）	仅靠字体排版就能形成足够的层级
它代表系统中的一个独立“事物”	它是章节标题、副标题或注释

通过字体排版建立层级：使用字号、字重和颜色来建立视觉层级，无需方框。28px 的标题不需要外面再套一个矩形框。

容器测试：对于每个带框的元素，问问自己：“改成自由浮动文本也行吗？”如果可以，就移除容器。

---

设计流程（在生成 JSON 之前执行）

步骤 0：评估所需深度

首先，确定内容应采用哪种形式：

• 简单／概念性：抽象形状、标签、关系（心智模型、理念）
• 详尽／技术性：具体示例、代码片段、真实数据（系统、架构、教程）

如果需要详尽内容：先做研究。查找实际规范、格式、事件名称和 API。

步骤 1：深入理解

阅读内容。针对每个概念，思考：

• 这个概念会做什么？（而不是它是什么）
• 概念之间有哪些关系？
• 核心转换或流程是什么？
• 要理解这一点，读者需要看到什么？（而不只是读到相关说明）

步骤 2：将概念映射到模式

针对每个概念，寻找能体现其行为的视觉模式：

如果概念……	使用这种模式
产生多个输出	扇出（从中心向外辐射的箭头）
将多个输入合并为一个	汇聚（漏斗、合并的箭头）
具有层级／嵌套结构	树形结构（线条 + 自由浮动文本）
是一系列步骤	时间线（线条 + 圆点 + 自由浮动标签）
持续循环或改进	螺旋／循环（箭头返回起点）
是抽象状态或上下文	云形（重叠的椭圆）
将输入转换为输出	流水线（之前 → 处理 → 之后）
比较两件事	并排展示（平行排列并体现对比）
分为不同阶段	间隔／断开（各部分之间用视觉间隔区分）

步骤 3：确保多样性

对于包含多个概念的图示：每个主要概念都必须使用不同的视觉模式。不要使用样式统一的卡片或网格。

步骤 4：勾勒流程

生成 JSON 之前，先在脑海中追踪视线如何在图示中移动。图示应呈现清晰的视觉叙事。

步骤 5：生成 JSON

现在才创建 Excalidraw 元素。大型图示的处理方式见下文。

第 6 步：渲染与验证（强制）

生成 JSON 后，必须反复执行渲染、查看和修复流程，直到图示效果理想为止。这不是可选步骤——完整流程请参阅下方的 渲染与验证 部分。

---

大型／综合图示策略

**对于综合性或技术性图示，必须一次构建 JSON 的一个部分。**不要试图一次性生成整个文件。这是硬性要求——Claude Code 每次响应的输出限制约为 32,000 个 token，而综合性图示很容易一次就超出限制。即使没有超出，一次性生成所有内容也会导致质量下降。分部分构建在各方面都更好。

分部分工作流程

阶段 1：构建各个部分

1. 创建基础文件，包含 JSON 封装（type、version、appState、files）以及第一部分元素。
2. **每次编辑添加一个部分。**每个部分都要单独进行专门处理——仔细考虑布局、间距，以及此部分如何与已有内容衔接。
3. 使用描述性字符串 ID（例如 "trigger_rect"、"arrow_fan_left"），以便清晰地查看跨部分引用。
4. 按部分划分种子编号命名空间（例如，部分 1 使用 100xxx，部分 2 使用 200xxx），以避免冲突。
5. **随时更新跨部分绑定。**当新部分中的元素需要绑定到前面部分的元素时（例如，连接不同部分的箭头），同时编辑前面元素的 boundElements 数组。

阶段 2：整体审查

所有部分就位后，通读完整 JSON 并检查：

• 跨部分箭头两端的绑定是否正确？
• 整体间距是否平衡，还是有些部分过于拥挤，而其他部分留白过多？
• ID 和绑定引用的元素是否都确实存在？

渲染之前修复所有对齐或绑定问题。

阶段 3：渲染与验证

现在按照「渲染与验证」部分的说明，执行渲染、查看和修复流程。此时可以发现 JSON 中不明显的视觉问题——重叠、裁切、构图失衡。

部分边界

根据图示规划中的自然视觉分组来规划各个部分。大型图示通常可以拆分为：

• 部分 1：入口点／触发器
• 部分 2：第一个决策或路由
• 部分 3：主要内容（核心部分，可能是最大的单个部分）
• 部分 4-N：剩余阶段、输出等

每个部分都应能独立理解：包括其元素、内部箭头，以及与相邻部分的任何交叉引用。

不要这样做

• **不要在一次响应中生成整个图示。**这会触及输出 token 限制，并生成被截断、无法使用的 JSON。即使图示足够小，可以一次生成完，分部分处理也能带来更好的效果。
• 不要使用编码 Agent来生成 JSON。该 Agent 不会充分了解技能规则，而且协调开销会抵消任何收益。
• **不要编写 Python 生成脚本。**模板和坐标计算看似有用，但会增加一层间接性，让调试更困难。手工编写带有描述性 ID 的 JSON 更易于维护。

---

视觉模式库

扇出（一对多）

中心元素通过箭头向多个目标辐射。适用于：来源、PRD、根本原因、中心枢纽。

        ○
       ↗
  □ → ○
       ↘
        ○

汇聚（多对一）

多个输入通过箭头汇聚到单一输出。适用于：聚合、漏斗、综合。

  ○ ↘
  ○ → □
  ○ ↗

树（层级结构）

父子分支通过连线连接，并配以悬浮文本（无需方框）。适用于：文件系统、组织结构图、分类体系。

  label
  ├── label
  │   ├── label
  │   └── label
  └── label

主干和分支使用 line 元素，标签使用悬浮文本。

螺旋／循环（持续循环）

元素按顺序排列，并通过箭头返回起点。适用于：反馈循环、迭代过程、演进。

  □ → □
  ↑     ↓
  □ ← □

云（抽象状态）

使用大小各异、彼此重叠的椭圆。适用于：上下文、记忆、对话、心理状态。

流水线（转换）

输入 → 处理框 → 输出，清晰呈现前后变化。适用于：转换、处理、格式转换。

  ○○○ → [PROCESS] → □□□
  chaos              order

并排展示（比较）

两个并列结构，形成视觉对比。适用于：前后对比、选项、权衡。

间隔／断点（分隔）

在各部分之间留出空白或设置屏障。适用于：阶段变化、上下文重置、边界。

用线条构建结构

将线条（类型：line，而非箭头）作为主要结构元素，而不是使用方框：

• 时间线：垂直或水平线条，间隔设置小圆点（10-20px 的椭圆），在每个圆点旁放置自由浮动的标签
• 树形结构：垂直主干线 + 水平分支线，搭配自由浮动的文本标签（无需方框）
• 分隔线：使用细虚线分隔各部分
• 流程主线：使用一条中心线，让各元素与其关联，而非用线连接方框

Timeline:           Tree:
  ●─── Label 1        │
  │                   ├── item
  ●─── Label 2        │   ├── sub
  │                   │   └── sub
  ●─── Label 3        └── item

线条 + 自由浮动的文本通常比方框 + 框内文本更简洁。

---

形状的含义

根据形状所代表的内容来选择形状，也可以完全不使用形状：

概念类型	形状	原因
标签、描述、详情	无（自由浮动文本）	通过排版建立层级
章节标题、注释	无（自由浮动文本）	字号／字重足以建立层级
时间线上的标记	小型 ellipse（10-20px）	作为视觉锚点，而非容器
起点、触发器、输入	ellipse	柔和，类似起点
终点、输出、结果	ellipse	表示完成与目的地
决策、条件	diamond	经典的决策符号
流程、操作、步骤	rectangle	包含具体操作
抽象状态、上下文	重叠的 ellipse	模糊、类似云状
层级节点	线条 + 文本（无方框）	通过线条呈现结构

规则：默认不使用容器。只有在形状能承载含义时才添加。尽量让位于容器内的文本元素少于 30%。

---

用颜色表达含义

颜色用于编码信息，而非装饰。每种颜色都应选自 references/color-palette.md——其中定义了语义形状颜色、文本层级颜色和证据材料颜色。

核心原则：

• 每种语义用途（起点、终点、决策、AI、错误等）都有指定的填充色／描边色组合
• 自由浮动文本使用颜色表示层级（标题、副标题、详情分别处于不同层级）
• 证据材料（代码片段、JSON 示例）使用专属的深色背景 + 彩色文本方案
• 始终搭配较深的描边色和较浅的填充色，以形成对比

请勿自行创造新颜色。 如果某个概念不属于现有语义类别，请使用 Primary/Neutral 或 Secondary。

---

现代美学

打造简洁、专业的图表：

粗糙度

• roughness: 0 — 边缘简洁清晰。用于现代／技术类图表。
• roughness: 1 — 手绘、有机的感觉。用于头脑风暴／非正式图表。

大多数专业场景默认使用 0。

描边宽度

• strokeWidth: 1 — 纤细优雅。适合线条、分隔线和细微连接。
• strokeWidth: 2 — 标准宽度。适合形状和主要箭头。
• strokeWidth: 3 — 粗线。仅在强调时谨慎使用（主流程线、关键连接）。

不透明度

所有元素的 opacity: 100。 使用颜色、大小和描边宽度来建立层级，而非透明度。

使用小型标记代替形状

不要使用完整形状，而应使用小圆点（10-20px 的椭圆）作为：

• 时间线标记
• 项目符号
• 连接节点
• 自由浮动文本的视觉锚点

---

布局原则

通过比例建立层级

• 主视觉元素：300×150 — 视觉锚点，最重要
• 主要元素：180×90
• 次要元素：120×60
• 小型元素：60×40

留白体现重要性

最重要的元素周围应留出最多空白（200px 以上）。

流向

引导视线：序列通常从左到右或从上到下，中心辐射式结构则采用径向布局。

必需连接

仅靠位置无法体现关系。如果 A 与 B 有关联，就必须有箭头。

---

文本规则

重要：JSON 的 text 属性中只能包含可读文字。

{
  "id": "myElement1",
  "text": "Start",
  "originalText": "Start"
}

设置：fontSize: 16、fontFamily: 3、textAlign: "center"、verticalAlign: "middle"

---

JSON 结构

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [...],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": 20
  },
  "files": {}
}

元素模板

请参阅 references/element-templates.md，其中包含各类元素（文本、线条、圆点、矩形、箭头）的 JSON 模板，可直接复制粘贴。根据每个元素的语义用途，从 references/color-palette.md 中选取颜色。

---

渲染与验证（必须）

仅凭 JSON 无法判断图表效果。生成或编辑 Excalidraw JSON 后，必须将其渲染为 PNG、查看图像，并根据所见进行修正——循环往复，直到效果满意。这是工作流的核心环节，而非最后的检查。

如何渲染

cd .claude/skills/excalidraw-diagram/references && uv run python render_excalidraw.py <path-to-file.excalidraw>

这会在 .excalidraw 文件旁输出一个 PNG。然后使用 Read 工具实际查看该 PNG。

循环流程

生成初始 JSON 后，按以下步骤循环：

1. 渲染并查看 — 运行渲染脚本，然后用 Read 查看 PNG。

2. 对照原始构想审核 — 查找错误之前，先将渲染结果与步骤 1-4 中的设计进行比较。自问：

• 视觉结构是否符合规划的概念结构？
• 每个部分是否采用了预期的模式（扇出、汇聚、时间线等）？
• 视线是否按设计顺序流经图表？
• 视觉层级是否正确——核心元素是否突出，辅助元素是否较小？
• 对于技术图表：证据材料（代码片段、数据示例）是否清晰易读且位置恰当？

3. 检查视觉缺陷：

• 文本被容器裁切或溢出
• 文本或形状与其他元素重叠
• 箭头穿过元素，而非绕行
• 箭头指向错误的元素或空白处
• 标签位置模糊（未明确关联到其描述对象）
• 本应均匀间隔的元素之间间距不均
• 某些区域留白过多，而相邻区域过于拥挤
• 按渲染尺寸查看时，文字过小而难以阅读
• 整体构图失衡或偏斜

4. 修正 — 编辑 JSON，解决发现的所有问题。常见修正方法：

• 文本被裁切时，加宽容器
• 调整 x/y 坐标以修正间距和对齐
• 在箭头的 points 数组中添加中间航点，使箭头绕开元素
• 将标签移到更靠近其描述对象的位置
• 调整元素大小，以平衡各区域的视觉权重

5. 重新渲染并查看 — 再次运行渲染脚本，并用 Read 查看新的 PNG。

6. 重复 — 持续循环，直到图表通过构想检查（步骤 2）和缺陷检查（步骤 3）。通常需要迭代 2-4 次。即使没有严重问题，也不要只检查一遍就停止；如果构图还有改进空间，就继续优化。

停止条件

满足以下条件时，即可结束循环：

• 渲染后的图表符合规划步骤中的概念设计
• 没有文本被裁切、重叠或难以阅读
• 箭头走向清晰，并连接到正确的元素
• 间距一致，构图平衡
• 你可以放心地将图表展示给他人，无需附加说明

首次设置

如果尚未设置渲染脚本：

cd .claude/skills/excalidraw-diagram/references
uv sync
uv run playwright install chromium

---

质量检查清单

深度与证据（技术图表请先检查）

1. 已完成调研：是否查阅了实际规格、格式和事件名称？
2. 证据材料：是否包含代码片段、JSON 示例或真实数据？
3. 多层级缩放：是否同时包含摘要流程、分区边界和细节？
4. 具体内容优先于抽象概念：是否展示了真实内容，而不只是带标签的方框？
5. 教育价值：读者能否从中学到具体知识？

概念

6. 同构性：每种视觉结构是否都映射了其概念的行为？
7. 论证性：图表是否展示了仅靠文字无法表达的内容？
8. 多样性：每个主要概念是否都采用了不同的视觉模式？
9. 避免统一的容器：是否避免使用卡片网格和大小相同的方框？

容器使用规范

10. 尽量减少容器：任何带框元素是否可以改为自由排布的文本？
11. 用线条表示结构：树状图或时间线是否用线条和文本，而非方框来呈现？
12. 字体层级：是否通过字体大小和颜色形成视觉层级，从而减少对方框的需求？

结构

13. 连接关系：每种关系是否都有箭头或线条表示？
14. 流程：视线是否有清晰的视觉路径可循？
15. 层级：重要元素是否更大或更突出？

技术要求

16. 文本简洁：text 是否只包含可读文字？
17. 字体：fontFamily: 3
18. 粗糙度：对于简洁／现代风格，设置 roughness: 0（除非要求手绘风格）
19. 不透明度：所有元素的 opacity: 100（不使用透明效果）
20. 容器比例：位于容器内的文本元素是否少于 30%？

视觉验证（必须渲染）

21. 渲染为 PNG：图表是否已渲染并经过目视检查？
22. 无文本溢出：所有文本是否都能容纳在其容器内？
23. 无元素重叠：形状和文本是否没有意外重叠？
24. 间距均匀：相似元素之间的间距是否一致？
25. 箭头连接准确：箭头是否连接到目标元素，且未穿过其他元素？
26. 导出尺寸下清晰可读：渲染后的 PNG 中，文本是否清晰可辨？
27. 构图平衡：是否没有大片空白或过于拥挤的区域？