better-ui

UI 润色

润色来自一系列不断叠加的小细节。本指南列出了哪些细节值得关注，以及具体取值。

审查时，放慢界面速度。以 10% 速度播放时感觉不对劲的地方，在全速播放时往往也有细微问题。

沿用项目的组件库、设计令牌和密度，并遵循其动效风格，除非以下规则规定了确切的交互方式。

以下每个时长、曲线、缩放和模糊值都是具体值，而非可近似取用的范围。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。

同心边框圆角

外层圆角 = 内层圆角 + 内边距。嵌套元素的圆角不匹配，是界面显得不协调的最常见原因。圆角、阴影和轮廓的配置方案见 surfaces.md。

优先光学校准，而非几何对齐

几何居中看起来不对时，应进行光学校准。带图标的按钮、播放三角形和不对称图标都需要手动微调。

用阴影表示层级，用边框表示结构

如果边框只是用来营造深度，优先使用多层透明 box-shadow 值。保留用于表达结构或状态的边框：分隔线、分隔符，以及选中或焦点状态。

可中断的动画

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

分段并错开进入动画

对于不常见的分阶段进入动画，如果动画顺序能够体现层级，应将内容拆分为语义区块，并以约 100ms 的间隔依次播放。为一个容器添加动画，效果不如拆分内容来得好，成本却相同。高频交互不要错开播放。参见 enter-exit.md。

轻柔的退出动画

使用小幅固定的 translateY，而不是完整高度的位移。退出动画应比进入动画更柔和。两个方向都使用 ease-out。

上下文相关的图标动画

使用 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 中，其中一个采用绝对定位，并使用 cubic-bezier(0.2, 0, 0, 1) 交叉淡化。这样无需依赖项即可实现进入和退出动画。两种方案均见 icon-transitions.md。

图像轮廓

为图像添加低透明度的 1px 轮廓，以确保深度表现一致。浅色模式下使用纯黑色（oklch(0 0 0 / 0.1)），深色模式下使用纯白色（oklch(1 0 0 / 0.1)）。不要使用类似 slate 或 zinc 的近黑色，也不要使用带色调的中性色。带色调的轮廓会融入下方表面，在图像边缘显得像污渍。

按下时缩放

点击时使用 scale(0.96)，可为按钮带来触感反馈。始终使用 0.96；低于 0.95 会显得夸张。添加 static 属性，以便在动效会造成干扰时将其关闭。参见 CSS、Tailwind 和 Motion 配置方案。

页面加载时跳过动画

在 AnimatePresence 上使用 initial={false}，以便在首次渲染时关闭进入动画。请确认这不会影响有意设计的页面进入动画。

切换主题时禁用过渡效果

切换主题会同时改变几乎所有元素的颜色、背景、边框和阴影。这些属性上的所有过渡都会同时触发，导致切换效果拖沓，而非瞬间完成。注入 *,*::before,*::after{transition:none !important}，强制重排，然后在下一帧将其移除。参见方案。

只过渡发生变化的属性

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

谨慎使用 will-change

仅用于 GPU 可以合成的 transform、opacity 和 filter。绝不要使用 will-change: all。发现首帧卡顿时再添加，不要提前添加。参见 performance.md。

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

文本旁的图标在视觉上应与文本同等粗细：常规（400）字重的文本旁使用 1.5px 描边，半粗体（600）文本旁使用 2px。每套图标只用一种描边粗细，每个界面只用一个图标库。尺寸和 RTL 翻转参见 icons.md。

一个 SVG，按状态重新着色

图标使用 currentColor，并通过 CSS 的颜色和不透明度呈现悬停、选中和禁用状态，而不是使用单独的资源。默认样式为轮廓；填充表示激活状态。

克制使用动效

对高频交互提供即时反馈，或对不透明度和颜色使用不超过 150ms 的过渡。自定义动画会在每次触发时消耗用户的注意力。

每种动画状态变化还需要静态提示：颜色、图标或标签。动效绝不能成为唯一的反馈方式。

完成前检查

问题	修复方法
图标看起来未居中	通过内边距进行视觉微调，或修复 SVG
分阶段进入或退出效果突兀	错开低频进入动画；让退出效果保持轻微
主题切换时整个页面交叉淡入淡出	切换期间禁用过渡，强制重排，并在下一帧恢复
元素上使用了 transition: all	指定具体属性
首帧动画卡顿	谨慎添加 will-change: transform
细线图标放在粗体文本旁	让描边宽度与文本字重匹配

报告

严重程度。 HIGH 表示破坏交互、导致动效无法使用，或状态变化仅在动画运行时可见。MEDIUM 表示界面、图标或动效存在明显不一致。LOW 表示局部细节问题。

验证。 无浏览器时：检查组件定义的每种状态，即悬停、焦点、激活、加载和空状态，以及代码中设置的动效时长和缓动。使用浏览器时：逐一检查每种状态，并在浏览器的 Animations 面板中以 10% 速度重放动效。将所有无法执行的检查报告为 Not verified。

格式。 按违反的原则分组，按严重程度排序；每个根本原因占一行，并列出其出现的所有位置：

严重程度	位置	修改前	修改后	原因

位置 格式为 path/to/file:line。原因需指出相关原则和对用户的影响。

只要仍有 HIGH 问题，就以 Block 结尾；否则以 Approve 结尾，并将其余工作保留在表格中。未检查的内容绝不可标记为 Approve。如果没有需要报告的问题，请说明 “No actionable UI-polish findings”，并报告验证情况。