圖表設計
建立自包含的 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 並選擇一個主要模式。然後為佈局選擇最接近的視覺類型。如果沒有匹配的模式，則直接選擇類型。
| 行為觸發條件 | 語意模式 → 最接近的類型 |
|---|---|
| 扇入、佇列深度、有限容量、瓶頸 | 扇入佇列 / 瓶頸 → 資料流 |
| 跨階段的反覆問題 / 輸入 / 治理 / 輸出插槽 | 具有語意插槽的階段框架 → 流程 |
| 對話或鬆散輸入轉變為結構化的持久工件 | 非結構化輸入 → 結構化工件 → 資料流 |
| 需要通過/失敗/跳過/未到達及首次分歧的兩條規則追蹤 | 配對的政策評估追蹤 → 流程圖 |
| 信任邊界加上允許/禁止的入口或部署路徑 | 安全鋪設路徑 → 架構 |
| 按執行位置分組的控制項 | 治理 / 控制目錄 → 圖層堆疊 |
| 防禦措施補償先前的缺口，且殘餘風險會傳播 | 補償性安全層 → 圖層堆疊 |
| 層級式、可透過 ID 定址的分解，需要每個區塊的 I/O、約束條件和程式碼連結 | 可追蹤的區塊分解 → 樹狀圖 |
| 一個主體經歷多個階段、等待、重試、取消和最終結果 | 生命週期階段圖 → 狀態機 |
模式擁有語意基本元素及其更嚴格的預算；類型擁有佈局語法。僅在請求動畫或動畫能實質性地闡明有序變化時，才使用 references/animation.md；靜態圖表仍為預設值。
視覺類型指南（45 種）
| 如果你在展示… | 使用 | 參考文件 |
|---|---|---|
| 單快照中的元件 + 連線；巢狀管理與流量範圍 | 架構 | type-architecture.md |
| 同步的 Before / After 拓撲之間的結構性變化，附帶變更記錄 | 架構差異 | type-architecture-delta.md |
| 按階段或部門劃分的舊有 IT 環境；顯示之前的狀態 | 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 |
經驗法則：
- 如果一個三欄表格能傳達相同資訊，請選擇表格。
- 如果兩種類型似乎都有用，請選擇主軸；語意模式可能會添加特定於行為的基本元素，而不是第二種佈局語法。
- 如果你超出了複雜度預算（§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 | 次要文字 / 筆畫 |
accent | 強調色，用於 1–2 個焦點節點 |
link | 超連結顏色 |
（更多角色和它們的十六進位值、字型系列、間距代碼，請參閱 style-guide.md。）
6. 連線規則
所有圖表類型的連線都必須遵循這六條規則：
- 連線必須是正交的（水平和垂直路徑）。禁止對角線。
- 標籤不得接觸其筆畫。 始終為文字標籤使用遮罩矩形（
<rect>），覆蓋在其後面的連線部分之上。 - 遮罩不得被其他節點裁剪。 確保標籤遮罩的 z 索引高於所有重疊的節點。
- 連線不得重疊。 多條平行線之間至少保持 4px 間距。
- 連線必須連接到專用的連接點。 節點上的每個連接點只能用於一條連線的起點或終點。
- 連線不得穿過非端點節點。 路徑必須繞過其端點之間的中間節點。
違反任何規則都是自動失敗。
7. 複雜度預算
- 節點上限（大多數類型）：9 個。 超過此數量，請將圖表一分為二，或為主要圖表選擇 9 個關鍵節點，並將其餘的放入詳細圖表中。
- 連線密度： 每節點不超過 2 條連線（平均）。總連線數應少於節點數的 2 倍。
- 圖層上限（圖層堆疊）：6 層。
- 泳道上限：5 條泳道。
超過這些限制會觸發結構性重新設計，而不是簡單的調整。
8. 輸出格式
- HTML（預設）： 自包含的 HTML 檔案，內嵌 SVG、CSS 和字型。所有內容都內嵌，無外部依賴。副檔名：
.html。 - SVG： 純 SVG 檔案，帶有內嵌字型。副檔名：
.svg。 - PNG： 透過伺服器端渲染的點陣圖。副檔名：
.png。尺寸從 HTML/SVG 輸出中推斷。
使用者可要求任何格式。
9. 匯入格式
支援從以下來源匯入：
- Drawio (
.drawio)： 從 Drawio XML 格式解析節點、連線和文字。佈局將被重構以符合編輯設計系統。 - Mermaid： 接受 Mermaid 定義（文字或
.mmd檔案）並將其轉換為編輯佈局，保留語意結構。 - Excalidraw (
.excalidraw)： 從 Excalidraw JSON 格式匯入。
匯入流程：
- 載入來源檔案或文字定義。
- 擷取語意結構（節點、連線、標籤、分組）。
- 將結構映射到編輯設計系統的佈局語法。
- 根據 §1 和 §6 的規則最佳化佈局（如有必要，移除冗餘的連線和節點）。
- 根據所選的視覺類型重新渲染。
10. 儲存與設定檔
- 設定檔： 品牌自訂（顏色、字型、代碼）可以儲存在
references/profiles.md中的具名設定檔下。 - 專案標記： 在專案根目錄中放置一個空的
.diagram-design檔案，以標記該專案已準備好使用此技能。 - 提示快取： 此文件的內容可以快取，以加快後續呼叫的速度。
11. 生命週期階段圖與區塊分解
除了 §3 中的 45 種類型之外，此技能還包括：
- 生命週期階段圖： 一個專用於展示主體（產品、功能、資料）如何隨時間演進的模式，具有清晰的階段、閘門和遷移規則。在語意模式觸發時使用。
- 區塊分解樹： 一個專用於展示可透過 ID 定址的層級式分解的模式，每個區塊具有 I/O、約束條件和程式碼連結。在語意模式觸發時使用。
兩者都包含在參考文件中，並遵循與上述 45 種類型相同的編輯規則。
12. 入門指引
對於新使用者，此技能在 references/onboarding.md 中提供互動式入門流程。流程如下：
- 樣式指南設定： 在首次圖表之前自訂顏色和字型。
- 類型選擇： 引導使用者根據其資料選擇視覺類型。
- 複雜度檢查： 確保圖表保持在複雜度預算之內。
- 輸出格式： 選擇 HTML、SVG 或 PNG。
- 回饋： 如果使用者在 Spark 工作室中，請提供編輯建議。
入門流程旨在無縫上手，並在生產開始前解決所有設定問題。
13. 反模式與最佳實務
始終：
- 使用語意角色（
{ink}、{accent}）而非硬編碼的顏色。 - 保持節點統一：所有節點應具有相似的形狀和尺寸，除非類型另有指定。
- 使用清晰的標籤：每個節點一個簡短名詞短語。避免在標籤中使用完整句子。
- 保持連線整潔：僅在線條交叉或語意不明確時才添加標籤。
- 尊重密度目標：4/10。
從不：
- 混合使用兩種類型的佈局語法（例如，在流程圖中使用泳道規則）。
- 在沒有語意意義的情況下使用動畫。
- 提供多個出口 — 如果路徑分歧，則是兩個圖表。
- 在沒有考量語意模式的情況下選擇類型，除非使用者已指定類型。
14. 參考文件索引
| 文件 | 內容 |
|---|---|
references/style-guide.md | 顏色、字型、代碼 |
references/semantic-patterns.md | 行為觸發條件和模式 |
references/animation.md | 動畫規則 |
references/profiles.md | 設定檔儲存和載入 |
references/onboarding.md | 入門流程 |
references/type-*.md | 45 種類型的參考文件 |
所有參考文件都位於 references/ 目錄中。技能的超智慧至`