ios-animations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

dot-skills — Airbnb iOS SwiftUI Animations Best Practices

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

Opinionated, strict animation craft guide for SwiftUI iOS 26 / Swift 6.2 apps. Contains 50 rules across 8 categories, prioritized by impact. Derived from Airbnb Engineering motion patterns, Apple WWDC sessions, and Apple Human Interface Guidelines. Mandates @Equatable on every animated view, motion tokens for all spring/timing values, and design system tokens for layout.

这是一份针对SwiftUI iOS 26 / Swift 6.2应用的、具有明确立场的严格动画设计指南。包含8个类别共50条规则，按影响优先级排序。内容源自Airbnb工程团队的动效模式、Apple WWDC技术讲座及Apple人机界面指南。要求为每个动画视图添加@Equatable协议，所有弹簧/计时值使用动效令牌，布局使用设计系统令牌。

Mandated Architecture Alignment

强制架构对齐要求

This skill is designed to work alongside

swift-ui-architect

and

ios-design-system

. All code examples follow the same non-negotiable constraints:

```
@Equatable
```
macro on every view (Airbnb measured 15% scroll hitch reduction)
```
@Observable
```
for complex animation state that involves business logic triggers
```
@State
```
for view-owned animation state (toggle booleans, drag offsets)
Design system tokens:
```
Spacing.xs/sm/md/lg
```
,
```
Radius.sm/md/lg
```
— zero hardcoded layout numbers
Motion tokens:
```
Motion.standard/responsive/playful
```
— zero scattered spring literals
Semantic colors:
```
.backgroundSurface
```
,
```
.accentPrimary
```
— no raw Color literals in views
Feature animations remain presentation-only; data/network concerns stay in Data package

本指南需与

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包内

Scope & Relationship to Sibling Skills

适用范围与关联技能的关系

This skill is the motion layer — it teaches how to BUILD fluid, performant animations. When loaded alongside sibling skills:

Sibling Skill	Its Focus	This Skill's Focus
`swift-ui-architect`	Architecture (modular MVVM-C, route shells, protocol boundaries)	Animation architecture (motion tokens, spring selection, orchestration)
`ios-design-system`	Design system infrastructure (tokens, styles, governance)	Motion tokens and animated component patterns
`ios-hig`	HIG compliance patterns	Motion-specific HIG (reduce motion, spatial continuity)

Out of scope: Designer-authored vector animations (use Lottie for After Effects exports). Complex UIKit transition controllers (see Airbnb's declarative transition framework). This skill covers programmatic SwiftUI animations only.

本指南是动效层内容 — 教授如何构建流畅、高性能的动画。与关联技能配合使用时：

关联技能	其核心关注点	本指南的核心关注点
`swift-ui-architect`	架构（模块化MVVM-C、路由壳、协议边界）	动画架构（动效令牌、弹簧选择、编排）
`ios-design-system`	设计系统基础设施（令牌、样式、治理）	动效令牌与动画组件模式
`ios-hig`	HIG合规模式	动效专属HIG（减少动效、空间连续性）

不包含范围： 设计师制作的矢量动画（After Effects导出内容请使用Lottie）。复杂UIKit转场控制器（请参考Airbnb的声明式转场框架）。本指南仅涵盖程序化SwiftUI动画。

Clinic Architecture Contract (iOS 26 / Swift 6.2)

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

All guidance in this skill assumes the clinic modular MVVM-C architecture:

Feature modules import
```
Domain
```
+
```
DesignSystem
```
only (never
```
Data
```
, never sibling features)
App target is the convergence point and owns
```
DependencyContainer
```
, concrete coordinators, and Route Shell wiring
```
Domain
```
stays pure Swift and defines models plus repository,
```
*Coordinating
```
,
```
ErrorRouting
```
, and
```
AppError
```
contracts
```
Data
```
owns SwiftData/network/sync/retry/background I/O and implements Domain protocols
Read/write flow defaults to stale-while-revalidate reads and optimistic queued writes
ViewModels call repository protocols directly (no default use-case/interactor layer)

本指南的所有内容均基于Clinic模块化MVVM-C架构：

功能模块仅导入
```
Domain
```
+
```
DesignSystem
```
（禁止导入
```
Data
```
或其他兄弟功能模块）
App目标是聚合点，负责
```
DependencyContainer
```
、具体协调器及路由壳的连接
```
Domain
```
层为纯Swift实现，定义模型及仓库、
```
*Coordinating
```
、
```
ErrorRouting
```
和
```
AppError
```
协议
```
Data
```
层负责SwiftData/网络/同步/重试/后台I/O，并实现Domain层协议
读写流程默认采用 stale-while-revalidate 读取策略和乐观队列写入策略
ViewModel直接调用仓库协议（默认不使用用例/交互器层）

When to Apply

适用场景

Reference these guidelines when:

Adding animations to SwiftUI views or transitions
Building gesture-driven interactions (drag, swipe, pan)
Connecting views with spatial transitions (expand/collapse, navigation morphs)
Designing micro-interactions (button press, toggle, loading states)
Making content changes feel physical (number rolls, symbol replacements)
Choreographing multi-element animation sequences (KeyframeAnimator, PhaseAnimator)
Defining motion tokens for a design system
Reviewing animation code for performance, accessibility, and architecture compliance

在以下场景中参考本指南：

为SwiftUI视图或转场添加动画
构建手势驱动的交互（拖拽、滑动、平移）
使用空间转场连接视图（展开/折叠、导航形变）
设计微交互（按钮按压、切换、加载状态）
让内容变化具有物理质感（数字滚动、符号替换）
编排多元素动画序列（KeyframeAnimator、PhaseAnimator）
为设计系统定义动效令牌
评审动画代码的性能、无障碍访问及架构合规性

Rule Categories by Priority

按优先级划分的规则类别


spring-
feel-
gesture-
spatial-
micro-
orch-
craft-
content-

Priority	Category	Impact	Prefix	Rules
1	Spring Physics	CRITICAL	`spring-`	8
2	Timing & Feel	CRITICAL	`feel-`	6
3	Gesture Continuity	HIGH	`gesture-`	7
4	Spatial Transitions	HIGH	`spatial-`	6
5	Micro-interactions	HIGH	`micro-`	6
6	Orchestration	HIGH	`orch-`	5
7	Craft & Polish	HIGH	`craft-`	5
8	Content Motion	MEDIUM-HIGH	`content-`	5


spring-
feel-
gesture-
spatial-
micro-
orch-
craft-
content-

优先级	类别	影响级别	前缀	规则数量
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

Quick Reference

快速参考

1. Spring Physics (CRITICAL)

1. 弹簧物理（CRITICAL）

```
spring-motion-tokens
```
— Define motion tokens as a caseless enum for all spring presets
```
spring-smooth-default
```
— Default to .smooth spring for all UI transitions
```
spring-snappy-responsive
```
— Use .snappy spring for responsive interactions
```
spring-bouncy-celebration
```
— Use .bouncy spring for playful and celebratory moments
```
spring-custom-parameters
```
— Tune custom springs with response and dampingFraction
```
spring-velocity-preservation
```
— Springs preserve velocity on interruption
```
spring-never-linear
```
— Never use linear or easeInOut for interactive UI
```
spring-completion-chaining
```
— Use withAnimation completion for chained sequences

```
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绝不使用线性或easeInOut动画
```
spring-completion-chaining
```
— 使用withAnimation的完成回调实现链式动画序列

2. Timing & Feel (CRITICAL)

2. 时序与质感（CRITICAL）

```
feel-250ms-max
```
— Keep UI animations under 250ms
```
feel-faster-better
```
— Faster animations almost always feel better
```
feel-asymmetric-enter-exit
```
— Use asymmetric timing for enter and exit
```
feel-distance-proportional
```
— Match duration to distance traveled
```
feel-haptic-sync
```
— Sync haptic feedback to visual animation keyframes
```
feel-stagger-timing
```
— Stagger reveals at 30-50ms intervals

```
feel-250ms-max
```
— UI动画时长控制在250ms以内
```
feel-faster-better
```
— 动画速度越快，体验通常越好
```
feel-asymmetric-enter-exit
```
— 进入和退出动画使用非对称时序
```
feel-distance-proportional
```
— 动画时长与移动距离成正比
```
feel-haptic-sync
```
— 触觉反馈与视觉动画关键帧同步
```
feel-stagger-timing
```
— 按30-50ms的间隔错开元素展示

3. Gesture Continuity (HIGH)

3. 手势连续性（HIGH）

```
gesture-rubber-band
```
— Rubber band at drag boundaries
```
gesture-momentum-dismiss
```
— Dismiss on velocity OR distance threshold
```
gesture-snap-points
```
— Use velocity-aware snap points
```
gesture-interruptible
```
— Make all gesture animations interruptible
```
gesture-scroll-drag-conflict
```
— Resolve scroll and drag gesture conflicts
```
gesture-state-transient
```
— Use GestureState for transient drag state
```
gesture-projected-landing
```
— Project gesture velocity for natural landing position

```
gesture-rubber-band
```
— 拖拽边界处添加橡皮筋效果
```
gesture-momentum-dismiss
```
— 满足速度或距离阈值时触发关闭
```
gesture-snap-points
```
— 使用感知速度的吸附点
```
gesture-interruptible
```
— 所有手势动画需支持中断
```
gesture-scroll-drag-conflict
```
— 解决滚动与拖拽手势的冲突
```
gesture-state-transient
```
— 使用GestureState存储临时拖拽状态
```
gesture-projected-landing
```
— 根据手势速度预测自然着陆位置

4. Spatial Transitions (HIGH)

4. 空间转场（HIGH）

```
spatial-matched-geometry
```
— Use matchedGeometryEffect for expand/collapse morphs
```
spatial-zoom-navigation
```
— Use zoom navigation transition for collection detail (iOS 18)
```
spatial-transition-origin
```
— Anchor transitions to their trigger location
```
spatial-hero-shared-element
```
— Share multiple element IDs for rich hero animations
```
spatial-sheet-morph
```
— Use matchedGeometryEffect for sheet presentations
```
spatial-tab-continuity
```
— Maintain spatial direction in tab transitions

```
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. Micro-interactions (HIGH)

5. 微交互（HIGH）

```
micro-button-press-scale
```
— Scale buttons to 0.97 on press for tactile feedback
```
micro-haptic-pairing
```
— Pair every visual state change with haptic feedback
```
micro-symbol-effect
```
— Use symbolEffect for SF Symbol animations
```
micro-toggle-bounce
```
— Add bounce to toggle state changes
```
micro-long-press-fill
```
— Animate progressive fill for long press actions
```
micro-loading-phase
```
— Use repeating spring for organic loading states

```
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. Orchestration (HIGH)

6. 动画编排（HIGH）

```
orch-phase-animator
```
— Use PhaseAnimator for multi-step sequences
```
orch-keyframe-animator
```
— Use KeyframeAnimator for timeline-precise motion
```
orch-stagger-children
```
— Stagger child elements for orchestrated reveals
```
orch-coordinated-entrance
```
— Coordinate multi-element entrances with shared trigger
```
orch-timeline-view
```
— Use TimelineView for continuous repeating animations

```
orch-phase-animator
```
— 使用PhaseAnimator实现多步骤序列动画
```
orch-keyframe-animator
```
— 使用KeyframeAnimator实现时间线精确的动效
```
orch-stagger-children
```
— 错开子元素展示以实现编排式揭露效果
```
orch-coordinated-entrance
```
— 通过共享触发器协调多元素入场动画
```
orch-timeline-view
```
— 使用TimelineView实现持续重复动画

7. Craft & Polish (HIGH)

7. 设计与打磨（HIGH）

```
craft-reduce-motion
```
— Respect accessibilityReduceMotion with crossfade fallback
```
craft-blur-bridge
```
— Use blur to bridge imperfect transition states
```
craft-drawing-group
```
— Use drawingGroup() for Metal-backed complex animations
```
craft-geometry-group
```
— Use geometryGroup() to isolate layout animation propagation
```
craft-transaction-debug
```
— Use Transaction to debug and override animation behavior

```
craft-reduce-motion
```
— 遵循accessibilityReduceMotion要求，提供淡入淡出 fallback 方案
```
craft-blur-bridge
```
— 使用模糊效果衔接不完善的转场状态
```
craft-drawing-group
```
— 使用drawingGroup()实现基于Metal的复杂动画
```
craft-geometry-group
```
— 使用geometryGroup()隔离布局动画的传播
```
craft-transaction-debug
```
— 使用Transaction调试和覆盖动画行为

8. Content Motion (MEDIUM-HIGH)

8. 内容动效（MEDIUM-HIGH）

```
content-numeric-text
```
— Use contentTransition(.numericText) for number changes
```
content-scroll-transition
```
— Use scrollTransition for scroll-position effects
```
content-visual-effect
```
— Use visualEffect for position-aware animations
```
content-symbol-replace
```
— Animate symbol replacement with contentTransition
```
content-text-renderer
```
— Use Text Renderer for character-level animation (iOS 18)

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

How to Use

使用方法

Read individual reference files for detailed explanations with incorrect/correct code examples:

Section definitions — Category structure and impact levels
Rule template — Template for adding new rules

阅读单个参考文件获取包含错误/正确代码示例的详细说明：

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

Reference Files

参考文件

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

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