プラグインインストール: セットアップや更新コマンドを実行する前に、プラグイン実行ルールに従ってください(このスキルが 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 → セキュリティ → パーソナルアクセストークン → 新しいトークンを生成。
- スコープ — この統合で必要なのは読み取り専用のみです(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 ではバックオフします。
ルーティング
ユーザーの 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 "<名前>" を追加して、後で media-use resolve --entity で検索できるようにします(エンティティは画像/アイコン間でマッチします)。
複数のノードを1つのリクエストでバッチ処理 — 同じファイルの複数のリファレンス(スペース区切りまたはカンマ区切り)を渡します: hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'。すべてが1回の /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 を報告し、コネクタが利用可能な場合、親シーンの変数を1回取得し、生のレスポンスを .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>'
ノードツリー → 編集可能な HTML(Figma の正確なジオメトリで)として、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はレンダリングの実際のカード端から測定し、推測しないでください。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つのフレームは、その要素の時間を通じた状態を表します。要素を状態間でアニメーションさせます。フレームを静止画のシーケンスとして再生しないでください。4つの連続したフレームに下降する y で描かれたロゴは、4つのキーフレームを通じて上昇する1つの要素です。ストーリーボードフレームを連続して再生することは失敗モードです。それらが暗示する要素のタイムラインを再構築することが仕事です。
ストーリーボードファイルは機械的に解析できる文法に従います — 目視せずにデコードしてください:
- シーンユニット: SECTION 内で、フレームサイズのすべてのノードはシーンです — 名前付き FRAME と、ゆるいフルフレームの RECTANGLE(デザイナーが静止画をセクションに直接貼り付ける)の両方です。ノードタイプや名前ではなく、サイズ(≈ コンポジションのアスペクト、例: >1400×900)でフィルタリングします。
- 順序 = x 位置(ストリップが折り返す場合は行優先)。
absoluteBoundingBox.xでシーンをソートします。 - 隣接する差分を取る: 各隣接シーンペア(
Si → Si+1)に対して、すべての子孫ノードを ID でマッチングします。マッチしたものはキーフレーム化されます(位置、スケール、回転、不透明度)。欠落しているものは削除され(opacity → 0は配置してフェードアウト)、新しいものは表示されます(opacity 0 → 1はフェードイン)。マッチしなかった子ノードを異なるノードと誤ってマッチングしないでください — マッチングは ID のみで行います。ID のないノード(Figma でグループ化解除されたもの)は、親フレーム内の座標によって推論できます(5px 以内なら同じ要素とみなしますが、ユーザーに ID の喪失と、完璧な再構築には Figma での再グループ化が必要であることを伝えます)。 - ツリー差分をアニメーション化: 各マッチした要素に対して、
keyframeブロックを生成します。補間はマッパーのデフォルト(CSS イージング: 移動にはease-out、スケールにはease-in-out)を使用します — 生成されたアニメーションで Figma の元のイージングを再現しようとしないでください(ストーリーボードにエンコードされていません)。 - オーバーラップとトランジション: 各シーンの出力キーフレームは、次のシーンの入力キーフレームまで持続します。
transition-durationが SECTION で定義されている場合はそれを使用します。定義されていない場合は300msを使用します。古い要素は前のシーンの出力継続時間中にフェードアウトします。 - Check:
npx hyperframes checkを実行します — これは bringing するすべての要素のバインディングが最新であること、タイムライン構文を検証し、compositions/timelines/に出力を保存することを確認します。
ストーリーボード — CLI
hyperframes figma storyboard '<figma-url>' --section "セクション名" [--duration 300] [--ease "ease-in-out"]
SECTION ノードの子を解析し、各子フレーム名付きでマニフェストエントリを生成します。
ストーリーボード — コネクタ支援利用
Figma コネクタが利用可能な場合、アニメーショントラック(タイミンググラフ、トリガー)を抽出します。コネクタの getStoryboardMotions() が生のトラックデータを返します。次に:
- トラックを
motionDocToGsap()で GSAP タイムラインに変換します。 - 手動で構築したタイムラインより優先されます。
- コネクタが利用できない場合は、上記の REST のみのパスにフォールバックします。
使用例
例1: ブランドロゴのインポート
# Figma からロゴを SVG としてインポート
hyperframes figma asset 'abc123:1-2' --format svg --description "会社ロゴ" --entity "brand-logo"
# 出力: .media/images/abc123-1-2.svg に保存、マニフェストに追加
例2: ブランドトークンのインポート
# ファイル abc123 からトークンをインポート
hyperframes figma tokens abc123
# 出力: figma-tokens.json とバインディングインデックスを生成
例3: フレームをコンポーネントとしてインポート
# ノード 1-2 をコンポーネントとしてインポート
hyperframes figma component 'abc123:1-2'
# 出力: compositions/components/MyFrame/ に HTML ファイル
例4: ストーリーボードの構築
# セクション "Scene 1-4" からストーリーボードを構築
hyperframes figma storyboard 'abc123' --section "Scene 1-4" --duration 400
# 出力: キーフレームアニメーションを生成