lksnmnn/product-ui

Product UI

一個應用程式是一個工作表面：人們會回來用它完成工作。每個元素都必須透過服務該工作來證明其存在的價值。目標是掙得的熟悉感 — 一個熟練使用此類工具的人，能憑直覺信任每個控制項，讓介面消失在任務之中。

這些規則適用於任何應用程式。特定於某個專案的內容 — 裝置目標、設計系統、元件、方向、已知的偏離 — 則存在於專案檔案中；請以此為基礎進行建置。在宣告一個畫面完成之前，先執行 review.md。

專案檔案

按以下順序尋找：首先是在 CLAUDE.md 或 AGENTS.md 中命名的路徑，然後是 .claude/product-ui.md。如果都不存在，請在第一次建置前從 templates/project.md 建立 .claude/product-ui.md：

1. 尋找設計系統：Token 文件（CSS 自訂屬性、Tailwind 主題、Token JSON）、元件庫（儲存庫內的 components/ui、shadcn、MUI、Radix 等）、Story 檔案。
2. 列出畫面所需的建構區塊（頁面架構、表格、表單欄位、空白狀態、對話框、提示訊息等）及其路徑。將每個缺失的標記為缺失；切勿自行發明路徑。
3. 注意你在過程中發現的偏離：程式碼違反下述規則的地方。
4. 詢問使用者每個應用程式的裝置目標，以及誰擁有視覺語言（設計團隊或開發者）。根據應用程式的意圖建議目標。

只寫下你已驗證的內容。將 CLAUDE.md 指向該檔案，以便後續的會話能找到它。

當專案沒有視覺方向，且表面不應看起來過於通用時，請先執行 design-direction 技能；它會將結果記錄在同一個檔案中。

目的優先

在進行版面配置之前，請針對每一項各寫一行：

• 畫面服務的任務與執行該任務的人；
• 第一眼資訊：他們開啟畫面時會看的第一件事；
• 主要操作以及他們重複操作的頻率；
• 目標裝置：手機、平板、筆電、大螢幕，來自專案檔案。

畫面中的每個區域都必須對應到上述其中一行。無法對應的區域將被刪除。

真實內容

使用形同生產環境的內容進行建置和判斷：真實長度的真實姓名、最長的合理標題、0、1、7 和 500 個項目、一個缺失的選填值、比英文長 30% 的翻譯文字。「John Doe」、「Acme Inc」、「Lorem ipsum」、「Item 1」和整數會隱藏所有版面配置問題，並且是讓畫面看起來像自動產生的首要原因。當不知道領域的資料時，請詢問樣本或從 schema 推導出來。

每種尺寸

一個畫面針對其主要裝置進行最佳化，並在所有其他中斷點以相同功能運作。每個尺寸都使用最適合它的模式，而不是桌面板的縮小複製品：側邊欄變成抽屜或圖示軌道、表格變成堆疊列表、分割面板變成帶有返回步驟的頁面、懸停變成可見的控制項、密集的工具列變成溢出選單。在某個中斷點以下消失的功能是一個發現。

在目標寬度下，沒有任何東西會橫向滾動：頁面不會，其自身容器內的列表也不會。自由文字欄位（姓名、標題、電子郵件、檔案名稱）會縮小並截斷，並在懸停時顯示完整文字；只有真正寬的網格（矩陣、時間軸）可以滾動，並且必須明確說明。

在大螢幕上，內容應保持可讀的度量：文字區塊應保持在每行約 75 個字元以下，表單保持其欄位寬度，表格可以增長，但其自由文字欄位佔用空間。

導航

• 全域導航列出應用程式的區塊，並在每個螢幕上保持不變。
• 一個有自己的子區域的區塊可以添加一個本地層級（第二欄或頁籤）。每個層級只顯示其自身的層級：沒有層級重複另一個層級的條目，兩個條目絕不共享一個標籤。
• 範圍 — 畫面所操作的組織、工作區或帳戶 — 由一個切換器設定，只顯示一次。
• 每個頁面距離全域導航最多兩個選擇，且本地導航在主裝置上維持可見。
• 第一個控制項上方的 chrome 保持小尺寸：麵包屑絕不重複其下方的頁面標題。
• 一個具有多個區塊或大量記錄的應用程式，應提供一個可跳轉至任何地方的搜尋功能（⌘K / Ctrl+K），可依名稱或貼上的 ID 找到頁面和記錄。

密度

• 一次顯示工作集。需要掃描或比較的列表是表格，每項一行；卡片網格適用於少數項目，其圖片或預覽即為內容。

• 行高跟隨內容：單行 36–44px，帶有第二行或縮圖的行最多 64px；內距的高度絕不超過內容的高度。

• 相關項目之間的間距小於群組之間的間距，因此僅從間距就能看出分組。

• 行中的每個元素都必須證明其存在的價值。測試每一個：

  • 任務：它服務於尋找、比較、開啟或操作該項目，針對此畫面的工作；
  • 刪除：移除它會遺失使用者需要的東西；否則它應該被移除，或移到詳細檢視中；
  • 冗餘：它不重複任何欄位、啟用的篩選器或頁面標題；
  • 不言自明：無需懸停、工具提示或圖例即可閱讀，狀態是文字，而不是僅靠顏色；
  • 順序：先識別項目的資訊，然後是人們會比較的事實，最後是操作。

  缺少的事實也是一個發現：當人們為了比較一個值而逐一開啟項目時，該值就應該放在行中。

• 預設每行一行。次要資訊應放在自己的欄位或灰暗的第二行中，絕不放在需要使用者懸停才能比較的工具提示中。

• 標題、描述和輔助文字應盡可能簡短，以符合任務需求。重複標題的頁面描述應被刪除。

• 空白用於分隔群組；它絕不用於將稀疏的畫面填充至看起來飽滿。

• 盒子（邊框、背景、陰影）用於標示使用者將其作為一個單元操作的東西。僅使用空間或分隔線進行分組；卡片內的卡片是一個發現。

階層

• 每個檢視一個主要操作，在視覺上主要，位於其範圍（頁面標題或面板標題）的右上角。次要操作為輪廓或幽靈按鈕；破壞性操作放在最後。
• 每個尺寸、間距、顏色和圓角都必須來自表面的設計系統，並保持在系統內。任意值（text-[10px]、p-[13px]、原始十六進制）是一個發現；修復方式是使用最接近的階層，或當沒有階層符合時建立新的 Token。
• 權重和顏色在尺寸之前傳達階層。
• 顏色承載意義：強調色標記主要操作、選擇和狀態。狀態顏色僅在存在狀態時出現。
• 圖示伴隨標籤，以加速識別（導航、頻繁操作），並僅對通用操作（關閉、搜尋、更多）單獨使用，且需具備可訪問的名稱。每個按鈕、標題或卡片上的圖示都是裝飾。
• 唯讀值呈現為文字，絕不呈現為輸入框。
• 檢視者的角色無法使用的控制項應隱藏，由與伺服器檢查的相同能力決定。當知道操作存在很重要時，它會顯示為禁用狀態並附上原因（例如「只有管理員可以邀請」）。
• 文案應使用人們能識別的名稱，而非背後的基礎設施：除非受眾直接與供應商或管道合作，否則不要使用供應商或管道名稱。導航不要列出未建置或已關閉的功能。

文案

介面文字是設計的一部分，也是生成式畫面最明顯的特徵。

• 按鈕應說明其功能，使用動詞及其受詞：「邀請成員」、「匯出 CSV」。永遠不要使用「提交」、「確定」、「點擊此處」、「開始使用」等詞語。
• 確認按鈕應重複問題中的動詞：「刪除 3 個檔案？」 → 「刪除檔案」。
• 所有標籤、標題和按鈕使用句子大小寫。不要使用驚嘆號、不要用「哎呀」、不要用「成功」、不要用「請」。
• 反饋應以使用者的角度說明結果：「發票已寄送至 finance@…」，而不是「操作成功完成」。
• 空白狀態應以一兩句簡單的句子說明這裡應該有什麼以及如何得到它。不要使用機智的語言、插圖填充或「這裡什麼都沒有」。
• 不要在工具內部使用行銷用語：刪除「無縫」、「省力」、「強大」、「解鎖」、「加速」、「神奇」、「AI 驅動」以及任何讚美產品的句子。
• 整個應用程式中一個概念只使用一個術語；詞彙表存在於專案檔案中。
• 數字、日期和單位在整個應用程式中遵循一種格式；計數使用正確的複數形式（「1 個檔案」、「2 個檔案」）。

列表和表格

• 數字右對齊，使用 tabular-nums；文字左對齊。
• 時間戳記在整個應用程式中使用一種固定的格式，永遠不要使用瀏覽器的區域設定預設值，且永遠不要截斷。監控畫面將相對時間（「3 分鐘前」）與懸停時的絕對時間配對，或反過來。
• 頁首以一到兩個單字命名欄位；可排序的頁首在點擊時排序。
• 搜尋、篩選器、排序、頁碼和已開啟的項目都應存在於 URL 中，以便檢視能在重新載入、返回和共享連結後保持狀態。
• 行是其項目的真實連結：整行可開啟項目，Cmd+點擊可開啟新分頁。
• 行中的每個參照 — 人員、組織、職位、ID — 都應連結到其自身的頁面。
• 對行的操作應位於行的末端，一個穩定的欄位中，在靜止時可見；至少在觸控螢幕上應顯示。一個需要點擊才能看見的控制項是一個錯誤。
• 批次處理需要選取核取方塊、全選和批次操作列。
• 超過約 50 行時使用分頁或視窗化；計數始終可見。一個能限制集合範圍的篩選器（例如月份範圍）可以在顯示範圍時取代分頁。
• 篩選芯片可以帶有計數；這樣它們就可以兼作頁面的摘要。

表單

• 標籤在欄位上方，單欄，順序應符合使用者思考資料的順序。
• 在失焦和提交時驗證；錯誤訊息應位於其欄位下方，並說明如何修正。
• 預設值是最常見的答案。選填欄位標記為選填，必填欄位不標記。
• 建立或操作表單上的提交按鈕應保持啟用狀態。提交無效輸入時，應聚焦到第一個無效欄位，並在該欄位下方顯示如何修正。
• 編輯表單上的儲存按鈕可以在沒有任何變更時保持禁用狀態，因為沒有待儲存的內容；一旦有任何變更，它就會啟用，上述規則也適用，並且旁邊的「有未儲存的變更」提示顯示狀態。
• 每個檢視一個儲存按鈕。在未儲存變更的情況下離開時需要先詢問。
• 當控制項自身的操作正在進行時，它應被禁用，以防止雙重點擊。
• 短表單或單一欄位應就地編輯；對話框適用於需要專注且不能失去上下文的任務。
• 輸入框應使用正確的類型並設定 autocomplete（電子郵件、電話、一次性密碼等），以便手機顯示正確的鍵盤，瀏覽器也能自動填寫。
• 檔案上傳觸發器是一個可聚焦的按鈕，可開啟選擇器，並同時接受拖放。
• 配置其他表面繪製內容的頁面（例如入職流程、品牌、範本），應在其設定旁邊顯示該表面的預覽。

操作與反饋

• 具有恢復路徑的操作（還原、取消歸檔、重新啟用）應立即執行並提供復原功能，無需額外確認。切換開關本身就是一種復原，只需要即時反饋。
• 沒有恢復路徑的操作需要一個確認對話框，說明會遺失什麼（例如「刪除 3 個文件」）。看起來可逆但實際上沒有的操作，應視為不可逆，直到反向操作存在為止。
• 每個操作應在 100ms 內回應：樂觀更新、控制項上的待處理狀態，或內容將放置處的骨架屏。
• 需要幾秒鐘以上的工作應在背景執行並顯示可見的進度，並且在導航後繼續執行。
• 錯誤訊息應說明發生了什麼以及下一步該怎麼做，並顯示在發生錯誤的位置附近。

狀態矩陣

每個檢視都應附帶所有狀態，經過設計，而非使用預設值：

狀態	形狀
載入中	內容將佔用的版面中的骨架屏
空白	說明這裡應該有什麼，並提供新增的操作
篩選後空白	說明篩選器未匹配任何內容，並提供清除篩選器的操作
部分載入	已載入的部分渲染；失敗的部分顯示其自身的錯誤，絕不顯示 0
無存取權限	說明誰可以看到此內容以及如何獲得存取權限，並提供前進的方式
錯誤	失敗的內容、重試按鈕、螢幕的其餘部分仍可使用
完整	真實內容、逼真的數量，包含長名稱和許多行

每個互動控制項都有預設、懸停、焦點可見、啟用、禁用和待處理狀態。

在儀表板上，每個圖磚和圖表都有自己的狀態：讀取失敗顯示其自身的錯誤，絕不顯示 0 或空圖表。儀表板應開啟在需要注意的事項上，而不是一排行指標卡；數字只有在附帶使其有意義的比較值（目標、上一期）以及團隊同意的定義時才出現。圖表在安裝了 dataviz 技能時遵循該技能。

無障礙與主題

• 正文文字在每個主題中都必須達到 4.5:1 的對比度，大字型文字和控制項邊界為 3:1。灰色上的淺灰色是最常見的失敗案例。
• 焦點總是可見且不被裁剪；焦點環是經過設計的，而不是移除瀏覽器預設值。
• 每個控制項都有一個可訪問的名稱；僅圖示按鈕需要 aria-label。地標（nav、main）和每個頁面一個 h1。
• 文字可縮放至 200% 且佈局保持不變。
• 當應用程式支援深色主題時，它必須經過設計：有自己的表面階層和重新調整的強調色，而不是反轉顏色。在兩種主題下審查每個畫面。

人體工學

• 主要任務可透過鍵盤完成：Tab 順序遵循閱讀順序、Enter 提交、Escape 關閉、焦點回到原來的位置。
• 點擊目標至少為 24×24px，頻繁使用的目標更大，觸控螢幕上為 44px；點擊區域應涵蓋整行或整個標籤，而不僅僅是圖示。
• 頻繁的操作應靠近其操作的對象。距離和點擊次數…

…

[此處為截斷內容]