ingest-figma

Figma から取り込む

REST API を使って、Figma ファイルからデザインシステムを抽出します。トークンがない場合は SVG インポートにフォールバックします。

事前確認

1. Bash(test -n "$FIGMA_TOKEN" && echo has-token || echo no-token) — 環境変数を確認します
2. no-token の場合：
   • ユーザーに次のように伝えます："FIGMA_TOKEN が見つかりません。次の 2 つの方法があります。（a）https://www.figma.com/developers/api#access-tokens でトークンを取得し、シェルで export FIGMA_TOKEN=... を実行する。または（b）Figma でフレームを SVG としてエクスポート（フレームを右クリック → コピー形式 → SVG としてコピー）し、ファイルを artifacts/ingested/ に貼り付ける — SVG を解析します。"
   • 停止して、ユーザーの返答を待ちます。

URL を解析する

Figma の URL 形式：https://www.figma.com/(file|design|proto)/<fileKey>/<name>?node-id=<nodeId>

抽出項目：

• fileKey — /file/ または /design/ の後にある英数字
• nodeId — クエリパラメーター node-id（URL デコード済みで、多くの場合 : を含みます）

手順（トークンを使う場合）

1. ファイルノードを取得：

   Bash(curl -H "X-FIGMA-TOKEN: $FIGMA_TOKEN" \
     "https://api.figma.com/v1/files/<fileKey>/nodes?ids=<nodeId>&depth=2" \
     -o /tmp/figma-<ts>.json)
   

2. スタイル定義を取得：

   Bash(curl -H "X-FIGMA-TOKEN: $FIGMA_TOKEN" \
     "https://api.figma.com/v1/files/<fileKey>/styles" \
     -o /tmp/figma-styles-<ts>.json)
   

3. JSON を解析：

   • 色：document.children をたどり、type === 'SOLID' の fills を見つけて、color {r,g,b} を抽出し、16 進数に変換します
   • エフェクト（シャドウ）：type === 'DROP_SHADOW' の effects を見つけます
   • テキストスタイル：fontFamily、fontSize、fontWeight、lineHeightPx を含む style を見つけます
   • コンポーネント：type === 'COMPONENT' および type === 'COMPONENT_SET' をたどって見つけます
   • /styles のローカルスタイル：スタイルエンドポイントは名前付き変数を返します

4. 書き込み：

   artifacts/ingested/figma-<fileKey>-tokens.json
   

   ingest-github と同じスキーマに、"source": { "figma_url": "...", "file_key": "...", "node_id": "..." } を追加します。

5. 次のステップを提案：

   • "Figma から色を X 個、テキストスタイルを Y 個、コンポーネントを Z 個抽出しました。artifacts/ingested/figma-<fileKey>-tokens.json に保存しました。"
   • /create-design-system を続行するか、アーティファクトスキルを開始します。

手順（SVG にフォールバックする場合）

1. ユーザーが SVG ファイルを artifacts/ingested/ に配置します
2. SVG の内容を Read します
3. fill="#..." / stroke="#..." / style="...color..." 属性を抽出します
4. <text> 要素からフォント情報（font-family、font-size、font-weight）を認識します
5. "source": { "svg": "<path>" } と信頼度フラグを含む部分的な tokens.json を作成します
6. 注意：SVG エクスポートではコンポーネント構造が失われ、視覚的なプリミティブのみが残ります

レート制限

Figma API：無料プランでは 1 分あたり 50 リクエストです。1 つのフレームとスタイルの取得は 2 リクエストで、上限を大きく下回ります。

セキュリティ

FIGMA_TOKEN は環境変数内にのみ保持します。ディスクへの書き込みやログへの記録は決して行いません。