cc-figma-tokens

cc-figma-tokens — Component Contracts トークンスキル

component-contracts のトークンファイルから Figma の変数コレクションを構築します。このスキルは、すべてのコンポーネントがバインドする Primitive および Semantic 変数コレクションを作成します。

前提条件 — 先にこれらのスキルを読み込んでください:

• figma-use — Plugin API の構文ルール（すべての use_figma 呼び出しの前に必須）
• figma-generate-library — デザインシステムのワークフローと変数作成のパターン

このスキルの一環として use_figma を呼び出す際は、必ず skillNames: "cc-figma-tokens" を渡してください。

---

1. 設定

何よりも先に、プロジェクトルートの .component-contracts を読み込んでください。このファイルには必要な設定がすべて含まれています。いかなる応答でも FIGMA_ACCESS_TOKEN を出力しないでください。

FIGMA_ACCESS_TOKEN=...       # never output this value
FIGMA_FILE_KEY=...           # use for all use_figma calls
TOKENS_DIR=...               # root directory of token files
CONTRACTS_DIR=...            # root directory of contract files

.component-contracts が存在しない場合は、先に進む前に .component-contracts.example をコピーして値を記入するようユーザーに伝えてください。

---

2. トークンファイルの構造

Component-contracts は、2 つの階層に整理された W3C DTCG トークン形式を使用します:

{TOKENS_DIR}/
  primitive/
    color.tokens.json
    motion.tokens.json
    shape.tokens.json
    space.tokens.json
    typography.tokens.json
  semantic/
    semantic.tokens.json

階層 1 — Primitive: 生の値。スケール接尾辞（color/blue/500、space/4）を付けて命名します。エイリアスはありません。単一モード: Value。

階層 2 — Semantic: Primitive へのエイリアス。ロール（brand/500、surface/default、text/primary）を付けて命名します。単一モード: Value。

Figma で何かを作成する前に、すべてのトークンファイルを読み込んでください。use_figma を呼び出す前に、すべてのトークンとその値/エイリアスの完全なインメモリマップを構築してください。

---

3. Figma 変数アーキテクチャ

コレクション

この順序でちょうど 2 つのコレクションを作成します:

コレクション	モード	目的
Primitives	Value	生のトークン値 — コンポーネントに直接バインドされることはありません
Semantic	Value	Primitive へのエイリアス — コンポーネントがバインドするのはこちらです

変数の命名

W3C DTCG のパス構造に合わせて、グループ区切りとして / を使用します:

Primitives:  color/blue/500, space/4, radius/md
Semantic:    brand/500, surface/default, text/primary, focus/default

変数スコープ

ALL_SCOPES は絶対に使用しないでください。 トークンのセマンティックロールに基づいてスコープを割り当てます:

トークンのロール	スコープ
カラー — 背景/塗り	FRAME_FILL、SHAPE_FILL
カラー — テキスト	TEXT_FILL
カラー — 境界線/ストローク	STROKE_COLOR
カラー — フォーカスリング	FRAME_FILL、SHAPE_FILL、STROKE_COLOR
スペーシング — パディング、ギャップ	GAP
スペーシング — 境界線の幅	STROKE_WIDTH
境界線の角丸	CORNER_RADIUS
タイポグラフィ — フォントサイズ	FONT_SIZE
タイポグラフィ — フォントの太さ	FONT_WEIGHT
タイポグラフィ — 行の高さ	LINE_HEIGHT
Primitive（すべて）	[] — プロパティパネルから非表示

注記: HORIZONTAL_PADDING と VERTICAL_PADDING は、Figma Plugin API の有効な VariableScope 列挙値ではありません。すべてのスペーシング変数には GAP のみを使用してください。

コード構文

すべての変数に WEB コード構文を設定する必要があります。CSS カスタムプロパティ名とともに var() ラッパーを使用します:

Primitive color/blue/500  →  var(--ds-color-blue-500)
Semantic brand/500        →  var(--ds-brand-500)
Semantic surface/default  →  var(--ds-surface-default)

CSS の命名規則: --ds-{path-with-dashes}（/ は - になります）。

ANDROID と iOS は var() ラッパーを使用しません。

---

4. 実行モード

デフォルト（高速）: フェーズ 0 の計画を提示して承認を待ち、その後フェーズ 1〜4 を中断せずに順番に実行します。これがすべての実行のデフォルトです。

デバッグモード: 各フェーズの後に停止し、次に進む前に明示的な承認を待ちます。問題の診断や中間出力の検証に使用します。プロンプトに「debug mode」を含めることで有効になります。

---

5. ワークフロー

バッチ処理の要件 (パフォーマンス上、極めて重要)

コレクションごとに 1 回の use_figma 呼び出しで、すべての変数を作成してください。 変数を 1 つずつ、またはカテゴリ単位で作成しないでください。

• 1 回の use_figma 呼び出しで Primitives コレクション + すべての変数を作成します
• 1 回の use_figma 呼び出しで Semantic コレクション + すべてのエイリアスを作成します
• 変数間に中間状態ファイルを書き込まないでください
• 個々の変数間で検証しないでください
• コレクション全体の完了後に 1 回だけ検証してください

トークンの作成は決定的で低リスクです。figma-generate-library にある状態台帳や中間ファイル書き込みのパターンは、ここでは適切ではありません。完全に省略してください。まずすべてのトークンファイルを読み込み、完全な変数マップをメモリ上に構築し、コレクションごとに 1 回の呼び出しで実行します。

コレクションが約 80 変数を超え、2 回の呼び出しに分割する必要がある場合は、カテゴリ単位で分割してください (例: color を 1 回の呼び出し、それ以外を別の呼び出し) — 個々の変数単位で分割しないでください。

---

フェーズ 0 — 検査 (読み取り専用)

何かを作成する前に:

1. TOKENS_DIR からすべてのトークンファイルを読み込む
2. Figma ファイルを検査する — Primitives または Semantic という名前の既存の変数があるか確認する
3. コレクションが存在する場合、これが作成操作か更新操作かを確認する
4. ユーザーにサマリーを提示する: 階層ごとのトークン数、既存と新規のコレクション、その他
5. 先に進む前に、ユーザーの明示的な承認を待つ

フェーズ 1 — Primitives コレクション

1. すべてのプリミティブトークンファイルを読み込み、変数マップをメモリ上に構築する
2. 単一の Value モードで Primitives コレクションを作成する
3. 1 回の use_figma 呼び出しですべてのプリミティブ変数を作成する — color、space、motion、shape、typography
4. すべてのプリミティブでスコープを [] に設定する (非表示)
5. すべてのプリミティブで WEB コード構文を設定する
6. 検証: get_metadata で変数数がトークンファイル数と一致することを確認する
7. デバッグモードの場合: 先に進む前にユーザーのチェックポイントを待つ

フェーズ 2 — Semantic コレクション

1. セマンティックトークンファイルを読み込み、すべての {token.path} 参照を Primitive 変数 ID に解決する
2. 作成順序を処理する — 他のセマンティック変数をエイリアスする変数 (例: border/brand → brand/500) は、そのターゲットの後に作成する必要があります
3. 単一の Value モードで Semantic コレクションを作成する
4. 1 回の use_figma 呼び出しで figma.variables.createVariableAlias を使用してすべてのセマンティック変数を作成する
5. セマンティックな役割に基づいてスコープを設定する (§3 のスコープ表を参照)
6. すべてのセマンティック変数で WEB コード構文を設定する
7. 検証: get_metadata — すべてのエイリアスが正しく解決されることを確認する
8. デバッグモードの場合: 先に進む前にユーザーのチェックポイントを待つ

フェーズ 3 — 明示的なモードの割り当て

両方のコレクションが存在したら、ファイル内のすべてのノードで setExplicitVariableModeForCollection を呼び出し、Value モードを強制します。これにより、変数が未解決に見えるゴーストモードの問題を防ぎます。

// Apply to every node recursively
function applyModes(node, collection, modeId) {
  node.setExplicitVariableModeForCollection(collection, modeId);
  if ('children' in node) {
    for (const child of node.children) {
      applyModes(child, collection, modeId);
    }
  }
}

デバッグモードの場合: 先に進む前にユーザーのチェックポイントを待つ

フェーズ 4 — 検証

最終検証パスを実行します:

• get_metadata — 両方のコレクションが正しい変数数で存在することを確認する
• get_screenshot — Figma で変数が正しく表示されることを視覚的に確認する

構造化されたサマリーを返します:

{
  "collections": {
    "Primitives": { "variableCount": N, "modeCount": 1 },
    "Semantic": { "variableCount": N, "modeCount": 1 }
  },
  "status": "complete"
}

---

6. 更新と作成

変数コレクションがすでに存在する場合:

• 新しい変数を追加: 作成してエイリアスを設定し、既存の変数には触れない
• 値を更新: Primitive の生の値を変更すると、Semantic のエイリアスチェーンが自動的に更新される
• 既存の変数を削除しない — ユーザーの明示的な確認がない限り。コンポーネントがそれらにバインドされている可能性があります
• 作成のたびに冪等性チェックを使用する: getLocalVariables().find(v => v.name === name && v.variableCollectionId === collId)

---

7. 既知の制約

• 常に setSharedPluginData / getSharedPluginData を使用してください — setPluginData / getPluginData は決して使用しないでください。非共有バージョンは、ツールを実行するたびに変化するデバッグ UUID をプラグイン識別子として使用するため、保存されたデータが永久に取得できなくなり、ファイルの肥大化を引き起こします。常に component_contracts 名前空間を使用してください：

  // CORRECT
  node.setSharedPluginData('component_contracts', 'dsb_key', value);
  node.getSharedPluginData('component_contracts', 'dsb_key');
  
  // WRONG — UUID changes per execution, data becomes orphaned
  node.setPluginData('dsb_key', value);
  

• レタースペーシングは Figma 変数として保存できません — Figma の FLOAT 変数は単位のない整数であり、em ベースのレタースペーシング値は互換性がありません。レタースペーシングは変数ではなく、テキストスタイルのみで処理してください。

• HORIZONTAL_PADDING と VERTICAL_PADDING は有効な VariableScope の値ではありません — Plugin API はこれらを列挙型メンバーとして公開していません。すべてのスペーシング変数には GAP のみを使用してください。

• タイポグラフィ変数 — フォントサイズとウェイトは FLOAT 変数として保存できます。フォントファミリーには STRING 変数を使用する必要があります。

• 連鎖エイリアスは許可されています：Semantic/brand/500 → Primitive/color/blue/500。チェーンをフラット化しないでください。

• 連鎖するセマンティックエイリアスでは作成順序が重要です — エイリアス先の変数を先に作成してください。たとえば、brand/500 を先に作成してから、それをエイリアスする border/brand を作成します。

• ゴーストモード：Figma はコレクションが作成されると、空のゴーストモードを自動的に作成します。これは想定された動作です。これを抑制するには、常に明示的なモード割り当て（フェーズ 3）を呼び出してください。