Communitygithub.com

figma-state-board

盤點一個功能的所有 UI 狀態,從程式碼產生對應畫面,並在 Figma 上產出一張「情境稿(State Board)」——包含原型已處理的實際畫面,以及缺失的錯誤、空狀態和載入狀態的缺口檢查,分為「規格有寫」與「建議補」。當使用者要求製作「情境稿」、列出功能的所有 Figma 狀態、檢查缺少哪些錯誤畫面,或要更新現有情境稿時使用。

figma-state-board 是什麼?

此技能專為開發者和 AI Agent 設計,能自動從產品專案的程式碼中盤點一個功能的所有 UI 狀態,並在 Figma 上生成或更新一張「情境稿(State Board)」。情境稿是一種 Figma 區段,將功能的所有狀態排列在同一畫布上,並按裝置、分頁或主題分組;每張卡片包含 ID、名稱、觸發條件與結果,以及產品畫面。最後一個群組「缺漏檢查」會列出原型尚未處理但功能應有的狀態(如錯誤、空狀態、載入等),並進一步區分為「規格有寫」(規格要求但原型漏做)和「建議補」(規格與原型均未提及)。此技能適用於所有技術棧和產品類型,支援 Claude Code、Cursor 等平台,並與 `state-discovery`(盤點狀態)、`code-to-figma`(從程式碼重建畫面)等技能協作。流程包含確認輸入、建立狀態矩陣、準備卡片資料、建立情境稿骨架、在 Figma 中繪製畫面,以及最終稽核。使用者可選擇三種繪製路線:複製既有 Mockup、從程式碼重建,或使用瀏覽器截圖,以適應不同預算與需求。

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

在你喜歡的 AI 中提問

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

說明文件

Figma State Board(情境稿)

情境稿(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 指南技能),請遵循其產品畫面權杖、命名與驗收標準。

步驟

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 建立矩陣。預先分配卡片 ID,遵循 board-format.md 的規則。

在使用者確認矩陣之前不要繪製。 群組如何劃分、哪些卡片合併、保留哪些建議補卡片,都在此步驟決定;繪製後再修改成本更高。如果原型卡片超過 150 張,遵循 scale-guard.md 並詢問使用者是否要合併卡片、拆分頁面或拆分檔案。在使用者決定之前不要繪製。

3. 為每張卡片準備資料

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

完成條件:每張原型卡片都有可重現的資料,或清楚標示「僅在 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
  • 重新計算覆蓋率摘要中的數字
  • 保留情境稿的現有語言,即使使用者現在使用另一種語言;混合標籤的情境稿難以閱讀
  • 不要觸碰右側的設計師筆記區域或回饋區段

完成條件:每張原型卡片都有佔位符插槽與 slotId;所有缺口檢查線框都已繪製。

5. 在 Figma 中建立畫面

使用 use_figma 建立原生圖層並放入步驟 4 的佔位符插槽中。send_code_to_figma 會匯入 Code 圖層且不產生可編輯的設計圖層,因此不適用於情境稿。

路線 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;產品畫面會放入卡片的佔位符插槽中。目前僅支援 Web 前端。
  • 路線 C:瀏覽器截圖。每張原型卡片顯示執行中應用程式的截圖;不重建任何內容。無論卡片數量多少,整個情境稿約需 3 次計數呼叫,因此當呼叫預算不足以覆蓋路線 B(Starter 方案、View 和 Collab 席位),或使用者只需要狀態清單與缺口檢查時,提供此選項。畫面是圖片,非可編輯圖層;提供時及報告中均需說明。僅支援 Web 前端。步驟如下「路線 C」所示。

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

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

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

路線 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 無法填入插槽,改用 currentPageId 與 count 呼叫;截圖會以 <ID>.jpg 命名的圖層落在頁面上,下一步驟再將其移入卡片。不要重新命名檔案
  4. 執行 screenshot-slots.js,將 SECTION_ID 取代,並與 audit.js(步驟 6)放在同一個 use_figma 呼叫中:將每個包裝在 async 函式中,依序呼叫,然後在回傳兩個結果前先對情境稿區段執行 await section.screenshot(),以便在相同呼叫中取得情境稿圖片。它會將每個插槽調整為其截圖的尺寸,並回傳 placed、missing 與 skipped。對 missing 中的卡片再次上傳
  5. 若要稍後將截圖卡片轉換為可編輯圖層,使用路線 B 重建該卡片並傳入相同的 slotId;重建會取代圖片

完成條件:已查看每個裝置代表性畫面的截圖,且與原型相符,或已註明無可比較對象。路線 B 還必須滿足 code-to-figma 中的完成標準。路線 C 中,每張原型卡片都在 placed 中,否則報告需列出未放置的卡片。

6. 稽核

  1. 執行兩個稽核腳本,將 SECTION_ID 取代為目標區段。將兩者貼入同一個 use_figma 呼叫(每個包裝在 async 函式中,依序呼叫並回傳兩個結果),以節省一次呼叫預算:
    • audit.js:情境稿稽核。檢查群組是否有標題與描述、重複的卡片 ID,以及是否…

…(後續內容截斷,待補全)

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。

相關技能