kinqsradio/motion-match

Motion Match（モーション一致）

ユーザーが「何かの動きを同じようにしたい」「同じように動いている証拠が欲しい」と指摘したときに使用します。結果はコードと数値、シートで提供し、「大体合ってる」という状態では決して終わりません。

まずは権利の確認

何かをキャプチャする前に、リファレンスの権利所有者を判断し、最初のメッセージでそれを明示してください。

リファレンス	許可される操作
自社の作品、またはユーザーが所有・ライセンスしているもの	ピクセルレベルを含む任意の忠実度
他社のサイトや動画	タイミング、イージング、順序、距離のみを計測し、文章の仕様として記録。自社のデザインで構築

他社の作品の場合：

• コード、シェーダー、アセット、フォント、ブランド、レイアウト、テキストを決してコピーしないでください。実際の製品を自社のもののように再作成しないでください。
• ピクセル一致は、リクエストの文言がどのようなものであっても禁止です。代わりにモーションレベルでの一致を提案し、その理由を説明します：「動きをあなたのデザインに合わせることはできます。彼らの見た目をコピーすると、彼らのデザイン作業を流用することになるので、それはしません。」
• ログイン壁、ペイウォール、Bot対策、DRMはそのままにします。サイトの利用規約を尊重し、通常の訪問者が見るものだけをキャプチャします。ページにアクセスできない場合は、画面録画を依頼してください。他社の動画をダウンロードしないでください。
• 生のキャプチャデータは Git で無視されるローカルフォルダに保管します。これらは決してコミット、公開、成果物として使用されず、ユーザーが選択した時点で削除されます。引き継ぐのは文章の数値のみです。キャプチャの場所をユーザーに伝えてください。

ユーザーがリファレンスの権利を所有していると言い、矛盾する事実がない場合は、その言葉を信じて仕様に記録します。「あの会社のサイトとまったく同じにして」というのはライセンスではありません。権利が不明な場合は --rights third-party を使用してください。

忠実度（Fidelity）

最初のメッセージで忠実度を宣言します。これによって検証内容が決まります。

レベル	一致必須	変更可
モーション（デフォルト）	トリガー、順序、スケジュール、各ステップのタイミング（80ms以内）、イージング、方向、距離	コピー、色、フォント、画像、レイアウト、ブランド
ピクセル（自社またはライセンスのみ）	上記すべてに加え、フォント、サイズ、色、間隔、アセット；平均差異は最大2%	ユーザーが変更を依頼しなかったものは一切不可
混合	一致部分は上記いずれかのレベル	追加部分は一致モーションを壊さない限り自由

ユーザーが指定したものだけを一致させます：1つのセクション、1つのウィジェット、または時間範囲。

手順

output/motion-match/<name>/ または Git が無視する別のフォルダで作業します。すべてのラウンドを保持します。--playwright と --chrome を渡すか、PLAYWRIGHT_CORE と CHROME_PATH を設定します。Node 22、既存のブラウザドライバ、既存のブラウザが必要です。動画には ffmpeg が必要です。何もインストールされません。

1. スコープ定義。 ターゲット、プロジェクト内の出力先、権利、忠実度を記述します。

2. リファレンスのキャプチャ scripts/capture.mjs を使用するか、提供された動画の場合は scripts/frames.mjs を使用します。決定した権利をコマンドに渡します。

   node <skill>/scripts/capture.mjs --url <page> --out <dir>/ref --rights third-party \
     --selector .hero --track ".title, .cta" --duration 2000
   

3. すべてのシートを読む。 scripts/sheet.mjs filmstrip を実行し、各シートを開きます。イージングは中間フレームにあります。

4. 仕様を書く。 scripts/spec.mjs draft を実行します：要素ごと、プロパティごとに1行。? はフレームの読み取りが完了していないことを示し、すべて置き換えられるまでチェックは実行されません。

5. 構築 プロジェクト自身のスタックで行い、第三者のリファレンスには自社のデザインを使用します。

6. 自社の動きを同じ方法で撮影。 リファレンスコマンドを再利用し、--url、--out、--rights のみ変更します。異なる設定はセットアップの差異を測定し、compare.mjs はそれらを不合格にします。

7. 比較。 scripts/spec.mjs check、scripts/compare.mjs、scripts/sheet.mjs compare を実行します。すべてのシートを読みます。

8. 数値が示す最小の原因を変更し、1ラウンドにつき1つの原因のみ修正し、ステップ6に戻ります。

9. 5ラウンド後に まだ失敗している行があれば停止し、その数値と理由を報告します。閾値はそのままにします。

10. レポート メッセージだけで完結するようにします：権利と忠実度、一致・追加した内容、ファイルと動きのトリガー方法、最終ラウンドの表、シートのパス、残差の数値と理由、生の第三者キャプチャの保存場所。

失敗例

ラウンド1で3つのカードのうち1つが失敗：

.card-1 opacity  start +300 ms  end +300 ms  easing RMSE 0.0003  FAIL
.card-2 opacity  start +300 ms  end +300 ms  easing RMSE 0.0055  FAIL
gaps             116.7 against 116.7         pass

すべての行が同じ遅延時間で、カーブと間隔は正しいため、原因はベースディレイのみです。その数値を1つ変更して再撮影します。フレームを自動で揃えると、この行は合格になりますが、300ms遅れたアニメーションを出荷することになるため、compare.mjs は2つのキャプチャ間での --auto-align を拒否します。

落とし穴

• 両側でビューポートやクロップ領域が異なる：コードを触る前にキャプチャを修正する。
• 最初と最後のフレームだけで判断する：中間フレームを読む。
• フォント：代替フォントは全フレームのピクセルを変える。モーション忠実度ではタイミング行だけを読み、テキストピクセルは無視する。
• ページがすでにビジーでコールドスタートと異なる：両側で同じ --wait-before を使用する。
• スクロール駆動モーションはスクロール位置に従い、時間には従わない。同じ --scroll-steps と --scroll-ms を使用し、scrollY ごとに比較する。
• スプリング：easing.mjs はオーバーシュート、適合された剛性と減衰を報告する。オーバーシュートと整定時間で調整する。
• 画面録画にはカーソル、ブラウザのクローム、圧縮ノイズが含まれる。これらをクロップアウトし、--activity-threshold を若干上げる。
• キャンバスコンテンツ：仮想クロックと両側で同じ --seed を使用する。実時間クロックでのランダムコンテンツはマシンの性能を測定することになる。
• CSSアニメーションは timing.easing で linear と報告される。実際のイージングは各キーフレームに設定されている。

境界線

orbyn-ui-design を使用して製品がどのようなモーションを持つべきかを決定し、動画には technical-illustration を、擬似UIには product-illustration を使用します。動画は コードのみルール に従います：リファレンスを技術研究のために使用し、そのフレームを決してコピーしません。

必要なときに読む

• キャプチャのレシピ、トリガー、出力ファイルについては capture を読む。
• 仕様形式とフレームの読み方については analysis を読む。
• イージング、スプリング、構築パターンについては implementation を読む。
• 合格基準と各失敗の意味については verify を読む。