UI 清理工具

UI 清理工具 是做什麼的？

編輯一個介面，使其上的每個文字和裝飾都對使用它的人有意義。生成的畫面往往會自我解釋：標題上方有個標籤，標題下方有個句子，按鈕旁邊有個提示。每個添加看起來無害，但加在一起就掩蓋了使用者真正想找的那幾個字。

目標是創建一個服務於使用者的畫面。這不是一個避免看起來像生成的畫面。當一條規則與使用者的需求衝突時，後者優先，並且你需要在報告中說明這一點。

目標： 使用者指定的檔案、資料夾或元件。如果未指定，則使用此對話中修改過的介面檔案。如果也沒有，則提出詢問。

範圍： 文案、操作、狀態、虛構內容、裝飾和圖表。視覺表面（規則 X1 至 X4）僅在使用者要求時才包含，無論是口頭說明還是帶有 --surface 參數。

步驟 1：說明誰在使用這個畫面

在讀取任何字串之前，寫下一行：

誰： 一個在任務中按下 Esc 鍵的玩家。在做什麼： 決定是返回遊戲、更改設定還是重新開始。

這一行是你判斷一切的依據。沒有它，下面的規則就會被當作模式匹配來應用，而模式匹配會把密碼要求和填充內容一起刪掉。首次訪問定價頁面的用戶需要的文字比行政表格的日常用戶更多。遊戲可以帶有風格化文字，但稅務表單則不行。

如果程式碼沒有告訴你使用者是誰，請從產品中推斷並說明你的推斷。只有在兩種合理的解讀會導致不同的編輯結果時，才提出詢問。

步驟 2：測試

對於每一段可見文字和每個裝飾元素，問：

如果沒有這個，那個人會猶豫、犯錯，或是對接下來發生的事情感到驚訝嗎？

• 不會 → 刪除。
• 不會，但某處的某人需要它 → 移動它。給開發者的事實放入程式碼註解。少數使用者會找的事實放入工具提示或文檔。僅輔助技術需要的名稱放入 aria-label。
• 會，但它說得不好 → 改寫它，只使用你能在程式碼、內容或對話中找到的事實。
• 會 → 保留它，並且不要動它。

下面這些規則是生成的畫面常見的測試失敗方式。它們幫助你快速找到候選項。當一個畫面以規則未命名的方式失敗時，測試仍然適用。當一條規則標記了某個通過測試的內容時，保留它。

值得完整句子的文字

這些幾乎每次都能通過測試。不要把它們縮短成一個標籤，也不要刪除它們：

• 使用者必須滿足的限制：密碼規則、接受的檔案類型和大小、日期和數字格式、字元限制。
• 後果：破壞性或不可逆操作會刪除的內容、付款收取的金額和時間、權限授予的內容、共享後誰會看到。
• 錯誤訊息：出了什麼問題以及下一步該怎麼做。
• 空白狀態：這裡應該有什麼以及如何添加第一個。
• 同意、法律和法規文字。切勿編輯其措辭。如果看起來有問題，請報告。
• 使用者很少執行且無法撤銷的任務的說明。

規則

ID 是穩定的。在報告中引用它們。

文案

• C1. 眼神標題。 標題上方的小寫大寫或字母間距文字（"FEATURES"、"HOW IT WORKS"、"OPERATION ON HOLD" 在 "PAUSED" 上方）。標題本身已經命名了該部分，所以刪除眼神標題。如果眼神標題是更好的那行（遊戲中的風格文字、產品自身的術語），則將其提升為標題並刪除通用的那一個。兩者選其一，從不保留兩者。
• C2. 裝飾性編號。 "01 02 03"、"01 // Features"、"§" 和 "//" 前綴。除非順序是真實的且使用者會遵循（例如結帳步驟或安裝指南），否則刪除。
• C3. 副標題反射。 每個標題下都有一個句子，每個選單項下都有一個描述（"設定：更新您的設定"）。僅當它說明了標題未提及的事實時才保留一個。
• C4. 敘述。 描述元素顯而易見的樣子或功能的幫助文字和說明文字（"點擊下面的按鈕開始"、"這張卡片顯示您的近期活動"）。刪除。
• C5. 洩漏的實作註記。 關於畫面底層如何運作的文字，或從提示中渲染出來的要求："繼續會重新捕獲滑鼠"、"（實時更新）"、"（由 AI 驅動）"、"數據快取 5 分鐘"。使用者不會根據它行動。將其移動到程式碼註解中，或刪除。
• C6. 狀態字串。 用 "·" 或 "|" 連接的事實（"12 個項目 · 2 分鐘前更新 · 已同步 · v2.1"）。保留使用者會據此行動的事實。將其他事實放在需要的地方，或刪除它們。
• C7. 重複提示。 重複佔位符、圖示、按鈕文字或部分標題的標籤。保留一個。對於表單欄位，保留可見標籤：佔位符在輸入時會消失，並且不是可訪問的名稱。
• C8. 口號。 "One. Big. Thing."、"Built different."、"Ship faster. Think less." 如果來源給了你有關事物本身及其功能的資訊，則將其改寫成一個命名事物及其功能的句子。否則，將其標記給負責人。
• C9. 通用部分標題。 "為什麼選擇我們"、"您所需的一切"、"專為像您這樣的團隊打造"。一個可以放在任何產品頁面上的標題對這個產品來說毫無意義。根據部分內容重新命名，如果內容本身沒有標題也能成立，則刪除標題。
• C10. 提示過載。 對已有文字標籤的控制項、每個操作上的鍵盤快捷鍵晶片、"提示：" 和 "專業提示" 的提示框、普通畫面上的引導標記。當控制項其他方面不明確時（如僅圖示按鈕）或快捷鍵是主要使用方式時，保留提示。

操作

• A1. 模糊的操作標籤。 "開始"、"了解更多"、"提交"、"繼續"、"確定"、"點擊這裡"。按鈕應該說出按下時會發生什麼：一個動詞，以及當動詞單獨使用時不明確時的受詞（"建立帳戶"、"匯出 CSV"、"發送邀請"）。在步驟式流程中，"繼續" 和 "下一步" 是可以的。
• A2. 一個操作，多個名稱。 同一個操作在一個畫面上叫 "刪除"，下一個畫面叫 "移除"，選單裡叫 "丟入垃圾桶"；或者 "登入" 旁邊是 "登錄"。選擇專案使用最多的術語，並在目標範圍內統一應用。如果兩個名稱代表不同的操作（從列表中移除 vs 永久刪除），則兩者都保留。
• A3. 確認對話框。 "您確定嗎？" 配上 "確定" 和 "取消"。標題命名操作及其受詞（"刪除 3 個專案？"），主體說明後果（如果有的話）（"這也會移除它們的 14 個任務。此操作無法撤銷。"），確認按鈕重複動詞（"刪除專案"）。對於可以輕鬆撤銷的操作進行確認，其本身就是一種雜亂：將其標記給負責人。

狀態

載入、成功、空白和錯誤文字是填充內容的聚集地，因為在審查畫面時沒有人會看這些狀態。在編輯任何狀態文字之前，請閱讀 references/states.md：它說明了每個狀態應包含什麼，這遠不止於要刪除什麼。

• S1. 載入填充內容。 "請稍候！"、"正在計算..."、"請稍等，我們正在準備一切"。僅在等待時間足夠長以閱讀時，才說明正在載入的內容。否則，只使用旋轉圖示或骨架螢幕。
• S2. 成功填充內容。 "成功儲存！"、"您的更改已成功儲存。" 用盡可能少的文字陳述結果（"已儲存"、"邀請已發送至 [email protected]"）。如果畫面已經顯示了結果，則不需要提示訊息。
• S3. 空白狀態填充內容。 "這裡什麼都沒有！"、"看起來您還沒有建立任何專案。點擊開始，建立您的第一個專案！" 說明這裡應該有什麼，並提供添加它的單一操作。
• S4. 模糊或可愛的錯誤訊息。 "糟糕！出了點問題"、"發生錯誤。請稍後再試。" 說明失敗了什麼以及使用者可以做什麼。如果程式碼無法知道失敗了什麼，請直說並提供重試選項。

虛構內容

• F1. 虛假證明。 使用者數量、正常運行時間數據、星級評分、帶有姓名和職位的推薦、"受信任於" 的標誌行、"曾見於"。如果專案沒有其來源，那麼它對於一個已發布的頁面就是一個虛假聲明。不要把它改寫成一個更小的虛假聲明。將其移除並在報告中列出，以便負責人能提供真實內容。
• F2. 已發布畫面中的佔位數據。 "John Doe"、"Acme Corp"、lorem ipsum、example.com 地址、庫存頭像服務。在測試固定裝置、測試和故事中，這是可以的。在已發布的畫面中，將其作為任務報告。你無法提供真實數據。

裝飾

• D1. 無狀態徽章。 爲增添趣味而添加的 "NEW"、"LIVE"、"AI"、"Beta"、"Pro"、"Popular"。僅在徽章反映了應用程式追蹤的某個狀態時才保留。
• D2. 狀態點。 文字旁邊的脈動或彩色點。僅在綁定到真實狀態時保留，並為其提供一個可訪問的名稱。
• D3. 裝飾性表情符號和圖示。 在標題、按鈕、標籤和列表項中。刪除。當圖示是控制項本身（帶有 aria-label 的圖示按鈕）或它承載了文字未說明的意義時，才保留圖示。

圖表和儀表板

• V1. 標題命名圖表類型。 "每月收入長條圖" 變成 "每月收入"。僅當你面前的數據顯示了發現時（"收入自三月以來翻倍"），才陳述發現。
• V2. 閱讀說明。 "每個長條代表一個月"、"懸停以查看詳細資訊"。刪除。
• V3. 重複說明。 每個度量使用一種編碼。一個帶有箭頭、百分比、"上升" 單詞以及一個重申所有三個的句子的 KPI，保留數字和一個比較。
• V4. 與數據競爭的框架。 繪圖框架、深色或密集的網格線、粗軸邊框、3D、標記上的陰影和發光效果。刪除，或將必須保留的部分縮細至髮絲線。相同的圖表類型、相同的數據、相同的系列顏色。
• V5. 直接標籤可用時的圖例。 對於四個或更少的系列並且有空間標記它們時，在線條末端或長條旁邊直接命名每個系列，並移除圖例。

表面（僅在要求時）

首先閱讀 references/surface.md。它以一個檢查設計意圖的步驟開始，該步驟決定這些規則是否適用：一個遊戲、一個行銷頁面或一個具有刻意顯示排版的編輯佈局，不是需要被標準化的缺陷。

• X1. 漸層和發光效果。 表面和按鈕上的色相到色相漸層、漸層文字、彩色發光、模糊的彩色斑塊。
• X2. 比例外間距。 當周圍使用比例值時出現的單例值，如 mt-[13px] 或 gap: 7px。
• X3. 運行中 UI 的粗體字重。 主體文字、標籤、表格儲存格和控制項上的 800 和 900 字重。顯示標題不在範圍內。
• X4. 裝飾性動畫。 transition-all、懸停時縮放的卡片、不說明任何東西的彈跳和循環。

對於你保留或改寫的文字的樣式層級（大小寫、標點、填充詞、一致性），請閱讀 references/writing.md。對於實際操作的前後對比範例，包括正確編輯是保留文字的情況，當你不確定要刪除多少時，請閱讀 references/examples.md。

護欄

• 永不添加事實。 改寫使用程式碼、內容檔案、數據或對話中存在的內容。"編輯內容在幾秒內同步" 是一個產品聲明，而你無法知道它是否為真。如果誠實的改寫需要你沒有的資訊，則刪除這一行或將其列為給負責人的任務。這是最容易被違反的規則，因為一個虛構的具體描述比它所取代的模糊行看起來更好。
• 僅更改可見文字和裝飾元素。 不要觸碰邏輯、數據、顏色、字體和佈局結構。例外情況是 V4 下的圖表框架以及被要求時的表面規則。
• 保留可訪問的名稱。 永遠不要刪除圖示按鈕上的 aria-label、alt、title 或僅供螢幕閱讀器使用的文字。如果你刪除的可見文字是唯一的可訪問名稱，請將其移動到 aria-label。
• 在來源處編輯文字。 來自 i18n 檔案、props、測試固定裝置或 CMS 的字串，在那裡編輯，或報告。不要在元件中硬編碼替換。當你在一個語言檔案中更改字串時，將其他語言檔案列為任務；除非被要求，否則不要自行翻譯。
• 刪除後清理。 移除現在為空的包裝器以及僅為已移除元素存在的邊距或間距。
• 保留乾淨的畫面。 如果沒有任何東西通過測試，則不做任何更改。
• 遵循專案。 當專案有自己的語音指南、詞彙表、令牌或設計系統時，朝著這些方向修復，而不是朝向此技能的預設值。

程序

追蹤這些步驟：

- [ ] 1. 誰和在做什么：一行
- [ ] 2. 計數：python3 scripts/count_tells.py <target>      (如果要求則添加 --surface)
- [ ] 3. 查看：如果可以，截取畫面
- [ ] 4. 閱讀每個狀態下的每個可見字串和裝飾；應用測試；使用規則 ID 標記失敗項
- [ ] 5. 裁決：重度、輕度或無
- [ ] 6. 編輯
- [ ] 7. 再次計數，再次查看
- [ ] 8. 報告

scripts/ 在此技能的資料夾中。使用其完整路徑執行腳本。

計數。 count_tells.py 是對原始碼進行的正則表達式掃描。它會找到候選項，並為具有程式碼簽名的模式提供前後數字。它無法看到 C3、C4、C5、C7、A2、V3 或任何依賴於含意的內容，並且會標記合法的使用情況。將其輸出視為一個需要查看的位置列表。當剩餘的內容是特意保留的時，計數未達到零是可以的。

查看。 原始碼隱藏了使用者看到的內容：哪些字串一起出現、什麼來自數據、刪除會對佈局造成什麼影響。如果你有瀏覽器或截圖工具，請在前後擷取畫面。如果都沒有，python3 scripts/screenshot.py <url-or-html-file> <out.png> 可以在安裝了 Playwright 的情況下做到。檢查後的圖像是否有孤立的空白、失去層級結構的標題以及移動過的控制項。如果你無法渲染畫面，請在報告中說明。

閱讀每個狀態。 預設視圖只顯示了介面的一小部分。在目標中搜尋載入、空白、錯誤、成功和禁用分支、提示訊息、對話框和驗證。

...