better-ui

讓介面感覺更好的細節

出色的介面很少來自單一因素。通常是許多小細節累積成出色的體驗。在建構或審查 UI 程式碼時應用這些原則。

審查時，放慢介面速度：在瀏覽器的「動畫」面板中以 10% 速度重播動畫，並檢查每個狀態：懸停、焦點、啟用、載入、空狀態。在 10% 速度下感覺不對勁的地方，就是全速時微妙地出錯的地方。

保留專案的元件庫、設計 token 和密度。符合其既有的動畫語言，除非以下原則指定了確切的互動模式。

排版（文字換行、字型渲染、表格數字、間距）由 better-typography 技能處理；任何與文字相關的事項請使用該技能。無障礙（點擊區域、焦點狀態、鍵盤支援、ARIA、減少動畫）由 better-accessibility 技能處理。佈局結構（分組、區塊間距、斷點、空間 RTL）由 better-layout 技能處理。

快速參考

類別	使用時機
表面	邊框圓角、光學對齊、陰影、圖片外框
動畫	可中斷動畫、進場/離場轉場、圖示動畫、按壓縮放、動畫節制
圖示	圖示筆畫粗細、透過 currentColor 的狀態、輪廓 vs 填滿、尺寸、RTL 翻轉
效能	轉場屬性指定、will-change 使用

核心原則

1. 同心圓邊框圓角

外層圓角 = 內層圓角 + 內邊距。巢狀元素圓角不匹配是讓介面感覺不對勁最常見的原因。

2. 光學對齊優先於幾何對齊

當幾何置中看起來不對時，使用光學對齊。含有圖示的按鈕、播放三角形和不對稱圖示都需要手動調整。

3. 陰影用於層次，邊框用於結構

對於按鈕、卡片和容器，如果邊框僅用於創造深度，優先使用分層的透明 box-shadow 值。保留用於傳達結構或狀態的邊框：分隔線、佈局分隔線、選取或焦點狀態。

4. 可中斷動畫

使用 CSS 轉場處理互動狀態變化：它們可以在動畫進行中被中斷。保留關鍵影格用於只執行一次的分階段序列。

5. 拆分與交錯進場動畫

對於不頻繁的分階段進場，且序列有助於傳達層級時，將內容拆分成語意區塊，並以約 100ms 交錯，而不是動畫整個容器。不要對常規、高頻率的互動進行交錯。

6. 微妙的離場動畫

使用小的固定 translateY 而不是完整高度。離場應比進場更柔和。進場和離場轉場都使用 ease-out。

7. 情境式圖示動畫

使用 opacity、scale 和 blur 來動畫圖示，而不是切換可見性。確切使用這些值：縮放從 0.25 到 1，透明度從 0 到 1，模糊從 4px 到 0px。如果專案在 package.json 中有 motion 或 framer-motion，則匹配該套件的匯入路徑（或兩者都存在時使用既有的附近匯入），並使用 transition: { type: "spring", duration: 0.3, bounce: 0 }；bounce 必須始終為 0。如果未安裝任何動畫庫，則將兩個圖示保留在 DOM 中（一個絕對定位），並使用 CSS 轉場進行交叉淡入淡出，使用 cubic-bezier(0.2, 0, 0, 1)；這樣無需任何依賴即可同時獲得進場和離場動畫。

8. 圖片外框

為圖片添加微妙的 1px 外框，透明度低，以獲得一致的深度。淺色模式下顏色必須是純黑色（oklch(0 0 0 / 0.1)），深色模式下是純白色（oklch(1 0 0 / 0.1)），絕不能使用接近黑色的顏色，如 slate、zinc 或任何帶色調的中性色。有色調的外框會吸收其下方的表面顏色，在圖片邊緣看起來像髒污。

9. 按壓縮放

點擊時微妙的 scale(0.96) 為按鈕提供觸覺回饋。始終使用 0.96。絕不使用小於 0.95 的值：任何低於此的值都感覺誇張。添加 static prop 以在動畫會分散注意力時停用此效果。

10. 頁面載入時跳過動畫

在 AnimatePresence 上使用 initial={false} 以防止首次渲染時的進場動畫。確認它不會破壞有意的進場動畫。

11. 絕不使用 transition: all

始終指定確切屬性：transition-property: scale, opacity。Tailwind 的 transition-transform 涵蓋 transform, translate, scale, rotate。

12. 謹慎使用 will-change

僅用於 transform、opacity、filter，這些是 GPU 可以合成的屬性。絕不使用 will-change: all。僅在注意到第一幀卡頓時才添加。

13. 圖示筆畫粗細與文字粗細匹配

文字旁的圖示應承載文字的光學重量：1.5px 筆畫搭配一般（400）文字，2px 搭配半粗體（600）。每個圖示集使用一種筆畫粗細；絕不在同一表面上混合不同圖示庫。

14. 一個 SVG，按狀態重新著色

圖示使用 currentColor，其狀態（懸停、選取、禁用）透過 CSS 顏色和透明度獲得，絕不使用單獨的素材。輪廓變體為預設；填滿變體標記啟用狀態。

15. 動畫節制

高頻率互動上不要使用自訂動畫：注意力成本會在每次觸發時重複。動畫絕不是唯一的回饋通道；每個動畫狀態變化也需要一個靜態提示（顏色、圖示、標籤）。

常見錯誤

錯誤	修正
緊密巢狀的父層和子層使用相同的邊框圓角	計算 outerRadius = innerRadius + padding
圖示看起來未置中	使用內邊距進行光學調整，或直接修正 SVG
邊框僅用於偽造層次	使用分層的透明 box-shadow；保留結構性和狀態性邊框
突兀的分階段進場或情境式離場	對不頻繁的進場進行交錯，並保持保留情境的離場微妙
有狀態的圖示或切換在頁面載入時動畫其預設狀態	在該 AnimatePresence 上添加 initial={false}；保留有意的頁面進場
元素上的 transition: all	指定確切屬性
第一幀動畫卡頓	添加 will-change: transform（謹慎使用）
細線圖示搭配粗體文字	將筆畫寬度匹配文字粗細
每個狀態使用不同的圖示素材	一個 currentColor SVG，狀態透過 CSS
到處都是填滿圖示	預設為輪廓，僅在啟用狀態使用填滿
每次懸停或按鍵都觸發進場動畫	即時回饋或 ≤150ms 的透明度/顏色轉場

審查輸出格式

僅在使用者要求獨立的 UI 打磨審查時使用此格式。當 better-interface 協調審查時，請將領域證據和發現提供給該技能，並讓其輸出格式、嚴重性等級、合併規則、上限和裁決優先。

將獨立審查分為兩部分呈現。

發現

按原則分組所有確認的發現。使用包含嚴重性、位置、之前、之後和原因欄位的 Markdown 表格。絕不使用單獨的「之前：」/「之後：」行。

• 嚴重性：HIGH 使互動誤導、無回應或反覆干擾；MEDIUM 造成明顯的工藝或一致性問題；LOW 是孤立的打磨問題。
• 位置：引用 path/to/file:line。如果成品沒有原始檔，請引用確切的畫面和元件。
• 之前 / 之後：顯示當前實作和可操作的替代方案。
• 原因：指出違反的原則，並解釋它如何影響介面。

將重複的系統性問題合併為一行，並列出所有受影響的位置。省略沒有發現的原則。

範例

同心圓邊框圓角

嚴重性	位置	之前	之後	原因
LOW	src/Card.tsx:28	卡片上 rounded-xl + 內部按鈕上 rounded-xl（p-2）	卡片上 rounded-2xl（8 + 8 = 16），內部按鈕上 rounded-lg	巢狀角落應為同心圓
LOW	src/card.css:11	兩個巢狀表面上 border-radius: 16px	外部 24px，內部 16px，內邊距 8px	相等的巢狀圓角使內部表面看起來被擠壓

按壓縮放

嚴重性	位置	之前	之後	原因
LOW	src/Button.tsx:19	<button className="...">	添加 active:scale-[0.96] transition-transform	按壓回饋使控制項感覺有回應
MEDIUM	src/button.css:24	按壓時 scale(0.9)	提高到 scale(0.96)	低於 0.95 的任何值都感覺誇張

驗證與裁決

在發現之後：

1. 驗證：列出執行的確切檢查及其觀察結果。檢查每個相關狀態，並在涉及動畫時以 10% 速度檢查動畫。如果某項檢查未執行，請說明仍需驗證的內容。
2. 裁決：如果仍有任何 HIGH 發現，則為 Block；如果僅有 MEDIUM 或 LOW 發現，則為 Needs changes；僅在沒有可操作的發現時為 Approve。

當沒有發現時，省略表格，說明「無可操作的 UI 打磨發現」，報告驗證，並以 Approve 結束。