transitions-polish

过渡效果润色

transitions-dev 技能的一个附加组件。transitions-dev 会安装完整的过渡效果，而此技能会润色已有的动效：它会扫描五个动效令牌维度——时长、距离、缩放、模糊、缓动——并建议每个值应引用的令牌，以及更高层级的规则，说明何时适合使用某个值（打开/关闭的不对称、悬停移入/移出、交错、延迟）。

将它与 transitions-dev 一起安装，也可以单独安装——下方会再次列出令牌值，因此此技能可以独立审查项目。安装后，transitions.dev 的精修面板会自动将这些规则纳入每项小幅优化任务。

核心原则：根据用途匹配，绝不选择数值最接近的令牌

某个值不会因为相差 20ms 就“错了”。只有当它不符合动效的作用时，才算错。始终先判断用途——模态框关闭、下拉菜单打开、工具提示、徽章出现、页面滑动、文本显现、抖动——再选择用途说明与之匹配的令牌。300ms 的模态框关闭应映射到 --duration-quick（150ms），因为两者的用途都是“模态框关闭”，即使数值不同。如果某个值的用途与任何令牌用途都不匹配，就保持不变。绝不要只因为数值接近就强行替换。

五个维度

与 transitions.dev 的 Motion 令牌标签页公开的范围相同。将此技能的 _root.css 复制到项目中一次；导入后，即可使用 var(--…) 引用任意令牌。transitions-dev 中的过渡效果使用字面值，因此无需这些令牌也能正常工作——安装此技能，即可根据共享尺度对它们进行调优。

时长

令牌	值	用途
--duration-stagger	40ms	每个项目的交错偏移
--duration-micro	80ms	工具提示/路径延迟、抖动片段、大幅交错
--duration-quick	150ms	模态框/下拉菜单关闭、文本切换、工具提示出现
--duration-fast	250ms	图标切换、下拉菜单/模态框打开、标签页滑动、页面滑动
--duration-medium	350ms	面板关闭、提示框关闭
--duration-slow	400ms	面板打开、骨架屏内容显现、输入内容清除
--duration-very-slow	500ms	强调时刻、徽章出现、文本显现、成功勾选

缓动

令牌	值	用途
--ease-smooth-out	cubic-bezier(0.22, 1, 0.36, 1)	模态框/下拉菜单/面板打开与关闭、页面滑动、调整大小、位置变化
--ease-in-out	ease-in-out	图标切换、文本切换、文本显现、骨架屏显现
--ease-out	ease-out	工具提示打开/关闭
--ease-linear	linear	微光、骨架屏脉动、加载指示器
--ease-bounce	cubic-bezier(0.34, 1.36, 0.64, 1)	徽章弹出
--ease-bounce-strong	cubic-bezier(0.34, 3.85, 0.64, 1)	带弹性的悬停移出（头像返回）

--ease-smooth-out 是默认值。仅对表面动效（打开/关闭、滑动、调整大小、位置变化），将通用的 ease、ease-in 或手写的 cubic-bezier(...) / linear(...) 调整为更接近它的值。其余五种令牌缓动保持不变——它们已符合规范，各自也有明确的用途。

距离

令牌	值	用途
--distance-micro	4px	文本切换
--distance-small	6px	错误抖动（小幅片段）
--distance-base	8px	徽章对角线显现、页面滑动、错误抖动（大幅片段）
--distance-medium	12px	文本显现
--distance-large	30px	勾选徽章出现

移动距离会随频率减小，随仪式感增大：原地切换的文本几乎不移动（4px），页面滑动会移动一个清晰可见的距离（8px），而一次性的庆祝徽章可以移动 30px。除了完整的面板/抽屉外，如果平移距离大于 ~40px，通常会显得迟缓——应将其调整到接近 --distance-base。

缩放比例

令牌	值	用途
--scale-large	0.96	模态框打开 / 关闭
--scale-medium	0.97	下拉菜单打开
--scale-small	0.98	工具提示打开
--scale-tiny	0.99	下拉菜单关闭

捕获的值是界面元素动画的起始缩放比例，即非静止的“前置”缩放比例；最终总会回到 1。较大的界面元素从更远的位置开始（模态框为 0.96），小提示只做轻微缩放（0.98–0.99）。低于 ~0.9 的前置缩放比例看起来像“缩放”效果，很少适合 UI 装饰元素——请将其调整为对应用途的令牌。

模糊

令牌	值	用途
--blur-small	2px	面板显现、图标切换、文本切换、骨架屏显现、数字弹入
--blur-medium	3px	页面滑动、文本显现
--blur-large	8px	成功勾选标记打开

模糊是非静止的“前置”模糊值，最终会回到 0。用它来柔化切换或滑动效果，不要用于纯淡入淡出或颜色 / 主题变化。模糊也可能缺失，而不仅仅是未使用令牌：当用途显然需要模糊效果时（例如没有模糊效果的页面滑动），建议添加 --blur-medium。

调整规则——何时某个值合适

打开 / 关闭的不对称性

打开是一种邀请；关闭则应迅速让出空间。关闭应比打开更快、更轻柔。

• 持续时间：下拉菜单 / 模态框打开 250ms → 关闭 150ms（--duration-fast → --duration-quick）；面板打开 400ms → 关闭 350ms（--duration-slow → --duration-medium）；提示条关闭 350ms（--duration-medium）。
• **对称例外——两个方向使用相同的持续时间和缓动，切勿拆分：**页面并排切换（250ms）、标签页滑动（250ms）、手风琴（250ms）、图标切换（250ms）、文本切换（150ms）。这些效果读起来像一个可逆的连贯动作，而不是一组打开 / 关闭动作。
• **距离和模糊：**进入阶段带有距离和模糊效果；退出时可以去掉或减弱这些效果，避免关闭时内容飞过整个屏幕。
• **缓动：**大多数打开和关闭动作都使用 --ease-smooth-out。过冲曲线只适用于进入效果（徽章弹出、数字弹入）——关闭时绝不要弹跳。

悬停进入与悬停离开

• **进入：**快速直接——使用 --duration-fast 或更短的抬升动画，并搭配 --ease-smooth-out。
• **离开：**更柔和、更有弹性——返回动画可以耗时更长，并使用 --ease-bounce-strong（头像返回时使用 cubic-bezier(0.34, 3.85, 0.64, 1)），让行元素平稳归位，而非突然弹回。这是唯一一种离开效果比进入效果更复杂的情况。

错开和延迟

• 错开间隔：每个项目使用 --duration-stagger（40ms）；少量大型项目可增加至 --duration-micro（80ms）。确保错开的总时长（间隔 × 项目数）低于约 300ms，避免最后一个项目显得迟缓——对于长列表，应限制错开的项目数或缩短间隔。
• **意图延迟：**工具提示在出现前等待 --duration-micro（80ms），避免光标掠过时误触发；成功勾选标记的路径绘制也使用相同的 80ms 节拍。只有在需要过滤意外触发或对两个动作进行排序时，延迟才合适——不要用它来补偿缓慢的动画。
• 延迟与持续时间：如果动作显得迟缓，应优先缩短持续时间，而不是增加延迟。仅在错开、意图门控和刻意排序时使用延迟。
• 关闭或悬停离开时绝不要添加延迟——消失效果必须显得即时。

命令

该技能提供两个带命名空间的动词。每个命令都以 transitions 开头，因此调用时不会与同一项目中安装的其他技能的动词冲突。review 用于报告；polish 用于应用调整。

transitions review — 根据令牌审查动效

触发短语： transitions review、"review my animations"、"audit the motion"、"scan for ad-hoc transitions"、"tokenize my animations"、"where are my durations off"、"align to the motion tokens"、"make the timing consistent"。

行为：

1. 扫描整个项目 — 不仅扫描样式表，还要扫描内联 style= / CSS-in-JS、styled-components、<style> 块和 Tailwind 任意值（duration-[300ms]、[transition-timing-function:...]），检查以下五个维度：时长（…ms/…s）、缓动（cubic-bezier(...) / 关键字）、平移距离（translate*(…px)）、scale(...) 和 blur(...)。通过驱动它们的 animation 读取 @keyframes。
2. 对每个值，根据周围的选择器 / 组件名称推断动效用途（模态框关闭、下拉菜单展开、工具提示、徽章出现、页面滑动、文本显现、抖动、悬停上移等）。在上方的令牌表中查找该用途，并选择文档中用途与之匹配的令牌 — 用途优先，绝不选择数值最接近的令牌。不要建议整体替换过渡方案；那属于 transitions-dev 的 transitions apply 范畴。
3. 应用润色规则：检查打开 / 关闭是否对称、悬停进入 / 移出、交错总时长和延迟 — 不仅要检查单个值是否符合令牌。
4. 按文件分组输出编号列表，只显示应更改的值：
   • path/to/Component.css:L42 — modal close: 300ms → var(--duration-quick) (150ms) — 关闭应比 250ms 的打开更快。
   • path/to/List.css:L20 — stagger: 120ms → var(--duration-stagger) (40ms) — 8 个项目 × 120ms = 960ms 总时长，最后一个项目显得太迟。
   • 跳过用途与任何令牌都不匹配的值 — 将它们列为 no matching token usage 并保持不变。
5. 不要编辑任何内容。 结尾写上："运行 transitions polish 以应用这些更改，或确认任意一行以单独应用。"

transitions polish — 应用动效令牌优化

触发短语： transitions polish、"polish my transitions"、"refine the motion"、"tune the timing / easing"、"apply the motion tokens"、"fix the stagger"、"tokenize my animations"。

行为：

1. 如果用户在本次会话中尚未运行 transitions review，先运行相同的 transitions review 扫描（步骤 1–4）以生成更改列表。如果用户指定了文件、行或值，则将扫描范围限定在该上下文。
2. 提出简短方案：按文件分组说明将更改多少个值，并举出一个示例行。编辑前先征求确认。
3. 确认后，将令牌更改应用到源代码：
   • 如果项目已导入 _root.css（此技能的 _root.css），则将硬编码的时长 / 缓动 / 距离 / 缩放 / 模糊值替换为 var(--…) 引用；否则写入令牌的字面值，并说明导入 _root.css 后，未来只需在一处进行调整。
   • 保留文件现有的单位 / 格式（0.25s 与 250ms），除非改用 var(--…)。
   • 只修改正在润色的动效值 — 不要重新格式化，也不要进行无关编辑。
   • 处理普通 CSS、CSS Modules、styled-components/emotion、Tailwind 工具类 / 配置、内联 style 对象以及 Motion/Framer variants。
4. 如果项目中尚未包含 _root.css，则在润色前或润色时提出安装一次。
5. 保持差异精简。结尾用一行总结修改过的文件。

与 Refine 面板的关系

在项目中安装此技能后，transitions.dev Refine 面板的 Small refinement 选项卡会自动将 _refine-rules.md 中的精简规则内联到其 Agent 提示词中，因此每次点击给出的建议都会遵循这些规则，无需额外读取文件。transitions review 会在项目范围内执行同样的审查；transitions polish 会将已接受的调整写入源代码。

未来扩展

此技能自然的后续扩展方向：性能优化规范（使用 transition: all，以动画形式改变 width、top 或 box-shadow，而不是使用 transform 或 opacity，以及滥用 will-change）、检测是否缺少 prefers-reduced-motion、跨项目一致性审计（用途相同的过渡使用不同的值）、Tailwind/Framer 令牌适配器，以及“动效润色评分”报告。