make-interfaces-feel-better

让界面更显精致的细节

出色的界面很少只靠单一因素实现。通常是许多细节逐渐累积，最终带来出色的体验。构建或审查 UI 代码时，请运用这些原则。提出或编写修复方案前，先确认项目现有的样式系统，并用该系统表达改动：Tailwind 项目使用 Tailwind，CSS 项目使用纯 CSS，或沿用项目已有的 CSS-in-JS 方案。切勿仅为润色而引入第二套样式系统。

审查时，不妨放慢界面：在浏览器的 Animations 面板中以 10% 的速度重播动画，并逐一检查各种状态：悬停、焦点、激活、加载、空状态。以 10% 的速度播放时显得不对劲的地方，往往在正常速度下也存在不易察觉的问题。

快速参考

类别	适用场景
Typography	文本换行、字体平滑、等宽数字
Surfaces	边框圆角、视觉对齐、阴影、图像轮廓、点击区域
Animations	可中断动画、进入/退出过渡、图标动画、按压缩放、克制动效
Icons	图标描边粗细、通过 currentColor 设置状态、轮廓与填充、尺寸、RTL 翻转
Performance	过渡属性的指定、will-change 的用法

核心原则

1. 同心边框圆角

外层圆角 = 内层圆角 + 内边距。嵌套元素的圆角不匹配，是最常见的界面观感不协调原因。

2. 优先考虑视觉对齐，而非几何对齐

几何居中看起来不协调时，应按视觉效果对齐。带图标的按钮、播放三角形和不对称图标都需要手动调整。

3. 用阴影表现层级，用边框呈现结构

对于边框仅用于营造纵深感的按钮、卡片和容器，优先使用多层透明 box-shadow 值。保留用于传达结构或状态的边框：分隔线、布局分隔符，以及选中或焦点状态。

4. 可中断的动画

交互状态变化使用 CSS 过渡——它们可以在动画播放过程中被中断。关键帧则留给只播放一次的分阶段序列。

5. 拆分并错开进入动画

对于不常出现、且通过顺序有助于传达层级的分阶段入场效果，将内容拆成语义区块，并以约 100ms 的间隔依次播放，而不是为整个容器添加动画。不要错开常见的高频交互。

6. 轻柔的退出动画

使用较小的固定 translateY，而不是完整高度。退出效果应比进入效果更柔和。进入和退出过渡都使用 ease-out。

7. 与情境相符的图标动画

使用 opacity、scale 和 blur 为图标添加动画，而不是切换可见性。数值必须严格如下：scale 从 0.25 变为 1，opacity 从 0 变为 1，blur 从 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. 字体平滑

在 macOS 上，为根布局应用 -webkit-font-smoothing: antialiased，让文本显示得更清晰。

9. 等宽数字

对任何动态更新的数字使用 font-variant-numeric: tabular-nums，避免布局偏移。

10. 文本换行

标题使用 text-wrap: balance。正文使用 text-wrap: pretty，避免出现孤行。

11. 图片描边

为图片添加低不透明度的细微 1px 描边，以保持一致的纵深感。浅色模式下，颜色必须是纯黑色（oklch(0 0 0 / 0.1)）；深色模式下，必须是纯白色（oklch(1 0 0 / 0.1)），绝不能使用接近黑色的颜色，例如 slate、zinc 或任何带色调的中性色。带色调的描边会受到下方表面颜色的影响，看起来像是图片边缘沾了污渍。

12. 按下时缩放

点击时轻微应用 scale(0.96)，为按钮提供触感反馈。始终使用 0.96。切勿使用小于 0.95 的值——低于此值会显得夸张。添加 static 属性，以便在动效可能造成干扰时将其禁用。

13. 页面加载时跳过动画

在 AnimatePresence 上使用 initial={false}，以防止首次渲染时播放进入动画。确认这不会破坏有意设置的进入动画。

14. 切勿使用 transition: all

始终指定确切的属性：transition-property: scale, opacity。Tailwind 的 transition-transform 涵盖 transform, translate, scale, rotate。

15. 谨慎使用 will-change

仅用于 transform、opacity、filter 这类可由 GPU 合成的属性。切勿使用 will-change: all。仅在注意到首帧卡顿时才添加。

16. 最小触控区域

交互元素应优先采用 44×44px 的触控区域，以适用于触屏或移动场景。在密集的桌面界面中，至少使用 40×40px。如果可见元素较小，可通过伪元素扩展。绝不允许两个元素的触控区域重叠。

17. 让图标描边与文本字重匹配

文本旁的图标应与文本保持视觉重量一致：常规（400）文本旁使用 1.5px 描边，半粗体（600）文本旁使用 2px。每套图标只用一种描边粗细；同一界面中切勿混用不同的图标库。

18. 使用单个 SVG，并根据状态重新着色

图标使用 currentColor，并通过 CSS 颜色和不透明度呈现不同状态（悬停、选中、禁用），而不是使用不同资源。默认使用线框变体；填充变体表示活动状态。

19. 克制动效

高频交互不要使用自定义动画：每次触发都会重复消耗注意力。动效绝不能是唯一的反馈渠道；每次动画状态变化都需要配备静态提示，例如颜色、图标或标签。

常见错误

错误	修正方法
父元素和子元素使用相同的边框半径	计算 outerRadius = innerRadius + padding
图标看起来没有居中	通过内边距进行视觉调整，或直接修正 SVG
仅用边框伪造高度	使用带透明度的分层 box-shadow；保留结构性边框和状态边框
分阶段进入或保留上下文的退出效果突兀	为低频进入效果添加交错，并让保留上下文的退出效果保持轻微
数字导致布局偏移	应用 tabular-nums
macOS 上文本显得粗重	在根元素上应用 antialiased
页面加载时播放动画	在 AnimatePresence 上添加 initial={false}
元素上使用 transition: all	指定确切的属性
首帧动画卡顿	添加 will-change: transform（谨慎使用）
小控件的触控区域太小	通过伪元素扩展至适用于触屏/移动端的 44×44px，或在密集的桌面界面中至少扩展至 40×40px
细线描边的图标搭配粗体文本	让描边宽度与文本字重匹配
每种状态使用单独的图标资源	使用单个 currentColor SVG，通过 CSS 表示状态
所有图标都使用填充样式	默认使用线框样式，仅在活动状态下使用填充样式
每次悬停或按键都播放进入动画	提供即时反馈，或使用 ≤150ms 的透明度/颜色过渡

审查输出格式

未指定审查模式时，使用 full。

模式	覆盖范围	发现项上限
quick	主要用户路径和访问频率最高的状态；仅报告 HIGH 和 MEDIUM 问题	5
full	请求范围内的全部内容，包括排版、表面、动画、图标和性能	15

范围与覆盖情况

说明模式、确切范围、框架、样式约定以及任何审查边界。展示实际检查过的内容：

类别	检查的证据	结果
排版	文件、组件、状态或检查项	发现数量、Clear，或附带原因的 Not reviewed

包括全部五个 Quick Reference 类别。绝不要暗示检查过实际上未检查的界面。

发现

按原则归类发现。使用包含 Severity、Location、Before、After 和 Why 列的 Markdown 表格。包含所有已做或提议的更改，不要只列其中一部分。绝不要单独另起“Before:”/“After:”行。

• Severity：HIGH 表示交互无法访问、具有误导性、不可读或反复造成干扰；MEDIUM 表示造成明显的可用性或一致性问题；LOW 表示个别细节润色，且仅出现在 full 模式中。
• Location：引用 path/to/file:line。如果产物没有源文件，则引用确切的屏幕和组件。
• Before / After：展示当前实现和可执行的替换方案。
• Why：指出违反的原则，并说明对用户造成的影响。

将重复出现的系统性问题合并为一行，并列出所有受影响的位置。省略没有发现问题的原则，绝不要为了凑够上限而填充报告。

示例

同心边框圆角

Severity	Location	Before	After	Why
LOW	src/Card.tsx:28	卡片和内部按钮（p-2）均使用 rounded-xl	卡片使用 rounded-2xl（8 + 8 = 16），内部按钮使用 rounded-lg	嵌套圆角应保持同心
LOW	src/card.css:11	两个嵌套表面均使用 border-radius: 16px	外层设为 24px，内层设为 16px，间距为 8px	嵌套圆角相同会让内部表面显得局促

等宽数字

Severity	Location	Before	After	Why
MEDIUM	src/Counter.tsx:17	<span>{count}</span>	<span className="tabular-nums">{count}</span>	比例数字会导致数值变化时位置偏移
LOW	src/timer.css:8	计时器使用默认数字	为计时器添加 font-variant-numeric: tabular-nums	等宽数字可让计时器保持稳定

按下时缩放

Severity	Location	Before	After	Why
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 会显得夸张

已考虑但未采纳

在 quick 模式中列出 1–3 个真实候选项，在 full 模式中列出 2–5 个：

Location	Candidate	Rejected because
src/Card.tsx:28	增强阴影	现有层次符合共享表面令牌；仅修改单张卡片会降低一致性

不要编造凑数内容。如果范围内的边缘候选项较少，列出实际存在的候选项并说明这一点。

验证与结论

列出发现后：

1. 验证：列出实际运行的确切命令或执行的交互，并说明观察到的结果。遍历所有相关状态；涉及动画时，以 10% 速度检查动效。如果未运行某项检查，将其标记为 Not verified 并说明尚待检查的内容。
2. 结论：若仍有任何 HIGH 级别发现，则结论为 Block；若仅有 MEDIUM 或 LOW 级别发现，则结论为 Needs changes；只有不存在任何可执行的发现时，结论才为 Approve。在结论旁列出所有未经验证的检查。

如果没有发现问题，则省略发现表格，注明“No actionable interface-polish findings”，报告验证情况和未采纳的候选项，并以 Approve 结束。