Figma から Claude Code へ — Anthropic CLI 向け構造化デザインコンテキスト

「すでに存在するコンポーネントを再実装しない」という指示は、コンポーネントインベントリが共有されている場合に重要です。Claude Code は design/components/inventory.json を読んで、どのコンポーネントがすでに実装されているかを特定し、再生成せずにインポートできます。

デザイントークンの配線

figmascope がエクスポートする tokens.json は、$value と $type フィールドを持つ W3C に準じたネスト構造を使います。

{
  "color": {
    "surface":    { "$value": "#f6f2ea", "$type": "color" },
    "ink":        { "$value": "#1f1d1a", "$type": "color" },
    "accent":     { "$value": "#d96a3a", "$type": "color" }
  },
  "spacing": {
    "1": { "$value": "4px",  "$type": "dimension" },
    "2": { "$value": "8px",  "$type": "dimension" },
    "4": { "$value": "16px", "$type": "dimension" },
    "8": { "$value": "32px", "$type": "dimension" }
  },
  "typography": {
    "body": {
      "fontFamily": { "$value": "Inter",  "$type": "fontFamily" },
      "fontSize":   { "$value": "14px",   "$type": "dimension" },
      "lineHeight": { "$value": 1.45,     "$type": "number" }
    }
  }
}

スクリーンを実装する前の最初のステップとして、このファイルから tailwind.config.ts の theme extension ブロックを生成するよう Claude Code に依頼します。そうすることで以降のすべてのスクリーン実装が Tailwind トークンエイリアスを一貫して使えるようになります。

claude --print "Read design/tokens.json and generate a tailwind.config.ts
theme.extend block. Map color tokens to theme.extend.colors,
spacing tokens to theme.extend.spacing, and typography to
theme.extend.fontFamily / fontSize. Output only the config object."

トークンフォーマットと、Figma Variables が設定されていない場合に figmascope が使用する頻度推論フォールバックについての詳細は AI エージェント向けデザイントークンエクスポート を参照してください。

文字列レイヤーの処理

Figma ファイル内のすべてのテキストノードが strings.json にスロットとして格納されます。キーはフレーム階層から導出されたドット記法です。

{
  "home.hero.title":        "Everything you need",
  "home.hero.subtitle":    "Ship faster with structured context",
  "home.cta.primary":      "Get started",
  "settings.account.heading": "Account settings"
}

これらのキーを i18n 識別子として使用するよう Claude Code に指示します。JSX に文字列 "Everything you need" をハードコードするのではなく、生成されたコンポーネントが t('home.hero.title')（または使用する i18n ライブラリの同等のもの）を呼び出します。リソースファイルはすでに strings.json にあります — あとは i18n セットアップにインポートまたは接続するだけです。

figmascope が衝突を検出した場合 — 同じキーにハッシュされる 2 つのノード — は _meta.json に strings-collision 警告を出力し、数値サフィックスで曖昧さを解消します。セッションを開始する前に _meta.json を確認しておきましょう。

CLAUDE.md との統合

CLAUDE.md プロジェクトコンテキストファイルを使用している場合は、design ディレクトリにエージェントを向ける短いセクションを追加します。これは AI デザインハンドオフ で説明されたアプローチとうまく組み合わせられ、figmascope が Figma インスペクタープラグインと異なる理由を補完します。

以下のような design セクションを追加します。

## Design context

Design tokens, layout IR, reference renders, and strings live in `design/`.
Always read `design/CONTEXT.md` before implementing any screen.
Token values are in `design/tokens.json` — never hardcode color or spacing.
Component canonical names are in `design/components/inventory.json`.

これにより、プロジェクト内のすべての Claude Code セッションが、毎回プロンプトに繰り返すことなく、design コンテキストを自動的に作業知識として持つようになります。

エージェントが実際に正しく処理できること

構造化されたコンテキストがあると、Claude Code は以下を確実に処理できます。

• スペーシング値 — tokens.json に spacing.4 → 16px として存在するため、スクリーンショットから目測する必要がありません
• カラー — 「暖かいオレンジに見える」ではなく正確な hex 値
• タイポグラフィ — フォントファミリー、サイズ、ウェイト、行間、すべて型付き
• レイアウト方向 — スタックノードに明示的な direction と gap フィールドがあります
• コンポーネント命名 — inventory.json が正規ソースであるため、でたらめな名前はありません
• コピー — strings.json でエージェントが言い換えたりプレースホルダーテキストを作ったりするのを防ぎます

人間によるレビューが依然として必要なもの：静的な Figma フレームでは見えないインタラクション状態（ホバー、フォーカス、アクティブ）、アニメーションタイミング、ファイル内で明示的にデザインされていないレスポンシブブレークポイント。IR は静的レイアウトをキャプチャします。動的な挙動はスコープ外です。

制御された環境での --dangerously-skip-permissions の使用

デザイン更新後にコンポーネントスタブを生成する CI ステップなど、インタラクティブな承認プロンプトなしに Claude Code を動作させたい自動化パイプラインでは、--dangerously-skip-permissions を使用できます。本番の認証情報がないサンドボックス環境でのみ適切です。

claude --dangerously-skip-permissions --print "$(cat <<'EOF'
Read design/CONTEXT.md. Generate component stub files for any components
in design/components/inventory.json that don't already exist in src/components/.
Use TypeScript + React functional component format. Include a TODO comment
for each component referencing the relevant screen JSON.
EOF
)"

本番の開発者ワークフローでは、権限をインタラクティブなままにします。プロンプトには正当な理由があります。Claude Code はファイルを書き込むことができるので、どのファイルかを事前に確認することが重要です。

プロンプトを送る前にエクスポート警告を確認する

figmascope は出力品質に影響する可能性のある状態について _meta.json に警告を出力します。Claude Code セッションを開始する前に確認します。

python3 -c "
import json
meta = json.load(open('design/_meta.json'))
for w in meta.get('warnings', []):
    print(f\"{w['code']}: {w['message']}\")
print(f\"Frames exported: {meta['frameCount']}\")
print(f\"Tokens source: {meta.get('tokensSource', 'variables')}\")
"

注意すべき 2 つの警告：

• layout-mode-none-inferred — フレームに auto-layout が設定されていません。figmascope は子要素の絶対位置からレイアウトを推論しましたが、信頼性が低い場合があります。プロンプトで該当スクリーンにフラグを立てましょう：「このスクリーンは絶対配置を使っています。それに合わせて生成してください。」
• strings-collision — 2 つのテキストノードが同じリソースキーを生成しました。figmascope は数値サフィックスで曖昧さを解消しますが、エージェントが i18n コールを生成する前に strings.json の文字列が正しいことを確認してください。

Android および iOS ワークフロー

Claude Code は Web フレームワークに限りません。コンテキストバンドルはフレームワーク非依存です。レイアウト IR とトークンはデータであり、CSS ではありません。Jetpack Compose の場合：

claude --print "$(cat <<'EOF'
Read design/CONTEXT.md and design/tokens.json.

Implement design/screens/Home.json as a Jetpack Compose screen.
- Map color tokens to a MaterialTheme ColorScheme
- Map spacing tokens to Dp values (strip 'px' suffix, use .dp)
- Map typography tokens to MaterialTheme.typography
- Use the component names from design/components/inventory.json as Composable names
- Reference design/screens/Home.png for visual accuracy
EOF
)"

IR の stack ノードは Compose の Column（direction: vertical）と Row（direction: horizontal）に自然にマッピングされます。type: "text" の leaf ノードは Text コンポーザブルになり、type: "image" は Image またはプレースホルダーになります。完全なパターンについては Jetpack Compose from Figma を参照してください。

デザインバンドルのバージョン管理

design/ ディレクトリを他のプロジェクト依存関係と同様に扱います。デザインが大きく変わったら figmascope.dev から再エクスポートし、コミットして、PR に変更を記載します。

# Check when the bundle was last exported vs when Figma file was last modified
python3 -c "
import json
from datetime import datetime
meta = json.load(open('design/_meta.json'))
exported = datetime.fromisoformat(meta['exportedAt'].replace('Z', '+00:00'))
modified = datetime.fromisoformat(meta['figmaLastModified'].replace('Z', '+00:00'))
delta = modified - exported
if delta.total_seconds() > 0:
    print(f'WARNING: Figma file was modified {delta} after last export')
else:
    print('Bundle is current')
"

バンドルが古い場合、エージェントは古いデザインから作業していることになります。タイムスタンプチェックにより、時代遅れのスペックに基づくコード生成セッションに時間を費やす前にこれを検知できます。