一张正在画、正在量的配图 左边是几行 SVG 源码和检查结果:class 等于 dd-card、class 等于 t-acc、图 1 先写一句论点、overflow 0 · cross 0、对比度不低于 4.5 比 1。右边一张图纸上画着分区、两张记录卡和一个虚线框,一条强调色的线索把三处串起来;图纸后面压着一张配色相反的同一张图;一把放大镜照着其中一行,镜片里是文字的虚线外框,下面是一把尺子。 <rect class="dd-card"/> <tspan class="t-acc"> 图 1 · 先写一句论点 overflow 0 · cross 0 contrast ≥ 4.5 : 1

本站每篇文章的配图,都是让 AI(Claude)直接写 SVG 代码画出来的。到 2026 年 11 月 1 日,除本文外的 64 篇文章里一共有 307 张 SVG 讲解图、184 张表格,每篇还有一张头图。常有读者问这些图是怎么画的、用的什么工具。工具其实没有什么特别的,就是让 AI 写 <rect>、<text>、<path>;画得出来,靠的是一套慢慢攒起来的画法。

这套画法不是一开始就有的。2026 年 10 月 13 日,我们让 AI 给 tmux 那篇文章补三张架构图,它交来的图 1 是这样的:本地终端、tmux 客户端、tmux 服务端,三个方框,每个方框里写着名字,下面一行小字;图注写的是“tmux 的客户端 / 服务端架构”。图不难看,可它讲不清什么:方框里的名字,正文早就说过了。打开源码,14 段文字各自带着一长串 font-family,全图 43 处 style 写着颜色,字号用了 5 种。第二天这三张图全部重画,同时写下了一份配图规则;后来的 300 多张图,都是照着这份规则、按同一套流程画的。

为什么让 AI 写 SVG 代码,而不是用生图模型?因为讲解图里的字必须一个不错:命令、路径、哈希、报文字段,生图模型画出来的字没法保证;SVG 里的字是真正的文本,能搜索、能复制。颜色写成 CSS 类,深色模式就能自动切换;文件本身是文本,改一个数字就是一行 diff,AI 和人都能逐行审。

但“写 SVG”只是手段。从 tmux 那三张图开始,我们依次碰到了这些问题:

  1. AI 每画一张图,都会把配色、字号重新决定一遍,几十篇文章的图怎么才能像一套?
  2. 文中的一个概念,怎么变成一张讲得清楚的图,而不是一排写着名字的方框?
  3. 一篇文章十来张图,怎么让它们串成一条线,而不是十张互不相干的插图?
  4. 头图、人像这类插画没有“机制”可画,AI 又画不像具体的对象,怎么办?
  5. AI 看不见自己画的图,画完怎么知道哪里有问题?

本文按这几个问题,把本站的画法整理一遍。文末附上可以直接交给 AI 的工作流程,规则文件和检查脚本都在仓库里。

一、统一的视觉语法

现象:每张图都在重新“设计”

tmux 第一版的三张图,字号分别用了 5 种、6 种和 3 种,从 8px 到 15px;每段文字都自己写一遍字体、颜色和字重。同一篇文章里的三张图已经各不相同,换一个对话、换一篇文章,AI 又会挑一组新的颜色。问题不在于它挑得不好看,而在于它每次都在挑。

解决:把“长什么样”从 AI 手里拿走

办法是把所有视觉决定提前做完,写进站点的样式表。global.css 里的 .dd 一节定义了 11 个颜色变量,浅色、深色各一套,再配二十来个样式类1。AI 画图时只写类名,不写任何颜色和字号。同一个“tmux 服务端”标签,前后两版的源码是这样的:

HTML
<!-- 第一版 -->
<text x="532" y="150.0" style="fill:var(--dd-ink)" font-size="14" font-family="'Geist', 'Noto Sans SC', 'PingFang SC', 'Microsoft YaHei', system-ui, sans-serif" text-anchor="middle" font-weight="600">tmux 服务端</text>
<!-- 重画后 -->
<text class="t-name" x="264" y="229">tmux 服务端</text>

重画后的图 1 有 33 段文字,比第一版多了一倍多,文件反而从 6,809 字节降到 4,442 字节。更要紧的是,AI 能挑的只剩下有限几个词,每个类都对应一种意思,选类就是在表态:这是一个“地方”,这是一条记录,这个东西会消失。

本站配图的几种图元 左边是用本站图元重画的 tmux 架构片段:远程服务器分区里,虚线框是随 SSH 断开退出的 tmux 客户端,记录卡是 tmux 服务端的 socket、两个会话和客户端字段,右边三个节点是被托管的进程,会话名 work 用强调色从命令一直串到客户端那一行。右边逐条说明六种图元:分区、记录卡、虚线框、强调色线索、连线、说明句各表示什么。 远程服务器 · dev@10.0.0.8 ① 图元和它的意思 Unix socket ⑤ tmux 客户端 ③ $ tmux a -t work 虚线:客户端随 SSH 断开退出, 服务端和进程照常运行。 ⑥ tmux 服务端 ② pid 2187 socket /tmp/tmux-1000/default session work · 2 windows attached session ops · 1 window detached client /dev/pts/3 → work ④ vim main.go npm run dev pytest -f ① dd-zone · 分区 一个“地方”:本机、服务器、存储桶 ② dd-card · 记录卡 一个对象的真实字段,一行一个 ③ dd-derived · 虚线框 会消失或算出来的东西,要配一句话 ④ t-acc · 线索 读者跟着走的标识符,一张图只追一条 ⑤ dd-edge · 连线 只走横竖线和 r=8 的圆角折线 ⑥ t-say · 说明句 图里看不出来的那一点,最多两句
图 1 · 图元不是装饰,每一种都表达一个意思:选哪个类,就是在说这个东西是什么

这套语法的样子参照了 Anthropic 工程博客的一张图2:暖色纸面、分区面板、等宽字体的数据行、只给一个标识符上强调色;基础图元和连线规则沿用了开源的 diagram-design3。全站 307 张讲解图里,用得最多的类是 t-mono(字段名、命令)2,787 次、t-note(注记)2,435 次、dd-card(卡片)1,737 次。

规则写成文件,每条都来自一次返工

样式类只管“长什么样”。什么时候用虚线、一张图追几条线索、表格要不要画成 SVG,这些要写成文字。本站把它们写在 .claude/skills/blog-diagram/SKILL.md 里4,仓库根目录的 CLAUDE.md 指向它,AI 每次画图前先读一遍。

这份文件不是一次写成的。翻 git 历史,每一条规则背后都是一次具体的返工:

配图规则的来历 2026 年 10 月的五次返工:13 日 tmux 第一版方框只写名字,还没有规则;14 日重画,写下真实数据、一条线索、样式只写 class;15 日 git-server 文章六段文字改成两张图,规定大段文字都要配图;17 日图在手机上横向滚动,改成整图缩小、点按放大,对照表改用 HTML;20 日列表缩略图裁掉头图右边,规定头图文字只放在左侧 280 以内。 blog-diagram/SKILL.md 是怎么攒起来的(2026 年 10 月) 10-13 10-14 10-15 10-17 10-20 tmux 第一版 方框只写名字 颜色字号逐个写 (还没有规则) tmux 重画 图注改成论点 方框换成真实字段 真实数据、一条线索 样式只写 class git-server 改图 六段文字加一张表 改成两张图 大段文字都要配图 窄屏看图 图在手机上横向滚动 整图缩小、点按放大 对照表改用 HTML 列表缩略图 按卡片高度放大 右边被裁掉 头图文字只放在 左侧 280 以内
图 2 · 规则文件里的每一条,都是某张图返工以后补上的:卡片上半是返工的原因,下半是写进文件的那句话

所以这份文件最好的写法,是每次返工都问一句:这个错下次能不能用一句话拦住?能,就把那句话写进去。只在对话里纠正 AI,下一次对话它就忘了;写进文件,以后每张图都会照着做。

样式和规则统一以后,60 多篇文章的图看起来就是一套了。可一套好看的图元,照样能拼出一张什么都没讲的图。

二、从一个概念到一张图

现象:方框里只写名字

回头看 tmux 的第一版(原样嵌在下面,只改了 id)5:

tmux 文章图 1 的第一版 2026 年 10 月 13 日 AI 交的第一版:本地终端、tmux 客户端、tmux 服务端各是一个只写着名字的方框,服务端连着 vim、npm、tail 三个进程,强调色给了 socket 那条连线,底部一句斜体说明 detach 只断开客户端。 REMOTE HOST · 远程服务器 SSH SOCKET 本地终端 iTerm2 / WT tmux 客户端 tmux attach SERVER tmux 服务端 /tmp/tmux-$UID vim main.go npm run dev tail -f log detach 只断开客户端这一段,服务端和右侧的进程照常运行
图 3 · 第一版:方框里只有名字,图注也只是一个名字,回答不了“为什么断线以后程序还在跑”

这张图的每个元素都没错,问题在于它只回答了“有哪几样东西”。读者真正的疑问是“为什么 SSH 断了,程序还在跑”,图里能回答这个问题的,只有底部那一句斜体字。方框里的“tmux 客户端”“tmux 服务端”,换成任何一个客户端 / 服务端程序都成立。强调色给了 socket 那条线,可它并不是读者要追的东西。

重画后的图 1(第一节图 1 左半边就是它的缩略版)6,改的是这几处:

  • 图注从名字换成了一句论点:“tmux 的客户端 / 服务端架构”变成“程序挂在服务端上,客户端只是一扇随时可以关上的窗”。
  • 方框里换成真实的值:服务端卡片写着 pid 2187、socket 路径 /tmp/tmux-1000/default、两个会话 work 和 ops;进程写的是 vim main.go、npm run dev。
  • 强调色只追一条线索:会话名 work 从终端里敲的 tmux a -t work,到服务端的会话记录,再到客户端那一行,读者顺着它就能走完全图。
  • 虚线有了固定的意思:只有客户端是虚线框,旁边一句话说明它随 SSH 断开退出。第一版里虚线框框的是“远程服务器”,它哪儿也不去。

这几处改动可以整理成一个从概念到图的顺序。

第一步:先写图注

动笔之前,先用一句话写出这张图要证明什么,这句话就是 figcaption。写不出来,说明还没想清楚这张图为什么存在,要么不画,要么回去把正文想清楚。

图注写成论点以后,图里每个元素就有了取舍标准:能支撑这句话的留下,和它无关的删掉。tmux 图 1 的论点是“客户端随时可以关”,所以 pid、socket、客户端那一行都要画出来,它们是“程序挂在服务端上”的证据;本地电脑用的是哪个终端模拟器,就只留一个名字。

第二步:按问题选图型

论点定了,图的形状往往也就定了,因为不同的问题有各自顺手的画法。本站反复用到的是这几种:

读者在问什么,就画成什么
读者的问题画法本站的例子
先后顺序、来龙去脉时间线git-server 图 1:Git 网络协议的几代,原来是六段文字加一张表
谁跟谁说了什么泳道 + 报文walgit 图 4:一次 push 对存储桶发 3 轮共 5 个请求,每个请求写出方法、路径和条件头
东西在哪、怎么关联分区 + 记录卡tmux 图 1;walgit 图 3:桶里每个对象的路径和字段
同一个输入,几种结果并排对照HRV 图 3:同样 16 个心跳间隔换个顺序,RMSSD 从 19 ms 变成 89 ms;git-server 图 2:同一个请求发给三种服务器
一个量怎么变化坐标图llm-why-now 图 5:训练一个模型要的运算量,和一张卡跑一天的算力,在对数坐标上交叉
几样东西逐项比较HTML 表格,不画 SVG全站 184 张表;SVG 在手机上只能整体缩小,表格能换行

这张表本身就属于最后一行:行 × 列的对照,用表格比画图清楚。

图 4 · 图型跟着问题走:先判断读者在问哪一类问题,再挑画法

“并排对照”是最有说服力的一种。HRV 那篇的开头,是两个 App 显示的 HRV 对不上;图 3 只做了一件事,把同一组数换个顺序,两个公式一个不变、一个从 19 变成 89。读者一眼就明白两个 App 为什么对不上,比正文解释三段都管用。能构造出这样一个“同一输入、不同结果”的小实验,图就成功了一半。

第三步:填真实的数据

方框里写“客户端”“某个进程”,读者得到的只是名词。写 pid 2187、/tmp/tmux-1000/default,读者能拿去和自己终端里的 ps、ls 对照,图就从“示意”变成了“证据”。

有些数据只能是编的,比如为了讲清 push 流程而虚构的提交哈希。这时就在图注里说清楚:全站 491 条图注里,有 37 条带着“哈希为示例”“数值为示意”这类说明。

第四步:一条线索,虚线要解释

强调色是一张图里最贵的东西。本站的规则是一张图只追一条线索,这条线索可以在图里出现很多次,但不能出现第二条。307 张讲解图里有 305 张用了强调色,几乎每张都有一条读者可以跟着走的线。

虚线框也只有一个意思:派生出来的、会消失的、或者存在但不在场的东西,并且旁边必须有一句话说明它为什么是虚线。规则写得这么死,是因为虚线一旦用来“装饰”,读者就不知道哪些虚线是有意义的了。

把这四步交给 AI,最有效的做法是让它先交一份图的说明书,再写 SVG:这张图的图注是哪句话、画成哪种图型、方框里放哪些真实数据、线索追哪个标识符。说明书对了,SVG 很少出大错;说明书不对,画得再精致也要重来。

一张图讲清楚了,可一篇文章往往有十来张图。

三、让一组图串起来

现象:十张图,十套例子

walgit 那篇讲一个把 Git 仓库存进对象存储的服务器,一共 10 张图:从“为什么不能让 git 直接读桶”,到一次 push、并发 push、读路径、压缩、崩溃恢复。如果每张图各编各的例子,这张图的提交叫 abc123,下一张叫 def456,读者每看一张新图,都要重新认一遍里面的东西是什么。

做法:一套贯穿全文的示例数据

walgit 那篇的做法是,先定下一套示例数据,所有图都从里面取:仓库在 repos/acme/app/,唯一会被改写的对象是 manifest.pb,它的版本从 v41 变到 v42,这次 push 占用日志序号 42,写进 log/…2a.pb(0x2a 就是 42),新上传的包是 9c1e…,main 从 5be1… 变到 0a77…。把每个标识符在 10 张图里出现的位置画出来:

walgit 文章的 10 张图共用一套示例数据 七行是七个示例标识符,十列是十张图。manifest.pb 出现在 8 张图里,用强调色标出;v41 到 v42 出现在 5 张,日志序号 42 出现在 6 张,pack 9c1e 和 b4f0 各 4 张,main 的新旧值 4 张,仓库路径 4 张。图 2 是总图,七个标识符里出现了五个。 walgit-architecture 的 10 张图里,示例数据出现在哪 图 1 图 2 图 3 图 4 图 5 图 6 图 7 图 8 图 9 图 10 读文件 总图 桶布局 push 并发 批量 读路径 远程读 压缩 崩溃 repos/acme/app/ 仓库路径 manifest.pb 唯一可变对象 v41 → v42 manifest 版本 seq 42 · …2a.pb 日志序号 9c1e… 这次 push 的包 b4f0… 历史大包 5be1… → 0a77… main 新旧值 manifest.pb 在 8 张图里出现,其中 5 张的强调色追的就是它。
图 5 · 一组图共用一套示例数据:同一个 v42、同一个 9c1e…,在第几张图里出现都是同一个东西

读者在图 2 里第一次见到 manifest.pb ETag v42,到图 4 的 push、图 5 的并发、图 7 的读路径,看到的还是这个 v42,只是换了个角度。示例数据固定下来,读者就只需要关心每张图里新出现的那一点。

除了共用数据,这一组图还有几个配合的地方:

  • 先总图,后局部。 图 2 是“整体形状”:客户端、三台实例、一个桶,七个标识符里出现了五个;后面每张图放大其中一块。multica 那篇也是这样,图 1 先画一条 @ 引起的全部通信,后面逐段展开。
  • 同一样东西,每张图里画法一样。 manifest.pb 在图 2、4、5、6、10 里都用强调色标出,读者一看颜色就知道“又是它”。
  • 图注连起来读,就是全文的论证。 walgit 的 10 条图注,从“读一个文件要串行跳好几次”到“提交点之前死掉,留下的只是没人引用的垃圾”,单独读一遍,就能知道这篇文章讲了什么。
  • 正文引用图里的值。 正文写“图 4 里的 v41、v42 就是 manifest 的 ETag”,图和文字说的是同一个东西,读者在两边来回看也不会迷路。

落到给 AI 的指令上,就是在画第一张图之前,先让它写出全文共用的示例数据表:主机名、路径、ID、哈希、数字,各取什么值。之后每张图都只能从这张表里取。

讲解图有机制可画,规则也就写得出来。头图和插画就不一样了。

四、头图与具体对象

头图:一个场景,几处真实细节

头图不讲机制,它要用一个场景把文章的主题“演”出来。go-project-layout 那篇的头图,第一版是几张卡片,写着 $ ls kubernetes/、ls | grep controller 和几行目录,其实是一张缩小的讲解图;重画以后是一排货架上的四个盒子:一个装着三层叠放的纸板(分层),一个上面绕着首尾相接的圆环(控制循环),一个上面立着高矮不一的竖条(平铺的功能包),一个是三个小方块被一条带子扎在一起(多 module)。四个仓库的目录结构,变成了四种摆放东西的方式。

头图的约束主要来自它被显示的地方。文章列表里,头图按卡片高度放大、靠左对齐,右边被裁掉,所以文字只能放在左侧 280 以内,右侧只放图形,被裁掉也不影响;缩略图会剥掉 id,所以头图里不能用渐变、marker、clipPath 这些要靠 url(#…) 引用的东西,渐变感只能用半透明色块叠出来。这些都写进了规则文件,AI 不用每次重新踩坑。

具体对象:先找参照,再照着画

头图和插画还会碰到另一类难题:画一个具体的对象。让 AI 不带任何参照画一张鲁迅像,结果是圆脸、平头、两撇小胡子,换任何一个留胡子的男人都成立。AI 对“鲁迅长什么样”只有几个文字标签(短发、浓眉、一字胡、长衫),画出来自然是标签的拼凑。认出一个人靠的是比例和轮廓,这些写不成几个词。

所以要先给它找一张画着这个对象本身的图当参照,按这个顺序找:

  1. 先搜现成的 SVG。Wikimedia Commons 搜索时加 filetype:drawing 只看矢量图7;Openclipart 的 18 万幅图全部是公有领域8。鲁迅在两处都搜不到肖像,爱因斯坦、林肯这类西方名人则能搜到不少。
  2. 搜不到,就找公有领域的照片。Commons 上有一张 1930 年在上海拍的照片,文件页写明在中国和美国都属于公有领域9。后人画的肖像、木刻要小心,画家去世不满 50 年的还在版权期内。
  3. 避开写了 AI 禁令的素材站。unDraw 的许可禁止把插画“用来训练、验证或测试 AI 系统”10,DrawKit 禁止用于训练或改进 AI 模型11。贴进 prompt 当参照算不算这些条款里的“使用”,条文没说清,既然有公有领域的可选,就不碰它们。
  4. 图标例外。热门图标库被转载过无数次,AI 早就记住了:让它“按 Lucide 的风格画一个云上传图标”,箭头的路径和 Lucide 原版一字不差。图标先到 Iconify 按名词搜12,搜到了、许可允许就直接用,不必让 AI 重画。

找到照片以后,用开源的描摹工具 vtracer13 把它描成矢量:先中值滤波去噪、把灰度压成 3 档、把背景涂白,结果是 22 条路径。可直接用描摹结果是不行的(图 6 中间):它本质上是照片加了一层色调分离滤镜,衣服上一块块灰斑,下巴的阴影被描成了一大把络腮胡,而鲁迅只有一字胡。

描摹结果真正有用的是位置:发际线在哪、眉眼间距多大、胡子多宽、肩膀多斜,这些正是 AI 凭空画不准的。于是把它当成垫在下面的底稿,量出关键位置(440 像素宽的画面里,发际线 y≈56,眼睛 y≈110,胡子 y≈158–182,下巴 y≈210),再用干净的路径从头画,轮廓线统一 3 像素,平涂只用四种颜色,最后拿掉底稿。每画一轮就和照片并排渲染对照:头发画成光滑的圆顶不像板寸,改平顶又成了锯齿,最后只留一点起伏;眼睛画成圆眼珠显得在吃惊,照片里他眯着眼,改成眼皮压住的半个眼珠。

同一个 AI 画的三张鲁迅像 左:不给参照直接写 SVG,圆脸、平头、两撇小胡子,像任何一个留胡子的男人。中:把 1930 年的公有领域照片用 vtracer 描摹成矢量,比例对了,但只是一片片灰斑,下巴的阴影被描成了络腮胡。右:把照片和描摹当底稿,量出发际线、眉眼、胡子、下巴和肩线的位置,再用干净的路径重画:直立的板寸、浓眉、一字胡、立领长衫,3.1 KB、28 个元素。 不给参照,直接画 描摹出的底稿 照着底稿重画 圆脸、小胡子、平头, 换个名字也成立 比例对了,但只是一片灰斑; 圈里的阴影成了络腮胡 板寸、浓眉、一字胡、立领, 位置全从底稿上量
图 6 · 同一个 AI 画的三张鲁迅像:没有参照画不像,直接用描摹结果不好看,把描摹当底稿重画才两头都顾上

三张图是同一个 AI 画的。底稿解决“像不像”,重画解决“好不好看”,两步缺一不可。

到这里,图已经画出来了。可无论是讲解图还是插画,AI 交出 SVG 的那一刻,它其实没有“看见”过这张图。

五、画完怎么验证

现象:AI 看不见自己画的图

AI 写 SVG 时是在算坐标:这段字从 x=52 开始,大概多宽,卡片右边在哪。规则文件里给了估算办法(中文每字 1em,12px 等宽字符每个约 7.2px),可估算总有误差,字体也因机器而异。结果就是一类类反复出现的毛病:文字伸出卡片,连线从标签上穿过,两个标签挤成一串,深色模式下某段字几乎看不见。这些在源码里看不出来,Markdown 预览和 GitHub 的 diff 也不渲染内联 SVG。

第一层:构建

npm run build 能拦下结构上的错:引用了不存在的参考资料、类号不在分类表里。不过要看日志,不能只看退出码:写这篇文章时,一条参考资料没被正文引用,日志里打出了 ERROR,npm run build 的退出码却是 0,这篇文章直接从站点上消失了。还有一类结构错构建根本不报:<svg> 中间留了空行,Markdown 会把它拆成段落,构建照样通过,页面上整张图却碎了。这些都要到浏览器里才看得出来。

第二层:脚本检查

构建通过的图,还要在浏览器里量一遍。浏览器知道每段文字实际渲染出来有多宽:getBBox() 给出元素的外框14,getPointAtLength() 能沿一条路径取点15,getComputedStyle() 能拿到深色模式下实际生效的颜色,再按 WCAG 的公式算出对比度16。我们用 Playwright17 打开构建好的每一篇文章,在浅色、深色两种模式下逐张检查18:

检查脚本怎么判断四类问题 四个面板。一:用 getBBox 得到文字的外框,和所在卡片的右边比较,外框超出就是溢出。二:沿连线每 2 个单位取一个点,落进文字外框的点说明连线从字上穿过。三:同一基线上的两段文字,外框间隔不到 3 个单位,读起来就连成了一串。四:按 WCAG 公式算文字色和底色的对比度,半透明的底色要先和下面一层混合,强调色文字压在 22% 不透明度的强调色面积上,浅色模式只有 3.72 比 1。 ① 溢出:文字外框超出卡片 ② 穿字:沿连线每 2 个单位取一个点 ③ 挨太近:同一基线,间隔不到 3 ④ 对比度:按 WCAG 公式计算 513100 昨收 → 11:30 超出 6 bbox.x + bbox.width > 卡片右边 实例:nasdaq-etf-overnight 图 3 w = 1.8,L = 5.76 橙色的点落进了文字外框(图里画得比实际稀) 实例:transformer-training-by-hand 图 1 1847 梯度下降 1948 信息论 间隔 2 改法: 1847 梯度下降 1948 信息论 实例:llm-why-now 图 7 实际请求:只有这部分有收入 浅色 3.72 : 1 深色 4.11 : 1 要求 4.5 : 1;半透明的底先和下层混合再算 实例:gpu-api-resale 图 3
图 7 · 脚本不看图,它量浏览器算出来的外框和颜色:虚线框就是 getBBox 给出的文字外框,橙色是超标的那一段

除了这四项,脚本还在源码层面查三件事:元素上有没有直接写颜色值(写死的颜色不会跟着深色模式变);同一个页面里有没有重复的 id;头图里有没有 title、desc 以外的 id。重复 id 的后果比看上去严重:我们曾在一个页面里先后内联两张都被 svgo 压缩过的图,两张里都有 id="a",后一张的渐变引用 #a 时取到了前一张的,结果有 1,674 个像素和单独渲染时不一样。所以本站每张图的 id 都带着这篇文章的前缀,外来的 SVG 用 svgo 的 prefixIds 加前缀19。

全站跑一遍

把脚本在除本文外的 64 篇文章上跑了一遍,307 张讲解图、64 张头图,浅色、深色各一次。报警的图再逐张截图,人工判断是真问题还是误报:

307 张讲解图的检查结果(2026-11-01,按“图 × 检查项”计)
检查项报警真问题轻微误报典型情况
穿字181341walgit-vs-continuity 图 2:骤降的数据线正好穿过它自己的标签“925 → 2”,读成了“9|25”
溢出3300quickjs-embedding 图 1:一行代码伸出卡片约 20,右花括号落在框外
重叠3210ilya-30u30 图 4:坐标刻度“d=384 · 354万”撞上图例“训练集(虚线)”
挨太近1100llm-why-now 图 7:“1847 梯度下降1948 信息论”
对比度4130轻微的都在 4.0–4.4 之间;真问题是一段写死的白字,深色模式下只有 3.27
写死颜色1100就是上一行那段白字:style="fill:#fff" 不跟着深色模式变
伸出分区10316误报最多:泳道图里的报文标签本来就横跨两个分区
合计(按图)362196一张图可能同时报几项,所以按图计的合计小于各行之和

64 张头图另有 12 张报警,逐张看过,没有一处算真问题:头图是插画,印章、头像上的字本来就压在色块上。

图 8 · 307 张图里,脚本报出 36 张,人工看过以后 21 张确实有毛病:最准的是“穿字”,最吵的是“伸出分区”

按规则,这些图发布前都要截图看过,可 21 张图里的毛病还是漏过去了。原因不难猜:一条线从标签边上擦过去、一个括号伸出卡片 6 个单位,缩小到手机宽度上看不出来,人眼扫一遍也很容易放过;脚本不会累,每张图每段字都量一遍。

误报也有规律。“伸出分区”报了 10 张,6 张是误报,因为泳道图里的报文标签本来就横跨两个分区,脚本分不出这是故意的;“穿字”只有 1 张误报:那条连线被一块填了底色的分区盖住了,屏幕上看不见,第一版脚本没把分区算作遮挡,后来改掉了。所以脚本的报警只是待办清单,每一条都要截图看过再改。故意画出来的反例(比如图 7 这四个面板)包在 <g data-check="skip"> 里,脚本就会跳过。

第三层:看截图

脚本只能查“量得出来”的错。这张图有没有证明图注那句话,线索能不能从头走到尾,比例看起来别不别扭,这些还得看。本站的做法是让 AI 自己看:把每张图在浅色、深色、手机宽度下截图,交给它读图,对照规则文件里的出图前检查清单逐条过,有问题就改,改完再截。鲁迅像那几轮“头发像王冠”“眼睛像在吃惊”,就是在这一步发现的。最后一遍由人看。

六、交给 AI 的工作流程

把前面几节合起来,本站让 AI 画一篇文章的配图,是按这个顺序走的。下面这段可以直接当作 prompt 的骨架,规则细节放在单独的规则文件里,让 AI 先读:

先读 .claude/skills/blog-diagram/SKILL.md 和 src/styles/global.css 的 .dd 一节,
只用其中的样式类,SVG 里不写任何颜色值和字号。
一、先交说明书,不要直接画:
1. 列出全文共用的示例数据:主机、路径、ID、哈希、数字,各取什么值。
之后每张图都只从这张表里取,编出来的值在图注里写明“为示例”。
2. 逐节找出连续三段以上的纯文字,判断能不能画成图。
3. 每张图写一份说明:
- 图注:这张图要证明的一句话;
- 图型:时间线、泳道、分区 + 记录卡、并排对照、坐标图;行 × 列的对照用 HTML 表格;
- 方框里放哪些真实数据;
- 强调色追哪一个标识符(只能一个);哪些东西画成虚线框、为什么。
先画总图,再画局部。
二、说明书确认后再画:
1. viewBox 宽 800,坐标落在 4 的网格上,id 都加上本文的前缀。
2. 画图顺序:外框 → 分区 → 连线 → 卡片 → 文字。
3. 具体对象(人像、建筑、器物)先找公有领域的参照,描成底稿量位置,再重画。
三、画完自己验证:
1. npm run build 通过。
2. 跑 svgcheck.py,每条报警都截图确认:真问题改掉,误报写明原因;
故意画出来的反例用 <g data-check="skip"> 包起来。
3. 截浅色、深色、手机宽度三张图,自己看一遍:
图有没有证明图注那句话?线索能不能从头走到尾?
4. 有问题就改,改完重新跑第 2、3 步。

这个流程里最省事的一步,是“先交说明书”。说明书只有几行字,改起来比改 SVG 便宜得多;图注、图型、数据、线索这四样定下来,后面的 SVG 基本就是按格子填空。

小结

  1. 为什么让 AI 写 SVG 代码? 图里的字是真实文本,命令和哈希一个字符都不会错;颜色写成类就能跟着深色模式切换;文件是文本,改动能逐行审。
  2. 怎么让几十篇文章的图像一套? 把颜色、字号这些视觉决定提前写进样式表,AI 只挑类名,每个类对应一种意思;什么时候用虚线、一张图追几条线索,写进规则文件。规则文件的每一条都来自一次返工。
  3. 一个概念怎么变成一张图? 先写图注,一句论点;再按读者的问题选图型;方框里填真实数据,编的值标明是示例;一张图只追一条强调色线索,虚线框必须解释。最有效的是让 AI 先交说明书再画。
  4. 十几张图怎么串起来? 全文共用一套示例数据,先总图后局部,同一样东西每张图里画法一样,图注连起来读就是全文的论证。
  5. 头图和具体对象怎么办? 头图用一个场景把主题演出来,约束来自它被显示的地方。具体对象先找公有领域的参照,描成底稿只用来量位置,再让 AI 按本站的风格重画,一轮轮和原图对照。
  6. 画完怎么验证? 三层:构建拦结构错,浏览器里的脚本量溢出、穿字、挨太近和对比度,截图交给 AI 和人看脚本量不出来的东西。全站跑一遍,脚本确实能找出肉眼漏掉的问题,也会误报,报警要逐张看。

参考资料

Footnotes

  1. twwy.net:src/styles/global.cssGitHubgithub.com ↗.dd 一节是配图用的颜色变量和样式类,浅色、深色各一套。https://github.com/0cloud-ai/twwy.net/blob/main/src/styles/global.css ↩

  2. Redesigning source controlAnthropic Engineeringanthropic.com ↗本站配图风格的参照:文中 “Shape of a Scion changeset” 那张图的暖色纸面、分区面板、等宽数据行和单一强调色。https://www.anthropic.com/engineering/redesigning-source-control ↩

  3. diagram-designCathryn Lavery · GitHubgithub.com ↗给 Claude Code 等编程助手用的编辑风格图解规则,本站的基础图元和连线规则沿用它。https://github.com/cathrynlavery/diagram-design ↩

  4. twwy.net:.claude/skills/blog-diagram/SKILL.mdGitHubgithub.com ↗本站的配图规则文件,AI 每次画图前先读它。https://github.com/0cloud-ai/twwy.net/blob/main/.claude/skills/blog-diagram/SKILL.md ↩

  5. tmux 指南:补充三张架构图(第一版)GitHubgithub.com ↗2026-10-13 的提交,图 3 就是它的原样。https://github.com/0cloud-ai/twwy.net/commit/ff247bc3837cecadcdb5b2ee7b53d0ef054741a2 ↩

  6. tmux 指南:按新配图规则重画三张图,并新增 blog-diagram 规则GitHubgithub.com ↗2026-10-14,规则文件第一次出现。https://github.com/0cloud-ai/twwy.net/commit/b8cd6dfc912f9de7450b54502fce0a26bcedeb8a ↩

  7. Help:CirrusSearch:filetypeMediaWikimediawiki.org ↗在 Commons 搜索里加 filetype:drawing 只返回 SVG 等矢量图。https://www.mediawiki.org/wiki/Help:CirrusSearch#Filetype ↩

  8. Openclipart ShareOpenclipartopenclipart.org ↗18 万余幅矢量图,全部放入公有领域。https://openclipart.org/share ↩

  9. File:鲁迅“五十岁纪念”时所摄 1930年9月17日摄于上海.jpgWikimedia Commonscommons.wikimedia.org ↗文件页标注在中国和美国均属公有领域;图 6 的鲁迅像以它为底稿。https://commons.wikimedia.org/wiki/File:%E9%B2%81%E8%BF%85%E2%80%9C%E4%BA%94%E5%8D%81%E5%B2%81%E7%BA%AA%E5%BF%B5%E2%80%9D%E6%97%B6%E6%89%80%E6%91%84_1930%E5%B9%B49%E6%9C%8817%E6%97%A5%E6%91%84%E4%BA%8E%E4%B8%8A%E6%B5%B7.jpg ↩

  10. unDraw LicenseunDrawundraw.co ↗禁止用作 AI 训练数据、禁止“用来训练、验证或测试 AI 系统”,也不能未经同意自动抓取。https://undraw.co/license ↩

  11. DrawKit LicenseDrawKitdrawkit.com ↗不能用于训练、微调或改进任何 AI 模型。https://www.drawkit.com/license ↩

  12. Iconify API:/searchIconifyiconify.design ↗按关键词搜图标,每套图标带 license 字段;单个 SVG 从 /<前缀>/<名字>.svg 取。https://iconify.design/docs/api/search.html ↩

  13. vtracerGitHub · visioncortexgithub.com ↗把位图按颜色分块、拟合成曲线的开源描摹工具,有 Python 包。https://github.com/visioncortex/vtracer ↩

  14. SVGGraphicsElement: getBBox()MDNdeveloper.mozilla.org ↗https://developer.mozilla.org/en-US/docs/Web/API/SVGGraphicsElement/getBBox ↩

  15. SVGGeometryElement: getPointAtLength()MDNdeveloper.mozilla.org ↗https://developer.mozilla.org/en-US/docs/Web/API/SVGGeometryElement/getPointAtLength ↩

  16. Understanding Success Criterion 1.4.3: Contrast (Minimum)W3Cw3.org ↗正文文字 4.5:1;18pt 以上,或 14pt 以上的粗体,3:1。https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html ↩

  17. Playwright for Python:ScreenshotsPlaywrightplaywright.dev ↗https://playwright.dev/python/docs/screenshots ↩

  18. twwy.net:thinkbox/svg-resources/svgcheck.pyGitHubgithub.com ↗本文第五节用的检查脚本,Python + Playwright。https://github.com/0cloud-ai/twwy.net/blob/main/thinkbox/svg-resources/svgcheck.py ↩

  19. SVGO:prefixIdsSVGOsvgo.dev ↗给每个文件的 id 和引用统一加前缀,避免内联后撞名。https://svgo.dev/docs/plugins/prefixIds/ ↩