HyperFrames キーフレーム は何をしますか?
キーフレームはポーズ契約です:可視状態、連続する被写体の同一性、シーク可能なランタイム、検証済みのピクセル。
幅広いシーンレシピには hyperframes-animation を、完全なコマンドドキュメントには hyperframes-cli を使用してください。
実装メカニズム(視覚スタイルではなく)の選択が必要な場合にのみ references/keyframe-patterns.md を参照してください。
手順
- アニメーションの対象、可視状態、最終状態、ランタイムを特定します。
- プロンプトを証明するための最小のメカニズムを選択します。メカニズムが不明瞭な場合にのみ
references/keyframe-patterns.mdを読んでください。 - 宣言されたランタイムでシーク可能なキーフレームを作成します。同期的に構築し、ランタイムインスタンスを登録します。
- lint、validate、
hyperframes keyframes、1つの焦点を絞った--shot、および証明時点でのスナップショットで検証します。 - 証明に失敗した場合、ソースキーフレームを修正し、レンダリング前に最小の失敗診断を再実行します。
契約
- 動く被写体に名前を付けます。
- 意図した動きを証明するために必要なポーズ(最終状態を含む)に名前を付けます。
- 隠れたヘルパー状態ではなく、可視チャンネルをキーフレーム化します。
- 連続性が重要な場合は、オブジェクトの同一性を保持します。
- 意図した動きが置換またはディゾルブである場合にのみクロスフェードします。
- 読み取り可能またはセマンティックな状態を、確認できる十分な時間保持します。
- 最終フレームはアニメーションの一部であり、後処理ではありません。
- 要求がない限り、静止状態にリセットしないでください。
- 要求がない限り、黒で終了しないでください。
- スタートシーンを編集する場合、再デザインが要求されていない限り、レイアウト、コピー、アセット、色、最終状態を保持します。
ランタイムルール
GSAP:
- ページ読み込み時に同期的に構築する
gsap.timeline({ paused: true })を使用するwindow.__timelines[compositionId]として登録する- レジストリキーは
data-composition-idと一致する必要がある - レンダリングクリティカルな動きのために
tl.play()を呼び出さない - 繰り返しは有限にする
CSS キーフレーム:
- 有限の duration と iteration count
- 確定的な delay
animation-fill-mode: both- タイミングがクリップに属する場合は
data-startを使用する
Anime.js:
- 同期的に作成する
autoplay: false- 有限の duration と loops
- 全てのインスタンスを
window.__hfAnimeにプッシュする
WAAPI:
- 有限の
duration fill: "both"- 確定的な構築
- テキストサーフェスは WAAPI をリストしません。
--shotで確認してください(WAAPI をシークします)とスナップショット
レンダリングクリティカルな動きには決して使用しないでください:
Date.now()performance.now()- シードされていない
Math.random() - ホバー/スクロールトリガー
- タイマー
- 非同期で作成されたタイムライン
- 未登録の
requestAnimationFrame - 無限ループ
GSAP スケルトン
const root = document.querySelector("[data-composition-id]");
const compositionId = root.dataset.compositionId;
const tl = gsap.timeline({ paused: true });
tl.addLabel("state-a", 0);
tl.to(".subject", {
keyframes: [
{ x: 0, opacity: 1, duration: 0.2 },
{ x: 120, opacity: 1, duration: 0.4, ease: "power2.out" },
{ x: 100, opacity: 1, duration: 0.2, ease: "power2.inOut" },
],
ease: "none",
});
window.__timelines = window.__timelines || {};
window.__timelines[compositionId] = tl;
セマンティックな状態にはラベルを使用します。
チェーン遅延の代わりに位置パラメータを使用します。
同じプロパティに後で from() / fromTo() トゥイーンを適用する場合は immediateRender: false を使用します。
キーフレーム形式
- 配列キーフレーム:ステップごとの duration/ease を持つポーズラダー
- パーセンテージキーフレーム:1 つのトゥイーン内の正確なタイミング
- プロパティ配列:コンパクトなマルチストップ変化
- 各ストップが独自のイージングを持つ場合、親に
ease: "none" - すべてのセグメントが同じ感触を共有する場合、
easeEach
例から数値の距離やタイミングをコピーしないでください。実際のコンポジションのジオメトリと duration から導出してください。
2 つのボックス間を移動する 1 つの被写体については、1 つの連続したトランスフォームトゥイーンまたは FLIP を優先します。ビューアが異なるビートを感じ取るべき場合にのみ、x/y/scale を複数のイージング付きキーフレームに分割します。すべてのセグメントは速度を変更し、ぎこちなさとして認識される可能性があります。
チャンネル
コンポジター/視覚チャンネルを優先:
x/y/z、xPercent/yPercent、scale、rotationX/Y/Z、skew、transformOrigin、svgOrigin、opacity、autoAlpha、clip-path、マスク、CSS 変数、SVG パス/ダッシュ値、カメラトランスフォーム、シェーダーユニフォーム。
レイアウト/ライフサイクルチャンネルは避ける:
top/left/right/bottom、width/height、margin/padding、display、visibility、後期 DOM 作成、被写体の動きを行うヘルパーオーバーレイ。
メカニズム選択
プロンプトを証明する最小のメカニズムを選択します:
| 必要性 | メカニズム |
|---|---|
| 同じ被写体がボックスまたは階層を変更する | 共有要素 / FLIP |
| 被写体が可視ルートを移動する | パス移動 |
| ストロークが成長またはトレースする | ストローク描画 |
| 形状が別の形状になる | 形状補間 |
| 境界を明らかにする | クリップ、マスク、またはシェーダーユニフォーム |
| 多くのアイテムが順序に従って移動する | スターガー / インデックス遅延 |
| テキスト自体が移動する | ライン、単語、文字、またはバンド分割 |
| サーフェスが曲がる、伸びる、または切り取られる | 親/子カウンタートランスフォーム |
| UI に状態がある | 明示的ステートマシン |
| シーンに深度がある | DOM 3D、Three.js、または WebGL カメラ/オブジェクトキーフレーム |
メカニズムは組み合わせることができますが、それぞれがアイデアを明確にする必要があります。装飾は証明ではありません。
タイミング
- 予告:原因や方向を明確にする場合のみ。
- 加速:静止状態から始まります。
- ピーク証明:メカニズムを間違いなく示します。
- フォロースルー:エネルギーと方向を伝えます。
- オーバーシュート:被写体が弾力的または触感的であるべき場合のみ。
- 等速パス移動:通常は
ease: "none"が必要です。 - 離散的な UI 状態:通常はシャープなイーズアウトが必要です。
- 繰り返し要素:同一のタイミングではなく、順序付けられたオフセットが必要です。
- 最終ロックアップ:トランジションポーズよりも長いホールドが必要です。
- 滑らかさ:同じ被写体上の連続的な速度を意味します。
- 同じトランスフォームプロパティに書き込むトゥイーンを重ねないでください。ただし、重なりが意図的で検証されている場合は除きます。
- 同じヒーローサーフェスがスケーリングまたは移動している間に、大きな
clip-path/ マスクの変更をアニメーション化しないでください。メインの移動が落ち着いた後で、ネストされたリビールを使用してください。
テキスト
ラインボックス、単語間隔、読みやすさ、最終的な収まりを保持します。テキストが内部で移動する場合は、テキストの周りの装飾だけでなく、グリフまたはマスクされたバンドを移動します。読み取り可能なフレームをスナップショットします。
SVG
ストロークの成長には DrawSVGPlugin を優先し、次に stroke-dasharray / stroke-dashoffset を優先します。
形状補間には MorphSVGPlugin を優先します。必要に応じてプリミティブをパスに変換し、複雑なシルエットをより単純な部分に分割します。
3D
スケールだけでは偽の深度です。
安定した親に perspective、transform-style: preserve-3d、z 軸移動、回転、カメラ/ワールドモーション、オクルージョン、およびオブジェクトが交差するときのレイヤー順序を使用します。
深度関係を明らかにする1つまたは2つの診断アングルを使用します。角度付きの証明が深度の交差を示さない場合、z / カメラ / オクルージョンを改善します。
Canvas / WebGL
カメラ位置、カメラターゲット、オブジェクトトランスフォーム、マテリアル不透明度、シェーダーユニフォーム、およびポストプロセス強度を確定的状態でキーフレーム化します。HyperFrames 時間からレンダリングします。マーカーボックスは内部のキャンバスモーションを認識できないため、--ghost を使用します。
CLI 証明
npx hyperframes lint
npx hyperframes check
npx hyperframes keyframes .
npx hyperframes keyframes . --json
npx hyperframes keyframes . --runtime all
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --samples <n>
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<file>" --ghost --angle <angle>
npx hyperframes snapshot . --at <times>
実際のアニメーション被写体には <selector> を選択します。
最初のフレーム、証明ポーズ、最終ホールド前、正確な最終フレームには <times> を選択します。
深度を証明する必要がある場合にのみ <angle> を選択します。
| ツール | 証明内容 |
|---|---|
keyframes | ターゲット、明示的な停止、パス、トレース、合成された親/子モーション、CSS 停止、Anime 登録 |
--shot | ゴースト、ルート形状、時間間隔、DOM 3D 投影、焦点を絞ったセレクター証明 |
--layout strip | インプレースモーション、オーバーラップ、接触、微妙なスケール/不透明度、テキストウェーブ |
--ghost | キャンバス、WebGL、シェーダーモーション、レンダリング 3D |
snapshot --at | マスク、テキストの読みやすさ、完全な状態、最終ロックアップ、黒/リセットテール |
セレクター証明が正しく見えない場合:
--jsonを再実行する- 実際のアニメーションターゲットを見つける
- そのターゲットを撮影する
- フルフレームをスナップショットする
- ログよりも描画されたピクセルを信頼する
診断結果の読み方
flat は明示的な中間ポーズがないことを意味します。keyframes は明示的な停止が存在することを意味します。motionPath はルートが存在することを意味します。trace はマルチストローク描画を意味します。composed with は子モーションが親モーションを継承することを意味します。
ゴースト間隔が均等であれば等速を意味します。ゴーストが密集している場合はスローインまたはセトルを意味します。大きなギャップは高速移動を意味します。
ヘルパーセレクターによるショットは証明ではありません。壊れたフルフレーム上のオニオンショットは証明ではありません。
エラー処理
| 失敗 | 修正 |
|---|---|
| エンドポイントのみ | 中間ポーズを追加し、ピーク証明を保持し、--shot を再実行する |
| 同一性の崩壊 | 1 つの要素を生かし続け、共有ソース/ファイナルボックスを使用し、代替クロスフェードを削除する |
| 偽 3D | z / カメラ移動、オクルージョン、角度付き証明を追加する |
| 誤った最終 | 最終ホールドを追加し、最終ホールド前と正確な最終をスナップショットする |
| シーク不可能なランタイム | 自動再生を一時停止し、インスタンスを登録し、タイマーを削除し、同期的に構築する |
| 読み取り不可能なテキスト | ラインボックスを保持し、変位を減らし、最終ホールドを追加し、テキストフレームをスナップショットする |
完了
lint、validate、keyframes、1 つの焦点を絞った --shot、およびスナップショットを実行します。最初のフレーム、証明ポーズ、最終ホールド前、正確な最終、被写体所有のモーション、およびデバッグオーバーレイがないことを確認します。