UI Animation

Reference files

File	Read when
references/decision-framework.md	デフォルト: アニメーション決定、easing、duration
references/spring-animations.md	spring physics、framer-motion useSpring、spring params の設定
references/component-patterns.md	ボタン、ポップオーバー、ツールチップ、ドロワー、モーダル、トーストのアニメーション構築
references/clip-path-techniques.md	clip-path を使用した reveal、タブ、hold-to-delete、comparison slider
references/gesture-drag.md	drag、swipe-to-dismiss、momentum、pointer capture の実装
references/performance-deep-dive.md	jank のデバッグ、CSS vs JS、WAAPI、CSS variables trap、Framer Motion の注意点
references/review-format.md	アニメーション code の review — Before/After/Why テーブル、issue チェックリスト
references/contextual-animations.md	contextual icon swap、word-level stagger entrance、fixed-offset exit animation の実装

Core rules

• フィードバック、方向性、連続性、または意図的な喜びのためにアニメーション化します。
• キーボード開始アクション (ショートカット、矢印ナビゲーション、tab/focus) を決してアニメーション化しないでください。
• interruptible UI には CSS transitions を優先; keyframes は予め決定されたシーケンスにのみ使用します。
• CSS transitions > WAAPI > CSS keyframes > JS (requestAnimationFrame)。
• アニメーションを interruptible でユーザー入力駆動にします。
• Asymmetric timing: enter は少し遅くしてもよく; exit は高速にする必要があります。
• DOM entry animation に @starting-style を使用; data-mounted にフォールバックします。
• 小さい filter: blur(2px) は粗いクロスフェードを隠すことができます。

Motion design principles

• 連続性対テレポーテーション。 両方の状態で可視の要素は、その場で遷移します。shared element transition を使用 — 要素が置かれている場所から拡大するのであって、新しいインスタンスをフェードインするのではありません。persistent element を複製したり、コンポーネントを共有するビュー間でハードカットしたりしないでください。
• 方向的な動きは位置と合致します。 タブおよびカルーセル遷移は、空間的なレイアウトと一致する方向でアニメーション化します (forward は左から右、back は右から左)。
• トリガーから出現。 オーバーレイ、トレイ、パネルは、それらを開いた要素から外側へアニメーション化します。generic center-screen entrance は空間的な方向性を損ないます。
• どこでも一貫したポーランド。 under-animated 領域は製品全体を unpolished に感じさせます。motion quality はすべてのサーフェスで統一する必要があります。
• 喜びは頻度に反比例します。 より稀な相互作用には、より多くのパーソナリティと驚きの余地があります。high-frequency アクションは見えないものである必要があります。
• 動きは知覚速度を向上します。 状態間のスムーズな遷移は、ハードカットよりも高速に感じられます、同一の読み込み時間でも。

What to animate

• 動き: transform と opacity のみ。
• 状態フィードバック: color、background-color、opacity は許容されます。
• layout properties (width、height、top、left) を決してアニメーション化しないでください; transition: all を決して使用しないでください。
• core interaction の filter animation を回避; 避けられない場合は blur <= 20px を保ちます。
• SVG: transform-box: fill-box; transform-origin: center を持つ <g> ラッパーに transforms を適用します。
• theme switch 中に transition を無効化 ([data-theme-switching] * { transition: none !important })。

Easing defaults

Element	Duration	Easing
ボタンプレスフィードバック	100–160ms	cubic-bezier(0.22, 1, 0.36, 1)
ツールチップ、小さいポップオーバー	125–200ms	ease-out または enter curve
ドロップダウン、select	150–250ms	cubic-bezier(0.22, 1, 0.36, 1)
モーダル、ドロワー	200–350ms	cubic-bezier(0.22, 1, 0.36, 1)
画面上でのスライド	200–300ms	cubic-bezier(0.25, 1, 0.5, 1)
シンプルなホバー (color/opacity)	200ms	ease
Illustrative/marketing	最大 1000ms	Spring またはカスタム

Named curves

• Enter: cubic-bezier(0.22, 1, 0.36, 1) — entrance と transform-based hover
• Move: cubic-bezier(0.25, 1, 0.5, 1) — slide、drawer、panel
• Drawer (iOS-like): cubic-bezier(0.32, 0.72, 0, 1)

UI に ease-in を使用しないでください。easing.dev からカスタム curve を優先します。

Spatial and sequencing

• ポップオーバーの trigger point で transform-origin を設定; モーダルは center を保ちます。
• ダイアログ/メニューの場合、scale(0.85–0.9) の周辺で開始します。scale(0) は決して使用しないでください。
• reveal を 30–50ms per item で stagger; total stagger は 300ms 以下。visual importance で timing を変化 — 最も重要な要素がリードする必要があります。Uniform stagger (すべての項目間の identical delays) は階層を削除し、mechanical に感じられます。
• Paired elements rule: 一緒にアニメーション化する要素 (modal + overlay、tooltip + arrow、FAB + label) は同じ easing curve と duration を共有する必要があります。paired element 間の mismatched timing は、「何か off に感じられる」バグの一般的な原因です。

Accessibility

• @media (hover: hover) and (pointer: fine) の背後に hover animation をゲート化して、touch で false positive を回避します。Tailwind v4 hover: utilities はこのガードを自動的に適用 — Tailwind v4 プロジェクトで manual media query をスキップします。
• direct manipulation 中は、要素をポインターに locked に保ちます。easing は release 後にのみ追加します。
• prefers-reduced-motion: reduce を尊重します。spatial movement (translateY、scale) を opacity crossfade に置き換え — reduced motion は spatial movement を減らすことを意味し、ゼロフィードバックではありません。color と background-color transition を保ちます。

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    transition-duration: 0.01ms !important;
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
  }
}

• Framer Motion では、useReducedMotion hook を使用して spatial initial values をスキップします:

const shouldReduceMotion = useReducedMotion();
<motion.div
  initial={shouldReduceMotion ? false : { opacity: 0, y: 20 }}
  animate={{ opacity: 1, y: 0 }}
/>

Performance

• transform と opacity のみをアニメーション化 — これらは layout と paint をスキップします。
• looping animation を IntersectionObserver で off-screen の時に pause します。
• will-change は heavy motion 中にのみ、transform/opacity にのみ toggle — 後で削除します。
• CSS variables を使用した drag gesture animation を実行しないでください (すべての子の recalc をトリガー)。
• Motion x/y value は axis-based movement と drag の通常の選択肢です。combined transform または interop に対して 1 つの transform owner が必要な場合は、full transform string を使用します。
• references/performance-deep-dive.md で WAAPI、compositing layer、CSS vs JS comparison を参照します。

Anti-patterns

• transition: all — layout recalc をトリガーし、unintended properties をアニメーション化します。
• layout properties (width、height、top、left) をアニメーション化して interactive feedback を行う。
• UI entrance に ease-in を使用 — sluggish に感じられます。
• scale(0) からアニメーション化 — 現実世界では何も無から出現しません。scale(0.85–0.95) を使用します。
• ユーザートリガーなしに mount でアニメーション化 — unexpected motion は disorienting です。
• Permanent will-change — heavy motion 中にのみ toggle します。
• drag gesture animation の CSS variables — every frame を reprint します。
• Symmetric enter/exit timing — exit は高速にする必要があります (ユーザーは instant response を期待)。
• drag boundary での hard stops — friction/damping を代わりに使用します。
• Motion x/y props と handwritten transform string を同じ要素で混合。
• rapidly-triggered element 上の keyframe — interruptibility のために CSS transition を使用します。
• 関連ビュー間の static cut — ビュースが要素を共有する場合、hard cut は spatial context を失います。shared element をその場で遷移させます。
• 状態全体で persistent element を複製 — 要素を現在の位置から次の位置にアニメーション化するのであって、1 つを非表示にして別の要素を表示するのではありません。
• contextual content の generic center-screen entrance — overlay と tray は何も無から fade in ではなく、trigger から出現する必要があります。
• container と staggering children の両方をアニメーション化 — container あたり 1 つの entrance を選択します。panel がスライドする場合、その content は到着時に既に visible である必要があります。

Workflow

このチェックリストをコピーして追跡します:

Animation progress:
- [ ] Step 1: 相互作用がアニメーション化すべきかを決定
- [ ] Step 2: 目的、easing、duration を選択
- [ ] Step 3: implementation style を選択
- [ ] Step 4: 関連する component または technique reference をロード
- [ ] Step 5: timing、interruption、device behavior を検証

1. references/decision-framework.md から 4 つの質問に答える: アニメーション化すべきか? どのような目的? どのような easing? どのような速度?
2. 上記の easing defaults テーブルから duration を選択します。
3. Implementation を選択: CSS transition > WAAPI > spring > keyframe > JS。
4. あなたの component type または technique の関連 reference をロードします。
5. review するときは、references/review-format.md からの Before/After/Why テーブル形式を使用します。

Validation

• layout property animation (width、height、top、left) がないことを確認します。
• looping animation が off-screen で pause されていることを確認します。
• will-change が animation 中にのみ toggle され、permanently set されていないことを確認します。
• component を素早く retoggle して、transition が zero からの restart ではなく cleanly retarget することを確認します。
• animation を DevTools で 0.1x にスローして、full speed で invisible の timing issue をキャッチします。
• frame-by-frame で coordinated property timing をキャッチするために記録と再生を行います。
• real device で touch interaction をテストします (simulator だけではなく)。