better-ui

让界面更出色的细节

出色的界面很少只依赖单一因素。通常是许多细节相互叠加，最终带来绝佳体验。构建或审查 UI 代码时，请运用这些原则。

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

保留项目的组件库、设计令牌和信息密度。遵循项目既有的动效风格，除非下文某条原则规定了确切的交互模式。

排版（文本换行、字体渲染、等宽数字、间距）由 better-typography 技能涵盖；任何与文本相关的内容都请使用该技能。无障碍（点击区域、焦点状态、键盘支持、ARIA、减少动态效果）由 better-accessibility 技能涵盖。布局结构（分组、区块间距、断点、空间方向的 RTL）由 better-layout 技能涵盖。

快速参考

类别	使用时机
表面	边框圆角、视觉对齐、阴影、图像描边
动画	可中断的过渡、按压时缩放、页面加载时跳过动画、切换主题、克制动效
进入与退出	分阶段进入、交错时间、退出过渡
图标过渡	状态变化时让图标交叉淡入淡出，有无动效库均适用
图标	图标描边粗细、通过 currentColor 表示状态、轮廓与填充、尺寸、RTL 翻转
性能	过渡的具体性、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. 图像轮廓

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

9. 按下时缩放

点击时轻微缩放至 scale(0.96)，可以为按钮带来触感反馈。始终使用 0.96；低于 0.95 会显得夸张。添加 static 属性，在动画会造成干扰时禁用缩放。CSS、Tailwind 和 Motion 配方。

10. 页面加载时跳过动画

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

11. 切换主题时禁用过渡效果

主题切换会同时改变几乎所有元素的颜色、背景、边框和阴影，因此这些属性上的所有过渡都会一起触发，让切换过程变得拖沓，而不是干脆利落。注入 *,*::before,*::after{transition:none !important}，强制重排，然后在下一帧移除它。配方。

12. 只过渡发生变化的属性

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

13. 谨慎使用 will-change

只用于 transform、opacity、filter 等可由 GPU 合成的属性。绝不要使用 will-change: all。只有在发现首帧卡顿时才添加。

14. 图标描边粗细要与文本字重匹配

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

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

图标使用 currentColor，并通过 CSS 颜色和不透明度呈现不同状态（悬停、选中、禁用），绝不要为不同状态使用单独的资源。默认使用轮廓变体；填充变体用于标记激活状态。

16. 克制使用动效

高频交互不要使用自定义动画：每次触发都会重复消耗注意力。动效绝不能成为唯一的反馈渠道；每次动画状态变化还必须有静态提示（颜色、图标、标签）。

常见错误

错误	修正方法
紧密嵌套的父元素和子元素使用相同的边框圆角	计算 outerRadius = innerRadius + padding
图标看起来不居中	通过内边距进行视觉校正，或直接修正 SVG
仅用边框营造层次感	使用带透明度的分层 box-shadow；保留用于结构和状态的边框
生硬的分阶段进入动画或破坏上下文的退出动画	为低频进入动画添加错开效果，并让能保留上下文的退出动画保持轻微
有状态的图标或切换控件在页面加载时播放默认状态动画	在相应的 AnimatePresence 上添加 initial={false}；保留有意设置的页面进入动画
主题切换让整个页面交叉淡化	切换时禁用过渡效果，强制重排，并在下一帧恢复
元素使用 transition: all	明确指定具体属性
首帧动画卡顿	添加 will-change: transform（谨慎使用）
细线图标与粗体文本并列	让描边粗细与文本字重匹配
为不同状态使用单独的图标资源	使用单个 currentColor SVG，通过 CSS 呈现不同状态
所有图标都使用填充样式	默认使用轮廓样式，仅在激活状态时使用填充样式
每次悬停或按键都播放进入动画	提供即时反馈，或使用 ≤150ms 的不透明度／颜色过渡

报告

独立的 UI 润色审查完成后，必须按照 review-output.md 中的格式报告所有已确认的问题，并附上验证过程和结论。在 better-interface 中，则以其规定的格式为准。