Back to Details

excalidraw-design-guide

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Excalidraw Diagram Design Guide

Excalidraw图表设计指南

Color Palette

调色板

Stroke Colors (borders & text)

描边颜色（边框与文本）

NameHexUse for
Black#1e1e1eDefault text & borders
Red#e03131Errors, warnings, critical
Green#2f9e44Success, approved, healthy
Blue#1971c2Primary actions, links
Purple#9c36b5Services, middleware
Orange#e8590cAsync, queues, events
Cyan#0c8599Data stores, databases
Gray#868e96Annotations, secondary
名称十六进制码适用场景
黑色#1e1e1e默认文本与边框
红色#e03131错误、警告、关键内容
绿色#2f9e44成功、已批准、健康状态
蓝色#1971c2主要操作、链接
紫色#9c36b5服务、中间件
橙色#e8590c异步流程、队列、事件
青色#0c8599数据存储、数据库
灰色#868e96注释、次要内容

Fill Colors (backgroundColor — pastel)

填充颜色（背景色 — 马卡龙色调）

NameHexPairs with stroke
Light Red#ffc9c9#e03131
Light Green#b2f2bb#2f9e44
Light Blue#a5d8ff#1971c2
Light Purple#eebefa#9c36b5
Light Orange#ffd8a8#e8590c
Light Cyan#99e9f2#0c8599
Light Gray#e9ecef#868e96
White#ffffff#1e1e1e
名称十六进制码搭配描边色
浅红色#ffc9c9#e03131
浅绿色#b2f2bb#2f9e44
浅蓝色#a5d8ff#1971c2
浅紫色#eebefa#9c36b5
浅橙色#ffd8a8#e8590c
浅青色#99e9f2#0c8599
浅灰色#e9ecef#868e96
白色#ffffff#1e1e1e

Sizing Rules

尺寸规则

  • Minimum shape: width >= 120px, height >= 60px
  • Shape width formula: 
    max(160, labelTextLength * 9)
    — prevents text truncation
  • Shape height: 60px single-line, 80px two-line, 100px three-line labels
  • Font sizes: body text >= 16, titles/headers >= 20, small labels >= 14
  • Padding: at least 20px inside shapes for text breathing room
  • Arrow length: minimum 80px between connected shapes
  • Consistent sizing: same-role shapes = same dimensions
  • 最小形状尺寸：宽度 ≥ 120px，高度 ≥ 60px
  • 形状宽度计算公式：
    max(160, labelTextLength * 9)
    — 防止文本截断
  • 形状高度：单行文本60px，两行文本80px，三行文本100px
  • 字体大小：正文文本≥16px，标题/表头≥20px，小标签≥14px
  • 内边距：形状内部至少保留20px的文本留白
  • 箭头长度：相连形状之间的最小距离为80px
  • 尺寸一致性：同类型角色的形状需使用相同尺寸

Layout Patterns

布局模式

  • Grid snap: align to 20px grid for clean layouts
  • Spacing: 40–80px gap between adjacent shapes
  • Flow direction: top-to-bottom (vertical) or left-to-right (horizontal)
  • Hierarchy: important nodes larger or higher; left-to-right = temporal order
  • Grouping: cluster related elements; use background rectangles as zones
  • Tier layout:
    • Tier 1 (y=50–130): Client apps / entry points
    • Tier 2 (y=200–280): Gateway / edge layer
    • Tier 3 (y=350–440): Services (spread wide: 160–200px apart)
    • Tier 4 (y=510–590): Data stores
    • Side panels: x < 0 or x > mainDiagramRight + 80
  • 网格对齐：对齐到20px网格以实现整洁布局
  • 间距设置：相邻形状之间的间距为40–80px
  • 流向：从上到下（垂直）或从左到右（水平）
  • 层级结构：重要节点更大或位置更靠前；从左到右代表时间顺序
  • 分组：将相关元素聚类；使用背景矩形作为分区
  • 分层布局:
    • 第一层（y=50–130）：客户端应用 / 入口点
    • 第二层（y=200–280）：网关 / 边缘层
    • 第三层（y=350–440）：服务（横向分散：间距160–200px）
    • 第四层（y=510–590）：数据存储
    • 侧边面板：x < 0 或 x > 主图表右侧边缘 + 80px

Arrow Best Practices

箭头最佳实践

Binding (always use element IDs, not raw coordinates)

绑定方式（始终使用元素ID，而非原始坐标）

json
{"type": "arrow", "x": 0, "y": 0, "start": {"id": "svc-a"}, "end": {"id": "svc-b"}}
Server auto-routes arrows to element edges using precise geometry.
json
{"type": "arrow", "x": 0, "y": 0, "start": {"id": "svc-a"}, "end": {"id": "svc-b"}}
服务器会通过精确几何计算自动将箭头路由到元素边缘。

Line styles

线条样式

  • Solid: synchronous calls, direct dependencies
  • Dashed (
    "strokeStyle": "dashed"
    ): async flows, optional paths, events
  • Dotted (
    "strokeStyle": "dotted"
    ): weak dependencies, annotations
  • 实线：同步调用、直接依赖
  • 虚线 (
    "strokeStyle": "dashed"
    )：异步流程、可选路径、事件
  • 点线 (
    "strokeStyle": "dotted"
    )：弱依赖、注释

Arrowheads

箭头头部

  • "endArrowhead": "arrow"
    — default directed flow
  • "endArrowhead": "dot"
    — data stores
  • "endArrowhead": null
    — plain line (undirected)
  • "endArrowhead": "arrow"
    — 默认的有向流
  • "endArrowhead": "dot"
    — 数据存储
  • "endArrowhead": null
    — 普通线条（无方向）

Labels on arrows

箭头标签

Use 
"label": {"text": "HTTP"}
— keep to 1–2 words. Long labels overlap shapes.
使用 
"label": {"text": "HTTP"}
— 标签控制在1–2个单词内，过长标签会导致形状重叠。

Routing complex arrows (avoid crossings)

复杂箭头路由（避免交叉）

Curved arrow (arc over elements):
json
{
  "type": "arrow", "x": 100, "y": 100,
  "points": [[0,0],[50,-40],[200,0]],
  "roundness": {"type": 2},
  "strokeColor": "#1971c2"
}
Elbowed arrow (L-shape, right-angle routing):
json
{
  "type": "arrow", "x": 100, "y": 100,
  "points": [[0,0],[0,-50],[200,-50],[200,0]],
  "elbowed": true
}
弧形箭头（从元素上方绕过）：
json
{
  "type": "arrow", "x": 100, "y": 100,
  "points": [[0,0],[50,-40],[200,0]],
  "roundness": {"type": 2},
  "strokeColor": "#1971c2"
}
直角箭头（L形，直角路由）：
json
{
  "type": "arrow", "x": 100, "y": 100,
  "points": [[0,0],[0,-50],[200,-50],[200,0]],
  "elbowed": true
}

Diagram Type Templates

图表类型模板

Architecture Diagram

架构图

json
{
  "elements": [
    {
      "id": "zone-backend",
      "type": "rectangle",
      "x": 40, "y": 40, "width": 600, "height": 400,
      "backgroundColor": "#e9ecef", "strokeColor": "#868e96",
      "opacity": 40,
      "label": {"text": "Backend", "fontSize": 20}
    },
    {
      "id": "api-gw",
      "type": "rectangle",
      "x": 80, "y": 100, "width": 180, "height": 70,
      "strokeColor": "#9c36b5", "backgroundColor": "#eebefa",
      "label": {"text": "API Gateway"}
    },
    {
      "id": "auth-svc",
      "type": "rectangle",
      "x": 80, "y": 240, "width": 180, "height": 70,
      "strokeColor": "#1971c2", "backgroundColor": "#a5d8ff",
      "label": {"text": "Auth Service"}
    },
    {
      "id": "db",
      "type": "rectangle",
      "x": 80, "y": 380, "width": 180, "height": 70,
      "strokeColor": "#0c8599", "backgroundColor": "#99e9f2",
      "label": {"text": "Postgres"}
    },
    {"type":"arrow","x":0,"y":0,"start":{"id":"api-gw"},"end":{"id":"auth-svc"},"label":{"text":"JWT verify"}},
    {"type":"arrow","x":0,"y":0,"start":{"id":"auth-svc"},"end":{"id":"db"},"label":{"text":"SQL"},"strokeStyle":"dashed"}
  ]
}
json
{
  "elements": [
    {
      "id": "zone-backend",
      "type": "rectangle",
      "x": 40, "y": 40, "width": 600, "height": 400,
      "backgroundColor": "#e9ecef", "strokeColor": "#868e96",
      "opacity": 40,
      "label": {"text": "Backend", "fontSize": 20}
    },
    {
      "id": "api-gw",
      "type": "rectangle",
      "x": 80, "y": 100, "width": 180, "height": 70,
      "strokeColor": "#9c36b5", "backgroundColor": "#eebefa",
      "label": {"text": "API Gateway"}
    },
    {
      "id": "auth-svc",
      "type": "rectangle",
      "x": 80, "y": 240, "width": 180, "height": 70,
      "strokeColor": "#1971c2", "backgroundColor": "#a5d8ff",
      "label": {"text": "Auth Service"}
    },
    {
      "id": "db",
      "type": "rectangle",
      "x": 80, "y": 380, "width": 180, "height": 70,
      "strokeColor": "#0c8599", "backgroundColor": "#99e9f2",
      "label": {"text": "Postgres"}
    },
    {"type":"arrow","x":0,"y":0,"start":{"id":"api-gw"},"end":{"id":"auth-svc"},"label":{"text":"JWT verify"}},
    {"type":"arrow","x":0,"y":0,"start":{"id":"auth-svc"},"end":{"id":"db"},"label":{"text":"SQL"},"strokeStyle":"dashed"}
  ]
}

Flowchart

流程图

json
{
  "elements": [
    {"id":"start","type":"ellipse","x":160,"y":40,"width":120,"height":60,
     "strokeColor":"#2f9e44","backgroundColor":"#b2f2bb","label":{"text":"Start"}},
    {"id":"step1","type":"rectangle","x":140,"y":160,"width":160,"height":60,
     "strokeColor":"#1971c2","backgroundColor":"#a5d8ff","label":{"text":"Validate Input"}},
    {"id":"decide","type":"diamond","x":140,"y":280,"width":160,"height":80,
     "strokeColor":"#e8590c","backgroundColor":"#ffd8a8","label":{"text":"Valid?"}},
    {"id":"end-ok","type":"ellipse","x":340,"y":290,"width":100,"height":60,
     "strokeColor":"#2f9e44","backgroundColor":"#b2f2bb","label":{"text":"Success"}},
    {"id":"end-err","type":"ellipse","x":0,"y":290,"width":100,"height":60,
     "strokeColor":"#e03131","backgroundColor":"#ffc9c9","label":{"text":"Error"}},
    {"type":"arrow","x":0,"y":0,"start":{"id":"start"},"end":{"id":"step1"}},
    {"type":"arrow","x":0,"y":0,"start":{"id":"step1"},"end":{"id":"decide"}},
    {"type":"arrow","x":0,"y":0,"start":{"id":"decide"},"end":{"id":"end-ok"},"label":{"text":"Yes"}},
    {"type":"arrow","x":0,"y":0,"start":{"id":"decide"},"end":{"id":"end-err"},"label":{"text":"No"}}
  ]
}
json
{
  "elements": [
    {"id":"start","type":"ellipse","x":160,"y":40,"width":120,"height":60,
     "strokeColor":"#2f9e44","backgroundColor":"#b2f2bb","label":{"text":"Start"}},
    {"id":"step1","type":"rectangle","x":140,"y":160,"width":160,"height":60,
     "strokeColor":"#1971c2","backgroundColor":"#a5d8ff","label":{"text":"Validate Input"}},
    {"id":"decide","type":"diamond","x":140,"y":280,"width":160,"height":80,
     "strokeColor":"#e8590c","backgroundColor":"#ffd8a8","label":{"text":"Valid?"}},
    {"id":"end-ok","type":"ellipse","x":340,"y":290,"width":100,"height":60,
     "strokeColor":"#2f9e44","backgroundColor":"#b2f2bb","label":{"text":"Success"}},
    {"id":"end-err","type":"ellipse","x":0,"y":290,"width":100,"height":60,
     "strokeColor":"#e03131","backgroundColor":"#ffc9c9","label":{"text":"Error"}},
    {"type":"arrow","x":0,"y":0,"start":{"id":"start"},"end":{"id":"step1"}},
    {"type":"arrow","x":0,"y":0,"start":{"id":"step1"},"end":{"id":"decide"}},
    {"type":"arrow","x":0,"y":0,"start":{"id":"decide"},"end":{"id":"end-ok"},"label":{"text":"Yes"}},
    {"type":"arrow","x":0,"y":0,"start":{"id":"decide"},"end":{"id":"end-err"},"label":{"text":"No"}}
  ]
}

ER Diagram

ER图

json
{
  "elements": [
    {"id":"users","type":"rectangle","x":40,"y":100,"width":180,"height":120,
     "strokeColor":"#1971c2","backgroundColor":"#a5d8ff",
     "label":{"text":"users\n─────\nid: UUID\nname: text\nemail: text"}},
    {"id":"orders","type":"rectangle","x":300,"y":100,"width":180,"height":120,
     "strokeColor":"#9c36b5","backgroundColor":"#eebefa",
     "label":{"text":"orders\n──────\nid: UUID\nuser_id: UUID\ntotal: decimal"}},
    {"type":"arrow","x":0,"y":0,"start":{"id":"users"},"end":{"id":"orders"},
     "label":{"text":"1..N"},"endArrowhead":"arrow","startArrowhead":"dot"}
  ]
}
json
{
  "elements": [
    {"id":"users","type":"rectangle","x":40,"y":100,"width":180,"height":120,
     "strokeColor":"#1971c2","backgroundColor":"#a5d8ff",
     "label":{"text":"users\n─────\nid: UUID\nname: text\nemail: text"}},
    {"id":"orders","type":"rectangle","x":300,"y":100,"width":180,"height":120,
     "strokeColor":"#9c36b5","backgroundColor":"#eebefa",
     "label":{"text":"orders\n──────\nid: UUID\nuser_id: UUID\ntotal: decimal"}},
    {"type":"arrow","x":0,"y":0,"start":{"id":"users"},"end":{"id":"orders"},
     "label":{"text":"1..N"},"endArrowhead":"arrow","startArrowhead":"dot"}
  ]
}

Anti-Patterns to Avoid

需避免的反模式

  1. Overlapping elements — always leave gaps; use 
    excalidraw distribute
  2. Cramped spacing — minimum 40px between shapes; 60px between diagram tiers
  3. Tiny fonts — never below 14px; prefer 16+ for readability
  4. Raw arrow coordinates — always use 
    start
    /
    end
    binding to connect to shapes
  5. Too many colors — limit to 3–4 fill colors per diagram
  6. Inconsistent sizes — same-role shapes should have identical width/height
  7. No labels — every shape and meaningful arrow needs descriptive text
  8. Flat layouts — use background zones/groups to show hierarchy
  9. Side panels overlapping main diagram — place at x < 0 or x > mainRight + 80
  10. Unchecked arrow crossings — route with waypoints if arrows would cross elements
  1. 元素重叠 — 务必保留间距；使用
    excalidraw distribute
    工具
  2. 间距过窄 — 形状之间最小间距为40px；图表分层之间最小间距为60px
  3. 字体过小 — 字体大小不能低于14px；优先使用16px以上以保证可读性
  4. 箭头使用原始坐标 — 始终使用
    start
    /
    end
    绑定来连接形状
  5. 颜色过多 — 每张图表的填充颜色限制在3–4种
  6. 尺寸不一致 — 同类型角色的形状应具有相同的宽高
  7. 缺少标签 — 每个形状和有意义的箭头都需要描述性文本
  8. 扁平化布局 — 使用背景分区/分组来展示层级结构
  9. 侧边面板与主图表重叠 — 放置在x < 0 或 x > 主图表右侧边缘 + 80px的位置
  10. 未处理箭头交叉 — 如果箭头会穿过元素，使用路径点进行路由

Pre-Drawing Checklist

绘图前检查清单

Before writing any JSON:
  • Plan coordinate grid on paper (tiers, x-positions, spacing)
  • Calculate shape widths: 
    max(160, textLength * 9)
  • Assign IDs to all shapes that arrows will reference
  • Choose 2–3 fill colors for semantic grouping
  • Decide flow direction (vertical or horizontal)
  • Run 
    excalidraw guide
    for quick color reference
在编写任何JSON之前：
  • 在纸上规划坐标网格（分层、x轴位置、间距）
  • 计算形状宽度：
    max(160, textLength * 9)
  • 为所有需要被箭头引用的形状分配ID
  • 选择2–3种填充颜色进行语义分组
  • 确定流向（垂直或水平）
  • 运行
    excalidraw guide
    快速查看颜色参考