Back to Details

excalidraw-diagrams

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Creating Excalidraw Diagrams

创建Excalidraw图表

When creating Excalidraw diagrams, ensure you:
  • Generate the layout with correct spacing
  • Make consistent and logical use of colours, fonts, and shapes
  • Text is correctly added within shapes, not as separate text elements (unless desired)
  • Arrows and lines are correctly anchored / connected to shapes (not floating) so that when objects are moved any connections remain intact
  • You save the Excalidraw diagram content to a file and link the file path
  • Call 
    read_me
    before your first 
    create_view
    call each session - it provides the colour palette, camera sizes, layout rules, and element format reference.
  • If the user has asked you to create Excalidraw diagrams but you do not have the Excalidraw MCP enabled, you should ask them to add it for you, they can configured it by using the HTTP MCP URL of: https://excalidraw-mcp-app.vercel.app/mcp and they can view the MCP documentation here: https://github.com/excalidraw/excalidraw-mcp
创建Excalidraw图表时，请确保：
  • 生成布局时保持正确的间距
  • 颜色、字体和形状的使用保持一致且符合逻辑
  • 文本应正确添加到形状内部，而非作为独立的文本元素（除非有特殊需求）
  • 箭头和线条应正确锚定/连接到形状上（而非悬浮状态），这样移动对象时所有连接都能保持完整
  • 将Excalidraw图表内容保存到文件并提供文件路径
  • 每个会话中首次调用
    create_view
    前先调用
    read_me
    ——它会提供调色板、画布尺寸、布局规则和元素格式参考
  • 如果用户要求你创建Excalidraw图表，但Excalidraw MCP未启用，你应请求用户添加它，用户可通过HTTP MCP URL：https://excalidraw-mcp-app.vercel.app/mcp 进行配置，MCP文档可在此查看：https://github.com/excalidraw/excalidraw-mcp

Choose your workflow

选择你的工作流

Pick one based on what the user needs. Do not default to doing both.
根据用户需求选择其中一种，不要默认同时执行两种。

Inline preview only (
create_view
)

仅在线预览（
create_view
）

Use when the diagram is for the conversation only - the user wants to see it in the chat and does not need a file.
  • Use 
    create_view
    with 
    label
    on shapes (works fine here)
  • Use 
    cameraUpdate
    to animate and guide attention
  • No file output needed
适用于图表仅用于会话场景——用户希望在聊天中查看图表，不需要文件。
  • 在形状上使用带
    label
    的
    create_view
    （在此场景下效果良好）
  • 使用
    cameraUpdate
    来制作动画并引导注意力
  • 无需输出文件

File output only (Python script)

仅输出文件（Python脚本）

Use when the user needs a 
.excalidraw
file to open, share, edit, or keep. Skip 
create_view
entirely.
  • Generate the file with 
    scripts/generate_excalidraw.py
    (see below)
  • Provide the file path to the user
  • Files can be opened by dragging into excalidraw.com, the Excalidraw desktop app, or VS Code with the Excalidraw extension
适用于用户需要
.excalidraw
文件来打开、分享、编辑或保存的场景。完全跳过
create_view
。
  • 使用
    scripts/generate_excalidraw.py
    生成文件（见下文）
  • 向用户提供文件路径
  • 文件可通过拖拽方式在excalidraw.com、Excalidraw桌面应用或安装了Excalidraw扩展的VS Code中打开

Both (inline preview + file)

两者兼顾（在线预览+文件）

Use when the user wants to see the diagram in the chat AND keep a file. Note: these are built independently with different element formats. There is no data bridge between them - you define the diagram structure once conceptually but render it twice.
  • create_view
    with 
    label
    for the inline preview
  • Python script with 
    labeled_rect
    for the 
    .excalidraw
    file
适用于用户既希望在聊天中查看图表，又需要保存文件的场景。注意：这两种方式是独立构建的，使用不同的元素格式，它们之间没有数据桥接——你只需在概念上定义一次图表结构，但要渲染两次。
  • 在线预览使用带
    label
    的
    create_view
  • .excalidraw
    文件使用带
    labeled_rect
    的Python脚本

Critical: text does not survive export

重要提示：文本无法在导出中保留

The 
label
property on shapes is a 
create_view
convenience only. It does NOT work in:
  • export_to_excalidraw
    uploads (shapes render, text is invisible)
  • .excalidraw
    files written from 
    create_view
    checkpoint data
Do NOT use 
export_to_excalidraw
for shareable diagrams. It seems to have a bug that can silently drop all text.
Native Excalidraw represents text inside shapes as two linked elements:
  1. Shape: 
    "boundElements": [{"id": "text-id", "type": "text"}]
  2. Text: 
    "containerId": "shape-id"
    , 
    "textAlign": "center"
    , 
    "verticalAlign": "middle"
The text element requires fields the 
label
shorthand omits: 
fontFamily
(1), 
width
, 
height
, 
originalText
, 
lineHeight
(1.25), 
autoResize
(true).
All elements in .excalidraw files also need: 
angle
, 
seed
, 
version
, 
versionNonce
, 
isDeleted
, 
groupIds
, 
frameId
, 
updated
, 
link
, 
locked
.
Hand-writing this JSON is error-prone. Use the Python script instead.
形状上的
label
属性只是
create_view
的便捷写法，它在以下场景中无效：
  • export_to_excalidraw
    上传（形状会渲染，但文本不可见）
  • 从
    create_view
    检查点数据生成的
    .excalidraw
    文件
不要使用
export_to_excalidraw
来创建可分享的图表，它存在一个会导致所有文本被静默丢失的bug。
原生Excalidraw将形状内的文本表示为两个关联元素：
  1. 形状：
    "boundElements": [{"id": "text-id", "type": "text"}]
  2. 文本：
    "containerId": "shape-id"
    , 
    "textAlign": "center"
    , 
    "verticalAlign": "middle"
文本元素需要
label
简写方式省略的字段：
fontFamily
（1）、
width
、
height
、
originalText
、
lineHeight
（1.25）、
autoResize
（true）。
.excalidraw
文件中的所有元素还需要以下字段：
angle
、
seed
、
version
、
versionNonce
、
isDeleted
、
groupIds
、
frameId
、
updated
、
link
、
locked
。
手动编写此JSON容易出错，请改用Python脚本。

Python script: 
scripts/generate_excalidraw.py

Python脚本：
scripts/generate_excalidraw.py

Generates native .excalidraw files with all required fields. Can be used inline in a bash heredoc or imported as a library.
Key functions:
FunctionReturnsPurpose
labeled_rect(id, x, y, w, h, bg, stroke, label, ...)
[rect, text]
Shape with centred bound text (handles all binding and field generation)
rect(id, x, y, w, h, bg, stroke, ...)
elementRectangle without text
txt(id, x, y, w, h, text, size, ...)
elementStandalone or bound text
bound_arrow(id, elements, start_id, start_point, end_id, end_point, ...)
elementArrow anchored to two shapes (mutates shapes' boundElements)
arrow(id, x, y, w, h, points, ...)
elementUnbound/floating arrow (use 
bound_arrow
instead when connecting shapes)
ellipse(...)
/ 
diamond(...)
elementOther shape types
write_scene(elements, path)
writes fileWraps in scene structure and saves
Example:
bash
python3 << 'PYEOF'
import sys, random
sys.path.insert(0, "/Users/samm/.claude/skills/excalidraw-diagrams/scripts")
from generate_excalidraw import *

random.seed(42)
elements = []
elements.append(txt("t1", 200, 10, 300, 30, "My Diagram", 24))
elements.extend(labeled_rect("a", 50, 60, 200, 70, "#a5d8ff", "#4a9eed", "Step One"))
elements.extend(labeled_rect("b", 350, 60, 200, 70, "#b2f2bb", "#22c55e", "Step Two"))
elements.append(bound_arrow("a1", elements, "a", [1, 0.5], "b", [0, 0.5]))
write_scene(elements, "/path/to/output.excalidraw")
PYEOF
For shapes without the 
labeled_rect
convenience, pair 
rect(..., bound_text="tid")
with 
txt(..., container="rid", align="center", valign="middle")
.
生成包含所有必填字段的原生
.excalidraw
文件。可在bash heredoc中内联使用，也可作为库导入。
核心函数：
函数返回值用途
labeled_rect(id, x, y, w, h, bg, stroke, label, ...)
[rect, text]
包含居中关联文本的形状（处理所有关联和字段生成）
rect(id, x, y, w, h, bg, stroke, ...)
元素无文本的矩形
txt(id, x, y, w, h, text, size, ...)
元素独立或关联的文本
bound_arrow(id, elements, start_id, start_point, end_id, end_point, ...)
元素锚定到两个形状的箭头（会修改形状的
boundElements
）
arrow(id, x, y, w, h, points, ...)
元素未锚定/悬浮的箭头（连接形状时请改用
bound_arrow
）
ellipse(...)
/ 
diamond(...)
元素其他形状类型
write_scene(elements, path)
写入文件将元素包装为场景结构并保存
示例：
bash
python3 << 'PYEOF'
import sys, random
sys.path.insert(0, "/Users/samm/.claude/skills/excalidraw-diagrams/scripts")
from generate_excalidraw import *

random.seed(42)
elements = []
elements.append(txt("t1", 200, 10, 300, 30, "My Diagram", 24))
elements.extend(labeled_rect("a", 50, 60, 200, 70, "#a5d8ff", "#4a9eed", "Step One"))
elements.extend(labeled_rect("b", 350, 60, 200, 70, "#b2f2bb", "#22c55e", "Step Two"))
elements.append(bound_arrow("a1", elements, "a", [1, 0.5], "b", [0, 0.5]))
write_scene(elements, "/path/to/output.excalidraw")
PYEOF
对于没有
labeled_rect
便捷方法的形状，可将
rect(..., bound_text="tid")
与
txt(..., container="rid", align="center", valign="middle")
配合使用。

Arrow anchoring

箭头锚定

By default, arrows float free - moving a shape leaves the arrow behind. Use 
bound_arrow
instead of 
arrow
to anchor arrows to shapes. It handles the bidirectional binding automatically (arrow references shapes, shapes list the arrow in 
boundElements
).
fixedPoint
values for connection points on shapes: top=
[0.5, 0]
, right=
[1, 0.5]
, bottom=
[0.5, 1]
, left=
[0, 0.5]
. Any 
[fx, fy]
value works where 0,0 is the shape's top-left corner and 1,1 is bottom-right.
Important:
  • Shapes must already exist in 
    elements
    before calling 
    bound_arrow
    , since it looks them up and mutates their 
    boundElements
    .
  • Minimum 60px between connected shapes. Excalidraw recalculates bound arrow geometry at render time. When shapes are too close together (under ~60px gap), arrows overlap and pass through boxes instead of connecting at edges. The script warns if this threshold is violated. Plan layouts with adequate spacing.
  • Avoid large background rectangles that overlap connectable shapes. Excalidraw's binding resolution can misfire when a bound arrow's endpoint falls inside a background rect that overlaps the intended target shape. If you need section backgrounds, add them after all bound arrows, or use standalone text labels and colour-coded boxes instead.
For the inline 
create_view
workflow, use 
startBinding
/
endBinding
with 
fixedPoint
directly on arrow elements.
默认情况下，箭头是悬浮的——移动形状时箭头会留在原地。请使用
bound_arrow
替代
arrow
来将箭头锚定到形状上，它会自动处理双向关联（箭头引用形状，形状在
boundElements
中列出箭头）。
形状连接点的
fixedPoint
值：顶部=
[0.5, 0]
、右侧=
[1, 0.5]
、底部=
[0.5, 1]
、左侧=
[0, 0.5]
。任何
[fx, fy]
值都有效，其中0,0是形状的左上角，1,1是右下角。
重要注意事项：
  • 调用
    bound_arrow
    前，形状必须已存在于
    elements
    中，因为它需要查找并修改形状的
    boundElements
    。
  • 连接的形状之间至少保持60px间距。Excalidraw会在渲染时重新计算关联箭头的几何形状。当形状间距过近（小于约60px）时，箭头会重叠并穿过方框，而非连接到边缘。如果违反此阈值，脚本会发出警告。规划布局时请预留足够的间距。
  • 避免使用会覆盖可连接形状的大型背景矩形。当关联箭头的端点落在覆盖目标形状的背景矩形内时，Excalidraw的关联解析可能会出错。如果需要分区背景，请在所有关联箭头添加完成后再添加背景，或使用独立文本标签和颜色编码的方框替代。
对于在线
create_view
工作流，可在箭头元素上直接使用带
fixedPoint
的
startBinding
/
endBinding
。

Privacy

隐私说明

Note that if the diagram contains potentially sensitive information (e.g. detailed network diagrams, identifiable information etc...) and the user asks you to upload the diagram to excalidraw.com - you should first warn them that this will make the diagram publicly accessible and ask if they want to proceed.
请注意，如果图表包含潜在敏感信息（例如详细的网络图表、可识别信息等），且用户要求你将图表上传到excalidraw.com，你应首先警告用户这会使图表公开可访问，并询问用户是否要继续。