SVG Book Illustrator

设计规范

详见 references/style-guide.md。核心要点：

• 画布：宽 720px 固定（16开 115mm 通栏物理尺寸），高度按内容裁剪（v1.7.1）——viewBox="0 0 720 H"，H = 内容底边最大 y + 40px；不再固定 400（固定 400 会让内容少的图底部留白过大、SVG 下边缘离图注间距忽大忽小）。透明背景（硬约束）——不画背景矩形、不设底色；左右 + 顶部安全边距 40px，底部 = H − 内容底（即 40px）。底色由书页/排版提供。
• 元素删除后的画布回收（v1.9.2,设计演进负债纪律）：删除图内任何可见元素——历史设计的顶部「标记标题」、说明条、废弃节点/分组——时,必须同步收紧 viewBox 与显式 height,使留白回归口径(首内容距上缘约 24-40px、四周安全边距 40px)。「删元素不删空间」是多轮修改的技术负债:真实项目实证——早期顶部标记标题设计被整体移除后未回收画布,4 张图在书页上方遗留大片无信息留白,最终需全书统一排查修正(图 7-2/8-4/11-7/13-1)。配套检查口径:成稿 scan --padding 只拦「边距不足」;「留白过大」无法与有意分组留白机械区分,由视觉复审兜底——因此本纪律约束的是删除动作的当下,不是事后清扫。
• 风格：简洁、专业、静态（无动画、无渐变、无滤镜、无 emoji）
• 颜色（v1.5.0 透明背景 + 内部模块多色版）：新生成图透明底，配色用于 SVG 内部不同模块 / 分支 / 方向 / 层级之间的多色柔和区分——颜色尽量多样（一图 4-6 种甚至更多柔和模块色）。从 8 组预定义调色板（P1 雾蓝系 / P2 浅青系 / P3 嫩绿系 / P4 暖米系 / P5 浅紫系 / P6 浅粉系 / P7 暖灰系 / P8 混合柔和系）选 1 组，组内 5-6 个柔和模块色按"模块 1 取色 1、模块 2 取色 2…"依次分配，相邻模块不同色。文字色统一深灰 #2D3436/#636E72 保证可读。打印友好约束（文字 vs 所在模块填充色对比 ≥4.5:1 WCAG AA、相邻模块区分度 ≥10%、模块色明度 L*≥80、禁高饱和荧光、CMYK 不偏色、灰度差≥10%）。仅新生成图用新配色，main 上既有 34 张白底单色 SVG 保持稳定不回改。
• 颜色语法硬约束：颜色只用 fill/stroke 属性内联——禁 <style> 块定义颜色、禁 <svg> 开标签写 font-family、禁 CSS 变量/class、禁画背景矩形（已验证的 Obsidian 渲染 + 透明背景硬约束，详见 references/style-guide.md §5.4）。
• 可视友好化配色与渲染禁忌（v1.8.7 硬约束，详见 references/style-guide.md §5.5）：① 深底浅字——深色填充（L* ≤ 50，如 #2C5282/#1A202C/G4 深档/项目 canonical 强调色）的模块内 <text> 必须用 #FFFFFF/#EDF2F7，禁深底深字；② 字色对比度——文字 fill 与所在模块 fill 对比 ≥ 4.5:1（AA，大文本 ≥ 3:1）；③ 箭头落点——marker 单 id="arrow" + markerUnits=userSpaceOnUse + orient=auto，落点 x2 = 目标框边 − 4px、方向指向目标节点；④ 文字完整性——每个有标题语义的节点框都有非空 <text>、文字坐标在框内、fill 与模块不同色。源 T134 review 实测：图 7-6 箭头错位 / 图 11-8 字色不可辨 / 图 11-9 深蓝底深字 / 图 7-13/8-3/6-7 框内文字缺失。
• 蓝色焦点 + 文字二档（v1.8.8 通用规则，DEC-020，详见 references/style-guide.md §5.0/§5.1）：① 文字色统一深灰二档——图内所有文字仅允许 #2D3436（主）/#636E72（次），深底走 #FFFFFF/#EDF2F7；不再用 #1A202C/#4A5568（收敛二档消除四档混用）。② 项目 canonical 主色（如 #2C5282/#1A365D 蓝）只用于焦点节点填充/描边，禁作文字 fill——以色块承载强调，文字强调改用字重/字号；这是通用纪律，非项目指针（任何项目锁定主色为视觉标识时都适用）。③ 每张结构/流程图 ≥1 焦点节点——layer/tree/flow/hub/cycle/matrix 应至少有 1 个焦点节点（canonical 主色或更深一档填充/描边）承载层次，反对纯灰平铺；纯并列清单无自然焦点时用灰阶递进 + 边框粗细区分。源法律 AI Skill 实战 DEC-114 方案 A 定调（图 1-6 灰阶 + 唯一蓝色焦点 = 层次标杆、零蓝字）。
• 关系与标签卡语法（v1.8.11，详见 references/style-guide.md §六）：有流程 / 反馈 / 复核 / 状态含义的线不因删繁而删除；同一分叉主干与支线连续；相邻层级箭头优先 16–32px 可见线身、超过 48px 先压缩布局。深色标签 + 浅色正文是一张卡时标题栏只留上圆角；步骤编号占独立上方带；图例只说明读者需要理解的关系。
• 文字：继承渲染环境默认无衬线字体（PingFang SC / Microsoft YaHei 落在系统层），节点标签 18px 起（16开 115mm 通栏下物理 2.88mm = 8.2pt）
• 形状：圆角矩形（rx="6"）、简洁箭头、最小 24px 间距
• 形状包含：默认修复意外重叠；只有真实承载子 shape 的外层 area shape 才声明 data-overlap-role="container"，并同时写单图唯一原生 id、明示承载关系的 data-overlap-note 与非透明 hex/rgb/hsl fill。静态契约只审声明，实际几何由 writing-reviewer render gate 审计
• 印刷：黑白可辨，颜色不是唯一区分手段（黑白降级仍可辨是硬约束）

插图目录

references/diagram-catalog.md 定义插图目录格式和创建方法。

PNG 导出

出版社通常需要位图版本。scripts/svg2png.js 会读取 assets/render-fonts.css，将 SVG 转为高分辨率 PNG：

# 单张转换（默认 600 DPI）
node scripts/svg2png.js input.svg

# 指定输出文件和 DPI
node scripts/svg2png.js input.svg output.png 300

# 批量转换目录下所有 SVG
find figures/ -name "*.svg" -exec node scripts/svg2png.js {} \;

依赖：快速预览 wrapper 需要系统已有 rsvg-convert；高 DPI 导出需要 Puppeteer 和 Chrome/Chromium。缺失时脚本会明确报错，不会自动安装。首次使用高 DPI 功能前由用户自行运行：npm install puppeteer

印刷 DPI 建议：

• 300 DPI：最低印刷要求
• 600 DPI：推荐，清晰锐利
• 1200 DPI：线条图最高质量

成稿一致性 scan（v1.9.0，对既有书稿）

生成流程之外，对已成稿书稿的全部内联 SVG 跑规则巡检（只报告，不改稿；不替代 writing-reviewer render gate 的几何/视觉审计）：

python3 scripts/scan_consistency.py --book-root <书仓根目录> --report <报告输出.md>
# 阈值可调：--padding 40（安全边距 px）、--arrow-gap 8（箭头悬空 px）
# CI 门禁形态：--fail-on hard（存在 hard finding 时退出码 1）

规则覆盖（19 条，每条 finding 带规则 ID / 文件 / SVG 序号 / 位置 / 严重度 hard|soft）：

• 留白：内容距画布边缘 < 阈值（默认 40px，style-guide §一）
• 箭头落点：尖端穿入目标框（禁穿框）、离最近目标框 > 阈值且无 data-arrow-role="axis|annotation" + 非空 note 声明的悬空箭头（style-guide §5.5.3 / FIGURES-OUTLINE DEC-128）
• marker 硬约束：非 arrow 的多 marker / 缺 markerUnits="userSpaceOnUse"+orient="auto" / 悬空 url(#id) 引用（v1.6.0）
• 语法：<style> 块、style=、font-family、整幅画布底色矩形、width/height/viewBox 契约（v1.8.9）
• 身份：data-figure-id 缺失（soft，历史不回填口径）/ 格式不安全 / fig-template-* 落稿 / 跨图重复
• sidecar 同步：canonical 内联 SVG ↔ manuscript/**/*_images/<stem>-svg-N.svg 派生缓存内容一致（T261 口径）

历史口径：对 v1.8.9 前历史书稿的 SYNTAX/IDENTITY 发现只登记不要求回改（与本 skill「不回改历史书稿」既有口径一致）。v1.9.1 新增 --exemptions <台账.json>:逐项豁免已裁决历史项(键=file/svg_index/rule_id),命中不计 findings、未命中报警防台账漂移、坏台账 fail-closed;整规则豁免被有意排除——新图违规永远照报。与 BLOCKED Task-001（producer 冲突）/ Task-002（shape containment）互不侵入：本 scan 不改 producer、不做包含几何判定。

成功标准

• 每张图只表达 1-2 个核心概念
• 架构图层次清晰，流程图逻辑通顺
• 风格简洁专业，无装饰性元素
• SVG 在 Markdown 预览中正确渲染（源契约：开标签严格为 viewBox="0 0 720 H"、width="720"、height="H"，且有项目内唯一安全 data-figure-id；无嵌入 font-family、无 <style>/style=、颜色只用 fill/stroke 属性内联、无背景矩形、xmllint well-formed；受控 wrapper 渲染无警告）
• 图注格式统一：图 N-X：标题
• 配图密度达标：图/节 ≥ 0.7、图/万字 ≥ 0.8
• 图-正文一致：节点/层级/方向/维度与正文论点吻合，替换 mermaid/ASCII 图信息无损
• 视觉目检通过：渲染后无溢出/意外重叠/箭头错位，字号可读、黑白可辨、美观；有意的 shape 包含仅走可审计 container 窄声明并由 writing-reviewer render gate 留证
• 印刷友好：16开 115mm 通栏下文字 ≥8pt 清晰可读，黑白打印可辨，文字对比度 ≥4.5:1（WCAG AA），CMYK 转换不偏色
• 配色合规（v1.5.0）：新生成图透明背景（无画布底色矩形）；从调色板 8 组选 1 组，组内模块色用于内部模块多色柔和区分（一图 4-6 色）、相邻模块不同色；文字色统一深灰；颜色只用 fill/stroke 属性内联；既有 34 张白底单色图保持稳定不回改
• 可视友好化（v1.8.7）：深底（L* ≤ 50）模块内文字走浅色 #FFFFFF/#EDF2F7（禁深底深字）；文字 vs 所在模块对比 ≥ 4.5:1；箭头落点 x2 = 目标框边 − 4px、方向指向目标；每个有标题语义的节点框都有非空 <text>、坐标在框内、fill 与模块不同色（详见 style-guide §5.5）
• 蓝色焦点 + 文字二档（v1.8.8）：文字色仅 #2D3436/#636E72（+ 深底浅字 #FFFFFF/#EDF2F7），不再用 #1A202C/#4A5568；项目 canonical 主色只焦点节点填充/描边、禁作文字 fill；每结构/流程图 ≥1 焦点节点（详见 style-guide §5.0/§5.1）
• 关系与标签卡（v1.8.11）：有含义的关系线完整保留且不压文字；分叉连续、相邻层级连接紧凑；标签卡只标题上圆角，步骤编号在独立上方带，图例面向读者（详见 style-guide §六）

源生产契约与受控渲染只是必要不充分条件——保证 SVG 可解析、画布与样式受控，不保证图正确美观。密度 + 一致性 + 目检三道审查才是验收依据（references/review-checklist.md）。