跳至主要内容

Mermaid 圖表範本庫與語法

本目錄有 2 種資源：

類型文件何時用
📖 語法教學Mermaid 語法速查學語法、查語法、不熟時看
📋 範本庫（8 種圖型）見下方清單要畫圖時複製修改

使用建議：先看範本庫（複製即用），看不懂再查語法速查，特殊需求才去官方文件（mermaid.js.org）。

為什麼有這個範本庫​

  • 一致性：公司所有文件風格統一
  • 速度：5 分鐘搞定，不是 30 分鐘嘗試
  • 品質底線：範本都遵循 PM repo 的 docs/shared/agent-rules/COMMON-RULES.md 圖表規範
  • Agent 友善：Agent 讀得懂範本，產出的圖品質更穩

範本清單​

範本用途典型場景
Architecture Flowchart系統架構 / 分層結構系統概觀、模組關係、部署拓撲
Sequence Diagram元件互動 / 訊息流API 流程、Protocol 交握、Agent 協作
State Machine狀態轉換Pipeline 狀態、設備 state model、UI flow
Gantt Project專案時程Roadmap、Phase 規劃、release 排程
ERD Database資料模型資料庫 schema、entity 關係
Class DiagramOOP 結構類別繼承、Interface 關係
User Journey使用者體驗訪客動線、工作流程體驗
Git BranchGit 分支策略PR workflow、release branching

怎麼用​

Step 1：找對範本​

依「你要表達的內容」選對圖型（不是依好不好看）：

我要表達…
├── 「誰連誰、系統長怎樣」     → flowchart
├── 「先做 A，再做 B」         → flowchart (LR) 或 sequence
├── 「A 跟 B 在溝通」           → sequenceDiagram
├── 「狀態怎麼變」              → stateDiagram-v2
├── 「什麼時候做什麼」          → gantt
├── 「資料表長怎樣」            → erDiagram
├── 「類別 / 介面結構」         → classDiagram
└── 「使用者感受」              → journey

Step 2：複製範本​

直接複製整個 Mermaid 區塊到你的文件。

Step 3：依樣畫葫蘆改​

  • 換節點文字（必須是完整句子，不能用 A/B/C）
  • 換邊的 label（特別是決策樹的 Yes/No）
  • 改顏色（重點節點才加色）
  • 加 subgraph 分組（節點 > 10 時）

Step 4：Review Checklist​

發布前檢查：

  • 節點文字有意義（不是代號）
  • 邊有 label（特別是分支）
  • 圖前後有文字說明
  • 手機上可讀（別太寬）
  • 如果 > 10 節點，有用 subgraph

Agent 使用這個範本庫​

Agent（如 PM、Strategist、Architect）寫文件時應該：

  1. 需要畫圖 → 先來這找最接近的範本
  2. 複製 + 修改
  3. 符合 COMMON-RULES 的品質標準

不要從零寫 Mermaid，除非這個範本庫沒有適用的。

貢獻新範本​

如果發現某種圖常用但沒範本，請新增：

  1. 在本目錄建新 .md
  2. 依現有範本格式（標題、用途、範本程式碼、客製化建議）
  3. 更新本 README 的範本清單