interaction-physics

インタラクションの物理法則

すべてのユーザー操作に物理的な応答を与えます。一貫した duration、意味のあるイージング、そして即座に届くフィードバックです。最優先の原則: すべてのアニメーションには役割がなければなりません — 操作の確認、注意の誘導、状態変化の説明のいずれかです。これらのどれも行わないモーションは、調整するのではなく削除します。 2 つの成果物を同時に提供します。プロジェクト全体のアニメーション仕様（今後のモーションを一貫させるため）と、対象範囲のインタラクションについて実装されたコードです。

使うべきとき / 使うべきでないとき

使うべきケース: ホバー/プレス/フォーカスのフィードバック、enter/exit トランジション（モーダル、トースト、ページ、リスト項目）、フォームフィードバックのアニメーション、アニメーションの監査、duration とイージングの選定、prefers-reduced-motion のサポート。

本当に必要なものが以下である場合は、代わりに引き継ぎます:

• どのローディングインジケーターをいつ表示するか → skills/frontend-design/loading-states（このスキルはそれをアニメーションさせ、そのスキルはそれを選択します）
• 楽観的 UI、体感レイテンシ、Core Web Vitals → skills/frontend-design/performance-optimization
• レンダリングパイプライン、レイアウトスラッシング、フレームバジェット → skills/frontend-design/design-engineer-mindset
• モーション以外の視覚的な仕上げ（余白、コントラスト、ヒエラルキー） → skills/frontend-design/visual-hierarchy-refactoring

ステップ 0 — コードベースを調査し、残ったことだけを尋ねる

1. 既存のモーションを grep します: transition、animation、@keyframes、framer-motion、motion.、react-spring、gsap、Tailwind の transition-*/animate-* クラス。使用されているすべての duration とイージングを記録します — ここでの不整合（たとえば、ホバー用に 150ms、200ms、250ms、300ms がすべて使われている）は、通常最初の指摘事項になります。
2. どこかで prefers-reduced-motion が扱われているかを確認します。存在しない場合は自動的な修正項目です。
3. アニメーションの手段を特定します: プロジェクトがすでにモーションライブラリを使用している場合はそれで実装し、そうでなければデフォルトで CSS の transition/keyframes を使います。CSS で実現できるエフェクトのためにモーションライブラリを追加してはいけません。
4. 死んだインタラクションを見つけます: ホバー/アクティブ状態のないボタン、トランジションなしで現れるモーダル/トースト、ポンと表示されるフォームエラー。

ユーザーに尋ねます（推測できない場合のみ、1 回にまとめて）: 望ましいパーソナリティ（落ち着いた/プロフェッショナル vs 遊び心 — 製品のドメインから明らかなら推測します）と範囲（アプリ全体の一括対応 vs 特定のフロー）。ユーザーが「アプリがカクカクする」と言った場合は、問い詰めずに監査し、前提を述べて、進めます。

ワークフロー

1. まずアニメーション仕様を書く

コードに触れる前に語彙を確定します。標準的な duration クラス:

クラス	Duration	イージング	適用対象
マイクロフィードバック	150〜250ms	ease-out	ホバー、プレス、フォーカス、トグル、色/状態の変化
構造的トランジション	300〜500ms	進入時 ease-out、退出時 ease-in	モーダル、ドロワー、ページ、アコーディオン、トースト
注意	500〜1000ms	ease-in-out	アラート、パルス、一度きりの強調
連続	約 1s ループ	linear	スピナー、不確定プログレス

判断ルール:

• 方向によるイージング: 進入する要素は減速します（ease-out）。退出する要素は加速します（ease-in）。画面上の移動は ease-in-out を使います。機械的なループのみ linear を使います。cubic-bezier(0.34, 1.56, 0.64, 1) のようなバウンスする曲線は、意図的な遊び心のために取っておきます — アプリ内で多くても 1〜2 か所です。
• サイズと距離による duration: 短い距離を移動する小さな要素は範囲の下限に位置します（ホバーの色付け: 150〜200ms）。大きなサーフェスや長い移動は上限に位置します（全画面ドロワー: 400〜500ms）。ツールチップとモーダルが同じ duration を共有してはいけません。
• 退出は進入より速く（進入 duration の約 75%） — ユーザーはすでに離れることを決めています。
• ステップ 0 で見つけた不整合な値は、最大 3〜4 個の名前付きトークンに集約します（例: --duration-fast: 200ms; --duration-base: 300ms; --duration-slow: 450ms）。CSS 変数またはテーマトークンとして定義します。

2. 四部分構成で各マイクロインタラクションを指定する

対象範囲内のすべてのインタラクションについて、次のように記述します: トリガー (ユーザーの操作 / システムイベント) → ルール (何が変化するか、duration、easing) → フィードバック (ユーザーが知覚するもの) → ループとモード (繰り返すか、中断できるか)。中断可能性のルール: 状態駆動型のトランジション (CSS の transition またはモーションライブラリ) は、ユーザーが素早くトグルできるものについては、撃ちっぱなしのキーフレームよりも優れています。中途半端に開いたメニューは、再スタートするのではなく、滑らかに逆再生される必要があります。

3. パフォーマンスとアクセシビリティの制約のもとで実装する

• アニメーションするのは transform と opacity のみ (コンポジターフレンドリー)。width、height、top、left、box-shadow を直接アニメーションしないでください。影のアニメーションは、擬似要素の opacity をクロスフェードすることで疑似再現します。background-color のアニメーションは、小さなコントロールに限り許容されます。
• reduced-motion ブロックを同じ変更内で必ず出荷する — ベースラインは references/patterns.md を参照してください。装飾的なモーションは消えます。情報を伝えるモーション (進捗) は opacity のみとして残してもかまいません。
• フィードバックをモーションだけに依存させない: アニメーションするすべての状態変化には、色/テキスト/アイコンの変化を組み合わせ、reduced-motion でも伝わるようにしてください。
• キーボード同等性: すべての :hover 効果には :focus-visible の等価なものを用意してください。
• 1 秒あたり 3 回より速い点滅は決して行わないでください (てんかん発作のリスク — これはスタイルの好みではなく、WCAG の要件です)。

マイクロフィードバックの標準的な例 (完全なギャラリー — ボタン、フォームバリデーション、トースト、モーダル、ページ遷移 — は references/patterns.md にあります):

button {
  transition: background-color 200ms ease-out, transform 200ms ease-out;
}
button:hover:not(:disabled)  { background-color: var(--color-primary-dark); }
button:active:not(:disabled) { transform: scale(0.98); }
button:focus-visible         { outline: 2px solid var(--color-focus); outline-offset: 2px; }

4. 検証する

可能であればアプリを実行する (またはレンダリングパスを論理的にたどる) ことで、トランジションが発火すること、exit がアニメーションすること (よくある見落とし — exit アニメーションの前に要素がアンマウントされる)、素早いトグルでスタッターや再スタートが起きないこと、reduced-motion メディアクエリが実際に動きを抑制することを確認してください。

必須の出力形式

両方の成果物を提出してください:

1. コード — 実装されたトランジション/アニメーション。プロジェクトに既存のモーションの仕組みとトークンを使用してください。

2. Animation Spec (markdown、プロジェクトのモーションリファレンスになります):

## Motion tokens
| Token | Value | Easing | Used for |
| --duration-fast | 200ms | ease-out | hover, press, focus, toggles |
| --duration-base | 300ms | ease-out/ease-in | toasts, dropdowns, accordions |
| --duration-slow | 450ms | ease-out/ease-in | modals, drawers, page transitions |

## Interaction inventory
| Interaction | Trigger | Motion | Duration/easing | Status |
| Button hover | pointer/focus | bg tint + scale on press | fast / ease-out | implemented |
| Modal open | click | fade + 20px rise | slow / ease-out | implemented |
| Toast exit | timeout/dismiss | slide right + fade | base×0.75 / ease-in | implemented |

## Audit findings (for audit engagements)
| Issue | Location | Fix |
| 5 different hover durations | [files] | collapsed to --duration-fast |
| No reduced-motion support | global | baseline block added |

## Deliberately not animated
[List, with one-line reasons — restraint is part of the spec]

品質基準 (提出前に確認)

• 提出したコード内のすべてのアニメーションが目的 (確認 / 誘導 / 説明) に対応している — 問われたらそれを言えるようにする
• すべての duration が spec のトークンから来ている。触れたファイルにマジックナンバーが残っていない
• Enter = ease-out、exit = ease-in、ループ = linear — 理由を明記しない限り例外なし
• アニメーションするのは transform/opacity のみ (小さなコントロールの色変化は例外)
• prefers-reduced-motion ブロックが存在し、有効である
• すべての :hover 状態に :focus-visible の対応するものがある
• アニメーションする状態変化は色/テキスト/アイコンも変化させる (モーションだけが唯一のシグナルではない)
• 1 秒あたり 3 回を超えて点滅するものはない。無限の装飾ループもない

厳守すべき禁止事項: スクロールハイジャックをしない。テキスト入力でのキーストロークに対してアニメーションしない。CSS で十分なときにモーションライブラリを追加しない。レイアウトプロパティをアニメーションしない。

統合

• skills/frontend-design/component-architecture → このスキルがアニメーションするコンポーネント状態 (hover/active/loading/disabled) を提供します。トークンシステムが存在する場合は、そこにトークンを追加してください。
• skills/frontend-design/loading-states → どの インジケーターを表示するかを決定します。このスキルはそのシマー/スピン/進捗のモーションを提供します。
• skills/frontend-design/performance-optimization ← コンポジタープロパティのみをアニメーションするという spec の制約を利用します。アニメーションが依然としてフレーム落ちする場合は、知見を返します。
• skills/frontend-design/accessibility-excellence ← あなたが提出するものの reduced-motion と点滅頻度の準拠を監査します。

リファレンス

• references/patterns.md — 完全な実装ギャラリー: ボタンの完全な状態セット、フォームバリデーション、スケルトン/スピナー/進捗のモーション、トーストの enter/exit、ページとモーダルの遷移、reduced-motion のベースラインブロック。実際の CSS を書くときに読んでください。