Cursor の AI は多くの UI コードを書けます。しかし、Figma ファイルを直接読むことはできません。スクリーンショットを貼り付けると推測が始まり、スペースが違う、カラー値が違う、コンポーネント名がでたらめ、といったことが起きます。問題はモデルの能力ではなく、構造化されたコンテキストが不足していることです。

figmascope はそのギャップを埋めます。Figma ファイルを zip バンドルとしてエクスポートします。デザイントークン、スクリーンごとのレイアウトツリー、参照用レンダリング、コンポーネントインベントリ、UI 文字列 — 言語モデルが正確なコードを生成するために必要なすべてが含まれています。メインアプリはバックエンドやアップロード不要で、完全にブラウザ上で動作します。

このページでは、Figma URL から Cursor によるコード生成までの全ワークフローを説明します。Cursor の代わりに Claude Code を使う場合は、Figma から Claude Code へを参照してください。エージェント向けハンドオフの全体像については、AI デザインハンドオフをご覧ください。

コンテキストバンドルに含まれるもの

figmascope を Figma ファイルに対して実行すると、以下を含む .zip が生成されます。

何もアップロードされません。Personal Access Token はブラウザのメモリにのみ保存され、api.figma.com へのリクエストにのみ使われます。zip はクライアントサイドで組み立てられ、ブラウザのダウンロードとして渡されます。

ステップ 1 — Figma Personal Access Token を取得する

Figma → アカウント設定 → Personal Access Tokens に移動し、File content: read-only スコープのトークンを作成します。これが最低限必要なスコープです。

トークンはブラウザセッション外に出ることはありません。figmascope は api.figma.com へのリクエストの X-Figma-Token ヘッダーにのみ使用し、それ以外には送信しません。完全な脅威モデルについては PAT セキュリティと figmascope をご覧ください。

ステップ 2 — コンテキストバンドルをエクスポートする

  1. ブラウザで figmascope.dev を開きます。
  2. Figma ファイル URL（例：https://www.figma.com/file/ABC123/MyDesign）を貼り付けます。
  3. Personal Access Token を貼り付けます。
  4. Export Context Bundle をクリックします。
  5. figmascope-<fileKey>.zip がマシンにダウンロードされます。

プロジェクトに展開します。リポジトリルートの design/ フォルダが適切な場所です。

unzip figmascope-ABC123.zip -d design/
# → design/CONTEXT.md
# → design/tokens.json
# → design/screens/Home.json
# → design/screens/Home.png
# → design/components/inventory.json
# → design/strings.json
# → design/_meta.json

ステップ 3 — Cursor でプロジェクトを開く

通常どおり Cursor でプロジェクトフォルダを開きます。design/ ディレクトリがワークスペースの一部となり、Cursor のインデクサーに含まれます。

モデルにプロンプトを送る前に、design/CONTEXT.md を一度自分で読んでください。どのフレームがエクスポートされたか、トークンの命名スキームは何か、エクスポート中に出力された警告（例：auto-layout が設定されていないフレームの layout-mode-none-inferred）が記載されています。これらの警告はエージェントが直面するものと同じです。

ステップ 4 — 効果的な Cursor プロンプトを書く

Cursor Chat に貼り付けられる参照プロンプトが最もシンプルな出発点です。

Read design/CONTEXT.md first, then implement the Home screen.

Use:
- design/tokens.json for all color, spacing, and typography values
- design/screens/Home.json for the layout tree
- design/screens/Home.png as the visual reference
- design/strings.json for all copy (use the resource keys as i18n identifiers)
- design/components/inventory.json to match component names

Target: React + Tailwind CSS. Map token values to Tailwind config entries rather
than hardcoding hex values. Use the component names from inventory.json as
component file names (PascalCase).

Cursor の Composer は CONTEXT.md の制約に従い、Home.json のレイアウトツリーを参照し、tokens.json からスペーシングを取得して、デザインシステムに合致したコードを生成します。

モデルはあなたのデザインを知りません。あなたが与えたものだけを知っています。構造化された JSON はスクリーンショットより常に優れています。

ステップ 5 — トークンをフレームワーク設定にマッピングする

エクスポートされた tokens.json は W3C に準じたネスト構造を使っています。

{
  "color": {
    "surface": { "$value": "#f6f2ea", "$type": "color" },
    "accent":  { "$value": "#d96a3a", "$type": "color" }
  },
  "spacing": {
    "4":  { "$value": "16px", "$type": "dimension" },
    "8":  { "$value": "32px", "$type": "dimension" }
  },
  "radius": {
    "sm": { "$value": "4px",  "$type": "dimension" },
    "md": { "$value": "8px",  "$type": "dimension" }
  },
  "typography": {
    "body": {
      "fontFamily": { "$value": "Inter",  "$type": "fontFamily" },
      "fontSize":   { "$value": "14px",   "$type": "dimension" },
      "fontWeight": { "$value": 400,       "$type": "number" }
    }
  }
}

Tailwind の場合は、tokens.json から直接 tailwind.config.js の theme.extend ブロックを生成するよう Cursor に依頼できます。トークンフォーマットと頻度推論の詳細については AI エージェント向けデザイントークンエクスポート を参照してください。トークン構造は十分にフラットなので、自動化したい場合は単一の Node スクリプトで処理できます。

// scripts/tokens-to-tailwind.js
const tokens = require('../design/tokens.json');

const colors = Object.fromEntries(
  Object.entries(tokens.color).map(([k, v]) => [k, v.$value])
);
const spacing = Object.fromEntries(
  Object.entries(tokens.spacing).map(([k, v]) => [k, v.$value])
);

module.exports = { colors, spacing };

ステップ 6 — マルチスクリーンプロジェクトを扱う

Figma ファイルの各フレームは screens/<FrameName>.json と対応する .png になります。十数スクリーンのプロジェクトでは、段階的に作業を進めます。Cursor Composer は 1 セッションあたり 1 スクリーンをうまく処理します。スクリーン JSON と PNG を明示的な @file 参照として渡しましょう。

@design/screens/Settings.json
@design/screens/Settings.png

Implement the Settings screen. Follow the same component structure
as the Home screen already implemented. Use tokens from design/tokens.json.

コンポーネントインベントリ（design/components/inventory.json）は、スクリーンをまたいだ名前のずれを防ぐのに役立ちます。スクリーン JSON で参照されるすべてのコンポーネントには、インベントリに正規の id と name があります。共有コンポーネントライブラリを生成する場合は、それらの名前を信頼できる情報源として使用してください。

IR の実際の姿

スクリーンごとの JSON は再帰的なノード構造を使っています。カードコンポーネントの簡略例を以下に示します。

{
  "kind": "stack",
  "name": "ProductCard",
  "direction": "vertical",
  "gap": { "$ref": "spacing.4" },
  "padding": { "top": 16, "right": 16, "bottom": 16, "left": 16 },
  "background": { "$ref": "color.surface" },
  "radius": { "$ref": "radius.md" },
  "children": [
    {
      "kind": "leaf",
      "name": "ProductImage",
      "type": "image",
      "width": 320,
      "height": 200
    },
    {
      "kind": "leaf",
      "name": "ProductTitle",
      "type": "text",
      "text": { "$ref": "strings.product.card.title" },
      "style": { "$ref": "typography.heading.sm" }
    }
  ]
}

トークン参照は $ref 文字列を使用し、tokens.json のキーに対応しています。モデルは別途ルックアップのステップなしに解決できます。完全なノードスキーマについては per-screen IR explained をご覧ください。

コンテキストを最新の状態に保つ

デザインファイルは変わります。よい習慣として：デザインに大きな変更があるたびに figmascope を再実行し、更新された design/ フォルダをコミットして、PR の説明にバージョンを記載します。_meta.json にはタイムスタンプと Figma ファイルの lastModified フィールドが含まれているので、バンドルの最終再生成日時とファイルの最終更新日時を比較できます。

// _meta.json
{
  "figmascopeVersion": "1.0.0",
  "fileKey": "ABC123",
  "exportedAt": "2026-05-11T09:14:00Z",
  "figmaLastModified": "2026-05-10T18:30:00Z",
  "frameCount": 12,
  "warnings": []
}

warnings が空でない場合は、エージェントにコンテキストを渡す前に対処してください。よくある警告：strings-collision（同じスラグを持つ 2 つのノードが同じキーに解決された）と layout-mode-none-inferred（明示的な auto-layout がないコンテナで、figmascope が子要素の位置からレイアウトを推論した）。

よくある Cursor ワークフロー

差分ベースの更新

デザインが軽微に変更された場合 — たとえばカードコンポーネントのスペーシング値が spacing.4 から spacing.6 に変わった場合 — スクリーン全体を再生成するのではなく、差分だけ適用するよう Cursor に依頼できます。

The design/tokens.json was updated. spacing.4 is now 24px instead of 16px.
Find all components using spacing.4 and update them. Do not touch anything else.

生成されたコンポーネントがトークン名を Tailwind クラス（gap-spacing-4）として参照しており、生のピクセル値を使っていないため、これが可能です。トークンの変更はデザインの再検討ではなく、検索と置換で済みます。

既存のコードベースに新しいスクリーンを追加する

スクリーン 1〜N-1 が実装済みのコードベースにスクリーン N を追加する場合、既存のコンポーネントライブラリにエージェントを根付かせることが重要です。

@design/screens/Checkout.json
@design/screens/Checkout.png

Implement the Checkout screen. Reuse existing components from src/components/
wherever the component name matches design/components/inventory.json.
Only create new component files for components not already implemented.
Use design/tokens.json for all token values.

コンポーネントインベントリは、デザインのコンポーネント名とコードベースのファイル名を繋ぐ橋渡し役です。これがないと、エージェントはインポートパスを作り上げ、重複するコンポーネントを生成してしまいます。

デザインシステムのベースラインを生成する

スクリーンを実装する前に、コンテキストバンドルを使ってデザインシステムのベースライン（トークン設定、カラーパレットコンポーネント、基本タイポグラフィスタイル）を生成します。これにより、以降のすべてのスクリーン実装が同じ基盤に固定されます。

Read design/tokens.json and design/CONTEXT.md.

Generate:
1. tailwind.config.ts theme.extend block from all tokens
2. src/styles/tokens.css with CSS custom properties for the same tokens
3. src/components/foundations/ColorPalette.tsx showing all color tokens
4. src/styles/typography.css with the typography token classes

Name all classes and variables using the token key paths
(e.g. --color-accent, text-ink, bg-surface).

このベースラインが存在すれば、すべてのスクリーン実装がそれを参照できます。エージェントはセッションごとにデザインからカラーを再導出するのではなく、すでに生成されたクラスを使用します。

事前に知っておくべき制限

figmascope のコンテキストバンドルは静的な構造をキャプチャします。表現できないものがいくつかあります。

CONTEXT.md ファイルには除外されたフレームとその理由が記載されているため、エージェントがスコープ外のものを実装しようとすることはありません。