プラグインインストール: セットアップまたはフレッシュネスコマンドの前に、このスキルが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エントリがあれば設定済みとみなします)。どちらにもない場合は、エラーを確認するためにコマンドを実行せず、まずユーザーに一回限りのセットアップを説明し、その後停止して待機します:
- figma.com/settings → Security → Personal access tokens → Generate new token。
- スコープ — 読み取り専用でこの統合には十分です(Figmaに書き込むことはありません): File content: Read-only + File metadata: Read-only。Enterpriseプラン以外で
tokensを実行する場合は、Library content: Read-onlyを追加してください — 公開スタイルへのフォールバックは/v1/files/:key/stylesにアクセスし、これがないと403エラーになります(以前のセットアップテキストで省略されていたスコープです)。オプションでVariables: Read-only(ブランド変数用、Enterpriseのみ) — これがない場合、tokensは自動的に公開スタイルにダウングレードします(想定内であり、エラーではありません — その旨を伝えてください)。403エラーは、不足している正確なスコープを表示するようになりました。429エラーは自動的にリトライされます(1分あたりの制限、Retry-Afterを尊重します)。 - ユーザーに、シェルプロファイルまたはプロジェクトの
.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でバックオフします。
ルーティング
ユーザーのfigmaリンクをparseFigmaRef(URL、fileKey:nodeId、ベアfileKey)で解析します。その後、意図に応じて:
- "このレイヤー/ロゴ/画像を使う" → アセット(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'。すべてが1回の/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を実行し、コンポーネントを再インポートしてリンクします。不明なライブラリごとに、それがどのファイルかを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つの再帰的リクエストで取得します。生のJSONをプロジェクトの横(
.media/figma-cache/)に保存して、再翻訳が無料になるようにします。 @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を実行します — モーションエネルギーのデルタを比較し(静的インポートフィデリティは相殺されます)、最小モーションPSNRが15dB未満の場合は失敗します(キャリブレーション済み: 忠実≈20+、発散≈5)。--cropはレンダリングの実際のカードエッジから測定し、推測しないでください。失敗は、しきい値ではなく、翻訳を再確認することを意味します。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つのフレームは、その要素の経時的な状態を記述します — フレームの連続する静止画として再生するのではなく、フレーム間のELEMENTをアニメーション化します。連続する4つのフレームに下降Yで描かれたロゴは、4つのキーフレームを通じて上昇する1つの要素です。ストーリーボードフレームを連続再生することは障害モードです。それらが意味する要素タイムラインを再構築することが仕事です。
ストーリーボードファイルは、機械的に解析できる文法に従います — 目視せず、デコードしてください:
- シーンユニット: SECTION内では、フレームサイズのすべてのノードがシーンです — 名前付きFRAME および ルーズなフルフレームRECTANGLE(デザイナーが静止画をセクションに直接貼り付けます)の両方です。ノードタイプや名前ではなく、サイズ(≈ コンポジションアスペクト、例: >1400×900)でフィルタリングします。
- 順序 = X位置(ストリップが折り返す場合は行優先)。シーンを
absoluteBoundingBox.xでソートします。 - 隣接するシーン間の差分を取ります — 子のID/名前が一致するかどうかを確認します。セット演算にはshallow diff(フェーズ3のアセット表現を使用、バインディングは無視)を使用します。
- 各シーンを、マッチングインデックスを介して****フェーズ1アセット**に解決します —
hyperframes figma assetを介してインポートされたフリーズ画像を参照します。フレームがまだインポートされていない場合は、最初にインポートしてください("このストーリーボードのフレームをインポート"を確認、すべてのシーンを1つの呼び出しにバッチ処理)。 - アセット("フレーム1.png"、"フレーム2.png"、...)をタイムラインに配置し、
opacityとtransformのプロパティを0から1にアニメーション化します — 単純なクロスフェード、ストーリーボードのアニメーションインテントがより豊かでない限り。デフォルトのタイミング: フレームあたり500ms、全体で2秒。
- 差分が要素の追加を示す場合(例: フレーム3に新しいロゴ)→ それは新しい要素の出現です(opacity 0→1)。
- 要素が削除された場合(例: フレーム4でロゴが消えた)→ それはその要素の退出です(opacity 1→0、またはtransformでオフセット)。
- 要素が移動した場合(位置が変わった)→
transform: translate(...)でアニメーション化します。 - 設計者のインテントを超えた複雑さを推測しないでください — アニメーションが単純なクロスフェード+移動である場合、派手なイージングやスケール変更を追加しないでください。タイムラインは、フレームが何であるかを反映する必要があります: 要素状態のスナップショット、補間ポイントではありません。
セクション全体のインポート(CLI): プロンプトが複数のフレームを含むセクションを参照している場合は、以下のワンショットコマンドを使用してすべてを同時にインポートしてください:
hyperframes figma storyboard '<url-or-fileKey:sectionNodeId>'
これにより、セクション内のすべてのシーンフレームが(フェーズ1アセットとして)自動インポートされ、ストーリーボードマニフェスト(.media/figma-storyboards.json)が生成され、フェーズ3コンポーネントとしてレンダリング可能なHTMLストーリーボードが組み立てられます。マニフェストは、各フレームのファイルキー、ノードID、順序、および差分情報(他のフレームと比較した要素の追加/削除/変更)を記録します。要素タイムライン(スライドショーではない)としてレンダリングされます。ビルド後にnpx hyperframes checkを実行して、ストーリーボードの整合性を検証します。
エラーハンドリング(仕様 §8.1)
hyperframes figma ...コマンドは、失敗時に非ゼロの終了コードと構造化されたエラーJSONを常に返します。出力をユーザーに再フォーマットするときは、この構造を保持してください:
- 400: リクエストの形式が正しくありません — ユーザーに有効なfigmaリンクまたはfileKeyを提供するように依頼してください。
- 401/403: 認証またはスコープの問題 — 上記の認証セクションを参照して、ユーザーにトークンまたはスコープを修正するように依頼してください。
- 404: ノードまたはファイルが見つかりません — URLを確認してください。
- 429: レート制限 — 自動リトライ後に発生した場合、1分待ってから再試行するようにユーザーに依頼してください。
- 5xx: サーバーエラー — しばらく待ってから再試行するようにユーザーに依頼してください。
コマンドが失敗した場合、部分的な結果(例: バッチ内の一部のアセットがインポートされた)は、成功したアイテムのマニフェストレコードとともに.media/ディレクトリに残ります。失敗したアイテムは、解決後に再試行できます。
重要な注意: npx hyperframes checkは、このスキルの整合性を検証する主要な方法です。すべての主要な操作の後にそれを実行し、すべてが期待どおりに構成されていることを確認します。