Content Mermaid
為技術流程與結構產生 Mermaid 圖表。這是 content-diagrams 的快速、語法驅動的對應版本：擁有相同的視覺清晰度標準，但建立在一個已保證幾何正確性的語言上，因此心力投入在選擇正確的圖表類型以及可讀、一致的色彩系統，而非驗證座標。
與 content-diagrams 的關係
兩個技能共享相同的標準——可讀的文字、真正的色彩系統（而非裝飾）、清晰勝過密度——但 content-diagrams 自行計算 SVG 幾何，而此技能將幾何完全交給 Mermaid 佈局引擎；根據圖表實際被檢視的地方（原生 Mermaid 表面 vs. 僅顯示靜態圖片的平台）來選擇，而不是根據習慣，如果不確定就詢問——Mermaid 原始碼若不經實際重新處理，無法乾淨地螢幕截圖成精美的獨立圖形。
為什麼這裡沒有驗證循環
content-diagrams 大部分心力花在幾何上：SVG 線條、方框或標籤只是 Claude 計算出的數字，而計算出的數字可能出錯——因此需要渲染、截圖、裁切、檢查。
Mermaid 完全消除了那種失敗模式。節點寬度、文字換行、箭頭路徑以及元素間的碰撞避免是渲染器的工作，而非 Claude 的工作——渲染器不會將標籤放在方框之上，也不會將線條穿越形狀。在此複製那個驗證循環（將渲染後的圖表截圖、裁切、檢查重疊）只會浪費 token 和延遲，去確認工具已經保證的事情。
仍然可能出錯的部分完全不同，而且完全是文字層面的：
- 語法錯誤（未閉合的括號、用作節點 ID 的保留字、不符的箭頭類型）
- 邊引用了一個從未定義的節點 ID
- 色彩對比度差（填充色和文字色實際閱讀起來彼此不協調）
- 針對內容實際結構選錯了圖表類型
因此，此處的驗證意味著：將語法從頭到尾檢查一次正確性，確保每個 classDef 都將填充色與真正對比的文字色配對，並確認圖表類型與被建模的內容相符。不需要影像渲染。
圖表類型選擇
根據內容本身的結構來選擇類型——這是 Mermaid 版本的 content-diagrams 主題選擇：
| 內容結構 | Mermaid 類型 |
|---|---|
| 帶有分支/迴圈的順序步驟（流程、工作流程、演算法） | flowchart TD（由上而下）或 LR（由左至右，用於管道/時間軸） |
| 服務/角色之間按時間排序的訊息（API 呼叫、協定交換） | sequenceDiagram |
| 實體的狀態與其間的轉換（生命週期、狀態機） | stateDiagram-v2 |
| 資料模型/實體關係（綱要、資料庫表格） | erDiagram |
| 物件導向結構（類別、繼承、介面） | classDiagram |
| 具有持續時間和相依性的時程 | gantt |
| 無嚴格順序的層級式分解/腦力激盪 | mindmap |
| 按時間順序的敘事（專案歷史、版本歷史） | timeline |
| 雙軸優先級（影響力 vs. 努力等） | quadrantChart |
不要凡事都預設使用 flowchart——像「圖表化我們的服務如何互相呼叫」這樣的請求應該是 sequenceDiagram，即使容易想用方框和箭頭來畫；像「展示票證經歷的狀態」這樣的請求是 stateDiagram-v2，而不是用菱形充當狀態的流程圖。
色彩與可讀性系統
這是人工驗證仍然重要的領域，因為 Mermaid 會愉快地渲染出難以閱讀的色彩選擇而不發出抱怨。
規則：每個 classDef 必須將填充色與一個特意選擇與之對比的文字色配對——絕不要留下 color 不設定，指望主題的預設值能起作用。 Mermaid 自己的預設調色板（淡綠/粉紅/藍色搭配黑色文字）之所以沒問題，正是因為填充和文字是一起選擇的；一旦你將 fill 覆蓋為更飽和或更暗的顏色，你必須也明確設定 color，否則就會重現一個常見的缺陷：看起來可讀的方框，但實際上文字與其對比度很低。
兩種調色板配方，選擇一種並在一個圖表中的每個類別一致地使用（不要混用）：
- 深色填充 / 白色文字（預設方案——經過驗證、高對比度、在淺色和深色聊天主題中都能良好閱讀）：
classDef category1 fill:#1e3a5f,stroke:#0d1f33,stroke-width:2px,color:#ffffff - 淺色調填充 / 深色文字 / 飽和邊框（當圖表需要與遵循其淺色調慣例的 content-diagrams SVG 在視覺上並排放置時使用）：
classDef category1 fill:#e1f0ff,stroke:#1e3a5f,stroke-width:2px,color:#1a1a1a
直接借用 content-diagrams 的規則：每個類別一個色調，並在該類別出現的每個地方都應用它——在該角色的每個節點上使用相同的填色和邊框顏色，而非一次性使用。根據角色分配色調，例如：
- 藍色 → 輸入 / 資料 / 待辦項目
- 綠色 → 流程 / 進行中的工作步驟
- 琥珀色或棕色 → 決策點 / 閘門
- 紫色 → 輸出 / 發行版 / 終止狀態
- 紅色 → 回饋迴圈 / 失敗路徑 / 回顧
鎖定畫布，使其不依賴主機的淺色/深色模式。 在圖表的第一行放一個 init 指令：
%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'Trebuchet MS, Verdana, Arial, sans-serif', 'fontSize': '16px', 'primaryColor': '#1e3a5f', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0d1f33', 'lineColor': '#666666', 'background': '#ffffff' } } }%%
theme: 'base' 加上明確的 themeVariables 意味著無論主機環境預設使用哪個 Mermaid 主題，圖表看起來都一樣——不要只依賴主題名稱（default、dark、forest 等），因為那會讓實際顏色由渲染器決定。
字型大小：對於節點超過少數幾個的圖表，最小 16px；只有在圖表簡單到可讀性不成問題時才使用 14px。如果圖表需要縮小到 14px 以下才能容納標籤，那就是 content-diagrams 中相同的「清晰勝過密度」信號——拆分圖表或刪減內容，不要進一步縮小文字。
不同圖表類型的樣式設定範圍不同：flowchart、stateDiagram-v2 和 classDiagram 都直接支援按節點進行 classDef/class 指派，因此請逐節點使用上述的類別色彩系統。sequenceDiagram、erDiagram 和 gantt 的逐元素樣式設定能力非常有限——針對這些類型，應將心力投入 init 區塊中的 themeVariables（序列圖的 actorBkg、actorTextColor、noteBkgColor 等），而不要期望節點層級的類別能以相同方式運作。
箭頭語法
與手寫 SVG 不同，Mermaid 會自動放置箭頭標籤，且位置正確——-->|label| 文字不會像手動定位的 SVG 標籤那樣有落在形狀之上的風險。因此，與 content-diagrams「將文字留在箭頭之外，透過圖例解碼」的預設相反，直接在箭頭上標註標籤是可行的，而且通常更清晰。但還是要將標籤保持為短片段（「已核准」、「重試」、「失敗時」），而非句子——標籤是標記，不是句子。
保留線條樣式用於與 content-diagrams 相同的廣泛區分：
- 實線箭頭 (
-->) → 主要/正常流程 - 虛線箭頭 (
-.->) → 回饋、可選路徑，或外部/間接互動 - 粗箭頭 (
==>) → 強調的或關鍵路徑，應節制使用
保持標籤簡短；使用子圖進行分組
節點文字應為短語，而非句子——Mermaid 會像其他工具一樣，對段落長度的標籤進行尷尬的換行或溢出。如果節點需要多行，請在標籤內使用 <br/> 明確插入，而不是依賴自動換行在合理的位置斷行。
使用 subgraph 來聚類相關步驟（例如，同一個衝刺、同一個部署階段、同一個服務邊界內的所有內容）——它是 Mermaid 版本的群組方框，並可透過它自己的 style SubgraphName fill:...,stroke:... 行來設定樣式。不要將子圖嵌套超過一層；這會很快變得難以閱讀。
工作流程
- 識別底層結構並從上方的表格中選擇圖表類型，然後再開始編寫語法。
- 為出現的角色分配類別色彩（輸入、流程步驟、決策、輸出、回饋）——用一兩句話先勾勒出這個分配，就像 content-diagrams 的「勾勒主題推理步驟」，這樣如果使用者想要調整某個部分時，選擇是可稽核的。
- 編寫圖表，從
%%{init: ...}%%指令開始，然後是結構，接著是classDef/class指派（或針對不支援按節點類別的類型使用 themeVariables）。 - 自行檢查語法——每個在邊中使用的節點 ID 都在某處定義；每個
classDef都同時設定了fill和color；括號/引號是平衡的；沒有段落長度的標籤。不需要渲染，不需要截圖。 - 透過
create_file儲存為.mermaid檔案，以便它作為內嵌的成品渲染，使用描述性的 slug：/mnt/user-data/outputs/<slug>.mermaid。使用present_files展示。 - 如果使用者需要可攜帶的靜態圖片形式的圖表（用於嵌入不會渲染 Mermaid 的地方，或用於歸檔），請直說：此環境無法可靠地執行無頭 Mermaid 到圖片匯出（這依賴於沙盒網路通常無法連線的 Chromium 下載）。建議使用 mermaid.live 進行手動匯出，或者如果真正的需求是獨立圖形，則切換到
content-diagrams。
不該做的事
- 不要在覆蓋
fill之後遺留classDef的color未設定——這正是此技能存在要避免的對比度錯誤。 - 不要在一個圖表中混用深色填充和淺色填充配方。
- 不要將每個請求都預設為
flowchart——選擇與實際結構相符的類型（序列、狀態、實體關係等）。 - 不要在此處重新引入 content-diagrams 的渲染/裁切/驗證循環——它解決的是 Mermaid 佈局引擎沒有的問題。
- 不要在節點標籤中放入段落長度的文字；使用
<br/>換行或刪減內容。 - 不要將子圖嵌套超過一層。
- 不要在未附加說明無頭 Mermaid 渲染可能在此處無法運作的情況下，承諾從此沙盒產出乾淨的 PNG/SVG 匯出。