まず、このスキルを最新に保つためにユーザーに確認してから実行してください:
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 に書き込むことはありません):ファイルコンテンツ:読み取り専用 + ファイルメタデータ:読み取り専用。非エンタープライズプランで
tokensを実行する場合は、ライブラリコンテンツ:読み取り専用 も追加します。公開スタイルへのフォールバックが/v1/files/:key/stylesにアクセスし、このスコープがないと 403 エラーになります(以前のセットアップ手順では省略されていたスコープです)。オプションでブランド変数用に 変数:読み取り専用 を追加 — エンタープライズ限定です。これがない場合、tokensは自動的に公開スタイルにダウングレードします(予期された動作であり、エラーではありません — そのように伝えてください)。403 エラーは、正確に不足しているスコープを指定します。429 エラーは自動的にリトライされます(分単位の制限、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 分待つか、呼び出しあたりのインポートノード数を減らしてください。
レート制限の認識(仕様 §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>' [さらに ref…] [--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 つのリクエストで複数のノードをバッチ処理します — 同じファイルの複数の 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)としてインポートします。変数は上流でエンタープライズゲートされています。他のプランでは、コマンドは公開スタイルのメタデータにダウングレードされます(値はコンポーネントインポート時に解決されます)。印刷されたエントリをコンポジションの data-composition-variables に追加します。
両方が必要な場合は、コンポーネントの前にトークンをインポートします — これにより、コンポーネントの色がブランド変数にリンクされ、重複が焼き付けられるのを防ぎます。
非エンタープライズ変数パス(フィールドテスト済み): REST 変数はエンタープライズゲートされていますが、互換性のあるコネクタが変数定義を提供する場合があります。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 コネクタ経由のトークン — エンタープライズプランでは hyperframes figma tokens から直接取得されます。」
ランタイムは、宣言されたすべてのコンポジション変数を CSS カスタムプロパティ(ドキュメントルート + サブコンポホスト)として定義するため、インポートされた var(--slug, リテラル) は、変数のデフォルトが変更されたときに塗り替えを満たします。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, #リテラル)— ブランドリフレッシュが反映されます。 - 不明な トークンにバインド → リテラル +
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 skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Yを実行します。これはモーションエネルギーデルタを比較し(静的インポートの忠実度は相殺されます)、15dB 最小モーション PSNR を下回ると失敗します(キャリブレーション済み:忠実 ≈ 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 のコネクタレンダリングパスはシェーダーを実行しません(ベースカラーにフラット化されます)。また、シェーダーソースは ライブラリ公開 スタイル(有料の Full シート)でのみ到達可能です。デフォルトのパス:ユーザーに Figma でシェーダーフレームをネイティブエクスポート(PNG または Motion MP4)してもらい、それをフェーズ 1 のアセット/クリップとしてインポートします。シェーダーのコネクタピクセルキャプチャを試みないでください。静かに間違った結果を生成します。
ストーリーボード(シーンフレームの SECTION → アニメーション)
最重要ルール:ストーリーボードのフレームはキーフレームであり、スライドではありません。 同じ要素を含む 2 つのフレームは、時間を通したその要素の状態を記述します。フレーム間で ELEMENT をアニメーション化します。フレームを一連の静止画として再生しないでください。4 つの連続したフレームに下降する y で描かれたロゴは、4 つのキーフレームを通して上昇する 1 つの要素です。ストーリーボードのフレームを連続して再生することは障害モードです。それらが示唆する要素タイムラインを再構築することが仕事です。
ストーリーボードファイルは、機械的に解析できる文法に従います。目視ではなく、デコードします:
- シーンユニット: SECTION 内では、フレームサイズのすべてのノードがシーンです。名前付き FRAME と、ゆるい全フレーム RECTANGLE(デザイナーが静止画をセクションに直接貼り付ける)の両方です。サイズ(≈ コンポジションアスペクト、例:>1400×900)でフィルタリングし、ノードタイプや名前ではフィルタリングしません。
- 順序 = x 位置(ストリップが折り返す場合は行優先)。
absoluteBoundingBox.xでシーンをソートします。 - 隣接するフレームを差分して要素チェーンを構築します — これがアニメーションが存在する場所です。連続するフレーム間で子を一致させます。最初に 名前(同じ名前 = 同じ要素 → 状態間の相対的な x/y/w/h をトゥイーン)、次に ジオメトリの類似性(同様のサイズと位置、名前が異なるものは無視します — ランタイムがデフォルトで補間する可能性のある再ラベル付けをキャッチするため)。不可能な場合(子の数が完全に異なる)は、未知の要素をその場でフェードイン/アウトします(opacity 0→1、1→0)。
- 各要素チェーンを
buildTimeline(elementChain, { duration: 0.3, ease: "power2.out" })に渡し、ドキュメントごとに 1 つのMotionDocを取得し、上記のモーションパス(フェーズ 4)と同じmotionToGsap/emitTimelineScriptルーチンにフィードします。タイムラインを<script>として注入します。 - 比較レンダリングチェック(必須): アセットエクスポートされたシーンキーフレームと再構築されたトランジションの両方のキーフレームで
verify-motion.mjsを実行します。上記と同じしきい値。失敗 → 要素の一致を再確認し、リニアなトランジションを試し、それでも一致しない場合は、レンダリング結果をユーザーに提示して確認してもらいます。 - 完全にコネクタレスのワークフロー — ストーリーボードは REST エクスポートされたアセット(フェーズ 1)のみに依存します。コネクタは不要です。
ElementRef を介した既存のバインディングは、ストーリーボードの再構築によって新しいインポートをトリガーしません。mediaUse コマンド(hyperframes figma media-use...)を使用して、要素をインポートされたアセットの静的な 参照に接続します。フェーズ 1 のアセットはフリーズされているため、これらのバインディングは決定論的です。
コア設計仮定の詳細については、skill/figma/spec-v2.md のスキル全体の設計仕様を参照してください。