AIコード生成向けFigma Variables — なぜ重要か、なければどうするか

Figma Variablesは2023年にプラットフォームの長年待望されていたデザイントークンへの回答として登場しました。この機能は強力です。任意のコンポーネントの任意のプロパティにバインドできる、プリミティブ値（カラー、数値、文字列、ブール値）の名前付きコレクション。Variableを変更すると、すべてのインスタンスが更新されます。ダークモードコレクションを追加すると、すべてのVariableバインディングが自動的に切り替わります。

AIコード生成において、VariablesはNot just useful です。それらはFigmaファイルをピクセルパーフェクトなモックアップからエージェントが正しく実装できる仕様に変換するメカニズムです。カラーに名前がある場合（#7F5CFE ではなく color/brand/primary）、エージェントはそれをコードトークンにマッピングし、ダークモードを正しく実装し、実際のデザインシステムに参加する出力を生成できます。

問題はこれです。現在アクティブに使用されているほとんどのFigmaファイルにはVariablesがセットアップされていません。figmascope は両方のケースを処理します。この記事ではその方法を説明します。

Variablesとは何か

Figma Variableはコレクションにバインドされた名前付きスカラーです。コレクションはモードでVariablesを整理します。「Light」と「Dark」が標準的な例です。コレクション内のすべてのVariableはモードごとに異なる値を持てます。color/surface/background はLightでは #FFFFFF、Darkでは #0D0D0D です。バインディングは伝播します。color/surface/background を参照するすべてのフィルはモードを切り替えると更新されます。

Variablesはカラー、数値、文字列、またはブール値です。実際には、最も影響が大きいのはカラーと数値です。これは典型的なデザインシステムのトークンサーフェスのほとんどをカバーします。カラーパレット、スペーシングスケール、ボーダー半径、フォントサイズ、エレベーション値。

FigmaはVariablesをREST APIを通じて localVariables コレクションとして公開しています。各VariableにはID、名前、タイプ、およびモードごとの値があります。Variablesを参照するコンポーネントプロパティにはVariableIDを持つ boundVariables フィールドがあります。これは抽出パイプラインをクリーンに通過する構造化されたデータです。

ハッピーパス：Variablesが存在する場合

FigmaファイルにVariablesがある場合、figmascope はAPIからそれらを読み込み、W3C Design Tokens Community Group互換の構造に従った tokens.json を構築します。各トークンには $value と $type があります。カラートークンはオプションのアルファを持つhex値を取得します。スペーシングトークンは px 単位のヒントを持つ数値を取得します。トークン名はVariableのコレクションと名前パスに従います：

{
  "color": {
    "brand": {
      "primary": { "$value": "#7F5CFE", "$type": "color" }
    },
    "surface": {
      "background": { "$value": "#FFFFFF", "$type": "color" }
    }
  },
  "spacing": {
    "4": { "$value": 4, "$type": "number" },
    "8": { "$value": 8, "$type": "number" },
    "16": { "$value": 16, "$type": "number" }
  }
}

画面ごとのIRが構築される際、boundVariables 参照を持つすべてのフィルは解決されたhexではなくトークン名を取得します。ノードは以下を保持します：

"fills": [{ "type": "SOLID", "tokenRef": "color/brand/primary" }]

#7F5CFE ではありません。トークン名です。エージェントはこれを読み込み、ターゲットフレームワークのトークン消費パターンに応じて background-color: var(--color-brand-primary) または Color.brandPrimary を生成します。これが望ましい出力です。デザインシステムに接続されたコードで、デザイナーがカラーを更新した瞬間に壊れるコードではありません。

セマンティックな名前付けは、長く使えるコードと時間とともにドリフトするコードの違いです。ソースのhex値は負債です。トークン参照は契約です。VariablesはFigmaファイルをピクセルだけでなく契約を表現できるものにします。

現実：ほとんどのファイルにVariablesがない

VariablesはFigma Professional以上のプランが必要です。セットアップしたデザイナーが必要です。コレクションの作成、Variablesの命名、すべてのコンポーネントプロパティへの手動バインドを意味します。成熟した、よくメンテナンスされたデザインシステムファイルではこれが行われています。スタートアップのプロダクトFigma、フリーランサーのクライアントファイル、またはVariables機能より前のファイルでは、通常行われていません。

figmascopeはそれらのファイルにも有用であるように設計されました。優雅に劣化します。Variablesがない場合、頻度ベースのトークン推論にフォールバックします。

フォールバック：頻度から推論

推論アルゴリズムは次のように動作します：

エクスポートされたすべてのフレームのすべてのリーフノードを走査します。
すべてのフィルカラー、スペーシング値、ボーダー半径を収集します。
ユニークな値それぞれの出現回数をカウントします。
頻度閾値を超えた値は推論トークンに昇格されます。
各トークンには値から導かれた名前が付きます：color.7f5cfe、spacing.16、radius.8。

出力の tokens.json はVariablesパスと構造的に似ていますが、名前は意味論的ではなく値から導かれています：

{
  "color": {
    "7f5cfe": { "$value": "#7F5CFE", "$type": "color" },
    "f6f2ea": { "$value": "#F6F2EA", "$type": "color" }
  },
  "spacing": {
    "16": { "$value": 16, "$type": "number" },
    "8": { "$value": 8, "$type": "number" }
  }
}

IRでは、これらの値を使用するノードはトークン参照を取得します："tokenRef": "color.7f5cfe"。ハードコードされたリテラルではありません。参照です。ただし、名前付きトークンではなく推論されたトークンへの参照です。

エージェントはまだトークン参照されたコードを生成します。var(--color-7f5cfe) は var(--color-brand-primary) ほど読みやすくありませんが、それでもトークンです。見つけて置換できます、名前を変えられます、使用状況を監査できます。値の魔法の数値ではなく、名前付きのハンドルです。

tokensSourceフィールド

すべてのfigmascopeバンドルには、バンドルの内容とどのように生成されたかを文書化した _meta.json が含まれています。tokensSource フィールドには3つの可能な値があります：

figma-variables — Variablesが存在し使用されました。トークン名はデザイナーが設定したものです。
inferred-from-frequency — Variablesが見つかりませんでした。トークンは値頻度から推論されました。名前は値から導かれています。
none — トークンを抽出または推論できませんでした。IRは直接解決した値を使用します。

これは消費するエージェント（およびバンドルを読むデベロッパー）にトークン名をどれだけ信頼できるかを伝えます。figma-variables バンドルはデザインシステムの真実の情報源です。inferred-from-frequency バンドルは正規化する前にデザイナーの名前レビューが必要な有用な構造的スキャフォールドです。none バンドルは後でトークン化する必要があるハードコードされた値の出発点です。

正直なメタデータは過小評価されています。推論をフラグなしに黙って行うツールは誤った信頼を生み出します。figmascopeは推論チェーンを明示的に表示するので、何を扱っているかがわかります。

頻度推論がないよりも優れている理由

頻度推論の代替は解決されたリテラル値をあらゆる場所に出力することです。そのカラーを使用するすべてのフィルノードに #7F5CFE を。これはリファクタリングが難しく、監査が難しく、デザインシステムが最終的に追加されたときに接続が難しいコードを生成します。

頻度推論は少なくとも、デザインが実際に使用する値のセットを抽出します。#7F5CFE がデザイン全体で47回出現する場合、それはシグナルです。これはアクセントではなくプライマリカラーです。トークン名はそれを知りません（単に color.7f5cfe です）が、頻度データがその話をします。推論されたトークンを与えられたエージェントは、どの値がプライマリでどれが1回きりかについて合理的な推測ができます。

より実際的には：頻度推論はバージョン間で差分可能な tokens.json を提供します。デザイナーが繰り返し使用するカラーを変更した後に同じファイルを2回エクスポートすると、差分にトークン値が変わったことが表示されます。推論なしでは、複数のIRファイルに散らばるすべての個別のリテラル変更を追跡することになります。

デザイナーがまだすべきこと

頻度推論は互換性レイヤーであり、Variablesの代替ではありません。正しいパスはデザイナーがデザインシステムに参加するすべての値にVariablesを採用することです。ブランドカラー、ニュートラルスケール、スペーシングスケール、ボーダー半径、エレベーション、タイポグラフィ。それが整ったら、figmascopeバンドルはスキャフォールド品質のトークンからプロダクション品質のトークンになります。

Variablesはバンドル内のテーマも解放します。トークンごとの複数のモード値。Light/Darkモードを持つファイルはメディアクエリオーバーライドを持つCSS カスタムプロパティ、またはプラットフォーム固有のテーマオブジェクトに直接フィードするモードごとの値を持つ tokens.json を生成します。これは単一のデザインスナップショットからは推論できません。明示的なデザイナーの意図、Variablesを通じて表現されたものが必要です。

アップグレードパスは増分的です。チームは今日推論品質のトークンから始め、デザインシステムが成熟するにつれて徐々にVariablesを採用し、そうするにつれて自動的により良いバンドルを取得できます。tokensSource フィールドはその進行状況を追跡します。

完全なトークンパイプライン

具体的にするために、IRの各フィルに対してfigmascopeが使用する完全な解決順序を示します：

ノードに boundVariables.fills 参照がありますか？ある場合、Variable名とモードゼロの値に解決します。トークンソース：figma-variables。
解決された値が推論頻度トークンに存在しますか（閾値以上）？ある場合、推論されたトークン名にマッピングします。トークンソース：inferred-from-frequency。
それ以外の場合：解決されたhex値を直接使用します。トークン参照なし。トークンソース：none。

ステップは順番に試されます。最高品質のソースが勝ちます。_meta.json の tokensSource フィールドはバンドル全体の支配的なパスを反映します。

つまり、部分的にVariablesが設定されているファイル（一部のコンポーネントにバインディングがあり、他はない）は混合バンドルを生成します。存在するところには名前付きトークン、ないところには推論されたトークン。これが正しい動作です。利用可能な構造化情報をすべて使い、ないところには優雅にフォールバックし、各値がどのパスをたどったかについて正直です。

figmascopeアプリからバンドルをエクスポートして、あなたのファイルがどの tokensSource を生成するか確認してください。そしてバンドルを Claude Code または Cursor で使用して、正確なトークン参照されたコード生成を行ってください。