drawnix 白板 JSON 生成

把一段需求（或一张参考图）转换成一个可直接导入、并且导入后仍能继续编辑的 drawnix 白板 JSON。

核心目标不是「画出一张图」，而是「画出一张别人能接着改的图」。判断标准只有一条：

用户能否在编辑器里单独选中、单独修改每一段文字、每一个框、每一条线？

如果做不到，即使视觉上完全正确，也不是合格产出。

交付形态

开始之前

1. 读完本文件。
2. 判断这是哪种任务，读对应文档：

3. 只输出一个 JSON 对象作为正文，不加注释、不加尾逗号、不加 Markdown 围栏（除非明确要求解释）。

一、基本契约

1. 顶层必须是 cells 数组。

2. 每个节点/边有唯一字符串 id。边通过 source.cell / target.cell 引用节点 id，不引用节点对象。

3. 节点必须有 shape、position、size。只使用已注册的 shape 值，不要自创名称。

4. 颜色统一用 #RRGGBB；透明度用 fillOpacity / strokeOpacity；虚线用 strokeDasharray。

5. 不要写 UI 相关字段（view、tools、attrs.selection、attrs.hover、attrs.collapse 等）。

6. 多行文字用 attrs.label.html（如 <div>第一行</div><div>第二行</div>），不要依赖 \n。

7. 手动尺寸标记：

   • shape 以 shape- 开头的图形 → data.manualResized: true
   • text-node → data.textManualResized: true
   • topic / sticky-node / table-node / image-node / pen-stroke / section / group / edge → 两个都不写

   字段写在 data 里，不是 attrs。已有 data 时只合并，不覆盖。

最小可用示例：

{
  "cells": [
    {
      "id": "n1",
      "shape": "shape-rounded-rect",
      "position": { "x": 100, "y": 100 },
      "size": { "width": 120, "height": 80 },
      "attrs": { "label": { "text": "开始" } }
    }
  ]
}

shape-* 的默认背景、边框、文字颜色会由形状配置补齐，不需要手写样式。

二、字号规则

只允许 12 / 14 / 16 / 18 / 20 及更大的标题字号。禁止 9 / 10 / 11 / 13 / 15 / 17 / 19。

为什么要卡死：13 这类值通常是「14 略大、12 略小」时随手写的，结果同一张图里出现 12/13/14 三种接近却不等比的字号，视觉上参差。要么 14，要么 12，不要中间态。

配套约束：

• 调字号后若节点宽度不足，必须同步加宽 size.width 或拆分文本，不能让文字溢出或被挤压换行。
• 表格类节点还要同步更新 tableStyle.fontSize。
• 12px 的文字面积占比不要超过约 20%，内容多时优先放大画布或拆分布局，不要靠缩字号硬塞。
• 校验必须是白名单，不能写成 fontSize < 12 —— 下限判断会放过 13/15/17。

三、节点类型

3.1 特殊节点

3.2 常用 shape-*

常用默认尺寸（生成时应显式写 size，不要依赖默认值）：

3.3 四个形状陷阱（都会造成「看不出来」的错误）

这几条的共同特点：从 JSON 字段上看完全正常，但渲染出来不对。只能靠形状名称的正确用法规避。

陷阱 1：全圆角矩形不能用 rx = 高度/2 冒充

rx 是普通圆角矩形的参数，渲染时会对它做上限裁剪。一旦裁剪，两端就不再是半圆， 退回普通圆角矩形 —— 而 JSON 里 rx 的值确实等于 h/2，看不出问题。

// ✗ 错：看着对，渲染出来不是胶囊
{ "shape": "shape-rounded-rect", "attrs": { "body": { "rx": 17, "ry": 17 } } }

// ✓ 对：形状类型本身保证两端是完整半圆
{ "shape": "shape-full-rounded-rect" }

判据：检查 shape 字段必须是 shape-full-rounded-rect。

陷阱 2：六边形的朝向不可控

shape-hexagon 的朝向（平顶 / 尖顶）和斜边内缩量由渲染实现决定，JSON 里没有参数可调。

需要精确朝向时，用 6 顶点闭合 pen-stroke 自己画：

k = w * 0.25
x0, x1, y0, y1 = cx - w/2, cx + w/2, cy - h/2, cy + h/2
pts = [(x0+k, y0), (x1-k, y0), (x1, cy), (x1-k, y1), (x0+k, y1), (x0, cy)]

并断言「最上面一行有两个不同的 x」（存在水平边）：

top_y = min(p["y"] for p in pts)
assert len([p for p in pts if abs(p["y"] - top_y) < 0.01]) == 2, "尖顶六边形"

陷阱 3：弧 / 环不能用粗描边画

把 pen-stroke 的 strokeWidth 设成环厚，看起来能得到环带，但每段折线是独立矩形， 拐角处 linejoin 表现不稳 → 锯齿 + 接缝，环看起来是碎的。

正解：外弧正向采样 + 内弧反向采样 + Z 闭合成一整块实心面， fill 填色、strokeWidth: 0。详见 [builder-workflow.md](references/builder-workflow.md) §5。

陷阱 4：任何背景色形状压在环带上都会挖洞

环带范围内出现任何白色形状（箭头挖槽、装饰覆盖、内部缺口），就会在环上啃出一个洞， 视觉上环被劈成两截。三种常见错法：

正解：箭头做成一个轮廓自带内凹的实心多边形（与环同色），全程不用白色形状。 自检要逐度扫描环带：

holes = [d for d in range(360) if not band_has_fill(d)]
assert not holes, f"环在 {holes} 度被挖洞"

3.4 table-node

表格的 size 应等于 colWidths 之和 × rowHeights 之和。需要固定行高时把该行 rowDragged 写成 true（组合片段首行保持 false），否则行高会按内容自适应。

网格类布局最易踩的坑：格子高度必须一致。

table-node 的高度由自己的 rowHeights 之和决定。若各格行数不同（左上 3 条、左下 2 条）， 实际高度就不同，而坐标仍按统一 Q_H 推算，于是出现：中间空出一段、上下排下沿不齐、轴标签悬空。

HEAD_H, ROW_H, ROWS = 46, 46, 5
Q_H = HEAD_H + ROW_H * ROWS          # 高度由行数反算，不预设
rows = [[title]] + [[t] for t in items] + [[""] for _ in range(ROWS - len(items))]

空行铺成等高空行，不要用一条超高填充行代替（那样看起来是一整块色块，不像表格）。

四、连线

4.1 两类连线

普通连接线必须写 data.lineType。漏写会被当成树边：两端是 topic 时会破坏树结构， 并且不进入连接线的选中/编辑逻辑。

4.2 端点必须绑定节点（最重要的一条）

{
  "cell": "node-id",
  "anchor": { "name": "right", "args": { "rotate": true } },
  "connectionPoint": { "name": "shape-boundary", "args": { "side": "right" } }
}

选择建议：

• 矩形类、table-node、text-node、topic → connectionPoint: { "name": "anchor" }
• 不规则图形（菱形、圆、箭头、手绘）→ shape-boundary，避免线停在包围盒空白处
• 不确定时统一用 shape-boundary 也安全，没有外轮廓的形状会自动退回锚点

4.3 不要使用自由端点

自由端点写作 { "x": 700, "y": 500 }，没有 cell。

问题：节点的 position 会被精确保留，而自由端点需要渲染器自行解释，是唯一会被二次换算的东西。 实测结果是所有自由端点连线整体平移，节点位置完全正确而箭头全部跑偏 —— 看起来像「箭头和文字脱节」， 其实文字是对的，错的是线。

规则：

1. 能用 source.cell / target.cell 绑定的，一律绑定。
2. 不要用 vertices 补偿漂移 —— vertices 同样是自由坐标，会跟着一起漂。
3. 不要用细长矩形假造连线：拖动节点不跟随、不能重新布线、没有箭头语义、导出到其它工具只是一堆矩形。 连线必须是 shape: "edge"。

需要「线端落在精确位置、但那里没有节点」时，放一个 1×1 隐形锚点：

{
  "id": "pt-1",
  "shape": "shape-rect",
  "position": { "x": 312, "y": 279.5 },
  "size": { "width": 1, "height": 1 },
  "attrs": { "body": { "fill": "none", "stroke": "none", "strokeWidth": 0 } },
  "data": { "manualResized": true },
  "zIndex": 0
}

要点：

• fill: none + stroke: none，用户看不到也点不中；zIndex: 0 压最底层
• 不要写 attrs.label（否则渲染出「输入文本」占位）
• 连线的 connectionPoint 用 { "name": "anchor" }
• 对齐方向要算准：left 取 x，right 取 x + 1，top 取 y，bottom 取 y + 1。 1×1 的盒子无法让 left 和 right 同时精确，所以一个锚点只服务一个方向

锚点要严格限量（每张图 ≤ 10 个）。 锚点是空壳节点，数量一多， 在导入 / 复制 / 导出链路里容易被当空对象清理，挂在上面的边会被整条丢弃 —— 表现为「一部分连线凭空消失」，且没有任何报错。

优先换布局让两端自然对齐到节点边中点，而不是继续堆锚点。布局让位给可靠性。

4.4 连线类型与端点装饰

端点装饰写在边 data 上的 startCap / endCap，取值 1–15：

默认 startCap = 1；endCap 在 line 类型为 1，其余为 3。

完整连线示例：

{
  "id": "edge-1",
  "shape": "edge",
  "source": {
    "cell": "a",
    "anchor": { "name": "right", "args": { "rotate": true } },
    "connectionPoint": { "name": "shape-boundary", "args": { "side": "right" } }
  },
  "target": {
    "cell": "b",
    "anchor": { "name": "left", "args": { "rotate": true } },
    "connectionPoint": { "name": "shape-boundary", "args": { "side": "left" } }
  },
  "connector": { "name": "arrow-line" },
  "attrs": { "line": { "stroke": "#A2B1C3", "strokeWidth": 2,
                       "strokeOpacity": 1, "targetMarker": null } },
  "data": { "lineType": "line-arrow", "startCap": 1, "endCap": 3 },
  "zIndex": 10
}

无论是否需要箭头，都建议在 attrs.line 里写 targetMarker: null，避免残留默认箭头。

4.5 树边

{
  "id": "tree-1",
  "shape": "edge",
  "source": { "cell": "parent", "anchor": { "name": "right", "args": { "rotate": true } },
              "connectionPoint": { "name": "anchor" } },
  "target": { "cell": "child", "anchor": { "name": "left", "args": { "rotate": true } },
              "connectionPoint": { "name": "anchor" } },
  "connector": { "name": "topic-stub", "args": { "stub": 30 } },
  "attrs": { "line": { "stroke": "#3F6AFC", "strokeWidth": 2, "strokeOpacity": 1,
                       "strokeDasharray": "none", "targetMarker": null } },
  "data": { "topicOrder": 0 },
  "zIndex": 1
}

规则：

• 树边不写 data.lineType
• 必须写 attrs.line.targetMarker = null，否则默认箭头会出现在思维导图线上
• data.topicOrder 是同一父节点下的兄弟顺序，从 0 开始
• 树状图「根 → 子节点」用 connector: { "name": "rounded" }，并建议写一个 L 形拐点： vertices: [{ "x": 根中心x, "y": 子节点中心y }]；分支内部继续用 topic-stub

4.6 类图关系

类图关系额外写 data.capsCustomized = true。

五、坐标与排版

5.1 基本约定

• 单位是 px；position 是节点左上角，size 是宽高
• 所有坐标为绝对值；父容器只负责分组/移动，不改变子节点坐标基准
• zIndex 建议分层：分区 0、组盒 1、普通节点 2–9、连线 10+
• 边不需要 size，其包围盒由端点、vertices、标签推导

5.2 导入不会自动排版

导入只执行升级、反序列化、补标题与 topicOrder，不会调用自动布局。因此：

• position 必须就是期望的最终位置
• data.layout 影响方向按钮和后续新增节点时的布局方向，但不会在打开时重排
• 之后在画布上增删子节点，整棵树会按 data.layout 重新排版，手算位置会被覆盖

5.3 文本尺寸

主题和文本节点不会按文案自动撑开，尺寸过小会溢出或挤压换行。按内容留足：

• 中文按 字号 × 字数 估算
• 英文/数字按 字号 × 0.55 × 字符数 估算
• 再加 2px 余量

节点尺寸建议：根主题高约 44、宽 120–160；子主题高约 34、宽 80–140。

六、可编辑性（决定模板质量）

模板是给用户改文案、改颜色、改位置的，不是一张合成图。

例外——文字可以写在 shape-* 的 label 上：

• 简单流程图单步（一个矩形 = 一步，整体拖动）
• 形状未旋转、文字与形状一一对应（如胶囊标签）
• 反之，形状带旋转/变形（鱼头三角、斜向骨线）时，文字要单独放 text-node 浮在合适位置，不与任何节点连线

七、生成检查清单

• [ ] 顶层是 { "cells": [...] }，JSON 可解析
• [ ] 所有 id 唯一且非空
• [ ] 每个节点有 shape、position、size
• [ ] 所有 shape 都在已注册清单内
• [ ] 每条边的 source.cell / target.cell 都能在 cells 里找到
• [ ] 没有自由端点边：所有边的端点都含 cell
• [ ] 没有用矩形假造连线：结构线一律是 shape: "edge"
• [ ] 隐形锚点为 1×1 + fill:none + stroke:none + 无 label + zIndex: 0
• [ ] 隐形锚点数量 ≤ 10，且每个都服务于「真实节点上没有的落点」
• [ ] 锚点的 anchor.name 与对齐方式匹配（left→x，right→x+1，top→y，bottom→y+1）
• [ ] 树边没有 data.lineType，有 data.topicOrder 与 targetMarker: null
• [ ] 普通连接线有合法 data.lineType、attrs.line 和 startCap / endCap
• [ ] 表格 cells 每行等长，colWidths / rowHeights 长度匹配，size 等于总和
• [ ] 网格类布局所有格子等高，size.height 等于行高之和
• [ ] 分区同时有 data.title 和 attrs.label.text
• [ ] group / section 的 children 与子节点 parent 一致，组盒 zIndex 低于成员
• [ ] 多行文字用 label.html；表格文字已做 HTML 转义
• [ ] 所有字号在 12 / 14 / 16 / 18 / 20 白名单内，正文为 14
• [ ] 字号校验用的是白名单，不是 fontSize < 12
• [ ] 调字号后未出现文字溢出、裁切或异常换行
• [ ] 全圆角矩形用 shape-full-rounded-rect，不是 rx = h/2
• [ ] 六边形朝向正确（需要平顶时未依赖默认朝向）
• [ ] 弧 / 环是填充面（有 fill + strokeWidth: 0），不是粗描边
• [ ] 环带范围内无任何背景色形状，逐度扫描无空洞
• [ ] 未写 tools、view、selection、hover、collapse 等 UI 字段

八、常见问题速查

延伸阅读

此文件可在下载的资源包中查看。

此文件可在下载的资源包中查看。

用脚本生成，而不是手写 JSON

图复杂到一定程度后，手写 JSON 一定会出错：坐标靠心算、改一个尺寸要连带改几十处、 字号容易飘、自由端点与悬空引用无法自查。

正确做法是用一个小脚本生成 JSON，再用断言校验。本文给出可直接复用的构件与写法。

0. 为什么值得上一套脚本

脚本不要求多复杂，一个文件、百来行足够。

1. 目录约定

project/
├── _lib/
│   └── drawnix.py          # 共享构件（assets/drawnix.py 可直接用）
├── refs/                   # 参考图存档
└── <分类>/
    ├── build.py            # 生成脚本（唯一真相）
    └── out.json            # 产物，由 build.py 生成，不要手改

产物永远由脚本生成。 手改 JSON 会在下次重跑时被覆盖，而且断言不再反映真实状态。

2. build.py 骨架

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""图的名称

## 结构          ← 用文字画一遍版式，便于后续维护
## 尺寸依据      ← 有参考图时必写：所有比例的出处
## 实现要点      ← 关键约束，为什么这么写
"""

import sys, os, math
sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "_lib"))
from drawnix import Builder, FS, FS_MIN, FS_SUB, FS_TITLE, INK, MUTED

b = Builder()

X0, TITLE_Y = 140, 44          # 版式原点，全图统一

# ---------- 1. 视觉 token ----------
# ---------- 2. 版式 token（全部写成变量，禁止散落魔数）----------
# ---------- 3. 画图 ----------
# ---------- 4. 保存 + 通用校验 ----------
b.save("out.json")
b.verify("图表名", expect_edges=0, max_anchors=0)

# ---------- 5. 本图专属断言 ----------
by = {c["id"]: c for c in b.cells}
assert ...

三段缺一不可：通用校验保证不违反契约，专属断言保证这张图长得对。 只跑通用校验的图，几何仍然可能错 —— 通用校验不知道「蜂巢应该六边形等距」。

3. Builder API

完整实现见 [assets/drawnix.py](../assets/drawnix.py)。

3.1 文本

text() 的高度由宽度反算行数（lines = ceil(text_width / width)）。 传了 width 就会自动给多行高度，但不要传过小的 width，否则行数算多、高度虚高。

3.2 基础图形

pill() 与 hexagon() 的存在就是为了绕开两个形状陷阱，详见 README 3.3。

3.3 折线与多边形

pen() 是画任意形状的唯一入口。它会成对写全 attrs.penPath.d 与 data.points —— 这两个字段缺任何一个，图形完全不可见（不是显示异常，是彻底看不见，且没有任何报错）。

任何自定义轮廓都必须走 pen()，不要用多个矩形拼凑。

3.4 几何图元

3.5 表格与连线

3.6 收尾

4. 两个容易写错的图元

4.1 全圆角矩形必须用 pill()

shape-full-rounded-rect 的圆角由形状类型本身保证（两端完整半圆）。

错误写法：rounded(...) + rx = h/2。看起来一样，但 rx 是普通圆角矩形的参数， 渲染时会被上限裁剪，一旦裁剪就退回普通圆角矩形 —— 两端不再是半圆， 而从 JSON 上完全看不出问题（rx 的值确实等于 h/2）。

判据：shape 字段必须是 shape-full-rounded-rect。

4.2 六边形必须用 hexagon()

shape-hexagon 的朝向（平顶/尖顶）和斜边内缩量由渲染实现决定，无法通过 JSON 控制。 蜂巢拼接必须平顶，所以用 6 顶点 pen-stroke 自己画，朝向与比例完全可控。

配套断言：

top_y = min(p["y"] for p in pts)
assert len([p for p in pts if abs(p["y"] - top_y) < 0.01]) == 2, "尖顶六边形"

5. 几何图元的正确画法

5.1 弧 / 环：必须画成「实心填充面」

正解：外弧正向采样 + 内弧反向采样 + Z 闭合 = 一整块实心环形面， fill 填色、strokeWidth: 0。

outer = [pt(a, r_out) for a in arc_angles]
inner = [pt(a, r_in) for a in reversed(arc_angles)]
poly  = outer + inner          # 首尾自然闭合

5.2 环上有箭头：环必须完整，且不能有背景色形状压在环上

这是最容易反复出错的一处。判断标准很简单：

环带范围内只要出现背景色像素，环在视觉上就是断的。

三种错法：

正解：箭头是一个斜跨环带的实心多边形，与环同色，轮廓本身带内凹（形成燕尾观感）， 全程不用任何白色形状。

用归一化坐标表示（环厚 = 1，环中线 = 0）：

自检必须能拦住「环带被挖洞」：

holes = [d for d in range(360) if not band_has_fill(d)]
assert not holes, f"环在 {holes} 度被挖洞"

5.3 蜂巢：间距要先「向外扩 g/2」再密铺

直接写 DX = 0.75 × 格宽 会让横向缝比纵向窄，斜向格子贴住而上下留空。

GAP = 16                                    # 六个方向统一白缝
CELL_W = HEX_W + 2 * GAP / math.sqrt(3)     # 扩边后等效格宽
CELL_H = HEX_H + GAP
DX = CELL_W * 0.75                          # 水平相邻中心距
DY = CELL_H                                 # 垂直相邻中心距

六个格子中心：(0, ±DY) 与 (±DX, ±DY/2)。

不要用角度摆（每 60° 取一个 cos/sin）—— 角度摆法会让斜向格子与中心格的边对不齐。

5.4 网格类布局：格子必须等高

table-node 高度由自己的 rowHeights 之和决定。若各格行数不同（左上 3 条、左下 2 条）， 高度就不同，而坐标仍按统一 Q_H 推算 → 中间空出一段、上下排下沿不齐、轴标签悬空。

HEAD_H, ROW_H, ROWS = 46, 46, 5
Q_H = HEAD_H + ROW_H * ROWS        # 高度由行数反算，不预设
rows = [[title]] + [[t] for t in items] + [[""] for _ in range(ROWS - len(items))]

空行铺成等高空行，不要用一条超高填充行代替。

5.5 时序图：不要依赖自带生命线的图元

shape-object-lifeline / shape-focus-control 这类图元自带内部渲染，包围盒与实际可见范围不一致， 坐标不可控，消息线端点无法可靠对齐。

改用基础图形自己拼：

关键：消息端点要落在激活条外缘，不是生命线中心（外移半个激活条宽，通常 13px）， 否则箭头会被激活条遮住一截。

激活条要按消息区间合并连续段，否则会出现「一条长条贯穿全图」或「每两条消息一个碎条」：

spans = {}
for idx, frm, to, *_ in MESSAGES:
    for key in {frm, to}:
        spans.setdefault(key, []).append(msg_y(idx))

for key, ys in spans.items():
    ys = sorted(set(ys))
    cluster = [ys[0]]
    for y in ys[1:]:
        if y - cluster[-1] <= STEP * 2:      # 相邻消息并入同一段
            cluster.append(y)
        else:
            FOCUS.append((key, cluster[0], cluster[-1])); cluster = [y]
    FOCUS.append((key, cluster[0], cluster[-1]))

6. 断言清单

verify() 内置以下检查，任一失败即退出：

verify() 只管契约，不管「长得对不对」。每张图还要写自己的断言：

# 等距 / 等高 / 对齐
assert len({round(t["size"]["height"]) for t in tabs}) == 1
# 中心落在网格上
assert abs(ccx - (CX + ox)) < 0.5
# 元素不溢出容器
assert hx1 < PANEL_X + PANEL_W - 8
# 文字宽不超该高度处的可用内宽
assert w / 2 <= inner_half_width(off) + 0.5
# 环带无空洞
assert not [d for d in range(360) if not band_has_fill(d)]

7. 渲染预览

assets/preview.py 把 JSON 渲染成 PNG，用于目视与像素比对：

python3 assets/preview.py <json路径> <输出.png>
# 超采样 4 倍再缩回，模拟抗锯齿
SS_SCALE=4 python3 assets/preview.py <json路径> <输出.png>

预览器的锯齿不代表产物有问题。 简单渲染器通常不做抗锯齿，粗描边折线必然呈阶梯状。 判断「是否有锯齿」要看 JSON 用的是填充面还是粗描边（见 5.1），不要只看 PNG。

8. 新图 checklist

• [ ] build.py + 生成的 out.json
• [ ] docstring 三节齐全：结构、尺寸依据、实现要点
• [ ] 视觉与版式参数全部变量化，无散落魔数
• [ ] verify() 通过
• [ ] 本图专属断言 ≥4 条
• [ ] 渲染 PNG 目视一遍
• [ ] 全量重跑所有 build.py，确认没有互相影响

视觉规范

一张图的专业感，八成来自间距、字号、颜色的一致性，不是来自图形本身多花哨。 本文给出可直接套用的 token 与版式规则。

一、两套配色体系

1.1 默认：办公分析风

适合数据表、方法论模型、汇报类图示。特征是蓝表头 + 深色分区标 + 白底斑马表。

1.2 柔和色（需要更轻的观感时）

适合流程图、架构图、时间线这类以图形为主的图。

填充色（同一图内不超过 5 种，同色系深浅搭配）：

规则：填充用浅色，文字用同色系的深色。不要浅底配黑字（对比过硬）， 也不要深底配浅字做大面积区块（视觉过重）。

二、字号

只允许 12 / 14 / 16 / 18 / 20 及更大的标题字号。

禁止 9 / 10 / 11 / 13 / 15 / 17 / 19。

12px 使用面积占比不超过约 20%。内容放不下时，优先放大画布或拆分布局， 不要靠缩字号硬塞。

三、间距

间隙要一致。 同一张图里出现 12 / 16 / 24 三种间隙而无明确层级理由， 视觉上就是「没对齐」。

四、圆角

注意：全圆角必须用 shape-full-rounded-rect，不能用 rx = 高度/2 模拟。 rx 会被渲染时裁剪，退化成普通圆角矩形，而 JSON 上看不出问题。

五、层级（zIndex）

组盒必须低于其成员，否则会遮住子节点。

六、留白与密度

判断标准：把图缩小到 50% 看，如果还能分清层级，密度就是合适的。

七、常见视觉问题

八、配色速查

需要快速给一组分类上色时，按这个顺序取（同一图内前 N 个）：

1  蓝  #D6EBFF / #2A5F94
2  紫  #E5D4FA / #6C4CC4
3  绿  #D5F2E0 / #2F6B3E
4  黄  #F9EDBE / #8A6A12
5  粉  #FAD9E6 / #9C4157
6  橙  #FDE3CC / #A0522D

超过 6 类时，第 7 类起改用中性灰 #EDEEF0 / #5A6169， 或用同色系的不同深浅（如蓝的 #D6EBFF 与 #B8D9F5）区分。

按「图形骨架」选型

拿到需求时，先判断骨架，不要先判断名字。骨架决定用哪些图元；名字只是叫法， 同一个名字在不同人嘴里可能指完全不同的结构。

一、十四种骨架

二、三种范式（最易混）

最容易犯的错：把「时间线示意图」做成 B 类（topic + 时间线布局）， 得到的是可展开的链条主题树，和一张固定的时间线图完全不是一个东西。

判断方法：问「用户要在这张图上继续增删节点吗？」要 → B 类；只改文字 → A 类。

三、闭环 vs 比例环（最容易混的一对）

用错的表现：闭环用分段弧 → 环是断的；比例环用单箭头 → 只有一个箭头，其它段没有指向。

四、放射族三兄弟

五、各骨架的实现要点

5.1 时间轴

单事件 = 底框 + 内缩色条 + 日期/标题/说明三个文本节点 + 圆点 + 竖线。

• 色条四边内缩，宽度通栏内缩，不要顶满也不要缩成只包住日期
• 说明文字的高度按行数给：单行 22、两行 44、三行 62
• 上下交替时，轴上与轴下的卡片分别按圆点半径 + 间距推算 y

5.2 闭环

• 环：完整 360° 实心环形面（外弧正向 + 内弧反向 + Z）
• 箭头：斜跨环带的单个实心多边形，轮廓自带内凹
• 环外装饰件：与环体完全脱开，最近角距离 > 环外径

自检：环带逐度无空洞 + 连通块数 = 1（主体）+ N（装饰件）。

5.3 比例环

• 每段是一条弧形填充面，段间留 1–2° 白缝
• 百分比标签放在该段中角、环带中线位置
• 中心留白直径建议为 外径 − 环宽 − 20，放总量或核心结论

5.4 放射 / 蜂巢

• 六边形用 6 顶点 pen-stroke 自画（平顶）
• 间距：DX = 0.75 × (W + 2g/√3)、DY = H + g
• 中心坐标：(0, ±DY) 与 (±DX, ±DY/2)
• 格内多段文字（标题 / 分隔线 / 释义）用独立 text-node 叠加，不要塞进 attrs.label
• 分隔线长度取该高度处内宽的 60%，避免顶到斜边

5.5 矩阵

• 所有格子行数统一，不足补空行
• Q_H = 表头高 + 行高 × 行数，由行数反算而非预设
• 轴标签坐标由实际表格边界反推，不要用 Q_H 手算

5.6 泳道

两种实现：

5.7 层级树

• 同层卡片统一高度，否则水平分支线会错开
• 分支线用真实节点当端点；T 形横干横跨多列时，端点不在任何节点上， 需要 1×1 锚点（这是锚点的合法用途之一）
• 锚点总数仍要控制在 10 个内

5.8 流程

• 判定框出口对齐：是/否分支分别从左右或上下引出
• 箭头统一 endCap: 3
• 回环线容易与其它线交叉，优先调整节点位置而不是加折点

5.9 时序

见 [builder-workflow.md](builder-workflow.md) §5.5。核心三条：

1. 不用自带生命线的图元
2. 消息端点落在激活条外缘
3. 激活条按消息区间合并

5.10 鱼骨

• 主脊为一条水平粗线，斜骨从主脊斜向引出
• 斜骨上的标签用 text-node 浮在线段中点，不与任何节点连线 （一旦连线，会参与布局、被拖乱）
• 末梢小横线与斜骨垂直

5.11 便签墙

• 便签统一尺寸，间距一致
• 分区用 section，data.title 与 attrs.label.text 都写
• 便签默认文字 20px，注意与字号白名单一致

5.12 分组列

• 外层容器直角（rx: 0），白底黑边
• 标题胶囊骑跨在容器顶边：y = 容器顶 − 胶囊高/2
• 胶囊必须 shape-full-rounded-rect
• 各组列宽与间距一致；底部汇总框宽度 = 各组总宽

六、选型自检

动手前回答三个问题：

1. 用户要在这张图上继续增删节点吗？ 要 → B 类主题树；不要 → A 类展示型
2. 是「流动」还是「占比」？ 流动 → 闭环；占比 → 比例环
3. 有没有两个轴？ 有 → 矩阵 / 四象限；没有 → 列表或放射

三个问题答完，骨架基本就定了。剩下的是套用该骨架的约束。

照着参考图复刻：测量与验收

有参考图（截图、导出图、别人的画板）时，不能靠肉眼判断像不像。 视觉判断能发现「整体歪了」，但发现不了「环带被挖了个 3px 的洞」这类致命细节。

正确做法是先测量再动手，并把量出来的比例写进断言。本文给出可直接运行的测量方法。

0. 四条原则

1. 先测量，再动手。 拿到参考图第一件事：量尺寸、量颜色、量间距，写进脚本的 docstring。
2. 归一化后再比。 用「环厚 = 1」「格宽 = 1」这类相对单位。绝对像素不可跨分辨率比较。
3. 判据写进断言。 量出来的比例要落到 assert，否则下次改代码就丢了。
4. 目视只做最后一道。 它只能确认整体观感，不能用来验收几何。

1. 读取基础信息

from PIL import Image
from collections import Counter

im = Image.open(path).convert("RGB")
W, H = im.size
print("尺寸", W, H)
print("主要颜色", Counter(im.getdata()).most_common(8))

颜色统计直接给出填充色、描边色、背景色。不要凭感觉猜色值。

2. 找图形边界

2.1 按颜色找连通域

from collections import deque

def components(mask_fn, W, H, px, min_area=200):
    """mask_fn(rgb) -> bool；返回 [(面积, x0, y0, x1, y1)]，按面积降序。"""
    seen = bytearray(W * H)
    out = []
    for y in range(H):
        for x in range(W):
            i = y * W + x
            if seen[i] or not mask_fn(px[x, y]):
                continue
            q = deque([(x, y)]); seen[i] = 1
            n = 0; x0 = y0 = 10**9; x1 = y1 = -1
            while q:
                cx, cy = q.popleft(); n += 1
                x0 = min(x0, cx); x1 = max(x1, cx)
                y0 = min(y0, cy); y1 = max(y1, cy)
                for dx, dy in ((1,0),(-1,0),(0,1),(0,-1)):
                    nx, ny = cx + dx, cy + dy
                    if 0 <= nx < W and 0 <= ny < H \
                       and not seen[ny*W+nx] and mask_fn(px[nx, ny]):
                        seen[ny*W+nx] = 1; q.append((nx, ny))
            if n >= min_area:
                out.append((n, x0, y0, x1, y1))
    return sorted(out, reverse=True)

连通域数量本身就是判据。 例如「一个闭环 + 两个脱离的装饰件」应当是 3 个连通块： 少了说明有元素粘在一起，多了说明主体断了。

2.2 按描边找精确边界

填充色连通域会因抗锯齿偏小 1–2px。要精确尺寸就扫描描边（暗像素）：

def dark(rgb, t=160):
    return max(rgb) < t

def v_lines(px, W, ys):
    """在若干行上找暗像素，合并连续段，得到竖直边界的 x。"""
    xs = set()
    for y in ys:
        for x in range(W):
            if dark(px[x, y]):
                xs.add(x)
    xs = sorted(xs); segs = []
    if xs:
        s = pv = xs[0]
        for x in xs[1:]:
            if x - pv > 3:
                segs.append((s, pv)); s = x
            pv = x
        segs.append((s, pv))
    return segs

3. 极坐标扫描（环形 / 放射状图形专用）

圆形、环形、蜂巢、雷达图的核心判据都在极坐标上。

3.1 拟合圆心

先用包围盒中心粗估，再用「环带厚度方差最小」精修：

best = None
for CX in range(cx0 - 40, cx0 + 41):
    for CY in range(cy0 - 40, cy0 + 41):
        ths = []
        for d in test_degs:                  # 避开箭头区域的角度
            hits = [r for r in radii if is_fill(sample(CX, CY, d, r))]
            if hits:
                ths.append(max(hits) - min(hits))
        if len(ths) < len(test_degs) - 2:
            continue
        var = sum((t - sum(ths)/len(ths))**2 for t in ths) / len(ths)
        if best is None or var < best[0]:
            best = (var, CX, CY)

环带厚度方差最小的点就是圆心。不要用包围盒中心代替 —— 不对称凸出（如箭头）会让包围盒偏心。

3.2 逐度剖面（发现缺口与挖洞）

import math

def radial_profile(px, W, H, CX, CY, r_lo, r_hi, is_fill):
    """返回 {角度: 该角度上所有填充段 [(r0, r1), ...]}。"""
    prof = {}
    for deg in range(0, 360):
        a = math.radians(deg)
        segs, cur = [], []
        for r in range(r_lo, r_hi):
            x = int(round(CX + r * math.cos(a)))
            y = int(round(CY + r * math.sin(a)))
            ok = 0 <= x < W and 0 <= y < H and is_fill(px[x, y])
            if ok:
                cur.append(r)
            else:
                if cur:
                    segs.append((cur[0], cur[-1])); cur = []
        if cur:
            segs.append((cur[0], cur[-1]))
        prof[deg] = segs
    return prof

判据：环必须每度都有填充。 任何一度缺失就是断开：

holes = [d for d, segs in prof.items() if not segs]
assert not holes, f"环在 {holes} 度断开"

3.3 归一化（跨分辨率比较）

R_mid = (r_in + r_out) / 2
sw    = r_out - r_in
norm  = (r - R_mid) / sw        # 环中线 = 0，环厚 = 1

归一化后，参考图与产物可以放在同一张表里逐度对比：

偏差判据建议取 ±0.05 环厚（约 ±2.5px @ 环厚 50px）。

4. 整体相似度（IoU）

对齐后做像素交并比，快速判断版式对不对：

def iou(mask_a, mask_b):
    inter = sum(1 for a, b in zip(mask_a, mask_b) if a and b)
    union = sum(1 for a, b in zip(mask_a, mask_b) if a or b)
    return inter / union

对齐方法：按主图形半径缩放，再把两个圆心平移到同一点。

5. 逐度 ASCII 图（定位细节缺陷最快）

数值表看不出「形状长什么样」，ASCII 图可以：

print("      " + "".join(str((r // 100) % 10) for r in range(r_lo, r_hi, 4)))
for deg in range(168, 216):
    a = math.radians(deg)
    row = "".join("#" if is_fill(sample(CX, CY, a, r)) else "."
                  for r in range(r_lo, r_hi, 4))
    print(f"{deg:4d}  {row}")

一屏内就能看出：形状从哪个角度开始张开、哪里收窄、凹口在什么半径位置。 数值对得上但形状不对时，ASCII 图能立刻暴露问题。

6. 验收流程

1. 测量参考图     颜色统计 → 连通域 → 描边扫描 → 圆心拟合
2. 写进 docstring 归一化比例表（所有魔数的出处）
3. 生成产物       比例全部来自那张表
4. 渲染产物       assets/preview.py
5. 同尺度对比     按主图形半径缩放 + 圆心对齐
6. 三项测量       连通域数 / 逐度剖面 / IoU
7. 目视确认       最后一道，只看整体

第 6 步全部通过才算完成。任一项不过就回第 3 步。

7. 常见误判

8. 判据模板（直接抄进脚本）

# ============ 对齐参考图实测 ============
# 1) 主比例（参考图实测：环厚 / 中线半径 = 0.264）
ratio = SW / R
assert abs(ratio - 0.264) < 0.03, f"厚度/半径 {ratio:.3f}，参考 0.264"

# 2) 环必须每度有填充（无挖洞）
holes = [d for d in range(360) if not band_has_fill(d)]
assert not holes, f"环在 {holes} 度断开"

# 3) 连通块数必须等于参考图
assert len(components) == 3, f"连通块 {len(components)} 个，参考图 3 个"

# 4) 关键元素位置（归一化）
assert abs(head_r_max / R - 2.52) < 0.10        # 箭头尖端伸出环外的倍数
assert abs(loose_gap / r_out - 1.43) < 0.08     # 装饰件最近角距圆心 / 环外径