生成具备“视觉论证”能力的 Excalidraw 架构图 JSON 文件。当用户需要对工作流、系统架构或抽象概念进行可视化表达时使用。
Excalidraw Diagram Creator
生成真正的 .excalidraw JSON 文件——用图形进行论证，而不仅仅是罗列信息。
安装配置： 如果用户让你配置此 Skill（渲染器、依赖项等），请参阅 README.md 获取指引。
定制化指南
所有颜色和品牌样式统一保存在单个文件中： references/color-palette.md。在生成任何图表前，务必先读取该文件，并将其作为所有配色选择（形状填充、描边、文本颜色、实物证据背景等）的唯一真理来源（Single Source of Truth）。
如果你想让该 Skill 按照自定义的品牌风格生成图表，直接修改 color-palette.md 即可。本文件中的其他内容均为通用设计方法论与 Excalidraw 最佳实践。
核心设计理念
图表应该用于“论证”，而不是纯“展示”。
图表不是格式化文本的简单堆砌，而是一种用视觉语言表达关系、因果和流转的论证方式，这些是单纯靠文字无法直观表达的。形状本身就是含义。
同构性检验（The Isomorphism Test）：如果把图中所有的文字抹去，单凭结构本身还能传达出核心概念吗？如果不能，请重新设计。
教学性检验（The Education Test）：读者能否从这张图中学到具体干货，还是说它只是给几个方框打了个标签？一张优秀图表是有教学价值的——它会展示真实的格式、具体的事件名称以及贴合实际的示例。
细节深度评估（设计前的首要步骤）
在动手设计之前，先确定这张图表需要多大的细节颗粒度：
简单 / 概念型图表
在以下场景使用抽象形状：
- 讲解某种思维模型或设计哲学
- 受众不需要了解技术细节
- 概念本身就是抽象的（例如“关注点分离”）
完整 / 技术型图表
在以下场景使用具体示例：
- 绘制真实的系统、协议或架构图
- 图表将用于教学或讲解（例如制作 YouTube 视频）
- 受众需要清楚了解实际数据和组件的具体形态
- 展示多种技术栈如何集成
对于技术型图表，必须包含“实物证据”（Evidence Artifacts，详情见下文）。
调研硬性要求（针对技术型图表）
在绘制任何技术架构之前，先去查阅真实的技术规范（Specs）。
如果你要绘制协议、API 或框架图表：
- 查阅真实的 JSON 或数据格式
- 找到真实的事件名称、方法名或 API 端点
- 搞清楚各个组件之间真实的连接机制
- 使用真实的技术术语，绝不用通用的占位符
错误示例：“Protocol” → “Frontend”
正确示例：“AG-UI 抛出流式事件（RUN_STARTED, STATE_DELTA, A2UI_UPDATE）” → “CopilotKit 通过 createA2UIMessageRenderer() 进行渲染”
充分的调研能让图表既准确又具教学价值。
实物证据（Evidence Artifacts）
实物证据是用于证明图表准确性并帮助读者学习的具体示例。在技术型图表中务必包含它们。
实物证据类型（根据图表主题选择合适类型）：
| 证据类型 | 适用场景 | 渲染方式 |
|---|---|---|
| 代码片段 | API、集成细节、实现细节 | 深色矩形 + 语法高亮文本（颜色详见配色方案中的实物证据说明） |
| 数据 / JSON 示例 | 数据格式、Schema、Payload | 深色矩形 + 彩色文本（详见配色方案） |
| 事件 / 步骤序列 | 协议、工作流、生命周期 | 时间轴模式（线条 + 节点 + 标签） |
| UI 原型 | 展示实际输出 / 结果 | 模拟真实 UI 的嵌套矩形 |
| 真实输入内容 | 展示进入系统的原始输入 | 包含可见示例内容框 |
| API / 方法名 | 真实的函数调用、端点 | 使用文档中的真实名称，拒绝占位符 |
示例：对于流式传输协议图表，可以展示：
- 规范中的真实事件名称（而不是“Event 1”、“Event 2”）
- 展示如何建立连接的代码片段
- 流式数据的真实呈现形态
示例：对于数据转换 Pipeline 图表：
- 展示输入样例数据（真实格式，而不是写个“Input”）
- 展示输出样例数据（真实格式，而不是写个“Output”）
- 必要时展示中间状态
核心原则：展示事物真实的模样，而不仅仅是标出它们叫什么。
多层级缩放架构（Multi-Zoom Architecture）
完整的图表可以同时在多个缩放层级上工作。就像地图一样，既能看到国家边界，又能看清街道名称。
Level 1：概览主流（Summary Flow）
简化版的高层概览，让全貌 Pipeline 或流程一目了然。通常放在图表顶部或底部。
示例：Input → Processing → Output 或 Client → Server → Database
Level 2：区域边界（Section Boundaries）
带标签的划片区域，用于归类相关组件。它们就像视觉上的“房间”，帮助读者理清归属关系。
示例：按职责划分（Backend / Frontend）、按阶段划分（Setup / Execution / Cleanup）、或按团队划分（User / System / External）
Level 3：区域内细节（Detail Inside Sections）
每个区域内部包含的实物证据、代码片段和具体示例。这就是教学价值所在。
示例：在“Backend”区域内部，展示真实的 API 响应格式，而不是只放一个写着“API Response”的方框。
对于完整型图表，尽量覆盖这三个层级。 概览给上下文，区域作组织，细节出干货。
好坏对比
| 坏（单纯展示） | 好（深入论证） |
|---|---|
| 5 个带标签的等大方框 | 每个概念都有与其行为镜像对应的图形结构 |
| 卡片网格化布局 | 视觉结构完全契合概念结构 |
| 用图标给文本做装饰 | 图形本身即是含义 |
| 所有内容都用同一种容器 | 每个概念拥有独特的视觉语言 |
| 把所有东西都塞进框里 | 自由浮动文本结合精选容器 |
简单 vs 完整（明确你需要哪一种）
| 简单图表 | 完整图表 |
|---|---|
| 通用标签：如“Input” → “Process” → “Output” | 具体明确：展示输入 / 输出的实际形态 |
| 仅标出名称的方框：如“API”、“Database”、“Client” | 标名方框 + 真实请求/响应示例 |
| 仅标记“Events”或“Messages” | 时间轴 + 规范中真实的事件/消息名称 |
| 写着“UI”或“Dashboard”的矩形 | 原型框 + 真实 UI 元素与内容 |
| 约 30 秒能讲完 | 包含 2~3 分钟的干货教学内容 |
| 读者只记住了结构 | 读者掌握了结构 且 理解了细节 |
简单图表 适用于讲解抽象概念、快速概览，或者受众已经了解细节的场景。完整图表 则适用于技术架构图、教程、教学内容，或者希望图表本身就能教明白人的场景。
容器文本 vs. 自由浮动文本
不是所有文字都需要套个外框。 默认优先使用自由浮动文本。只有在明确起作用时才使用容器框。
| 何时使用容器框…… | 何时使用自由浮动文本…… |
|---|---|
| 它是某个区域的核心焦点 | 它是标签或说明文字 |
| 需要与其他元素进行视觉分组 | 它是辅助细节或元数据 |
| 需要有箭头连接到它 | 它在描述旁边的某个组件 |
| 形状本身具备含义（如决策菱形等） | 仅靠排版字号就足以构建清晰层级 |
| 它代表系统中的一个独立实体 | 它是区域标题、副标题或标注文字 |
利用排版建立层级：通过字号、字重和颜色建立视觉层级，无需画框。一个 28px 的标题完全不需要外面套个矩形。
容器检验法：对于每个加框元素，问一句：“把它换成自由浮动文本行得通吗？” 如果行得通，就删掉框。
设计流程（在生成 JSON 之前必须完成）
Step 0：评估所需深度
首先确定本图表属于哪类：
- 简单 / 概念型：抽象形状、标签、关联关系（思维模型、设计哲学）
- 完整 / 技术型：具体示例、代码片段、真实数据（系统、架构、教程）
如果是完整型图表：务必先做调研。查阅真实规范、格式、事件名称、API。
Step 1：深入理解概念
仔细阅读内容。针对每个概念，思考：
- 这个概念做了什么？（而不是它“是什么”）
- 概念之间存在怎样的关系？
- 核心转换或流转过程是什么？
- 读者需要“看到”什么才能彻底理解它？（而不仅仅是阅读文字）
Step 2：概念与视觉模式映射
为每个概念找到能反应其行为特征的视觉模式：
| 如果该概念特征为…… | 使用这种视觉模式 |
|---|---|
| 衍生出多个输出 | 扇出（Fan-out）（从中心向外放射箭头） |
| 将多个输入聚合为一个 | 收敛（Convergence）（漏斗、箭头合并） |
| 具备层级 / 嵌套关系 | 树状（Tree）（连线 + 自由浮动文本） |
| 属于连续步骤序列 | 时间轴（Timeline）（线条 + 节点 + 自由浮动标签） |
| 循环或持续迭代优化 | 螺旋 / 循环（Spiral/Cycle）（箭头折返回起点） |
| 属于抽象状态或上下文 | 云朵（Cloud）（重叠椭圆） |
| 将输入转换为输出 | 流水线（Assembly line）（前 → 处理 → 后） |
| 对比两个事物 | 左右对比（Side-by-side）（平行展示 + 对比色） |
| 划分为不同阶段 | 间隙 / 断层（Gap/Break）（区域之间的视觉隔离） |
Step 3：确保视觉多样性
对于包含多个概念的图表：每个主要概念必须使用不同的视觉模式。绝不能搞千篇一律的卡片或网格。
Step 4：构思视线流向
在编写 JSON 之前，先在脑海中追踪视线浏览图表的轨迹，确保具备清晰的视觉叙事线索。
Step 5：生成 JSON
完成上述步骤后，再开始创建 Excalidraw 元素。关于大型图表的处理方法，请参阅下文。
Step 6：渲染与校验（硬性要求）
生成 JSON 后，必须执行“渲染 - 查看 - 修复”循环，直到图表视觉效果无误。这是 mandatory 步骤——完整流程见下文 渲染与校验 章节。
大型 / 完整图表生成策略
对于完整型或技术型图表，必须分区域（Section by Section）分步构建 JSON。 切勿尝试单次生成整份文件。这是一项硬性约束——Claude Code 每次响应约有 32,000 token 的输出上限，完整图表很容易单次溢出。即便不溢出，一次性生成所有内容也会导致质量下降。按区域分步构建在各方面都表现更佳。
分区域构建工作流
第一阶段：逐个构建区域
- 创建基础文件：包含 JSON 包装器（
type,version,appState,files）以及第一个区域的元素。 - 每次编辑增加一个区域：每个区域分配独立的处理轮次——耐心雕琢。仔细思考布局、间距以及该区域如何与已有部分进行衔接。
- 使用具象化的字符串 ID（例如
"trigger_rect","arrow_fan_left"），方便跨区域引用时具备可读性。 - 按区域给 seed 划分命名空间（例如第 1 区域使用 100xxx，第 2 区域使用 200xxx），避免碰撞冲突。
- 边写边更新跨区域绑定：当新区域元素需要绑定到先前区域的元素（如连接不同区域的箭头）时，同步修改先前元素的
boundElements数组。
第二阶段：全局审查
所有区域就位后，通读完整 JSON 并检查：
- 跨区域箭头的两端绑定是否均正确？
- 整体间距是否均衡？是否存在某些区域太挤而另一些区域留白过大的情况？
- 所有的 ID 和绑定是否都指向实际存在的元素？
在渲染前修复所有的对齐或绑定问题。
第三阶段：渲染与校验
运行“渲染 - 查看 - 修复”循环。在这一步，你可以发现从 JSON 代码中无法直接察觉的视觉问题——重叠、裁剪、构图失衡等。
区域划分原则
围绕自然的视觉分组来规划区域
