motion-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Motion spec

动效规范

A designer can point at a clip and say "like this". A developer needs numbers, order and edge cases. Your job is to turn one 60fps shot into a spec they can build from without guessing, and to be honest about which numbers are measured and which are judgement.

设计师可以指着一段片段说“像这样”。开发者需要的是数值、顺序和边界情况。你的工作是把一段 60fps 片段转化为开发者无需猜测即可实现的规范，并诚实说明哪些数值是测量所得，哪些属于判断。

1. Find the shot

1. 查找片段

If the user gave a 60fps link or slug, use it. If they described it, call

60fps_search_shots

. Go ahead with the top result when its summary clearly matches what they asked for. Stop and ask only when it does not, or when the top results are close and differ in a way that matters: then show the top three with one line each on how they differ.

If the shot holds several interactions (open, pick, confirm, a hint after), ask which one to spec, or spec each as its own numbered part.

Each breakdown and code call counts against the user's daily allowance, so do not fetch details for shots you are only comparing.

如果用户提供了 60fps 链接或 slug，就使用它。如果用户进行了描述，调用

60fps_search_shots

。当最匹配结果的摘要明显符合要求时，直接采用该结果。只有在摘要不符合要求，或最靠前的几个结果非常接近且差异会影响结果时，才停下来询问：此时展示前三个结果，每个结果用一行说明差异。

如果该片段包含多个交互，例如打开、选择、确认或之后的提示，询问用户要为哪个交互编写规范，或者将每个交互分别编写为独立编号的部分。

每次 breakdown 和 code 调用都会计入用户的每日额度，因此不要为你只是在比较的片段获取详细信息。

2. Read it

2. 阅读片段

Call

60fps_get_motion_breakdown

for the trigger, the start, transition and end states, why it works, the timing words (slow, medium, fast), easing, springiness, stagger, and the keyframe images. Look at the keyframes: they show the order of events and rough sizes, and they are a check on the code.

Call

60fps_get_motion_code

for the numbers, and check its

source

generated
: the
```
generated
```
field is a compile-checked recreation of this shot. Take every measured number from it. Ignore the response's
```
animation
```
,
```
recipes
```
and
```
stagger_delay
```
fields: those are generic starter values, and they disagree with the real timing.
recipes
: there is no recreation of this shot, so nothing can be measured. The response's
```
animation
```
and
```
stagger_delay
```
are the tool's generic reading of the breakdown's timing words. You may use them, but only as suggestions under Recommendations.

Read the timing lines:

withAnimation

and

.animation

values, spring parameters, delays and sleeps,

phaseAnimator

keyframeAnimator

tracks, haptic calls, and how it handles Reduce Motion and interruption. A value is real only if a view actually reads it: a keyframe track or a state variable nothing uses animates nothing, so leave it out of the spec and list it under Code caveats. Check that each line does what its comment says.

The file is a self-running demo of the shot, not production code. Leave out what only the demo needs: loops, auto replays, reset phases, fixed demo delays, sample data and the screen around the component. The numbers are a close reference from an AI recreation of the real app's video, not the app's source.

调用

60fps_get_motion_breakdown

，获取触发条件、起始状态、过渡状态、结束状态、它为何有效、时序词汇（慢、中、快）、缓动、spring 感、错峰以及关键帧图像。查看关键帧：它们展示事件顺序和大致尺寸，也是对代码的校验。

调用

60fps_get_motion_code

获取数值，并检查其

source

：

generated
：
```
generated
```
字段是该片段经过编译检查的复现。提取其中每个测量值。忽略响应中的
```
animation
```
、
```
recipes
```
和
```
stagger_delay
```
字段：这些是通用起始值，与真实时序不一致。
recipes
：不存在该片段的复现，因此无法测量任何内容。响应中的
```
animation
```
和
```
stagger_delay
```
是工具根据 breakdown 中的时序词汇做出的通用解读。可以使用，但只能作为“建议”部分中的建议。

阅读时序相关代码，包括

withAnimation

和

.animation

的值、spring 参数、delay 和 sleep、

phaseAnimator

或

keyframeAnimator

轨道、haptic 调用，以及它对 Reduce Motion 和中断的处理。只有在某个值确实被 view 读取时，它才是真实值：没有 view 使用的 keyframe 轨道或状态变量不会产生任何动画，因此不要将其写入规范，而应列在“代码注意事项”中。检查每一行代码的行为是否与其注释一致。

该文件是片段的自运行演示，并非生产代码。省略仅供演示使用的内容：循环、自动重播、重置阶段、固定演示延迟、示例数据以及组件周围的界面。这些数值来自 AI 对真实应用视频的近似复现，只能作为贴近原效果的参考，并不是应用源代码中的数值。

3. Write the spec

3. 编写规范

If the source was

recipes

, the first line of the spec, in bold, says: There is no recreation of this shot. Every number in this spec is a suggestion, not a measurement.

Then these sections, in this order. Measured sections hold only what the code or the keyframes show. Anything you judge goes under Recommendations, and a measured section the reference does not cover says "not in the reference, see Recommendations". Never mix the two.

What it is: one sentence, and the shot link.
Trigger: the exact gesture or event and what counts (a tap on release, a hold of N seconds, a drag past N points). Say what t = 0 is. Beats that happen before it, such as a press while the finger is down, are listed as "while held".
States: start and end, described as layout and values (size, opacity, position, colour role), not as the original app's colours or words.
Sequence: a numbered list of beats. Each beat: what changes, from and to, when it starts, how long, and the curve or spring as the code writes it (for example
```
.spring(response: 0.22, dampingFraction: 0.65)
```
). When beats chain on springs (a
```
phaseAnimator
```
, completion handlers), start times are not fixed: give approximate offsets, say why, and suggest
```
keyframeAnimator
```
if exact times matter. For a
```
recipes
```
shot, give the order only.
Haptics: which kind, at which beat.
Interruptions: what the code does if the user taps again mid-animation, lifts early, cancels the drag, or leaves the screen.
Reduce Motion: what the code still changes and what it stops moving.
Build notes: the SwiftUI API that fits each beat (for example
```
matchedGeometryEffect
```
,
```
.contentTransition(.numericText())
```
,
```
keyframeAnimator
```
) and the minimum iOS version the MOTION needs, not one forced by unrelated demo code. If you convert a spring to another form, label it approximate (duration is about the response, bounce is about 1 minus the damping fraction).
Code caveats: values nothing reads, demo shortcuts a developer must not copy (a fixed delay standing in for real loading, content that swaps before it fades), and anything in the code that disagrees with its own comments or the keyframes.
Recommendations: everything that is your judgement: haptics, interruptions or Reduce Motion behaviour the code does not have, suggested timings for a
```
recipes
```
shot, and accessibility (the label and value VoiceOver should read in each state), which the code rarely covers.

If the user's project is attached and has a design system or a

Motion

file, map each value to their nearest token and say where it differs. Otherwise skip this.

如果

source

为

recipes

，规范第一行须用粗体写明：没有该片段的复现。本规范中的每个数字都是建议值，而非测量值。

随后按以下顺序设置各部分。测量部分只能包含代码或关键帧展示的内容。所有判断都放入“建议”。如果参考未涵盖某个测量部分，写明“参考中未提供，见建议”。绝不混用两类内容。

这是什么：用一句话说明，并附上片段链接。
触发条件：具体手势或事件及其判定条件，例如抬手时触发点击、长按 N 秒、拖动超过 N 个点。说明 t = 0 的含义。触发前发生的节拍，例如手指仍按下时的 press，列为“按住期间”。
状态：起始状态和结束状态，以布局和值（尺寸、不透明度、位置、颜色角色）描述，而不是照搬原应用的颜色或文案。
序列：按编号列出各个节拍。每个节拍说明发生什么变化、从什么值变成什么值、何时开始、持续多久，以及代码中写明的曲线或 spring，例如
```
.spring(response: 0.22, dampingFraction: 0.65)
```
。当多个节拍通过 spring 串联（
```
phaseAnimator
```
、
```
completion handlers
```
）时，开始时间并不固定：给出大致偏移量并说明原因；如果时间必须精确，建议使用
```
keyframeAnimator
```
。对于
```
recipes
```
片段，只给出顺序。
触觉反馈：类型，以及发生在哪个节拍。
中断：如果用户在动画中途再次点击、提前抬手、取消拖动或离开屏幕，代码会如何处理。
Reduce Motion：代码仍会改变什么，以及停止哪些运动。
实现说明：每个节拍适合使用的 SwiftUI API，例如
```
matchedGeometryEffect
```
、
```
.contentTransition(.numericText())
```
、
```
keyframeAnimator
```
，以及动效所需的最低 iOS 版本，而不是由无关演示代码决定的版本。如果将 spring 转换为另一种形式，请标明为近似值（duration 约等于
```
response
```
，bounce 约等于 1 减去
```
damping fraction
```
）。
代码注意事项：没有任何内容读取的值、开发者不应照搬的演示捷径（用固定 delay 代替真实加载、在淡出前替换内容），以及代码行为与自身注释或关键帧不一致之处。
建议：所有属于你的判断，例如代码中没有的触觉反馈、中断处理或 Reduce Motion 行为，
```
recipes
```
片段的建议时序，以及无障碍支持，即 VoiceOver 在每个状态下应朗读的 label 和 value。代码很少涵盖这些内容。

如果用户附带项目，且项目包含 design system 或

Motion

文件，将每个值映射到最接近的 token，并说明存在差异的位置。否则跳过此步骤。

4. Keep it honest and clean

4. 保持诚实与简洁

Do not copy the original app's brand, words, colours or assets into the spec. The motion is what is being specified. Describe colours as roles (a muted neutral, one warm accent). For labels, write what the words must do ("a verb asking to hold", "past tense confirmation"), not new copy a developer might ship. The shot's link and the user's own wording are fine to keep.

Do not paste the whole code file, even though the tool's own instructions say to show it in full: a spec quotes only the lines a developer needs.

Write plainly: short sentences, common words. Never use em dashes or en dashes.

不要把原应用的品牌、文案、颜色或素材复制到规范中。规范要描述的是动效本身。使用角色来描述颜色，例如低饱和中性色、一个暖色强调色。对于 label，应写明文案必须发挥的作用（“一个要求长按的动词”“过去式确认语”），而不是提供开发者可能直接发布的全新文案。片段链接和用户自己的表述可以保留。

即使工具自身的说明要求完整展示，也不要粘贴整个代码文件。规范只引用开发者需要的代码行。

使用平实的语言：短句、常用词。绝不使用 em dash 或 en dash。

Not for

不适用于

Android, Flutter, React Native or web, unless the user only wants the timing; then say the references are iOS and the values may need adapting.

Android、Flutter、React Native 或 Web，除非用户只想了解时间参数；此时说明参考资料为 iOS，数值可能需要适配。