animate

分析一项功能，并添加动效，以提升清晰度、反馈、感知性能和精致感，同时避免让界面显得迟缓、嘈杂或戏剧化。

必须完成的准备工作

用户通过 /animate 启动此工作流。此技能激活后，加载 $frontend-design — 其中包含设计原则、反模式和上下文收集协议。继续之前，请遵循该协议 — 如果尚无设计上下文，必须先加载 $setup。此外，还需收集：性能限制。 需要了解时长、缓动、编排和减少动态效果的处理方式时，请参阅 motion reference。 需要按使用场景浏览更深入的动态效果库，而不是猜测文件名时，请参阅 animate reference index。 需要了解动态效果如何强化凸起、按压、凹陷、拖动或分层的深度感时，请参阅 elevation system。 当动画决策与焦点、加载、过渡或反馈状态相关时，请参阅 interaction reference。 当动态效果会影响按钮、标签页、工具提示、提示框、切换开关、抽屉或提交操作等自定义基础组件时，请参阅 component anatomy reference。 当动态效果需要适配小屏幕、触控场景或有限的视口空间时，请参阅 responsive design reference。 在做出特定于框架的动画决策之前，请参阅 framework official docs reference。 当需求涉及 React 提示框、抽屉、文本动态效果或其他已有强大加速工具的 UI 模式时，请参阅 React shadcn accelerators reference。 请参阅 CSS、Tailwind 和 WAAPI 动态效果参考，以判断现代 CSS、Tailwind 或 WAAPI 是否能直接实现理想的动态效果，而无需使用框架动画库。 当动态效果应随滚动位置而非时间推进时，请参阅 scroll-driven animations reference。 当需要通过共享元素的连续性，在页面状态或 DOM 变更之间创建动画时，请参阅 view transitions reference。 有关这项技能受 Emil 启发的动态效果指南的来源脉络，请参阅 归属与来源。 请参阅 进入动画、退出动画、手势交互和微交互，按动态效果类型查看汇总指南。 选择动态曲线时，请参阅 默认缓出、按场景选择缓动和自定义缓动曲线。 当主要问题是时长而非缓动时，请参阅 300ms 以下的 UI、按压与释放的非对称时长、抽屉的 500ms 时长、提升感知性能和工具提示时长递进。 当动态效果模式需要更具体的指导时，请参阅 屏幕内移动的缓动、面板与抽屉的缓动和弹簧动态效果。 实现手势密集型界面时，请参阅 阻尼拖动边界、向上拖动摩擦力、可中断动画、基于动量的关闭、指针捕获、滚动与拖动冲突和感知速度的吸附点。 有关精细化和无障碍优化，请参阅 模糊桥接过渡、clip-path 标签页、尊重减少动态效果偏好、不透明度回退、减少动态效果的替代方案、Motion 的 useReducedMotion、填补悬停间隙、滚动显现阈值、子元素编排和提示框堆叠深度。 针对性能敏感的属性选择，请参阅 仅使用 transform 和 opacity、避免在拖动循环中使用 CSS 变量、不影响布局的 clip-path 显现、主线程繁忙时的硬件加速动态效果和精准使用 will-change。 有关策略性更强的动态效果决策，请参阅 即时操作反馈、交互频率、键盘操作不使用动画、营销场景例外和动画的目的。 如果问题实际上涉及变换技巧和空间感，请参阅 preserve-3d 效果、绝不从零开始缩放、感知原点的动画和百分比 translateY。 有关更细致的变换效果优化，请参阅 按钮按压缩放 0.97、缩放对其子元素的影响和 SVG 路径变形披露图标。 如果界面在频繁使用时已经显得迟滞，也加载 optimize。 如果界面需要更好地应对减少动态效果、错误、溢出、边缘情况或混合输入模式，也加载 harden。

---

致谢与灵感来源

本技能的动态效果指导部分参考了 Emil Kowalski 的 animations.dev 课程，尤其是其中对缓动选择、时机把握、适度克制、弹簧效果，以及让生产环境中的 UI「感觉恰到好处」的强调。

此外，本技能也参考了 Emil 在动画方面颇具代表性的开源作品 Sonner 和 Vaul。本库中有关 React toast 和抽屉的指导已涉及这些作品。

本仓库将这些经验改写为原创且针对本仓库的指导，而不是直接复现课程材料。

---

动态效果的应用原则

添加任何动画前，按以下顺序进行判断：

1. 先调整结构——动态效果应强化层级和状态，而不是弥补令人困惑的布局。
2. 动画必须有所作用——每个动画都应改善反馈、方向感、关联性或趣味性。
3. 优先追求速度——产品 UI 首先应让人感觉响应迅速，其次才是令人印象深刻。
4. 让动态效果可中断——用户的新意图优先于完成旧动画。
5. 匹配输入方式——鼠标、触控和键盘交互不应一概采用相同的动态效果。
6. 提前规划减少动态效果的方案——无障碍设计是系统的一部分，不是最后才做的清理工作。
7. 优先选择满足需求的最轻量实现——先用现代 CSS 和 Tailwind；需要命令式控制时机时再用 WAAPI；只有交互确实需要时才用 Motion。

动态效果可用于以下一项或多项目的：

• 反馈——确认某项操作已发生
• 方向感——帮助用户理解某个元素从何处出现或移向何处
• 关联性——展示界面、图层和控件之间的空间关系
• 趣味性——在基础体验已经完善后，增添温度或个性

如果动画无法用其中任何一项来证明其价值，就删掉它。

评估动态效果的应用机会

分析动态效果可以改善体验的地方：

1. 找出静态区域：

   • 缺少反馈：操作没有得到视觉确认（例如点击按钮、提交表单等）
   • 转场突兀：状态瞬间变化，显得生硬（例如显示/隐藏、页面加载、路由切换）
   • 关系不明确：空间或层级关系不够直观
   • 缺乏趣味性：交互虽能正常使用，却显得乏味
   • 错失引导机会：本可用于吸引注意力或解释行为的机会

2. 了解使用场景：

   • 产品的个性是什么？（活泼还是严肃、充满活力还是平和）

• 性能预算是多少？（是否优先适配紧凑布局？页面是否复杂？）
• 受众是谁？（对动态效果敏感的用户？追求速度的高级用户？）
• 什么最重要？（一个主视觉动画，还是许多微交互？）
• 哪些输入方式很重要？（鼠标、触控、键盘、手写笔）
• 哪些交互发生频率较高，应特别保持灵敏？

如果无法从代码库中明确判断以上任何一项，直接询问用户，澄清无法推断的内容。

重要：遵循 prefers-reduced-motion。始终为有需要的用户提供无动画替代方案。

动态效果应强化层级，而不是弥补层级混乱。如果只有在界面动起来后布局才变得容易理解，就应先调整布局。

规划动画策略

制定有明确目的的动画计划：

• 主角时刻：哪一个是标志性动画？（页面加载？主视觉区？关键交互？）
• 反馈层：哪些交互需要确认反馈？
• 过渡层：哪些状态变化需要平滑处理？
• 手势层：哪些拖动、滑动、吸附或关闭交互需要遵循物理逻辑？
• 惊喜层：有哪些地方可以带来惊喜和愉悦？
• 深度逻辑：哪些元素应呈现凸起、按下、拖动、凹陷或分层的感觉？
• 减少动态效果方案：哪些动画可简化为淡入淡出、模糊或即时状态变化？
• 性能预算：哪些动画因发生频繁而必须保持轻量？

重要：一个精心编排的体验胜过到处散布动画。应聚焦于影响最大的时刻。

默认动态效果规则

除非产品情境有充分理由偏离，否则在动画设计中采用以下默认指南。

1. 策略与目的

• 每个动画都必须通过反馈、方向引导、关联或愉悦感来证明其存在价值。
• 产品界面通常应给人快速、平静、精准的感觉。较慢或更具戏剧性的动态效果应留给新手引导、主角时刻、叙事或营销界面。
• 与其到处添加动态效果，不如采用一个标志性时刻，再搭配克制的微交互。
• 不要仅仅因为指针交互带有动画，就为键盘触发的操作添加动画。键盘用户通常希望状态变化可预测且延迟极低。
• 交互发生得越频繁，通常越不需要动态效果。高频控件应给人近乎即时的感觉。
• 立即确认用户输入。只要可能，微交互应在约 80ms 内提供可见反馈。
• 如果实际处理可能超过约 400ms，应立即通过乐观 UI、骨架屏、进度提示或明确的加载反馈作出响应，而不是让界面陷入无响应状态。
• 切勿用动态效果掩盖加载缓慢、层级薄弱或状态设计缺失。

2. 缓动默认值

• 进入、显现和大多数反馈过渡默认使用 ease-out。
• 使用自定义 cubic-bezier 曲线，而不是通用的 CSS ease 默认值。
• 对可逆且在屏幕内往返的状态变化使用 ease-in-out。
• 当移动应与手势输入或物体行为呈现物理关联时，使用弹簧动态效果。
• 对于抽屉、底部面板及类似界面，可从面板风格曲线 cubic-bezier(0.32, 0.72, 0, 1) 开始调整。
• 精致的 UI 动态效果优先采用指数式减速曲线，例如 ease-out-quart、ease-out-quint 或 ease-out-expo。
• 除非产品有意采用玩具般或俏皮的物理隐喻，否则避免使用弹跳和弹性曲线。这些曲线通常会显得过时、杂乱或刻意。
• 根据情境匹配缓动方式：
  • 界面进入 → ease-out
  • 界面退出 → 时长更短，通常使用 ease-in 或更利落的退出曲线
  • 状态切换／可逆移动 → ease-in-out
  • 与手势联动的移动 → 弹簧效果或感知速度的插值

3. 时长与持续时间

• 大多数重复出现的 UI 动效应控制在 300ms 以内。
• 按压状态、开关切换、颜色变化和即时确认应使用 100-150ms。
• 悬停、菜单、工具提示和小范围显示等常规 UI 状态变化应使用 200-300ms。
• 抽屉、模态框、手风琴和大面积界面变化等较大的布局过渡应使用 300-500ms。
• 将 500ms 视为较大界面动效（如面板或分阶段入场）的特殊情况上限，而非常规控件的默认时长。
• 退出动画应比入场动画更快。一个不错的默认值是入场时长的 75% 左右。
• 按下动作应比释放动作更快。按下时的反馈应即时，而复位过程可以稍微柔和一些。
• 必要时，延迟首次显示工具提示或悬停后出现的辅助信息；但后续相关内容应更快显示，甚至即时显示，避免界面反应迟钝。
• 过长的交错动画链是个危险信号。应限制交错动画的总时长，避免最后一项迟迟才出现。

4. 属性选择与性能

• 优先对 transform 和 opacity 添加动画。
• 除非有充分理由且涉及的界面范围较小，否则应避免对 width、height、top、left、padding、margin、border-width 等布局开销较大的属性添加动画。
• 对于手风琴式的高度过渡，在可行时优先使用 grid-template-rows 或同类的布局友好模式，而非直接对 height 添加动画。
• 需要无需布局的显示效果时，可使用 clip-path、蒙版或合成图层显示效果。
• 主线程繁忙或组件频繁播放动画时，应使用对硬件友好的变换。
• 谨慎使用 will-change，仅在动画即将开始或已确认确实需要时使用。
• 在拖动循环中，如果某些动画方案会导致每一帧都经过开销较大的 CSS 变量或布局重算流程并引入延迟，就应避免使用这些方案。
• 对滚动触发的动效优先使用 Intersection Observer；如果动效只需播放一次，完成后应停止观察。

5. 变换与缩放技巧

• 按钮或标签按压反馈可从 scale(0.97) 开始尝试，这是一个不错的默认值。
• 入场动画绝不要从 scale(0) 开始。应从更接近 scale(0.95) 或更大的值开始，让元素保持可信的质感。
• 当移动距离应随元素或视口尺寸变化时，使用百分比形式的 translate 值。
• 动效应以变换原点为参考：
  • 菜单和工具提示应从触发器所在的边缘展开
  • 抽屉和面板应从其固定的一侧滑入
  • 卡片抬升时应感觉像是从当前平面升起
• 请记住，缩放会影响子元素。如果缩放幅度过大，文字和图标可能会显得模糊或变形。
• 仅在 3D 变换能提升空间理解或显著增加趣味性时才使用。不要只因为 preserve-3d 单独看起来炫酷就贸然使用。

6. 手势与交互模式

• 让交互动画可以中断。用户表达新的操作意图时，不应被迫等待动画播放完毕。
• 对于滑动关闭、面板吸附等类似手势，应结合距离和速度，而不是只考虑距离。
• 在边界附近增加摩擦或阻尼，让拖动受到阻力，而不是突然停止。
• 有意处理滚动与拖动的冲突。嵌套界面不应让人感觉输入操作在相互争夺。
• 实现拖动交互时，应使用可靠的指针处理机制，例如指针捕获或同类的手势控制机制。
• 通过阴影、轻微缩放或提升图层等深度提示，让被拖动的元素在视觉上抬起。
• 如果界面可以被拖过静止位置，应提供可控的阻力，而不是让手势感觉被突然挡住。
• 吸附点应考虑速度并经过有意设计，而不应像随意设置的隐形墙。

7. 无障碍与润色

• 始终遵循 prefers-reduced-motion。
• 减少动态效果通常应意味着简化动态效果，而不是取消所有反馈。尽可能用透明度、模糊、高亮或更短的过渡替代大幅空间移动。
• 保留功能提示，例如焦点状态、进度、加载反馈以及成功或错误确认。
• 当直接切换显得生硬时，谨慎使用模糊效果来衔接视觉状态。
• 有目的地使用交错动画来组织流程，而不是将其当作装饰。短列表可以受益；超长列表通常不适合。
• 滚动显现动画应在用户尚未完全滚过元素时触发，但也不要过早，以免效果脱离滚动语境。
• 填补触发区域与浮动界面之间的悬停空隙，避免用户移动指针时工具提示、菜单和弹出框意外关闭。
• Toast 堆叠可以利用偏移、缩放和透明度营造纵深感，同时避免显得杂乱。
• 在紧凑布局和支持触控的场景中，也要像在宽屏布局中一样尊重用户对动态效果的敏感度。手势驱动的移动效果如果过度，尤其容易令人不适。

实现动画

在以下类别中系统地添加动态效果：

入场动画

• 页面加载编排：仅在有助于理解时使用交错动画；控制整体编排时长
• 主视觉区域：如果符合产品调性，为核心内容设计独特的入场效果
• 内容显现：使用交叉观察器触发滚动动画
• 模态框/抽屉入场：平滑滑入并淡入，背景遮罩淡入，管理焦点

微交互

• 按钮反馈：
  • 悬停：仅在有助于增强可操作性的情况下，轻微缩放、改变颜色或阴影
  • 点击/按下：快速缩小再放大、呈现按压感，或改变纵深
  • 加载：显示旋转指示器或脉冲状态
• 表单交互：
  • 输入框聚焦：过渡边框、背景或高度，以清晰表明焦点，同时避免分散注意力
  • 验证：优先通过清晰的颜色、图标或文本状态变化来提示，再考虑装饰性动画
• 切换开关：平滑滑动并过渡颜色
• 复选框/单选框：清晰地改变状态，并控制好动画时长
• 点赞/收藏：仅在符合产品调性的情况下，添加轻微缩放或图标动画

状态过渡

• 显示/隐藏：淡入淡出并滑动（而非瞬间切换），时长适宜（200-300ms）
• 展开/折叠：使用适应布局的展开/关闭过渡，并处理溢出；必要时旋转图标
• 加载状态：骨架屏淡入淡出、旋转指示器动画、进度条
• 成功/错误：颜色过渡、图标动画、轻柔的缩放脉冲
• 启用/禁用：透明度过渡、光标变化

导航与流程

• 页面过渡：在路由之间交叉淡化；仅在确实能清晰呈现连续性时使用共享元素过渡
• 标签页切换：使用滑动指示器、内容淡入淡出、裁剪路径或其他快速方向提示
• 轮播/滑块：使用平滑变换、吸附点、惯性，以及可中断的输入
• 滚动效果：视差图层、随状态变化的粘性页眉、滚动进度指示器

反馈与引导

• 悬停提示：工具提示淡入、光标变化、元素高亮
• 拖放：抬升效果（阴影 + 缩放）、放置区域高亮、平滑重新定位——拖动时，项目应有沿 z 轴向前弹出的感觉
• 复制/粘贴：粘贴时短暂闪烁高亮，并确认“已复制”
• 焦点流：沿表单或工作流突出显示焦点路径

深度与高度动态效果

• 抬升的元素应给人向用户靠近的感觉
• 按下的元素应给人向内或向下移动的感觉
• 结合使用阴影和移动来传达状态，而不只是装饰
• 动态效果的强调程度应符合颜色和排版所采用的层级逻辑

惊喜时刻

• 空状态：插图上带有微妙的浮动动画
• 操作完成：彩纸飞舞、勾号动画、成功庆祝效果
• 彩蛋：等待用户发现的隐藏交互
• 情境动画：天气效果、昼夜主题、季节元素

技术实现

针对每种动画使用恰当的技术：

时长与缓动

按用途设置时长：

• 100-150ms：即时反馈（按钮按下、切换）
• 200-300ms：状态变化（悬停、菜单打开）
• 300-500ms：布局变化（手风琴面板、模态框、抽屉）
• 默认最长 500ms：确实需要较长时长的大面积过渡

缓动曲线（请使用这些曲线，而非 CSS 默认值）：

/* Recommended - natural deceleration */
--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1);    /* Smooth, refined */
--ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1);   /* Slightly snappier */
--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1);     /* Confident, decisive */
--ease-in-out-standard: cubic-bezier(0.65, 0, 0.35, 1); /* Reversible movement */
--ease-sheet-standard: cubic-bezier(0.32, 0.72, 0, 1);   /* Sheets / drawers */

/* AVOID - feel dated and tacky */
/* bounce: cubic-bezier(0.34, 1.56, 0.64, 1); */
/* elastic: cubic-bezier(0.68, -0.6, 0.32, 1.6); */

**退出动画应比进入动画更快。**时长约为进入动画的 75%。

CSS 动画

/* Prefer for simple, declarative animations */
- transitions for state changes
- @keyframes for complex sequences
- transform + opacity first (GPU-friendly)
- Tailwind utilities when the project already uses Tailwind

JavaScript 动画

/* Use for complex, interactive animations */
- Web Animations API for programmatic control
- Framer Motion / Motion for React
- GSAP for complex sequences

默认规则：如果悬停、按下、显示或减少动态效果的回退方案可以通过现代 CSS 或 Tailwind 工具类简洁实现，就优先采用这种方式，再考虑使用 Motion。

性能

• GPU 加速：使用 transform 和 opacity，避免使用布局属性
• will-change：仅对已知开销较大的动画谨慎添加
• 减少绘制：尽量减少重绘，并在适当情况下使用 contain
• 监控 FPS：确保目标设备达到 60fps
• 交互优先：即使在性能较弱的设备上，频繁的产品交互也应保持响应迅速

无障碍

@media (prefers-reduced-motion: reduce) {
  * {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

与其删除所有形式的反馈，不如将大幅移动替换为短暂淡入淡出、突出显示、模糊过渡或即时状态变化。

实用默认值

将这些值作为起点，再根据具体情境调整：

值	适用的默认场景
scale(0.97)	按钮和标签按下反馈
scale(0.95)	最小且可信的进入缩放比例
200ms	标准 UI 过渡
300ms	常见 UI 动效的柔性上限
500ms	大型底部面板 / 抽屉过渡的上限
cubic-bezier(0.32, 0.72, 0, 1)	抽屉 / 底部面板缓动
10-16px	Toast 堆叠偏移的起始范围
距视口边缘约 100px	滚动显示触发位置的起始值

切勿：

• 默认使用弹跳或弹性缓动曲线——它们会让动画本身过于引人注目
• 在使用 transform 或 opacity 就能实现效果时，仍对宽度、高度、顶部或左侧等布局属性进行动画处理
• 为常规反馈使用过长的时长——很快就会让人觉得迟缓
• 在没有目的的情况下添加动画——每个动画都需要有其理由
• 忽略 prefers-reduced-motion——这会违反无障碍要求
• 为所有内容添加动画——动画疲劳会让界面令人厌倦
• 强迫用户等待动画结束后才能继续操作
• 用动效掩盖薄弱的结构、不清晰的层级或缓慢的数据获取
• 发布忽略惯性、阻尼或滚动冲突的手势逻辑

验证质量

彻底测试动画：

• 流畅达到 60fps：目标设备上没有卡顿
• 感觉自然：缓动曲线自然流畅，而非机械生硬
• 时长恰当：既不会太快（令人突兀），也不会太慢（感觉迟缓）
• 即时确认：输入后应迅速得到可见响应
• 必要时可中断：新的意图可以覆盖旧的动效
• 手势质量：拖动、滑动、吸附和关闭交互感觉符合物理规律
• 减少动态效果可用：动画应根据需要禁用或简化
• 不造成阻碍：用户可在动画期间或结束后进行交互
• 带来价值：让界面更清晰或更令人愉悦

请记住：最好的 UI 动画通常让人觉得顺理成章，而非刻意吸引注意。让动画各有目的，针对响应速度进行调优，尊重无障碍需求，并让动效服务于产品，而不是喧宾夺主。