UI 設計
一個被要求編寫畫面的代理，寫出畫面。這項技能彌補了這前後的缺口。首先，決定這個介面的目的及其應有的外觀。然後，確認所構建的內容是否達成任務。
以下所有內容都受兩條規則約束。在建立第一個檔案之前，先指出客戶的成果。在說它運作之前，先實際驅動產品。
先選擇深度
| 變更類型 | 階段 |
|---|---|
| 複製、一個顏色、一個屬性 | 1, 7，然後查看結果 |
| 一個元件、一個狀態 | 1, 4, 6, 7, 9 |
| 一個畫面、一個表單、一個流程 | 0 到 10，簡要 |
| 一個新介面，或「讓它變現代」 | 0 到 10 完整，且階段 3 需在階段 7 前獲批准 |
| 「審計這個」 | 使用 ui-review。不要開始編輯 |
| 「幫我找一個……的元件」 | 使用 ui-find |
在開始前，用一行話說出你選擇的深度。只有在變更完全無法觸及某個階段所保護的面向時，才能跳過該階段。
0. 飛行前檢查：在問任何問題前先閱讀專案
按此順序閱讀，並在能找到答案的第一個項目停止：
- 專案根目錄的
DESIGN.md。已存在的設計系統優先於此技能的所有預設設定和您個人的品味。 遵循它。若工作需要該檔案未涵蓋的內容，請將其加入檔案，而不是在樣式表中憑空發明。 PRODUCT.md、README.md、.claude/、任何現有的簡報。- 正在使用的技術棧、樣式系統和元件庫。
- 最接近的現有畫面，以及涵蓋它的測試。
一個與產品自身系統矛盾的畫面，是一個發現，而不是開始第三個系統的許可。
1. 設計系統
references/design-system.md 包含其格式和兩種進入方式。
| 專案有 | 執行方式 |
|---|---|
一份 DESIGN.md | 閱讀它，遵循它，並用一行話說明 |
| 程式碼中真實的設計系統：Token、主題檔案、Tailwind 設定 | 通過從程式碼中讀取值（絕不猜測），將其編撰至 DESIGN.md |
| 一個沒有書面系統的現有產品或品牌 | 從真實事物編撰：渲染它，讀取計算後的值，記錄下來 |
| 什麼都沒有 | 在階段 3，根據用戶選擇的方向撰寫一份 |
切勿撰寫一份聲明產品未使用之值的 DESIGN.md。一個被編撰的系統是對現有內容的記錄。一個新系統是一個提案，在用戶選定之前，應被標記為提案。
在根據該檔案進行構建之前，對其進行門控檢查：
pnpm dlx @google/design.md lint DESIGN.md
這是一個真實的已發布套件。它會捕捉中斷的 Token 引用、遺失的 primary、從未定義的排版，以及任何低於 4.5:1 對比度下限的元件顏色組合。在階段 7 之前修復它所報告的所有問題。
2. 客戶成果
references/product-thinking.md 包含方法。業務成果、客戶及其工作，以及最小可用版本。每個項目兩行話。
將成果寫成可觀察的結果：
一個有 40 個進行中任務的調度員，可以看到哪個任務延遲，並在不離開列表的情況下重新分配它。
然後是可以在瀏覽器中獨立驗證的接受標準。「看起來不錯」不是一個標準。「在 375px 寬度下，每個任務的狀態及其重新分配控制項都可以在不需要水平滾動的情況下觸及到」才是。
在沒有證據的地方，寫下假設並標記它。切勿撰寫任何非真實人物產生的角色、引言或轉換數據。
3. 方向，與用戶的選擇
references/directions.md 包含方法和詞彙。
提出三個方向，而不是一個。單一提案只是模型的美學默認搭配上一套理由。每個方向都應包含：名稱、錨色調、字型搭配、密度以及一個令人難忘的重點，共四行。
然後停下來，使用互動式提問工具將其呈現給用戶。這是一個批准關卡：不要基於假設就繞過它進行構建。如果用戶說「你來選」，就選一個，用一行話說明選了哪個以及原因，然後繼續進行。
一旦獲得批准，就用所選方向的真實值撰寫或更新 DESIGN.md，並對其進行 lint 檢查。
4. 旅程及其狀態
references/journey-and-states.md。
列出這個介面實際上會有的狀態：空白、一個項目、多個項目、最密集的真實案例、載入中、部分失敗、錯誤、無權限。基於一個固定樣本構建的畫面會隱藏所有其他狀態，而這正是完成的畫面在接觸客戶時失敗的最常見原因。
5. 在撰寫元件前先尋找它們
執行 ui-find，或直接執行其腳本：
node .claude/skills/ui-design/scripts/find-components.js <搜尋詞> --limit 15
首先搜尋專案自己的元件。產品已有的元件被二次實現是一個缺陷。只有在說出已讀取過的候選元件以及每個元件為何不合適後，才能從頭開始撰寫元件。
6. 模型，或真實產品
用一行話詢問選擇哪種路線，除非用戶已經說過。兩種路線都建立真實的 HTML 和 CSS；區別在於檔案放置的位置及其連接的對象。
| 路線 | 時機 | 檔案位置 |
|---|---|---|
| 模型 (Mock) | 新介面、重新設計、需要說服利益相關者，或用戶要求 | 在 mock/ 下的獨立頁面，使用真實設計 Token 和範例資料，並明確說明是範例 |
| 直接 (Direct) | 在現有產品內部的變更，或用戶說直接構建 | 產品自己的檔案 |
模型獲批准後，再用產品的元件重建。在構建之前就說明這點，這樣就不會有人期望模型檔案被發佈。
7. 構建
構建階段 4 中的狀態，而不僅僅是快樂路徑。使用產品自己的 Token 和元件。
在每次 UI 編輯之前，即使是小編輯，都要立即閱讀 references/gates.md 和 references/craft.md。
gates.md 是基礎：每個模型都會落入的預設陷阱，以及應該怎麼做。craft.md 是更上一層的工藝。陰影要深度而非邊框。同心圓角。ease-out 曲線在 300ms 以下。只在首次出現且不重複響應的入場動畫。等寬數字。將畫面的兩個部分連接起來，讓客戶覺得它們是一體的。
先單獨構建最重要的畫面，或英雄區塊。 在構建其餘部分之前，用全新的視角審查它：一個對先前決策毫無記憶的子代理能抓住你遺漏的問題。然後再構建其餘部分。
8. 運行它並觀察它
這不是程式碼審查。啟動應用程式，在瀏覽器中打開它，並像客戶一樣從真實的入口點使用它。
references/playwright.md 包含操作細節以及應用程式無法在此啟動時的應對方法。
查看截圖。讀取檔案列表不等於查看。
9. 審查與修復
對你構建的內容執行 ui-review。它會測量即時渲染，走查旅程，檢查結果是否符合 DESIGN.md，並按危害程度對發現進行排序。
按嚴重性順序修復。一個你無法根據階段 2 的成果來證明的變更，就是沒有人要求的範圍蔓延。說出你保留了什麼以及原因。
然後 references/regression.md：識別在修改程式碼之前就已經能正常運作的旅程，並區分你的變更導致的失敗和原本就存在的失敗。
10. 報告
- 客戶成果，以及是否達成。
- 選擇的方向，以及由誰選擇。
- 構建或更改了什麼，按檔案列出。
- 驗證了什麼，透過何種方式，在哪些寬度下，在哪些狀態下。
- 未驗證什麼，以及原因。
- 已修復的發現，以及未修復的發現及其原因。
- 仍然是假設的假設。
誠信，其優先級高於以上所有階段
- 絕不報告你未執行的測量或未渲染的畫面。
- 指出每個替代品。用固定樣本代替即時資料，用靜態頁面代替應用程式，用本地字型代替品牌字型。
- 當應用程式無法啟動或訪問時，要說明情況，並將所有關於旅程的主張標記為未驗證。不要描述程式碼就好像你親眼看到它運行一樣。
- 絕不虛構指標、推薦信、標誌牆或客戶數量。當真實數據缺失時，留下一個標記好的空位並說明是空的。
- 一個背後沒有實際功能表單，要在其表面說清楚。一個顯示「已發送」但實際並未發送的頁面是一個缺陷，而不是佔位符。
- 親自走查旅程能發現摩擦點。但它不能衡量客戶的真實行為。
此技能借鑒了什麼，以及從何處借鑒
NOTICE 記錄了相關資訊。元件來源及其許可證記錄在 sources.json；scripts/check-sources.js 用於驗證該檔案，tests/run.sh 用於測試腳本。