图表与配色规范

本仓库所有文档图表（mermaid / SVG / labs 生成图）遵循本规范，配色取自 Claude 官网风格。

调色板

角色	变量名	色值	用途
主色	primary	#D97757	强调、热路径、主曲线
辅色	secondary	#D4A27F	次要元素
填充	fill	#EBDBBC	面板填充、网格线
背景	bg	#FAF9F5	画布背景
文字	ink	#191919	文字、坐标轴、边框
冷色	cool	#6A9BCC	对照项、数据流
灰	muted	#8A8A85	参考线、弱化元素

mermaid 模板

每个 mermaid 图开头插入以下 init（复制即用）：

三类图的分工

1. 流程/结构图 → mermaid（走上面模板）；
2. 计算类数据图（曲线、采样、对比实验）→ 必须由 labs/ 脚本生成 SVG 到 docs/assets/generated/，保证图和数学一致、可复现；
3. 几何示意图（坐标系、变换演示、色域三角形等）→ 同样由 labs/ 脚本生成。

第 3 类原先规定手写 SVG，自 M1 重构起改为脚本生成：手写图与正文里的具体数字容易失配，而教材式行文大量依赖"图和算例说的是同一组数"，脚本生成能保证两者同源可复现。

例外：引用外部图

上面那条"所有图都由脚本生成"有一类例外：脚本原理上做不出来的图。matplotlib 画得出几何示意和数据曲线，画不出真实世界的照片，也画不出真实渲染器的输出—— 而"投影到底把画面变成什么样"这种事，读者最需要看的恰恰是后者。这类图允许从 外部教程引用。

收录标准（三条都要满足）：

1. 脚本做不出来：真实照片、真实软件的渲染截图、经典教材的标志性画法。 凡是几何示意图或数据图，一律自己画——这类图必须和正文的数字同源。
2. 补的是缺口，不是替换：外部图和自绘图各干各的活，不能是同一张图的两个版本。
3. 来源可查、许可允许。

引用规则：

• 必须下载到 assets/external/，不外链。外链会随对方改路径而全挂，也让文档 没法离线读。文件名统一 <来源>-<原文件名>.png。
• 必须在 external/SOURCES.md 登记：原始地址、作者、 下载日期、许可。
• 必须在正文图注里写出来源并给链接，不能让读者以为是本仓库自绘的。
• 图内文字保持原样，不汉化——引用就该是原样，改图会破坏引用的真实性； 英文标注在图注里译出。这是"图内文字用中文"那条规则唯一不适用的地方。

图内文字

图内文字用中文。 labs/common/plotstyle.py 的 use_style() 会自动选用本机可用的中文字体（优先 Noto Sans CJK SC），并把 SVG 里的文字转成路径轮廓（svg.fonttype="path"），因此生成的图在任何机器上打开都能正确显示，不依赖阅读者本地装了哪套字体。

本机若一套中文字体都没有，use_style() 会直接抛错而不是静默画出豆腐块——图里全是方框的 SVG 一旦提交进仓库，很难在 review 时发现。Debian/Ubuntu 安装：sudo apt install fonts-noto-cjk。

（此前规定"图内文字一律用英文"，成因是当时 matplotlib 没有可用的中文字形；成因已消失。M2/M4 的存量插图仍是英文，重跑对应脚本时会自然转成中文，不单独安排改造。）

中文标点约定

正文中的引用、强调、术语首现等一律使用直双引号 "..."（ASCII U+0022，与模块一 03–09 篇的实际写法一致），不使用直角引号 「」，保持全系列风格一致。（模块一 01–02 篇曾用直角引号，属早期风格漂移，自模块二起统一为直双引号。）

labs 用法

python3 -m pip install -r labs/requirements.txt
python3 labs/m1/lab_06_interp.py        # 重新生成第 6 篇的插图

每个脚本可从任意目录运行，输出文件名与文档引用一一对应（m1-<篇号>-<主题>.svg）。