一張正在畫、正在量的配圖 左邊是幾行 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 和人看指令碼量不出來的東西。全站跑一遍,指令碼確實能找出肉眼漏掉的問題,也會誤報,報警要逐張看。

參考資料

參考資料

  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/ ↩