プラグインのインストール: セットアップまたはフレッシュネスコマンドの前に、このスキルがHyperFramesプラグイン内にある場合は、プラグイン実行ルールに従ってください。スタンドアロンインストールの場合は、以下の更新手順を保持します。
最初に、このスキルを最新の状態に保ってください — ユーザーに確認してから実行:
npx hyperframes skills update figma。すべてが最新の場合は高速なno-opです。それ以外の場合は、このスキルとそれが依存するコアドメインスキルを、それらに依存する前に更新します。
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エントリは設定済みと見なされます）。どちらもない場合は、エラーを収集するためにコマンドを実行せず、ユーザーに一度だけセットアップを説明し、停止して待機します:
- figma.com/settings → セキュリティ → パーソナルアクセストークン → 新しいトークンを生成。
- スコープ — 読み取り専用で、この統合に必要なすべてです（Figmaに書き込むことはありません）: ファイルコンテンツ: 読み取り専用 + ファイルメタデータ: 読み取り専用。非Enterpriseプランで
tokensを実行する場合は、ライブラリコンテンツ: 読み取り専用を追加します — 公開スタイルのフォールバックは/v1/files/:key/stylesにヒットしますが、これがないと403が返ります（古いセットアップテキストで省略されたスコープ）。ブランド変数用にオプションで変数: 読み取り専用 — Enterpriseのみ。これがないとtokensは自動的に公開スタイルに低下します（予期されることであり、エラーではありません — そのように伝えてください）。403は不足しているスコープを正確に示します。429は自動的にリトライします（分単位の制限、Retry-Afterを尊重）。 - ユーザーに
FIGMA_TOKENをシェルプロファイルまたはプロジェクトの.envに設定してもらいます。トークンを会話に貼り付けさせないでください。
オンボーディング中に、一度に期待値を設定します: すべてのインポートは、記録された出典を持つローカル固定ファイルとして配置されます — レンダリングは決して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>' [さらに refs…] [--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つのリクエストにバッチ処理 — 同じファイルの複数のrefを（スペース区切りまたはカンマ区切りで）渡します: hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'。すべてが単一の/v1/images呼び出しでレンダリングされます。これは、分単位のレート制限に対する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回の再帰的リクエストで取得します。生のJSONをプロジェクトの横に保存し（
.media/figma-cache/）、再翻訳が無料になるようにします。 @hyperframes/core/figmaのmotionContextToDocs(rawResponse, { selectorFor, repeat })を使用してMotionDocに正規化します — キーフレーム番号を手動で書き写さないでください。ヘルパーは、フィールドテスト済みのデコードルールを機械的にエンコードします: motion.devスニペット（信頼性の高いエンコーディング — CSSスニペットは継続時間を引き伸ばし、矛盾する可能性があるため、無視されます）を解析し、ループラップテールキーフレーム（時間≈0.9999→1のサブミリ秒セグメントはループの瞬間的なリセットであり、作成者のモーションではない — ラップはrepeatの再起動によって実現されます）を削除し、ベジェイージングをそのまま保持します。selectorForは、フェーズ3のコンポーネントインポートからIDを返す必要があります — ノード名からセレクタを導出しないでください。 2b. 完了と見なす前に、グラウンドトゥルースに対して検証 — 必須: 利用可能なコネクタを介してコホートのルートフレームをエクスポートし、node skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Yを実行します — モーションエネルギーのデルタを比較し（静的インポートの忠実度は相殺されます）、最小モーションPSNRが15dB未満の場合は失敗とします（較正済み: 忠実 ≈ 20+、発散 ≈ 5）。--cropをレンダリングの実際のカードエッジから測定し、推測しないでください。FAILは、しきい値ではなく翻訳を再確認することを意味します。motionToGsap(doc)→emitTimelineScript(spec)→ GSAP + CustomEase CDNタグの後に<script>として注入します。一時停止、有限、リテラルキーでwindow.__timelinesに登録されます。- 翻訳不可能なトラック（シェーダー駆動、サポートされていないプロパティ、複雑なマスク） → コネクタを介してエクスポートし、MP4を固定し、
<video class="clip">として埋め込みます。例外: シェーダー駆動トラック — Figmaのエクスポートパスはシェーダーをベースカラーに平坦化します（以下のシェーダーを参照）。そのため、そこでのベイクは静かにシェーダーを失います。代わりにユーザーにネイティブFigmaエクスポートを依頼してください。使用したパスとその理由を常に伝えてください。マップされたセット外の名前付きイージングは線形にフォールバックします — マッピングテーブルはmotionEase.tsにあります。フォールバックが発生した場合は、ユーザーにフラグを立ててください。 - 完了と見なす前に
npx hyperframes checkを実行します。
シェーダー（フェーズ5 — ほぼ手動）
Figmaのコネクタレンダリングパスはシェーダーを実行しません（ベースカラーに平坦化されます）。シェーダーソースはライブラリ公開スタイル（有料フルシート）でのみ到達可能です。デフォルトパス: ユーザーにFigmaでシェーダーフレームをネイティブにエクスポート（PNGまたはモーションMP4）するよう依頼し、フェーズ1のアセット/クリップとしてインポートします。シェーダーのコネクタピクセルキャプチャを試みないでください — 静かに間違った結果を生成します。
ストーリーボード（シーンフレームのセクション → アニメーション）
基本ルール: ストーリーボードフレームはキーフレームであり、スライドではありません。 同じ要素を含む2つのフレームは、時間を通したその要素の状態を記述します — フレーム間で要素をアニメーション化します。決してフレームを静止画のシーケンスとして再生しないでください。降順のyで4つの連続したフレームに描かれたロゴは、4つのキーフレームを通して上昇する1つの要素です。ストーリーボードフレームを連続して再生することが失敗のモードです。それらが暗示する要素タイムラインを再構築することが仕事です。
ストーリーボードファイルは、機械的に解析できる文法に従います — 目視せず、デコードしてください:
- シーンユニット: SECTION内で、フレームサイズのすべてのノードはシーンです — 名前付きFRAMEも、ルーズな全フレームRECTANGLEも（デザイナーは静止画をそのままセクションに貼り付けます）。サイズでフィルタリングします（≈ コンポジションアスペクト、例: >1400×900）。ノードタイプや名前ではフィルタリングしません。
- 順序 = x位置（ストリップが折り返す場合は行優先）。
absoluteBoundingBox.xでシーンをソートします。 - 隣接するシーン間の差分: 各シーンを（そのノード）としてシリアル化し、前のシーンとの差分を取ります。削除は排除としてマークされません — その要素が単にそのシーンに存在しないことを意味します。差分には、各要素の開始状態と終了状態の両方を含めます。遷移を推測しないでください。
- タイムラインの構築: 各要素について、その状態をシーンインデックス（時間）の関数としてプロットします。アイデンティティはフェーズ3のコンポーネントインポートによって確立されます —
selectorForを介して接続します。リストされている各プロパティ（fills,opacity,effects,transform）を、それらが変化するシーンにわたってトラックします。 - 双一次補間: プロパティが明確なままであるところは、
@hyperframes/core/figmaのinterpolateState(a, b, t)を使用します。不透明度は線形。色はOKLab。変換は行列補間。 - 出力:
@hyperframes/core/figmaのsceneTimelineToGsap(docs)を呼び出します — これは、motionToGsapと同じ出力形式を自動的に生成します。npx hyperframes checkを実行します。 - ユーザーにラベルを付けてください: 「ストーリーボードをキーフレームタイムラインとして再構築しました — スライドショーではありません。」
環境
FIGMA_TOKEN— 読み取り専用Figma PAT。設定されていない場合のメッセージは上記の手順に従います。- プロジェクト
.env— CLIによって自動ロードされます。 - 他のenvはありません。
依存関係
スキル更新によって管理され、ユーザーはこれらを手動でインストールする必要はありません。
@hyperframes/cli— すべてのhyperframes figma *コマンド。@hyperframes/core/figma— モーション、ストーリーボード、バインディングルール用の純粋なヘルパー。
ユーザーへのメッセージングのヒント
- 各コマンドの前に: 「これから[ファイル]から[何を]を取得します。」
- コマンドの後: 「[パス]に固定されました。コンポジションの[X]が更新されました。[次のアクション]を実行できます。」
- 不明な変数: 「トークンからの変数にリンクされていない値が見つかりました。
tokensを実行してからコンポーネントを再インポートしますか？」 - コネクタ認証エラー: 「モーションをインポートするにはFigmaコネクタが必要です。接続されていることを確認するか、ネイティブエクスポートを提供してください。」
- ストーリーボードの説明: 「このストーリーボードはスライドショーとしてではなく、キーフレームアニメーションとして再構築されました。各要素はその状態間で補間されます。」