figma-build

figma-build

コードや説明を、ファイルに自然になじむ Figma デザインに変換します。既存のコンポーネント、変数、スタイルを再利用し、本当に不足しているものだけを作成します。 これは figma-codegen の対をなす機能です。「再生成より再利用を優先する／リテラルではなく参照トークンを使う」という同じ理念を、コードベースではなくキャンバスに適用します。このファイルはルーターです。詳しい情報は references/ にあります。手順に該当するリファレンスを読み込んでください。

接続されている Figma ファイル（プラグインの現在のセッション）を操作します。URL から取得することはできないため、ユーザーが対象のファイルを開いている必要があります。作成を始める前に、プラグインが接続されていることを ping で確認してください。

使用する場面

• コードや説明をもとに、Figma で何かを作成または更新する場合。画面、ビュー、モーダル／ダイアログ／ドロワー／サイドバー／パネル、単一のコンポーネント、デザインシステムのアセットなどが該当します。
• Figma のデザインをコードに変換する場合には使用しません。その場合は figma-codegen を使ってください。

複数の Figma ファイルが開いている場合

該当する場合は、すべてのツール結果にその旨が表示されるため、あらかじめ確認する必要はありません。2 つ以上のファイルが接続され、どのファイルも指定されていない場合、結果にはファイル名を列挙した MORE THAN ONE FIGMA FILE IS OPEN ブロックが含まれます。指定が重要なのは、指定しないと呼び出しはユーザーが最後に操作したファイルに従い、タブの切り替えによって対象が変わるためです。その結果、タスクで一方のファイルを読み取り、別のファイルに書き込んでしまっても、成功したと報告される可能性があります。

この表示が出た場合は、ほかの操作をする前にファイルを指定してください。list_files ですべての接続済みファイルを確認し、use_file({ fileName }) でこのセッションにファイルを指定します。名前が同じファイルが 2 つ開いている場合は use_file({ sessionId }) を使ってください。Figma では同じ名前のファイルを開くことができ、そのような場合は x (Copy) のように表示されます。以降の呼び出しはすべて、タブがバックグラウンドにあっても、画面の手前にあるファイルにかかわらず、指定したファイルを対象にします。ユーザーがどのファイルか明示していない場合は、名前から推測せず、確認してください。

まず環境を理解してから構築する（プロバイダー優先）

これは、コード生成のグラウンディングにおける書き込み側のミラーであり、最も重要な習慣です。見た目が不自然なビルドの原因は、ほとんどの場合、値を勝手に作ったこと、または慣例を決めつけたことにあります。ですから、まずユーザーの実際の環境を理解し、それに合わせて構築してください。汎用テンプレートを適用してはいけません。「唯一の正しい」スタックがあるわけではなく、あるのは その人の スタックです。何かを作成する前に、両端を確認してください。

• Figma ファイル — 既存のデザインシステムを再利用し、それにバインドします。
  1. get_variable_defs → ファイルの変数（カラー／間隔／角丸／タイポグラフィ）を、名前・値・hex とともに取得します。これらがバインドするトークンです。
  2. scan_components ／ get_local_components → 作り直すのではなく、インスタンス化する既存のコンポーネントを取得します。元の UI パターン（カード、リスト行、ナビゲーション、ボタン）に合うコンポーネントを選びます。
  3. get_styles → 適用する共有のペイント／テキスト／エフェクトスタイルを取得します。
  4. 公開済みライブラリにあるデザインシステム — これらの読み取りで一覧表示されるのは、ファイル自身の定義だけです。結果が空、または少なくても、そのファイルがチームライブラリを使っている場合（コンポーネントがライブラリのインスタンスである、またはユーザーがそう述べている場合）、トークンはライブラリファイルにあります。そこでキーを読み取り、バインドするものをインポートしてください。「トークンなし」と判断して値をハードコードしてはいけません。 → references/write-rules.md、「公開済みライブラリのトークン」。
• 渡されたソース — コードの場合は、どのスタックとスタイリングシステム（Tailwind ／ Chakra ／ MUI ／ CSS modules ／ vanilla など）を使っているか、また設定／テーマ／トークンファイルがあるかを確認します。実際の値はそこにあります。デフォルトを決めつけず、そこから読み取ってください。

次に、すべての値の出典を優先順位に沿ってたどりながら構築します。既存のコンポーネント／変数／スタイルを再利用し、ない場合はソースコードにある正確な値を使います。プロバイダーを優先し、使用しているスタイリングシステムを実際の px ／ hex に変換します（CSS はそのまま、Tailwind ／ Chakra ／ UnoCSS などは設定またはスケールから取得）。目視で推測してはいけません。どちらもない場合に限り、一貫したスケールに基づいて値を新たに作成します。詳細と値の解決方法については references/write-rules.md を参照してください。

2 つの作業 — どちらも書き込みルールに従う

すべてのビルドに、同じ共通ルールが適用されます。値の根拠を確認する（デザインシステム → ソースコード → スケール）、トークンを参照する（カラーは bind_variable_to_paint、スカラー値は bind_variable_to_node、共有スタイルは apply_style_to_node）、関連する子要素にはオートレイアウトを使う（絶対配置は最上位の配置にのみ使う）、set_layout_props で HUG ／ FILL ／ FIXED のサイズ指定を行う（レイアウトにサイズを計算させ、幅／高さをハードコードしない）、実際のフォントを使う（新しい TEXT ノードのデフォルトは Inter）。→ references/write-rules.md。

• 既存の要素を使って画面／コンポーネントを組み立てる（一般的なケース）：UI パターンを認識し、一致するコンポーネントを create_instance で作成し、トークンをバインドして、段階的に構築し、各段階をスクリーンショットで確認します。→ references/assemble-screens.md。
• 新しいデザインシステムのアセットを作成する（グラウンディングの結果、同等のものが見つからない場合のみ）：変数／コレクション、ペイント／テキストスタイル、またはコンポーネントとバリアントセットを作成し、その後、再利用の手順に戻ります。→ references/author-design-system.md。

モーション（アニメーション）

ソースにアニメーション（CSS @keyframes ／ transition、Framer Motion、GSAP、Vue ／ Svelte のトランジション）が含まれている場合は、削除せず、構築したフレームに Figma の**モーション（ベータ版）として作成します。長さには set_timeline_duration を使い、apply_animation_style（get_motion_styles で取得したプリセット）またはプロパティごとの apply_manual_keyframe_track を使います。段階的に表示される行は、config.timelineOffset を増やしながら apply_animation_style の操作をまとめた1 つのアトミックな batch**にします。モーションが使えるのは Figma-Design のみで、キーフレームは最上位フレームのレイヤーに適用されるため、先にフレームを作成してください。→ references/motion.md。

見た目を確認する（最後まで確認する）

構築したノードを get_screenshot で撮影し、差異を修正して、もう一度スクリーンショットを撮ります。コード生成が行う、同じ描画と差分確認の作業を逆方向に行います。元の意図と照らし合わせるだけでなく、客観的なデザイン品質も確認します（曖昧な説明に基づいて構築し、比較対象となるソースがない場合にも問題を見つけられます）。何も切れたり、はみ出したりしていないこと、エッジが揃っていること、余白が一貫していること（単一のスケール）、明確なタイポグラフィの階層があることを確認します。empty: true のエクスポートは、ノードが何も描画しなかったことを意味します（非表示／キャンバス外）。

ルール

• 環境を理解してから構築します。 何かを作成する前に、ファイルのデザインシステムとソースのスタック／スタイルシステムの両方を確認します。唯一の正解となるスタックはなく、選ぶのはそのファイルで使われているスタックです。すべての値は、デザインシステム → コード内の値 → 妥当なスケールの順に根拠を持たせ、決して推測で作りません。
• 再生成より再利用を優先します。 既存のコンポーネントをインスタンス化し、既存の変数／スタイルをバインドします。新たに作成するのは、システムに存在しないものだけとし、既存の規則に合うよう命名・構成します。
• リテラルではなくトークンを参照します。 色には bind_variable_to_paint、スカラー値には bind_variable_to_node、共有の見た目には apply_style_to_node を使います。トークンがある場合は、16 進数や px 値をハードコードしません（利用可能なトークンは get_variable_defs で確認できます）。
• コード由来の色は sRGB と明記します。 r／g／b の値と並べて space: "SRGB" を指定します。指定しないと、Display P3 のファイルではコードより彩度が高く描画されます（references/write-rules.md）。
• 関連する子要素にはオートレイアウトを使い、絶対座標は最上位要素の配置に限ります。親の配置設定（primaryAxisAlignItems／counterAxisAlignItems）で中央揃えにします。異なる配置が必要な子要素には、それぞれ専用のラッパーフレームを用意し、x／y を調整して中央揃えにすることは避けます。レイアウトのない要素の整列／分布には align_nodes を使い、set_text_properties では textAlignHorizontal／textAlignVertical を指定します。レシピ、図形（create_shape、boolean_nodes、flatten_nodes）、およびツールでまだ描画できないものについては、references/write-rules.md の「Centering and alignment」を参照してください。
• 作成呼び出しは 1 回でスタイルまで設定します。 create_frame、create_rectangle、create_ellipse、create_shape、create_text では、fills、strokes、layoutSizing* を指定できます（フレームと長方形では cornerRadius も指定でき、フレームでは autoLayout と clipsContent も指定でき、テキストでは textAlignHorizontal を含むタイポグラフィ設定も指定できます）。各プロパティの意味は対応する set_* ツールと同じです。作成後に一連の追加呼び出しを行うのではなく、これらを使います。
• ok: true は成功の証明ではありません。 レイアウトに影響する書き込みは、スクリーンショットまたは読み戻しで確認し、ツールで表現できなかった内容があれば、完了したと主張せずに報告します。
• 段階的に構築して検証します（スクリーンショット）。UI パターンを見極め、プリミティブから再現するのではなく、対応するコンポーネントを組み合わせます。
• ファイルの規約に合わせます。 コード生成がプロジェクト既存のコードスタイルを踏襲するように、命名、構成、デザインシステム独自のパターンに従います。