fixing-motion-performance

fixing-motion-performance

アニメーションのパフォーマンス問題を修正します。

使い方

• /fixing-motion-performance この会話で行うすべての UI アニメーション作業に、これらの制約を適用します。

• /fixing-motion-performance <file> 以下のすべてのルールに照らしてファイルをレビューし、次の内容を報告します。

  • 違反（該当する正確な行またはスニペットを引用）
  • 重要な理由（簡潔な一文）
  • 具体的な修正案（コードレベルの提案）

明示的に依頼されない限り、アニメーションライブラリは移行しないでください。既存のスタック内でルールを適用してください。

適用するタイミング

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

• UI アニメーション（CSS、WAAPI、Motion、rAF、GSAP）を追加または変更する
• カクつくインタラクションやトランジションをリファクタリングする
• スクロール連動のモーションやスクロール時の表示を実装する
• レイアウト、フィルター、マスク、グラデーション、CSS 変数をアニメーションする
• will-change、トランスフォーム、計測を使用するコンポーネントをレビューする

レンダリングステップ用語集

• コンポジット：トランスフォーム、opacity
• ペイント：色、境界線、グラデーション、マスク、画像、フィルター
• レイアウト：サイズ、位置、フロー、グリッド、フレックス

優先度別のルールカテゴリ

優先度	カテゴリ	影響
1	禁止パターン	重大
2	手法の選択	重大
3	計測	高
4	スクロール	高
5	ペイント	中〜高
6	レイヤー	中
7	ぼかしとフィルター	中
8	ビュートランジション	低
9	ツールの境界	重大

クイックリファレンス

1. 禁止パターン（重大）

• 同じフレーム内でレイアウトの読み取りと書き込みを交互に行わない
• 大きな領域や重要な領域のレイアウトを継続的にアニメーションしない
• scrollTop、scrollY、スクロールイベントを使ってアニメーションを駆動しない
• 停止条件のない requestAnimationFrame ループを使用しない
• それぞれがレイアウトを計測または変更する複数のアニメーションシステムを混在させない

2. 手法の選択（重大）

• モーションには、デフォルトでトランスフォームと opacity を使用する
• インタラクションで必要な場合にのみ、JS 駆動のアニメーションを使用する
• ペイントまたはレイアウトのアニメーションは、小さく独立した領域に限り使用できる
• 連続的なモーションよりも、単発のエフェクトを優先する
• モーションを完全に削除するより、手法をより負荷の低いものに変更する

3. 計測（高）

• 一度だけ計測し、その後はトランスフォームまたは opacity でアニメーションする
• すべての DOM の読み取りを、書き込みより先にまとめて行う
• アニメーション中にレイアウトを繰り返し読み取らない
• レイアウトに似たエフェクトには、FLIP スタイルのトランジションを優先する
• 計測と書き込みをまとめて行える方法を優先する

4. スクロール（高）

• スクロール連動のモーションには、利用可能な場合、Scroll Timelines または View Timelines を優先する
• 表示状態の確認と一時停止には IntersectionObserver を使用する
• アニメーションのためにスクロール位置をポーリングしない
• 画面外ではアニメーションを一時停止または停止する
• スクロール連動のモーションで、大きな領域のレイアウトまたはペイントを継続的に発生させない

5. ペイント（中〜高）

• ペイントを発生させるアニメーションは、小さく独立した要素に限り使用する
• 大きなコンテナーのペイント負荷が高いプロパティをアニメーションしない
• トランスフォーム、opacity、位置のために CSS 変数をアニメーションしない
• 継承される CSS 変数をアニメーションしない
• アニメーションする CSS 変数のスコープをローカルに限定し、継承を避ける

6. レイヤー（中）

• コンポジターでのモーションにはレイヤーへの昇格が必要なため、昇格されると決めつけない
• will-change は一時的かつ必要な箇所に限って使用する
• 昇格させるレイヤーの数やサイズを増やしすぎない
• パフォーマンスが重要な場合は、ツールを使ってレイヤーの動作を検証する

7. ぼかしとフィルター（中）

• ぼかしのアニメーションは小さく保つ（<=8px）
• ぼかしは短時間の単発エフェクトにのみ使用する
• ぼかしを継続的にアニメーションしない
• 大きな領域にぼかしをアニメーションしない
• ぼかしよりも opacity と translate を優先する

8. ビュートランジション（低）

• ビュートランジションはナビゲーションレベルの変更にのみ使用する
• インタラクションが多い UI ではビュートランジションを避ける
• 中断やキャンセルが必要な場合はビュートランジションを避ける
• サイズ変更はレイアウトを発生させる可能性があるものとして扱う

9. ツールの境界（重要）

• 明示的に依頼されない限り、アニメーションライブラリを移行したり書き換えたりしないでください
• これらのルールは、既存のアニメーションシステム内で適用してください
• API を部分的に移行したり、同じコンポーネント内でスタイルを混在させたりしないでください

一般的な修正

/* layout thrashing: animate transform instead of width */
/* before */ .panel { transition: width 0.3s; }
/* after */  .panel { transition: transform 0.3s; }

/* scroll-linked: use scroll-timeline instead of JS */
/* before */ window.addEventListener('scroll', () => el.style.opacity = scrollY / 500)
/* after */  .reveal { animation: fade-in linear; animation-timeline: view(); }

// measurement: batch reads before writes (FLIP)
// before — layout thrash
el.style.left = el.getBoundingClientRect().left + 10 + 'px';
// after — measure once, animate via transform
const first = el.getBoundingClientRect();
el.classList.add('moved');
const last = el.getBoundingClientRect();
el.style.transform = `translateX(${first.left - last.left}px)`;
requestAnimationFrame(() => { el.style.transition = 'transform 0.3s'; el.style.transform = ''; });

レビューの指針

• まず重要なルール（禁止パターン、ツールの境界）を徹底してください
• 意図に合う中で、最もコストの低い描画処理を選んでください
• デフォルト以外の選択をする場合は、その選択を正当化する制約（表示領域のサイズ、時間、インタラクション要件）を明示してください
• レビューでは、理論よりも、実行可能な指摘と具体的な代替案を優先してください