AI

diagram-design：讓 AI Agent 畫出「有品牌感」的技術圖表，告別千篇一律的 Mermaid

Monday

本內容僅供參考，詳細使用規則與工具安全性與否，建議要進行相關安全性測試與評估

請 AI Agent 幫忙畫架構圖，大多數人得到的都是同一種東西：一張 Mermaid 流程圖，預設配色、方框加箭頭，能看但不好看，更不可能直接放進簡報或對外文件。diagram-design（cathrynlavery/diagram-design）的標語很直白：「No shadows. No Mermaid slop.」——它是一個 Agent Skill，讓 Agent 照著一套嚴格的設計規範，產出符合你品牌風格的單一檔案 HTML + SVG 圖表。專案目前約 57.7k stars，出現在 10 月 12 日的 AI 開源趨勢報告中。

1. 專案背景與定位

diagram-design 由 Cathryn Lavery 開發，MIT 授權。它不是一個繪圖軟體，也不是一個新的圖表語法，而是一份讓 Agent 變成資訊設計師的規範與素材包：告訴 Agent 該選哪種圖、怎麼排版、用什麼字型與配色，再輸出一個雙擊就能離線開啟的 HTML 檔。

支援 Claude Code、Codex、GitHub Copilot、Cursor、Factory Droid、Pi、Gemini CLI、Cline、Windsurf、Amp、Kiro、OpenCode 等，安裝方式為 npx skills add cathrynlavery/diagram-design 或各 Agent 的 plugin marketplace。

2. 技術架構與核心設計

  • 40 多種圖表類型（About 寫 44 種、README 正文寫 45 種）：架構圖、流程圖、序列圖、狀態機、ER 圖、時間軸、象限圖、Sankey、甘特圖、Wardley map、UML 類別圖、爆炸軸測圖等，部分類型還有 slopegraph、bubble、marimekko 等變體。每種都有淺色極簡、深色極簡、完整編輯風三種樣式。
  • 單一檔案輸出：一個 HTML 檔內嵌 SVG，不需要建置、不需要 JavaScript，雙擊即可離線開啟；另可匯出純 SVG，或透過 Playwright 以 2 倍解析度輸出 PNG。
  • 嚴格的設計規則：
    • 只用一個強調色，標示 1–2 個焦點元素
    • 1px 細線框、沒有陰影、圓角最大 10px
    • 所有座標、寬度與間距都必須是 4 的倍數
    • 固定三種字型：Instrument Serif、Geist、Geist Mono
  • 品牌自動擷取：Agent 會抓取你的網站、擷取配色與字型，對應到 paper、ink、accent、title font 等角色，檢查 WCAG AA 對比度，並在寫入設定前先給你看差異；支援多個客戶的品牌設定檔。
  • 舊圖重繪：可以匯入 draw.io、Mermaid、Excalidraw 檔案重新繪製，用格式、尺寸、細節程度、目標讀者四個「旋鈕」調整，最後附上一份「保真度清單」，列出哪些內容被合併、收斂或捨棄。
  • 其他素材：註解元件、手繪風濾鏡、87 個圖示，以及跨 Linux、Windows、macOS 的 CI 驗證。

3. 社群熱度與生態採用

約 57.7k stars、3.7k forks、357 commits，open issue 只有 16 個。官方提供線上範例圖庫，包含 OAuth 序列圖、動畫政策追蹤圖、手機拆解圖等。在 Agent Skill 爆發的這段期間，它是少數聚焦在「輸出品質與美感」而非工程流程的熱門 Skill。

4. 局限性與潛在風險

  • 輸出不穩定：README 自己承認，品質取決於模型，同樣的 prompt 可能排出不同版面。
  • 無法在 PR 中 diff：輸出的 HTML/SVG 不是可編輯的原始格式，圖表改了什麼很難在 code review 中看出來。官方建議：放在 Git 裡、經常變動的文件，還是用 Mermaid。
  • 不適合所有內容：清單、前後對照、只有一個方框的「圖」，官方明說不適合用它。
  • 品牌擷取會連外：Agent 會抓取指定網站，預設也會從 Google Fonts 載入字型（可改用系統字型）。在受限網路或處理未公開品牌時要注意。
  • 重繪可能遺漏資訊：匯入舊圖時會合併或捨棄部分內容，雖然有保真度清單，仍應人工確認關鍵資訊沒有被拿掉。
  • 圖表正確性仍需人工驗證：圖畫得漂亮不代表架構描述正確，特別是 Agent 自行推斷系統關係時。

5. 應用價值與適用場景

最適合需要對外呈現的技術圖表：簡報、提案、技術部落格、產品文件、客戶交付物。品牌擷取功能對顧問與代理商特別有用——同一個 Agent 可以為不同客戶產出各自風格的圖。設計團隊人力有限的新創，也能用它快速做出一致、專業的視覺素材。

至於工程團隊內部、需要頻繁更新並納入版本控管的架構文件，Mermaid 或 PlantUML 這類文字格式仍然比較合適。

Monday 的觀點與架構建議

  • diagram-design 證明了一件事：Agent 輸出的品質上限，很多時候取決於「規範」而不是模型。把「4 的倍數格線、單一強調色、無陰影」這類設計原則寫成 Skill，就能讓同一個模型的產出從「堪用」變成「可以直接拿去用」。
  • 「保真度清單」是很值得推廣的設計：任何 AI 轉換工作（重繪、翻譯、摘要、重構）都應該明確列出「改了什麼、丟了什麼」，讓人可以快速驗收。
  • 建議的使用分工：內部持續演進的文件用文字格式圖表；對外、定稿的內容再交給 diagram-design 產出精緻版本。
  • 這兩週介紹的 Skill 從工程紀律（Superpowers、agent-skills）、程式精簡（Ponytail）一路延伸到視覺設計，Agent Skill 正在變成「把各種專業知識打包給 AI」的通用格式。

參考來源