Excalidraw 圖表建立工具

產生 .excalidraw JSON 檔案，以視覺方式進行論證，而不只是展示資訊。

設定： 如果使用者要求你設定此技能（渲染器、相依套件等），請參閱 README.md 中的說明。

自訂

所有顏色與品牌專屬樣式都集中在一個檔案： references/color-palette.md。在產生任何圖表前請先閱讀該檔案，並將其作為所有顏色選擇的單一事實來源——包括形狀填色、線條、文字顏色、證據成品背景等。

若要讓此技能以你自己的品牌風格產出圖表，請編輯 color-palette.md。此檔案中的其他內容都是通用的設計方法論與 Excalidraw 最佳實務。

核心哲學

圖表應該論證，而非展示。

圖表不是格式化文字。它是一種視覺論證，能呈現文字無法單獨表達的關係、因果關係與流程。形狀本身就應該代表意義。

同構測試： 如果移除所有文字，結構本身能否傳達概念？如果不能，請重新設計。

教育性測試： 觀看者能否從此圖表中學到具體內容，還是它只是標籤盒子？好的圖表能教學——它會展示實際格式、真實事件名稱、具體範例。

深度評估（請先執行此步驟）

在設計之前，先判斷此圖表需要何種細節層級：

簡單／概念性圖表

在以下情況使用抽象形狀：

解釋心智模型或哲學
受眾不需要技術細節
概念本身就是抽象（例如「關注點分離」）

全面性／技術性圖表

在以下情況使用具體範例：

繪製真實系統、協定或架構
圖表將用於教學或說明（例如 YouTube 影片）
受眾需要了解事物實際的樣子
你正在展示多項技術如何整合

對於技術性圖表，你必須包含證據成品（見下方說明）。

研究要求（適用於技術性圖表）

在繪製任何技術性內容之前，請先研究實際規格。

如果你正在繪製協定、API 或框架：

查閱實際的 JSON／資料格式
找出真實的事件名稱、方法名稱或 API 端點
了解各個部分實際如何連接
使用真實術語，而非通用佔位符

錯誤：「協定」→「前端」
正確：「AG-UI 串流事件 (RUN_STARTED, STATE_DELTA, A2UI_UPDATE)」→「CopilotKit 透過 createA2UIMessageRenderer() 渲染」

研究能讓圖表既準確又具教育性。

證據成品

證據成品是具體範例，用來證明你的圖表準確無誤，並幫助觀看者學習。請在技術性圖表中包含它們。

證據成品的類型（選擇與你的圖表相關的類型）：

成品類型	使用時機	渲染方式
程式碼片段	API、整合、實作細節	深色矩形 + 語法上色的文字（請參閱色票中的證據成品顏色）
資料／JSON 範例	資料格式、結構、酬載	深色矩形 + 彩色文字（請參閱色票）
事件／步驟序列	協定、工作流程、生命週期	時間軸模式（線條 + 圓點 + 標籤）
UI 模型	顯示實際輸出／結果	模仿真實 UI 的巢狀矩形
真實輸入內容	顯示系統接收的內容	矩形內含可見的範例內容
API／方法名稱	真實函式呼叫、端點	使用文件中的實際名稱，而非佔位符

範例： 對於串流通訊協定的圖表，你可以展示：

規格中的實際事件名稱（而不只是「事件 1」、「事件 2」）
顯示如何連接的程式碼片段
串流資料實際的樣貌

範例： 對於資料轉換管線的圖表：

顯示範例輸入資料（實際格式，而非「輸入」）
顯示範例輸出資料（實際格式，而非「輸出」）
如有相關，顯示中間狀態

關鍵原則：展示事物實際的樣子，而不只是它們的名稱。

多縮放層級架構

全面性圖表同時在多個縮放層級運作。把它想像成一張地圖，同時顯示國界與街道名稱。

層級 1：摘要流程

簡化的概覽，一眼就能看出完整的管線或流程。通常放在圖表的頂部或底部。

範例： Input → Processing → Output 或 Client → Server → Database

層級 2：區塊邊界

標記區域，將相關元件分組。這些區域創造視覺上的「房間」，幫助觀看者理解哪些部分屬於同一組。

範例： 按責任分組（後端／前端）、按階段分組（設定／執行／清理）、或按團隊分組（使用者／系統／外部）

層級 3：區塊內的細節

每個區塊內的證據成品、程式碼片段與具體範例。這是教育價值所在。

範例： 在「後端」區塊內，你可以展示實際的 API 回應格式，而不只是一個標示「API 回應」的盒子。

對於全面性圖表，目標是包含所有三個層級。 摘要提供背景，區塊組織內容，細節則負責教學。

錯誤 vs 正確

錯誤（展示）	正確（論證）
5 個等大的標籤盒子	每個概念都有反映其行為的形狀
卡片網格佈局	視覺結構符合概念結構
用圖示裝飾文字	形狀本身就是意義
所有東西都用相同容器	每個概念有獨特的視覺詞彙
所有東西都在盒子裡	自由浮動文字搭配選擇性容器

簡單 vs 全面（要知道你需要哪一種）

簡單圖表	全面性圖表
通用標籤：「輸入」→「處理」→「輸出」	具體：顯示輸入／輸出實際的樣子
命名盒子：「API」、「資料庫」、「客戶端」	命名盒子 + 實際請求／回應的範例
「事件」或「訊息」標籤	時間軸搭配規格中的真實事件／訊息名稱
「UI」或「儀表板」矩形	顯示實際 UI 元素與內容的模型
約 30 秒可解釋完	約 2-3 分鐘的教學內容
觀看者學到結構	觀看者學到結構與細節

簡單圖表適合抽象概念、快速概覽，或當受眾已經知道細節時。全面性圖表則用於技術架構、教學、教育內容，或當你希望圖表本身能教學時。

容器 vs 自由浮動文字

並非每段文字都需要形狀包圍。 預設使用自由浮動文字。只有在有特定目的時才加入容器。

使用容器的時機	使用自由浮動文字的時機
它是區塊的焦點	它是標籤或描述
需要與其他元素進行視覺分組	它是輔助細節或後設資料
箭頭需要連接到它	它描述附近的某個東西
形狀本身具有意義（決策菱形等）	單靠字體就能建立足夠的層級
它代表系統中的一個獨立「事物」	它是區塊標題、副標題或註解

字體作為層級： 使用字型大小、粗細與顏色來建立視覺層級，而不需要盒子。28px 的標題不需要矩形包圍。

容器測試： 對於每個有盒子的元素，問「這個元素能否作為自由浮動文字？」如果可以，移除容器。

設計流程（在產生 JSON 之前請先執行）

步驟 0：評估所需深度

在開始之前，先判斷這需要：

簡單／概念性：抽象形狀、標籤、關係（心智模型、哲學）
全面性／技術性：具體範例、程式碼片段、真實資料（系統、架構、教學）

如果是全面性：先做研究。查閱實際規格、格式、事件名稱、API。

步驟 1：深入理解

閱讀內容。對於每個概念，問：

這個概念做什麼？（而不是它是什麼）
概念之間存在什麼關係？
核心的轉換或流程是什麼？
觀看者需要看到什麼才能理解？（而不只是閱讀）

步驟 2：將概念對應到模式

對於每個概念，找到反映其行為的視覺模式：

如果概念...	使用此模式
產生多個輸出	扇形展開（從中心輻射的箭頭）
將多個輸入合併為一個	匯聚（漏斗、箭頭合併）
具有層級／巢狀結構	樹狀（線條 + 自由浮動文字）
是一系列步驟	時間軸（線條 + 圓點 + 自由浮動標籤）
循環或持續改進	螺旋／循環（箭頭回到起點）
是抽象狀態或背景	雲狀（重疊橢圓）
將輸入轉換為輸出	組裝線（之前 → 處理 → 之後）
比較兩個事物	並排（平行對比）
分為多個階段	間隔／斷點（區塊之間的視覺分隔）

步驟 3：確保多樣性

對於多概念圖表：每個主要概念必須使用不同的視覺模式。不能使用統一的卡片或網格。

步驟 4：草擬流程

在產生 JSON 之前，先在腦中追蹤視線在圖表中的移動路徑。應該要有清晰的視覺故事。

步驟 5：產生 JSON

現在才建立 Excalidraw 元素。關於如何處理大型圖表，請見下方說明。

步驟 6：渲染與驗證（強制）

產生 JSON 後，你必須執行渲染-檢視-修正的循環，直到圖表看起來正確為止。這不是可選項——請見下方渲染與驗證章節的完整流程。

大型／全面性圖表策略

對於全面性或技術性圖表，你必須一次建立一個區塊的 JSON。 不要試圖在單次回應中產生整個檔案。這是硬性限制——Claude Code 每次回應的輸出限制約為 32,000 個 token，而全面性圖表很容易一次就超過這個限制。即使沒有超過，一次產生所有內容也會導致品質較差。逐區塊進行在各方面都更好。

逐區塊工作流程

階段 1：建立每個區塊

建立基礎檔案，包含 JSON 包裝（type、version、appState、files）以及第一個區塊的元素。
每次編輯加入一個區塊。 每個區塊都有專屬的處理次數——慢慢來。仔細思考佈局、間距，以及此區塊如何與現有內容連接。
使用描述性字串 ID（例如 "trigger_rect"、"arrow_fan_left"），讓跨區塊的參照易於閱讀。
按區塊命名空間化種子（例如區塊 1 使用 100xxx，區塊 2 使用 200xxx），以避免衝突。
隨著進度更新跨區塊綁定。 當新區塊的元素需要綁定到先前區塊的元素時（例如連接區塊的箭頭），同時編輯較早元素的 boundElements 陣列。

階段 2：檢視整體

在所有區塊就定位後，閱讀完整的 JSON 並檢查：

跨區塊的箭頭是否在兩端都正確綁定？
整體間距是否平衡，還是某些區塊過於擁擠而其他區塊空白過多？
ID 與綁定是否都參照實際存在的元素？

在渲染之前修正任何對齊或綁定問題。

階段 3：渲染與驗證

現在執行渲染與驗證章節中的渲染-檢視-修正循環。這是你會發現 JSON 中不明顯的視覺問題的地方——重疊、裁切、不平衡的構圖。

區塊邊界

根據圖表規劃中的自然視覺分組來規劃區塊。典型的大型圖表可能分為：

區塊 1：進入點／觸發器
區塊 2：第一個決策或路由
區塊 3：主要內容（英雄區塊——可能是最大的單一區塊）
區塊 4-N：其餘階段、輸出等

每個區塊應能獨立理解：其元素、內部箭頭，以及任何與相鄰區塊的交叉參照。

不該做的事

不要在單次回應中產生整個圖表。 你會達到輸出 token 限制，產生截斷且損壞的 JSON。即使圖表小到可以容納，分成區塊也能產生更好的結果。
不要使用程式碼代理來產生 JSON。代理沒有足夠的關於此技能規則的背景資訊，而且協調的開銷會抵銷任何好處。
不要撰寫 Python 產生器腳本。 模板化和座標數學看似有幫助，但會引入一層間接性，使除錯更困難。手動製作的 JSON 搭配描述性 ID 更易於維護。

視覺模式庫

扇形展開（一對多）

中央元素搭配輻射到多個目標的箭頭。用於：來源、PRD、根本原因、中心樞紐。

匯聚（多對一）

多個輸入透過箭頭合併到單一輸出。用於：聚合、漏斗、綜合。

  ○ ↘
  ○ → □
  ○ ↗

樹狀（層級）

父子分支，使用連接線與自由浮動文字（不需要盒子）。用於：檔案系統、組織圖、分類法。

  label
  ├── label
  │   ├── label
  │   └── label
  └── label

使用 line 元素作為主幹與分支，自由浮動文字作為標籤。

螺旋／循環（連續迴圈）

元素依序排列，箭頭回到起點。用於：反饋迴圈、迭代過程、演化。

  □ → □
  ↑     ↓
  □ ← □

雲狀（抽象狀態）

重疊的橢圓，大小不一。用於：背景、記憶、對話、心理狀態。

組裝線（轉換）

輸入 → 處理盒子 → 輸出，清楚顯示之前／之後。用於：轉換、處理、轉化。

  ○○○ → [PROCESS] → □□□
  chaos              order

並排（比較）

兩個平行結構，具有視覺對比。用於：之前／之後、選項、取捨。

間隔／斷點（分隔）

區塊之間的視覺空白或屏障。用於：階段變更、背景重置、邊界。

線條作為結構

使用線條（類型：line，而非箭頭）作為主要結構元素，而非盒子：

時間軸：垂直或水平線條，間隔放置小圓點（10-20px 橢圓），每個圓點旁有自由浮動標籤
樹狀結構：垂直主幹線 + 水平分支線，搭配自由浮動文字標籤（不需要盒子）
分隔線：細虛線用於分隔區塊
流程主軸：元素與之相關的中央線條，而非連接盒子

時間軸：          樹狀：
  ●─── 標籤 1        │
  │                   ├── 項目
  ●─── 標籤 2        │   ├── 子項
  │                   │   └── 子項
  ●─── 標籤 3        └── 項目

線條 + 自由浮動文字通常比盒子 + 包含文字產生更乾淨的結果。

形狀意義

根據形狀所代表的內容選擇形狀——或者完全不使用形狀：

概念類型	形狀	原因
標籤、描述、細節	無（自由浮動文字）	字體建立層級
區塊標題、註解	無（自由浮動文字）	字型大小／粗細就足夠
時間軸上的標記	小 `ellipse`（10-20px）	視覺錨點，非容器
開始、觸發、輸入	`ellipse`	柔和、類似起點
結束、輸出、結果	`ellipse`	完成、目的地
決策、條件	`diamond`	經典決策符號
處理、動作、步驟	`rectangle`	包含的動作
抽象狀態、背景	重疊 `ellipse`	模糊、雲狀
層級節點	線條 + 文字（無盒子）	透過線條建立結構

規則： 預設不使用容器。只有在形狀具有意義時才加入。目標是讓 <30% 的文字元素位於容器內。

顏色作為意義

顏色編碼資訊，而非裝飾。每個顏色選擇都應來自 references/color-palette.md——語意形狀顏色、文字層級顏色與證據成品顏色都在那裡定義。

關鍵原則：

每個語意用途（開始、結束、決策、AI、錯誤等）都有特定的填色／線條組合
自由浮動文字使用顏色來建立層級（標題、副標題、細節——每個層級不同）
證據成品（程式碼片段、JSON 範例）使用自己的深色背景 + 彩色文字方案
總是將較深的線條與較淺的填色搭配以獲得對比

不要發明新顏色。 如果某個概念不符合現有的語意類別，請使用主要／中性或次要。

現代美學

對於乾淨、專業的圖表：

粗糙度

roughness: 0——乾淨、銳利的邊緣。用於現代／技術性圖表。
roughness: 1——手繪、有機感。用於腦力激盪／非正式圖表。

預設為 0，適用於大多數專業使用案例。

線條寬度

strokeWidth: 1——細、優雅。適合線條、分隔線、細微連接。
strokeWidth: 2——標準。適合形狀與主要箭頭。
strokeWidth: 3——粗體。謹慎使用以強調（主要流程線、關鍵連接）。

不透明度

所有元素一律使用 opacity: 100。 使用顏色、大小與線條寬度來建立層級，而非透明度。

小標記取代形狀

使用小圓點（10-20px 橢圓）取代完整形狀，作為：

時間軸標記
項目符號
連接節點
自由浮動文字的視覺錨點

佈局原則

透過比例建立層級

英雄：300×150——視覺錨點，最重要
主要：180×90
次要：120×60
小：60×40

空白 = 重要性

最重要的元素周圍有最多的空白空間（200px 以上）。

流向

引導視線：序列通常從左到右或從上到下，樞紐與輻射模式則為放射狀。

需要連接

僅靠位置無法顯示關係。如果 A 與 B 相關，必須有箭頭。

文字規則

關鍵：JSON 的 text 屬性只包含可讀的文字。

{
  "id": "myElement1",
  "text": "Start",
  "originalText": "Start"
}

設定：fontSize: 16、fontFamily: 3、textAlign: "center"、verticalAlign: "middle"

JSON 結構

{
  "type": "excalidraw",
  "version": 2,
  "source": "https://excalidraw.com",
  "elements": [...],
  "appState": {
    "viewBackgroundColor": "#ffffff",
    "gridSize": 20
  },
  "files": {}
}

元素模板

請參閱 references/element-templates.md，取得每種元素類型（文字、線條、圓點、矩形、箭頭）的可複製 JSON 模板。根據每個元素的語意用途，從 references/color-palette.md 中選取顏色。

渲染與驗證（強制）

你無法僅從 JSON 判斷圖表的好壞。在產生或編輯 Excalidraw JSON 後，你必須將其渲染為 PNG、檢視圖片，並修正你所看到的問題——重複此循環直到正確為止。這是工作流程的核心部分，而非最終檢查。

如何渲染

cd .claude/skills/excalidraw-diagram/references && uv run python render_excalidraw.py <path-to-file.excalidraw>

這會在 .excalidraw 檔案旁輸出一個 PNG。然後使用讀取工具來實際檢視該 PNG。

循環

在產生初始 JSON 後，執行此循環：

1. 渲染與檢視——執行渲染腳本，然後讀取 PNG。

2. 與原始願景比對——在尋找錯誤之前，先將渲染結果與你在步驟 1-4 中設計的內容進行比較。問：

視覺結構是否符合你規劃的概念結構？
每個區塊是否使用了你預期的模式（扇形展開、匯聚、時間軸等）？
視線是否按照你設計的順序流經圖表？
視覺層級是否正確——英雄元素突出，輔助元素較小？
對於技術性圖表：證據成品（程式碼片段、資料範例）是否可讀且位置適當？

3. 檢查視覺缺陷：

文字被容器裁切或溢出
文字或形狀與其他元素重疊
箭頭穿過元素而非繞過它們
箭頭落在錯誤的元素上或指向空白空間
標籤漂浮不明確（未清楚錨定到它們描述的內容）
應均勻間距的元素之間間距不均
某些區塊空白過多，相鄰區塊則過於擁擠
文字在渲染尺寸下太小而無法閱讀
整體構圖感覺不平衡

4. 修正——編輯 JSON 以解決你發現的所有問題。常見修正：

當文字被裁切時加寬容器
調整 x／y 座標以修正間距與對齊
在箭頭 points 陣列中加入中間路徑點以繞過元素
將標籤重新定位到更靠近它們描述的元素的
調整元素大小以重新平衡各區塊的視覺重量

5. 重新渲染與重新檢視——再次執行渲染腳本並讀取新的 PNG。

6. 重複——持續循環，直到圖表通過願景檢查（步驟 2）與缺陷檢查（步驟 3）。通常需要 2-4 次迭代。不要因為沒有嚴重錯誤就在一次通過後停止——如果構圖可以更好，就改進它。

何時停止

循環完成的條件：

渲染的圖表符合你規劃步驟中的概念設計
沒有文字被裁切、重疊或無法閱讀
箭頭路徑乾淨且連接到正確的元素
間距一致且構圖平衡
你可以放心地將其展示給他人而無需附加說明

首次設定

如果渲染腳本尚未設定：

cd .claude/skills/excalidraw-diagram/references
uv sync
uv run playwright install chromium

品質檢查清單

深度與證據（技術性圖表優先檢查）

已完成研究：你是否查閱了實際規格、格式、事件名稱？
證據成品：是否有程式碼片段、JSON 範例或真實資料？
多縮放層級：是否包含摘要流程 + 區塊邊界 + 細節？
具體而非抽象：是否顯示真實內容，而不只是標籤盒子？
教育價值：觀看者能否從中學到具體內容？

概念性

同構：每個視覺結構是否反映其概念的行為？
論證：圖表是否展示了文字無法單獨表達的內容？
多樣性：每個主要概念是否使用不同的視覺模式？
無統一容器：是否避免了卡片網格與等大盒子？

容器紀律

最少容器：是否有任何有盒子的元素可以改為自由浮動文字？
線條作為結構：樹狀／時間軸模式是否使用線條 + 文字而非盒子？
字體層級：字型大小與顏色是否建立了視覺層級（減少對盒子的需求）？

結構性

連接：每個關係都有箭頭或線條
流程：視線有清晰的視覺路徑可遵循
層級：重要元素較大／較孤立

技術性

文字乾淨：text 只包含可讀的文字
字型：fontFamily: 3
粗糙度：roughness: 0 以獲得乾淨／現代感（除非要求手繪風格）
不透明度：所有元素使用 opacity: 100（無透明度）
容器比例：<30% 的文字元素應位於容器內

視覺驗證（需要渲染）

已渲染為 PNG：圖表已渲染並進行視覺檢查
無文字溢出：所有文字都適合其容器
無重疊元素：形狀與文字不會意外重疊
間距均勻：相似元素具有一致的間距
箭頭正確著陸：箭頭連接到預期元素，且不穿過其他元素
在匯出尺寸下可讀：文字在渲染的 PNG 中清晰可辨
平衡的構圖：沒有大的空白區域或過度擁擠的區域

excalidraw-diagram

相關技能