figma-generate-library

デザインシステムビルダー — Figma MCP スキル

コードと一致する、プロフェッショナル品質のデザインシステムを Figma で構築します。このスキルは、20～100 回以上の use_figma 呼び出しにわたる複数フェーズのワークフローを統括し、実際のデザインシステム（Material 3、Polaris、Figma UI3、Simple DS）で培われた品質パターンを適用します。

前提条件：すべての use_figma 呼び出しで、figma-use スキルも必ず読み込んでください。このスキルは Plugin API の構文ルール（戻り値のパターン、ページのリセット、ID の返却、フォントの読み込み、色の範囲）を提供します。このスキルは、デザインシステムの専門知識とワークフローの統括を提供します。

このスキルの一部として use_figma を呼び出す際は、常に skillNames: "figma-generate-library" を渡してください。 これはログ記録用のパラメーターであり、実行には影響しません。

---

1. 最も重要な唯一のルール

これは決して一度きりのタスクではありません。 デザインシステムの構築には、複数のフェーズにわたる20～100回以上の use_figma 呼び出しと、各フェーズ間に必須となるユーザーチェックポイントが必要です。すべてを1回の呼び出しで作成しようとすると、必ず不具合や不完全な結果、復旧不能な結果が生じます。各操作を有用な最小単位に分割し、検証して、フィードバックを得てから次に進んでください。

---

2. 必須ワークフロー

デザインシステムの構築では、すべてこのフェーズ順序に従います。フェーズを省略したり順序を入れ替えたりすると、修正に多大な手間がかかる構造上の不具合が発生します。

Phase 0: DISCOVERY (always first — no use_figma writes yet)
  0a. Analyze codebase → extract tokens, components, naming conventions
  0b. Inspect Figma file → pages, variables, components, styles, existing conventions
  0c. Search subscribed libraries → use search_design_system for reusable assets
  0d. Lock v1 scope → agree on exact token set + component list before any creation
  0e. Map code → Figma → resolve conflicts (code and Figma disagree = ask user)
  ✋ USER CHECKPOINT: present full plan, await explicit approval

Phase 1: FOUNDATIONS (tokens first — always before components)
  1a. Create variable collections and modes
  1b. Create primitive variables (raw values, 1 mode)
  1c. Create semantic variables (aliased to primitives, mode-aware)
  1d. Set scopes on ALL variables
  1e. Set code syntax on ALL variables
  1f. Create effect styles (shadows) and text styles (typography)
  → Exit criteria: every token from the agreed plan exists, all scopes set, all code syntax set
  ✋ USER CHECKPOINT: show variable summary, await approval

Phase 2: FILE STRUCTURE (before components)
  2a. Create page skeleton: Cover → Getting Started → Foundations → --- → Components → --- → Utilities
  2b. Create foundations documentation pages (color swatches, type specimens, spacing bars)
  → Exit criteria: all planned pages exist, foundations docs are navigable
  ✋ USER CHECKPOINT: show page list + screenshot, await approval

Phase 3: COMPONENTS (one at a time — never batch)
  For EACH component (in dependency order: atoms before molecules):
    3a. Create dedicated page
    3b. Build base component with auto-layout + full variable bindings
    3c. Create all variant combinations (combineAsVariants + grid layout)
    3d. Add component properties (TEXT, BOOLEAN, INSTANCE_SWAP)
    3e. Link properties to child nodes
    3f. Add page documentation (title, description, usage notes)
    3g. Validate: get_metadata (structure) + get_screenshot (visual)
    3h. Optional: lightweight Code Connect mapping while context is fresh
    → Exit criteria: variant count correct, all bindings verified, screenshot looks right
    ✋ USER CHECKPOINT per component: show screenshot, await approval before next component

Phase 4: INTEGRATION + QA (final pass)
  4a. Finalize all Code Connect mappings
  4b. Accessibility audit (contrast, min touch targets, focus visibility)
  4c. Naming audit (no duplicates, no unnamed nodes, consistent casing)
  4d. Unresolved bindings audit (no hardcoded fills/strokes remaining)
  4e. Final review screenshots of every page
  ✋ USER CHECKPOINT: complete sign-off

---

3. 重要なルール

プラグイン API の基本（use_figma スキルより — ここでも適用されます）：

• return を使ってデータを返します（自動でシリアライズされます）。IIFE で囲んだり、closePlugin を呼び出したりしないでください。
• すべての return 値に、作成または変更したノード ID をすべて含めてください。
• ページコンテキストは呼び出しごとにリセットされます — 常に最初に await figma.setCurrentPageAsync(page) を実行してください。
• figma.notify() は例外をスローするため、絶対に使用しないでください。
• 色の値は 0〜255 ではなく、0〜1 の範囲です。
• テキストを書き込む前に、必ずフォントを読み込む必要があります：await figma.loadFontAsync({family, style})

デザインシステムのルール：

1. コンポーネントより先に変数を作成 — コンポーネントは変数にバインドします。トークンがなければ、コンポーネントも作成しません。
2. 作成前に確認 — 読み取り専用の use_figma を実行して、既存の規則を調べます。それに合わせてください。
3. コンポーネントごとに 1 ページ (デフォルト) — 例外：密接に関連するファミリー（例：Input とそのヘルパー）は、セクションを明確に分ければ 1 ページにまとめてもかまいません。
4. 視覚的なプロパティを変数にバインド (デフォルト) — 塗り、線、パディング、角丸、間隔。例外：意図的に固定するジオメトリ（アイコンのピクセルグリッドサイズ、静的な区切り線）。
5. すべての変数にスコープを設定 — 絶対に ALL_SCOPES のままにしないでください。背景：FRAME_FILL, SHAPE_FILL。テキスト：TEXT_FILL。境界線：STROKE_COLOR。間隔：GAP。角丸：CORNER_RADIUS。プリミティブ：[]（非表示）。
6. すべての変数にコード構文を設定 — WEB 構文では必ず var() ラッパーを使用します：var(--color-bg-primary)。--color-bg-primary だけにしないでください。コードベースで実際に使われている CSS 変数名を使用してください。ANDROID/iOS ではラッパーを使用しません。
7. セマンティック変数をプリミティブにエイリアス — { type: 'VARIABLE_ALIAS', id: primitiveVar.id }。セマンティックレイヤーで生の値を重複させないでください。
8. combineAsVariants の後にバリアントを配置 — バリアントは (0,0) に重なります。手動でグリッド状に配置し、サイズを変更してください。
9. アイコンには INSTANCE_SWAP を使用 — アイコンごとにバリアントを作成しないでください。バリアントの組み合わせを制限します：Size × Style × State が 30 を超える場合は、サブコンポーネントに分割してください。
10. 決定論的な命名 — 冪等なクリーンアップと再開ができるよう、一貫性のある一意なノード名を使用してください。作成したノード ID は return 値と状態台帳で追跡します。
11. 破壊的なクリーンアップは禁止 — クリーンアップスクリプトでは、推測ではなく、ノード名の規則または返された ID を使って対象を特定してください。
12. 先に検証してから進む — 検証していない作業を基に次の作業を進めないでください。作成のたびに get_metadata を、コンポーネントごとに get_screenshot を実行してください。
13. use_figma の呼び出しを並列化しない — Figma の状態変更は厳密に順次実行する必要があります。ツールが並列呼び出しに対応していても、2 つの use_figma 呼び出しを同時に実行しないでください。
14. Node ID を絶対に捏造しない — 以前の呼び出しから返された状態台帳を参照して、必ず ID を読み取ってください。記憶から ID を再構成したり、推測したりしないでください。
15. ヘルパースクリプトを使用 — scripts/ のスクリプトを use_figma の呼び出しに埋め込んでください。ゼロから 200 行のインラインスクリプトを書かないでください。
16. 各フェーズの明示的な承認 — 各チェックポイントで、次のフェーズを明示してください。フェーズ 1 について尋ねた場合、「よさそうです」だけではフェーズ 3 に進む承認になりません。

---

4. 状態管理（長いワークフローで必須）

getPluginData() / setPluginData() は use_figma ではサポートされていません。 代わりに getSharedPluginData() / setSharedPluginData() を使用するか（こちらはサポートされています）、名前ベースの検索と状態台帳（返された ID）を使用してください。

エンティティの種類	冪等性キー	存在の確認方法
シーンノード（ページ、フレーム、コンポーネント）	setSharedPluginData('dsb', 'key', value) または一意の名前	node.getSharedPluginData('dsb', 'key') または page.findOne(n => n.name === 'Button')
変数	コレクション内の名前	(await figma.variables.getLocalVariablesAsync()).find(v => v.name === name && v.variableCollectionId === collId)
スタイル	名前	getLocalTextStyles().find(s => s.name === name)

作成したシーンノードには、作成直後にすべてタグを付けます。

node.setSharedPluginData('dsb', 'run_id', RUN_ID);        // identifies this build run
node.setSharedPluginData('dsb', 'phase', 'phase3');        // which phase created it
node.setSharedPluginData('dsb', 'key', 'component/button');// unique logical key

状態の永続化：状態台帳を会話のコンテキストだけに頼らないでください。ディスクに書き込みます。

/tmp/dsb-state-{RUN_ID}.json

毎ターンの開始時にこのファイルを再読み込みします。長いワークフローでは会話のコンテキストが切り詰められるため、このファイルを信頼できる情報源とします。

以下を追跡する状態台帳を維持します。

{
  "runId": "ds-build-2024-001",
  "phase": "phase3",
  "step": "component-button",
  "entities": {
    "collections": { "primitives": "id:...", "color": "id:..." },
    "variables": { "color/bg/primary": "id:...", "spacing/sm": "id:..." },
    "pages": { "Cover": "id:...", "Button": "id:..." },
    "components": { "Button": "id:..." }
  },
  "pendingValidations": ["Button:screenshot"],
  "completedSteps": ["phase0", "phase1", "phase2", "component-avatar"]
}

冪等性チェック：作成する前に毎回、名前と状態台帳の ID で検索します。見つかった場合はスキップまたは更新し、重複は作成しません。

再開プロトコル：セッション開始時、またはコンテキストが切り詰められた後に、読み取り専用の use_figma を実行し、すべてのページ、コンポーネント、変数、スタイルを名前でスキャンして {key → id} マップを再構築します。その後、利用可能であればディスクから状態ファイルを再読み込みします。

続行用プロンプト（新しいチャットで再開するときにユーザーに提示します）：

「デザインシステムの構築を続けます。実行 ID：{RUN_ID}。figma-generate-library スキルを読み込み、最後に完了したステップから再開してください。」

---

5. search_design_system — 再利用の判断マトリクス

まずフェーズ 0 で検索し、各コンポーネントを作成する直前にも再度検索します。

search_design_system({ query, fileKey, includeComponents: true, includeVariables: true, includeStyles: true })

以下をすべて満たす場合は再利用します。

• コンポーネントのプロパティ API が要件に合っている（同じバリアント軸で、型に互換性がある）
• トークンのバインド方式に互換性がある（同じ変数を使用するか、エイリアス化できる変数を使用する）
• 命名規則が対象ファイルに合っている
• コンポーネントを編集できる（所有していないリモートライブラリでロックされていない）

以下のいずれかに該当する場合は再構築します。

• API に互換性がない（プロパティ名が異なる、バリアントのモデルが適切でない）
• トークンモデルに互換性がない（値がハードコードされている、変数スキーマが異なる）
• 所有権に問題がある（ライブラリを変更できない）

見た目は一致しているものの API に互換性がない場合は、ラップします。

• ライブラリのコンポーネントを、新しいラッパーコンポーネント内にネストしたインスタンスとしてインポートします
• ラッパーに使いやすい API を公開します

3 つの優先順位：既存のローカルコンポーネント → サブスクライブ済みライブラリからのインポート → 新規作成。

---

6. ユーザー確認ポイント

必須です。デザイン上の判断には人の判断が必要です。

タイミング	必要な成果物	確認事項
調査とスコープの確定後	トークン一覧、コンポーネント一覧、ギャップ分析	「こちらが計画です。作成を始める前に承認しますか？」
基盤の作成後	変数の概要（N 個のコレクション、M 個の変数、K 個のモード）、スタイル一覧	「すべてのトークンを作成しました。ファイル構成に進む前に確認しますか？」
ファイル構成の作成後	ページ一覧とスクリーンショット	「ページを設定しました。コンポーネントに進む前に確認しますか？」
各コンポーネントの作成後	コンポーネントページの get_screenshot	「N 個のバリアントを含む [Component] です。問題ありませんか？」
各不一致（コード ≠ Figma）	両方のバージョンを表示	「コードでは X、Figma では Y となっています。どちらを優先しますか？」
最終 QA	ページごとのスクリーンショットと監査レポート	「完了しました。承認しますか？」

ユーザーに却下された場合：先に進む前に修正します。却下された作業を土台にして構築してはいけません。

---

7. 命名規則

既存のファイル規則に合わせてください。新規に始める場合は、次のとおりです。

変数（スラッシュ区切り）：

color/bg/primary     color/text/secondary    color/border/default
spacing/xs  spacing/sm  spacing/md  spacing/lg  spacing/xl  spacing/2xl
radius/none  radius/sm  radius/md  radius/lg  radius/full
typography/body/font-size    typography/heading/line-height

プリミティブ：blue/50 → blue/900、gray/50 → gray/900

コンポーネント名：Button、Input、Card、Avatar、Badge、Checkbox、Toggle

バリアント名：Property=Value, Property=Value — 例：Size=Medium, Style=Primary, State=Default

ページ区切り：---（最も一般的）または ——— COMPONENTS ———

命名規則の完全なリファレンス：naming-conventions.md

---

8. トークンアーキテクチャ

複雑さ	パターン
50 トークン未満	単一コレクション、2 モード（Light/Dark）
50～200 トークン	標準：プリミティブ（1 モード）＋カラーセマンティック（Light/Dark）＋スペーシング（1 モード）＋タイポグラフィ（1 モード）
200 トークン以上	高度：複数のセマンティックコレクション、4～8 モード（Light/Dark × Contrast × Brand）。token-creation.md の M3 パターンを参照してください

標準パターン（開始時に推奨）：

Collection: "Primitives"    modes: ["Value"]
  blue/500 = #3B82F6, gray/900 = #111827, ...

Collection: "Color"         modes: ["Light", "Dark"]
  color/bg/primary → Light: alias Primitives/white, Dark: alias Primitives/gray-900
  color/text/primary → Light: alias Primitives/gray-900, Dark: alias Primitives/white

Collection: "Spacing"       modes: ["Value"]
  spacing/xs = 4, spacing/sm = 8, spacing/md = 16, ...

---

9. フェーズごとのアンチパターン

フェーズ 0 のアンチパターン：

• ❌ ユーザーとスコープを確定する前に何かを作成し始める
• ❌ 既存のファイル規則を無視して、新しい規則を押し付ける
• ❌ コンポーネント作成を計画する前に search_design_system を実行しない

フェーズ 1 のアンチパターン：

• ❌ 変数に ALL_SCOPES を使用する
• ❌ エイリアスを使わず、セマンティックレイヤーに生の値を重複して記述する
• ❌ コード構文を設定しない（Dev Mode とラウンドトリップが機能しなくなります）
• ❌ トークンの分類体系について合意する前にコンポーネントトークンを作成する

フェーズ 2 のアンチパターン：

• ❌ カバーページや基盤ドキュメントを省略する
• ❌ 関連のない複数のコンポーネントを 1 ページに配置する

フェーズ 3 のアンチパターン：

• ❌ 基盤が整う前にコンポーネントを作成する
• ❌ コンポーネント内の塗りつぶし、線、スペーシング、角丸の値をハードコードする
• ❌ アイコンごとにバリアントを作成する（代わりに INSTANCE_SWAP を使用してください）
• ❌ combineAsVariants の実行後にバリアントを配置しない（すべて 0,0 に重なります）
• ❌ 分割せずに 30 を超えるバリアントマトリックスを構築する（バリアントの爆発的増加）
• ❌ リモートコンポーネントをインポートして、すぐにデタッチする

一般的なアンチパターン：

• ❌ エラーの内容を理解せずに、失敗したスクリプトを再試行する
• ❌ クリーンアップに名前のプレフィックス一致を使う（ユーザー所有のノードが削除されます）
• ❌ 前のステップで検証されていない作業を基に進める
• ❌ 「時間を節約する」ためにユーザーのチェックポイントを省略する
• ❌ use_figma 呼び出しを並列化する（必ず逐次実行してください）
• ❌ 記憶を頼りにノード ID を推測する（必ず状態台帳から読み取ってください）
• ❌ 提供されたヘルパースクリプトを使わず、巨大なインラインスクリプトを書く
• ❌ フェーズ 0～2 を完了せずに、ユーザーが「ボタンを作って」と言っただけでフェーズ 3 を始める

---

10. リファレンスドキュメント

必要に応じて読み込んでください。各リファレンスは、該当するフェーズでの正式な情報源です。

必要なときは、ファイル読み取りツールを使ってこれらのドキュメントを読んでください。ファイル名から内容を推測しないでください。

ドキュメント	フェーズ	必須／任意	読み込むタイミング
discovery-phase.md	0	必須	あらゆるビルドを始めるとき — コードベースの分析と Figma の調査
token-creation.md	1	必須	変数、コレクション、モード、スタイルを作成するとき
documentation-creation.md	2	必須	カバーページ、基盤ドキュメント、スウォッチを作成するとき
component-creation.md	3	必須	コンポーネントまたはバリアントを作成するとき
code-connect-setup.md	3–4	必須	Code Connect または変数のコード構文を設定するとき
naming-conventions.md	任意	任意	変数、ページ、バリアント、スタイルなどに名前を付けるとき
error-recovery.md	任意	エラー発生時に必須	スクリプトの失敗、複数ステップのワークフローからの復旧、放棄されたワークフロー状態のクリーンアップ

---

11. スクリプト

再利用可能な Plugin API のヘルパー関数です。use_figma 呼び出しに埋め込んでください。

スクリプト	用途
inspectFileStructure.js	すべてのページ、コンポーネント、変数、スタイルを検出し、完全な一覧を返します
createVariableCollection.js	モードを含む名前付きコレクションを作成し、{collectionId, modeIds} を返します
createSemanticTokens.js	トークンマップからエイリアス付きのセマンティック変数を作成します
createComponentWithVariants.js	バリアントマトリックスからコンポーネントセットを作成し、グリッドレイアウトを処理します
bindVariablesToComponent.js	デザイントークンをすべてのコンポーネントの視覚的プロパティにバインドします
createDocumentationPage.js	タイトル、説明、セクション構造を含むページを作成します
validateCreation.js	作成されたノードが想定される数、名前、構造と一致するか確認します
cleanupOrphans.js	名前の規則または状態台帳の ID に基づいて孤立ノードを削除します
rehydrateState.js	ファイルをスキャンして、名前に基づくすべてのページ、コンポーネント、変数を検出し、状態を再構築するための完全な {key → nodeId} マップを返します