スクリーンショットプロンプティングには限界があります。デザインを貼り付け、モデルがもっともらしい近似値を生成し、修正し、次のターンでまたドリフトします。何も固定されていません。モデルはターン間で自分の出力を照合する真実の情報源を持っていません。

figmascope のコンテキストバンドルは契約を変えます。モデルが毎回解釈しなければならないピクセル参照の代わりに、セッション内で一貫して参照できる構造化されたファイルセット（デザイントークン、レイアウトIR、コンポーネントインベントリ、UIストリング）が提供されます。Claude Codeはそれらを読み込み、実装し、必要に応じてその出力を照合できます。

このウォークスルーでは、バンドルのエクスポートからレビュー済みのトークン検証済み実装までの完全なパイプラインを解説します。

なぜ決定論的なのか

バンドルを解釈可能ではなく参照可能にする3つの要素：

  1. トークンは型付きでキー化されています。 tokens.json はセマンティックな名前（spacing.16、color.7f5cfe）を正確な値にマッピングします。モデルはデザインを再処理することなく、ファイルに対して出力を確認できます。
  2. IRはツリーであり、ピクセルではありません。 screens/home.json はレイアウトをstack/overlay/absolute/leafノードで記述します。これは実装ターゲット（Compose、Reactなど）が使用するものと同じ抽象化です。視覚的な解釈ステップは不要です。
  3. バンドルはターン間で安定しています。 リポジトリに入れておくと、セッション内のすべてのプロンプトが同じファイルを参照できます。トークンドリフトは検出可能です。モデルにその出力を tokens.json と比較するよう依頼すれば、機械的に行えます。

ステップ1：バンドルを生成する

ブラウザで figmascope.dev を開きます。FigmaファイルのURLを貼り付けます。エクスポーターはFigma REST APIを使用してクライアントサイドで動作します。Figmaのパーソナルアクセストークンは localStorage に保存され、figmascopeのサーバーに送信されることはありません。

エージェントコンテキストをエクスポート をクリックします。ページはトップレベルのフレームをエクスポートし、デザイントークンを解決し、IRを構築し、context-bundle.zip をダウンロードします。

ステップ2：プロジェクトに展開する

# プロジェクトルートから
unzip ~/Downloads/context-bundle.zip -d ./design/

# 内容を確認
find design/ -type f | sort
# design/CONTEXT.md
# design/_meta.json
# design/components/inventory.json
# design/screens/home.json
# design/screens/home.png
# design/screens/settings.json
# design/screens/settings.png
# design/strings.json
# design/tokens.json

ディレクトリ名は重要ではありません。design/ は単なる慣例です。重要なのは、Claude Codeが作業ディレクトリからファイルを読み取れることです。

ステップ3：リポジトリでClaude Codeを起動する

cd my-app
claude

Claude Codeはリポジトリのルートで完全なファイルアクセス権限を持って起動します。セッション全体にわたってツリー内の任意のファイルを読み書きし参照できます。これがバンドルパターンを機能させる主要な機能です。

ステップ4：エージェントを方向付ける

実装の前に読み取りプロンプトから始めます。これにより仕様がセッションコンテキストに読み込まれ、コードを書く前にエクスポートが正しいことを確認できます。

Read ./design/CONTEXT.md and tell me:
1. What target framework is this bundle for?
2. What token files does it reference?
3. Are there any warnings I should know about before implementing?

Claudeはターゲット（デフォルトでJetpack Compose）、トークンソース、CONTEXT.mdヘッダーからの警告（グラデーションフィル、トークンマッピングの欠落、サポートされていないエフェクト）を報告します。200行のコードを生成した後ではなく、今これらを把握します。

クイックトークンチェックでフォローアップします：

List the top 10 color tokens from ./design/tokens.json.
Then list the spacing tokens.

これによりトークンファイルが正しく解析されたことを確認し、実装前にパレットの概要を把握できます。

ステップ5：画面を実装する

次は実装プロンプトです。どのファイルがどの決定に対して権威があるかを明示してください：

Implement ./design/screens/home.json as a Jetpack Compose screen.

Rules:
- CONTEXT.md constraints apply. Read it if you haven't already.
- All spacing, color, and radius values must come from ./design/tokens.json.
  Map token keys to the appropriate Compose primitives (e.g. spacing.16 → 16.dp).
- UI strings must use keys from ./design/strings.json via stringResource().
  Fall back to the "fallback" field value if no resource ID is available yet.
- The IR node kinds map as follows:
    stack (axis:vertical)   → Column
    stack (axis:horizontal) → Row
    overlay                 → Box
    absolute                → Box with Modifier.offset
    leaf (text)             → Text with TextStyle
    leaf (rectangle)        → Box with Modifier.background
- Do not invent any value not present in the token or IR files.
  If something is missing, leave a TODO comment with the token key you expected.

Claude CodeはIRを読み込み、ノードツリーを走査し、各ノードをComposeプリミティブにマッピングし、キーでトークン値を取得します。出力は追跡可能です。すべての .dp 値はスペーシングトークンに対応し、すべての Color(0xFF...) はカラートークンに一致するはずです。

ステップ6：トークンドリフトを検出して修正する

最初の実装パスの後、視覚的にレビューする前にドリフトチェックを実行します。これがバンドルのスクリーンショットプロンプティングに対する主要な利点です。モデルに自分の出力を機械的に検証させることができます。

Compare every color value in the generated HomeScreen.kt against ./design/tokens.json.
List any hex values in the output that don't correspond to a color token key.
For each one, identify the correct token and replace the hardcoded value.

スペーシングでも同様に：

Compare every .dp value in HomeScreen.kt against the spacing tokens in ./design/tokens.json.
Flag any value that doesn't match a spacing token. Replace with the correct token reference.

実装 → ドリフト確認 → 修正というループは素早く収束します。2〜3回目のパスで出力は完全にトークン参照されるようになります。

ヒント：最初のプロンプトに _meta.json の警告を含める

design/_meta.json には warnings 配列が含まれています。これらはエクスポーターが完全に解決できなかったもので、グラデーションフィル、埋め込み画像、トークンに対応するエフェクトがない場合などです。実装前に確認してください：

cat design/_meta.json

出力に次のようなものが含まれていた場合：

{
  "warnings": [
    "node 'hero-background': gradientFill not fully supported — background fill omitted",
    "node 'avatar': imageFill — reference only, no pixel data"
  ]
}

これらを実装プロンプトに明示的に追加してください。「ヒーローの背景フィルはスキップして // TODO: gradient を残してください。アバターノードにはグレーの背景を持つプレースホルダー AsyncImage を使用してください。」

これにより、Claudeが黙って近似値を使うことを防ぎ、指示通りに動作させられます。

スクリーンショットプロンプティングより優れている理由

マルチターン安全。 トークンファイルとIRはターン間で変わりません。ターン12で「カードパディングに正しいスペーシングを使用しましたか？」と聞いても正確な答えが得られます。真実の情報源はまだディスク上にあるからです。

diff対応。 デザイン変更後に再エクスポートすると、新しいバンドルが古いものに対してdiffを生成します。Claudeにdiffを確認させ、影響を受けたコンポーネントのみを更新するよう依頼できます。全面的な再実装は不要です。

再アップロード不要。 バンドルはリポジトリに存在します。新しい画面ごとにスクリーンショットを再貼り付けする必要はありません。各新画面は design/screens/<name>.json という1ファイルで、次のプロンプトで参照するだけです。

ギャップに対して正直。 CONTEXT.md と _meta.json はバンドルがカバーしていないものを明示的にリスト化しています。スクリーンショットプロンプティングにはこれに相当するものがなく、モデルはギャップを推測するだけです。

figmascope のメインアプリがブラウザでエクスポートを処理します。FigmaのURLを貼り付けてバンドルをエクスポートすれば、決定論的な仕様に対してClaude Codeを実行する準備が整います。