diagram-design：讓 Coding Agent 產出能交付的技術圖表

寫架構圖、流程圖時，最常見的痛點往往出現在成品：畫面塞滿圓角方框，連線交錯複雜，每個節點都像在搶風頭。雖然該有的資訊都在上面，但讀者一眼看過去，根本抓不到重點。

diagram-design 的核心概念，是把「畫圖」收斂成一套 Coding Agent 可以遵循的設計規範。作為一個專為 Claude Code、Codex 和 Pi 設計的 Agent Skill / plugin 套件，它會根據圖表的語意來挑選版型，並產出內嵌 SVG 與 CSS 的單一 HTML 檔案。它的重點放在資訊的化繁為簡、視覺層級的拿捏、品牌配色以及輸出尺寸的適配，工作位置接近「讓 Agent 產出可交付圖表」的設計工作流。[1][2]

這個定位非常關鍵：diagram-design 的產物是 Agent 依照規範重繪的圖表。使用者透過文字需求和檔案輸入驅動流程，操作介面不包含拖拉節點的編輯器。Mermaid 的原始排版也不會直接成為成品。Agent 會先整理圖表資訊，再套用固定的編輯設計系統（editorial design system）重新繪製。

本文是基於 main 分支 commit c238e8a 的 README、SKILL.md、輸出規格與匯入文件整理而成。由於這類 Agent Skill 專案更新速度極快，實際安裝與使用內容，仍應以你當下取得的版本為準。[3]

解決「圖畫得出來，卻無法直接交付」的痛點

一般的 Coding Agent 確實能寫出 HTML 或 Mermaid 語法，但若缺乏具體規範的約束，產出的成果往往容易伴隨以下問題：

• 每個元件都用一模一樣的方框呈現，完全看不出主次關係。
• 為了強調「重要」，到處填滿各種顏色，反而導致整張圖失去焦點。
• 連線為了繞開節點而四處斜穿，讓閱讀動線變得凌亂不堪。
• 未針對不同媒介（如部落格文章、簡報投影片、社群分享卡片）調整畫布比例與字體大小。
• 成品帶有濃厚的「工程程式碼產物」感，一旦放入精緻的文件或網頁中，就會顯得格格不入。

diagram-design 將解決這些痛點的思維寫成了 Skill 規範：

• 每個節點都必須代表一個獨立概念。
• 如果版面配置已經能表達層級關係，就省略多餘的線條。
• 強調色（accent color）最多只能用在一到兩個焦點元素上。
• 預設的資訊密度目標為 4/10。複雜度超出上限時，就拆分為總覽圖（overview）與細節圖（detail）。[3]

它甚至連連線的細節都規範得極為嚴苛：

• 非水平或垂直對齊的連線，必須採用直角折線並搭配圓角，避免出現斜線。
• 箭頭上的標籤與連線需保持 6–10px 的間距。
• 多條連線匯入同一節點時，接點必須錯開。
• 各條連線之間不能相互重疊。[3]

這些規範看似繁瑣，但恰好切中了 AI 產圖最容易失控的盲點：模型雖然清楚「圖裡有哪些元素」，卻未必懂得「該刪除哪些線條、該突出哪個節點，以及如何引導讀者的視覺動線」。

支援的圖表類型與選型邏輯

目前在 SKILL.md 的視覺類型導覽中，涵蓋了架構圖、IT current-state、流程圖、sequence diagram、state machine、ER/data model、timeline、swimlane、quadrant、radar/spider、loop/flywheel、nested、tree、org chart、layer stack、Venn、pyramid/funnel，以及 bar、line、Gantt、scatter 等基本圖表，另外也包含了 high-level、process、medallion、data flow、DP integration 與 DP security matrix 等類型。[3]

不過這裡有個有趣的細節值得留意：目前 README 和 SKILL.md 的內容主要是以 27 種視覺類型（visual types）為主，但 GitHub 專案資訊（metadata）的 description 卻寫著 29 種。這在快速迭代的開源專案（moving repository）中算是常見的同步落差。我們不該把 27 或 29 這兩個數字當作一成不變的承諾，實際應用時，建議還是以你所安裝版本中的 Skill 和畫廊（gallery）實作為準。[1][2][3]

在選擇圖表樣式時，它並非單純抓到「架構」兩個字就無腦套用 architecture 模板。diagram-design 的處理流程分為兩個層次：

1. 判斷語意模式：例如分析是否屬於 fan-in queue、stage framework、unstructured input to structured artifact、paired policy traces、secure paved road、governance catalog，或是 compensating security layers。
2. 選擇對應的視覺類型：像是將 bottleneck 對應到 data flow、把 policy trace 對應到 flowchart，或者將 trust boundary 映射到 architecture 等。[3]

這種兩階段的選型機制，能有效避免「萬物皆可架構圖」的通病。例如，登入流程用 sequence diagram 更清晰，狀態轉換適合 state machine，跨部門協作則推薦 swimlane。如果僅僅是條列幾個項目，用表格呈現其實比硬要畫張圖來得更直覺——這也是 Skill 文件中特別提醒開發者「不要為了畫圖而畫圖」的初衷。[3]

輸出會隨場景調整，最後交付的不只是一張圖

diagram-design 將圖表的輸出規格拆分為四個可調整的維度：format、size、detail 與 audience。[4]

這意味著，面對同一個架構來源，如果要放入給開發團隊看的工程文件，可以保留詳細的服務名稱、通訊協定與 port。若要放進給主管或客戶看的簡報，則可轉換為展現能力與業務價值的邏輯。這個流程會同時調整文字層級和資訊密度，畫布縮放只是其中一部分。

在細節（Detail）的刪減上，它也有一套固定的優先順序。當節點數量超出上限時，它會依序刪除裝飾與孤立的註記、合併重複的背景工作執行器（workers）、將僅包含葉節點（leaf nodes）的群組收攏為單一節點，最後才去處理監控（monitoring）、CI、日誌（logging）等橫切關注點（cross-cutting concerns）。而任何在過程中被合併或刪除的內容，都會被記錄在「保真度清單（fidelity ledger）」中，讓使用者能清楚比對原始資料中有哪些細節在這次輸出中被省略了。[4]

這樣的設計非常適合需要撰寫文章與製作簡報的場景：讀者需要一條清晰的主線，系統的其餘實作細節則可放到後續圖表。當圖表來源超過 24 個節點時，文件強烈建議拆分為一張總覽圖（overview）搭配各區域的細節圖（detail），避免把所有東西塞進一張令人眼花撩亂的接線圖（wiring diagram）中。[4]

融入品牌視覺，而不只是事後套用 CSS

diagram-design 內建了一份 style-guide.md，將 paper、ink、muted、accent、link、rule 等語意顏色與字體角色進行集中化管理。當你第一次在新的專案中使用它時，如果圖表仍是預設的 neutral stone + rust 配色，Skill 會主動引導，詢問你是否要進行品牌導入（onboarding）。[3]

品牌導入可以透過三種途徑取得來源資訊：直接輸入網站 URL、讀取已安裝的 design skill，或偵測本機專案中的 design-system 資料夾。它會解析背景色、主要與次要文字顏色、CTA/連結顏色，以及標題、內文與程式碼所使用的字型，接著將這些設定映射到 diagram-design 的語意 Token 中。在正式寫入 style guide 之前，它會先呈現 diff 差異供你確認，經同意後才會更新設定。[5]

這個流程最大的優勢在於，圖表從繪製之初就已經是整體內容視覺系統的一部分。對於部落格、產品說明文件或專業簡報而言，這比產出一張「雖然精緻，但配色與網站格格不入」的獨立圖片要實用得多。

不過，這種視覺對齊也有其技術限制。公開的 Google Fonts 可以精確保留字型與字重。自託管（self-hosted）或付費授權的字型，如果無法安全嵌入單一輸出檔案，Skill 就會將它標記為備用字型（fallback）。文章不會把原站的特殊字型當成已經完整複製。[5]

如何整合既有的 Mermaid 與 draw.io 圖表？

如果你手邊已經有現成的圖表，diagram-design 支援將 .drawio、.drawio.xml、內嵌圖表的 .drawio.png 與 .drawio.svg，或是 .mmd、.mermaid 以及 Markdown 檔案中的 Mermaid 程式碼區塊作為輸入來源。[2][6][7]

不過必須強調的是，它的核心邏輯是重新繪製（redraw），而非單純的格式轉換（conversion）。

它的處理流程大致如下：

1. 從原始檔案中解析並擷取出節點、連線、群組、方向性、樞紐（hubs）與整體複雜度資訊。
2. 確認使用者指定的輸出格式、畫布尺寸、細節層級與目標受眾。
3. 選擇最切合的語意模式與視覺類型。
4. 捨棄原圖中的座標位置、主題配色、字型與渲染器排版（renderer layout）。
5. 根據全新的編輯設計系統重新配置版面。
6. 產出保真度清單（fidelity ledger），向使用者交代有哪些元件在重繪過程中被合併、折疊或刪除了。[6][7]

舉例來說，Mermaid 中定義的 flowchart 若本質上只是服務拓撲，重繪時不一定會被保留為傳統的流程圖。只有在確實存在決策菱形與 yes/no 分支時，才會以流程圖呈現。同樣地，draw.io 中常見的圓柱狀資料庫圖示也會改畫成符合設計系統風格的 Store/State 視覺標示。[6][7]

這種重繪機制非常適合用來將工程師隨手畫出的草圖，快速轉化為適合放上部落格或簡報的質感插圖。原圖所承載的「內容與關聯性」得以保留，而視覺呈現則被重新塑造成最適合交付的模樣。

/diagram-design:import platform.drawio
/diagram-design:import platform.drawio --size=slide-16x9 --detail=simplified --audience=executive
/diagram-design:import-mermaid architecture.mmd --size=slide-16x9 --detail=simplified

安裝與快速上手

如果你使用的是 Codex，可以直接安裝此 Skill：

npx skills add https://github.com/cathrynlavery/diagram-design --skill diagram-design

Claude Code 使用者則可以透過 plugin marketplace 來安裝：

/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design

若使用的是 Pi，安裝指令如下：

pi install https://github.com/cathrynlavery/diagram-design

完成安裝後，你就能直接用文字向 Agent 描述你的繪圖需求，例如：

Make an architecture diagram of my app:
frontend, API server, Redis cache, PostgreSQL, and the background worker.

Output: self-contained HTML for a blog post.
Audience: mixed.
Keep the request path as the focal story.

或者是：

把這個登入流程畫成 sequence diagram，
包含 access token 過期後的 refresh flow，
輸出成適合文件內嵌的 HTML。

在正式動筆繪製之前，該 Skill 規範 Agent 必須先向使用者說明所選用的視覺類型（visual type）、語意模式（semantic pattern）、輸出尺寸，以及為了符合複雜度上限而規劃刪除或合併的節點。這個預檢步驟（checkpoint）能讓使用者在實際產圖前及時微調方向。[3]

最終生成的預設產物是一個單一 HTML 檔案，其中已內嵌 CSS 且 SVG 採 inline 形式，預設無須載入 JavaScript。此外，產出的每個 SVG 皆會配置 role="img"、aria-labelledby、title 與 desc 等屬性，確保圖表能被無障礙輔助技術正確辨識。[3]

若有交付 PNG 或獨立 SVG 的需求，專案中也提供了 /export-diagram 工作流。導出 SVG 時會自動抽離圖表本體。導出 PNG 時則會透過 Playwright 在瀏覽器中進行點陣化（rasterize）。根據 README 說明，此功能需要本機額外安裝 Playwright 與 Chromium 瀏覽器。[2]

動畫定位為加分層，而非預設呈現

在 diagram-design 的設定中，動畫被歸類在表現層（presentation layer），不屬於獨立的圖表類型。它的預設模式為 none，輸出結果保持靜態且不含指令碼。使用者明確要求，或動態效果確實有助於解釋先後順序、階段累積、條件評估與狀態傳播時，才會啟用 reveal、step 或 loop 等動態模式。[2][3]

其動畫設計遵循「靜態優先（static-first）」原則：所有的圖表語意與結構必須先完整存在於 HTML/SVG 中，JavaScript 僅作為控制顯示狀態的輔助手段。若瀏覽器偵測到用戶啟用了 prefers-reduced-motion（減少動態效果），系統將直接呈現完整的靜態畫面，並自動隱藏或停用播放控制項。畢竟，動畫不該被用來掩蓋圖表本身內容的缺漏。[3]

這種嚴格的邊界界定相當符合技術文件的實務需求。例如，在說明原則評估（policy evaluation）或請求流程（request flow）時，可以使用 step-by-step 的互動動畫引導讀者理解。系統架構圖、ER model 或預計轉存為 PNG 的圖表，則維持靜態版本即可。

如何將它融入日常開發工作流？

在實際應用中，建議將 diagram-design 定位在「內容收斂」之後的步驟，先整理資料，再交給 Agent 進行設計：

1. 理清故事線：先以文字或程式碼草稿整理出系統主線，確保這張圖只聚焦於解答一個核心問題。
2. 定義輸出目標：將原始資料交給 diagram-design，並明確指定受眾、輸出路徑與細節層級。
3. 確認預檢計畫：讓 Agent 在動筆前先提出圖表類型選用與資訊刪減計畫。
4. 驗收 HTML 結構：先接收生成的 HTML，仔細檢視節點命名、主線邏輯與保真度清單（fidelity ledger）。
5. 按需衍生格式：當需要將圖表置入簡報、社群卡片或作為文章封面時，再依據對應目的導出為 PNG 或 SVG 檔。
6. 執行自我檢查：善用專案提供的 self-check 機制，檢查無障礙 SVG 屬性、單一檔案安全性，以及是否符合基本輸出規範。[2][3]

這套工具的工作位置在視覺呈現階段。系統設計決定與圖表中的技術正確性，仍需要由開發者或其他驗證流程確認。它會將整理就緒的資訊，轉化為讀者能快速理解、與品牌視覺一致，且能直接用於文件的產出物。[2][3]

誰適合使用？誰不適合？

這套工具非常適合：

• 需要高頻率產出部落格技術圖表、系統流程圖或產品架構圖的創作者或開發者。
• 手邊已有現成的 Mermaid 或 draw.io 草圖，但不希望耗費心力手動調整排版的人。
• 在 Claude Code、Codex 或 Pi 等環境中，希望 Agent 能產出符合一致設計規範圖表的使用者。
• 需要同時交付多種格式（HTML、SVG、PNG），並希望能針對文章、投影片與社群貼文快速調整尺寸的人。
• 期待將自家網站的品牌配色與字型延伸應用到技術圖表中的團隊。

但它可能不適合：

• 尋求多人即時協作、視覺化拖拉節點、留言評論與版本控制的線上圖表編輯器。
• 想要進行天馬行空的插畫創作、白板腦力激盪，或不受任何排版規則約束的自由設計。
• 僅僅是想在終端機（terminal）中快速輸出簡易的 ASCII 結構圖。
• 原始資料尚未整理，寄望工具能幫忙梳理並判斷系統底層邏輯的人。

另外需注意的是，該專案目前尚未發布正式的發行版本（published release），主要仍透過 GitHub 儲存庫、Skill 套件與 plugin 入口來調用。[1] 目前的 Codex plugin metadata 也以 GitHub repository 作為主要入口。[10]

程式碼與 Skill 本身採用 MIT 授權條款。套件中內嵌的元件則要分開確認：

• Tabler Icons
• Simple Icons
• Devicon
• log-z/logos
• 個別品牌的商標與圖示來源

這些來源各有自己的授權與商標使用規範。若要用於商業用途，建議事前逐項確認。[8][9]

結論：將「繪圖」化為一套結構化的交付流程

diagram-design 的價值在於兩件事：它提供多樣的圖表模板，也把「如何畫出一張好圖」的判斷思維整理成一套 Agent 可確實執行的標準流程。

• 從語意分析出發，再挑選版型。
• 確認輸出尺寸與目標受眾後，過濾細節。
• 刪除冗餘資訊，再套用視覺風格。
• 以無障礙（accessibility）檢驗、連線規則以及 self-check 守住最終的輸出品質。

如果你只需要快速產生一張簡單的 Mermaid 圖，這套工具的規範可能顯得較多。複雜的系統架構、資料流向或產品運作流程，若要轉換成能直接置入部落格文章、技術文件或簡報投影片的視覺作品，這套 Skill 能提供一條比放任 Agent 自由發揮更穩定的產出路徑。

它最理想的定位，是作為技術內容產製工作流的最後一哩路：由開發者或 Agent 在前期梳理出正確的系統故事，再由它在後段負責將故事精煉、壓縮為層次分明、具高度可讀性且能直接交付的精美圖表。

Sources

• [1] https://github.com/cathrynlavery/diagram-design
• [2] https://raw.githubusercontent.com/cathrynlavery/diagram-design/main/README.md
• [3] https://raw.githubusercontent.com/cathrynlavery/diagram-design/main/skills/diagram-design/SKILL.md
• [4] https://raw.githubusercontent.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/output-spec.md
• [5] https://raw.githubusercontent.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/onboarding.md
• [6] https://raw.githubusercontent.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/import-drawio.md
• [7] https://raw.githubusercontent.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/import-mermaid.md
• [8] https://raw.githubusercontent.com/cathrynlavery/diagram-design/main/LICENSE
• [9] https://raw.githubusercontent.com/cathrynlavery/diagram-design/main/THIRD_PARTY_LICENSES.md
• [10] https://raw.githubusercontent.com/cathrynlavery/diagram-design/main/.codex-plugin/plugin.json