【2026 最新】Diagram Design 教學：把 Mermaid 變成可交付 SVG／PNG

這篇 Diagram Design 教學要解決一個很常見的落差：Mermaid 明明把系統關係寫對了，貼進簡報後卻像工程草稿；截圖一放大就糊，換成公司色又得整張重畫。你需要的不是再畫一遍，而是一條能把內容骨架、圖型、品牌規則與輸出驗收接起來的工作流。

在 AlphaLab 於 2026 年 8 月 19 日觀察到的一次 GitHub Weekly Trending 頁面快照中，Diagram Design 官方倉庫列在當週第一；這是會持續滾動的注意力排名，不是品質評分。真正值得測的是：它怎麼處理 Mermaid、能不能重跑、輸出的字型與替代文字是否可靠。

這篇專為第一次接觸 Agent plugin、也不想先學設計軟體的讀者寫。你會從 Claude Code／Codex 安裝開始，匯入一張四節點 Mermaid 流程圖，設定四個輸出旋鈕，再把 HTML 交付成 SVG／PNG；最後用一份可直接搬進專案的 QA 清單驗收。

先說結論：Diagram Design 教學先記住這條公式

🧭 記憶把手：可交付圖表＝正確骨架 × 合適圖型 × 品牌規則 × 輸出驗收。
Mermaid 負責「有哪些東西、怎麼相連」；Diagram Design 像編輯台，重新決定讀者先看哪裡、用什麼版式，最後才輸出檔案。

• 只要可維護的技術骨架：繼續把 Mermaid 當原始檔，不必為漂亮而增加流程。
• 要交給客戶、主管或簡報：保留 Mermaid，另外用 Diagram Design 產生經過編排的交付版。
• 要進 CI：不要只檢查檔案存在；字型、瀏覽器、可及性名稱與實際像素都要各自驗收。

Diagram Design 是什麼？不是 Mermaid 換皮轉檔器

Diagram Design 是一套給 coding agent 使用的設計 skill、範本與檢查腳本。它不是獨立的拖拉式 App，也不是收到 Mermaid 就固定吐出同一組座標的排版引擎。Agent 會先讀取內容，載入適合的圖型規則，再產生含 inline SVG 的 HTML。這和AI Agent Harness的觀念相通：模型負責判斷，外層規則負責限制輸入、產物與驗收。

最容易誤會的是「import」。官方 Mermaid 匯入規格明寫這是 redraw（重畫），不是 render（渲染）或 lossless conversion（無損轉換）。來源的節點、連線、群組與方向提示會進入中介資料；Mermaid 的自動座標、主題、字型、class 與 click 目標則不帶過去。

目前 Mermaid importer 支援 flowchart／graph、sequenceDiagram、stateDiagram-v2 與 erDiagram。工具本身可以從文字建立時間線、Gantt 等其他視覺，但這不等於它能匯入 Mermaid 的同名 grammar。若你的來源是 mindmap、timeline 或 classDiagram，extractor 會明確停止；不要偷偷改成另一種圖。

Diagram Design 教學 Step 1：先安全安裝 Claude Code／Codex plugin

Marketplace plugin 是高信任元件：在 Claude Code 中可能以你的使用者權限執行任意程式碼；Codex 端的動作仍受 host sandbox 與 approval policy 約束。先看固定 commit 的安裝說明、授權與最近變更，再決定要不要裝。Claude Code 官方文件也說明第三方 marketplace 預設不自動更新。

Claude Code 安裝

1. 在 Claude Code 輸入 /plugin marketplace add cathrynlavery/diagram-design。
2. 再輸入 /plugin install diagram-design@diagram-design。
3. 同一個 session 要立刻使用，就跑 /reload-plugins；之後可在 /plugin 的 Marketplaces 分頁決定是否開啟自動更新。

Codex CLI 安裝

1. 在終端機執行 codex plugin marketplace add cathrynlavery/diagram-design。
2. 再執行 codex plugin add diagram-design@diagram-design。
3. 開一個新 session，直接用自然語言要求「把這份 Mermaid 重畫成簡報版 SVG」。

OpenAI 官方 Plugins 文件確認 Codex CLI 有 plugin browser；Codex IDE extension 目前不支援 plugins。因此本文的 Codex 路線指 CLI，不是 IDE 外掛。若你還分不清兩個 coding agent 的工作方式，可先讀Claude Code vs Codex 客觀比較；只想先選 Claude 介面，則看Claude、Claude Code、Cowork 怎麼選。

Diagram Design 教學 Step 2：用四節點 Mermaid 跑一次

先建立 order-flow.mmd。這個例子故意包含一個判斷與一條重試循環，方便確認 importer 沒把「否」分支或 cycle 吃掉：

flowchart LR
  A[使用者送出訂單] --> B{付款成功？}
  B -- 是 --> C[寄出確認信]
  B -- 否 --> D[重試或更換卡片]
  D --> B

Claude Code 可輸入 /diagram-design:import-mermaid order-flow.mmd --format=html --size=doc-inline --detail=balanced --audience=mixed。Codex CLI 則直接說：「讀取 order-flow.mmd，用 Diagram Design 以 doc-inline、balanced、mixed 重畫成 HTML；完成後回報 fidelity ledger。」

AlphaLab 用 2026 年 8 月 19 日取用的 commit 2991772 extractor 跑這份檔案，得到 4 個可畫節點、4 條邊、2 條有標籤的邊，並回報 has_cycle=true；付款判斷是連線度最高的 hub，入口與終點也都有列出。倉庫隨附的 Mermaid 驗證腳本也在這個 commit 與本次環境通過 flowchart、sequence、state、ER 與惡意 label 測試。這是一次有保留紀錄的 fixture 成功執行，不代表不同模型或環境重畫出的像素會完全相同。

Diagram Design 教學 Step 3：先設定 format、size、detail、audience

不要先叫 Agent「畫漂亮一點」再補需求。四個旋鈕會一起改變畫布、節點數、字級與文案；畫完才改，常常等於重畫。

1. Format：交付到哪裡？預設 html；需要後製用 svg，需要凍結「這一次瀏覽器 render」的像素用 png。PNG 不保證換一台環境重跑仍逐像素相同。
2. Size：讀者離多遠？文件用 doc-inline，投影用 slide-16x9，社群卡用 social-og，向量交接可用 fit。
3. Detail：保留多少？faithful 上限 24 節點，超過 9 個才強制分區；預設 balanced 上限 12；simplified 上限 7。
4. Audience：怎麼命名？engineer 保留 protocol／port，mixed 用團隊共通語言，executive 改用能力與結果。它控制用詞，不控制節點數。

Step 4：把內容與品牌分開，先審 diff 再套版

第一次在新品牌專案產圖時，style-guide gate 會先暫停，讓你完成或略過 onboarding；完成後才進入內容語意與重畫。Onboarding 可以讀公開網站、CSS／design system 資料夾、手動 token 或既有 profile，提出 paper、ink、accent 與字體 token 的差異，人工批准後再套用；它不會替你改寫圖型與元件規則。不要因為品牌色是紅色，就把每個節點都塗紅；重點色只應指向一兩個真正焦點。

常做多客戶圖表，可把批准後的設定存到 ~/.diagram-design/profiles/<slug>.md，再由專案的 .diagram-design marker 指向它。這比直接改已安裝的 style-guide.md 穩定，因為 managed plugin 更新可能替換安裝目錄，profile 則保留。若你想把品牌規則與 AI 工作流都變成可維護檔案，Claude Code HTML vs Markdown解釋了「可視產物」與「長期真相」應如何分工。

Step 5：從 HTML 匯出 SVG／PNG，別忽略字型邊界

Diagram Design 先產生 HTML，再從裡面的第一個 SVG 匯出。Claude Code 要兩種格式，可輸入 /diagram-design:export-diagram order-flow.html；只要向量檔就加 --svg-only，只要 PNG 就加 --png-only --scale=2。Codex CLI 用自然語言提出同一要求即可。

SVG：可縮放，但品牌字型要另外驗

官方 export 規格會保留 role="img"、<title>、<desc>，並注入預設 Instrument Serif／Geist 系列的 Google Fonts @import。這不會自動改成 onboarding 選出的品牌字型；離線 Illustrator、部分 Figma 匯入路徑或沒有相同 CJK fallback 的環境也可能替換字體。要交付品牌 SVG，先修正 stylesheet，再用真正的目標工具驗一次。

PNG：預設 2×；是否透明取決於 SVG 本身

PNG 流程會用 Playwright 開啟原始 HTML，只截第一個 SVG，預設 device_scale_factor=2。程式的 omit_background=True 只移除瀏覽器背景；如果 SVG 自己畫了滿版背景矩形——官方範本正是如此——輸出的 PNG 仍是不透明。官方會先檢查 Python Playwright；若不存在就停止，要求使用者自行執行 pip install playwright 與 playwright install chromium。若只有 Chromium 缺失，則會在 browser launch 階段失敗。

本次測試機沒有 Python Playwright，因此 AlphaLab 只保留 extractor、self-check、靜態驗證與系統 Chrome 全頁渲染結果，不把官方 diagram-only PNG 流程標成本站重現。這個區分很重要：瀏覽器「看得到整頁」與 Playwright「只裁出 SVG element」不是同一個驗收。

Step 6：交付前跑六層 QA，不要只問「好不好看」

1. 內容：對照 fidelity ledger；來源節點、邊、分支、cycle、ER cardinality 有沒有被合併或漏掉？
2. 圖型：流程圖有清楚入口與終點，架構圖有邊界與資料流，時間線有時間順序；不要只靠顏色表達關係。
3. 文字：在文章寬度、200% 縮放與手機預覽都讀得到；CJK 沒被拉丁字體頂成空白或溢出。
4. 可及性：SVG 的 aria-labelledby 確實指向第一個 <title> 與 <desc>；上傳 PNG 時另外寫能傳達目的的 alt text。W3C 圖片替代文字決策樹可用來判斷描述深度。
5. 格式：用目標工具真正開一次 SVG；PNG 檢查透明度、像素尺寸與是否只含圖表，不含 HTML 外框。
6. 重跑：在乾淨環境固定 Python、瀏覽器、字型與輸入，再跑兩次並做像素差異。在 commit 2991772 的 CI 中有跨作業系統的靜態驗證，但沒有安裝 Playwright，也沒有瀏覽器截圖或 pixel regression 步驟。

每份 HTML 至少跑一次 python3 /path/to/diagram-design/skills/diagram-design/scripts/self_check.py order-flow.html。AlphaLab 對官方 Mermaid 範例執行這個檢查已通過；它能攔下缺少 accessible name、HTML attribute 裡的遠端 HTTP(S) asset 與非 canonical script，但不會掃盡 CSS 裡的 @import／url()，也取代不了人眼檢查字被線壓住、卡片太擠或重點順序錯誤。想把「生成→檢查→修正」做成可讀流程，可接著看Graph Engineering 實作教學與Agent Observability 教學。

Diagram Design 最常踩的 6 個坑

1. 把 redraw 當 conversion：原始配色可能承載「錯誤／成功」語意；既然樣式會被丟棄，就要把那層意思改成文字或明確圖例。
2. 來源超出支援 grammar：看到 gantt、mindmap、timeline 等 unsupported kind 就停，不要讓 Agent 自行近似。
3. 一張圖塞到底：超過 detail 預算時，依序移除裝飾、合併完全重複項、收斂 leaf cluster、刪除不影響故事的單連線終點與橫切基礎設施；仍超量才拆 overview＋detail，不要縮字。
4. 把星數當品質：Trending 是滾動注意力快照；真正要看的是自己的輸入、兩次重跑與目標閱讀環境。
5. 把 named image 當完整可及性：title／desc提供整張圖的名稱與描述，不等於螢幕閱讀器能逐節點走圖；複雜資訊仍要在正文保留文字版。
6. 把綠色 CI 當像素保證：靜態 linter 能抓結構錯誤，抓不到所有字型替換、瀏覽器版本差異與視覺碰撞。把 render-and-diff 另列一關。

Mermaid、Diagram Design、Figma／draw.io 怎麼選？

• 選 Mermaid：圖和程式碼一起版本控制、變動頻繁、團隊最在意 diff 與可重生性。
• 加一層 Diagram Design：內容已穩定，下一步是品牌、簡報、文件或交付格式；Mermaid 仍保留為骨架。
• 進 Figma／draw.io：多人要精修每個位置、需要手動審美判斷或客戶會直接編輯最終檔。Diagram Design 可先產生 SVG，但不要假設字型匯入後完全不變。

這三者不是競品淘汰賽，而是不同層。最穩的團隊流程通常是「文字原始檔可 diff、交付版可閱讀、最後一哩允許人工修正」。若你想把這種分層延伸到完整 Agent 專案，動手打造 AI Agent Harness有可重跑的控制迴圈範例。

常見問題 FAQ

1. Diagram Design 免費嗎？

程式庫是。目前倉庫採 MIT License；但實際執行 coding agent、模型與 CI 的成本仍由你使用的 Claude Code／Codex 方案與運算環境決定。

2. 它會取代 Mermaid 嗎？

不會。Mermaid 很適合當可版本控制的內容骨架；Diagram Design 解的是讀者視角、品牌與交付問題。把兩者分層，通常比只留漂亮 PNG 更可維護。

3. 每一種 Mermaid 都能直接匯入嗎？

不能。目前 importer 明列支援 flowchart／graph、sequence、stateDiagram-v2 與 ER；其他 grammar 應在 extractor 報錯後停止，改由文字需求重新建圖，而不是冒充無損匯入。

4. SVG 可以在 Figma 繼續編嗎？

可以編向量，但先驗字型。SVG 保留 vector text；若 Figma 匯入時沒抓到遠端字型或 CJK fallback 不同，換行與節點尺寸可能改變。交付前要在真正的 Figma 檔打開檢查。

5. PNG 一定是透明背景嗎？

不一定。omit_background=True 只移除瀏覽器底色；SVG 裡若有滿版背景矩形，像官方範本那樣，該底色仍會留在 PNG。預設倍率是 2×，是否帶 alpha 要看 SVG 自己的圖形。

6. 可以完全離線或直接丟進 CI 嗎？

不會自動做到。核心 extractor 多數只用 Python 標準庫，但 HTML／SVG 預設會碰遠端 Google Fonts，PNG 另需 Playwright＋Chromium。要穩定 CI，請自行固定瀏覽器與字型，並加入實際 render gate。

7. Claude Code 與 Codex 產物會一樣嗎？

不要假設會一樣。倉庫讓兩邊讀同一套 skill 與 profile，但沒有跨 host 像素等價契約或比較實驗。若工作要求像素重現，固定 host、模型、上下文、字型與瀏覽器並保留 render diff，別只固定 prompt。

8. 有 title、desc 就算無障礙完成嗎？

不算完成。這是好的 accessible-name 基礎，但複雜圖仍需要正文摘要、正確 alt、對比與縮放檢查；重要流程最好保留文字步驟，不能只藏在圖裡。

給新手的 5 個重點

1. Mermaid 留作骨架；Diagram Design 負責重編與交付。
2. 先定 format、size、detail、audience，才開始畫。
3. 品牌設定先看 diff、再批准，profile 不要和已安裝檔混在一起。
4. SVG 驗字型，PNG 驗 Playwright／Chromium 與透明度。
5. self-check、人工視覺 QA、乾淨環境重跑，三者缺一不可。

想把圖表背後的系統邊界、資料流與取捨也講清楚，可到 AlphaLab 的軟體工程課程練習完整 System Design；更多新手 AI 實作則收在AI 專區。