1仕組みと動作原理
「Figma → コンポジション」の処理を機能ごとに5つのフェーズ（静的アセット / ブランドトークン / コンポーネント / モーション / シェーダー）に分割。前3フェーズはREST + CLIを使用し、後2フェーズはRESTに対応するものがないためコネクタまたはネイティブエクスポートに依存します。
skills/figma/SKILL.md
Bring the user's Figma work into a composition. **Split by capability** (design spec §2):
フェーズ表にて各ステップのTransportとSurfaceを行単位で定義し、「どのステップでどの認証情報を使用するか」を明確に取り決め、障害発生時にどのフェーズで何の認可が不足しているかを明示できるようにしています。
RESTをデフォルトの通信経路（バッチ処理・ヘッドレス実行対応）とし、コネクタはモーション/シェーダー用のオプションとして位置づけます。レンダリングの決定性を保証するため、どちらの経路でもインポート時にアセットをローカルへ凍結します。
skills/figma/SKILL.md
REST is used wherever it can be (usable at volume, headless). A compatible Figma connector is optional for motion and shader data; without one, ask for a native export. Every path freezes assets locally so renders stay deterministic.
「レンダリング時のゼロネットワーク」をハードな制約とし、通信コストはインポート時に一括して支払います。コネクタの欠如は処理の失敗ではなく、グレースフルなデグレードパスとして扱います。
最初のステップではコマンドを実行せず認証情報の事前確認を行います。シェル環境またはプロジェクトの.env内に読み取り専用のFIGMA_TOKENが存在することを確認し、未設定の場合は一度だけセットアップを案内して停止します。「とりあえず実行してエラーを拾う」ことは禁止します。
skills/figma/SKILL.md
**Preflight — before the first CLI call, check a token exists**: shell env (`[ -n "$FIGMA_TOKEN" ]`) **or** the project `.env` (the CLI auto-loads it — a `.env` entry counts as configured).
認証情報の取得を試行錯誤から事前検証へと変更。同セクションで401/403/429のセマンティクス（BAD_TOKEN / 不足スコープを示すFORBIDDEN / REQUIRES_ENTERPRISE / 自動バックオフ済みのRATE_LIMITED）を定義しています。
アセットインポートは「冪等性・凍結・トレーサビリティ」を徹底します。fileKey:nodeId:format:scale:versionに基づいて冪等性を保ち、生成物は.media/images/に配置し、ソース情報をmanifestに記録してmedia-useの共有インデックスを再構築します。
skills/figma/SKILL.md
Idempotent per `fileKey:nodeId:format:scale:version`.
同セクション冒頭の「Renders over REST, sanitizes SVG, freezes under `.media/images/`, appends the manifest with provenance」に基づき、1回のインポート処理で再実行性、追跡性、関連スキルからの検索性を同時に満たします。
フレーム全体のアセット取得時は複数ノードを単一の/v1/imagesリクエストに統合して分あたりのレート制限を回避します。逆に絵コンテの一括エクスポートはチャンク分割します（12個を超えるIDではレンダータイムアウトが発生するため、約4個ずつに分割）。
skills/figma/SKILL.md
All render in a single `/v1/images` call, which is figma's own answer to the per-minute rate limit
実測に基づいて導き出された対照的なパラメータ調整ノウハウとその理由を明記し、後からの不適切な「最適化」を防いでいます。
コンポーネントフェーズではノードツリーを幾何学的に正確な編集可能HTMLへ再構築し、「値ではなくIDに基づく」トークンバインディングを実行します。インポート済みトークンにはvar(--slug, literal)をバインドし、未知のトークンはリテラル値を維持しつつフラグ付けします。
skills/figma/SKILL.md
Bound to an **unknown** token → literal + `data-figma-unresolved` flag.
予期せぬ誤バインドを招くカラーコード値の推測を明示的に禁止します。また、ヒーロー要素に対してはfigma assetからエクスポートした同一ノードのPNGを基準とするピクセル単位の自己検証を義務付けています。
モーションフェーズは「機械的デコード + 客観的ゲートチェック」を採用。コネクタから取得したモーションコンテキストは純粋なヘルパーでデコードし（手動でのキーフレーム転記を禁止、ループ折り返し末尾フレームを除去）、verify-motion.mjsでエクスポート動画のモーションエネルギーを比較し、15dB未満は不合格とします。
skills/figma/SKILL.md
it compares motion-energy deltas (static import fidelity cancels out) and fails below 15dB min motion-PSNR
「似ているかどうか」の主観的評価を再現可能な数値基準へと変換。失敗時は閾値を調整するのではなく、トランスレーションロジックの再確認を義務付けます。
絵コンテセクションは推測ではなく機械的構文に従ってデコードします。サイズでシーン単位をフィルタリングし、x座標で順序付け、隣接フレームの差分から要素チェーンを導出し、各チェーンにつき1つのアセットのみをエクスポートします。各フレームが同一UIである場合は「UIの再構築 + フレーム差分を1インタラクションとして扱う」アプローチへ昇格させます。
skills/figma/SKILL.md
**The cardinal rule: storyboard frames are KEYFRAMES, not slides.**
最も頻繁に見られる失敗パターン（絵コンテをスライドショーとして再生すること）を禁止事項として規定し、要素チェーンからアプリ再構築への昇格基準（code what changes state, freeze what doesn't）を提供します。
2コア機能
01Figmaアセットインポート: RESTレンダリング → SVGサニタイズ → .media/images/への凍結 → manifest台帳への記録 → .media/index.mdの再構築 → imgスニペットの出力（fileKey:nodeId:format:scale:versionに基づく冪等性を担保）
02複数ノードの一括アセット取得: 同一ファイル内の複数ノードを単一の/v1/images呼び出しに統合。--descriptionは必須、media-useのresolve一致用に--entityを提供
03ブランドトークン/変数のインポートとランタイムテーマ切り替え: コンポジション変数 + figma-tokens.json + .media/figma-bindings.jsonlバインディングインデックス。非Enterpriseプラン時はpublished stylesへ自動デグレード
04コンポーネントインポート: ノードツリー → 幾何学的に正確な編集可能HTML。compositions/components/<name>/配下のレジストリエントリとしてパッケージ化。ベクターやブーリアン演算はPhase-1の自動ラスタライズを適用
05verify-motion.mjsによるモーション再現性ゲートチェック: フレーム差分抽出後のモーションエネルギーPSNRを比較。デフォルト閾値は15dB、--cropでカード領域を指定可能
06絵コンテセクションの再構築: サイズによるシーン単位のフィルタリング、x座標ソート、隣接フレーム差分による要素チェーン抽出、監督指示メモのトランジション語彙へのマッピング、一括エクスポートのチャンク分割
07シェーダーパイプライン: コネクタによるピクセルキャプチャ（シェーダーが単色背景に統合されるため）は行わず、ユーザーにネイティブエクスポートを促してアセット/クリップとしてインポート
08決定論的な終了処理: コンポジション内にFigma URLを残さない、repeat: -1を使用しない、タイムラインを一時停止状態にし、リテラルキーで登録する
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| cli | hyperframes CLI 的 figma 子命令（asset / tokens / component）与 check 门禁 |
| api | Figma REST 批量渲染导出（host 未在 SKILL.md 出现，只写了路径） |
| api | Figma REST published-styles 回退（非 Enterprise 变量降级路径，需 library_content:read） |
| network | 用户粘贴的 figma.com 链接（解析 fileKey / nodeId 后走 REST）；取 token 的引导页在 figma.com/settings |
| network | 可选的兼容 Figma 连接器（运动上下文与着色器数据；与本 skill 的 token 分开授权；未指名具体服务） |
| package | @hyperframes/core/figma 纯 helper（motionContextToDocs 解码、motionToGsap、emitTimelineScript） |
| cli | ffprobe / ffmpeg（仅 verify-motion.mjs 以数组参数子进程调用，抽帧与 PSNR） |
| network | GSAP + CustomEase CDN（注入合成 HTML 的 script 标签；产物期由浏览器拉取，按范式不判级） |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトまたはコマンドの実行: node skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --rend
- 网络端点: 外部ネットワークアクセスの宣言: Figma REST 読み取り専用API呼び出し（/v1/images バッチエクスポート、/v1/files/:key/styles フォールバック、node tree、variable
- 本地工作目录: ファイルの読み書きと成果物出力: .media/images/（凍結されたFigmaレンダリングアセット）、.media/manifest.jsonl（ソース来歴台帳）、.media/index.md（
監査ノート： オレンジ区分に分類された主な要因は**認証情報の取り扱い**です。本スキルの宣言内容（SKILL.md記載事項）はFIGMA_TOKENを前提条件としており、シェル環境またはプロジェクトの.envのいずれもサポートし、CLIが.envを自動読み込みすることを明記しています。このトークンを用いてFigmaのノードツリー、変数、モーションコンテキストをRESTまたはコネクタ経由でローカルプロジェクト（およびモデルのコンテキスト内）に取り込みます。先行事例（product-launch-video / ~/.heygenを読み取るmedia-use）と同様にオレンジと判定されます。同時に、リスク軽減の理由も記録されています。トークンは最小限の読み取り専用スコープであり、Figmaへの書き込みや会話ログへのトークン出力を厳格に禁止しています。付属の検証スクリプト（verify-motion.mjs）は認証情報を一切読み込まず、ネットワーク接続も行わず、ローカルファイルに対して固定のffmpeg/ffprobeバイナリを呼び出すのみです。TLSのダウングレード、自動化検出の回避、任意のコード実行、隠蔽スクリプトなどは確認されず（レッドには該当しない）、また「固定の公開エンドポイントへの問い合わせ」というイエロー区分の特徴にも該当しません。トリガー条件: ユーザーが実際にFigmaからのインポートを要求した場合にのみ、認証情報およびREST処理が実行されます。
5二重目の独立検証
- [ok] FIGMA_TOKEN 是否真被读取并用于外发（橙档判定的关键证据） — SKILL.md 第 26 行给出预检（`[ -n "$FIGMA_TOKEN" ]` 或项目 .env），第 28–30 行给出取 token 的一次性设置与「never ask them to paste the token into the conversation」；第 36 行给出 401/403/429 的处置语义。读取与实际 REST 调用发生在官方 hyperframes CLI 侧，本 skill 的目录只声明并约束该行为——与 hyperframes-cli 同口径，故橙档依据记在 SKILL.md 的声明面，并注明执行主体。
- [unlocatable] Figma REST 的具体 host 能否在源码内定位 — SKILL.md 只写出路径（`/v1/images`、`/v1/files/:key/styles`），未出现 api.figma.com 或任何 host；连接器也未指名具体服务。故 external_deps.endpoint 按「仅路径」标注，不补写推测域名。
- [ok] verify-motion.mjs 的外部接触面（是否有隐藏网络/凭证/越界写入） — 全文 154 行只 import node:child_process / node:fs / node:os / node:path；调用为 execFileSync("ffprobe", …)、execFileSync("ffmpeg", …)、spawnSync("ffmpeg", …) 三处，全部数组参数无 shell；无 fetch、无 process.env、无凭证；写入仅限 mkdtempSync(join(tmpdir(), "verify-motion-")) 下的临时图，结束 rmSync 清理。阈值与标定写在文件头注释里（忠实 min 20.3dB / 发散 min 5.0dB，默认阈值 15dB）。
- [ok] 「连接器不执行 shader、会压平」这一关键警告是否自洽（会不会是夸大） — Phase 5 段与 Phase 4 步骤 4 的例外说明互相印证：两处都指向「请用户原生导出」，且 Phase 4 明确 shader 轨道烘焙会静默丢 shader。属同一声明的两处一致陈述，非矛盾。
- [ok] 「分镜帧是关键帧而非幻灯片」是否只是口号 — 同一段给出可机械执行的规则：场景单元按尺寸（如 >1400×900）过滤、顺序按 absoluteBoundingBox.x、相邻帧按 name 再按几何相似匹配成元素链、每链一资产、批量导出分块（~4/次，26 场景 ≈52 次单资产调用是反面教材），并给出升级判据（同一 UI 逐帧 → 重建 app、把帧差当作交互）。
6結論
最適な用途： 既存のFigmaデザインをHyperFramesコンポジションへ体系的にアセットとして移行したいユーザーに最適です。ロゴ・アイコン・画像のインポート、ブランドトークンの取得とそれに基づくコンポーネントの動的スタイリング、デザインフレームからの編集可能HTMLコンポーネントの再構築、FigmaアニメーションのGSAP変換、絵コンテ（一連のシーンフレーム + 指示メモ）からのキーフレームアニメーション再構築などをカバーします。また、Figmaアニメーションの再現性検証（モーションPSNRゲートチェック）を必要とするワークフローにも適しています。
不向きな用途： 以下には適していません: ① Figmaアカウント/ワークスペースがない、または読み取り専用トークンを取得できない環境（第1フェーズで停止します）；② レンダリング時にFigmaから直接読み込もうとする運用（ローカルへのアセット凍結を強制し、レンダリング中のネットワーク接続を禁止します）；③ Figmaのシェーダー効果を自動再現することを期待するシナリオ（コネクタはシェーダーを実行できないため、手動ネイティブエクスポートが必要です）；④ Figmaを単なるスクリーンショットのスライドショーとして再生したいだけのユーザー（絵コンテはキーフレームとして再構築するのが厳格なルールです）；⑤ 公式のhyperframes CLIを使用しない環境（本スキルの全操作はこのCLIに依存しています）。
Install Agent-Ready
① Verified Mirror 2026-09-28
Option A · Direct DownloadDownload figma.tar.gz
sha256:
Option B · Copy Guide for Agent22ae9717e5a19361…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d2f0bc7f34.