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 連結,立即執行兩件事。不要等到盤點完成才發現無法在檔案中繪製:
- 確認讀寫權限:執行
create_session,然後執行一次唯讀use_figma(列出頁面與頂層節點)。若回報「無法存取請求的檔案」,使用whoami查看 MCP 登入的帳號,並提供使用者兩個選項:與該帳號共用檔案並授予「可編輯」權限,或在連接器設定中切換為有權限的帳號(切換後無法開啟原始帳號的檔案) - 估算呼叫預算:依照 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:
- 尋找畫面與元件:若目標檔案已有完整的 Mockup 畫面,優先複製並切換狀態(切換 variants、隱藏圖層);這最接近產品。其次使用
search_design_system與本地元件。僅在兩者皆無時,才從程式碼的結構與樣式建立本地圖層。將顏色、字型大小與間距綁定至專案的變數。當 Mockup 與程式碼不一致時,遵循程式碼並在描述中註明。- 若產品字型無法在 Figma 執行環境中載入(例如 Arial),不要更改現有文字。對於新文字,使用寬度相容的字型(Arial → Arimo),並在報告中列出使用位置。
- 先為每個裝置建立一個代表性畫面,並將其截圖與原型或即時畫面進行比較:僅在文字、間距、圓角半徑與 Token 都正確後才繼續。若無可比對對象,在報告中說明這些畫面未經比較。
- 透過複製或 Instance 加上覆寫,從代表性畫面產生其餘原型卡片,僅變更此狀態下不同的部分。
路線 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無法填入 slot,改用currentPageId與count;截圖會以<ID>.jpg命名落在頁面上作為圖層,下一步再將其移入卡片。不要重新命名檔案。 - 執行 screenshot-slots.js,將
SECTION_ID替換,並與 audit.js(步驟 6)放在同一個use_figma呼叫中:將每個包裝為非同步函式,依序呼叫,然後在情境稿區段上執行await section.screenshot()後再回傳兩者結果,以便在同一呼叫中取得情境稿圖片。它會將每個 slot 調整為截圖大小,並回傳placed、missing與skipped。對missing中的卡片再次上傳。 - 若要將截圖卡片後續轉換為可編輯圖層,使用路線 B 重建該卡片並傳入相同的
slotId;重建會取代圖片。
完成條件:已檢視每個裝置代表性畫面的截圖,其與原型相符,或已說明無可比對對象。路線 B 還必須符合 code-to-figma 的完成標準。路線 C 中,每張原型卡片都在 placed 中,或報告列出未放置的卡片。
6. 稽核
- 執行兩個稽核腳本,將
SECTION_ID替換為目標區段。將兩者貼入同一個use_figma呼叫中(將每個包裝為非同步函式,依序呼叫並回傳兩者結果),以節省一次呼叫預算:- audit.js:情境稿稽核。檢查群組是否有標題與描述、卡片 ID 是否重複、畫面是否正確放置等。
- 將稽核結果整理為報告,包含覆蓋率摘要、任何問題清單與建議。
完成條件:所有問題已列出,或報告說明無問題。