Communitygithub.com

better-ui

精緻化表面、圖示與動畫效果,提供邊框圓角、光學對齊、陰影、圖示狀態與動畫的確切數值。

better-ui 是什麼?

better-ui 是一個專注於 UI 視覺細節微調的 AI 代理技能,適用於 Claude Code、Cursor 等開發工具及任何 CSS 動畫框架。它提供了關於邊框圓角、陰影、圖示、動畫和過渡效果等視覺屬性的精確數值,幫助開發者實現高度一致且專業的 UI 設計。此技能強調「互動優先」原則,確保視覺潤飾不會破壞底層互動邏輯,並與 better-accessibility 和 better-layout 等其他技能明確分工。其核心價值在於提供具體、可立即套用的數值(如按壓縮放比例 0.96、交錯進場間隔 100ms),而非模糊的區間建議。支援的平台包括所有現代瀏覽器與 CSS 框架(如 Tailwind CSS),並特別關注無障礙設計,例如配合 prefers-reduced-motion 媒體查詢。通過詳盡的檢查清單和報告格式,開發者可以系統性地找出並修正視覺不一致的問題,將成果整合至開發流程。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Atou4/skillsmith/tree/HEAD/skills/ui-ux/better-ui

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

UI 潤飾

此技能包含表面、圖示與動畫的視覺潤飾,包含每個細節的確切數值。它在底層互動邏輯成立後才套用,且潤飾的發現永遠不能凌駕於有問題的互動之上。

確切數值,選擇性潤飾

以下數值都是確切的,而非可近似的區間。cubic-bezier(0.2, 0, 0, 1) 不是 cubic-bezier(0.4, 0, 0.2, 1),0.96 也不是 0.95。光學微調和同心填充分隔線是例外,它們是起點,需以肉眼判斷。

保留專案的元件庫、設計記號和密度,並在無規則可循時,與其動態語言保持一致。刻意且一致的專案慣例(例如沒有陰影的樣式)屬於偏好設定,而非問題。若同一細節在專案中有兩種做法,則視為問題。

文字換行、字型渲染、表格數字與文字間距屬於 better-typography。點擊區域、鍵盤支援、ARIA 和減少動畫需求屬於 better-accessibility。分組、章節間距、斷點與空間 RTL 屬於 better-layout,但方向性圖示鏡射除外。色彩記號與對比度測量屬於 better-colors。

外側圓角等於內側圓角加上內距

當巢狀表面共享可見且均勻的內縮邊距時,外層圓角等於內層圓角加上內距再加上邊框寬度。若內距超過 24px,或內距刻意不對稱,則將各層視為獨立表面,並保留各自的圓角記號。配方請見 surfaces.md。

幾何視覺偏移時進行光學對齊

當幾何置中看起來不對勁時,以肉眼進行微調。為按鈕的圖示側減少 2px 內距,將播放三角形朝其頂點偏移,並直接在 SVG 中修正不對稱的字形。配方請見 surfaces.md。

陰影用於層次,邊框用於結構

當邊框僅為創造深度而存在時,將其替換為分層的透明 box-shadow 值。分隔線、分割器、表格儲存格和選取狀態則保留邊框。表單輸入框也保留邊框,其邊界需在 better-accessibility 下達到 3:1 的非文字對比度。焦點環同樣屬於 better-accessibility。

強制色彩模式會移除所有 box-shadow。請在陰影環下方保留 border: 1px solid transparent,以便該模式仍能繪製邊緣。配方請見 surfaces.md。

為圖片添加純黑或純白外框

為內容圖片添加 1px 內縮 1px 的外框。在淺色模式使用 oklch(0 0 0 / 0.1),深色模式使用 oklch(1 0 0 / 0.1)。切勿使用接近黑色的色票、色調中性色或強調色,因為色調會在圖片邊緣顯示為彩色邊紋。跳過透明素材,例如標誌和插圖。配方請見 surfaces.md。

互動狀態使用過渡效果而非關鍵影格

使用 CSS 過渡效果或動畫庫的彈簧效果來驅動互動狀態變化,這樣當使用者中途反向操作時可以重新定位。關鍵影格執行固定的時間軸且無法反向,因此保留給只執行一次的序列。詳見 animations.md。

按壓縮放至 0.96

按下的按鈕縮放至 0.96,持續 150ms,使用 ease-out;停用的按鈕永不縮放。為按鈕提供一個選擇退出機制,以便在動畫可能造成干擾時,透過元件現有的變體 API 或 static prop 來關閉。詳見 CSS、Tailwind 和 Motion 的配方。

高頻互動即時回應

按鍵、行懸停和分頁切換需獲得即時回饋,或是在 opacity 或 background-color 上使用 150ms 或更短的過渡效果。將富有表現力的動畫保留給非頻繁的時刻,例如頁面的首次載入、成功狀態或空狀態。

每個動畫化的狀態變化也必須留下靜態提示,例如顏色、圖示或標籤。動畫絕不能是唯一的回饋管道。

在減少動畫偏好設定下關閉動畫

better-accessibility 擁有此要求的所有權,此處的所有配方在未滿足此要求前都不應出貨。僅在 prefers-reduced-motion: no-preference 下執行移動、縮放和模糊效果。在減少動畫模式下,用不透明度交叉淡入淡出來取代,而不是瞬間移除元素。CSS、Tailwind 和 Motion 的配方請見 animations.md。

非頻繁進場交錯 100ms

當序列在分階段進場中傳達層級結構時,將內容拆分為語意區塊,例如標題、描述和操作。將它們交錯 100ms,每個區塊以不透明度、4px 模糊和 12px 的 translateY 在 300ms 內以 ease-out 進場。切勿將常規互動交錯處理。詳見 enter-exit.md。

退場比進場更短、更小

退場使用不透明度、4px 模糊和固定的 -12px translateY,持續 150ms,使用 ease-out,絕不使用完整的容器高度。僅在目標位置具有意義時才完全滑出,例如關閉抽屜。當動畫不提供任何資訊時,立即移除元素。詳見 enter-exit.md。

首次渲染時跳過狀態動畫

在包裹狀態切換的 AnimatePresence 上設定 initial={false},這樣預設狀態在掛載時就不會產生動畫。切勿在刻意設計的進場(例如交錯的主視覺)周圍設定此屬性。詳見 animations.md。

使用確切數值交叉淡入淡出情境圖示

當圖示在非頻繁的狀態變化(例如播放到暫停或複製到已複製)時切換,進行交叉淡入淡出。縮放從 0.25 到 1,不透明度從 0 到 1,模糊從 4px 到 0px。使用動畫庫時,使用 { type: "spring", duration: 0.3, bounce: 0 },且回彈永遠為 0。若無動畫庫,則將兩個圖示保留在 DOM 中,並在 300ms 內使用 cubic-bezier(0.2, 0, 0, 1) 進行交叉淡入淡出。

分頁的圖示切換和懸停時行操作顯示的動作,屬於高頻互動即時回應的範疇。兩個配方請見 icon-transitions.md。

在主題切換時抑制過渡效果

為主題切換停用所有過渡效果,強制樣式刷新,並在下一影格後恢復過渡效果。否則所有色彩過渡會同時觸發,導致切換模糊。詳見配方。

僅對變化的屬性進行過渡

指定確切的屬性名稱,例如 transition-property: scale, opacity,絕不使用 all。詳見 performance.md。

在 will-change 中命名動畫屬性

僅在觀察到首影格卡頓後才添加 will-change,並指定你要動畫化的屬性:scale 用於 scale,transform 用於 transform。僅限於 transform 屬性、opacity 和 filter,絕不使用 all。詳見 performance.md。

懸停效果僅適用於支援懸停的指標

將僅懸停的樣式置於 @media (hover: hover) 之後。在觸控裝置上,:hover 會在點擊後鎖定,看起來像是卡在選取狀態。Tailwind 4 的 hover: 變體已在該查詢下編譯,而 Tailwind 3 則沒有。當控制項自行繪製按下狀態時,設定 -webkit-tap-highlight-color: transparent,以防止預設的灰色閃爍與之重疊。

在覆蓋層內限制滾動

為可滾動的對話框、抽屜、選單和側面板設定 overscroll-behavior: contain,這樣在它們的邊界滾動時就不會滾動背後的頁面。

圖示筆畫粗細匹配文字粗細

圖示的渲染筆畫粗細跟隨其旁文字的粗細,從 400 粗的 1.5px 到 700 粗的 2.5px。每個表面使用一個圖示庫。表格、尺寸和網格規則請見 icons.md。

一個 SVG,按狀態重新著色

圖示使用 currentColor,並透過 CSS 顏色和不透明度取得懸停、選取和停用狀態,而非使用不同的素材。外框是預設變體,填色標示啟用狀態。在 dir="rtl" 下,僅鏡射意義跟隨閱讀方向的圖示。詳見 icons.md。

完成前檢查

檢測項目修正方式
有內距的父層和子層使用相同的 rounded-* 或 border-radius將內距加入外層圓角
box-shadow: 0 0 0 1px 環旁邊沒有 borderborder: 1px solid transparent
img 上使用 outline-slate-*、outline-zinc-* 或十六進制外框顏色outline-black/10 和 dark:outline-white/10
transition-all 或 transition: all指定正在變化的屬性
在 :hover、.open 或其他切換的 class 上設定 animation:在同一屬性上使用過渡效果
active:scale-95、scale-90 或低於 0.96 的 whileTap0.96
帶有縮放的 :active 但沒有 :disabled 排除條件enabled:active: 或 :not(:disabled):active
bounce: 設為非 0 的值bounce: 0
在基本規則中設定 opacity: 0,但僅透過 animation 顯示隱藏狀態在 from 關鍵影格中,animation-fill-mode: both
沒有任何 prefers-reduced-motion、motion-safe: 或 MotionConfig 保護的 translate、scale、filter 或 motion.* 動畫設置保護,並在減少動畫模式下交叉淡入淡出不透明度
色彩過渡加上主題切換,但沒有 disableTransitionOnChange 或覆寫主題切換抑制配方
will-change: all,或在從不動畫的元素上使用 will-change指定正在動畫化的屬性,或刪除它
圖示 SVG 內有 fill="#..." 或 stroke="#..."currentColor
純 CSS 的 :hover 或 Tailwind 3 的 hover: 不在 @media (hover: hover) 內將其包裹在查詢中
在對話框、抽屜或選單上使用了 overflow: auto 或 overflow-y-auto,但沒有 overscroll-behavioroverscroll-behavior: contain

回報

嚴重性。 HIGH 表示破壞了互動,例如無法反向的關鍵影格切換,或在觸控裝置上卡住的懸停狀態。better-interface 的兩個升級觸發條件屬於此類,一經發現即為 HIGH。一個是忽略 prefers-reduced-motion 的動畫,另一個是僅由動畫承載的狀態變化。MEDIUM 表示表面、圖示或動畫中存在可見的不一致性。LOW 表示孤立的潤飾問題。

驗證。 若無瀏覽器,請從程式碼中讀取元件定義的每個狀態(例如懸停、按下、選取、載入和空白),包括其持續時間和緩動函數。若有瀏覽器,請遍歷每個狀態,並在瀏覽器的「動畫」面板中以 10% 的速度重播動畫。將無法執行的檢查回報為 Not verified。

格式。 將發現的問題按其違反的原則分組,按嚴重性排序,每個根本原因一列,列出其出現的每個位置:

嚴重性位置修改前修改後原因

位置 為 path/to/file:line。原因 說明違反的原則和對使用者的影響。

最後,若仍有任何 HIGH 問題未解決,則以 Block 結尾;否則以 Approve 結尾,並將剩餘問題留在表格中作為後續工作。絕不能對未檢查的覆蓋範圍給予 Approve。若無任何事項可回報,請聲明「無可操作的 UI 潤飾發現」並報告驗證結果。

相關技能