Figma → HyperFrames

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

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

Figma → HyperFrames は何をしますか？

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

フェーズ	内容	転送方式	サーフェス（CLI コマンド）
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は自動的にリトライします（毎分制限、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分待つか、呼び出しごとにインポートするノード数を減らしてください。

レート制限の認識（仕様 §2.1）： コネクタのクォータはFigmaのプランによって異なります — 親フレームのリクエストをバッチ処理し、確認用スクリーンショットは要求がない限りスキップし、生のレスポンスをキャッシュして再導出が2回目の呼び出しを消費しないようにします。RESTは毎分あたり（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を推奨（スケーラブル、アニメーション可能）、ラスターの忠実度には --scale 2 のPNG。常に --description "<内容>" を渡す（それがインデックス行 + <img alt> になります）。名前付きブランドマークには --entity "<名前>" を追加。これにより、メディア使用の resolve --entity が後でそれらを見つけられます（エンティティヒットは画像/アイコン間で一致します）。

複数のノードを1つのリクエストにバッチ処理 — 同じファイルの複数の参照（スペース区切りまたはカンマ結合）を渡します： hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'。すべてが単一の /v1/images 呼び出しでレンダリングされます。これは、Figma自身の1分あたりのレート制限に対する答えです — フレーム全体のアセットを取得する場合は、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 <same node> --format png が真値です。テキストが既知のズレ軸です：行の高さより短いFigmaテキストボックスは、垂直方向にトリミングされた境界です（マッパーはこれらに対して text-box-trim を出力します。これがない場合の測定されたズレは、70pxフォントで約6pxでした）。比較でマッパーがカバーしないズレが示された場合は、それを報告してください — フラグメントを黙って手動調整しないでください。
• インポート済みトークンにバインドされたフィル → var(--slug, #literal) — ブランドリフレッシュが伝播します。
• 不明なトークンにバインド → リテラル + data-figma-unresolved フラグ。コマンドはそれを通知します。ユーザーに提案：ソース（またはライブラリ）ファイルで tokens を実行し、コンポーネントを再インポートしてリンクします。未知のライブラリごとに1回だけ、それがどのファイルかを尋ねます — 決して推測したり、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のアセット/クリップとしてインポートします。シェーダーのコネクタピクセルキャプチャを試みないでください — 静かに間違った結果を生成します。

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

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

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

1. シーンユニット：SECTION内では、フレームサイズのすべてのノードはシーンです — 名前付きFRAMEと、ルーズな全フレームRECTANGLE（デザイナーが静止画をセクションに直接貼り付ける）の両方。サイズでフィルタリングします（≈ コンポジションアスペクト、例：>1400×900）。ノードタイプや名前ではフィルタリングしません。
2. 順序 = x位置（ストリップが折り返す場合は行優先）。absoluteBoundingBox.x でシーンをソートします。
3. 隣接するシーン間の差分（正確 — 「50%異なる」などの曖昧な用語は禁止）：各シーンをHTML文字列としてレンダリングし、diff-match-patch を使用して文字列を比較します（インポートされたコンポーネントのキーでインデックス付けされ、FigmaノードIDによって解決されます）。要素がシーン間で変化しなかった場合、それはその要素のキーフレームではありません。変化した要素のみがキーフレームになります。DOMが安定している（追加/削除はキーフレームの挿入/削除）場合、diffはタイムラインマーカーに直接マッピングされます。
4. タイムラインアセンブリ：すべての独立した要素（交差しないサブツリー）は、そのキーフレームから並行タイムラインを取得します（開始時間0、持続時間はシーンの総数に合わせてスケーリング）。GSAPタイムラインは、各プロパティに keyframes: [...] を使用して fromTo() チェーンとしてエンコードします。
5. 検証：タイムラインをレンダリングし、出力をコネクタ駆動のモーションパスからのグラウンドトゥルースと比較します（上記の検証スクリプトと同じ — これはモーションパイプラインの残りの部分と交換可能になるように設計されています）。

常にシナリオをラベル付けします：「Figmaのストーリーボードセクション → [N] シーン → [M] 要素タイムライン（スライドショーではありません）。」

各コマンドの前に hyperframes figma asset を呼び出して、すべてのシーンのキーフレーム静止画をフリーズします — これによりグラウンドトゥルース比較が高速化され、再レンダリングが発生しません。

スキル境界と明示的なルーティング

• figma スキルは意図を次のようにルーティングします：静的アセット、ブランドデータ、コンポーネントHTML生成、コネクタ利用可能時および希望的観測がある場合のモーション再構築、シェーダーハンドリング、ストーリーボードパース。
• figma export はスタンドアロンで存在し、ここでは使用しません。別のスキルです。
• このスキルは、Figma Variables（Enterprise）と公開スタイル（すべてのプラン）に対して推論します — tokens コマンドを適切に方向付けます。
• コネクタとRESTの分割は、ユーザーに対して隠蔽されます — 異なるように見えるルーティングの痕跡を除外します。すべてのパスはアセットをローカルにフリーズし、マニフェストに追加します。
• キャッシュ管理：.media/figma-cache/ が保持する生のレスポンスは、ソースでの変更を検出するために fileVersion フィールドを使用します — コードをそれに一致するように更新してください。version フィールドを持たないキャッシュされたレスポンスは新しいものとして扱われ、再取得されます。

検索と置換 — ライブラリファイルの装飾

時々、ユーザーは「私を助けて」とだけ言いますが、彼らが欲しいものを特定しません。このスキルを呼び出す前に、listFigmaFiles を使用して利用可能なFigmaファイルを一覧表示します（REST：GET /v1/me/files — 最近のプロジェクトを返します）。ユーザーに選択してもらい、次にルーティングします。

このスキルを利用可能な場合のみアクティブ化します。

アクティブ化ルール

アクティブ化条件：

• ユーザーが figma.com、figma.com/file/、figma.com/community/file/ のURLを共有した場合。
• ユーザーがFigmaデザインを持ち込むよう依頼した場合：「Figmaからロゴをインポート」、「このデザインを動画にしたい」、「Figmaフレームをコンポジションに変換」、「ブランドカラーを同期」、「このアニメーションをFigmaから取得」または同様のバリエーション。
• ユーザーがファイルキー（例：abc123）またはファイルキー:ノードID（例：abc123:1-2）を明示的に提供した場合。
• ユーザーがFigmaストーリーボードまたはアニメーションフレームについて言及した場合。

非アクティブ化条件：

• Fitz、Penpot、Sketch、Adobe XDなどの他のデザインツールについての言及。
• Figmaに関する一般的な議論で、インポートやファイル参照がない場合。
• 動画/モーションの編集やエクスポートについての抽象的または非Figmaの質問。