excalidraw-diagram

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Workflow

工作流程

Step 1: Understand the request

步骤1：理解需求

Before generating anything, make sure you know:

What concept or system are they diagramming?
What are the major components or sections?
What is the flow or relationship between them?

If the request is vague (e.g., "make a diagram of Docker"), ask 1-2 clarifying questions:

What specific aspect? (architecture, networking, volumes, etc.)
What level of detail? (high-level overview vs. detailed internals)

在生成任何内容之前，请确保你明确以下几点：

他们要绘制的是哪个概念或系统的图表？
主要组件或模块有哪些？
组件之间的流程或关系是什么？

如果需求模糊（例如：“制作一个Docker的图表”），请提出1-2个澄清问题：

具体是哪个方面？（架构、网络、卷等）
需要什么详细程度？（高层概览 vs 详细内部结构）

Step 2: Research if needed

步骤2：必要时进行调研

If you're not confident about the technical accuracy of the concept, research it before diagramming. Verify:

Correct component names and relationships
Proper hierarchy and nesting
Accurate data flow direction

如果你对概念的技术准确性没有把握，请在绘图前先调研。验证以下内容：

组件名称和关系是否正确
层级和嵌套结构是否合理
数据流方向是否准确

Step 3: Plan the layout

步骤3：规划布局

Before writing any JSON, sketch the layout mentally:

What are the major sections? (left-to-right or top-to-bottom)
What is nested inside what?
What arrows connect what?

Write down the section plan:

[Section A: w=170] --40px gap-- [Section B: w=170] --40px gap-- [Section C: w=640]

在编写任何JSON之前，先在脑海中勾勒布局：

主要模块有哪些？（从左到右或从上到下）
哪些元素嵌套在哪些元素内部？
哪些箭头连接哪些元素？

写下模块规划：

[模块A: 宽度=170] --40px间距-- [模块B: 宽度=170] --40px间距-- [模块C: 宽度=640]

Step 4: Generate elements

步骤4：生成元素

Build elements in order:

Outer boxes / containers first
Section header text
Nested elements (top to bottom within each section)
Arrows and arrow labels last

按顺序构建元素：

先创建外部框/容器
添加模块标题文本
添加嵌套元素（每个模块内从上到下）
最后添加箭头和箭头标签

Step 5: Save and deliver

步骤5：保存并交付

Save to
```
[concept-slug].excalidraw
```
in the current directory
Show the full JSON in a code block so the user can copy it directly
Briefly describe what the diagram shows and what each color zone represents
Tell the user how to use the file:

How to view and edit your diagram:
Go to excalidraw.com (free, no account needed)
Option A: Click the menu (top-left hamburger icon) > "Open" > select the
.excalidraw
file
Option B: Copy the JSON code block above, open excalidraw.com, and paste it with Ctrl+V / Cmd+V

Every element is fully editable -- drag to move, grab handles to resize, double-click to edit text

将文件保存到当前目录下的
```
[概念缩写].excalidraw
```
在代码块中展示完整的JSON，方便用户直接复制
简要说明图表展示的内容以及每个颜色区域代表的含义
告知用户如何使用该文件：

如何查看和编辑你的图表：
访问excalidraw.com（免费，无需注册账号）
选项A：点击菜单（左上角汉堡图标）> “打开” > 选择
.excalidraw
文件
选项B：复制上方的JSON代码块，打开excalidraw.com，使用Ctrl+V / Cmd+V粘贴

所有元素均可完全编辑——拖动移动，拖动手柄调整大小，双击编辑文本

Step 6: Handle feedback

步骤6：处理反馈

If the user asks for changes:

Shifting an element = update x/y on that element + all elements that depend on it
Changing text = update both
```
text
```
and
```
originalText
```
fields
Adding a zone = assign it a new color from the palette, keep spacing consistent
If a diagram gets complex (20+ elements), build it section by section to avoid coordinate errors

如果用户要求修改：

移动元素 = 更新该元素的x/y坐标以及所有依赖它的元素的坐标
修改文本 = 同时更新
```
text
```
和
```
originalText
```
字段
添加区域 = 从调色板中分配新颜色，保持间距一致
如果图表变得复杂（20个以上元素），分模块构建以避免坐标错误

Critical Rule: Text Contrast

关键规则：文本对比度

Text inside colored shapes must be readable. Use

#1e1e1e

(near-black) or

#343a40

(dark charcoal) for all text inside filled shapes. Never use the zone's stroke color for text sitting on that zone's background (e.g., yellow text on a yellow card is unreadable). Reserve the zone's strokeColor for shape borders and arrows only.

彩色形状内的文本必须清晰可读。所有填充形状内的文本使用

#1e1e1e

（近黑色）或

#343a40

（深炭灰色）。绝不要使用区域的描边颜色作为该区域背景上的文本颜色（例如，黄色卡片上的黄色文本不可读）。仅将区域的strokeColor用于形状边框和箭头。

Design Principles

设计原则

Color tells the story: One color per logical zone. Everything in the "input" zone is blue. Everything in the "output" zone is green. The viewer should understand structure before reading a word.

Nesting shows containment: If X lives inside Y, X's box is drawn inside Y's box with consistent padding. Coordinates are absolute, not relative:

child_x = parent_x + padding

Labels are short: 2-5 words per label. Longer explanations become annotations with smaller fontSize and muted color (

#868e96

White space is structure: 15px minimum gap between siblings. 40px minimum between major sections.

Arrows carry intent: Color arrows to match purpose. Label every non-obvious arrow.

颜色传递信息： 每个逻辑区域使用一种颜色。“输入”区域内的所有元素均为蓝色。“输出”区域内的所有元素均为绿色。查看者应在阅读文字前先理解结构。

嵌套表示包含关系： 如果X包含在Y内，X的框应绘制在Y的框内，并保持一致的内边距。坐标为绝对坐标，而非相对坐标：

子元素x坐标 = 父元素x坐标 + 内边距

。

标签简洁： 每个标签2-5个单词。较长的说明使用更小字号和柔和颜色（

#868e96

）作为注释。

留白构建结构： 同级元素之间最小间距为15px。主要模块之间最小间距为40px。

箭头承载意图： 根据用途为箭头着色。为所有非直观的箭头添加标签。

Layout System

布局系统

Always plan coordinates before writing JSON.

Identify major sections (left-to-right or top-to-bottom)
Assign fixed width and starting x to each section
Calculate gaps: 40-60px between major sections, 15-25px between siblings

Work top-to-bottom within sections:

next_y = current_y + current_height + gap

Padding rules:

Outer box to inner label: 8-10px top offset
Outer box to nested box: 10-15px offset on all sides
Sibling elements: 10-15px gap

Text width trick: Set text width = parent box width. Text centers automatically when

textAlign: "center"

Arrow labels: Position as separate text elements, 20-25px above the arrow's midpoint y, with width and x matching the arrow.

Coordinate math example:

Section A: x=30,  w=170  -> right edge = 200
Gap:                        40px
Section B: x=240, w=170  -> right edge = 410
Gap:                        40px
Section C: x=450, w=600  -> right edge = 1050

在编写JSON之前务必规划坐标。

确定主要模块（从左到右或从上到下）
为每个模块分配固定宽度和起始x坐标
计算间距：主要模块之间40-60px，同级元素之间15-25px

模块内从上到下构建：

下一个元素y坐标 = 当前元素y坐标 + 当前元素高度 + 间距

内边距规则：

外框到内部标签：顶部偏移8-10px
外框到嵌套框：所有边偏移10-15px
同级元素：10-15px间距

文本宽度技巧： 设置文本宽度等于父框宽度。当

textAlign: "center"

时，文本会自动居中。

箭头标签： 作为独立文本元素放置，位于箭头中点y坐标上方20-25px处，宽度和x坐标与箭头匹配。

坐标计算示例：

模块A: x=30, 宽度=170  -> 右边缘 = 200
间距:                        40px
模块B: x=240, 宽度=170  -> 右边缘 = 410
间距:                        40px
模块C: x=450, 宽度=600  -> 右边缘 = 1050

Color System

颜色系统

Zone	Use for	strokeColor	backgroundColor
Blue	Input, source, external services	`#1971c2`	`#e7f5ff`
Yellow	Processing, transformation	`#f59f00`	`#fff9db`
Green	Output, containers, success	`#2f9e44`	`#d3f9d8`
Purple	Shared layers, infrastructure	`#862e9c`	`#f3d9fa`
Red	Host OS, warnings, errors	`#c92a2a`	`#ffe3e3`
Gray	Hardware, neutral containers	`#495057`	`#f8f9fa`

For nested elements, vary the fill intensity:

Outer: lightest (e.g.,
```
#d3f9d8
```
)
Inner: medium (e.g.,
```
#8ce99a
```
)
Deep inner: light-medium (e.g.,
```
#b2f2bb
```
)

区域	用途	strokeColor	backgroundColor
蓝色	输入、源、外部服务	`#1971c2`	`#e7f5ff`
黄色	处理、转换	`#f59f00`	`#fff9db`
绿色	输出、容器、成功状态	`#2f9e44`	`#d3f9d8`
紫色	共享层、基础设施	`#862e9c`	`#f3d9fa`
红色	宿主操作系统、警告、错误	`#c92a2a`	`#ffe3e3`
灰色	硬件、中性容器	`#495057`	`#f8f9fa`

对于嵌套元素，调整填充强度：

外层：最浅（例如：
```
#d3f9d8
```
）
中层：中等（例如：
```
#8ce99a
```
）
深层：浅中等（例如：
```
#b2f2bb
```
）

Typography Scale

排版规范

Role	fontSize	fontFamily
Diagram title	32-36	1 (Virgil)
Section header	20-24	1
Element label	16-18	1
Annotation	14-15	1
Small note	12-13	1
Code label	14-16	3 (Cascadia)

Text width = parent box width. Text x/y offset ~8-10px from box x/y for padding.

角色	fontSize	fontFamily
图表标题	32-36	1 (Virgil)
模块标题	20-24	1
元素标签	16-18	1
注释	14-15	1
小说明	12-13	1
代码标签	14-16	3 (Cascadia)

文本宽度 = 父框宽度。文本x/y偏移量为框x/y坐标外8-10px作为内边距。

Element Schema

元素 Schema

Every element needs these base fields. Do not omit any.

每个元素都需要以下基础字段，请勿遗漏任何字段。

Base fields (all types)

基础字段（所有类型）

json

{
  "id": "unique-string",
  "type": "rectangle|ellipse|diamond|arrow|line|text|freedraw",
  "x": 0, "y": 0,
  "width": 100, "height": 50,
  "angle": 0,
  "strokeColor": "#1e1e1e",
  "backgroundColor": "transparent",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid",
  "roughness": 1,
  "opacity": 100,
  "groupIds": [],
  "frameId": null,
  "roundness": null,
  "boundElements": [],
  "updated": 1,
  "link": null,
  "locked": false
}

json

{
  "id": "unique-string",
  "type": "rectangle|ellipse|diamond|arrow|line|text|freedraw",
  "x": 0, "y": 0,
  "width": 100, "height": 50,
  "angle": 0,
  "strokeColor": "#1e1e1e",
  "backgroundColor": "transparent",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "strokeStyle": "solid",
  "roughness": 1,
  "opacity": 100,
  "groupIds": [],
  "frameId": null,
  "roundness": null,
  "boundElements": [],
  "updated": 1,
  "link": null,
  "locked": false
}

Text fields (add to base)

文本字段（添加到基础字段）

json

{
  "text": "Label text",
  "fontSize": 16,
  "fontFamily": 1,
  "textAlign": "center",
  "verticalAlign": "top",
  "containerId": null,
  "originalText": "Label text",
  "lineHeight": 1.25
}

json

{
  "text": "Label text",
  "fontSize": 16,
  "fontFamily": 1,
  "textAlign": "center",
  "verticalAlign": "top",
  "containerId": null,
  "originalText": "Label text",
  "lineHeight": 1.25
}

Arrow fields (add to base)

箭头字段（添加到基础字段）

json

{
  "points": [[0, 0], [100, 0]],
  "lastCommittedPoint": null,
  "startBinding": null,
  "endBinding": null,
  "startArrowhead": null,
  "endArrowhead": "arrow"
}

json

{
  "points": [[0, 0], [100, 0]],
  "lastCommittedPoint": null,
  "startBinding": null,
  "endBinding": null,
  "startArrowhead": null,
  "endArrowhead": "arrow"
}

Key values

关键值说明

fontFamily: 1 = Virgil (handwritten, default), 2 = Helvetica, 3 = Cascadia (monospace)
roughness: 0 = smooth, 1 = slightly rough (default Excalidraw feel), 2 = very rough
fillStyle:
```
"solid"
```
for clean diagrams,
```
"hachure"
```
for classic Excalidraw hatching
roundness:
```
null
```
= sharp corners,
```
{"type": 3}
```
= rounded rectangles,
```
{"type": 2}
```
= curved arrows
strokeStyle:
```
"solid"
```
,
```
"dashed"
```
(optional connections),
```
"dotted"
```

fontFamily: 1 = Virgil（手写体，默认）, 2 = Helvetica, 3 = Cascadia（等宽字体）
roughness: 0 = 平滑, 1 = 轻微粗糙（默认Excalidraw风格）, 2 = 非常粗糙
fillStyle:
```
"solid"
```
用于简洁图表,
```
"hachure"
```
用于经典Excalidraw阴影填充
roundness:
```
null
```
= 尖锐角,
```
{"type": 3}
```
= 圆角矩形,
```
{"type": 2}
```
= 弧形箭头
strokeStyle:
```
"solid"
```
,
```
"dashed"
```
（可选连接）,
```
"dotted"
```

Common Patterns

常见模式

Labeled box

带标签的框

[Rect: x, y, w, h]
[Title text: x, y+10, w, fontSize=18]
[Subtitle: x, y+38, w, fontSize=14, strokeColor=#868e96]

[矩形: x, y, w, h]
[标题文本: x, y+10, w, fontSize=18]
[副标题: x, y+38, w, fontSize=14, strokeColor=#868e96]

Nested container

嵌套容器

[Host rect: x=0, y=0, w=640, h=500]
[Host label: x=0, y=10, w=640]
[Item 1: x=15, y=50, w=190, h=200]
[Item 2: x=225, y=50, w=190, h=200]
[Item 3: x=435, y=50, w=190, h=200]

[宿主矩形: x=0, y=0, w=640, h=500]
[宿主标签: x=0, y=10, w=640]
[项目1: x=15, y=50, w=190, h=200]
[项目2: x=225, y=50, w=190, h=200]
[项目3: x=435, y=50, w=190, h=200]

Arrow with label

带标签的箭头

[Arrow: x=start_x, y=mid_y, width=gap_width, points=[[0,0],[gap_width,0]]]
[Label: x=start_x, y=mid_y-25, width=gap_width, textAlign=center]

[箭头: x=起始x坐标, y=中点y坐标, width=间距宽度, points=[[0,0],[间距宽度,0]]]
[标签: x=起始x坐标, y=中点y坐标-25, width=间距宽度, textAlign=center]

JSON Wrapper

JSON 包装器

Every diagram uses this shell:

json

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

每个图表都使用以下结构：

json

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