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 アーキテクチャを前提としています。

• Feature モジュールがインポートするのは Domain と DesignSystem のみです（Data や兄弟 Feature はインポートしません）
• App ターゲットが各要素の収束点となり、DependencyContainer、具象コーディネーター、Route Shell の配線を所有します
• Domain は純粋な Swift を保ち、モデルに加えて、リポジトリ、*Coordinating、ErrorRouting、AppError の契約を定義します
• Data は SwiftData／ネットワーク／同期／再試行／バックグラウンド I/O を所有し、Domain のプロトコルを実装します
• 読み取り／書き込みフローの既定動作は、古いデータを表示しながら再検証する読み取りと、キューに登録する楽観的な書き込みです
• ViewModel はリポジトリのプロトコルを直接呼び出します（既定のユースケース／インタラクター層は設けません）

適用する場面

次の場合に、これらのガイドラインを参照してください。

• SwiftUI のビューやトランジションにアニメーションを追加するとき
• ジェスチャー駆動のインタラクション（ドラッグ、スワイプ、パン）を構築するとき
• 空間トランジション（展開／折りたたみ、ナビゲーションのモーフィング）でビューをつなぐとき
• マイクロインタラクション（ボタンの押下、トグル、読み込み状態）を設計するとき
• コンテンツの変更に物理的な感覚を持たせるとき（数字の回転表示、シンボルの置き換え）
• 複数要素のアニメーションシーケンス（KeyframeAnimator、PhaseAnimator）を振り付けるとき
• デザインシステムのモーショントークンを定義するとき
• パフォーマンス、アクセシビリティ、アーキテクチャへの準拠の観点から、アニメーションコードをレビューするとき

優先度別ルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス	ルール数
1	スプリング物理	重大	spring-	8
2	タイミングと感覚	重大	feel-	6
3	ジェスチャーの連続性	高	gesture-	7
4	空間的なトランジション	高	spatial-	6
5	マイクロインタラクション	高	micro-	6
6	オーケストレーション	高	orch-	5
7	細部の作り込みと仕上げ	高	craft-	5
8	コンテンツのモーション	中〜高	content-	5

クイックリファレンス

1. スプリング物理（重大）

• 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. タイミングと感覚（重大）

• 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-rubber-band — ドラッグ境界でラバーバンド効果を適用します
• gesture-momentum-dismiss — 速度または距離のしきい値に達したら閉じます
• gesture-snap-points — 速度を考慮したスナップポイントを使用します
• gesture-interruptible — すべてのジェスチャーアニメーションを中断可能にします
• gesture-scroll-drag-conflict — スクロールとドラッグのジェスチャー競合を解決します
• gesture-state-transient — 一時的なドラッグ状態には GestureState を使用します
• gesture-projected-landing — ジェスチャーの速度を予測に反映し、自然な着地点を実現します

4. 空間的なトランジション（高）

• 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 — SF Symbol のアニメーションには symbolEffect を使用します
• 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 — Metal を利用した複雑なアニメーションには drawingGroup() を使用します
• 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	バージョンとリファレンス情報