HyperFrames Keyframes(キーフレーム)
キーフレームはポーズコントラクトです。可視状態、連続する被写体の同一性、シークセーフなランタイム、検証されたピクセルを約束します。
ブロードなシーンレシピには hyperframes-animation を、完全なコマンドドキュメントには hyperframes-cli を使用してください。references/keyframe-patterns.md は、視覚的なスタイルではなく、実装メカニズムを選択する場合にのみ参照してください。
手順
- アニメーションの被写体、可視状態、最終状態、ランタイムを特定します。
- プロンプトを証明する最小のメカニズムを選択します。メカニズムが不明瞭な場合にのみ
references/keyframe-patterns.mdを参照します。 - 宣言されたランタイムでシークセーフなキーフレームを作成します。同期的に構築し、ランタイムインスタンスを登録します。
hyperframes lint、hyperframes check、hyperframes keyframes、1つのフォーカスされた--shot、および証明時点でのスナップショットで検証します。- 証明に失敗した場合は、ソースキーフレームを修正し、レンダリング前に失敗した最小の診断を再実行します。
コントラクト
- 動く被写体に名前を付けます。
- 意図した動き(最終状態を含む)を証明するために必要なポーズに名前を付けます。
- 隠れたヘルパー状態ではなく、可視チャンネルにキーフレームを設定します。
- 連続性が重要な場合は、オブジェクトの同一性を維持します。
- 意図した動きが置換またはディゾルブである場合にのみクロスフェードします。
- 読み取り可能または意味的な状態を、認識できる十分な時間保持します。
- 最終フレームはアニメーションの一部であり、クリーンアップではありません。
- 要求されない限り、静止状態にリセットしないでください。
- 要求されない限り、黒で終了しないでください。
- スターターシーンを編集する場合、再デザインを要求されない限り、レイアウト、コピー、アセット、色、最終状態を維持します。
ランタイムルール
GSAP:
- ページロード時に同期的に構築します
gsap.timeline({ paused: true })を使用しますwindow.__timelines[compositionId]として登録します- レジストリキーは
data-composition-idと一致する必要があります - レンダリングクリティカルな動きのために
tl.play()を呼び出さないでください - 繰り返し回数は有限にします
CSSキーフレーム:
- 有限の再生時間と反復回数
- 決定論的な遅延
animation-fill-mode: both- タイミングがクリップに属する場合は
data-startを使用します
Anime.js:
- 同期的に作成します
autoplay: false- 有限の再生時間とループ
- すべてのインスタンスを
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 を使用します。
キーフレームの形式
- 配列キーフレーム: ステップごとの継続時間とイージングを持つポーズラダー。
- パーセンテージキーフレーム: 1つのトゥイーン内の正確なタイミング。
- プロパティ配列: コンパクトな多段変化。
- 各ストップが独自のイージングを持つ場合の親の
ease: "none"。 - すべてのセグメントが同じ感覚を共有する必要がある場合の
easeEach。
例から数値の距離やタイミングをコピーしないでください。実際のコンポジションのジオメトリと継続時間から導き出します。
1つの被写体が2つのボックス間を移動する場合は、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作成、被写体の動きを行うヘルパーオーバーレイ。
可視性の変更には、登録されたシーク可能なGSAPタイムライン上の autoAlpha、または明示的な境界でのゼロ継続時間の tl.set() を使用します。クリップ外の要素またはクリップ内のラッパーのみをターゲットにします。決して .clip 自体をターゲットにしないでください。生の visibility を継続時間トゥイーンしたり、display をトゥイーンしたりしないでください。
メカニズムの選択
プロンプトを証明する最小のメカニズムを選択します:
| ニーズ | メカニズム |
|---|---|
| 同じ被写体がボックスや階層を変える | 共有要素 / FLIP |
| 被写体が見える経路を移動する | パストラベル |
| ストロークが成長またはトレースされる | ストローク描画 |
| ある形状が別の形状になる | 形状補間 |
| リビール境界が可視である | クリップ、マスク、またはシェーダーユニフォーム |
| 多くのアイテムが順序を持って移動する | スタガー / インデックス付き遅延 |
| テキスト自体が移動する | 行、単語、文字、またはバンドの分割 |
| サーフェスが曲がる、伸びる、または切り抜かれる | 親子カウンタートランスフォーム |
| UIに状態がある | 明示的ステートマシン |
| シーンに深度がある | DOM 3D、Three.js、またはWebGLカメラ/オブジェクトキーフレーム |
メカニズムは組み合わせることができますが、それぞれがアイデアを明確にする必要があります。装飾は証明ではありません。
タイミング
- 予告動作は、それが原因や方向を明確にする場合のみ。
- 加速は静止から始まります。
- ピーク証明はメカニズムを間違いなく示します。
- フォロースルーはエネルギーと方向を強調します。
- オーバーシュートは、被写体が弾力的または触感的であるべき場合のみ。
- 等速パストラベルは通常
ease: "none"が必要です。 - 離散的なUI状態には通常、鋭いイーズアウトが必要です。
- 繰り返し要素には、同一のタイミングではなく、順序付けられたオフセットが必要です。
- 最終的なロックアップは、トランジションポーズよりも長いホールドが必要です。
- スムーズさとは、同じ被写体の連続的な速度を意味します。
- オーバーラップが意図的で検証されていない限り、同じトランスフォームプロパティを書き込むトゥイーンをオーバーラップさせないでください。
- 同じヒーローサーフェスがスケーリングまたは移動している間に、大きな
clip-path/マスクの変更をアニメーション化するのは避けてください。メインの移動が落ち着いた後に、ネストされたリビールを使用してください。
テキスト
ラインボックス、ワードスペーシング、読みやすさ、最終的なフィットを維持します。テキストが内部で移動する場合は、テキスト周囲の装飾だけでなく、グリフまたはマスクされたバンドを移動させます。読み取り可能なフレームをスナップショットします。
SVG
ストロークの成長には DrawSVGPlugin を優先し、次に stroke-dasharray/stroke-dashoffset を優先します。形状補間には MorphSVGPlugin を優先します。必要に応じてプリミティブをパスに変換し、複雑なシルエットをより単純な部分に分割します。
3D
スケールだけでは偽の深度です。安定した親にパースペクティブ、transform-style: preserve-3d、z移動、回転、カメラ/ワールドモーション、オクルージョン、およびオブジェクトが交差するときのレイヤー順序を使用します。
深度関係を明らかにする1つまたは2つの診断角度を使用します。角度付き証明が深度交差を示さない場合は、z/カメラ/オクルージョンを改善します。
キャンバス / 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/カメラ移動、オクルージョン、角度付き証明を追加します |
| 間違った最終 | 最終ホールドを追加し、最終マイナスホールドと正確な最終をスナップショットします |
| シーク不可能なランタイム | 自動再生を一時停止し、インスタンスを登録し、タイマーを削除し、同期的に構築します |
| 読み取れないテキスト | ラインボックスを維持し、変位を減らし、最終ホールドを追加し、テキストフレームをスナップショットします |
完了
hyperframes lint、hyperframes check、hyperframes keyframes、1つのフォーカスされた --shot、およびスナップショットを実行します。最初のフレーム、証明ポーズ、最終マイナスホールド、正確な最終、被写イドメインのモーション、およびデバッグオーバーレイがないことを確認します。