courtneymgabrus-star/Video

プラグインのインストール: セットアップまたはフレッシュネスコマンドの前に、このスキルがHyperFramesプラグイン内にある場合は、プラグイン実行ルールに従ってください。スタンドアロンインストールの場合は、以下の更新手順をそのまま使用します。

まず、このスキルを最新の状態に保つため、ユーザーに確認してから実行してください: npx hyperframes skills update figma。すべてが最新の場合は高速に何も実行しません。それ以外の場合は、このスキルと、依存するコアドメインスキルを更新してから使用します。

Figma → HyperFrames

ユーザーのFigma作業をコンポジションに取り込みます。機能別に分割（設計仕様 §2）:

フェーズ	内容	トランスポート	サーフェス
1	静的アセット	REST	hyperframes figma asset
2	ブランドトークン/スタイル	REST	hyperframes figma tokens
3	コンポーネント → HTML	REST	hyperframes figma component
4	モーション → GSAP	利用可能な場合コネクタ	そのモーションコンテキストを使用
5	シェーダー	コネクタ / 手動エクスポート	それを使用するか、ネイティブエクスポート

利用可能な場合はRESTを使用します（大量、ヘッドレスで利用可能）。互換性のあるFigmaコネクタはモーションおよびシェーダーデータ用にオプションです。コネクタがない場合は、ネイティブエクスポートを要求します。すべてのパスでアセットをローカルにフリーズし、レンダリングの決定性を保ちます。ストーリーボードの再構築は、フェーズ1のアセットエクスポート（REST）とエージェント駆動のタイムラインアセンブリを組み合わせます。コネクタは不要です。既存のフリーズされたアセット、マニフェストレコード、バインディングはルーティング変更の影響を受けません。分割によって次のインポートで使用するクレデンシャルが変わるだけです。

認証 — 2つのクレデンシャル、スコープ付き

事前チェック — 最初のCLI呼び出しの前に、トークンが存在することを確認します: シェル環境（[ -n "$FIGMA_TOKEN" ]）またはプロジェクト.env（CLIが自動ロードします — .envエントリがあれば設定済みと見なします）。どちらもない場合は、エラーを取得するためにコマンドを実行せず、まずユーザーに一回限りのセットアップを案内し、その後停止して待機します:

1. figma.com/settings → セキュリティ → パーソナルアクセストークン → 新しいトークンを生成。
2. スコープ — この統合に必要なのは読み取り専用のみです（Figmaに書き込むことはありません）: ファイルコンテンツ: 読み取り専用 + ファイルメタデータ: 読み取り専用。非Enterpriseプランでtokensを実行する場合は、ライブラリコンテンツ: 読み取り専用を追加します — 公開スタイルのフォールバックは/v1/files/:key/stylesをヒットし、これがないと403になります（以前のセットアップテキストで省略されたスコープです）。ブランド変数用にオプションで変数: 読み取り専用 — Enterpriseのみ。これがない場合、tokensは自動的に公開スタイルにダウングレードします（期待される動作であり、エラーではありません — そのように伝えてください）。403は不足しているスコープを正確に示します。429は自動的にリトライされます（1分あたりの制限、Retry-Afterを尊重します）。
3. ユーザーにシェルプロファイルまたはプロジェクト.envでFIGMA_TOKENを設定してもらいます。トークンを会話に貼り付けるよう依頼しないでください。

オンボーディング中は、以下の点を一度に説明して期待値を設定します: すべてのインポートは記録された来歴を持つローカルのフリーズファイルとして保存されます。レンダリングがFigmaを呼び出すことは決してなく、コマンドを再実行するとFigmaで変更されたものだけが再インポートされ、1つのトークンで、Figmaアカウントが閲覧可能なすべてのファイルのアセット、ブランドトークン、コンポーネントが機能します。

• フェーズ4〜5（モーション/シェーダー）: 互換性のあるFigmaコネクタが必要で、トークンとは別の認証が必要です。利用できないか認証されていない場合は、ユーザーにコネクタの接続またはネイティブエクスポートの提供を依頼し、停止します。
• 失敗したフェーズに必要なクレデンシャルを正確に伝えます — 分割が壊れていると決して伝えないでください。
• BAD_TOKEN（401）がフロー中に発生した場合 → トークンが期限切れ/無効になっています。再発行してください。FORBIDDEN（403）→ メッセージは不足している正確なスコープを示します（例：スタイルフォールバックのlibrary_content:read） — それを追加するか、ファイルがアカウントに表示されません。REQUIRES_ENTERPRISE（変数の403）→ 障害ではありません。スタイルフォールバックはすでに実行されています。RATE_LIMITED（429）→ クライアントはすでにバックオフでリトライしています（これは全ての読み取り（アセット、トークン、スタイル、ノードツリー、バージョン）に適用されます。リトライは共有リクエストパスにあります。Retry-Afterは尊重され、60秒で上限が設定されます）。それでも発生する場合は、1分待つか、1回の呼び出しでインポートするノードを減らしてください。

レート制限の認識（仕様 §2.1）: コネクタのクォータはFigmaプランによって異なります。親フレームのリクエストをバッチ処理し、要求がない限り確認用スクリーンショットをスキップし、生のレスポンスをキャッシュして、再導出で2回目の呼び出しが発生しないようにします。RESTは1分あたりの制限があります（10+/分、エンドポイントごとのバケット） — 大量の場合は問題ありませんが、429の場合はバックオフしてください。

ルーティング

parseFigmaRef（URL、fileKey:nodeId、ベアfileKey）を使用してユーザーのFigmaリンクを解析します。次に、意図に応じて:

• "このレイヤー/ロゴ/画像を使う" → アセット（CLI）
• "ブランド/色/トークンを取得" → トークン（CLI）
• "このフレームからシーンを構築" → コンポーネント（CLI）
• "このアニメーション/モーションをインポート" → モーション（利用可能な場合コネクタ、以下参照）
• ストーリーボードセクション/シーンフレームのフィルムストリップ → ストーリーボード（以下参照）
• シェーダーフィル/エフェクト → シェーダー（以下参照）

ユーザーにすべてのステップを説明します — 各コマンドの前に、Figmaから何を取得しようとしているかを伝えます。コマンドの後は、アーティファクトがどこに保存されたか（フリーズされたパス/サイドカー/コンポーネントディレクトリ）、コンポジションで何が変わったか、そして次のアクション（プレビュー、印刷された変数の追加、バインディングをリンクするための再インポート）を伝えます。ユーザーが「うまくいきましたか？」や「次はどうすれば？」と尋ねる必要があってはなりません。

アセット（フェーズ1 — CLI）

hyperframes figma asset '<url-or-fileKey:nodeId>' [その他の参照…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]

REST経由でレンダリングし、SVGをサニタイズし、.media/images/の下にフリーズし、来歴とともにマニフェストに追加し、.media/index.md（共有メディア使用インベントリ）を再生成し、<img>スニペットを出力します。fileKey:nodeId:format:scale:versionごとに冪等です。ベクター/ロゴにはSVGを優先します（スケーラブル、アニメーション可能）。ラスターの忠実性にはPNG --scale 2を使用します。常に--description "<説明>"を渡します（インデックス行+ <img alt>になります）。名前付きブランドマークには--entity "<名前>"を追加して、メディア使用のresolve --entityが後でそれらを検索できるようにします（エンティティヒットは画像/アイコン間で一致します）。

多くのノードを1つのリクエストにバッチ処理します — 同じファイルの複数の参照を（スペース区切りまたはカンマ区切りで）渡します: hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'。すべてが単一の/v1/images呼び出しでレンダリングされます。これは、1分あたりのレート制限に対するFigma自身の回答です。フレーム全体のアセットを取得する場合は、N個の個別コマンドよりもこれを優先します。--description/--entityはバッチ内のすべてのノードに適用されるため、同じ目的を共有するノードをバッチ処理します。429もバックオフで自動リトライされます。

トークン（フェーズ2 — CLI）

hyperframes figma tokens <fileKey>

変数をコンポジションブランド変数エントリ + figma-tokens.jsonサイドカー + バインディングインデックスレコード（.media/figma-bindings.jsonl）としてインポートします。変数は上流でEnterpriseゲートされています。他のプランでは、コマンドは公開スタイルのメタデータにダウングレードします（値はコンポーネントインポート時に解決されます）。出力されたエントリをコンポジションのdata-composition-variablesに追加します。

両方が必要な場合は、コンポーネントの前にトークンをインポートします — これにより、コンポーネントの色が重複を焼き付ける代わりにブランド変数にリンクできるようになります。

非Enterprise変数パス（フィールドテスト済み）: REST変数はEnterpriseゲートされていますが、互換性のあるコネクタが変数定義を提供する場合があります。tokensがREQUIRES_ENTERPRISEを報告し、コネクタが利用可能な場合は、親シーンの変数を一度取得し、生のレスポンスを.media/figma-cache/にキャッシュし、それを使用してバインディングインデックスを構築します。RESTノードツリーのboundVariablesは、プロパティごとにVariableIDを提供します。ノードとプロパティでそれらを結合し、.media/figma-bindings.jsonl行（{kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<name>", version}）とコンポジション変数エントリを書き込みます。下流のすべて（コンポーネントのvar()解決、リフレッシュ、ランタイムCSS変数）は、出荷されたメカニズムです。ユーザーに次のように説明します: 「Figmaコネクタ経由のトークン — Enterpriseプランではhyperframes figma tokensから直接取得できます。」

ランタイムは、宣言されたすべてのコンポジション変数をCSSカスタムプロパティ（ドキュメントルート+サブコンポホスト）として定義するため、インポートされたvar(--slug, literal)は、変数のデフォルトが変更されたときに色の変更を埋めます。data-composition-variablesの1つの値を更新すると、何も再インポートせずにすべてのインポート済みコンポーネントがリブランドされます。hyperframes render --variables '<json>'はレンダリング時にそれらをオーバーライドします。

コンポーネント（フェーズ3 — CLI）

hyperframes figma component '<url-or-fileKey:nodeId>'

ノードツリー → 正確なFigmaジオメトリの編集可能なHTML、compositions/components/<name>/の下のレジストリアイテムとしてパッケージ化されます。ベクター/ブール演算はフェーズ1のエクスポートを介して自動ラスタライズされます。バインディングパス（仕様 §7.1、正確なIDのみ — 値のマッチングは決して行いません）:

• 静的忠実性セルフチェック（ヒーローコンテンツには必須）: インポート後、フラグメントをレンダリングし、Figma自身のピクセルと比較します — figma asset <同じノード> --format pngがグラウンドトゥルースです。テキストは既知のドリフト軸です。行の高さよりも短いFigmaテキストボックスは、垂直方向にトリミングされた境界です（マッパーはこれらに対してtext-box-trimを出力します。これがない場合の測定されたドリフトは、70pxフォントで約6pxでした）。比較がマッパーがカバーしていないドリフトを示す場合は、報告してください — フラグメントをサイレントに手動調整しないでください。
• インポートされたトークンにバインドされた塗りつぶし → var(--slug, #literal) — ブランドリフレッシュが伝播します。
• 不明なトークンにバインドされた塗りつぶし → リテラル + data-figma-unresolvedフラグ。コマンドが通知します。ユーザーに提案します: ソース（またはライブラリ）ファイルでtokensを実行し、コンポーネントを再インポートしてリンクします。未知のライブラリごとに、それがどのファイルかを一度だけ尋ねます — 推測したり、16進数でマッチングしたりしないでください。

モーション（フェーズ4 — コネクタアシスト）

使用ビーコン: コネクタアシストフェーズにはCLIタッチポイントがないため、開始時と終了時にスキルビーコンを発行します（匿名、同意ゲート、失敗しない）: 開始時にnpx hyperframes events --skill=figma-motion、終了時にnpx hyperframes events --skill=figma-motion --event=skill_completed --outcome=success|error。シェーダー（figma-shaders）とストーリーボード（figma-storyboard）も同様です。

RESTの同等物はありません。互換性のあるコネクタが利用可能な場合は、それを使用して出力を@hyperframes/core/figmaの純粋なヘルパーに渡します。それ以外の場合は、ネイティブエクスポートを要求します:

1. 親フレームのモーションコンテキストを、要素ごとに1つのリクエストではなく、1つの再帰的なリクエストで取得します。生のJSONをプロジェクトの隣（.media/figma-cache/）に保存して、再翻訳が無料になるようにします。
2. @hyperframes/core/figmaのmotionContextToDocs(rawResponse, { selectorFor, repeat })を使用してMotionDocに正規化します — キーフレーム番号を手動で書き写さないでください。ヘルパーは、フィールドテスト済みのデコードルールを機械的にエンコードします。motion.devスニペット（信頼性の高いエンコーディング — CSSスニペットは持続時間を引き伸ばし、矛盾する可能性があります。これらは無視されます）を解析し、ループラップテールキーフレーム（時間≈0.9999→1のサブミリ秒セグメントはループの瞬間的なリセットであり、作成されたモーションではありません — ラップはrepeat再起動によって実現されます）を除去し、ベジェイージングをそのまま保持します。selectorForはフェーズ3のコンポーネントインポートからのIDを返す必要があります — ノード名からセレクターを導出しないでください。 2b. 完了と判断する前にグラウンドトゥルースに対して検証する — 必須: 利用可能なコネクタを通じてコホートのルートフレームをエクスポートし、node <SKILL_DIR>/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Yを実行します — モーションエネルギーのデルタを比較し（静的インポートの忠実性は相殺されます）、15dBの最小モーションPSNRを下回ると失敗します（キャリブレーション済み: 忠実≈20以上、乖離≈5）。--cropはレンダリングの実際のカードエッジから測定し、推測しないでください。FAILは、しきい値ではなく、翻訳を再確認することを意味します。
3. motionToGsap(doc) → emitTimelineScript(spec) → GSAP + CustomEase CDNタグの後に<script>として注入します。一時停止、有限、リテラルキーでwindow.__timelinesに登録されます。
4. 翻訳不可能なトラック（シェーダー駆動、サポートされていないプロパティ、複雑なマスク） → コネクタを通じてエクスポートし、MP4をフリーズしてから、<video class="clip">として埋め込みます。例外: シェーダー駆動トラック — Figmaのエクスポートパスはシェーダーをベースカラーにフラット化します（以下のシェーダーを参照）。そのため、ベイクはサイレントにシェーダーを失います。代わりにユーザーにネイティブのFigmaエクスポートを依頼してください。使用したパスとその理由を常に説明してください。マップされたセット外の名前付きイージングはリニアにフォールバックします — マッピングテーブルはmotionEase.tsにあります。フォールバックが発生した場合は、ユーザーにフラグを立ててください。
5. 完了と判断する前にnpx hyperframes checkを実行します。

シェーダー（フェーズ5 — 主に手動）

Figmaのコネクタレンダリングパスはシェーダーを実行しません（ベースカラーにフラット化します）。シェーダーソースは、ライブラリ公開スタイル（有料Fullシート）の場合にのみ到達可能です。デフォルトパス: ユーザーにFigmaでシェーダーフレームをネイティブにエクスポート（PNGまたはモーションMP4）してもらい、フェーズ1のアセット/クリップとしてインポートします。コネクタでシェーダーのピクセルキャプチャを試みないでください — サイレントに間違った結果を生成します。

ストーリーボード（シーンフレームのSECTION → アニメーション）

基本ルール: ストーリーボードフレームはキーフレームであり、スライドではありません。 同じ要素を含む2つのフレームは、時間の経過によるその要素の状態を記述します。フレーム間で要素をアニメーション化します。フレームを静止画のシーケンスとして再生しないでください。下降するyで4つの連続するフレームに描かれたロゴは、4つのキーフレームを通じて上昇する1つの要素です。ストーリーボードフレームを連続して再生することは失敗モードです。それらが示唆する要素のタイムラインを再構築することが仕事です。

ストーリーボードファイルは機械的に解析できる文法に従います — 目視せず、デコードしてください:

1. シーンユニット: SECTION内で、フレームサイズのすべてのノードはシーンです — 名前付きFRAMEと、ルーズな全フレームRECTANGLEの両方（デザイナーがセクションに静止画を直接貼り付けます）。ノードタイプや名前ではなく、サイズ（≈ コンポジションアスペクト、例: >1400×900）でフィルタリングします。
2. 順序 = x位置（ストリップが折り返す場合は行優先）。absoluteBoundingBox.xでシーンをソートします。
3. 隣接するシーンを差分比較します:
   • 各シーンを、フェーズ1のアセットエクスポート（hyperframes figma asset、いくつかの参照をバッチ）を使用して静的アセットのセットとしてエクスポートします。
   • フェーズ3のコンポーネントインポート（hyperframes figma component）を使用して、各ノードをHTML構造としてインポートします。
   • 各シーン内で、前のシーンと比較して、変更された、追加された、または削除された要素を特定します。
   • 同一の要素（同じnodeId）は、その要素の新しいキーフレーム状態を表します。変更されていない要素は、そのキーフレーム間で補間する必要があることを示します。
   • キーフレーム遷移のマップを構築します: 要素ごとに、その状態が変化するシーンインデックスのリスト。
4. タイムラインの組み立て:
   • 各シーンにタイムスタンプを割り当てます（等間隔、またはユーザーが指定した場合）。
   • 各要素について、そのキーフレーム状態を持つシーンをモーションキーフレームに変換します。
   • フェーズ4のモーションヘルパーを使用してGSAPタイムラインを生成します。motionContextToDocsはありません — 代わりにbuildStoryboardTimeline(elementKeyframes, sceneTimestamps)を使用します。
   • 補間: 変化するプロパティ（位置、サイズ、不透明度、色）に対して、GSAPのto()/fromTo() tweensを生成します。同一要素の連続するキーフレーム間のイージングは、デフォルトで"power2.out"と仮定します（明示的でない場合）。
5. フェーズ4の検証手順（verify-motion.mjs）とnpx hyperframes checkを実行します。
6. 結果をユーザーに説明します: 「4つのキーフレームシーンから、上昇しフェードインするロゴとスライドして表示されるテキストブロックをアニメーション化しました。」

重要な考慮事項:

• ストーリーセクションには、Figma変数バインディングを持つコンポーネントが含まれる場合があります。フェーズ2のトークンインポート（該当する場合）の後に実行して、カラーリンクが機能するようにします。
• パフォーマンス: バッチアセットエクスポートとコンポーネントインポート。個々のノードのリクエストは避けてください。
• エラーハンドリング: ストーリーボードに翻訳できない要素（ビデオ、埋め込みシェーダー）が含まれている場合、それらをプレースホルダー（ボックス+ラベル）としてマークし、続行します。

一般的な指示

• すべてのステップを説明します: 各コマンドの前に、何を取得しようとしているか、なぜかをユーザーに伝えます。各コマンドの後、アーティファクトがどこに保存されたか、コンポジションで何が変わったかを伝えます。
• トークンをコンポーネントの前にインポートします（両方が必要な場合）。
• アセットをバッチ処理します: 特にアセットとコンポーネントの場合、同じファイルから多数のノードを1回の呼び出しでインポートします。
• レート制限: 429が発生した場合、自動リトライが処理します。リトライ後も続く場合は、より少ないノードを取得するか、1分待ちます。
• 未解決のバインディング: コンポーネントに未知のトークンへのバインディングがある場合、ユーザーにtokensの実行を提案しますが、推測しないでください。
• ストーリーボードの差分比較: 常に隣接するシーンを比較して変更を特定し、すべてを独立した要素として扱わないでください。
• シェーダー: コネクタキャプチャは避けてください。常にユーザーにネイティブのFigmaエクスポートを依頼してください。
• 安全チェック: すべてのフェーズの後、特にモーションとストーリーボードの後は、npx hyperframes checkを実行します。