Communitygithub.com

設計系統同步

將程式碼中的設計系統(UI 套件、設計代碼、元件庫)匯入設計工具,或將設計工具指南中的變更同步回程式碼。

設計系統同步 是什麼?

此技能專為已存在程式碼中但尚未反映在設計工具內的設計系統而設計。當設計任務即將開始,或開發者要求「匯入」、「套用」、「推送」、「同步」設計系統時,此技能會自動啟動。它支援透過自訂的 `design-sync.json` 檔案記錄上次同步的狀態,並採用「程式碼為真理源」的原則。技能涵蓋兩個主要方向:**匯入**(從程式碼將代碼和元件帶入設計工具)與**匯出**(將設計工具指南中的變更以經過審查的 diff 形式送回程式碼)。它會先盤點代碼與設計工具之間的差異,列出衝突,讓使用者決定要匯入的元件,然後才在工具中建立指南。匯出時則會分類每個名稱的變更(僅一方變更或雙方同時變更),提議編輯原始碼,執行專案檢查,最後更新同步記錄。支援的設計工具包括 Paper、Figma 以及純 HTML 情境,若無符合的轉接器則允許手動對應。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/diego3g/craft/tree/HEAD/skills/craft-sync

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

設計系統同步 是做什麼的?

概覽

當設計系統已存在於程式碼中時,設計工具應鏡像它,而非重新發明它。

  • 匯入 將程式碼的代碼以及使用者選取的元件帶入工具中,並使用相同的名稱。
  • 匯出 將工具指南中進行的變更,以經過審查的 diff 形式送回程式碼。

專案根目錄下的一個小檔案 design-sync.json 會記住上次同步的狀態。程式碼維持真理源的角色,除非使用者另有指示:變更首先在工具中繪製,然後透過核准的匯出落地到程式碼中。

使用時機

  • 某個設計任務即將啟動,該專案的設計系統存在於程式碼中,但工具內尚無指南。craft-setup 和 craft 會將此任務交接過來。
  • 「匯入/將我們的設計系統(代碼、元件)帶入 Paper / Figma / 設計工具中。」
  • 「套用/推送/將指南的變更同步到程式碼。」

何時不該使用

  • 程式碼中沒有設計系統:請使用 craft-system(建立模式)。
  • 在該類專案中進行審查、選項討論或小型編輯:這些技能會直接基於程式碼的現狀運作。
  • 使用者口頭指定了單一代碼值(例如「在程式碼中將強調色設為 #3d7f69」):請直接編輯該值,更新 design-sync.json 中對應的名稱,並說明它影響了哪些部分。

開始之前

  1. 如果存在的話,請閱讀 DESIGN.md(Brand 會說明系統的位置)和 design-sync.json。
  2. 在 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 條目。

匯入(程式碼 → 設計工具)

  1. 偵測 使用訊號。找出值的真理源(代碼的來源,而非產生的輸出)以及工具將使用的命名規則。兩個 UI 套件 → 列出兩者並詢問哪個是來源。

  2. 盤點,然後停止。 使用盤點格式:

    • 依角色分類的代碼,包含數量與路徑;
    • 元件(超過約 15 個時,依群組列出並附上數量);
    • 指南文件;
    • 缺口;
    • 衝突:任何已在工具中存在但值不同的名稱,以及任何工具無法容納的代碼型別。

    詢問現在要繪製哪些元件,建議接下來的畫面中選擇 3–6 個,並詢問如何解決每個衝突。預設情況下絕不繪製所有元件。

  3. 在工具中建置 取得回答後:

    • 依照命名規則註冊代碼;絕不覆寫使用者尚未解決的工具值;
    • 建立一個基礎指南頁面,將指南文件作為圖例;
    • 建立一個元件索引:名稱、程式碼路徑、狀態(drawn / in code only),繪製後補上變異;
    • 繪製選取的元件及其狀態矩陣,使用程式碼中的值。程式碼未定義的狀態將被繪製並標記為**「提議中」**。
  4. 自我檢查。 渲染指南。如果程式碼可以渲染該元件(Storybook、示範頁面),則以相同尺寸進行比較。否則說明值是從程式碼讀取但未渲染。

  5. 記錄:

    • 寫入 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。

如果工具尚無指南,或使用者從未同意匯入(或拒絕了匯入),請詢問一次:「輸入僅存在於程式碼中。是否先將其匯入到指南中?」

匯出(設計工具 → 程式碼)

  1. 讀取 指南的值(透過轉接器)以及程式碼的值,按名稱對應。

  2. 分類每一個名稱 使用 design-sync.json 與 diff 格式:

    • 現為相等 → 同步中;
    • 指南已變更 → 提議;
    • 程式碼已變更 → 提供重新整理指南的選項;
    • 兩者皆已變更 → 顯示三個值並詢問哪一方勝出。

    如果沒有 design-sync.json,列出所有差異並詢問每個差異的方向。

  3. 提議編輯 針對原始碼檔案(絕非產生的輸出):檔案與行號、每個編輯影響的內容、以及顏色的對比度。「提議中」的狀態和替代字型不是要匯出的變更。停止。

  4. 套用 僅套用已核准的內容,對於任何決定採用程式碼值的情況更新指南,然後執行專案的檢查(lint、型別檢查、測試、視覺測試),或說明沒有檢查。

  5. 記錄:

    • 更新 design-sync.json,使值現在雙方相等;
    • 在 DESIGN.md › 決策記錄中新增一行帶日期的記錄;
    • 將未解決的衝突加入「開放問題」。

規則

規則原因
程式碼與工具中使用相同名稱,且遵循一個書面命名規則每個決策一個名稱;沒有對應漂移的空間
design-sync.json 只記錄已同意的值沒有最後一次同意的值,「誰變更了它?」只是猜測
先盤點並挑選,再繪製;衝突列在盤點中大型套件和既有的工具代碼需要使用者表態
值取自程式碼,而非螢幕截圖螢幕截圖會四捨五入顏色和尺寸
缺少的狀態繪製為「提議中」指南不能宣稱程式碼做了它沒做的事
匯出先提議,然後停止;編輯原始碼,而非產生的輸出程式碼會交付給使用者;產生的檔案會被下一次建置覆寫
兩者皆已變更 → 詢問覆寫任何一方的值都會損失某人的決策
程式碼是真理源,直到使用者另有指示符合「程式碼比陳舊的簡報更有說服力」的原則

完成條件

  • 匯入: 盤點與衝突已解決;選取的元件已繪製;指南已渲染(或聲明「未渲染」);design-sync.json 與 DESIGN.md 已寫入。
  • 單一元件: 已繪製,其狀態已更新。
  • 匯出: 已核准的編輯已套用,檢查已執行(或聲明「無」),design-sync.json 已更新,衝突已解決或保持開放狀態。

常見錯誤

想法現實
「程式碼已經有系統了,所以設定只需要簡報」提供匯入選項,否則工具永遠不會有指南,畫面會與程式碼脫節。
「我會先建立基礎和索引,元件之後再說」顯示盤點清單,詢問現在要繪製哪些元件。
「匯入時我要把 --sand-200 重新命名為一個角色名稱」保留程式碼的名稱;將角色命名作為開放問題提議。
「工具已經有 --color-accent,我直接更新它」這是一個需要在盤點步驟處理的衝突,不是無聲的覆寫。
「指南和程式碼不同,所以指南過時了」檢查 design-sync.json:它可能是使用者尚未匯出的變更。
「diff 很小,我直接套用就好」提議、停止,然後再套用並執行專案的檢查。

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相關技能