excalidraw

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Excalidraw Diagrams

Excalidraw 图表

Overview

概述

Generate

.excalidraw

JSON files and export to PNG/SVG.

Two export options:

Kroki API (
```
curl
```
) — zero install, SVG output only
excalidraw-brute-export-cli — local Firefox-based, PNG + SVG

Supported formats: PNG (local CLI only), SVG (both options). PDF is NOT supported.

生成

.excalidraw

JSON 文件并导出为 PNG/SVG 格式。

两种导出选项：

Kroki API（
```
curl
```
）——无需安装，仅支持 SVG 输出
excalidraw-brute-export-cli ——基于本地 Firefox，支持 PNG + SVG 输出

支持的格式： PNG（仅本地 CLI）、SVG（两种选项均支持）。不支持 PDF 格式。

When to Use

使用场景

Explicit triggers: user says "画图", "diagram", "visualize", "flowchart", "draw", "架构图", "流程图"

Proactive triggers:

Explaining a system with 3+ interacting components
Describing a multi-step process or decision tree
Comparing architectures or approaches side by side

Skip when: a simple list or table suffices, or user is in a quick Q&A flow

明确触发条件： 用户提及「画图」「diagram」「visualize」「flowchart」「draw」「架构图」「流程图」

主动触发条件：

解释包含3个及以上交互组件的系统
描述多步骤流程或决策树
对比不同架构或方案

跳过场景： 简单列表或表格即可满足需求，或用户处于快速问答流程中

Prerequisites

前置条件

Option A: Kroki API (recommended — zero install, SVG only)

选项A：Kroki API（推荐——无需安装，仅支持SVG）

bash

undefined

bash

undefined

Just needs curl (pre-installed on macOS/Linux/Windows Git Bash)

仅需 curl（macOS/Linux/Windows Git Bash 预装）

curl --version


No additional setup. SVG rendered via `https://kroki.io`.

curl --version


无需额外配置。SVG 通过 `https://kroki.io` 渲染。

Option B: Local CLI (required for PNG)

选项B：本地CLI（生成PNG需用此方式）

The CLI uses Firefox (not Chromium). Check and install:

bash

npm install -g excalidraw-brute-export-cli
npx playwright install firefox

macOS patch (one-time, required):

bash

CLI_MAIN=$(npm root -g)/excalidraw-brute-export-cli/src/main.js
sed -i '' 's/keyboard.press("Control+O")/keyboard.press("Meta+O")/' "$CLI_MAIN"
sed -i '' 's/keyboard.press("Control+Shift+E")/keyboard.press("Meta+Shift+E")/' "$CLI_MAIN"

Windows/Linux: No patch needed.

该CLI依赖 Firefox（不支持Chromium）。检查并安装：

bash

npm install -g excalidraw-brute-export-cli
npx playwright install firefox

macOS补丁（一次性，必需）：

bash

CLI_MAIN=$(npm root -g)/excalidraw-brute-export-cli/src/main.js
sed -i '' 's/keyboard.press("Control+O")/keyboard.press("Meta+O")/' "$CLI_MAIN"
sed -i '' 's/keyboard.press("Control+Shift+E")/keyboard.press("Meta+Shift+E")/' "$CLI_MAIN"

Windows/Linux： 无需补丁。

Workflow

工作流程

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 — use Kroki (curl) for SVG; use local CLI for PNG
Plan — identify diagram type, pick a visual pattern, choose color palette
Generate — write
```
.excalidraw
```
JSON file (section-by-section for large diagrams)
Export — run Kroki or CLI command
Report — tell user the output file path

版本检查（仅通知，不自动拉取） —— 每次对话首次使用时执行。通过
```
<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
```
- 与该技能 frontmatter 中的
```
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安装的副本、只读路径、无权限），静默忽略错误并继续执行用户任务，不提及失败情况。
检查依赖 —— 生成SVG用Kroki（curl）；生成PNG用本地CLI
规划 —— 确定图表类型，选择视觉样式，挑选配色方案
生成 —— 编写
```
.excalidraw
```
JSON 文件（大型图表分节编写）
导出 —— 执行Kroki或CLI命令
反馈 —— 告知用户输出文件路径

Design Principles

设计原则

Default style

默认样式

```
roughness: 0
```
— clean, modern look for all technical diagrams (use
```
1
```
only when user requests hand-drawn/casual style)
```
fontFamily: 2
```
(Helvetica) — professional look; use
```
1
```
(Virgil) only for casual/sketch style,
```
3
```
(Cascadia) for code snippets
```
fillStyle: "solid"
```
— default fill

```
roughness: 0
```
—— 所有技术图表采用简洁现代风格（仅当用户要求手绘/非正式风格时设为
```
1
```
）
```
fontFamily: 2
```
（Helvetica）—— 专业风格；非正式/草图风格用
```
1
```
（Virgil），代码片段用
```
3
```
（Cascadia）
```
fillStyle: "solid"
```
—— 默认填充样式

Font size hierarchy

字体大小层级

Level	Size	Use for
Title	28px	Diagram title
Header	24px	Section/group headers
Label	20px	Primary element labels
Description	16px	Secondary text, descriptions
Note	14px	Annotations, fine print

级别	大小	用途
标题	28px	图表标题
页眉	24px	章节/分组标题
标签	20px	主要元素标签
描述	16px	次要文本、说明
注释	14px	注解、小字

Color palette

配色方案

Follow the 60-30-10 rule: 60% whitespace/neutral, 30% primary accent, 10% highlight.

Semantic fill colors (use with

strokeColor

one shade darker):

Category	Fill	Stroke	Use for
Primary / Input	`#dbeafe`	`#1e40af`	Entry points, APIs, user-facing
Success / Data	`#dcfce7`	`#166534`	Data stores, success states
Warning / Decision	`#fef9c3`	`#854d0e`	Decision points, conditions
Error / Critical	`#fee2e2`	`#991b1b`	Errors, alerts, critical paths
External / Storage	`#f3e8ff`	`#6b21a8`	External services, databases, AI/ML
Process / Default	`#e0f2fe`	`#0369a1`	Standard process steps
Trigger / Start	`#fed7aa`	`#c2410c`	Start nodes, triggers, events
Neutral / Container	`#f1f5f9`	`#475569`	Groups, swimlanes, backgrounds

Text colors:

Level	Color
Title	`#1e293b`
Label	`#334155`
Description	`#64748b`

Rule: Do not invent new colors. Pick from this palette.

遵循 60-30-10法则：60%留白/中性色，30%主强调色，10%高亮色。

语义填充色（搭配深一色阶的

strokeColor

）：

类别	填充色	描边色	用途
主要/输入	`#dbeafe`	`#1e40af`	入口点、API、用户交互部分
成功/数据	`#dcfce7`	`#166534`	数据存储、成功状态
警告/决策	`#fef9c3`	`#854d0e`	决策点、条件判断
错误/关键	`#fee2e2`	`#991b1b`	错误、警报、关键路径
外部/存储	`#f3e8ff`	`#6b21a8`	外部服务、数据库、AI/ML
流程/默认	`#e0f2fe`	`#0369a1`	标准流程步骤
触发/起始	`#fed7aa`	`#c2410c`	起始节点、触发器、事件
中性/容器	`#f1f5f9`	`#475569`	分组、泳道、背景

文本颜色：

级别	颜色
标题	`#1e293b`
标签	`#334155`
描述	`#64748b`

规则：禁止自定义颜色，必须从此配色方案中选择。

Arrow semantics

箭头语义

Style	Meaning
Solid ( `strokeStyle: null` )	Primary flow, main path
Dashed ( `"dashed"` )	Response, async, callback
Dotted ( `"dotted"` )	Optional, reference, weak dependency

样式	含义
实线（ `strokeStyle: null` ）	主流程、主要路径
虚线（ `"dashed"` ）	响应、异步、回调
点线（ `"dotted"` ）	可选、参考、弱依赖

Excalidraw JSON Structure

Excalidraw JSON结构

File skeleton

文件骨架

json

{
  "type": "excalidraw",
  "version": 2,
  "source": "claude-code",
  "elements": [],
  "appState": { "viewBackgroundColor": "#ffffff" }
}

json

{
  "type": "excalidraw",
  "version": 2,
  "source": "claude-code",
  "elements": [],
  "appState": { "viewBackgroundColor": "#ffffff" }
}

Element types

元素类型

type	use for
rectangle	boxes, components, modules
ellipse	start/end nodes, databases
diamond	decision points
arrow	directed connections
line	undirected connections
text	standalone labels

type	用途
rectangle	方框、组件、模块
ellipse	起始/结束节点、数据库
diamond	决策点
arrow	有向连接
line	无向连接
text	独立标签

Element sizing

元素尺寸

Calculate element width from label text to prevent truncation:

Latin text:  width = max(160, charCount * 9)
CJK text:   width = max(160, charCount * 18)
Mixed text:  estimate each character individually, sum up

Height: use

for single-line labels, add

per additional line.

根据标签文本计算元素宽度，避免截断：

拉丁文本:  width = max(160, 字符数 * 9)
CJK文本:   width = max(160, 字符数 * 18)
混合文本:  逐个字符估算，求和

高度：单行标签用

，每增加一行加

。

Required properties (all elements)

所有元素必需属性

json

{
  "id": "auth_service",
  "type": "rectangle",
  "x": 100, "y": 100,
  "width": 160, "height": 60,
  "angle": 0,
  "strokeColor": "#1e40af",
  "backgroundColor": "#dbeafe",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "roughness": 0,
  "opacity": 100,
  "seed": 100001,
  "boundElements": [
    { "id": "arrow_to_db", "type": "arrow" },
    { "id": "label_auth", "type": "text" }
  ]
}

Use descriptive string IDs (e.g.,

"api_gateway"

"arrow_gw_to_auth"

) instead of random strings.

Give each element a unique

seed

(integer). Namespace by section: 100xxx, 200xxx, 300xxx.

json

{
  "id": "auth_service",
  "type": "rectangle",
  "x": 100, "y": 100,
  "width": 160, "height": 60,
  "angle": 0,
  "strokeColor": "#1e40af",
  "backgroundColor": "#dbeafe",
  "fillStyle": "solid",
  "strokeWidth": 2,
  "roughness": 0,
  "opacity": 100,
  "seed": 100001,
  "boundElements": [
    { "id": "arrow_to_db", "type": "arrow" },
    { "id": "label_auth", "type": "text" }
  ]
}

使用 描述性字符串ID（如

"api_gateway"

、

"arrow_gw_to_auth"

）而非随机字符串。

为每个元素分配唯一的

seed

（整数）。按章节命名空间：100xxx、200xxx、300xxx。

JSON field rules

JSON字段规则

```
boundElements
```
: use
```
null
```
when empty, never
```
[]
```
```
updated
```
: always use
```
1
```
, never timestamps
Do NOT include:
```
frameId
```
,
```
index
```
,
```
versionNonce
```
,
```
rawText
```
```
points
```
in arrows: always start at
```
[0, 0]
```
```
seed
```
: must be a positive integer, unique per element

```
boundElements
```
：为空时用
```
null
```
，禁止用
```
[]
```
```
updated
```
：始终设为
```
1
```
，禁止使用时间戳
禁止包含：
```
frameId
```
、
```
index
```
、
```
versionNonce
```
、
```
rawText
```
箭头的
```
points
```
：始终以
```
[0, 0]
```
开头
```
seed
```
：必须为正整数，每个元素唯一

Text inside shapes (contained text)

形状内文本（包含文本）

When text belongs inside a shape, bind them bidirectionally:

json

{
  "id": "label_auth",
  "type": "text",
  "text": "Auth Service",
  "fontSize": 20,
  "fontFamily": 2,
  "textAlign": "center",
  "verticalAlign": "middle",
  "strokeColor": "#1e293b",
  "containerId": "auth_service"
}

CRITICAL: Text
strokeColor
is the text color. Always set it explicitly to a dark color from the text color palette. Never omit it — omitting

strokeColor

on text can cause invisible text that blends with the shape background.

The parent shape must list the text in its

boundElements

json

"boundElements": [{ "id": "label_auth", "type": "text" }]

当文本属于某个形状内部时，需双向绑定：

json

{
  "id": "label_auth",
  "type": "text",
  "text": "Auth Service",
  "fontSize": 20,
  "fontFamily": 2,
  "textAlign": "center",
  "verticalAlign": "middle",
  "strokeColor": "#1e293b",
  "containerId": "auth_service"
}

关键注意：文本的
strokeColor
即为文本颜色，必须显式设置为文本配色方案中的深色。禁止省略——省略文本的

strokeColor

可能导致文本与形状背景色融合而不可见。

父形状必须在其

boundElements

中列出该文本：

json

"boundElements": [{ "id": "label_auth", "type": "text" }]

Arrow binding (bidirectional)

箭头绑定（双向）

Arrows must bind to shapes, and shapes must reference bound arrows:

json

{
  "id": "arrow_gw_to_auth",
  "type": "arrow",
  "points": [[0, 0], [200, 0]],
  "startBinding": { "elementId": "api_gateway", "gap": 5, "focus": 0 },
  "endBinding": { "elementId": "auth_service", "gap": 5, "focus": 0 }
}

Both

api_gateway

and

auth_service

must include in their

boundElements

json

"boundElements": [{ "id": "arrow_gw_to_auth", "type": "arrow" }]

箭头必须绑定到形状，形状也必须引用绑定的箭头：

json

{
  "id": "arrow_gw_to_auth",
  "type": "arrow",
  "points": [[0, 0], [200, 0]],
  "startBinding": { "elementId": "api_gateway", "gap": 5, "focus": 0 },
  "endBinding": { "elementId": "auth_service", "gap": 5, "focus": 0 }
}

api_gateway

和

auth_service

都必须在其

boundElements

中包含：

json

"boundElements": [{ "id": "arrow_gw_to_auth", "type": "arrow" }]

Arrow routing

箭头路由

L-shaped (elbow) arrows — orthogonal routing with 3+ points:

json

"points": [[0, 0], [100, 0], [100, 150]]

Elbowed arrows — automatic right-angle routing:

json

{
  "type": "arrow",
  "points": [[0, 0], [0, -50], [200, -50], [200, 0]],
  "elbowed": true
}

Curved arrows — smooth routing with waypoints:

json

{
  "type": "arrow",
  "points": [[0, 0], [50, -40], [200, 0]],
  "roundness": { "type": 2 }
}

L形（弯头）箭头 —— 正交路由，包含3个及以上点：

json

"points": [[0, 0], [100, 0], [100, 150]]

自动弯头箭头 —— 自动直角路由：

json

{
  "type": "arrow",
  "points": [[0, 0], [0, -50], [200, -50], [200, 0]],
  "elbowed": true
}

弯曲箭头 —— 通过路径点实现平滑路由：

json

{
  "type": "arrow",
  "points": [[0, 0], [50, -40], [200, 0]],
  "roundness": { "type": 2 }
}

Grouping

分组

Related elements share

groupIds

. Nested groups list IDs innermost-first:

json

"groupIds": ["inner_group", "outer_group"]

Diagram Patterns

图表模式

Choose the right visual pattern for each diagram type.

根据图表类型选择合适的视觉模式。

Spacing Reference

间距参考

Scenario	Spacing
Labeled arrow gap (between shapes)	150–200px
Unlabeled arrow gap	100–120px
Column spacing (labeled arrows)	400px (220px box + 180px gap)
Column spacing (unlabeled arrows)	340px (220px box + 120px gap)
Row spacing	280–350px (150px box + 130–200px gap)
Zone/container padding	50–60px around children
Zone/container opacity	25–40
Minimum gap between any elements	40px

场景	间距
带标签箭头间距（形状间）	150–200px
无标签箭头间距	100–120px
列间距（带标签箭头）	400px（220px方框 + 180px间距）
列间距（无标签箭头）	340px（220px方框 + 120px间距）
行间距	280–350px（150px方框 + 130–200px间距）
区域/容器内边距	子元素周围50–60px
区域/容器透明度	25–40
元素间最小间距	40px

Flowchart (LR or TB)

流程图（LR或TB方向）

Ellipse for start/end, diamond for decisions, rectangle for process
200px horizontal spacing, 150px vertical spacing
Decision branches: "Yes" goes forward, "No" goes down
3–10 steps (max 15)

椭圆表示起始/结束，菱形表示决策，矩形表示流程
水平间距200px，垂直间距150px
决策分支：「是」向前，「否」向下
3–10个步骤（最多15个）

Architecture / System Diagram

架构/系统图

Column spacing per table above; use labeled arrow spacing when connections have labels
Group related services in dashed
```
Neutral
```
containers (opacity: 30, padding: 50px)
Gateway/entry at left or top, databases at right or bottom
3–8 entities (max 12)

列间距参考上表；连接带标签时使用带标签箭头间距
用虚线「中性色」容器（透明度30，内边距50px）分组相关服务
网关/入口位于左侧或顶部，数据库位于右侧或底部
3–8个实体（最多12个）

Sequence Diagram

时序图

200px between participants (rectangles at top)
Vertical lifelines as dashed lines
Horizontal arrows for messages, 60px vertical spacing
Solid arrow = request, dashed arrow = response

参与者（顶部矩形）间距200px
垂直生命线为虚线
水平箭头表示消息，垂直间距60px
实线箭头=请求，虚线箭头=响应

Mind Map

思维导图

Central node: largest (200x100),
```
Trigger
```
color
Level 1: 150x70,
```
Primary
```
color, radial around center
Level 2: 120x50,
```
Process
```
color
Level 3: 90x40,
```
Neutral
```
color
Use lines (not arrows) for connections
4–6 branches (max 8), 2–4 sub-topics per branch

中心节点：最大（200x100），「触发」配色
一级节点：150x70，「主要」配色，围绕中心呈放射状
二级节点：120x50，「流程」配色
三级节点：90x40，「中性」配色
使用线条（非箭头）连接
4–6个分支（最多8个），每个分支2–4个子主题

Swimlane

泳道图

Large transparent rectangles (
```
Neutral
```
fill,
```
"dashed"
```
stroke, opacity: 30) as lane boundaries
Lane label as free-standing text at top-left of lane (not bound to rectangle), 28px font
Elements flow left-to-right within lanes
Arrows cross lanes for handoffs

大型透明矩形（「中性」填充，
```
"dashed"
```
描边，透明度30）作为泳道边界
泳道标签为独立文本，位于泳道左上角（不绑定到矩形），字体28px
元素在泳道内从左到右流动
箭头跨泳道表示交接

Section-by-Section Construction

分节构建

For diagrams with 10+ elements, do NOT generate the entire JSON at once. Build in sections:

Plan all sections first — list element IDs, positions, and cross-section bindings
Write section 1 — create the file with initial elements
Append section 2 — read the file, add new elements to the
```
elements
```
array
Repeat — continue until all sections are done
Final pass — verify all
```
boundElements
```
and
```
startBinding
```
/
```
endBinding
```
references are consistent

Namespace element seeds by section (100xxx, 200xxx, 300xxx) to avoid collisions.

对于包含10个及以上元素的图表，禁止一次性生成完整JSON，需分节构建：

先规划所有章节 —— 列出元素ID、位置和跨章节绑定关系
编写第1节 —— 创建包含初始元素的文件
追加第2节 —— 读取文件，将新元素添加到
```
elements
```
数组
重复 —— 直到所有章节完成
最终检查 —— 验证所有
```
boundElements
```
和
```
startBinding
```
/
```
endBinding
```
引用一致

按章节对元素seed进行命名空间划分（100xxx、200xxx、300xxx），避免冲突。

Export

导出

Option A: Kroki API (SVG only — zero install)

选项A：Kroki API（仅SVG——无需安装）

bash

undefined

bash

undefined

SVG via Kroki API

通过Kroki API生成SVG

curl -s -X POST https://kroki.io/excalidraw/svg
-H "Content-Type: application/json"
--data-binary "@diagram.excalidraw"
-o diagram.svg

Via local Kroki Docker (offline)

通过本地Kroki Docker（离线）生成

curl -s -X POST http://localhost:8000/excalidraw/svg
-H "Content-Type: application/json"
--data-binary "@diagram.excalidraw"
-o diagram.svg

undefined

curl -s -X POST http://localhost:8000/excalidraw/svg
-H "Content-Type: application/json"
--data-binary "@diagram.excalidraw"
-o diagram.svg

undefined

Option B: Local CLI (PNG + SVG)

选项B：本地CLI（PNG + SVG）

bash

undefined

bash

undefined

PNG at 2x scale (recommended)

2倍缩放生成PNG（推荐）

excalidraw-brute-export-cli -i diagram.excalidraw -o diagram.png -f png -s 2

PNG at 1x scale

1倍缩放生成PNG

excalidraw-brute-export-cli -i diagram.excalidraw -o diagram.png -f png -s 1

SVG

生成SVG

excalidraw-brute-export-cli -i diagram.excalidraw -o diagram.svg -f svg -s 1


**Required flags:** `-f` (format: `png` or `svg`) and `-s` (scale: `1`, `2`, or `3`).

excalidraw-brute-export-cli -i diagram.excalidraw -o diagram.svg -f svg -s 1


**必需参数：** `-f`（格式：`png`或`svg`）和 `-s`（缩放比例：`1`、`2`或`3`）。

Anti-Patterns

反模式

Never put
text
on large background/zone rectangles. Excalidraw centers text in the middle of the shape, overlapping contained elements. Instead, use a free-standing

text

element positioned at the top of the zone.

Avoid cross-zone arrows. Long diagonal arrows create visual spaghetti. Route arrows within zones or along zone edges. If a cross-zone connection is unavoidable, route it along the perimeter.

Use arrow labels sparingly. Labels placed at the arrow midpoint overlap on short arrows. Keep labels to ≤12 characters and ensure ≥120px clear space between connected shapes. Omit labels when the connection meaning is obvious from context.

Don't use filled backgrounds on containers that hold other elements. Use

opacity: 30

(or 25-40 range) for zone/container rectangles so contained elements remain visible.

Always set explicit
strokeColor
on text elements. Text

strokeColor

is the rendered text color. If omitted, text may inherit the parent shape's background color and become invisible. Use

#1e293b

(title),

#334155

(label), or

#64748b

(description) from the text color palette.

禁止在大型背景/区域矩形上添加
text
。Excalidraw会将文本居中于形状，覆盖内部元素。应使用独立

text

元素放置在区域顶部。

避免跨区域箭头。长对角线箭头会造成视觉混乱。箭头应在区域内路由或沿区域边缘路由。若必须跨区域连接，沿周边路由。

谨慎使用箭头标签。短箭头中点的标签会重叠。标签长度≤12字符，且连接形状间需≥120px空白。当连接含义从上下文可明确时，省略标签。

禁止在包含其他元素的容器上使用实心背景。区域/容器矩形使用

opacity: 30

（或25-40范围），确保内部元素可见。

始终为文本元素显式设置
strokeColor
。文本的

strokeColor

即为渲染的文本颜色。若省略，文本可能继承父形状的背景色而不可见。使用文本配色方案中的

#1e293b

（标题）、

#334155

（标签）或

#64748b

（描述）。

Common Mistakes

常见错误

Mistake	Fix
Kroki returns error	Ensure file is valid JSON with `"type": "excalidraw"` and `"elements"` array
Kroki only outputs SVG	Use local CLI ( `excalidraw-brute-export-cli` ) for PNG
Export fails with "Missing required flag"	Always pass `-f png` and `-s 2`
Export fails with "Executable doesn't exist"	Run `npx playwright install firefox`
macOS: timeout waiting for file chooser	Apply the macOS Meta patch above
Arrow `points` not relative to origin	`points` always start at `[0,0]`
Missing `id` on elements	Use descriptive string IDs per element
Overlapping elements	Use spacing reference table; minimum 40px gap
Arrows not interactive in excalidraw.com	Add `boundElements` to shapes referencing all bound arrows/text
Text not centered in shape	Set `containerId` on text AND add text to shape's `boundElements`
All text same size	Use font size hierarchy: 28 → 24 → 20 → 16 → 14
Diagram looks monotone	Apply semantic colors from the palette, follow 60-30-10 rule
Text invisible / same color as background	Always set `strokeColor` on text elements to a dark color ( `#1e293b` , `#334155` , or `#64748b` )
Text overlaps inside zone/container	Don't bind text to zone rectangles; use free-standing text at top
Text truncated in shapes	Use width formula: `max(160, charCount * 9)` , double for CJK
`boundElements: []` causes issues	Use `null` for empty boundElements, never `[]`

错误	修复方案
Kroki返回错误	确保文件是包含 `"type": "excalidraw"` 和 `"elements"` 数组的有效JSON
Kroki仅输出SVG	使用本地CLI（ `excalidraw-brute-export-cli` ）生成PNG
导出失败提示「Missing required flag」	始终传递 `-f png` 和 `-s 2` 参数
导出失败提示「Executable doesn't exist」	执行 `npx playwright install firefox`
macOS：等待文件选择器超时	应用上述macOS Meta补丁
箭头 `points` 未相对原点	`points` 始终以 `[0,0]` 开头
元素缺少 `id`	为每个元素使用描述性字符串ID
元素重叠	使用间距参考表；最小间距40px
在excalidraw.com中箭头无交互性	为形状添加引用所有绑定箭头/文本的 `boundElements`
文本未在形状中居中	为文本设置 `containerId` 并将文本添加到形状的 `boundElements`
所有文本大小相同	使用字体大小层级：28 → 24 → 20 → 16 → 14
图表单调乏味	应用配色方案中的语义颜色，遵循60-30-10法则
文本不可见/与背景色相同	始终为文本元素设置深色 `strokeColor` （ `#1e293b` 、 `#334155` 或 `#64748b` ）
文本在区域/容器内重叠	不要将文本绑定到区域矩形；使用顶部的独立文本
文本在形状中被截断	使用宽度公式： `max(160, 字符数 * 9)` ，CJK文本翻倍
`boundElements: []` 导致问题	为空时用 `null` ，禁止用 `[]`