最重要:このスキルを常に最新に保つため、確認なしで以下を実行してください:
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エラーは自動的にリトライします(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分待つか、呼び出しごとにインポートするノード数を減らしてください。
レート制限の認識(仕様 §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 "<名前>"を追加すると、後でmedia-use resolve --entityでそれらを見つけられるようになります(エンティティヒットは画像/アイコン間で一致します)。
多くのノードを1つのリクエストにバッチ処理してください — 同じファイルの複数の参照をスペース区切りまたはカンマ区切りで渡します: hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'。すべてが単一の/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を報告し、コネクタが利用可能な場合は、親シーンの変数を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, リテラル)は、変数のデフォルトが変更されたときに再配色されます。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またはモーションMP4)し、フェーズ1のアセット/クリップとしてインポートするよう依頼してください。シェーダーのコネクタピクセルキャプチャを試みないでください。静かに間違った結果を生成します。
ストーリーボード(シーンフレームのSECTION → アニメーション)
絶対のルール: ストーリーボードのフレームはキーフレームであり、スライドではありません。 同じ要素を含む2つのフレームは、時間経過によるその要素の状態を記述しています。フレーム間で要素をアニメーション化し、フレームを静止画のシーケンスとして再生してはいけけません。4つの連続したフレームで下降するY座標に描かれたロゴは、4つのキーフレームを通じて上昇する1つの要素です。ストーリーボードのフレームを連続して再生することは失敗モードであり、それらが暗示する要素のタイムラインを再構築することが仕事です。
ストーリーボードファイルは機械的に解析可能な文法に従います。目視で判断せず、デコードしてください:
- シーンユニット: SECTION内では、フレームサイズのすべてのノードがシーンです。名前付きFRAMEと、ルーズな全フレームRECTANGLE(デザイナーが静止画をセクションに直接貼り付ける場合があります)の両方を含みます。ノードタイプや名前ではなく、サイズ(≈ コンポジションのアスペクト比、例:>1400×900)でフィルタリングします。
- 順序 = x座標(ストリップが折り返す場合は行優先)。シーンを
absoluteBoundingBox.xでソートします。 - 隣接するフレームを差分して要素チェーンを構築 — ここにアニメーションが存在します。連続するフレーム間で子要素をマッチングします。最初に名前で(同じ名前 = 同じ要素 → 状態間で相対x/y/w/hをトゥイーン)、次にジオメトリの類似性で(類似したサイズ+近接した位置):
computeRectIoU(rect1, rect2) >= 0.5。IoUベースのマッチングは、ノードツリーの並び替えに対して堅牢です。四分木空間インデックスは必要ありません — シーンあたりの平均要素数 < 200のため、総当たりで十分です。 - 同一要素チェーンの補間 → タイムライン: 要素がn個の連続するフレーム(i = 1..n)にわたって存在する場合、それぞれのプロパティ(x, y, width, height, opacity, rotateなど)においてiとi+1間を補間することでタイムラインを構築します。各補間は、ゼロデュレーションキーフレームが連続する同一値のセグメントを示すため、
duration = frameDurationです。frameDurationは推測するか、利用可能な場合はストーリーボードメタデータから取得してください。 - 要素がフレームnで消えた場合 → フェードアウト/出口アニメーション:
opacity: 1 → 0(デフォルトの終了)または、後続のフレームで別の位置に再出現する場合は、最後のフレームのジオメトリを使用します(新しいフレームのエッジの外側に補間)。要素が後続のフレームにマッチしない場合(IoUまたは名前)、それはフレームの開始時に開始する新しい要素です。 - 最終出力: すべての要素タイムラインを含むGSAPタイムライン。マージン、パディング、コンポジションの開始時間を説明するラッパータイムラインでラップします。タイムラインを
data-gsap-timeline属性としてコンポジションに注入します。 - 検証: 出力タイムラインをレンダリングし、ストーリーボードの静止画シーケンスと比較します(フレームnで一時停止)。各フレームで視覚的に同一である必要があります(ピクセル単位で同一である必要はなく、人間が同一と認識できること)。
CLIのタッチポイントはありません。フェーズ4のモーションビーコンパターンを使用します(上記参照)。また、ストーリーボードにはnpx hyperframes checkも必須です。
ストーリーボードがセクションフレームの再構成である場合(上記のルールを参照)、Figma = 静止したまま、セクションを反復し、差分し、アニメーション化します。手動ステップはありません。コネクタは必要ありません。
その他の指示
- 常に
npx hyperframes skills update figmaを静かに実行してからこのスキルを使用してください。コアスキルの更新は内部で処理されます。 - 許可なくスクリーンショットを撮らないでください。
- ユーザーがリンクを貼った場合、リンクをクリックしないでください。リンクからfileKeyを抽出してください。
- テキストノードやその欠落について尋ねる前に、CSSの
text-box-trimを試してください(上記参照)。 - 入力ノードがフレームでない場合(グループ、ベクターネットワークなど)、
--format svgでhyperframes figma assetを試してください。 - ユーザーにファイル名を推測させないでください。デフォルトの名前を使用するか、選択肢を提供してください。
hyperframes figma componentの後にhyperframes renderを自動的に実行しないでください。ユーザーに確認してください。「次に何をしますか?」- コンポーネントを自動的に複製しないでください。ユーザーが
data-entityを要求するか、fileKeyでインポートした場合にのみ複製します。 - 機能しない場合は、恐れずにFigmaのネイティブエクスポートをユーザーに依頼してください。エラーは隠さず、最高の結果を得るための最適な方法について正直になってください。
npx hyperframes checkが存在し、実行可能です。これを呼び出すことは、品質保証の必須ステップです。約束する前に結果を確認してください。
このスキルはDrama2557/4RealDigital-Video-Studioから派生しています。