Communitygithub.com

figma-state-board (Figma 狀態情境稿)

從程式碼盤點某個功能的所有 UI 狀態,在 Figma 中產出或更新「情境稿」:真實畫面呈現原型已處理的狀態,並透過「缺漏檢查」找出缺少的錯誤、空狀態與載入狀態,再區分為規格要求與建議補足。

figma-state-board (Figma 狀態情境稿) とは?

本技能(Figma State Board)協助開發者或設計師從專案程式碼中盤點某個功能的所有 UI 狀態,並在 Figma 畫布上以結構化的情境稿(state board)呈現。它會將原型已實作的狀態畫出真實畫面,同時自動產生「缺漏檢查」(Gap check)區域,列出尚未處理的錯誤、空狀態和載入狀態,並進一步區分為「規格有寫」(spec-required)和「建議補」(suggested)。此技能支援任何技術棧和產品類型,並可與其他技能(如 state-discovery、code-to-figma)搭配使用。主要流程包括:確認輸入(程式碼來源、規格文件、Figma 目標、維度、畫面來源與設計系統)、盤點狀態並建立矩陣、準備每張卡的資料、建構情境稿骨架、將真實畫面填入 Figma(可選路線:複製 Mockup、從程式碼重建或使用瀏覽器截圖),最後執行稽核確保一致性。使用者只需提出「做情境稿」「把所有狀態畫到 Figma」「檢查缺了哪些 error 畫面」等請求,即可自動化完成這項工作。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/byby325/code-to-figma-ui-states/tree/HEAD/skills/figma-state-board

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Figma 狀態情境稿 (State Board)

情境稿是一個 Figma 區段,在單一畫布上列出一個功能可能處於的所有狀態。分組依據裝置、分頁或主題。每張卡片包含「ID · 名稱」、「觸發條件;結果」以及產品畫面。最後一組為缺漏檢查 (Gap check),列出原型尚未提供但功能應有的狀態。設計師、工程師、QA 與 PM 皆以此作為共享的狀態清單。

專案的程式碼通常是以模擬資料 (mock data) 建構的原型,並未連接真實後端。因此不要將狀態拆分為「已實作 / 尚未實作」。只問一個問題:原型是否建構了這個狀態?卡片只有三種標籤:

  • 原型 (Prototype):原型有此分支。繪製真實畫面;無需標籤文字
  • 規格有寫 (In spec):在 AC、規格書、Mockup 或未使用的 i18n 文案中提到,但原型未建構。放入缺漏檢查
  • 建議補 (Suggested):規格與原型皆未提及;從程式碼證據或功能類型推斷。放入缺漏檢查

適用於任何技術棧與任何產品。board-format.md 是情境稿規格的真實來源。

語言。 矩陣、卡片名稱、描述、線框文字與報告皆使用使用者語言。情境稿的固定標籤(標籤名稱、缺漏檢查、覆蓋率摘要、線框標題、圖層名稱)來自 BOARD.lang:當使用者使用繁體中文時設為 'zh-TW',否則設為 'en'。其他語言則保留英文標籤,卡片文字使用使用者語言。

此技能負責整體流程、情境稿與稽核。其他工作交由同一個插件中的其他技能處理:

任務使用技能時機
規模防護scale-guard.md步驟 1 之前閱讀
綁定設計系統figma-library-binding步驟 1 確認,步驟 5 使用
盤點狀態、找出缺漏state-discovery步驟 2
從程式碼重建畫面code-to-figma步驟 5,路線 B

此技能自身的檔案:

  • board-format.md:情境稿佈局、字型大小、標籤與卡片 ID 規則。開始繪製前閱讀
  • board-skeleton.js:從矩陣建立情境稿骨架與缺漏線框。用於步驟 4
  • screenshot-slots.js:將上傳的瀏覽器截圖放入卡片。用於步驟 5 路線 C
  • audit.js:情境稿稽核。用於步驟 6

如果專案有自己的 UI 規則技能(例如專案的 UI 指南技能),請遵循其中的產品畫面 Token、命名與驗收標準。

步驟

1. 確認輸入

詢問任何缺少的項目:

  • 程式碼來源:儲存庫、分支、功能進入點(路由、頁面、畫面或元件)
  • 規格來源:Jira AC、PRD、Confluence、錯誤碼文件。若無,則寫「無」;缺漏檢查將包含更多卡片
  • 目標:Figma 檔案與頁面;新建區段,或更新現有情境稿。對於練習用途或與他人共享的情境稿,請使用團隊的共享練習檔案(規則見 board-format.md「共享練習檔案」)。若目標是現有檔案,也請要求使用者回報其目前記憶體使用量 (scale-guard.md)
  • 維度:狀態變化的軸線(裝置寬度、登入狀態、角色、分頁、資料量、互動順序…),以及每個裝置的視埠寬度
  • 產品畫面來源:目標檔案或函式庫中的元件,或執行中的原型 / 開發伺服器。若無,則只能繪製線框;需事先說明
  • 設計系統函式庫:產品畫面必須綁定的函式庫 (figma-library-binding)。若無,則寫「無」

一旦取得 Figma 連結,立即執行兩件事。不要等到盤點完成才發現無法在檔案中繪製:

  1. 確認讀寫權限:執行 create_session,然後執行一次唯讀 use_figma(列出頁面與頂層節點)。若回報「無法存取請求的檔案」,使用 whoami 查看 MCP 登入的帳號,並提供使用者兩個選項:與該帳號共用檔案並授予「可編輯」權限,或在連接器設定中切換為有權限的帳號(切換後無法開啟原始帳號的檔案)
  2. 估算呼叫預算:依照 scale-guard.md「MCP 呼叫預算」估算此次執行所需的呼叫次數,並與 whoami 中目標檔案方案的席位數比較。若不足,先說明並讓使用者選擇:路線 C(卡片中使用瀏覽器截圖,整個情境稿約需 3 次呼叫;步驟 5)、分批處理、切換檔案,或減少比較次數

完成條件:所有六個項目都有明確值,或使用者明確表示不適用;目標檔案可讀取;呼叫預算足夠,或使用者已選擇如何拆分工作。

2. 盤點狀態並建立狀態矩陣

使用 state-discovery 建立矩陣。按照 board-format.md 的規則預先分配卡片 ID。

在使用者確認矩陣之前,不要開始繪製。 分組方式、哪些卡片要合併、哪些建議補卡片要保留,都在此步驟決定;繪製後再修改成本高得多。若原型卡片超過 150 張,請遵循 scale-guard.md 並要求使用者決定是否合併卡片、拆分頁面或拆分檔案。在他們決定之前不要繪製。

3. 準備每張卡片的資料

  • 原型:使用固定的模擬資料或 Storybook story 重現。在模擬圖層中補充缺少的資料;不要僅為了截圖而為元件新增分支。
  • 規格有寫、建議補:原型沒有畫面,因此不需要資料;繪製線框。對於規格有寫的卡片,在線框中寫明規格要求與出處。

完成條件:每張原型卡片都有可重現的資料,或明確標示為「僅在 Figma 中作為示意」。

4. 建立情境稿骨架

首先載入 Figma 插件的兩個技能:figma-use 和 figma-generate-design(在 Claude Code 中:figma:figma-use / figma:figma-generate-design;若無 Figma 插件,使用 get_figma_skill 讀取 skill://figma/figma-use/SKILL.md 等,並在 skillNames 中使用 resource: 前綴)。

若目標是現有檔案,請使用者在寫入前儲存一個版本。在刪除或重建你自行建立的卡片前也是如此。若目標頁面上除了你建立的內容外沒有其他東西(全新的檔案、空白頁面),則可跳過儲存;在報告中說明。

對於新建的情境稿,使用 board-skeleton.js:將步驟 2 中確認的矩陣填入頂端的 BOARD,然後將整個腳本貼入一個 use_figma 呼叫中。依照 board-format.md,它會建立區段(命名為「<專案>-<功能>」,放置於頁面現有內容的右方)→ 情境稿標題、副標題、覆蓋率摘要(自動計算)→ 群組 → 場景 → 卡片。最後一組是缺漏檢查,並繪製其線框。原型卡片的畫面從預留位置開始,設定 placeholder = true;腳本會回傳每張卡片的 slotId,供步驟 5 建立畫面時使用。在共享檔案中,每個功能使用一個頁面,並將 BOARD.pageName 設為頁面名稱。根據上述「語言」規則設定 BOARD.lang,並將每張缺漏卡片的 tag 設為 'spec'(規格有寫)或 'suggested'(建議補)。

更新現有情境稿時,不要執行骨架腳本。請遵循以下規則:

  • 每次變更前重新讀取目標節點;設計師可能手動移動或拆分過內容
  • 僅修改受影響的卡片。保留其 ID;新卡片從該組最後一個號碼之後繼續編號
  • 當原型開始建構缺漏檢查卡片的狀態時,將該卡片移至所屬群組,移除標籤,賦予新 ID,並在描述中記錄舊的 G ID
  • 重新計算覆蓋率摘要中的數字
  • 對你新增的標籤,保留情境稿既有的語言,即使使用者現在使用另一種語言;混雜標籤的情境稿難以閱讀
  • 不要觸碰右手邊的設計師筆記區域或回饋區段

完成條件:每張原型卡片都有預留位置的 slot 與 slotId;所有缺漏檢查的線框都已繪製。

5. 在 Figma 中建立畫面

使用 use_figma 建立原生圖層,並放入步驟 4 的預留位置 slot 中。send_code_to_figma 會匯入 Code 圖層且無法產出可編輯的 Design 圖層,因此不適用於情境稿。

路線 B 請遵循 code-to-figma「寫入 Figma 的硬性規則」,一次只傳送一個畫面。若原型卡片超過 100 張或獨特圖片超過 20 張,請要求使用者每完成一個群組就回報記憶體使用量,依 scale-guard.md 進行。若在寫入時遇到 scale-guard.md 的停止條件(包括達到呼叫限制),請停止且不要重試。

首先選擇路線並與使用者確認:

  • 路線 A:複製 Mockup(預設)。當目標檔案或函式庫中有完整的 Mockup 畫面時使用。你可以綁定變數並保留 Auto Layout。
  • 路線 B:從專案程式碼重建。當目標檔案中沒有可複製的 Mockup,或使用者要求從程式碼重建而非貼上 Mockup 時使用。遵循 code-to-figma 並將 slotId 傳給 __alBuild;產品畫面會放入卡片的預留位置 slot。目前僅限 Web 前端。
  • 路線 C:瀏覽器截圖。每張原型卡片顯示執行中應用程式的截圖;不重建任何內容。無論有多少卡片,整個情境稿約需 3 次計費呼叫,因此當呼叫預算無法負擔路線 B(Starter 方案、檢視與協作席位)或使用者僅需狀態清單與缺漏檢查時提供此選項。畫面是圖片,非可編輯圖層;提供時與報告中均需說明。僅限 Web 前端。步驟見下方「路線 C」。

路線 A 和 B 的產品畫面必須遵循 screen-structure.md:畫面根框架寬度固定為 W;容器若子項目有排列則使用 Auto Layout;不允許 Group;重複的 UI 使用元件(不同狀態使用 variants);輪播容器裁剪且永不設為 Hug;長文字使用 Fill + 自動高度。缺漏檢查卡片(規格有寫、建議補)遵循 board-format.md 的線框規格;不要繪製假的產品 UI。

以下步驟 1-3 為路線 A:

  1. 尋找畫面與元件:若目標檔案已有完整的 Mockup 畫面,優先複製並切換狀態(切換 variants、隱藏圖層);這最接近產品。其次使用 search_design_system 與本地元件。僅在兩者皆無時,才從程式碼的結構與樣式建立本地圖層。將顏色、字型大小與間距綁定至專案的變數。當 Mockup 與程式碼不一致時,遵循程式碼並在描述中註明。
    • 若產品字型無法在 Figma 執行環境中載入(例如 Arial),不要更改現有文字。對於新文字,使用寬度相容的字型(Arial → Arimo),並在報告中列出使用位置。
  2. 先為每個裝置建立一個代表性畫面,並將其截圖與原型或即時畫面進行比較:僅在文字、間距、圓角半徑與 Token 都正確後才繼續。若無可比對對象,在報告中說明這些畫面未經比較。
  3. 透過複製或 Instance 加上覆寫,從代表性畫面產生其餘原型卡片,僅變更此狀態下不同的部分。

路線 C:

  1. 捕捉:遵循 web-capture.md 步驟 1-3,設定 shotOnly: true。它會以 2x 解析度寫入 shot/<ID>.jpg,並跳過佈局樹。讀取 stats.json:若有 4096px 的警告,表示畫面過長無法以單張圖片捕捉;應將其拆成數個視埠高度的卡片。
  2. 在上傳前,於本地檢視每一張截圖。這是路線 C 的比較步驟:錯誤的狀態、未完成的 spinner 或遺留的開發工具列,在此修正的成本極低。
  3. 上傳:呼叫 upload_assets,將 nodeIds 設為卡片的 slotId,按卡片順序排列(每次呼叫最多 60 張)。將 submitUrls 寫入檔案,每行一個,並以相同順序傳送截圖:python3 al-upload.py urls.txt capture/shot/C01.jpg capture/shot/C02.jpg。若 upload_assets 無法填入 slot,改用 currentPageId 與 count;截圖會以 <ID>.jpg 命名落在頁面上作為圖層,下一步再將其移入卡片。不要重新命名檔案。
  4. 執行 screenshot-slots.js,將 SECTION_ID 替換,並與 audit.js(步驟 6)放在同一個 use_figma 呼叫中:將每個包裝為非同步函式,依序呼叫,然後在情境稿區段上執行 await section.screenshot() 後再回傳兩者結果,以便在同一呼叫中取得情境稿圖片。它會將每個 slot 調整為截圖大小,並回傳 placed、missing 與 skipped。對 missing 中的卡片再次上傳。
  5. 若要將截圖卡片後續轉換為可編輯圖層,使用路線 B 重建該卡片並傳入相同的 slotId;重建會取代圖片。

完成條件:已檢視每個裝置代表性畫面的截圖,其與原型相符,或已說明無可比對對象。路線 B 還必須符合 code-to-figma 的完成標準。路線 C 中,每張原型卡片都在 placed 中,或報告列出未放置的卡片。

6. 稽核

  1. 執行兩個稽核腳本,將 SECTION_ID 替換為目標區段。將兩者貼入同一個 use_figma 呼叫中(將每個包裝為非同步函式,依序呼叫並回傳兩者結果),以節省一次呼叫預算:
    • audit.js:情境稿稽核。檢查群組是否有標題與描述、卡片 ID 是否重複、畫面是否正確放置等。
  2. 將稽核結果整理為報告,包含覆蓋率摘要、任何問題清單與建議。

完成條件:所有問題已列出,或報告說明無問題。

Individual skills in this repo

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

code-to-figma

Rebuild screens from a running web app as native, editable Figma layers (Auto Layout, components, instances) and diff them against browser screenshots — not a screenshot import or a Code layer. Use when the user asks to "turn this page into Figma", "code to Figma", "push this screen to Figma" or "rebuild the UI in Figma". 把 Web 專案實際跑出來的畫面重建成 Figma 原生圖層:造狀態、抽 DOM 版面樹,建 Auto Layout 和 component/instance,再跟瀏覽器截圖比對。單一畫面或一批畫面都能用,不需要做情境稿。Use when 使用者要「code to figma」「把這頁轉成 Figma」「從程式重建畫面」「push 畫面到 Figma」,或 figma-state-board 走路線 B。產出是可編輯圖層,不是 Code layer 或截圖。

figma-library-binding

Bind Figma screens to a design system library — tokens only on exact value matches, swap icons and components for library versions, and list unmatched values for designers instead of snapping to the nearest token. Use when the user asks to "bind tokens", "use library components" or "find unbound colors". 把 Figma 畫面綁到專案的 design system library:顏色、圓角、邊框、間距、字級完全相同才綁 token,圖示和元件換成 library 版本,沒有對應的值列給設計決定,不取最近值。Use when 使用者要「綁 library」「綁 token」「換成 design system 元件」「檢查沒綁 variable 的顏色」,或 code-to-figma、figma-state-board 的畫面要綁 design system。

関連スキル