Diagram Design
建立自包含的 HTML 檔案，內嵌 SVG 以及編輯設計系統。
四十五種視覺類型。語義模式描述行為；類型引用描述佈局。
0. 首次設定 — 風格指南關卡
在專案中產生第一個圖表之前，請確認風格指南已客製化。
請勿在品牌化專案中默默地套用預設外觀的圖表。
首先根據 references/profiles.md 的說明，確認專案中是否存在 .diagram-design 標記；成功解析的標記會選擇其設定檔，並跳過此關卡。該引用文件負責處理失敗、受保護的預設值以及儲存行為。
開啟 references/style-guide.md 並檢查預設代幣。如果仍然是出廠預設值（紙 #f5f5f5、墨 #2d3142、強調色 #bf4520），請暫停並詢問使用者：
「這是您在此專案中的第一個圖表，而且風格指南仍為預設值。現在要客製化嗎？選項：(a) 網站 URL、(b) 已安裝的技能、(c) 本地資料夾/設計系統、(d) 貼上代幣、(e) 保留預設、(f) 載入已儲存的設定檔。」
然後根據 references/onboarding.md 的對應章節進行分支處理；對於 (f) 選項，請遵循 references/profiles.md 的說明。
一旦風格指南已客製化（或使用者明確選擇保留預設值），則在後續執行時跳過此關卡。開頭的設定檔標頭會命名已複製進來的啟用中設定檔。如果沒有標頭，任何與出廠預設值不同的語義角色值或排版字體系列都表示「已客製但未儲存」：跳過關卡，並提供將其儲存為設定檔的選項。所有預設代幣且無標記/標頭則會觸發此關卡。導入完成後，根據 references/profiles.md 的說明，提供將其儲存為指定客戶端設定檔的選項。
1. 理念
最高品質的動作通常是刪除。
應用於示意圖：
- 每個節點代表一個獨特的概念。兩個總是同時出現的節點應視為一個節點。
- 每個連接都承載資訊。如果關係可以從佈局中明顯看出，則移除該線條。
- 珊瑚色是編輯重點，而非標記。 每個圖表 1–2 個焦點節點。在 5 個節點上使用它會抹煞其信號作用。
- 示意圖不是在所有東西都加上時完成，而是在無法再移除任何東西時完成。
目標密度：4/10。 足以達到技術上的完整，但又不至於密集到需要導引。超過 9 個節點，可能表示應該拆分為兩個圖表。
2. 使用時機
當讀者從視覺圖表中能學到比從散文、表格或項目符號列表更多時，請使用這 45 種視覺類型中的任何一種（§3）。
不適用於：
- 快速的 Unicode 圖表 → 使用其他純文字工具，例如 wiretext。此技能不提供此功能。
- 事物列表 → 使用表格或項目符號。
- 僅屬性的前後對照 → 使用表格；拓撲變更 → 使用架構差異圖。
- 單一形狀的「圖表」 → 直接寫成句子。
在繪製之前，請問：讀者從這個圖表中學到的東西，會比從一個寫得很好的段落中學到的更多嗎？ 如果不會，就不要繪製。
3. 選擇：先選語義模式，再選視覺類型
當行為、狀態、強制執行或風險承載意義時，請先載入 references/semantic-patterns.md 並選擇一個主要模式。然後為佈局選擇最接近的視覺類型。如果沒有符合的模式，則直接選擇類型。
| 行為觸發器 | 語義模式 → 最接近的類型 |
|---|---|
| 扇入、佇列深度、有限容量、瓶頸 | 扇入佇列 / 瓶頸 → 資料流 |
| 跨階段的重複問題 / 輸入 / 治理 / 輸出插槽 | 具有語義插槽的階段框架 → 流程 |
| 對話或鬆散輸入變成結構化的持久工件 | 非結構化輸入 → 結構化工件 → 資料流 |
| 需要通過/失敗/跳過/未達及首次分歧的兩個規則軌跡 | 成對的策略評估軌跡 → 流程圖 |
| 信任邊界加上允許/禁止的入口或部署路徑 | 安全鋪設道路 → 架構 |
| 按強制執行位置分組的控制項 | 治理 / 控制目錄 → 圖層堆疊 |
| 防禦措施彌補先前的漏洞，且殘餘風險會傳播 | 補償性安全層 → 圖層堆疊 |
| 需要每個區塊 I/O、約束和程式碼連結的階層式、ID 可尋址分解 | 可追蹤區塊分解 → 樹狀圖 |
| 一個主體經歷階段、等待、重試、取消和最終結果 | 生命週期階段圖 → 狀態機 |
模式擁有語義基本元素及其更嚴格的預算；類型擁有佈局語法。僅在要求動畫或動畫能實質上澄清有序變更時，才使用 references/animation.md；靜態仍為預設值。
視覺類型指南（45 種）
| 如果您要展示… | 使用 | 參考資料 |
|---|---|---|
| 在單一快照中的元件 + 連接；巢狀管理與流量範圍 | 架構 | type-architecture.md |
| 同步的「Before/After」拓撲之間的結構變更，附有變更清單 | 架構差異 | type-architecture-delta.md |
| 按階段或部門劃分的舊版 IT 環境；顯示「Before」狀態 | IT 現況 | type-it-state.md |
| 帶有分支的決策邏輯 | 流程圖 | type-flowchart.md |
| 參與者之間依時間排序的訊息 | 時序圖 | type-sequence.md |
| 狀態 + 轉換 + 守衛 | 狀態機 | type-state.md |
| 實體 + 欄位 + 關係 | ER / 資料模型 | type-er.md |
| 事件在時間軸上的定位 | 時間軸 | type-timeline.md |
| 跨功能流程與交接 | 泳道圖 | type-swimlane.md |
| 雙軸定位 / 優先排序 | 象限圖 | type-quadrant.md |
| 根據 3–5 個量化標準對多個實體進行評分 | 雷達圖 / 蜘蛛圖 | type-radar.md |
| 跨循環類別的一個量化系列；角度 = 類別，半徑 = 幅度 | 極座標圖 | type-polar.md |
| 強化循環；最後一步回饋到第一步，且一個樞紐累積狀態 | 循環圖 | type-loop.md |
| 透過包含 / 範圍形成的階層 | 巢狀圖 | type-nested.md |
| 父 → 子關係 | 樹狀圖 | type-tree.md |
| 人員/代理/團隊所有權、報告、路由、升級 | 組織圖 | type-org-chart.md |
| 堆疊的抽象層級 | 圖層堆疊 | type-layers.md |
| 一個物件的零件沿著一個軸線拆開：拆解、開箱、組裝順序 | 分解軸測圖 | type-exploded.md |
| 從上方以某個角度看到的單一樓層或地點：帶有家具的房間、按階段劃分的建築物 | 軸測平面圖 | type-axonometric-plan.md |
| 集合之間的重疊 | 文氏圖 | type-venn.md |
| 排序的階層或轉換漏斗 | 金字塔圖 / 漏斗圖 | type-pyramid.md |
| 跨類別的量化比較 | 長條圖 | type-bar.md |
| 透過正負貢獻（預算橋接、員工人數差異）將起始總數連結到結束總數 | 瀑布圖 | type-waterfall.md |
| 部分佔整體中，相對大小才是重點 | 樹狀圖 | type-treemap.md |
| 交叉表資料；填色編碼每個儲存格的值 | 熱力圖 | type-heatmap.md |
| 隨時間變化的連續趨勢、兩個狀態之間的變更（坡度圖）、每個系列一個分佈（山脊線圖）或跨多個快照的排名變動（碰撞圖） | 折線圖 | type-line.md |
| 時間軸上的任務和階段 | 甘特圖 | type-gantt.md |
| 兩個變數的相關性或分佈；泡泡圖（三個變數）和蜂群圖（一個變數，每個項目一個點）的變體 | 散點圖 | type-scatter.md |
| 在容器叢集上的端對端資料堆疊 | 高階圖 | type-high-level.md |
| 多參與者的循序流程與資料交接 | 流程圖 | type-process.md |
| 具有品質等級和存取策略的多層資料儲存 | 獎章圖 | type-medallion.md |
| 按角色劃分的資料流：每個管線步驟中誰做什麼 | 資料流 | type-data-flow.md |
| 資料平台的整合拓撲 — 來源 → 核心 → 消費者 | DP 整合 | type-dp-integration.md |
| 按角色 / 按元件的存取權限矩陣 | DP 安全矩陣 | type-dp-security-matrix.md |
| 一個數量在階段中拆分和合併，頻寬 = 數量 | 桑基圖 | type-sankey.md |
| 一個觀察到的結果的多個原因，按類別分組（根本原因分析） | 魚骨圖 | type-fishbone.md |
| 針對演進的價值鏈 — 要建置什麼、購買什麼、以及什麼正在改變 | Wardley 地圖 | type-wardley.md |
| 依狀態區分的工作進行中項目，包含 WIP 限制和受阻項目 | 看板圖 | type-kanban.md |
| 一個人在體驗的各個階段做了什麼，以及他們的感受 | 使用者旅程圖 | type-journey.md |
| 客戶做了什麼 vs 服務隱藏了什麼，跨階段，附有一條可見線 | 服務藍圖 | type-service-blueprint.md |
| 軟體運作的位置 — 區域、主機、工件、副本、連接埠 | 部署圖 | type-deployment.md |
| 什麼依賴於什麼，具有樹狀結構無法表達的扇入和循環 | 相依性圖 | type-dependency.md |
| 帶有操作、繼承、組合的類別（其他 UML 路線請參閱其他文件） | UML 類別圖 | type-uml-class.md |
| 將敘事主幹拆分為釋出，包含切割線 | 故事地圖 | type-story-map.md |
| 實體資料表：SQL 類型、約束、索引、欄層級的外鍵 | 資料庫結構描述 | type-db-schema.md |
經驗法則：
- 如果一個 3 欄的表格能傳達相同的資訊，請使用表格。
- 如果兩種看起來都適用，請選擇主要的軸線；語義模式可能添加特定於行為的基本元素，而非第二種佈局語法。
- 如果超出複雜度預算（§7），請拆分為概覽 + 詳細資訊。
在繪製之前，請務必載入指南中連結的所選類型參考資料。 如果經由上方路由，也請載入 semantic-patterns.md；如果選擇了動畫，請載入 animation.md。
在繪製之前確認
在轉譯之前，用一則簡短的訊息說明計劃：所選的視覺類型（以及語義模式，如果經由路由）、尺寸預設，以及任何將因複雜度預算（§7）而被排除的內容。如果可以聯繫到使用者，讓他們在您繪製之前重新導向；如果不行，則繼續進行，並在交付成果旁備註假設事項。僅在請求已精確指定類型、尺寸和內容時，才跳過此暫停。
4. 通用反模式
這些標記任何類型的「AI 垃圾」示意圖：
| 反模式 | 失敗原因 |
|---|---|
| 深色模式 + 青色/紫色發光 | 看起來「很技術」，但沒有設計決策 |
| 將 JetBrains Mono 作為通用的「開發」字體 | 等寬字體是給技術內容使用的 — 連接埠、命令、URL。名稱應使用 Geist 無襯線字體。 |
| 每個節點都使用相同的方框 | 抹煞了階層結構 |
| 圖例浮在圖表區域內 | 與節點碰撞 |
| 箭頭標籤沒有遮罩矩形 | 會與線條重疊 |
箭頭上的垂直 writing-mode 文字 | 難以閱讀 |
| 3 個等寬的摘要卡片作為預設值 | 通用網格 — 應變化寬度 |
| 任何元素上的陰影 | 陰影已過時。邊框當道。 |
方框使用 rounded-2xl | 最大圓角半徑為 6–10px 或無 |
| 每個「重要」節點都使用珊瑚色 | 珊瑚色是 1–2 個編輯重點，而非信號系統 |
| 複製 Mermaid 的轉譯器佈局 | 匯入自動間距和路由，而非製作編輯佈局 |
| 違反任何一條六項 §6 連接器規則 | 自動失敗：對角線傾斜、標籤接觸其描邊、遮罩被後續節點裁剪、重疊路徑、共享附加點、經過非端點方塊的傳遞 |
特定類型的反模式存在於指南中連結的每個類型參考資料中。
5. 設計系統
設計系統是可更換外觀的。 references/style-guide.md 是顏色、排版、代幣和預設調色盤的唯一真相來源；此檔案命名語義角色（paper、ink、muted、accent、link…）。若要套用品牌，請編輯 style-guide.md 或執行 references/onboarding.md 中基於 URL 的流程。
當下方的規格或類型參考資料中提到「ink」、「accent」、「muted」等時，請查閱
style-guide.md中目前的十六進位值。
類型參考資料的程式碼片段將角色寫為佔位符：{ink}、{ink @ 0.40}（用於某個透明度的角色），以及 {node-name}、{sublabel}、{eyebrow}、{arrow-label}、{title}、{callout}（用於字體）。在輸出之前，請根據 style-guide.md 解析所有佔位符。
語義角色（一覽）
| 角色 | 用途 |
|---|---|
paper、paper-2 | 頁面背景和容器背景 |
ink | 主要文字 / 描邊 |
muted、soft | 次要文字、預設箭頭、子標籤 |