animations

アニメーション

60 fps（高リフレッシュレートのディスプレイでは120 fps）を実現し、ユーザーのモーション設定を尊重し、用途に応じて最も負荷の低いツールを使うウェブアニメーションを作成またはレビューします。まずCSSを使い、実行時の制御にはWeb Animations APIを、スプリング物理、ジェスチャー、共有レイアウトアニメーションが必要な場合はMotionを、レンダリングモデル自体を3次元にする必要がある場合はReact Three Fiberを使います。

このSKILL.mdは簡易インデックスです。 詳細なルールは rules/*.mdに記載されており、必要に応じて読み込まれます。実用的なレシピは references/recipes.mdにあります。すぐに使えるHTML/CSS スニペットはtemplates/にあります。

ウェブ専用です。 このスキルの仕組みはウェブ（CSS、Motion、View Transitions、Web Animations API）を対象としています。React Native / Expoのモーション （Reanimated、gesture-handler、Moti、Lottie、Rive）には、代わりに animations-nativeスキルを使ってください。このスキルは、プラットフォームに依存しない ブレインストーミング／動詞→モーションのカタログを再利用します。

---

中心となる考え方

アニメーションはtransform、opacity、filterだけに適用してください。 これらは、メインスレッドでレイアウトやペイントを発生させずに、ブラウザーがGPU上で合成する3つのプロパティです。それ以外（width、height、top、left、margin、padding、box-shadow、…）ではレイアウトまたはペイントが発生し、カクつきの原因になります。全プロパティの一覧は rules/safe-properties.mdを参照してください。

アニメーションできないように見えるプロパティ（height: auto、display: none、リストの並べ替え、ルートの変更）には、最新のCSSにGPU処理として実現するネイティブのプリミティブが用意されています。詳しくは rules/modern-css.mdを参照してください。

---

ブレインストーミングモード — インタラクション → フィードバック

アニメーションの作り方ではなく、何をアニメーションすべきかをユーザーが尋ねている場合は、この項目から始めてください。以下は、下記の技術的な判断フローではなく、こちらを案内する質問の例です。

• 「このボタンを押したとき、理想的なフィードバックは何ですか？」
• 「カードを閉じるとき、どんな感触にすべきですか？」
• 「これを切り替えたとき、自然なアニメーションはどのようなものですか？」
• 「ユーザーが行を削除したとき、どうなるべきですか？」

手順：

1. rules/interaction-feedback.mdにある 5つの質問を使ったブレインストーミングを行います — 動詞、可逆性、開始者、空間的な起点、アフォーダンスの負荷です。 推奨案を選ぶ前に、それぞれを1行で回答してください。
2. 同じファイルのカタログでインタラクションを調べます。 カタログには、離散的な操作（ボタンの押下、切り替え、コピー）、 要素のライフサイクル（カードの開閉、モーダル、ドロワー、リストへの追加／ 削除）、状態（読み込み中、成功、エラー、スケルトン）、 継続的なジェスチャー（ドラッグ、スワイプ、ピンチ、プル・トゥ・リフレッシュ）、 ナビゲーション（タブ、ルート、アコーディオン、ウィザード）が含まれます。各行には 推奨するモーション、時間の目安、イージング、アニメーションするプロパティ、 そして選択の原則が記載されています。
3. 強度の段階（1 — マイクロインタラクションから5 — ヒーローモーメントまで）を選びます。目安として、重要度より2段階強い表現は 過剰なデザインに感じられます。
4. 方向の原則を適用します — モーションベクトルはインタラクションの意味を表す動詞に合わせます（開く場合はトリガーを起点に拡大し、閉じる場合は開く動きの逆にし、削除する場合は遠ざけ、選択する場合は近づけます）。
5. 下記の技術ワークフローに引き継ぎます — ブレインストーミングでは何を（例：「スケール＋不透明度、240 ms、起点を固定」）を決め、ワークフローではどのように（どのプロパティ、どのAPI、どのゲートを使うか）を決めます。

カタログとブレインストーミングのフレームワークの全容は rules/interaction-feedback.mdにあります。

---

判断フロー

以下を順に確認します。最初に一致したものを選びます。

#	シグナル	ツール
1	ホバー、フォーカス、またはクラスの切り替えによる単発の状態変化	CSS transition
2	初回描画時のフェードイン（モーダル、ポップオーバー、ダイアログ）	@starting-style + transition-behavior: allow-discrete (rules/modern-css.md)
3	宣言的なループまたは連続したキーフレーム	CSS @keyframes + animation
4	スクロール位置または要素の表示状態に連動するアニメーション	animation-timeline: scroll() / view() (rules/modern-css.md)
5	同一ページ内の DOM の切り替え、リストの並べ替え、またはクロスフェードを伴う SPA / MPA のルート変更	View Transitions API (rules/modern-css.md)
6	アコーディオン／height: auto への展開・折りたたみ	interpolate-size: allow-keywords（Chromium）または Motion layout（汎用）
7	状態の振り付け — リスト → カード、フルナビゲーション → アイコンのみのナビゲーション、グリッド → 詳細表示、タブのピル	Motion layout / layoutId (rules/state-choreography.md)
8	スプリング物理、ジェスチャー（ドラッグ／パン／ピンチ）、宣言的なバリアント	Motion (rules/when-to-use-js.md)
9	pause / reverse / scrub が必要な、プログラムによる単発のアニメーション	Web Animations API（element.animate）
10	3D レンダリング、WebGL、パーティクル、シェーダー、スクロールに連動する 3D シーン	React Three Fiber + Drei (rules/three-d.md)
11	デザイナーが作成したアセット（線形再生）— ローダー、イラスト、マイクロアニメーション	Lottie / dotLottie (rules/external-engines.md)
12	デザイナーが作成したインタラクティブなアセット — アニメーションアイコン、キャラクター、複数状態のボタン	Rive (rules/external-engines.md)

2 行が一致する場合は、番号が小さい方を選びます。依存関係が少ないためです。GSAP や requestAnimationFrame のみを使うその他のライブラリは、この判断フローには含まれません。 Motion のハイブリッドエンジンは、より小さなバンドルサイズで同じ範囲をカバーし、アニメーションがコンポジット処理のみで済む場合はコンポジター上で実行されます。

---

ワークフロー

アニメーションの作成でもレビューでも、次のフェーズに沿って進めます。

フェーズ	名前	ルールファイル	ゲート
A	ブレインストーミングのフィードバック（入力が「何？」の場合）	rules/interaction-feedback.md	ユーザーが インタラクション（動詞）を説明している場合は、ブレインストーミングの5つの質問に回答し、フェーズ0に進む前にカタログの行を選択します。ユーザーが「フェードイン」などの アニメーションプリミティブ を説明している場合は、フェーズAをスキップします。
B	知覚されるパフォーマンスを管理する（待機がある場合）	rules/perceived-performance.md	アニメーションが非同期の待機（フェッチ、ルート変更、ルート読み込み、画像デコード、楽観的更新）を挟む場合は、待機時間の基準（ローカル開発環境での「速く感じる」ではなく、p75で測定）を確認し、適切なパターン（ローダーなし、スケルトン、スピナー、プログレスバー、非同期アウト）を選択します。また、ローダーの最小表示時間200 msと、200 ms未満では表示を省略する設定を適用し、スケルトンを最終コンテンツの形状に合わせます。待機がない場合はフェーズBをスキップします。
0	プロパティを選ぶ	rules/safe-properties.md	アニメーション対象のプロパティは transform、opacity、filter のいずれかにします。それ以外の場合は、レイアウトスラッシングの測定値を示して正当化します。
1	パターンを選ぶ	rules/patterns.md	パターン（フェード、スタガー、スライド、スケール）をユーザーの意図に合わせます。
2	モダンなCSSを優先する	rules/modern-css.md	「非表示状態からの表示」「高さの自動設定」「DOMの置き換え」「スクロール連動」が必要な場合は、CSSのみで実現する方法を使用します。
3	インタラクティブな効果を組み込む	rules/interactive-effects.md	ポインター／スクロール／センサーによって値が変化する場合は、CSS変数を介して値を渡します。型付き補間には @property の使用を検討します。
4	タイミングを決める	rules/timing-easing.md	UIの継続時間は150～500 msの範囲にします。イージングには linear（意図的に使う場合を除く）ではなく、名前付きのものを指定します。
5	CSS、JS、3Dのどれを使うか決める	rules/when-to-use-js.md, rules/three-d.md	上記の判断フローに従います。Motion／R3Fは任意で使用し、デフォルトにはしません。
5.5	状態の変化を振り付ける	rules/state-choreography.md	まず計画チェックリストを実行します。選択したツール（Motionの layout、layoutId、View Transitions）は、カタログに記録された変更セットに合わせます。レイアウトプロパティを直接アニメーションさせないでください。
5.6	Reactの状態を組み込む	rules/react-state.md	状態を置く場所（コンポーネント／リフトアップ／URL／コンテキスト）を決定します。60 fpsの値はrefまたは useMotionValue に保持します。AnimatePresence のモードを選び、Strict ModeとServer Componentの境界を尊重します。
5.7	高度な効果を追加する	rules/advanced-effects.md	デザインでガラス効果、グロー、ホバー時の拡張、オーロラ、3Dチルトが必要な場合は、低コストのパターン（アニメーションする box-shadow／backdrop-filter ではなく、疑似要素＋opacity）を使います。prefers-contrast と prefers-reduced-motion のフォールバックを用意します。
5.8	外部エンジン	rules/external-engines.md	アセットがデザイナー作成のもの（Lottie／dotLottieまたはRive）の場合は、ランタイムを遅延読み込みし、画面外では一時停止し、prefers-reduced-motion に応じて静止画ポスターにフォールバックします。
6	モーション設定を尊重する	rules/accessibility.md	@media (prefers-reduced-motion: reduce) ブロックを用意し、テストします。状態の変化については、rules/state-choreography.md の専用のアクセシビリティセクションを参照してください。
7	測定する	rules/debugging.md	DevTools Performanceでアニメーションが60 fpsに達し、フレーム中に紫色のLayoutバー／緑色のPaintバーが表示されないことを確認します。
7.5	証拠を記録する（任意）	screencastスキル	複雑なアニメーション（View Transitions、Motionの layout、スクロールタイムライン、状態変化の振り付け）を扱う場合、またはユーザーから「見せて」と依頼された場合は、rules/record-and-iterate.md § Recording inputs の recording.json を使って（アニメーション要素に crop を設定し、maxWidth: 768 を指定）、Skill("screencast") を2回実行します。1回目は "reducedMotion": false、2回目は true を指定します。スキルがインストールされていない場合は、1行で報告してスキップします（screencast — skipped (not installed)）。
7.6	分析して反復する	video-analyserスキル	フェーズ7.5の録画を Skill("video-analyser") に渡し、アニメーションの要件を最初から最後まで検証します。アナライザーは、構造化された検出結果（エラー、主要フレームでのUI状態、推奨される次の手順）を返します。検出結果がアニメーションの要件（カクつき、reduced-motion分岐の欠如、フォーカスリングの消失、意図しないレイアウトのちらつき）に反する場合は、修正を適用してフェーズ7.5に戻ります。反復は最大3回までとし、4回目は Skill("confidence", analysis) でエスカレーションします。記録→分析→反復の全手順については、rules/record-and-iterate.md を参照してください。video-analyser がインストールされていない場合は、1行で報告してスキップします（video-analyser — skipped (not installed)）。

---

フェーズごとの必読資料

必要に応じて読み込んでください。事前に読み込まないでください。

フェーズ	ファイル
A	rules/interaction-feedback.md
B	rules/perceived-performance.md
0	rules/safe-properties.md
1	rules/patterns.md
2	rules/modern-css.md
3	rules/interactive-effects.md, templates/cursor-spotlight.html
4	rules/timing-easing.md
5	rules/when-to-use-js.md, rules/three-d.md
5.5	rules/state-choreography.md
5.6	rules/react-state.md
5.7	rules/advanced-effects.md
5.8	rules/external-engines.md
6	rules/accessibility.md
7	rules/debugging.md
7.5/7.6	rules/record-and-iterate.md
—	references/recipes.md（実例集。「X を最初から最後まで実装するとどうなるか」とユーザーから尋ねられた場合に読み込んでください。）

---

基本原則

1. 合成のみ。 transform と opacity は GPU 合成に割り当てられます。 それ以外はすべてフレームを消費します。
2. will-change はメスのように使います。 アニメーションの直前に適用し、 直後に取り除きます。アイドル状態の要素には適用せず、一度に適用するノードは ほんの数個までにします。
3. 値は変数で流し、状態はクラスで切り替えます。 ポインターやフレームごとの値は CSS カスタムプロパティに、ライフサイクルの状態はクラスに保持します。
4. @property でアニメーションが可能になります。 未登録のカスタムプロパティは 離散的にアニメーションします（瞬時に切り替わります）。登録済みのプロパティは 滑らかに補間されます。
5. プラットフォームの機能を優先します。 @starting-style、interpolate-size、 View Transitions、スクロール駆動タイムラインにより、以前は Motion や 独自の rAF ループが必要だった JavaScript のハックの多くは不要になりました。 アニメーションをプラットフォームで表現できない場合に限り、ライブラリを使います。
6. 動きをなくすのではなく、減らします。 prefers-reduced-motion: reduce の場合は、 動きをフェードやほぼ瞬時の状態変化に置き換え、フィードバックを完全になくすことは しないでください。
7. 最適化の前に計測します。 体感上のカクつきは、アニメーションではなく 画像のデコードにかかる 200 ms が原因かもしれません。Performance を開いて記録し、 調整する前にフレームチャートを確認します。
8. 選ぶ前にブレインストーミングします。 「このインタラクションにはどんな フィードバックを付けるべきか？」という問いには、まず interaction-feedback.md の 5 つの質問によるブレインストーミングを行います。動詞、取り消し可能性、 きっかけ、空間的な起点、アフォーダンスの負荷を検討します。いきなり 「フェードかスライドか？」と考えると、選択を正当化するための推論が抜け落ちます。
9. 時間に勝てないときは、目を欺きます。 実際の遅延は物理現象ですが、 体感上の遅延はデザインで変えられます。100 ms 以内に入力を認識し （ドハティ閾値）、答えが届く前にその形を描きます（最終レイアウトに 一致するスケルトンローダー）。取り消し可能な変更は楽観的に適用し、 200 ms 未満のローダーは最低表示時間を設けるか、完全に省略し、意図が 読み取れた時点で先読みします。同じ 1.2 秒のリクエストでも、待ち時間中の 挙動によって、軽快にも壊れているようにも感じられます。詳しくは rules/perceived-performance.md をご覧ください。

---

アンチパターン（簡潔な一覧 — 詳細な一覧はリンク先のルールを参照）

• width、height、top、left、margin、padding をアニメーションさせる （safe-properties.md）。
• ヒーロー要素に will-change: transform を設定したままにする （safe-properties.md）。
• transition: all — すべてのプロパティ変更にコストがかかり、意図せずレイアウトプロパティのアニメーションまで有効になります。
• UI のモーションに linear イージングを使う — 機械的に見えるため、ease-out または名前付きの cubic-bezier を使います （timing-easing.md）。
• 未登録のカスタムプロパティをアニメーションさせ、補間されずに切り替わることに驚く （interactive-effects.md）。
• CSS、View Transitions、Web Animations API を試す前に、25 KB のライブラリに手を伸ばす （when-to-use-js.md）。
• 新しいコードで framer-motion からインポートする — このパッケージはメンテナンスされていません。代わりに motion を使います。
• 60 fps の状態を React useState に入れる。特に R3F 内では避けます （three-d.md）。
• prefers-reduced-motion を見落とし、前庭への悪影響を招く （accessibility.md）。
• 5 つのブレインストーミングの質問に答える前に、アニメーションの形を決める （interaction-feedback.md） — 必要なのはスライドなのにフェードにしたり、カーブなのにスプリングにしたり、トグルにヒーロー級のモーションを使ったりすることになります。
• 開くときと閉じるときで異なる形を使う非対称な動き（モーダルはスケールで開き、スライドで閉じるなど） — 形は一つに決めて逆再生し、終了時は約 30 % 速くします。
• 通信が速いときに 200 ms 未満だけ表示されるスピナー — 速さではなく不具合のように見えます。perceived-performance.md のローダーの最低表示時間と 200 ms 未満でのスキップを使います。
• 最終的なコンテンツの形状に合わないスケルトン（カードグリッドのプレースホルダーが 3 本のテキストバーなど） — 切り替え時にレイアウトシフトが発生し、ページが再読み込みされたように見えます （perceived-performance.md）。
• ロールバックアニメーションのない楽観的 UI — クリック時に状態が切り替わり、サーバーに拒否されると何も示さずに元へ戻るため、ユーザーは自分の操作が原因だと思ってしまいます （perceived-performance.md）。
• ドミナントカラーや blurhash のプレースホルダーを使わないアトミックな画像読み込み — 空白の枠の後に画像が一気に表示され、レイアウトがずれます （perceived-performance.md）。

---

組み合わせるもの

• /visual-design — モーションの個性はブランドを表すシグナルです（ブルータリストな強い押し込みと、ソフト UI の穏やかな浮き上がりなど）。イージングや持続時間の選択は、決定したスタイルの方向性に沿う必要があります。新しいコンポーネントのモーションを一から設計するときは、まず /visual-design を実行して方向性を決め、その後ここに戻って仕組みを検討します。違和感のあるモーションを監査するときは、問題が技術的なもの（カクつき、GPU、イージングカーブ — このスキル）か、ブランドに合わない種類のモーションという個性の問題かを確認します（ホバー／押下／フォーカスを個性のある動きとして扱う方法は /visual-design/rules/signature-details.md を参照）。
• /ux — prefers-reduced-motion、トランジション中の focus-visible、モーションが引き起こす前庭への懸念は、/ux/rules/accessibility.md が担うアクセシビリティの最低限の確認項目です。
• /screencast — 複数フレームにわたるインタラクションは、静止画では検証できません。タイミングに左右される Critical / High の指摘には必ず呼び出します。

完了の定義

• アニメーションするプロパティが transform、opacity、filter、またはこれらのいずれかを動かす @property 登録済みカスタムプロパティであること。
• アイドル状態の要素に will-change が残っていないこと。
• イージングと時間が用途に合っていること（UI の動きは 150～500 ms で、名前付きのイージングカーブを使用します。非対称にする場合、入場と退場で異なる設定にしてもかまいません）。
• JavaScript を使用する場合、ライブラリは Motion（framer-motion でも GSAP でもありません）であること。ライブラリを使わない選択肢もあります。
• @media (prefers-reduced-motion: reduce) で、動きをフェードまたは瞬時の状態変化に抑えること。
• DevTools の Performance で、アニメーションスレッドがコンポジター上で実行されていること（Compositor 行に動作があり、アニメーション中のフレームで紫色の Layout バーや緑色の Paint バーが表示されないこと）。
• キーボードフォーカスとスクリーンリーダーの動作が、アニメーションによって変化しないこと。