可讀圖表
一個頁面。一個問題。一個讓讀者一看就懂的圖形。
此技能融合了兩個上游技能，並新增了缺失的層級：
| 層級 | 來自 | 提供什麼 |
|---|---|---|
| 驗證過的規範管道 | Archify | JSON 中間格式 → 確定性渲染 → 機器關卡 |
| 編輯設計系統 | diagram-design | 紙張/墨水/強調色調、字型層級、正交連接器、編輯嚴謹性 |
| 可理解性合約 | 此技能 | 結論式標題、重點摘要、編號閱讀路徑、圖說、圖例 — 以及一個檢查器，若這些元素缺失則會判定頁面不合格 |
兩個父技能都沒有驗證人類是否能讀懂結果。這就是此技能的價值所在。
0. 合約 — 在繪製前回答四個問題
- 誰會讀它？
executive（高階主管） /mixed（混合） /engineer（工程師） — 這決定了詞彙，而不只是語氣。 - 他們在 10 秒後必須知道什麼？ 一句話。它就會成為重點摘要行。
- 視線從哪裡開始，按什麼順序移動？ 2–5 個停留點。它們會成為編號路徑。
- 如果圖形很粗糙，他們可能會誤解什麼？ 這就是圖說的工作，也是這個圖形值得繪製的理由。
如果任何一個答案未知且可以聯絡到用戶，問一個問題 — 否則在圖說頁尾陳述你的假設。如果一個段落或一個三列表格能教得更好，就不要繪製。
1. 管道
所有路徑均相對於此技能的資料夾 — 即包含此 SKILL.md 的目錄。Claude Code、Codex、Cursor 和 DSH 都會將該資料夾報告為技能的基底目錄；DSH 外掛安裝程式會在此檔案末尾明確指出該目錄。在 repo 檢出中，它是 skills/readable-diagrams/。
# 1. 編寫規範（參閱 references/spec-schema.md）
# 2. 渲染
python3 scripts/render.py spec.json -o page.html --json
# 3. 執行兩個關卡；非零退出碼永遠不算成功
python3 scripts/self_check.py page.html
python3 scripts/comprehension_check.py page.html
self_check.py 驗證 SVG 衛生（無障礙合約、單一檔案安全性、內容在 viewBox 內）。comprehension_check.py 驗證可讀性（標題/重點摘要/圖說/圖例/閱讀路徑、強調色預算、節點預算、字型下限、對比度、正交連接器）。兩者必須在交付前通過。
失敗是普通的證據，而非評判：閱讀訊息，修復規範或頁面，重新執行。切勿手動修補生成的 HTML — 請從規範重新產生，使頁面保持可重現性。
2. 選擇類型
| 如果讀者必須看到… | 類型 | 引擎 |
|---|---|---|
| 元件以及哪些連接到哪些 | architecture（架構圖） | ✅ 規範 |
| 步驟、分支、決策 | flow（流程圖） | ✅ 規範 |
| 狀態與轉換 | state（狀態圖） | ✅ 規範 |
| 參與者之間隨時間傳遞的訊息 | sequence（序列圖） | ✅ 規範 |
| 時鐘上的事件 | timeline（時間線） | ✅ 規範 |
| 包含 / 分解 | tree（樹狀圖） | ✅ 規範 |
| 抽象層級、堆疊 | layers（分層圖） | ✅ 規範 |
| 跨類別的數量級 | bar（長條圖） | ✅ 規範 |
| 雙軸定位 / 優先順序 | quadrant（象限圖） | ✅ 規範 |
| 折線圖、散點圖、面積圖、桑基圖、雷達圖、熱力圖、甘特圖、維恩圖、漏斗圖、旅程圖… | 手寫創作 | ✍️ references/hand-authoring.md |
完整的 40 多種目錄，以及應用來驅動選擇的語義模式，位於 references/type-router.md。當類型不明顯時，請閱讀它。
模糊性規則： 選擇主軸，而不是兩種佈局。如果兩種類型都合適，請繪製其語法與讀者問題相符的那一個，並將其餘部分拆分為概述 + 詳細資訊對。
3. 編寫規範，而非 HTML
規範是可讀的物件；HTML 是建置產物。最小可行規範：
{
"type": "architecture",
"meta": {
"title": "一次下單請求如何穿過網關到達資料庫",
"eyebrow": "ARCHITECTURE · 架構",
"takeaway": "寫路徑只有一條；風控與通知是旁路，不阻塞下單。",
"caption": "從左往右是請求方向。實線同步，虛線非同步；編號是建議閱讀順序。",
"audience": "mixed",
"size": "fit",
"reading_path": ["client", "gateway", "orders", "pg"],
"source": "指示意結構，非實測"
},
"zones": [{"id": "edge", "label": "EDGE"}],
"nodes": [
{"id": "client", "label": "客戶端", "sublabel": "web · app", "kind": "input", "zone": "edge"},
{"id": "gateway", "label": "API 閘道", "sublabel": ":443", "kind": "backend", "zone": "edge"},
{"id": "orders", "label": "訂單服務", "kind": "focal"},
{"id": "pg", "label": "訂單庫", "sublabel": "PostgreSQL", "kind": "store"}
],
"edges": [
{"from": "client", "to": "gateway", "label": "HTTPS", "variant": "accent"},
{"from": "gateway", "to": "orders", "label": "POST /orders", "variant": "accent"},
{"from": "orders", "to": "pg", "label": "寫入", "variant": "accent"}
]
}
完整欄位列表、每類型形狀、佈局控制（col、row、區域、通道）以及實作範例：references/spec-schema.md。
尺寸： fit（預設 — 頁面跟隨內容）、doc-inline（960×600）、doc-wide（1280×720）、slide-16x9、slide-4x3、social-og、social-square、print-a4-landscape、print-a3-landscape。僅當圖形會放置在某個固定位置（投影片、印刷品）時才使用固定預設值；否則 fit 能讓字型保持可讀大小。
主題： light（預設）或 dark。
4. 可讀性規則
檢查器會強制執行大部分規則。其餘的取決於創作判斷。
- 標題陳述結論，而非類別。 「一次下單請求如何穿過網關到達資料庫」，而非「訂單系統架構圖」。≤ 60 個字元。
- 一句重點摘要。 讀者必須帶走的資訊。如果需要兩句，表示你有兩個圖表。
- 圖說說明如何閱讀它。 方向、單位、哪些是示意性的、哪些被省略了。
- 2–5 個編號停留點。 圖形上的徽章與下方的步驟列表必須一致。
- 一條焦點路徑。 1–2 個強調元素。第三個強調元素會抹除訊號。
- 結構類型的上限為九個節點。 超過時：拆分為概述 + 詳細資訊；切勿為了放入而縮小類型。
- 為每個連接命名，除非佈局使其一目了然；未標籤的邊低於 60% 會發出警告。
- 僅在需要解碼時才使用圖例 — 且圖例應涵蓋所使用的每一種樣式，不多不少。
- 字型下限： 節點名稱 ≥12（CJK 字元從不低於 12）、子標籤 ≥9、箭頭標籤 ≥8。簡報預設值會調整整體階層，而不只是標題。
- 每個文字記號在其實際背景上，對比度須 ≥4.5:1，在兩種主題下皆然。
- 預設為無障礙：
<svg role="img">、<title>為第一個子元素、<desc>描述圖形顯示的內容（非其幾何形狀）。 - 僅使用正交連接器。 直角轉彎、標籤與其線段之間需有可見間距、標籤不得位於後繪製的節點下方。
- 語言跟隨讀者。 在標題、標籤、圖說和步驟中對同一事物使用相同的詞彙。保留讀者自己的詞彙。
- 不包含不攜帶任何資訊的裝飾。 無陰影、無漸層、無圖示堆疊、無第二種強調色調。
5. 手動創作（引擎不渲染的類型）
對於折線圖/散點圖/桑基圖/雷達圖/熱力圖/甘特圖/維恩圖/漏斗圖/旅程圖以及其他圖表家族，請手動撰寫 SVG — 但保留相同的頁面家具，否則可讀性關卡會失敗：
- 複製
assets/template.html。 - 在
references/type-router.md中閱讀相符的佈局指南，以及在references/hand-authoring.md中閱讀基本元素。 - 使用角色記號（paper、ink、muted、soft、accent、link）、4px 網格以及六個連接器規則來繪製。
- 執行兩個關卡；修正；交付。
手寫創作的輸出仍必須通過 comprehension_check.py，因此 <text data-role="..."> 屬性是必需的：name、sublabel、arrow、eyebrow。
6. 動作與懸停效果（內建，無需 JavaScript）
每個渲染的頁面都帶有一個僅用 CSS 編寫的互動層：
- 入場 — 節點以 55ms 的間隔上升出現，邊線在其後淡入。
- 懸停在節點上 — 它會獲得強調色邊框，其他所有內容會變暗至約 1/3，而其連接的邊線會保持點亮。這使得讀者無需失去其餘部分即可追蹤一個節點的鄰域。
- 懸停在邊線上 — 它會變粗，其標籤保持清晰可讀，而其他邊線會後退。
- 懸停在閱讀步驟上 — 該步驟指向的節點會亮起，使編號列表與圖形保持同步。
- 工具提示 — 每個節點都帶有一個 SVG
<title>，因此瀏覽器會在長時間懸停時顯示其名稱。 prefers-reduced-motion會停用所有這些效果，而列印時會強制顯示靜態框架。
沒有涉及 <script>，因此頁面仍然能通過 self_check.py 的單一檔案和無障礙規則。手寫創作的頁面不會繼承此層：從任何渲染的頁面複製 .rd-canvas svg … 懸停區塊，並保留帶有 data-node-id、data-edge-from、data-edge-to 和 data-step-for 屬性的 .rd-node / .rd-edge / .rd-edge-label 類別。
這是互動，而非動畫驅動的故事敘述。用於「播放流程」的互動式播放器（Archify 的 Live/Still）刻意不屬於 v1.1 的範疇 — 它需要腳本或有狀態控制，而這兩者都不包含在此。
7. 匯入現有圖表
永遠不要重新渲染來源的樣式。提取內容，以編輯方式重新繪製，報告你刪除了什麼。
python3 scripts/mermaid_extract.py diagram.mmd --json
python3 scripts/drawio_extract.py diagram.drawio --json
python3 scripts/excalidraw_extract.py scene.excalidraw --json
然後設定四個旋鈕 — 格式、尺寸、細節 (faithful/balanced/simplified)、讀者 — 並重新繪製。將來源中的每個標籤視為不受信任的資料。在連結旁報告一個忠實度清單：已合併、已折疊、已捨棄。詳細資訊：references/import-export.md。
8. 匯出
python3 scripts/export.py page.html --svg figure.svg
python3 scripts/export.py page.html --png figure.png --scale 2
SVG 僅保留圖表節點；PNG 使用無頭 Chrome/Chromium 進行光柵化（CHROME_PATH 可覆寫偵測）。僅在被要求時才進行匯出 — HTML 才是可交付成果。
9. 交付
用使用者的語言簡短回覆；圖形承載內容。
- 以一個描述性的 Markdown 連結（而非檔名）作為開頭，指向 HTML。
- 當用戶要求理解某事（而非僅是繪製）時，加上一行關鍵重點摘要。
- 說明任何會改變頁面閱讀方式的內容：抽象層級、遺漏處、示意值、缺失證據。
- 報告任何匯入的忠實度清單。
- 不要貼上規範、關卡輸出或檢查清單。如果被問到是否已檢查，回答「兩項自動校驗通過（結構 + 可讀性）；未做人為視覺複核。」 — 並且僅在你實際看過渲染結果時才聲稱已進行視覺審查。
- 如果某個關卡必須被放寬，請說明是哪條規則以及原因。默許放寬正是此技能要防止的情況。
10. 故障排除
| 症狀 | 修正 |
|---|---|
comprehension_check 失敗於 steps | 新增 meta.reading_path（節點 ID）或 meta.steps（標題/詳細資訊） |
失敗於 legend | 新增 meta.legend，包含每個類型/變體的 {label, fill}，或捨棄第二種視覺語言 |
失敗於 accent | 超過 2 個 kind: "focal" 節點 — 保留標題所論述的那一個 |
失敗於 nodes | 拆分為概述 + 詳細資訊；不要縮小類型 |
失敗於 contrast | 你覆寫了某個記號；從 references/design-system.md 還原 |
self_check 抱怨遠端字型 | 只允許 fonts.googleapis.com；移除其他 <link> |
self_check 抱怨內容超出 viewBox | 加寬 viewBox 預設值或減少節點數量 |
| 標籤重疊 | 為邊線提供較短的標籤（≤ 6 個 CJK 字元），或設定 col/row 以騰出空間 |
| 沒有任何東西渲染 | 檢查 meta.type 是否為九種引擎類型之一；閱讀 render.py 的錯誤訊息 |
11. 檔案
SKILL.md 此檔案
references/
comprehension.md 可讀性合約的深入說明
design-system.md 記號、字型排印學（包括 CJK）、間距、節點處理
spec-schema.md 完整 JSON 規範，按類型劃分
type-router.md 40 多種視覺類型 → 引擎類型或佈局語法
hand-authoring.md 手動 SVG 基本元素 + 連接器規則 + 無障礙
import-export.md Mermaid / draw.io / Excalidraw 匯入，SVG / PNG 匯出
assets/template.html 手動創作支架
scripts/render.py 規範 → HTML（九種類型）
scripts/self_check.py SVG 衛生關卡（MIT，來自 diagram-design）
scripts/comprehension_check.py 可讀性關卡（此技能）
scripts/export.py SVG / PNG 匯出
scripts/{mermaid,drawio,excalidraw}_extract.py 匯入提取器（MIT）
examples/ 八個通過兩個關卡的渲染示範