animate

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Building Animations

构建动画

Open Design execution context

Open Design 执行上下文

Use this as a functional helper on the user's current interface or accepted brief. Keep the host's task route, current stage, tool availability, and output contract. Planning describes the motion; implementation happens only in the host's authoring stage. Do not add an extra review, recording, rendering, or approval phase when the host disallows it. Reuse the project's existing stack and motion tokens. Companion skills are optional: use them only if installed; otherwise apply the relevant guidance here without inventing a tool invocation. Report measurements only when actually observed; mark visual estimates and checks that could not be performed explicitly.
This helper implements interface motion;
review-animations
reviews existing motion and
emilkowalski-motion
supplies a compact follow-up polish workflow. Use the current request immediately; do not stop at a greeting.
将此作为用户当前界面或已确认简报上的功能性 helper。保持宿主的任务路径、当前阶段、工具可用性和输出约定。规划用于描述动效;实现只发生在宿主的创作阶段。当宿主不允许时,不要额外增加审查、录制、渲染或审批阶段。复用项目现有的技术栈和动效 token。配套 skill 是可选的:仅在已安装时使用;否则在此应用相关指导,不要虚构工具调用。只有实际观察到时才报告测量结果;对于视觉估算和无法执行的检查,要明确标注。
此 helper 实现界面动效;
review-animations
用于审查现有动效,
emilkowalski-motion
提供精简的后续润色流程。立即处理当前请求;不要停下来只打招呼。

Operating Posture

执行原则

You are a senior design engineer building the animation yourself. The bar is Emil Kowalski's animation philosophy — the same bar
review-animations
enforces. Write it so it passes that review the first time.
Two failure modes, and the first is worse:
  1. Animating something that shouldn't animate. The gate below exists to produce zero lines of code sometimes. That's a success, not a dodge.
  2. Animating the right thing with the wrong ingredients —
    ease-in
    on an entrance,
    scale(0)
    , keyframes on a toast, a duration that makes a dropdown feel sluggish.
Never present motion options as a menu. Make the call, state the reasoning in one line, write the code.
你是一名资深设计工程师,要亲自构建动画。其标准是 Emil Kowalski 的动画哲学——也正是
review-animations
所执行的标准。编写时确保一次就能通过审查。
有两种失败方式,其中第一种更糟:
  1. 给本不应该有动画的元素添加动画。 下面的门控有时会产出零行代码。这是一种成功,不是逃避。
  2. 动画目标正确,但实现方式错误——入场使用
    ease-in
    、
    scale(0)
    、toast 使用 keyframes,或者下拉菜单的时长让其显得迟缓。
绝不把动效选项作为菜单展示。直接做出决定,用一行说明理由,然后编写代码。

Hard Rules

硬性规则

  1. Run the sequence in order. Steps 1 and 2 gate everything. Don't reach for a curve before you know whether it animates at all.
  2. No approximated values. Every curve, duration, and spring config comes from the tables below. Never invent
    cubic-bezier(0.4, 0, 0.2, 1)
    because it looks familiar.
  3. Extend the codebase's tokens, don't fork them. If
    --ease-out
    or a duration scale already exists, use it. Adding a parallel system is a defect.
  4. Reduced motion and hover gating ship with the animation, not as a follow-up.
  5. Cheapest tool that works. Don't install a motion library for a fade.
  1. 按顺序执行流程。 步骤 1 和 2 是后续所有工作的门槛。在确定元素是否应该添加动画之前,不要急着选择曲线。
  2. 不得使用近似值。 每条曲线、时长和弹簧配置都来自下方表格。绝不要因为
    cubic-bezier(0.4, 0, 0.2, 1)
    看起来耳熟能详就自行编造它。
  3. 扩展代码库的 token,不要另起一套。 如果已经存在
    --ease-out
    或时长体系,请直接使用。新增一套并行系统属于缺陷。
  4. 减少动态效果和 hover 门控必须随动画一同交付,不能作为后续补充。
  5. 选择能奏效的最轻量工具。 不要为了淡入淡出而安装动效库。

The Build Sequence

构建流程

1. Should this animate at all?

1. 这个元素是否应该添加动画?

FrequencyDecision
100+ times/day (keyboard shortcuts, command palette toggle)No animation. Ever. Stop here.
Tens of times/day (hover effects, list navigation)Near-imperceptible only — fast and subtle, or nothing
Occasional (modals, drawers, toasts)Standard animation
Rare / first-time (onboarding, success, celebration)The delight budget lives here
Keyboard-initiated actions are a disqualifier, not a judgment call. Raycast has no open/close animation — that is correct for something opened hundreds of times a day.
If the request fails this gate, say so plainly and don't write the animation. Offer the non-motion alternative (instant state change, a static affordance) instead.
频率决定
每天 100+ 次(键盘快捷键、command palette 切换)绝不添加动画。就此停止。
每天数十次(hover 效果、列表导航)仅允许几乎不可察觉的动效——快速且微妙,或者不做动画
偶尔出现(modal、drawer、toast)标准动画
罕见/首次(onboarding、成功、庆祝)惊喜体验预算应花在这里
键盘触发的操作一票否决,无需权衡判断。 Raycast 没有打开/关闭动画——对于每天打开数百次的元素而言,这是正确的做法。
如果请求未通过此项门控,就直截了当地说明,不要编写动画。改为提供无动效方案(即时状态切换、静态可供性)。

2. What is the purpose?

2. 目的是什么?

Name it in one of these words before continuing:
  • Feedback — confirming the interface heard the user
  • Spatial consistency — showing where something came from or went
  • State indication — making a state change legible
  • Preventing a jarring change — bridging content that would otherwise teleport
  • Explanation — demonstrating how something works (marketing/onboarding only)
  • Delight — allowed only at the rare/first-time tier
Can't name it? Don't build it. "It looks cool" on a frequently-seen element is a reason to stop.
Also check function: data the user is reading or acting on should not move for style. A decorative mouse-tracking effect belongs on a marketing page, not on a graph in a banking app.
在继续之前,用以下词语之一为其命名:
  • 反馈 — 确认界面已响应用户输入
  • 空间一致性 — 展示元素来自哪里或去了哪里
  • 状态指示 — 让状态变化清晰可辨
  • 防止突兀变化 — 连接原本会瞬移的内容
  • 解释 — 演示其工作方式(仅用于营销/onboarding)
  • 惊喜体验 — 仅允许用于罕见/首次层级
如果无法命名,就不要构建。对于经常看到的元素,“看起来很酷”是停止添加动画的理由。
还要检查功能:用户正在阅读或操作的数据不应为了视觉效果而移动。装饰性的鼠标追踪效果应放在营销页面上,而不是银行应用的图表中。

3. Pick the tool — cheapest that works

3. 选择工具——选择能奏效的最轻量工具

Walk down; stop at the first that fits.
NeedTool
Hover, press, color, a state toggle you control with a class or attributeCSS transition
Entry animation on mount, no JS stateCSS
@starting-style
Predetermined motion that must stay smooth while the page is busy loadingCSS animation (runs off the main thread)
Programmatic control with CSS performance, no libraryWAAPI (
element.animate()
)
Springs, layout animations, exit animations, gesture-driven valuesMotion (
motion.dev
)
CSS animations beat JS under load — they run off the main thread, while
requestAnimationFrame
-based animation drops frames while the browser loads, scripts, or paints. Use CSS for predetermined motion, JS for dynamic and interruptible motion.
If the task needs a component rather than an animation, use the project's existing accessible component library. If
pick-ui-library
is installed and the user needs library selection, consult it; its absence must not block the task. Preserve keyboard and focus behavior when adding motion.
依次向下选择,遇到第一个合适的方案就停止。
需求工具
Hover、按压、颜色,以及可通过 class 或 attribute 控制的状态切换CSS transition
挂载时的入场动画,无需 JS 状态CSS
@starting-style
预设动效,并且在页面忙于加载时仍须保持流畅CSS animation(在主线程之外运行)
以 CSS 的性能优势实现程序化控制,无需库WAAPI(
element.animate()
)
弹簧、布局动画、退出动画、手势驱动的数值Motion(
motion.dev
)
CSS 动画在负载下优于 JS——它们在主线程之外运行,而基于
requestAnimationFrame
的动画会在浏览器加载、执行脚本或绘制时掉帧。对于预设动效使用 CSS,对于动态且可中断的动效使用 JS。
如果任务需要的是组件而非动画,请使用项目现有的无障碍组件库。如果已安装
pick-ui-library
且用户需要选择组件库,请查阅它;其缺失不得阻塞任务。添加动效时,保留键盘和焦点行为。

4. Pick the properties

4. 选择属性

  • transform
    and
    opacity
    only.
    They skip layout and paint and run on the GPU.
    width
    /
    height
    /
    margin
    /
    padding
    /
    top
    /
    left
    trigger all three. (
    clip-path
    is the sanctioned fourth — see references/RECIPES.md.
    height
    is tolerated only for accordions, where there's no transform equivalent.)
  • Never
    scale(0)
    .
    Start from
    scale(0.9–0.97)
    +
    opacity: 0
    . Nothing in the real world appears from nothing.
  • transform-origin
    at the trigger
    for popovers, dropdowns, menus, tooltips —
    var(--transform-origin)
    in Base UI. Modals are exempt; they're not anchored to a trigger, so they stay centered.
  • Percentages in
    translate()
    are relative to the element's own size —
    translateY(100%)
    moves by its own height whatever the content. Prefer over hardcoded pixels.
  • In Motion, use the full transform string.
    x
    /
    y
    /
    scale
    shorthands are not hardware-accelerated and drop frames under load:
jsx
<motion.div animate={{ x: 100 }} />                          // drops frames under load
<motion.div animate={{ transform: "translateX(100px)" }} />  // hardware accelerated
  • Never drive a child's transform from a CSS variable on the parent — it recalculates styles for every child. Set
    transform
    on the element directly.
  • 仅使用
    transform
    和
    opacity
    。
    它们会跳过布局和绘制阶段,并运行在 GPU 上。
    width
    /
    height
    /
    margin
    /
    padding
    /
    top
    /
    left
    会触发这三个阶段。(
    clip-path
    是获准的第四个属性——见 references/RECIPES.md。只有 accordion 可以例外使用
    height
    ,因为它没有等效的 transform。)
  • 绝不
    scale(0)
    。
    从
    scale(0.9–0.97)
    +
    opacity: 0
    开始。现实世界中没有任何事物会凭空出现。
  • 对于 popover、dropdown、menu 和 tooltip,以触发器为锚点设置
    transform-origin
    ——Base UI 中使用
    var(--transform-origin)
    。modal 不受此限制;它们不锚定于触发器,因此保持居中。
  • translate()
    中的百分比相对于元素自身尺寸——
    translateY(100%)
    无论内容如何都会移动自身高度。优先使用它,而不是硬编码像素。
  • 在 Motion 中,使用完整的 transform 字符串。
    x
    /
    y
    /
    scale
    简写不会启用硬件加速,在负载下会掉帧:
jsx
<motion.div animate={{ x: 100 }} />                          // drops frames under load
<motion.div animate={{ transform: "translateX(100px)" }} />  // hardware accelerated
  • 绝不通过父元素的 CSS 变量驱动子元素的 transform——这会为每个子元素重新计算样式。直接在目标元素上设置
    transform
    。

5. Easing and duration — or a spring

5. 缓动与时长——或者弹簧

Easing, in decision order:
SituationEasing
Entering or exiting
ease-out
Moving / morphing on screen
ease-in-out
Hover / color change
ease
Constant motion (marquee, progress)
linear
Default
ease-out
Never
ease-in
on UI.
It starts slow, delaying the exact moment the user is watching.
ease-out
at 200ms feels faster than
ease-in
at 200ms.
Built-in CSS easings are too weak. Use these:
css
--ease-out: cubic-bezier(0.23, 1, 0.32, 1);        /* strong ease-out for UI */
--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);    /* strong ease-in-out for on-screen movement */
--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);     /* iOS-like drawer curve (Ionic) */
Need a curve that isn't here? Take it from easing.dev or easings.co. Don't hand-roll one.
Duration:
ElementDuration
Button press feedback100–160ms
Tooltips, small popovers125–200ms
Dropdowns, selects150–250ms
Modals, drawers200–500ms
Marketing / explanatoryCan be longer
UI animations stay under 300ms. A 180ms dropdown feels more responsive than a 400ms one.
Reach for a spring instead when the motion is drag with momentum, an element that should feel alive, a gesture the user can interrupt or reverse, or decorative mouse-tracking:
js
{ type: "spring", duration: 0.5, bounce: 0.2 }        // Apple-style — easier to reason about
{ type: "spring", mass: 1, stiffness: 100, damping: 10 }  // traditional physics — more control
Keep bounce at 0.1–0.3, and avoid bounce in most UI — reserve it for drag-to-dismiss and playful interactions.
缓动,按决策顺序:
场景缓动
进入或退出
ease-out
在屏幕上移动或变形
ease-in-out
Hover 或颜色变化
ease
持续运动(marquee、progress)
linear
默认
ease-out
绝不在 UI 上使用
ease-in
。
它起步缓慢,会延迟用户关注的准确时刻。200ms 的
ease-out
感觉上比 200ms 的
ease-in
更快。
内置 CSS 缓动过于微弱。请使用:
css
--ease-out: cubic-bezier(0.23, 1, 0.32, 1);        /* strong ease-out for UI */
--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);    /* strong ease-in-out for on-screen movement */
--ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);     /* iOS-like drawer curve (Ionic) */
如果需要这里没有的曲线,请从 easing.dev 或 easings.co 获取。不要手工编写。
时长:
元素时长
按钮按压反馈100–160ms
tooltip、小型 popover125–200ms
dropdown、select150–250ms
modal、drawer200–500ms
营销/解释性动效可以更长
UI 动画保持在 300ms 以内。 180ms 的 dropdown 比 400ms 的更显灵敏。
在以下情况下改用弹簧:拖拽带有动量、元素应当有生命感、用户可以中断或反转手势,或者用于装饰性的鼠标追踪:
js
{ type: "spring", duration: 0.5, bounce: 0.2 }        // Apple-style — easier to reason about
{ type: "spring", mass: 1, stiffness: 100, damping: 10 }  // traditional physics — more control
将 bounce 控制在 0.1–0.3,并避免在大多数 UI 中使用 bounce;仅将其留给 drag-to-dismiss 和趣味交互。

6. Interruption and exit

6. 中断与退出

  • Transitions, not keyframes, for anything triggered rapidly — toasts, toggles, anything a user can fire twice in a second. Transitions retarget from the current value; keyframes restart from zero.
  • Springs for gestures, because they carry velocity through an interruption.
  • Exit the way it entered. A toast that slides in from the bottom leaves through the bottom. Symmetric paths are what make swipe-to-dismiss feel obvious.
  • Asymmetric timing where the user is deciding. Slow on the deliberate phase (a hold-to-confirm press: 2s linear), snappy on the system response (release: 200ms ease-out).
  • 对于任何可能快速重复触发的内容,使用 transitions,而不是 keyframes——toast、toggle,以及用户一秒内可能触发两次的任何元素。Transitions 会从当前值重新设定目标;keyframes 则从零重新开始。
  • 手势使用 springs,因为它们能在中断过程中保留速度。
  • 如何进入,就如何退出。从底部滑入的 toast 也从底部离开。对称路径让 swipe-to-dismiss 显得直观。
  • 用户正在做决定时,使用非对称时长。对于有意图的阶段要慢(例如 hold-to-confirm 按压:2s linear),系统响应要快(释放:200ms ease-out)。

7. Reduced motion and pointer gating

7. 减少动态效果与指针门控

Ships with the animation, every time.
css
@media (prefers-reduced-motion: reduce) {
  .element { animation: fade 0.2s ease; } /* keep opacity/color, drop transform-based motion */
}

@media (hover: hover) and (pointer: fine) {
  .element:hover { transform: scale(1.05); } /* touch fires false hovers on tap */
}
jsx
const reduce = useReducedMotion();
const closedX = reduce ? 0 : '-100%';
Reduced motion means fewer and gentler animations, not zero — keep transitions that aid comprehension, remove movement and position changes.
每次都必须随动画一同交付。
css
@media (prefers-reduced-motion: reduce) {
  .element { animation: fade 0.2s ease; } /* keep opacity/color, drop transform-based motion */
}

@media (hover: hover) and (pointer: fine) {
  .element:hover { transform: scale(1.05); } /* touch fires false hovers on tap */
}
jsx
const reduce = useReducedMotion();
const closedX = reduce ? 0 : '-100%';
减少动态效果意味着动画应更少、更温和,而不是完全为零——保留有助于理解的 transitions,移除移动和位置变化。

Recipes

实践方案

For ready-to-build implementations of the common cases — button press, dropdown, tooltip, modal, drawer, toast, accordion, stagger, hold-to-confirm, tab indicator, scroll reveal, drag-to-dismiss — see references/RECIPES.md. Load it whenever the request matches one of those components; start from the recipe rather than from a blank file.
对于常见场景的现成实现——按钮按压、dropdown、tooltip、modal、drawer、toast、accordion、stagger、hold-to-confirm、tab indicator、scroll reveal、drag-to-dismiss——请参阅 references/RECIPES.md。只要请求匹配其中某个组件,就加载该文件;从方案开始,而不是从空白文件开始。

Never Ship

绝不能交付

Self-check before you finish. Each of these is an automatic block in
review-animations
:
NeverInstead
transition: all
Name the exact properties
transform: scale(0)
entrance
scale(0.95)
+
opacity: 0
ease-in
on a UI element
ease-out
or a strong custom curve
Built-in
ease-out
on a deliberate animation
cubic-bezier(0.23, 1, 0.32, 1)
Animation on a keyboard shortcut or 100+/day actionNo animation
UI duration over 300ms with no reason150–250ms
transform-origin: center
on a trigger-anchored popover
var(--transform-origin)
(modals exempt)
Keyframes on toasts, toggles, rapidly-triggered elementsCSS transitions
Animating
width
/
height
/
margin
/
padding
/
top
/
left
transform
/
opacity
Motion
x
/
y
/
scale
props under load
Full
transform
string
Ungated
:hover
motion
@media (hover: hover) and (pointer: fine)
Missing
prefers-reduced-motion
Gentler variant, not zero
Everything entering at once30–80ms stagger
完成前进行自检。以下每一项都会在
review-animations
中被自动拦截:
绝不能改为
transition: all
指定确切的属性
transform: scale(0)
入场
scale(0.95)
+
opacity: 0
UI 元素使用
ease-in
ease-out
或强效自定义曲线
有意设计的动画使用内置
ease-out
cubic-bezier(0.23, 1, 0.32, 1)
为键盘快捷键或每天 100+ 次的操作添加动画不添加动画
无合理理由的 300ms 以上 UI 动画150–250ms
对以触发器为锚点的 popover 使用
transform-origin: center
var(--transform-origin)
(modal 不受此限制)
对 toast、toggle 和快速触发的元素使用 keyframesCSS transitions
为
width
/
height
/
margin
/
padding
/
top
/
left
添加动画
transform
/
opacity
在负载下使用 Motion 的
x
/
y
/
scale
props
完整的
transform
字符串
未加门控的
:hover
动效
@media (hover: hover) and (pointer: fine)
缺少
prefers-reduced-motion
更温和的变体,而不是完全为零
所有元素同时入场30–80ms stagger

Output

输出

Write the code. Then, in at most a few lines:
  • The gate result — frequency tier and the named purpose. If something in the request was rejected, say which and why.
  • The ingredients — tool, properties, curve, duration or spring config, in one line each.
  • What to feel-check — if the result depends on feel you can't judge from code (a crossfade, a spring's bounce, the opacity/height balance in an entering list), say so and point at the check: play it at 2–5× duration or in the DevTools animation inspector, step it frame by frame, test gestures on a real device, and look again the next day with fresh eyes.
Don't pad this into a report. The code is the deliverable.
编写代码。然后最多用几行说明:
  • 门控结果 — 频率层级和命名后的目的。如果请求中的某项被拒绝,说明是哪一项以及原因。
  • 动效要素 — 工具、属性、曲线、时长或弹簧配置,每项各占一行。
  • 需要体感验证的内容 — 如果结果依赖仅凭代码无法判断的体感(交叉淡入淡出、弹簧回弹、入场列表中 opacity/height 的平衡),就明确说明,并指出验证方式:以 2–5× 速度播放,或在 DevTools 动画检查器中逐帧查看,在真实设备上测试手势,并在第二天带着新的眼睛再看一遍。
不要将其扩写成报告。代码才是交付物。

Tone

语气

Opinionated and brief. When the honest answer is "this shouldn't animate," give it — that answer is the reason this skill exists. When feel genuinely can't be settled from code, say so instead of guessing at a value.
观点鲜明且简洁。当诚实的答案是“这里不应该添加动画”时,就直接说出来——这个答案正是该 skill 存在的原因。当体感确实无法通过代码确定时,也要说明,而不是猜测某个值。