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 連結,立即執行以下兩項操作,不要等到盤點完成才發現無法繪製:
- 確認讀取與寫入權限:
create_session,然後執行一次唯讀的use_figma(列出頁面與頂層節點)。如果回報「無法存取要求的檔案」,使用whoami查看 MCP 登入的帳戶,並給使用者兩個選項:與該帳戶共用檔案並授予編輯權限,或在連接器設定中以有權限的帳戶登入(切換後,原始帳戶的檔案將無法開啟) - 估算呼叫預算:遵循 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:
- 尋找畫面與元件:如果目標檔案已有完整的 Mockup 畫面,優先複製並變更狀態(切換變體、隱藏圖層);這最接近產品。其次使用
search_design_system與本地元件。只有在兩者都不存在時,才從程式碼的結構與樣式建立本地圖層。將顏色、字型大小與間距繫結至專案的變數。當 Mockup 與程式碼不一致時,遵循程式碼並在描述中註明。- 如果產品字型無法在 Figma 執行階段中載入(例如 Arial),不要變更現有文字。對於新文字,使用相容寬度的字型(Arial → Arimo),並在報告中列出使用位置。
- 首先為每個裝置建立一個代表性畫面,並將其截圖與原型或實際畫面進行比較:只有當文字、間距、邊角半徑與權杖都正確時才繼續。如果沒有可比較的內容,在報告中說明這些畫面未經比較。
- 透過複製或實例加上覆寫,從代表性畫面產生其餘原型卡片,僅變更此狀態中不同的部分。
路線 C:
- 捕捉:遵循 web-capture.md 的步驟 1-3,設定檔中
shotOnly: true。它會以 2x 解析度寫入shot/<ID>.jpg並跳過佈局樹。讀取stats.json:關於 4096px 的警告表示畫面過長無法容納於一張圖片;改以多個視埠高度的卡片捕捉 - 在上傳前檢查每張本地截圖。這是路線 C 的比較步驟:錯誤的狀態、未完成的 spinner 或開發工具條遺留在截圖中,在此修正成本為零
- 上傳:使用
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命名的圖層落在頁面上,下一步驟再將其移入卡片。不要重新命名檔案 - 執行 screenshot-slots.js,將
SECTION_ID取代,並與 audit.js(步驟 6)放在同一個use_figma呼叫中:將每個包裝在 async 函式中,依序呼叫,然後在回傳兩個結果前先對情境稿區段執行await section.screenshot(),以便在相同呼叫中取得情境稿圖片。它會將每個插槽調整為其截圖的尺寸,並回傳placed、missing與skipped。對missing中的卡片再次上傳 - 若要稍後將截圖卡片轉換為可編輯圖層,使用路線 B 重建該卡片並傳入相同的
slotId;重建會取代圖片
完成條件:已查看每個裝置代表性畫面的截圖,且與原型相符,或已註明無可比較對象。路線 B 還必須滿足 code-to-figma 中的完成標準。路線 C 中,每張原型卡片都在 placed 中,否則報告需列出未放置的卡片。
6. 稽核
- 執行兩個稽核腳本,將
SECTION_ID取代為目標區段。將兩者貼入同一個use_figma呼叫(每個包裝在 async 函式中,依序呼叫並回傳兩個結果),以節省一次呼叫預算:- audit.js:情境稿稽核。檢查群組是否有標題與描述、重複的卡片 ID,以及是否…
…(後續內容截斷,待補全)