設計系統同步 是做什麼的?
概覽
當設計系統已存在於程式碼中時,設計工具應鏡像它,而非重新發明它。
- 匯入 將程式碼的代碼以及使用者選取的元件帶入工具中,並使用相同的名稱。
- 匯出 將工具指南中進行的變更,以經過審查的 diff 形式送回程式碼。
專案根目錄下的一個小檔案 design-sync.json 會記住上次同步的狀態。程式碼維持真理源的角色,除非使用者另有指示:變更首先在工具中繪製,然後透過核准的匯出落地到程式碼中。
使用時機
- 某個設計任務即將啟動,該專案的設計系統存在於程式碼中,但工具內尚無指南。
craft-setup和craft會將此任務交接過來。 - 「匯入/將我們的設計系統(代碼、元件)帶入 Paper / Figma / 設計工具中。」
- 「套用/推送/將指南的變更同步到程式碼。」
何時不該使用
- 程式碼中沒有設計系統:請使用
craft-system(建立模式)。 - 在該類專案中進行審查、選項討論或小型編輯:這些技能會直接基於程式碼的現狀運作。
- 使用者口頭指定了單一代碼值(例如「在程式碼中將強調色設為 #3d7f69」):請直接編輯該值,更新
design-sync.json中對應的名稱,並說明它影響了哪些部分。
開始之前
- 如果存在的話,請閱讀
DESIGN.md(Brand 會說明系統的位置)和design-sync.json。 - 在
references/adapters/中挑選你的工具轉接器(paper.md、figma.md、html.md)。如果沒有轉接器符合你的工具,請在你的工具中執行相同的動詞,並說明你手動對應了哪些動作。如果完全沒有設計工具,則使用 HTML 建置(html.md)。如果你只有圖片,請說明從中讀取的值僅為估算值。
design-sync.json
{
"source": "packages/ui/tokens.css",
"tool": "paper: file 'Fieldnote', page 'Guide'",
"naming": "CSS custom property names as written in the source",
"synced": "2026-11-15",
"tokens": { "--color-accent": "#2e6b57", "--radius-md": "10px" },
"components": { "Button": "drawn", "Badge": "drawn", "Input": "in code only" }
}
tokens只存放雙方在上次同步時已同意的值。- 元件的匯入只會更新其自身的
components條目。
匯入(程式碼 → 設計工具)
-
偵測 使用訊號。找出值的真理源(代碼的來源,而非產生的輸出)以及工具將使用的命名規則。兩個 UI 套件 → 列出兩者並詢問哪個是來源。
-
盤點,然後停止。 使用盤點格式:
- 依角色分類的代碼,包含數量與路徑;
- 元件(超過約 15 個時,依群組列出並附上數量);
- 指南文件;
- 缺口;
- 衝突:任何已在工具中存在但值不同的名稱,以及任何工具無法容納的代碼型別。
詢問現在要繪製哪些元件,建議接下來的畫面中選擇 3–6 個,並詢問如何解決每個衝突。預設情況下絕不繪製所有元件。
-
在工具中建置 取得回答後:
- 依照命名規則註冊代碼;絕不覆寫使用者尚未解決的工具值;
- 建立一個基礎指南頁面,將指南文件作為圖例;
- 建立一個元件索引:名稱、程式碼路徑、狀態(
drawn/in code only),繪製後補上變異; - 繪製選取的元件及其狀態矩陣,使用程式碼中的值。程式碼未定義的狀態將被繪製並標記為**「提議中」**。
-
自我檢查。 渲染指南。如果程式碼可以渲染該元件(Storybook、示範頁面),則以相同尺寸進行比較。否則說明值是從程式碼讀取但未渲染。
-
記錄:
- 寫入
design-sync.json(所有代碼值現在雙方相等,加上元件狀態); - 在
DESIGN.md中,Brand 會得到「設計系統來源:<path>;<工具> 指南鏡像了它」,而決策記錄會增加一行帶日期的匯入記錄; - 如果不存在
DESIGN.md,建立一個第一行為<!-- sync record only: run craft-setup for the brief -->的檔案,僅包含 Brand 與決策記錄。craft將缺少 Product 區段的DESIGN.md視為缺失。
- 寫入
匯入單一元件(來自 craft)
使用者已同意鏡像系統,因此沒有盤點停止步驟:
- 繪製該元件;
- 將其
components條目設為drawn; - 不更動
tokens。
如果工具尚無指南,或使用者從未同意匯入(或拒絕了匯入),請詢問一次:「輸入僅存在於程式碼中。是否先將其匯入到指南中?」
匯出(設計工具 → 程式碼)
-
讀取 指南的值(透過轉接器)以及程式碼的值,按名稱對應。
-
分類每一個名稱 使用
design-sync.json與 diff 格式:- 現為相等 → 同步中;
- 指南已變更 → 提議;
- 程式碼已變更 → 提供重新整理指南的選項;
- 兩者皆已變更 → 顯示三個值並詢問哪一方勝出。
如果沒有
design-sync.json,列出所有差異並詢問每個差異的方向。 -
提議編輯 針對原始碼檔案(絕非產生的輸出):檔案與行號、每個編輯影響的內容、以及顏色的對比度。「提議中」的狀態和替代字型不是要匯出的變更。停止。
-
套用 僅套用已核准的內容,對於任何決定採用程式碼值的情況更新指南,然後執行專案的檢查(lint、型別檢查、測試、視覺測試),或說明沒有檢查。
-
記錄:
- 更新
design-sync.json,使值現在雙方相等; - 在
DESIGN.md› 決策記錄中新增一行帶日期的記錄; - 將未解決的衝突加入「開放問題」。
- 更新
規則
| 規則 | 原因 |
|---|---|
| 程式碼與工具中使用相同名稱,且遵循一個書面命名規則 | 每個決策一個名稱;沒有對應漂移的空間 |
design-sync.json 只記錄已同意的值 | 沒有最後一次同意的值,「誰變更了它?」只是猜測 |
| 先盤點並挑選,再繪製;衝突列在盤點中 | 大型套件和既有的工具代碼需要使用者表態 |
| 值取自程式碼,而非螢幕截圖 | 螢幕截圖會四捨五入顏色和尺寸 |
| 缺少的狀態繪製為「提議中」 | 指南不能宣稱程式碼做了它沒做的事 |
| 匯出先提議,然後停止;編輯原始碼,而非產生的輸出 | 程式碼會交付給使用者;產生的檔案會被下一次建置覆寫 |
| 兩者皆已變更 → 詢問 | 覆寫任何一方的值都會損失某人的決策 |
| 程式碼是真理源,直到使用者另有指示 | 符合「程式碼比陳舊的簡報更有說服力」的原則 |
完成條件
- 匯入: 盤點與衝突已解決;選取的元件已繪製;指南已渲染(或聲明「未渲染」);
design-sync.json與DESIGN.md已寫入。 - 單一元件: 已繪製,其狀態已更新。
- 匯出: 已核准的編輯已套用,檢查已執行(或聲明「無」),
design-sync.json已更新,衝突已解決或保持開放狀態。
常見錯誤
| 想法 | 現實 |
|---|---|
| 「程式碼已經有系統了,所以設定只需要簡報」 | 提供匯入選項,否則工具永遠不會有指南,畫面會與程式碼脫節。 |
| 「我會先建立基礎和索引,元件之後再說」 | 顯示盤點清單,詢問現在要繪製哪些元件。 |
「匯入時我要把 --sand-200 重新命名為一個角色名稱」 | 保留程式碼的名稱;將角色命名作為開放問題提議。 |
「工具已經有 --color-accent,我直接更新它」 | 這是一個需要在盤點步驟處理的衝突,不是無聲的覆寫。 |
| 「指南和程式碼不同,所以指南過時了」 | 檢查 design-sync.json:它可能是使用者尚未匯出的變更。 |
| 「diff 很小,我直接套用就好」 | 提議、停止,然後再套用並執行專案的檢查。 |