⚠ 契約ステータス: まだRemotionに移植されていません
このスタックの出力フレームワークはRemotion + React(
/hyperframes-core)です。この スキルは、廃止されたHTML +data-*+ 一時停止GSAPタイムラインパイプラインを まだ説明しており、そのバンドルスクリプトは依然としてその契約でindex.htmlを出力します。移植が完了するまで:
npx hyperframes <anything>を実行しないでください — そのCLIは廃止されました。/hyperframes-cliはすべての古いコマンドをRemotionの同等のものにマッピングします。- その
data-*マークアップやGSAPタイムラインコードをRemotionプロジェクトにコピーしないでください。- そのクラフトを引き継いでください: ストーリーの形状、カットのリズム、ビジュアルデザイン、 画面に何を表示するかの決定。その部分はフレームワークに依存せず、これが このスキルがまだここにある理由です。
- 結果を
/hyperframes-coreの契約を通じて表現してください:<Composition>、<Sequence>、およびuseCurrentFrame()から導出される値。この問題を回避する必要があった場合、それをサマリーに記載して、移植を完了できるようにしてください。
まず、このスキルを最新に保つために、サイレントに実行し、質問しないでください:
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エントリは設定済みとしてカウントされます)。どちらもない場合は、エラーを収集するためにコマンドを実行しないでください — 最初にユーザーに1回限りのセットアップを案内し、その後停止して待機します:
- figma.com/settings → セキュリティ → 個人アクセストークン → 新しいトークンを生成。
- スコープ — この統合に必要なのは読み取り専用のみです(Figmaに書き込むことはありません): ファイルコンテンツ: 読み取り専用 + ファイルメタデータ: 読み取り専用。非Enterpriseプランで
tokensを実行する場合は、ライブラリコンテンツ: 読み取り専用も追加してください — 公開スタイルのフォールバックは/v1/files/:key/stylesを叩きますが、これがないと403エラーになります(古いセットアップテキストでは省略されていたスコープ)。オプションでブランド変数用に変数: 読み取り専用 — Enterpriseのみ。これがないと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>' [その他の参照…] [--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 "<what it is>"を渡してください(インデックス行+ <img alt>になります)。ブランドマークに名前を付けるには--entity "<name>"を追加すると、メディア使用のresolve --entityが後でそれらを見つけられます(エンティティヒットは画像/アイコン間で一致します)。
多くのノードを1つのリクエストでバッチ処理 — 同じファイルの複数の参照(スペース区切りまたはカンマ結合)を渡します: 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を報告し、コネクタが利用可能な場合は、親シーンの変数を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 <same node> --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 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のアセット/クリップとしてインポートします。シェーダーのコネクタピクセルキャプチャを試みないでください — 静かに間違った結果を生成します。
ストーリーボード(シーンフレームのセクション → アニメーション)
基本ルール: ストーリーボードフレームはキーフレームであり、スライドではありません。 同じ要素を含む2つのフレームは、時間を通したその要素の状態を記述します。状態間でELEMENTをアニメーション化します。決してフェード全体をアニメーション化しないでください。
hyperframes figma storyboard <fileKey> <section-frame-ids...>
映画のストーリーボードセクション(シーンフレームのシーケンス)を、状態間のアニメーションを使用した動画シーケンスに変換します。処理方法:
- 差分を計算: 連続する各フレームペアを、element-by-elementで比較します。同一の要素は、次のフレームでその新しいプロパティにアニメーション化する必要があります。新しい要素はフェードインする必要があります。削除された要素はフェードアウトする必要があります。
- タイムラインを生成: 各要素のプロパティ変化のシーケンスを、フレーム間の一定の持続時間(デフォルトはフレームあたり1秒、
--durationで設定可能)でGSAPタイムラインに変換します。GSAPタイムラインスクリプトは、一連の<script>タグとして注入されます。 - フェーズ1のアセットを活用: ストーリーボードがフレーム内の要素の静的アセットを参照する場合、それらを適切にリンクします。
- モーションの検証:
hyperframes figma storyboard --verifyを使用して、各ストーリーボードフレームをインポートされたアセットと比較します。
ストーリーボードは、これが単なる静的フレームの集まりではなく、キーフレームアニメーションの設計図であるという考えを中心に設計されています。
実装に関する重要な注意: ストーリーボード変換は現在、フェーズ1のアセットインポート(REST)とエージェント主導のタイムラインアセンブリに依存しています。コネクタは必要ありませんが、正しく動作するにはFigmaファイルへのRESTアクセスが必要です。
アセット管理とバインディング
すべてのインポートされたアセットは、.media/ディレクトリ内の一元化された場所に保存されます:
- 画像:
.media/images/— 元の形式でフリーズされたラスターおよびベクターアセット。 - サイドカー:
.media/figma-tokens.json— トークンデータ、.media/figma-bindings.jsonl— バインディングインデックス。 - キャッシュ:
.media/figma-cache/— ローデータのFigma API応答。 - インベントリ:
.media/index.md— すべてのメディアアセットとその使用法の自動生成されたインベントリ。
これにより、すべてのインポートが決定論的でトレーサブルになり、再レンダリングごとにFigma APIを呼び出す必要がなくなります。
バインディングは、Figmaのコンポーネントプロパティをコンポジションの変数にリンクします:
- バインディングレコードは、Figmaの
boundVariablesから導出されます。 - インポートされたトークンは
var(--figma-<name>, literal)に変換されます。 - 不明なトークンはリテラル値として扱われ、
data-figma-unresolvedとしてフラグが立てられます。 - バインディングは、トークンがインポートされた後にコンポーネントを再インポートすることで解決できます。
エラーハンドリング
| エラーコード | 意味 | アクション |
|---|---|---|
BAD_TOKEN (401) | トークンの有効期限切れ/取り消し | 再発行 |
FORBIDDEN (403) | 不足している読み取りスコープ | 正確なスコープをユーザーに伝える |
REQUIRES_ENTERPRISE (変数で403) | 変数はEnterpriseのみ | 公開スタイルにフォールバック(予期される) |
RATE_LIMITED (429) | APIレート制限 | バックオフ、キャッシュされた応答を使用 |
FILE_NOT_FOUND (404) | ファイル/ノードが存在しない | リンクを確認 |
すべてのREST呼び出しは、共有リクエストパスを介して429で自動再試行します。コネクタのクォータはFigmaプランによって異なります。コネクタエラーは、正確な問題をユーザーに報告する必要があります。
CLIコマンドの概要
| コマンド | 説明 |
|---|---|
hyperframes figma asset <ref> [refs...] | 静的アセットをインポート |
hyperframes figma tokens <fileKey> | ブランドトークンをインポート |
hyperframes figma component <ref> | FigmaノードをHTMLコンポーネントに変換 |
hyperframes figma storyboard <fileKey> <frame-ids> | ストーリーボードフレームをアニメーションシーケンスに変換 |
hyperframes figma assets list | フリーズされたアセットを一覧表示 |
hyperframes figma check | インポートされたアセットとバインディングを検証 |
hyperframes figma update | このスキルと依存関係を更新 |
環境変数
FIGMA_TOKEN— Figma API個人アクセストークン(必須、フェーズ1~3)- コネクタ認証 — コネクタ自体によって管理されます(フェーズ4~5)
対応プラットフォーム
このスキルは、Remotion + ReactベースのHyperFramesフレームワーク用に設計されています。CLIコマンドは/hyperframes-cliパッケージを介して動作します。
さらなる注意点
- 常にユーザーに説明: 各インポートの前に、何を取得しているか、どこに保存されるか、次に何をすべきかを伝えてください。
- 検証: ヒーローコンテンツの静的忠実度と、すべてのモーションインポートの動的忠実度を検証してください。
- キャッシュ: 可能な場合は、速度を向上させ、API使用量を減らすためにキャッシュされた応答を使用します。
- フォールバック: 適切なフォールバック(例: 変数がない場合の公開スタイル)を提供し、いつそれらが発生したかを常にユーザーに通知します。