figma-developer

Figma Developer

概要

Figma REST API を使用して、Figma からコードへの連携を自動化します。デザイントークン（色、タイポグラフィ、スペーシング）を CSS 変数および JSON として抽出し、アイコンを SVG React コンポーネントとしてエクスポートし、Figma ノード構造から React コンポーネントを生成し、デザインを継続的に同期する CI パイプラインを設定します。

使用する場面： Figma のデザイントークンをコードに同期する場合、アイコンセットを React コンポーネントとしてエクスポートする場合、Figma のバリアントからコンポーネントのひな形を生成する場合、CI でデザインの自動同期を設定する場合です。

使用しない場面： 手動で一度だけデザインを調整する場合（値をコピーするだけで十分です）、Figma プラグインを開発する場合（代わりに Plugin API を使用してください）、リアルタイムの共同編集を行う場合（Figma の Webhook を直接使用してください）、Figma のデザインシステムがないプロジェクトの場合です。

クイックリファレンス

パターン	API / アプローチ	主なポイント
ファイルデータを取得	GET /v1/files/:key	スタイルと塗りを含むドキュメントツリー全体を返します
特定のノードを取得	GET /v1/files/:key/nodes?ids=...	必要なノードだけを取得して、ペイロードを減らします
画像をエクスポート	GET /v1/images/:key?ids=...&format=svg	ノードを SVG/PNG/PDF としてレンダリングします。URL の有効期限は 14 日です
スタイルを取得	GET /v1/files/:key/styles	公開済みの色、テキスト、エフェクトのスタイルをすべて一覧表示します
コンポーネントを取得	GET /v1/files/:key/components	メタデータ付きで公開済みコンポーネントをすべて一覧表示します
コンポーネントセットを取得	GET /v1/files/:key/component_sets	コンポーネントのバリアントのグループを返します
変数を取得	GET /v1/files/:key/variables/local	Figma Variables（色、スペーシングなど）を抽出します
変数を公開	POST /v1/variables	ローカル変数を組織全体に公開します
トークンを抽出	ファイルレスポンスからスタイルを解析し、CSS/JSON に変換します	組み込みの「トークン抽出」エンドポイントはありません
CI 同期	GitHub Actions cron + peter-evans/create-pull-request	Figma ファイルの変更時に PR を自動同期します

Figma ファイルの構成

セクション	内容
色	/ 階層構造のすべてのカラースタイル（Primary/500）
タイポグラフィ	テキストスタイル（Heading/Large、Body/Regular）
スペーシング	スペーシングガイドの値
コンポーネント	バリアントのグループ（Button/Primary、Card/Default）
アイコン	エクスポート可能な 1 つのフレーム内にすべてのアイコンを配置

よくある間違い

間違い	修正方法
extractDesignTokens() のような架空の API メソッドを使用する	GET /v1/files/:key のレスポンスからスタイルを手動で解析する
トークンを使わずに Figma の値をハードコーディングする	トークンを CSS 変数として抽出し、var() で参照する
Figma のスタイル名を正規化しない	小文字に変換し、特殊文字をハイフンに置き換える
Figma では RGB が 0～255 ではなく 0～1 であることを忘れる	16 進数に変換する前に 255 を掛けて四捨五入する
API レスポンスをキャッシュしない	レート制限を避けるため、有効期限（TTL）付きでキャッシュする
アイコンを手動でエクスポートする	GET /v1/images/:key と React コンポーネントの生成を自動化する
CI 同期ワークフローがない	GitHub Actions の cron と create-pull-request アクションを使用する
期限切れの画像 URL を使用する	画像のエクスポート URL は 14 日で期限切れになります。使用前に再取得してください

ライブラリ

パッケージ	用途
figma-api	コミュニティ製の Figma REST API クライアント（型付き）
@figma/rest-api-spec	Figma API の公式 TypeScript 型定義
style-dictionary	プラットフォーム間でデザイントークンを変換する
svgo	使用前にエクスポートした SVG を最適化する
@svgr/core	SVG ファイルを React コンポーネントに変換する

委任

• デザインシステム：design-system スキルを参照してください
• アセットの最適化：asset-manager スキルを参照してください

参考資料

• セットアップと認証
• デザイントークン
• アセットのエクスポート
• コンポーネントの生成
• CI の自動化
• トラブルシューティング