/svg-book-illustrator

配图审查清单（Review Checklist）

SVG 配图生成 + 嵌入后的四道审查门禁。多模态模型 / 审查者照此逐章执行。 配套 SKILL.md「第四阶段：审查与验收」。

核心原则：源生产契约（xmllint / 规范画布 / 无嵌入样式）与受控字体渲染是必要不充分条件——它们保证 SVG 合法且导出字体稳定，不保证图正确美观。下面四道审查（尤其 ③ 字宽硬算 + ④ 目检）才是验收依据。

⓪ 源身份门禁（进入四道内容/视觉审查前）

• 每张 v1.8.9+ 新生成/新落稿 SVG 的根元素都有非空安全 data-figure-id
• 当前项目 canonical scope 内 ID 全局唯一；推荐 fig-chNN-sN-NN，不能以文件遍历顺序或“第几张图”代替
• fig-template-* 已在落稿前替换，生成器调用已显式传入 --figure-id fig-chNN-sN-NN
• review finding、渲染截图/清单与修订复检均以同一 ID 绑定；缺失或重复时 fail-closed，不进入后续四道审查
• 默认不存在用属性“解释掉”的 shape 重叠；意外重叠已回改坐标，而不是添加 data-allow-overlap、data-overlap-role="decoration" 或任意自造 role
• 确有“外层 shape 承载内层 shape”语义时，只在外层 area shape 写 data-overlap-role="container"，并同时写单图唯一原生 id、至少六字且明示承载关系的 data-overlap-note 与非透明 hex/rgb/hsl fill
• producer contract 已静态通过容器声明；这只证明元数据合规，不证明几何合法
• writing-reviewer v0.16+ render gate 已以真实浏览器几何复核，并在 evidence 中记录实际命中的 outer / inner / reason；未命中的声明不得拿来替代修图

本门禁只约束新产物；是否为历史书稿补 ID 由项目另行决定，不在本 Skill 升级中强制迁移。

① 配图密度审查（整章统计，~5 分钟）

指标（按章节统计）：

• 图/节 = SVG 数 ÷ 节数（## 第N节 计数）
• 图/万字 = SVG 数 ÷ (字数 / 10000)

判定：

补图定位：扫描缺图小节，找「架构 / 流程 / 对比 / 层次 / 循环 / 关系」描述处（SKILL 第一阶段识别法），补占位 [[FIG:N:描述]]。

跨章均衡：相邻章密度比 < 2×；认知 / 入门篇（如 ch01-03）图密度不应远低于方法 / 实战篇。

实测参考（legal-ai-skill-book，2026-06-17）：

• 充足（1.3-1.6/万字）：ch07/08/11/12/13
• 适中（1.0-1.5）：ch01/09/10
• 偏少待补：ch03（1 张/7 节，0.6）、ch05（2/6，0.5）、ch02（3/7，0.9）

② 图-正文论点一致性审查（逐图对照正文，每图 2-3 分钟）

每张图，回溯所在小节原文，逐项核对：

• 节点数一致：图的节点 / 框数 = 正文描述的要素数（"四层"画 4 层、"七节点"画 7 个、"六对象"画 6 个）
• 层级 / 节点名一致：用正文术语，不擅自改写（如"思维内核层"不写成"思维层"、"MCP 工具层"不写成"工具层"——全称层名见各书总纲）
• 流程方向一致：箭头方向 = 正文叙述顺序（A→B 还是 B→A；自上而下 / 自下而上 / 蛇形）
• 对比维度一致：matrix 的列 / 行 = 正文对比维度（甲方/乙方、前后、Chatbot/Agent）
• 信息无损：替换 mermaid / ASCII 图时，原节点、关系、虚线标注、脚注不丢失
• 图注准确：「图 N-X：标题」概括图内容，不夸大（非"全景"除非真是）、不遗漏核心要素
• 正文锚点：图嵌入位置紧贴相关论述段，前后文有"如下图 / 这张图"类承接（避免孤图悬空）

发现问题：回 SVG 改节点 / 方向 / 图注，或调整嵌入位置；改后重跑一致性核对。

③ 字宽/坐标硬算自检（v1.8.5+，生成器产出后必跑，先于视觉目检）

为什么加这道：视觉多模态目检对"轻微溢出/贴近"易判 OK——v1.8.5 修过两例漏检（radar 底部图例与轴标签重叠、three-col 子卡片单行溢出）。坐标/字宽硬算更可靠，作为 ④ 视觉目检的前置计算闸。

逐图跑（生成器产出或手写 SVG 均适用，每图 ~1 分钟）：

• 文字装得下容器：估算每条文字宽度 ≤ 所在框/列/卡宽。估宽公式：CJK ≈ font-size px/字、Latin ≈ 0.55 × font-size px/字。超宽则：缩字号、拆 2 行、缩短文案，或换更宽布局。
• 元素 y 间距 ≥ 阈值：相邻文字行 / 图例 / 轴标签 / 脚注 的 y 差 ≥ 20px。重点查：标题↔首行、图例↔轴标签、脚注↔主体、卡片行间距。
• viewBox 高度足够：H ≥ 最低元素 y + 安全边距 40px；图例/脚注不与上方元素贴边（gap ≥ 20px）。
• 生成器参数自检：若用 scripts/gen-*.py，产出后用下方脚本算关键文本宽度 vs COL_W / CELL_W / 卡宽，全 ✅ 再渲染。

快捷自检脚本（粘贴改参数即可）：

def width(s, f):
    return sum((f if ord(c) > 0x2E80 else 0.55*f) for c in s)
# 示例：three-col 卡片内容是否 ≤ COL_W
COL_W = (720 - 2*40 - 2*30) / 3   # 193.3
for rest, f in [("流程全写在 SKILL.md", 13), ("证据→裁判预测→庭审大纲", 13)]:
    w = width(rest, f)
    print(f"[{'✅' if w<=COL_W else '❌'}] {rest} → {w:.0f}px (限 {COL_W:.0f})")

发现问题：回生成器参数（缩字号 / 拆行 / 换布局）或 SVG 坐标，重算至全 ✅ 再进 ④ 视觉目检。

④ 视觉目检（多模态渲染后眼检，每图 1-2 分钟）

前置：SVG 渲染为 PNG。

python3 scripts/render_svg.py in.svg out.png  # 快速预览：受控外部字体 CSS + 宽 720
# 或（高 DPI，读取同一 CSS）
node scripts/svg2png.js in.svg out.png 300

禁止把裸渲染器输出作为目检证据：未加载 assets/render-fonts.css 时会随环境回退到不同字体，文字宽度与像素结果均可能漂移。

多模态模型逐张查（看渲染 PNG，不看 SVG 源码）：

• 文字不溢出：所有文字落在所属容器 / 框内，不被边缘截断
• 无意外重叠：框 / 节点 / 文字互不遮挡，间距 ≥ 24px；确有容器包含语义时只走 container + 单图唯一原生 id + 明示承载关系的 note + 非透明 hex/rgb/hsl fill 窄声明，并核对 writing-reviewer render evidence，不把 decoration / 任意 role 当豁免
• 箭头正确：箭头起止落在节点边缘，方向正确，marker 不偏移
• 箭头硬约束（v1.6.0 新增）：SVG 源码 grep '<marker' 只允许单个 <marker id="arrow" ... markerUnits="userSpaceOnUse" orient="auto"> 定义；禁止多方向自造 marker（arrV/arrF/arrG/arrT/arrR/arrL 等），禁止为垂直 / 斜向箭头硬编码不同 refX/refY/orient——一个 marker 配 orient="auto" 通吃所有方向。所有 marker-end 必须引用规范 id="arrow"，禁止 inline marker-end="url(#arr...)" 自创 id。详见 style-guide §六 / DEC-011。
• 连线清晰：连线不穿越文字，交叉处可辨
• 关系语义未丢失：实线 / 虚线 / 点线所承载的流程、反馈、复核、状态或条件关系仍在图中；没有为了删繁就删掉有含义的线。线型含义以读者可理解的短标签 / 图例说明，不留作者或 AI 协作提示。
• 分叉与层级连接正确：同一关系的主干和支线视觉连续、无无意缝隙；相邻层级连接的可见线身优先 16–32px。若超过 48px，确认已因中间语义而有必要，否则回改留白或节点位置。
• 标签卡与编号清楚：深色标题 + 浅色正文的卡只在标题栏上边圆角、下边直角，无双层框 / 接缝；步骤编号置于独立上方带，不压住中文标题或说明。
• 字号可读：节点标签 ≥ 16px、副说明 ≥ 12px、标题 19-20px（16 开 115mm 通栏下 ≥ 8pt）
• 黑白可辨：去色后仍能区分层级 / 强调（颜色不是唯一区分手段）
• 配色对比度（v1.5.0 新增）：文字色（#2D3436/#636E72）与所在模块填充色对比 ≥ 4.5:1（WCAG AA，标题/≥18px 大文本 ≥ 3:1）；无高饱和荧光色；红绿不并置做区分
• 透明背景（v1.5.0 新增）：SVG 无背景矩形、无画布底色（grep 源码不应出现 <rect width="720" height="..." fill="..."/> 当画布底；模块矩形除外）；底色由书页提供
• 内部模块多色（v1.5.0 新增）：SVG 内部不同模块 / 分支 / 方向 / 层级用同色组（P1-P8）不同模块色区分，一图 4-6 种柔和色；相邻模块不同色（亮度差 ≥10%、色相可辨）；颜色尽量多样但不刺眼
• 配色规范（v1.5.0 新增）：新生成图从 8 组调色板选 1 组、不混色组；颜色只用 fill/stroke 属性内联（无 <style> / style=、无内嵌 font-family、无 class/CSS 变量引色、无背景矩形）
• 配色按模板分类（v1.7.0 新增）：layer / tree / 金字塔模板必须用 G1-G4 单色灰度梯度（同色相不同明度）——禁止误用 P1-P8 多色区分（把同色系层画成不同色相会破坏层级归属语义，详见 DEC-012）；flow / matrix / hub / cycle 必须从 P1-P8 选 1 组多色区分。检测手段：把每个模块的 fill 转 HSL 取 h 通道，layer/tree 相邻模块 hue 差 < 30° 判同色梯度合规，否则违规。
• 可视友好化（v1.8.7 新增，详见 style-guide §5.5）：
  • 深底浅字：深色填充（L* ≤ 50，如 #2C5282/#1A202C/G4 深档/项目 canonical 强调色）的模块内 <text> 必须是 #FFFFFF/#EDF2F7 等浅色——禁止深底深字（对比 < 2:1 不可辨，源 T134 review 图 11-9 深蓝背景配深字）。
  • 字色对比度：文字 fill 与所在模块 fill 对比度 ≥ 4.5:1（AA 正常文本 / ≥18px 大文本 ≥ 3:1）；临界档（G2-5 #B8A282 等）必测，不够换白字。
  • 箭头落点：每条 <line> 的 (x2,y2) 落在目标框边外 4px、方向指向目标节点（图 7-6 错位即 x1/y1 与 x2/y2 写反）；marker 单 id="arrow" + markerUnits=userSpaceOnUse + orient=auto（与 §六箭头硬约束协同）。
  • 文字完整性：每个有标题语义的 <rect>/节点 都有非空 <text>、文字坐标在框内、文字 fill 与模块 fill 不同色——防"框画了字没写 / 字与背景同色看似缺失"（图 7-13/8-3/6-7）。检测：grep <rect 计数 vs <text 计数 + 多模态渲染逐框核对框里是否有可读文字。
• 灰度降级可辨（v1.5.0 新增）：先用 python3 scripts/render_svg.py in.svg out.png 受控渲染，再 convert out.png -colorspace Gray gray.png；文字与模块填充灰度差 ≥ 15%、相邻模块灰度差 ≥ 10%
• 视觉重心稳：布局均衡，无头重脚轻或左右失衡
• 留白合理：不拥挤不空旷，安全边距 40px；viewBox 高度按内容裁剪（H = 内容底边 + 40px，不固定 400，v1.7.1）——底部留白统一 40px、图注间距一致

多模态目检 prompt 模板（供生产用）：

这是一张书籍配图（720×H SVG 的 PNG 渲染，宽 720 固定 / 高 H 按内容裁剪，v1.7.1 透明背景 + 内部模块多色/灰度梯度）。请逐项检查，只报问题：
1. 是否有文字溢出容器 / 被截断？
2. 是否有框、节点、文字意外重叠（间距应 ≥24px）？若是容器包含，是否确有承载语义且已由 writing-reviewer render evidence 记录 outer / inner / reason？
3. 箭头是否落位正确、方向无误？
4. 字号是否可读（节点≥16px）？
5. 黑白打印能否分辨层级（颜色不是唯一区分手段）？
6. 文字与所在模块填充色对比度是否 ≥ 4.5:1（标题大字 ≥ 3:1）？是否有高饱和荧光色？红绿是否并置做区分？
7. 内部模块之间是否多色柔和区分（一图 4-6 色），相邻模块不同色？配色是否来自单一调色板组（P1-P8）、不混色组？
8. SVG 是否透明背景（PNG 渲染下若叠在白底应看不出自带的画布底色矩形）？
9. 整体布局是否美观、留白合理？
若无问题回答"通过"；有问题逐条指出（位置 + 现象 + 修改建议）。

发现问题：回 SVG 改坐标（文字 x/y、框 w/h、连线端点、marker refX/refY），重新渲染复检，直到目检"通过"。

审查流程小结

1. 密度审查（整章统计）→ 偏少则补图
2. 一致性审查（逐图对照正文）→ 不符则改图 / 图注 / 位置
3. 字宽/坐标硬算自检（v1.8.5+，计算）→ 溢出/重叠则改坐标/字号/拆行
4. 视觉目检（多模态逐图）→ 不美则改坐标
5. 四道全过 → 验收通过；任一未过 → 回改 + 复检

与 writing-reviewer 的边界：本 Skill 负责生成期规则、producer 静态契约与人工/多模态配图审查；writing-reviewer v0.16+ 还负责 canonical Markdown 中 SVG inventory、静态规则与真实浏览器几何/render evidence。container 声明由本 Skill 约束写法，是否真的形成合法 shape 包含由 writing-reviewer render gate 最终判定；正文口吻、术语与图注贴切性仍由 writing-reviewer 审稿维度处理。