transitions-polish

トランジションの調整

transitions-dev スキルのアドオンです。transitions-dev がトランジション全体を導入するのに対し、このスキルはすでに存在するモーションを調整します。5つのモーショントークンの次元、つまり時間、距離、スケール、ぼかし、イージングをスキャンして、それぞれの値が参照すべきトークンと、値を選ぶ際のより高次のルール（開く／閉じる際の非対称性、ホバー時の移動、段階的な遅延、遅延時間）を提案します。

transitions-dev と一緒に、または単独でインストールできます。このスキルだけでプロジェクトを監査できるよう、トークン値は以下に再掲しています。インストールすると、transitions.dev の Refine パネルが、すべての Small refinement ジョブにこれらのルールを自動的に適用します。

基本方針：最も近い数値ではなく、用途に合わせる

値が20msずれているからといって「間違い」ではありません。モーションの役割に合っていないときに間違いとなります。必ず最初に用途を推測してください。モーダルを閉じる、ドロップダウンを開く、ツールチップ、バッジの表示、ページのスライド、テキストの表示、シェイクなどです。そのうえで、用途の説明が一致するトークンを選びます。300ms のモーダルを閉じる動作は、数値が異なっていても、どちらも「モーダルを閉じる」用途なので --duration-quick（150ms）に対応します。値の用途がどのトークンの用途とも一致しない場合は、そのままにします。数値が近いという理由だけで、決して無理に置き換えないでください。

5つの次元

transitions.dev の Motion tokens タブで公開されているものと同じスケールです。このスキルの _root.css を一度プロジェクトにコピーしてください。インポート後は、任意のトークンを var(--…) で参照できます。transitions-dev のトランジションはリテラル値を使用するため、これらのトークンがなくても動作します。共有スケールに合わせて調整するには、このスキルをインストールしてください。

時間

トークン	値	用途
--duration-stagger	40ms	アイテムごとの段階的な遅延
--duration-micro	80ms	ツールチップ／パスの遅延、シェイクの一区間、大きな段階的遅延
--duration-quick	150ms	モーダル／ドロップダウンを閉じる、テキストの切り替え、ツールチップの表示
--duration-fast	250ms	アイコンの切り替え、ドロップダウン／モーダルを開く、タブのスライド、ページのスライド
--duration-medium	350ms	パネル／トーストを閉じる
--duration-slow	400ms	パネルを開く、スケルトンコンテンツの表示、入力内容のクリア
--duration-very-slow	500ms	強調表示、バッジの表示、テキストの表示、成功チェック

イージング

トークン	値	用途
--ease-smooth-out	cubic-bezier(0.22, 1, 0.36, 1)	モーダル／ドロップダウン／パネルを開く・閉じる、ページのスライド、サイズ変更、位置変更
--ease-in-out	ease-in-out	アイコンの切り替え、テキストの切り替え、テキストの表示、スケルトンの表示
--ease-out	ease-out	ツールチップを開く／閉じる
--ease-linear	linear	シマー、スケルトンのパルス、スピナー
--ease-bounce	cubic-bezier(0.34, 1.36, 0.64, 1)	バッジを弾むように表示
--ease-bounce-strong	cubic-bezier(0.34, 3.85, 0.64, 1)	弾むようにホバーアウト（アバターが戻る動作）

--ease-smooth-out がデフォルトです。汎用の ease、ease-in、または手書きの cubic-bezier(...)／linear(...) は、サーフェスの動き（開く／閉じる、スライド、サイズ変更、位置変更）に限り、こちらに近づけてください。他の5つのトークンイージングはそのままにします。すでにグリッドに沿っており、それぞれ固有の意図があるためです。

距離

トークン	値	用途
--distance-micro	4px	テキストの切り替え
--distance-small	6px	エラー時のシェイク（短い区間）
--distance-base	8px	バッジを斜めに表示、ページのスライド、エラー時のシェイク（長い区間）
--distance-medium	12px	テキストの表示
--distance-large	30px	チェックバッジの表示

移動距離は、頻度が高いほど小さく、演出が大がかりなほど大きくなります。場所を変えないテキストの切り替えはほとんど動かず（4px）、ページのスライドは視認しやすい 8px 移動し、特別な祝賀演出のバッジは 30px 移動することがあります。フルパネル／ドロワー以外で translate の距離が ~40px を超えると、たいてい動きが鈍く見えます。--distance-base に近づけてください。

スケール

トークン	値	用途
--scale-large	0.96	モーダルを開く／閉じる
--scale-medium	0.97	ドロップダウンを開く
--scale-small	0.98	ツールチップを開く
--scale-tiny	0.99	ドロップダウンを閉じる

記録された値は、サーフェスがアニメーションで「開始」する、静止状態ではない「前」スケールです。最終的には常に 1 に落ち着きます。大きなサーフェスほど離れた位置から開始します（モーダルは 0.96）。小さなヒントはほとんどスケールしません（0.98～0.99）。~0.9 を下回る前スケールは「ズーム」のように見え、UI の装飾にはほとんど適合しません。その場合は該当する用途のトークンに合わせてください。

ぼかし

トークン	値	用途
--blur-small	2px	パネルの表示、アイコンの切り替え、テキストの切り替え、スケルトンの表示、数値のポップイン
--blur-medium	3px	ページのスライド、テキストの表示
--blur-large	8px	成功チェックの表示

ぼかしは静止状態ではない「前」ぼかしで、最終的に 0 に落ち着きます。切り替えやスライドをやわらかく見せるために使い、単純なフェードや色／テーマの変更には使わないでください。ぼかしはトークンの範囲外だけでなく、なしの場合もあります。用途からぼかしが必要なのが明らかな場合（ぼかしレーンのないページスライドなど）は、--blur-medium の追加を提案してください。

調整ルール — 値が適切な場合

開閉の非対称性

開く動きはユーザーを招き入れ、閉じる動きは邪魔にならないようにします。閉じる動きは開く動きより速く、控えめにします。

• 時間： ドロップダウン／モーダルは 開くとき 250ms → 閉じるとき 150ms（--duration-fast → --duration-quick）。パネルは 開くとき 400ms → 閉じるとき 350ms（--duration-slow → --duration-medium）。トーストは 閉じるとき 350ms（--duration-medium）。
• 対称にする例外 — 両方向で同じ時間とイージングを使い、分けない： ページの左右切り替え（250ms）、スライド式タブ（250ms）、アコーディオン（250ms）、アイコンの切り替え（250ms）、テキストの切り替え（150ms）。これらは開閉のペアではなく、単一の可逆的な動きとして感じられます。
• 距離とぼかし： 距離とぼかしは入場フェーズで使います。終了フェーズではそれらを省くか縮小し、閉じるときにコンテンツが画面を大きく横切らないようにします。
• イージング： ほとんどの開閉には --ease-smooth-out を使います。オーバーシュートするカーブは入場時のみ（バッジのポップ、数値のポップイン）に使い、閉じる動きでは決してバウンスさせないでください。

ホバー時とホバー解除時

• ホバー時： すばやく、直接的にします。--duration-fast 以下の短い持ち上がり動作に --ease-smooth-out を使います。
• ホバー解除時： やわらかく、バネのような動きにします。戻る動きには、より長い時間と --ease-bounce-strong（アバターが戻る場合は cubic-bezier(0.34, 3.85, 0.64, 1)）を使い、行が急に戻るのではなく落ち着くようにできます。ホバー解除時の動きをホバー時より凝ったものにするのは、ここだけです。

スタッガーと遅延

• スタッガーの間隔： 項目ごとに --duration-stagger（40ms）を使います。大きな項目が少数ある場合は --duration-micro（80ms）まで増やします。最後の項目が遅れて感じられないよう、スタッガーの合計（間隔 × 項目数）は ~300ms 未満にしてください。長いリストでは、スタッガーさせる項目数を制限するか、間隔を短くします。
• 意図的な遅延： 通り過ぎるカーソルでツールチップが表示されないよう、表示前に --duration-micro（80ms）待たせます。成功チェックのパス描画にも同じ 80ms の拍を使います。遅延は、誤操作による発動を防ぐ場合や、2 つの動きを順序付ける場合に適しています。遅いアニメーションをかさ増しするために使うものではありません。
• 遅延と時間： 動きが遅く感じられる場合は、遅延を追加するより時間を短くしてください。遅延はスタッガー、意図の判定、意図的な順序付けに限って使います。
• 閉じる動きやホバー解除時に遅延を入れないでください。非表示になる動きは瞬時に感じられる必要があります。

コマンド

このスキルには、名前空間付きの動詞が 2 つあります。同じプロジェクトにインストールされた他のスキルの動詞と呼び出しが衝突しないよう、すべてのコマンドは transitions から始まります。review はレポートを出し、polish は適用します。

transitions review — モーションをトークンに照らして監査する

トリガーフレーズ： transitions review、「アニメーションをレビューして」、「モーションを監査して」、「場当たり的なトランジションをスキャンして」、「アニメーションをトークン化して」、「duration がずれている箇所はどこ？」、「モーションのトークンに合わせて」、「タイミングを統一して」。

動作：

1. プロジェクト全体をスキャンします — スタイルシートだけでなく、インラインの style= / CSS-in-JS、styled-components、<style> ブロック、Tailwind の任意値（duration-[300ms]、[transition-timing-function:...]）も対象に、次の5つの要素をすべて調べます：duration（…ms/…s）、イージング（cubic-bezier(...) / キーワード）、translate 距離（translate*(…px)）、scale(...)、blur(...)。@keyframes は、それを動かす animation を確認します。
2. 値ごとに、周辺のセレクターやコンポーネント名からモーションの用途（モーダルを閉じる、ドロップダウンを開く、ツールチップ、バッジの表示、ページのスライド、テキストの表示、シェイク、ホバー時の浮き上がりなど）を推測します。上記のトークン表で用途を確認し、ドキュメントに記載された用途が一致するトークンを選びます — まず用途で判断し、数値の近さでは選びません。トランジション全体のレシピを入れ替える提案はしないでください。それは transitions-dev の transitions apply の担当範囲です。
3. 仕上げのルールを適用します。値が単独でトークンに沿っているかだけでなく、開く／閉じる際の非対称性、ホバー時の入退場、スタッガーの合計時間、遅延も確認します。
4. ファイルごとにまとめた番号付きリストを出力し、変更すべき値のみを記載します：
   • path/to/Component.css:L42 — modal close: 300ms → var(--duration-quick) (150ms) — 閉じる動作は、250ms の開く動作より速くする必要があります。
   • path/to/List.css:L20 — stagger: 120ms → var(--duration-stagger) (40ms) — 8 項目 × 120ms = 合計 960ms となり、最後の項目が遅く感じられます。
   • 用途がどのトークンにも一致しない値は変更せず、no matching token usage として記載します。
5. 何も編集しないでください。 最後に次の文を記載します："Run transitions polish to apply these changes, or confirm any line to apply individually."

transitions polish — モーショントークンの調整を適用する

トリガーフレーズ： transitions polish、「トランジションを仕上げて」、「モーションを調整して」、「タイミング／イージングを調整して」、「モーションのトークンを適用して」、「スタッガーを修正して」、「アニメーションをトークン化して」。

動作：

1. このセッションでユーザーが transitions review を実行していない場合は、まず transitions review と同じスキャン（手順1～4）を実行して変更リストを作成します。特定のファイル、行、値が指定されている場合は、その対象にスキャンを絞ります。
2. 変更する値の数とファイルごとの内訳を、例となる行を1つ添えて簡潔に提案します。編集前に確認を求めます。
3. 確認後、ソースにトークンの変更を適用します：
   • プロジェクトですでに _root.css（このスキルの _root.css）がインポートされている場合は、ハードコードされた duration／イージング／距離／スケール／ぼかしを var(--…) 参照に置き換えます。インポートされていない場合は、トークンのリテラル値を記述し、今後の調整を一か所で行えるようにするには _root.css のインポートが有効であることを伝えます。
   • var(--…) に切り替える場合を除き、ファイルで使われている単位や形式（0.25s と 250ms など）を維持します。
   • 仕上げの対象となるモーション値だけを変更します — 再フォーマットや無関係な編集はしません。
   • 通常の CSS、CSS Modules、styled-components/emotion、Tailwind のユーティリティ／設定、インラインの style オブジェクト、Motion/Framer のバリアントに対応します。
4. _root.css がまだプロジェクトにない場合は、仕上げ作業の前または同時に、一度だけインストールすることを提案します。
5. 差分は小さく保ちます。最後に、変更したファイルを一行でまとめます。

Refine パネルとの関係

このスキルをプロジェクトにインストールすると、transitions.dev の Refine パネルにある Small refinement タブは、_refine-rules.md の簡潔なルールをエージェントのプロンプトに自動でインライン化します。そのため、クリックごとの提案が、ファイルを追加で読み込まなくてもこれらのルールに従います。transitions review はプロジェクト全体を対象に同様の監査を行い、transitions polish は承認された調整をソースに書き込みます。

今後の拡張

このスキルに自然に追加できる項目として、パフォーマンスに関する注意点（transition: all、transform／opacityの代わりにwidth／top／box-shadowをアニメーションすること、will-changeの誤用）、prefers-reduced-motionの検出漏れ、プロジェクト横断の一貫性監査（同じ目的のトランジションに異なる値が使われていないか）、Tailwind／Framerのトークンアダプター、「モーションの仕上がりスコア」のレポートが挙げられます。