Flutter Motion UI は何をしますか?
このスキルは、Flutter の画面を、すべての要素が意図を持って配置され、すべてのタップが応答し、すべての状態変化が可視化され、データが画面間で一貫性を保つ、統一された完成品のように感じられるものにします。
22 のリファレンスアプリ(ウォレット、配達、ライドシェア、フィットネス、認証/OTP、アラーム、チェックアウト、予約、デバイスペアリング)のフレーム単位の分析から抽出されました。references/video-analysis.md に、各アプリの動作と、それを再現するレシピがリストされています。
中核となる考え方:状態がモーションを駆動する
リファレンスに見られる「スムーズな」瞬間のほとんどは、同じメカニズムです。状態が変化し、UI が古い値から新しい値へアニメーションしたのです。ボタンハンドラから誰も controller.forward() を呼び出していません。したがって、作業は常に次のようになります。
- 画面の状態を明示的にモデル化する(シールクラス。5 つのブール値ではありません)。
- その状態を
switchでレンダリングする。 - 変化する部分を暗黙的アニメーション(
AnimatedSwitcher、AnimatedContainer、TweenAnimationBuilder、またはキットのウィジェット)でラップし、2 つの状態間の差分が自動的にアニメーションされるようにする。
これを行うと、アニメーションと状態管理は 2 つの問題ではなくなります。中断されたアニメーション、ダブルタップ、「読み込みスピナーの横に成功チェックマーク」などのバグは、不可能な状態を表現できなくなるため発生しません。
明示的な AnimationController は、指によるジェスチャー、ループするアンビエント(パルス、スキャナー)、そして調整されたマルチパートシーケンスの 3 つの目的のために予約されています。
ワークフロー
1. コードを書く前にプロジェクトを読む
pubspec.yaml:Flutter/Dart SDK、既に使用されている状態管理ライブラリ(riverpod / bloc / provider / getx / なし)、ルーター(go_router / auto_route / Navigator)、既存のアニメーションパッケージ。- 既存のテーマ、色、スペーシング、共有ウィジェット。それを拡張すること。2 つ目のデザインシステムや 2 つ目の状態管理ライブラリを導入しないでください。プロジェクトのフォルダ構造と命名規則に合わせてください。既存のアプリでは、依頼されていないファイルへの変更は、機能に必要な範囲(
Heroラッパー、パディングインセット)に抑え、関連のない lint やスタイルのクリーンアップは依頼がない限り行わず、書き換えた既存のファイルはすべてサマリーにリストアップして、diff に驚きがないようにしてください。 - 新しいプロジェクトであるか、規約がない場合は、このスキルのデフォルト(Riverpod
Notifier、拡張機能付き Material 3 テーマ、lib/core/+lib/features/<name>/)を使用します。
2. モーションキットを 1 回インストールする
タスクに必要なキットファイルをプロジェクトの共有 UI フォルダ(デフォルトは lib/core/motion/)にコピーします。常に motion.dart と、実際に使用するウィジェットのみをコピーし、バレルファイルをそれに合わせてトリミングしてください。10 個のファイルすべてをコピーしても、3 つしか使用しない画面では、誰も呼び出さないコードが残ります。キットは依存関係のない純粋な Flutter で、アナライザークリーン、ウィジェットテスト済みです。プロジェクトに同等のもの(独自の duration ファイル、独自のナビゲーションバー)が既にある場合は、重複させるのではなく、そちらに適応してください。
| ファイル | 提供するもの |
|---|---|
motion.dart | Motion.fast/base/slow/page/hero、カーブ、スプリング、動きを抑えるヘルパー — 唯一 duration が存在する場所。Haptics.tap/selection/success/error — 唯一 haptics が実行される場所 |
entrance.dart | Entrance(段階的なフェード/スライド/ブラーイン)、StateSwitcher(状態に応じたアニメーション付き switch) |
page_routes.dart | AppRoute、AppPageTransitions.theme()、showAppSheet、heroFadeShuttle |
glass_nav_bar.dart | スライドするレンズインジケーターを備えたフローティングリキッドグラスピル型の GlassNavBar |
morph_button.dart | Pressable、MorphButton(待機→スピナー→成功)、AsyncMorphButton |
slide_to_confirm.dart | ドラッグしてコミットする SlideToConfirm(ハプティクスとステータス付き) |
rolling_number.dart | CountUpText、RollingText(走行距離計の数字) |
otp_boxes.dart | OtpBoxes、Shake |
animated_items.dart | AnimatedItems<T> — プレーンな不変リストからの挿入/削除をアニメーションするリスト |
assets/examples/send_money_flow.dart は、完全な実装済みフロー(リスト→キーパッド→スライド→送信中→成功→戻る、新しい行がアニメーションで追加される)です。マルチステートフローを構築する際に読んでください。これは模倣すべきパターンです。その隣にある send_money_flow_test.dart は、そのようなフローをテストする方法を示しています(フルパス、小画面でのオーバーフロー、動きを抑えた状態)。
assets/project_setup/analysis_options.yaml は、キットが合格する厳格な lint セットです。プロジェクトのアナライザー設定にマージすることを提案してください。チームが既に選択したルールを上書きしないでください。
3. 画面を状態とモーメントとして設計し、構築する
画面をコーディングする前に、(頭の中または短いコメントで)次のことを書き留めてください。
- 状態:この画面が取りうる明確な状態は何か?(例:
Editing → Submitting → Done | Failed) - 共有データ:この画面に表示されるが、別の画面にも表示されるデータは何か?そのデータは 1 つの所有者を持ちます。
- モーメント:エントランス、主要なアクション、各状態変化、そして終了。それぞれに、以下の表から 1 つの意図的なモーションを割り当てます。それ以外はすべて静止したままにします。
次に、この順序で構築します:トークン/テーマ → 静的レイアウト → 状態レイヤー → 状態変化アニメーション → エントランスの段階的アニメーション → ナビゲーショントランジション → ハプティクス → 動きを抑えた状態と小画面の確認。
4. 検証
タッチしたファイルで dart format を実行し、flutter analyze がクリアになるまで実行します。デバイス/エミュレータが利用可能な場合は、アプリを実行して実際にフローを確認します。そうでない場合は、状態を遷移する短いウィジェットテストを書き(サンプルテストの形状を参照)、実行します。次に、references/consistency-checklist.md を確認します。
どのモーメントにどのモーションを使うか
| モーメント | 使用するもの | タイミング |
|---|---|---|
| 画面が最初に表示される | 3~7 個のトップレベルブロックに Entrance(index: n)、上から下へ | slow、55 ms 間隔 |
| 関連のない画面への遷移(スプラッシュ→ホーム、認証→アプリ) | AppTransition.fadeThrough | page |
| 同じフローの次のステップ(電話→OTP→パスワード) | AppTransition.sharedAxisX + アニメーション化されたステップインジケーター | page |
| リストアイテム → その詳細 | 画像/カードに Hero + 詳細の残りは後でフェードイン | hero |
| 確認 / 選択 / 評価 / ピッカー | showAppSheet、内部でコンテンツが段階的に表示 | page |
| 処理中のリクエスト | MorphButton または SlideToConfirm(status 付き) | フェーズごとに base |
| 値の変更(価格、ETA、残高) | RollingText(離散値)/ CountUpText(絶対値) | base / long |
| アイテムの追加 / 削除 | AnimatedItems | base |
| 画面状態の変更(読み込み→コンテンツ→エラー) | StateSwitcher | base |
| 選択(チップ、カード、タブ、星) | AnimatedContainer の色/境界線 + 小さな AnimatedScale | fast |
| 任意のタップ | Pressable のスケール + 軽いハプティクス | instant |
| バリデーション失敗 | Shake + 赤い境界線 + メッセージ。入力は保持 | slow |
| 成功 | Motion.overshoot でチェックマークがポップ、successHold で保持、その後次へ | — |
洗練された印象を保つための経験則:
- エントランスは 1 回だけ再生される。 遅延リストでは、スクロールして再表示される行は再構築され、再びアニメーションするため、
Entrance(enabled: …)を渡して最初の表示時のみアニメーションするようにします。 - ナビゲーションごとに 1 つの見せ場。 Hero または ブラースルー または 大きな段階的アニメーション — 3 つすべてではありません。
- 入りはゆっくり、出は速く。 終了は、
Motion.exitを使用して、開始時の duration の約 60~80% の時間で実行されます。 - 関連するものは一緒に動き、関連しないものは段階的に動く。
- transform と opacity をアニメーションし、長いリストではレイアウトのアニメーションを避ける。 ブラーは負荷が高いため、少数の hero 要素にのみ使用し、リスト行ごとには使用しないでください。
- 装飾のために入力をブロックしない。 エントランスはタップ可能性を遅らせてはいけません。実際の処理(ネットワーク)のみがコントロールを無効にします。
- 動きを抑える設定を尊重する:キットは既に
Motion.of(context, …)を介して duration を短縮しています。作成するコントローラーでも同じことを行ってください。
状態管理の基本
完全なガイド(Riverpod / Bloc / ChangeNotifier 対応):references/state.md。譲れない点:
- フロー状態はシールクラス。 UI は網羅的な
switch。各状態が必要とするデータを内部に保持します。 - 共有データは 1 つの所有者。 リスト画面と詳細/フロー画面は同じプロバイダーを読み取ります。フローはそれに書き込みます。
Navigator.popで結果を返し、ローカルコピーを修正しないでください。そうすると画面間の同期がずれます。 - 失敗時はユーザーの入力を保持する。 送信失敗は、フィールドをそのままに、エラー付きの編集状態に戻ります。
- 副作用は
buildではなくリスナーで行う。 ナビゲーション、スナックバー、ハプティクスは状態遷移に反応します(ref.listen、BlocListener)。 - アニメーション状態はウィジェットに保持し、ビジネス状態は決して保持しない。 コントローラーは
Submittingを認識しますが、AnimationControllerについては認識しません。 - ライブデータは状態にマッピングされたストリーム(ETA、ドライバーの位置、注文ステータス)。ウィジェットはティック間を補間し、更新が 1 秒に 1 回でもモーションが継続するようにします。
awaitの後で状態に触れる前に、非同期ギャップ(ref.mounted/isClosed/mounted)をガードする。
UI の一貫性
一貫性こそが、設計されたアプリと単なる良い画面の集まりを区別します。トークンをテーマに配置し、ウィジェットにハードコードしないでください。
- 色:
ColorScheme+ ブランドの追加要素(成功、ガラスの色合い、グラデーション)用のThemeExtension。ウィジェットはTheme.of(context)を読み取ります。これにより、ライト/ダーク切り替えのアニメーションが無料で実現します。 - スペーシング:4 ポイント単位のスケール(4、8、12、16、20、24、32)。アプリ全体で 1 つの水平ページパディング。
- 半径:3 つの値(例:12 小 / 20 カード / 28 シート)+ ピル。同じカードはどこでも同じ半径。
- タイポグラフィ:
TextThemeロールのみ。変更される可能性のある数字には表形式の数字を使用。 - モーション:
Motion.*のみ。 - コンポーネント:1 つのプライマリボタン、1 つのシートスタイル、1 つの入力スタイル、1 つのナビゲーションバー。2 番目のバリアントが登場した場合は、パラメーターを持つ共有ウィジェットに昇格させます。
詳細と監査リスト:references/consistency-checklist.md。
コード品質基準
アニメーション UI は、ずさんなコードのコストを増大させます。毎秒 120 回実行されるビルドメソッド、画面より長生きするコントローラー、1 つの電話にしか合わないレイアウト。すべてのファイルをキットと同じ基準に保ちます。references/flutter-best-practices.md に完全なガイダンスがあります。最もよく問題になる点:
_buildX()ヘルパーメソッドではなく小さなウィジェットクラスとconstコンストラクター。これにより、再構築は変更されたものだけに影響します。- 作成したものはすべて破棄:アニメーション/テキスト/スクロール/ページコントローラー、
CurvedAnimation、フォーカスノード、タイマー、サブスクリプション。 - すべての非同期ギャップをガード(
context.mounted/ref.mounted/isClosed)し、Future を黙ってドロップしない(awaitまたはunawaited)。 - 安定したキー:動的リストと
AnimatedSwitcherの子にはValueKey(item.id)。インデックスキーやbuild内で作成されたキーは決して使用しない。 - オーバーフローではなくスクロールするレイアウト:キーパッド、フォーム、ピッカーがある画面はすべて、320×480 のビューポート、開いたキーボード、1.3 倍のテキストサイズに耐えなければなりません。
- すべての画面が狭い画面と大きいテキストに耐える。依頼されたフローだけでなく、幅 320、テキストサイズ 1.6 倍で、タイトルと金額を保持する
Row、数字とラベルを持つカード、リストタイルは、テキストがExpanded/FlexibleにmaxLinesとoverflow付きで配置されていない限り、横方向にオーバーフローします。tester.platformDispatcher.textScaleFactorTestValue = 1.6を使用して、アプリの最初の画面(および各タブ)を 320×568 でポンプし、例外が発生しないことを期待するテストを 1 つ含めてください。 - 嬉しくないジェスチャーをテストする:早く離されたドラッグ、読み込み中の 2 回目のタップ、リクエスト途中の戻るボタン。これらのパスには、開始から終了までのテストでは決して触れられないクラッシュが潜んでいます。
- 機能コードにリテラルなし:色、半径、スペーシング、duration、ハプティクスはすべてテーマ/トークン/
Motion/Hapticsから取得。ユーザー向け文字列はプロジェクトのローカライゼーション設定に従います。 - 遅延リストとスコープ指定された再構築:スクロール可能なもののためのビルダー、刻々と変化する値のための
select、静的なサブツリーはchildとして渡す。 - 設計段階からアクセシブル:カスタムコントロールのセマンティクス、ジェスチャーのみのアクションの代替手段、動きを抑える設定の尊重。
Semantics(label: …, excludeSemantics: true)ラッパーは子のタップアクションも削除するため、onTapもSemanticsに渡します。 - 重要な箇所はテストする:コントローラーの状態遷移はユニットテストとして。フローごとに 1 つのウィジェットテストで、アニメーション内部ではなく結果をアサートします。
リファレンスファイル — タスクに一致するものを読む
references/motion-system.md— トークンの説明、振り付け、キットにないエフェクト(スプラッシュシーケンス、ブラーフォーカスイン、プログレスリング、スキャナーライン、カラー/テーマの lerp、スクロール連動ヘッダー)のレシピ。references/navigation-transitions.md— ページトランジション、適切に行われた Hero、コンテナトランスフォーム、ボトムシート、マルチステップフロー、go_router 統合。references/glass-nav-bar.md— リキッドグラスバーの構築方法、チューニング、パフォーマンス、シェル/タブの状態、既知の落とし穴。references/state.md— フロー状態、共有状態、非同期/楽観的パターン、ライブストリーム。Riverpod、Bloc、ChangeNotifier 対応。references/components.md— レシピ:ステップ進行、選択可能なカード/チップ、リアクティブラベル付き星評価、ページを再色付けするカードカルーセル、ホイールピッカー、スケルトン、ライブ追跡シート + ルートマーカー、永続的なミニステータスバー。references/video-analysis.md— 分析された 22 の録画:画面上で何が起こっているか、そしてそれを再構築する方法。references/flutter-best-practices.md— プロジェクト構造、ウィジェット構成、ライフサイクル、非同期安全性、Dart 3 の習慣、堅牢なレイアウト、パフォーマンス、テーマ設定、l10n/アクセシビリティ、エラー状態、テスト、ツール。新しいプロジェクト構造を作成する前、または既存のコードをレビュー/リファクタリングする前に読んでください。references/consistency-checklist.md— トークン、納品前 QA、パフォーマンスとアクセシビリティのチェック。
出力の期待値
- 「…残りのコード」のような断片ではなく、プロジェクトの構造に沿った完全で実行可能なファイルを提供します。
- プロジェクトの既存パッケージを使用します。新しいパッケージは、その価値が明確に認められる場合にのみ提案し、その理由を説明します。
- Flutter API は急速に変化します。インストールされている SDK が自信を持って扱えるものより新しい場合は、推測するよりも署名を確認してください(
flutter analyzeが最も高速な手段です)。 - 終了するときは、どのモーメントがアニメーション化され、どのような状態形状が使用されたかをユーザーに簡潔に伝えます。
補足
プロジェクトにモーションキットがまだ存在しない場合は、lib/core/motion/ に作成し、motion.dart、entrance.dart、page_routes.dart、morph_button.dart など、実際に使用するファイルのみをコピーします。既存のアプリに合わせてフォルダ構造を調整することも可能です。
キットの各ファイルは、assets/examples/send_money_flow.dart のような完全な例を通じて理解を深めることができます。多段階の状態を持つフローを実装する際には、この例が最良の出発点となります。
状態管理の詳細については、references/state.md を参照してください。このドキュメントでは、Riverpod、Bloc、ChangeNotifier の各アプローチにおける同等の実装が説明されています。