UI 打磨
该技能涵盖界面表面、图标和动效的视觉打磨,并给出每个细节的精确数值。它应用于底层交互逻辑已完善之后,并且打磨发现永远不会凌驾于交互问题之上。
精确数值,可选打磨
以下数值是精确的,而非近似范围。cubic-bezier(0.2, 0, 0, 1) 不是 cubic-bezier(0.4, 0, 0.2, 1),0.96 不是 0.95。光学微调和同心内边距截止点是例外情况,它们是起点,需要目视判断。
保留项目的组件库、令牌和密度,并在本节未给出数值的地方,匹配其动效语言。项目中一致且深思熟虑的惯例(例如无阴影的样式风格)属于偏好,而非问题发现。项目中同一细节以两种不同方式实现,则属于问题发现。
文本换行、字体渲染、tabular 数字和文本间距属于 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
按下的按钮在 150ms 内使用 ease-out 缩放至 0.96,禁用的按钮永不缩放。为按钮提供退出机制,以便在动效会分散注意力时,通过组件现有的变体 API 或 static prop 禁用此效果。见 CSS、Tailwind 和 Motion 配方。
高频交互即时响应
按键、行悬停和标签切换获得即时反馈,或在 opacity 或 background-color 上使用不超过 150ms 的过渡。保留表现性动效用于非频繁时刻,例如视图的首次加载、成功状态或空状态。
每个动画状态变化还应留下静态提示,形式为颜色、图标或标签。动效绝不是唯一的反馈通道。
在减少动效偏好下限制动效
better-accessibility 拥有此要求的所有权,这里的配方均不能缺少它。仅在 prefers-reduced-motion: no-preference 下运行移动、缩放和模糊效果。在减少动效下,用不透明度交叉淡入淡出替换它们,而不是立即移除元素。CSS、Tailwind 和 Motion 的配方见 animations.md。
非频繁入场动画错开 100ms
当顺序在分阶段入场中传达层次结构时,将内容拆分为语义块,例如标题、描述和操作。将它们错开 100ms,每个块在 300ms 内使用 ease-out 以不透明度、4px 模糊和 12px 的 translateY 进入。切勿错开常规交互。见 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 中,并使用 cubic-bezier(0.2, 0, 0, 1) 在 300ms 内交叉淡入淡出。
标签的图标切换和行在悬停时显示的操作属于高频交互即时响应。两个配方都在 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 环旁边没有 border | border: 1px solid transparent |
img 上使用了 outline-slate-*、outline-zinc-* 或十六进制轮廓颜色 | outline-black/10 和 dark:outline-white/10 |
transition-all 或 transition: all | 命名变化的属性 |
在 :hover、.open 或其他切换类上设置了 animation: | 对相同属性使用过渡 |
active:scale-95、scale-90 或低于 0.96 的 whileTap | 0.96 |
:active 缩放没有 :disabled 排除 | enabled:active: 或 :not(:disabled):active |
bounce: 设置为 0 以外的值 | bounce: 0 |
基础规则中的 opacity: 0 仅由 animation 揭示 | 隐藏状态在 from 关键帧中,使用 animation-fill-mode: both |
translate、scale、filter 或 motion.* 动画没有 prefers-reduced-motion、motion-safe: 或 MotionConfig 保护 | 关闭它并在减少动效下交叉淡入淡出不透明度 |
颜色过渡加上主题切换没有 disableTransitionOnChange 或覆盖 | 主题切换抑制配方 |
will-change: all,或 will-change 用于从不动画的元素 | 命名动画属性或删除它 |
图标 SVG 内部的 fill="#..." 或 stroke="#..." | currentColor |
纯 CSS :hover 或 Tailwind 3 hover: 不在 @media (hover: hover) 内 | 将其包裹在查询中 |
对话框、抽屉或菜单上的 overflow: auto 或 overflow-y-auto 没有 overscroll-behavior | overscroll-behavior: contain |
报告
严重性。 HIGH 会破坏交互,例如无法反向的关键帧切换或触控上卡住的悬停状态。better-interface 的两个升级触发条件在此处视为 HIGH。一个是忽略 prefers-reduced-motion 的动效,另一个是仅由动效承载的状态变化。MEDIUM 是表面、图标或动效中可见的不一致。LOW 是孤立的打磨问题。
验证。 没有浏览器时,从代码中读取组件定义的每个状态(例如悬停、按下、选中、加载和空状态),包括其持续时间和缓动函数。有浏览器时,遍历每个状态,并在浏览器的“动画”面板中以 10% 速度重放动效。报告所有无法运行的检查为 Not verified。
格式。 将发现按违反的原则分组,按严重性排序,每个根本原因一行,列出其出现的每个位置:
| Severity | Location | Before | After | Why |
|---|
Location 是 path/to/file:line。Why 命名原则和用户影响。
当还存在任何 HIGH 问题时,以 Block 结尾;否则以 Approve 结尾,并将剩余项保留在表格中作为待办工作。切勿 Approve 未检查的覆盖范围。无需报告时,声明“No actionable UI-polish findings”并报告验证情况。