HTML 圖表建立器
產生自包含的 .html 檔案，內含單一內嵌 <svg>，旨在進行視覺論證，而不僅僅是顯示資訊。然後使用 Playwright 對其進行截圖，檢查 PNG，並修正直到完美。
此技能中的檔案
| 檔案 | 用途 | 何時讀取 |
|---|---|---|
references/color-palette.md | 所有顏色和品牌樣式：唯一的事實來源 | 在每個圖表之前 |
references/visual-patterns.md | 每種佈局模式（扇形展開、時間軸、樹狀圖...）的草圖 | 設計步驟 2 |
references/starter.html | 頁面外殼：CSS 權杖、文字/形狀類別、箭頭標記、每種慣例的一個範例 | 複製它作為每個圖表的開頭 |
scripts/render.py | 將 HTML 截圖為 PNG 並 lint 幾何圖形 | 每次編輯後執行（請參閱渲染與驗證） |
examples/ | 兩個已完成的圖表及其 PNG 檔案 | 當您需要參考密度和樣式時 |
若要為品牌重新設定所有圖表的樣式，請編輯 color-palette.md（以及 starter.html 中相符的權杖）。其他一切都是通用方法。
已做出的兩個決定（每個圖表無需重新討論）
1. 一切都是 SVG。HTML 只是環繞它的頁面。
方框、文字、箭頭和程式碼區塊都位於一個 <svg id="diagram"> 中。不要使用 HTML/CSS（flexbox/grid div）建立方框，然後疊加 SVG 作為連接器。
原因： 圖表是幾何問題，箭頭需要兩端的精確座標。使用全 SVG 時，每個節點和每個箭頭共享一個寫入檔案中的座標系統，因此您可以透過算術計算箭頭端點並透過編輯數字來修正它。使用 HTML 方框時，位置來自瀏覽器的佈局引擎：它們不在原始碼中，它們會隨著字型和視口寬度而變化，然後連接器需要 JavaScript 在執行時測量方框。這是需要除錯的第二個程式，而且讀者的視口可能與您驗證時使用的不同。全 SVG 的代價是真實存在的，但較小：SVG 文字不會自動換行（您需要使用 <tspan> 自行換行），並且其寬度在渲染前是未知的（lint 會測量它並回報溢位）。
<foreignObject>（SVG 內部的 HTML）預設為關閉：它是您可能獲得文字換行的唯一地方，但在瀏覽器外部渲染不一致，而且 lint 無法檢查它。僅當使用者需要在形狀內部使用段落時才使用它。
2. 不使用 Graphviz 或 D2 進行佈局。手動放置座標。
原因： 此方法要求佈局反映概念：扇形展開、時間軸、循環、並排比較、自由浮動註釋、放置在所說明步驟旁邊的程式碼區塊。自動佈局引擎針對不同的目標（具有較少邊交叉的分層圖）進行最佳化，因此它們會將每個圖表壓平成相同的由上而下層級結構，而這正是此技能旨在避免的「統一方框」輸出。它們還會引入二進制依賴關係，並產生難以重新設定樣式和註釋的 SVG。
例外情況： 一個真正圖形狀的主題（大約 15 個以上具有許多交叉連結的節點，例如依賴關係圖），其中交叉是主要問題。在那種情況下，僅執行 dot -Tplain (Graphviz) 以獲取節點座標，然後使用此技能的樣式和慣例自行繪製節點。請說明您正在這樣做及其原因。
核心理念
圖表應該論證，而非顯示。
圖表不是格式化文字。它是一個視覺論證，顯示關係、因果關係和流程，純文字無法表達這些。形狀本身應該就是意義。
同構測試：如果移除所有文字，結構本身是否能傳達概念？如果不能，請重新設計。
教育測試：有人能從這個圖表中學到具體的東西，還是它只是標記方框？一個好的圖表會教學——它顯示實際的格式、真實的事件名稱、具體的範例。
深度評估（請先執行此操作）
在設計之前，確定此圖表需要何種細節層級：
簡單/概念性圖表
在以下情況使用抽象形狀：
- 解釋心智模型或哲學
- 受眾不需要技術細節
- 概念本身就是抽象（例如，「關注點分離」）
全面/技術性圖表
在以下情況使用具體範例：
- 繪製真實系統、協定或架構的圖表
- 圖表將用於教學或解釋（例如，YouTube 影片）
- 受眾需要了解事物的實際樣貌
- 您正在顯示多種技術如何整合
對於技術圖表，您必須包含證據工件（請參閱下文）。
研究要求（針對技術圖表）
在繪製任何技術性內容之前，請研究實際的規格。
如果您正在繪製協定、API 或框架的圖表：
- 查閱實際的 JSON/資料格式
- 找到真實的事件名稱、方法名稱或 API 端點
- 了解各個部分實際如何連接
- 使用真實的術語，而非通用的佔位符
錯誤：「協定」→「前端」 正確：「AG-UI 串流事件（RUN_STARTED、STATE_DELTA、A2UI_UPDATE）」→「CopilotKit 透過 createA2UIMessageRenderer() 進行渲染」
研究使圖表既準確又具教育意義。
證據工件
證據工件是具體的範例，證明您的圖表是準確的，並幫助觀眾學習。在技術圖表中包含它們。
證據工件的類型（選擇與您的圖表相關的類型）：
| 工件類型 | 何時使用 | 如何渲染 |
|---|---|---|
| 程式碼片段 | API、整合、實作細節 | 深色矩形 + 語法著色的文字（請參閱證據工件顏色的色板） |
| 資料/JSON 範例 | 資料格式、結構、負載 | 深色矩形 + 彩色文字（請參閱色板） |
| 事件/步驟序列 | 協定、工作流程、生命週期 | 時間軸模式（線 + 點 + 標籤） |
| UI 模型 | 顯示實際輸出/結果 | 模仿真實 UI 的巢狀矩形 |
| 真實輸入內容 | 顯示進入系統的內容 | 矩形，其中顯示範例內容 |
| API/方法名稱 | 真實的函式呼叫、端點 | 使用文件中的實際名稱，而非佔位符 |
範例：對於關於串流通訊協定的圖表，您可以顯示：
- 規格中的實際事件名稱（不僅僅是「事件 1」、「事件 2」）
- 一個顯示如何連接的程式碼片段
- 串流資料的實際樣貌
範例：對於關於資料轉換管道的圖表：
- 顯示範例輸入資料（實際格式，而非「輸入」）
- 顯示範例輸出資料（實際格式，而非「輸出」）
- 如果相關，顯示中間狀態
關鍵原則：顯示事物的實際樣貌，而不僅僅是它們的名稱。
多層級縮放架構
全面的圖表同時在多個縮放層級運作。將其想像為一張同時顯示國界和街道名稱的地圖。
層級 1：摘要流程
一個簡化的概覽，一目瞭然地顯示完整的管道或流程。通常放置在圖表的頂部或底部。
範例：輸入 → 處理 → 輸出 或 用戶端 → 伺服器 → 資料庫
層級 2：區域邊界
標記的區域，用於對相關元件進行分組。這些建立了視覺「房間」，幫助觀眾理解哪些內容屬於同一組。
範例：按職責分組（後端 / 前端），按階段分組（設定 / 執行 / 清理），或按團隊分組（使用者 / 系統 / 外部）
層級 3：區塊內部細節
每個區塊內的證據工件、程式碼片段和具體範例。這是教育價值所在。
範例：在「後端」區塊內，您可以顯示實際的 API 回應格式，而不僅僅是標記為「API 回應」的方框
對於全面的圖表，目標是包含所有三個層級。 摘要提供脈絡，區域進行組織，細節則進行教學。
差與好
| 差（顯示） | 好（論證） |
|---|---|
| 5 個帶有標籤的相等方框 | 每個概念都有一個反映其行為的形狀 |
| 卡片網格佈局 | 視覺結構符合概念結構 |
| 裝飾文字的圖示 | 本身就是意義的形狀 |
| 所有東西都用相同的容器 | 每個概念都有不同的視覺詞彙 |
| 所有東西都在方框內 | 自由浮動文字搭配選擇性容器 |
簡單與全面（了解您需要哪一種）
| 簡單圖表 | 全面圖表 |
|---|---|
| 通用標籤：「輸入」→「處理」→「輸出」 | 具體：顯示輸入/輸出的實際樣貌 |
| 命名方框：「API」、「資料庫」、「用戶端」 | 命名方框 + 實際請求/回應的範例 |
| 「事件」或「訊息」標籤 | 時間軸，其中包含規格中的真實事件/訊息名稱 |
| 「UI」或「儀表板」矩形 | 顯示實際 UI 元素和內容的模型 |
| 約 30 秒解釋 | 約 2-3 分鐘的教學內容 |
| 觀眾了解結構 | 觀眾了解結構 AND 細節 |
簡單圖表適用於抽象概念、快速概覽，或當觀眾已經了解細節時。全面圖表適用於技術架構、教學、教育內容，或當您希望圖表本身進行教學時。
容器與自由浮動文字
並非每一段文字都需要一個形狀環繞。 預設使用自由浮動文字。僅在容器有用途時才新增它們。
| 使用容器的時機... | 使用自由浮動文字的時機... |
|---|---|
| 它是某個區塊的焦點 | 它是標籤或描述 |
| 它需要與其他元素進行視覺分組 | 它是支援性細節或元資料 |
| 箭頭需要連接到它 | 它描述附近的某物 |
| 形狀本身具有意義（決策菱形等） | 排版本身建立了足夠的層級結構 |
| 它代表系統中一個獨特的「事物」 | 它是章節標題、副標題或註釋 |
排版作為層級結構： 使用字型大小、粗細和顏色來建立視覺層級結構，而無需使用方框。一個 28px 的標題不需要一個矩形環繞它。
容器測試： 對於每個帶框的元素，問問「它是否可以作為自由浮動文字運作？」如果可以，請移除容器。
設計流程（在撰寫 SVG 之前執行此操作）
步驟 0：評估所需深度
在任何其他操作之前，確定這是否需要是：
- 簡單/概念性：抽象形狀、標籤、關係（心智模型、哲學）
- 全面/技術性：具體範例、程式碼片段、真實資料（系統、架構、教學）
如果是全面的：先進行研究。查閱實際的規格、格式、事件名稱、API。
步驟 1：深入理解
閱讀內容。對於每個概念，問問：
- 這個概念做什麼？（不是它是什麼）
- 概念之間存在什麼關係？
- 核心的轉換或流程是什麼？
- 某人需要看到什麼才能理解這個？（而不僅僅是閱讀）
步驟 2：將概念對應到模式
對於每個概念，找到反映其行為的視覺模式。每種模式的草圖和使用說明位於 references/visual-patterns.md。
| 如果概念... | 使用此模式 |
|---|---|
| 產生多個輸出 | 扇形展開（從中心放射狀的箭頭） |
| 將多個輸入合併為一個 | 收斂（漏斗，箭頭合併） |
| 具有層級/巢狀結構 | 樹狀圖（線條 + 自由浮動文字） |
| 是一系列步驟 | 時間軸（線條 + 點 + 自由浮動標籤） |
| 循環或持續改進 | 螺旋/循環（返回起點的箭頭） |
| 是抽象的狀態或脈絡 | 雲狀（重疊的橢圓） |
| 將輸入轉換為輸出 | 裝配線（之前 → 處理 → 之後） |
| 比較兩件事 | 並排（平行並列，帶有對比） |
| 分為階段 | 間隙/中斷（區塊之間的視覺分隔） |
步驟 3：確保多樣性
對於多概念圖表：每個主要概念必須使用不同的視覺模式。不要使用統一的卡片或網格。
步驟 4：草擬流程
在撰寫標記之前，在腦中追蹤視線如何移動通過圖表。應該有一個清晰的視覺故事。
步驟 5：建構 HTML/SVG
只有在現在才撰寫檔案，從 references/starter.html 開始。在 20px 網格上佈局，並在放置任何東西之前記下關鍵座標（欄、列、節點中心）。關於如何處理大型圖表，請參閱下文。
步驟 6：渲染與驗證（強制）
撰寫檔案後，您必須執行渲染-檢視-修正迴圈，直到圖表看起來正確。這不是可選的——請參閱下方的渲染與驗證章節以了解完整流程。
大型 / 全面圖表策略
對於全面或技術性圖表，請一次建立一個區塊的 SVG。 不要一次撰寫整個檔案。一個全面的圖表可能會超過每次回應的輸出限制，即使它符合，一次一個區塊也能讓每個區塊得到真正的關注。
逐區塊工作流程
階段 1：建立每個區塊
- 從
references/starter.html建立檔案：設定<title>、viewBox，並新增第一個區塊。 - 每次編輯新增一個區塊，每個區塊都在其自己的
<g id="sec-...">中。思考此區塊的佈局、其間距，以及它如何連接到已經存在的內容。 - 使用描述性 ID（
data-node="trigger"、id="sec-backend"），以便跨區塊的邊具有可讀性：data-from="trigger" data-to="router"。 - 在 svg 頂部的 HTML 註解中保留座標計劃（欄 x、列 y、區塊邊界）。每個後續區塊和每條邊都會讀取它，這是您在不猜測的情況下修正間距的方法。
階段 2：檢視整體
完整閱讀檔案並檢查：
- 每個
data-from/data-to是否都命名了一個存在的data-node？ - 間距是否平衡？或者某些區塊擁擠而其他區塊稀疏？
viewBox是否包含了所有內容，並有大約 40px 的邊距？
階段 3：渲染與驗證（如下）。
區塊邊界
… [為翻譯而截斷]