UI Lab：UX 建議
UX 建議會經歷三個階段：
- Mock（原型） — 僅修改 lab 程式碼，範圍以專案 lab 筆記中指定的平台為準。業主可以點擊檢視各個選項。
- Close the round（結束該輪測試） — 該輪測試會被標記，並將記錄寫入
docs/ux-history/，同時刪除相應的 lab 檔案。 - Promote（推廣） — 業主選定選項並核准計畫後，該選項就會成為正式畫面，並納入其共用邏輯，若應用程式有雙平台，也會一併處理。
專案的 lab 筆記
此技能定義了流程；每個專案的具體細節則存在其 .claude/ui-lab.md 中。請先閱讀該檔案再進行任何操作。它會提供：
- Platform（平台）：此機器上要使用哪個 lab 應用程式（
uname -s）、其 ID、lab 程式碼存放位置，以及開啟畫面的指令； - Option folders（選項資料夾）：每個平台對應的資料夾與套件，以及字串存放位置；
- Files（檔案）：選項畫面所使用的佈景主題或顏色，以及推廣時狀態的移動目標；
- Sample data（範例資料）：選項所需的資料來源；
- Fakes and edge cases（模擬資料與邊界情況）：此應用程式中無法顯示的模擬資料，以及需要檢查的邊界情況；
- Screenshots（螢幕截圖）：如何在各平台進行截圖；
- Promote（推廣）：目標路徑、另一平台的處理方式、需更新的文件以及 release 建置指令；
- lab 本身的運作方式（文件連結）。
若 .claude/ui-lab.md 的內容與此技能衝突，以筆記為準。若專案沒有 .claude/ui-lab.md，或其中缺少下方所需的任何項目，請詢問業主，不要自行猜測，並將答案補進筆記中。
第一階段：Mock（原型）
從當前分支建立一個 ux/<screen> 分支進行開發，以便其他機器可以拉取該輪測試。若工作目錄中有非你所為的未提交變更，請先詢問再切換。
每個選項一個資料夾
每個選項都位於自己的資料夾中（位置由筆記指定），以便能單獨刪除、恢復或推廣。該資料夾應位於 screens 套件內，這樣推廣時就只是移動檔案。
| 檔案 | 用途 | 推廣時的操作 |
|---|---|---|
<Screen>Option<B> | 畫面本身：<Screen>Screen<B>(state, actions)，須達到正式產品品質（使用應用程式的字串與佈景主題，依筆記規定），且不得包含 lab 專用型別 | 移入應用程式 |
<Screen>Option<B>State | 應用程式邏輯尚未產生的狀態，但須按照邏輯未來會產生的方式來設計 | 移至筆記指定的位置 |
<Screen>Option<B>Lab | 其範例資料、模擬行為、無實際操作的 actions，以及 LabOption 值（附帶它所模擬的內容說明） | 刪除 |
| 該選項的字串（若應用程式使用字串資源，位置與名稱依筆記規定） | 該選項新增的文字 | 移入應用程式的字串中 |
- 除資料夾（以及無法放入資料夾的字串資源檔案）外，每個選項還需新增一行：在
LabScreens的畫面清單中加入<screen>OptionB,。 - 資料夾內的所有內容均設為
private，除了畫面本身、其狀態以及LabOption值（這些名稱需包含選項名稱，以避免衝突）。 - 若某選項需要修改應用程式的現有元件，則在其資料夾中使用自己的副本。
- 範例資料來自筆記指定的來源（保持原樣），加上該選項在其
Lab檔案中新增的內容。若筆記說明資料為真實資料，請勿自行編造文字。
步驟
- 在 lab 中開啟該畫面，檢視
current（應用程式目前的畫面）。 - 撰寫 2 到 3 個不同的方向作為選項
a、b、c（排在current之後），每個選項附上一行說明其變更內容。 - 在每個
LabOption值上方，列出該選項模擬了什麼：應用程式邏輯尚缺的資料、未建置的行為，以及無法顯示的模擬資料（筆記會列出此應用程式的常見項目）。 - 檢查筆記所列的邊界情況，以及該畫面可能出現的特殊情況。會影響設計的情況應自成一個選項（例如
a-rtl、a-dark）。 - 建置後，開啟每個選項並檢視螢幕截圖（指令在筆記中；Android 裝置的相關事項請參考 android-emulator 技能）。從手機傳回的全黑螢幕截圖表示手機已鎖定：請業主解鎖。
- 在分支上提交，並告知業主選項 ID（
<screen> <option>）、每個選項模擬了什麼，以及所使用的裝置。
若業主要求修改某個選項，修改內容應成為新資料夾中的新選項（例如 b2 與 b 並列）。業主否決的選項在該輪測試結束前仍應保留，以便該輪的標籤能包含所有選項。
第二階段：Close the round（結束該輪測試）
業主已選定某選項或否決所有選項後：
- 在該輪測試的最後一次提交上打標籤（此時所有選項都還在），並推送標籤：
git tag ux/<screen>/<yyyy-mm-dd> && git push origin ux/<screen>/<yyyy-mm-dd>。標籤可確保分支刪除後程式碼仍可存取；同一天的第二輪測試則使用-2。 - 按照下方格式撰寫
docs/ux-history/<screen>/<yyyy-mm-dd>-<topic>.md，並依照筆記規定將它連結到應在的位置（例如畫面的文件）。 - 刪除其他選項的資料夾、字串檔案以及
LabScreens中的行；被選中的選項則保留至第三階段。 - 提交。若所有選項都被否決，該輪到此結束：合併分支（歷史檔案是其唯一的永久變更）或刪除分支，依業主喜好選擇。
# <Screen> — <topic>（<yyyy-mm-dd>，<platform>）
Tag：`ux/<screen>/<yyyy-mm-dd>`
## 選項
- **a — <name>**：<變更內容>。*已選取*，在 <commit> 中推廣。
- **b — <name>**：<變更內容>。*已否決*：<業主的原因（若有提供）>。
## 模擬的內容
- b：<原型所展示但應用程式尚無法做到的功能>。
## 恢復選項
git checkout ux/<screen>/<yyyy-mm-dd> -- <option folder> <strings files>
然後在 `LabScreens` 中加入 `<screen>Option<B>,`。
建立在該標籤當時所使用的 <components 與 sample data> 之上。恢復後若有編譯錯誤，表示問題出在選項的副本與範例資料中；請在該處修正。
恢復
若業主要求使用較早的選項，請遵循其歷史檔案：從標籤中將路徑 checkout 到 ux/<screen> 分支，加入 LabScreens 行，修正選項資料夾內無法編譯的部分，然後開啟它。該選項即成為新一輪測試中的有效選項。
第三階段：Promote（推廣）
該輪測試結束並有選定選項後，進入計畫模式（EnterPlanMode），並使用 ExitPlanMode 呈現計畫；業主會透過按鈕核准。計畫應涵蓋：
- 要移動的檔案以及它們要取代的畫面；
- 每個模擬項目背後的邏輯工作：提議的狀態、ViewModel 或 Controller 變更，及其測試；
- 若應用程式有雙平台，另一平台的處理方式（依筆記規定）；
- 筆記規定需要更新的文件。
業主核准後，在同一個分支上：
- 使用
git mv將選項的畫面檔案移入應用程式（目標位置依筆記規定），取代舊畫面，並將函式或 View 命名為該畫面的名稱。 - 將它的字串移入應用程式的字串中，移除選項前綴或 table。
- 將其狀態移至筆記指定的位置，讓應用程式的邏輯能透過測試產生該狀態，並連接 actions。
- 將其複製的元件合併回原始元件，然後刪除其資料夾的其餘部分及
LabScreens中的行；將LabScreens中該畫面的current指向已推廣的畫面。 - 使用筆記的指令進行 release 建置，此時任何對 lab 程式碼的引用都應導致編譯失敗。
- 完成計畫中關於另一平台與文件的部分，並將推廣的提交記錄到該輪的歷史檔案中。
分支的合併由業主決定。