ios-animations

dot-skills — Airbnb iOS SwiftUI 动画最佳实践

面向 SwiftUI iOS 26 / Swift 6.2 应用的严格动画制作指南，带有明确主张。包含 8 个类别中的 50 条规则，并按影响排序。内容源自 Airbnb Engineering 的动效模式、Apple WWDC 专题和 Apple Human Interface Guidelines。规定每个动画视图都必须使用 @Equatable，所有弹簧和时长值都必须使用动效令牌，布局则必须使用设计系统令牌。

强制架构约定

此技能旨在与 swift-ui-architect 和 ios-design-system 配合使用。所有代码示例都遵循以下不可妥协的约束：

• 每个视图都使用 @Equatable 宏（Airbnb 测得滚动卡顿减少了 15%）
• 对涉及业务逻辑触发条件的复杂动画状态使用 @Observable
• 对视图拥有的动画状态（切换布尔值、拖动偏移量）使用 @State
• 设计系统令牌：Spacing.xs/sm/md/lg、Radius.sm/md/lg —— 不使用硬编码布局数值
• 动效令牌：Motion.standard/responsive/playful —— 不零散使用弹簧字面值
• 语义颜色：.backgroundSurface、.accentPrimary —— 视图中不使用原始 Color 字面值
• 功能动画仅负责呈现；数据和网络相关工作留在 Data 包中

范围与同级技能的关系

此技能负责动效层——教你如何构建流畅、高性能的动画。与同级技能一起加载时：

同级技能	其关注点	此技能的关注点
swift-ui-architect	架构（模块化 MVVM-C、路由外壳、协议边界）	动画架构（动效令牌、弹簧选择、编排）
ios-design-system	设计系统基础设施（令牌、样式、治理）	动效令牌和动画组件模式
ios-hig	HIG 合规模式	动效相关的 HIG（减少动态效果、空间连续性）

不在范围内： 设计师创作的矢量动画（After Effects 导出内容请使用 Lottie）。复杂的 UIKit 转场控制器（参见 Airbnb 的声明式转场框架）。此技能仅涵盖以编程方式实现的 SwiftUI 动画。

Clinic 架构约定（iOS 26 / Swift 6.2）

此技能中的所有指导都基于 Clinic 模块化 MVVM-C 架构：

• 功能模块仅导入 Domain + DesignSystem（绝不导入 Data 或同级功能模块）
• App 目标是汇合点，并负责 DependencyContainer、具体协调器和 Route Shell 的连接
• Domain 保持纯 Swift，定义模型以及 repository、*Coordinating、ErrorRouting 和 AppError 契约
• Data 负责 SwiftData/网络/同步/重试/后台 I/O，并实现 Domain 协议
• 读写流程默认采用 stale-while-revalidate 读取和乐观排队写入
• ViewModel 直接调用 repository 协议（不设默认的用例/交互器层）

何时应用

在以下情况下参考这些准则：

• 为 SwiftUI 视图或转场添加动画
• 构建手势驱动的交互（拖动、滑动、平移）
• 通过空间转场连接视图（展开/折叠、导航变形）
• 设计微交互（按钮按下、切换、加载状态）
• 让内容变化呈现出真实的物理效果（数字滚动、符号替换）
• 编排多元素动画序列（KeyframeAnimator、PhaseAnimator）
• 为设计系统定义动效令牌
• 审查动画代码的性能、无障碍性和架构合规性

按优先级划分的规则类别

优先级	类别	影响	前缀	规则
1	弹簧物理	CRITICAL	spring-	8
2	时长与体验	CRITICAL	feel-	6
3	手势连续性	HIGH	gesture-	7
4	空间转场	HIGH	spatial-	6
5	微交互	HIGH	micro-	6
6	编排	HIGH	orch-	5
7	工艺与润色	HIGH	craft-	5
8	内容动效	MEDIUM-HIGH	content-	5

快速参考

1. 弹簧物理（CRITICAL）

• spring-motion-tokens — 将动效令牌定义为无关联值枚举，涵盖所有弹簧预设
• spring-smooth-default — 所有 UI 转场默认使用 .smooth 弹簧
• spring-snappy-responsive — 响应式交互使用 .snappy 弹簧
• spring-bouncy-celebration — 在活泼、庆祝的时刻使用 .bouncy 弹簧
• spring-custom-parameters — 使用 response 和 dampingFraction 调整自定义弹簧
• spring-velocity-preservation — 弹簧在动画被打断时保留速度
• spring-never-linear — 交互式 UI 中绝不使用 linear 或 easeInOut
• spring-completion-chaining — 使用 withAnimation completion 串联动画序列

2. 时长与体验（CRITICAL）

• feel-250ms-max — 将 UI 动画时长控制在 250ms 以内
• feel-faster-better — 更快的动画几乎总是感觉更好
• feel-asymmetric-enter-exit — 进入和退出时采用不对称时长
• feel-distance-proportional — 根据移动距离设置动画时长
• feel-haptic-sync — 将触觉反馈与视觉动画关键帧同步
• feel-stagger-timing — 以 30-50ms 的间隔依次显示内容

3. 手势连续性（HIGH）

• gesture-rubber-band — 在拖动边界应用橡皮筋效果
• gesture-momentum-dismiss — 达到速度或距离阈值时关闭
• gesture-snap-points — 使用感知速度的吸附点
• gesture-interruptible — 让所有手势动画都可中断
• gesture-scroll-drag-conflict — 解决滚动与拖动手势冲突
• gesture-state-transient — 使用 GestureState 管理临时拖动状态
• gesture-projected-landing — 投射手势速度，确定自然的落点位置

4. 空间转场（HIGH）

• spatial-matched-geometry — 使用 matchedGeometryEffect 实现展开/收起变形
• spatial-zoom-navigation — 为集合详情页使用缩放导航转场（iOS 18）
• spatial-transition-origin — 将转场锚定到触发位置
• spatial-hero-shared-element — 共享多个元素 ID，打造丰富的主视觉动画
• spatial-sheet-morph — 使用 matchedGeometryEffect 呈现工作表
• spatial-tab-continuity — 在标签页转场中保持空间方向

5. 微交互（HIGH）

• micro-button-press-scale — 按下时将按钮缩放至 0.97，提供触觉反馈
• micro-haptic-pairing — 每次视觉状态变化都配合触觉反馈
• micro-symbol-effect — 使用 symbolEffect 实现 SF Symbol 动画
• micro-toggle-bounce — 为切换状态变化添加弹跳效果
• micro-long-press-fill — 为长按操作添加渐进填充动画
• micro-loading-phase — 使用重复弹簧动画呈现自然的加载状态

6. 编排（HIGH）

• orch-phase-animator — 使用 PhaseAnimator 实现多步序列
• orch-keyframe-animator — 使用 KeyframeAnimator 实现时间线精准的动态效果
• orch-stagger-children — 错开子元素的显示时机，实现有序呈现
• orch-coordinated-entrance — 使用共享触发器协调多个元素的入场动画
• orch-timeline-view — 使用 TimelineView 实现连续循环动画

7. 细节与润色（HIGH）

• craft-reduce-motion — 尊重 accessibilityReduceMotion 设置，并在不支持时回退为交叉淡化
• craft-blur-bridge — 使用模糊效果衔接不完美的过渡状态
• craft-drawing-group — 使用 drawingGroup() 实现由 Metal 加速的复杂动画
• craft-geometry-group — 使用 geometryGroup() 隔离布局动画的传播
• craft-transaction-debug — 使用 Transaction 调试并覆盖动画行为

8. 内容动态效果（MEDIUM-HIGH）

• content-numeric-text — 数字变化时使用 contentTransition(.numericText)
• content-scroll-transition — 使用 scrollTransition 实现滚动位置效果
• content-visual-effect — 使用 visualEffect 实现位置感知动画
• content-symbol-replace — 使用 contentTransition 为符号替换添加动画
• content-text-renderer — 使用 Text Renderer 实现字符级动画（iOS 18）

使用方法

阅读各个参考文件，了解详细说明和错误／正确代码示例：

• 章节定义 — 类别结构和影响级别
• 规则模板 — 添加新规则的模板

参考文件

文件	描述
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息