motion-spec

动效规格

设计师可以指着一个片段说：“就像这样。”开发者则需要数字、顺序和边界情况。 你的任务是把一段 60fps 镜头转化为可供开发者直接实现的规格，无需猜测，并如实说明哪些数字是测量所得，哪些是判断。

1. 找到镜头

如果用户提供了 60fps 链接或 slug，就使用它。如果用户只是描述了镜头，就调用 60fps_search_shots。只要排名第一的结果摘要明显符合用户的需求，就直接使用。如果不符合，或者前几个结果很接近、但差异会影响实现，再停下来询问：列出排名前三的结果，并各用一行说明区别。

如果镜头包含多个交互（打开、选择、确认、之后出现提示），询问用户要为哪个交互编写规格，或将每个交互分别列为一个编号部分。

每次拆解和代码调用都会计入用户的每日额度，因此不要获取仅用于比较的镜头详情。

2. 阅读镜头

调用 60fps_get_motion_breakdown，了解触发条件、开始状态、过渡状态和结束状态、动效有效的原因、时长描述（慢、中、快）、缓动、弹性、错开时序以及关键帧图像。查看关键帧：它们展示事件顺序和大致尺寸，也可用于核对代码。

调用 60fps_get_motion_code 获取数字，并检查其 source：

• generated：generated 字段是经过编译检查的该镜头复现代码。从中提取所有测量所得的数字。忽略响应中的 animation、recipes 和 stagger_delay 字段：这些是通用初始值，与实际时序不符。
• recipes：这不是该镜头的复现代码，因此无法测量任何数据。响应中的 animation 和 stagger_delay 是工具根据拆解中的时长描述给出的通用解读。可以使用，但只能作为 Recommendations 下的建议。

阅读时序代码行：withAnimation 和 .animation 的值、弹簧参数、延迟和休眠时长、phaseAnimator 或 keyframeAnimator 的轨道、触觉反馈调用，以及对 Reduce Motion 和中断的处理。只有视图实际读取的值才是真实有效的：无人使用的关键帧轨道或状态变量不会产生动画，因此应从规格中省略，并列在 Code caveats 下。检查每行代码是否确实实现了注释所说的效果。

该文件是用于演示镜头的自运行示例，并非生产代码。省略演示本身才需要的内容：循环、自动重播、重置阶段、固定演示延迟、示例数据以及组件外围的屏幕。代码中的数字是根据真实应用视频由 AI 复现所得的近似参考值，并非应用本身的源代码。

3. 撰写规格说明

如果来源是 recipes，规格说明的第一行应使用粗体，并写明：无法复现此镜头。本规格中的所有数值都是建议值，并非测量结果。

然后按以下顺序列出各节。测量类章节只记录代码或关键帧中呈现的内容。所有判断都归入“建议”章节；如果参考内容未涵盖某个测量类章节，则写明“参考内容中未提及，请参阅建议”。两者绝不混写。

• 内容概述：用一句话说明，并附上镜头链接。
• 触发条件：说明准确的手势或事件，以及判定条件（例如，抬手时轻点、按住 N 秒、拖动超过 N 个点）。说明 t = 0 的定义。触发前发生的动作，例如手指按下期间的变化，列为“按住期间”。
• 状态：说明起始和结束状态，包括布局和值（尺寸、不透明度、位置、颜色角色），而非原应用使用的颜色或文字。
• 序列：按编号列出各个节拍。每个节拍都应说明变化内容、变化的起点和终点、开始时间、持续时长，以及代码中写明的曲线或弹簧（例如 .spring(response: 0.22, dampingFraction: 0.65)）。如果多个节拍通过弹簧衔接（如 phaseAnimator、完成处理程序），开始时间就不是固定的：请给出大致时间偏移，说明原因；如果需要精确时间，建议使用 keyframeAnimator。对于 recipes 镜头，只需说明顺序。
• 触觉反馈：说明反馈类型及其对应节拍。
• 中断处理：说明如果用户在动画中途再次轻点、提前抬手、取消拖动或离开屏幕，代码会如何处理。
• 减少动态效果：说明代码仍会改变什么，以及停止了哪些动态效果。
• 构建说明：说明适用于各个节拍的 SwiftUI API（例如 matchedGeometryEffect、.contentTransition(.numericText())、keyframeAnimator），以及实现该动效所需的最低 iOS 版本，不包括无关演示代码强制要求的版本。如果将弹簧转换为其他形式，请注明是近似值（持续时间约等于响应时间，回弹程度约等于 1 减去阻尼系数）。
• 代码注意事项：说明没有被读取的值、开发者不应照搬的演示代码捷径（例如，用固定延迟代替真实加载、内容在淡出前就已替换），以及代码中与自身注释或关键帧不一致的地方。
• 建议：列出所有主观判断，包括代码未实现的触觉反馈、中断处理或减少动态效果行为、为 recipes 镜头建议的时长，以及无障碍信息（每种状态下 VoiceOver 应读出的标签和值）。代码通常不会涵盖这些内容。

如果附带了用户的项目，且项目中包含设计系统或 Motion 文件，请将每个值映射到最接近的设计令牌，并说明差异。否则跳过此项。

4. 保持诚实、简洁

不要将原应用的品牌、文字、颜色或资源复制到规格说明中。规格说明的对象是动效。请用颜色角色来描述颜色（例如，柔和的中性色、一种暖色强调色）。对于标签，请说明文字要表达的功能（例如，“要求按住的动词”“过去时的确认语”），不要编写开发者可能直接发布的新文案。镜头链接和用户自己的表述可以保留。

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

使用简洁明了的语言和常见词语。不得使用 em dash 或 en dash。

不适用范围

不适用于 Android、Flutter、React Native 或 Web，除非用户只需要时长；此时应说明参考内容针对 iOS，数值可能需要调整。