figma-code-connect-components

Code Connect コンポーネント

概要

このスキルは、Figma の Code Connect 機能を使用して、Figma のデザインコンポーネントを対応するコード実装に接続するのに役立ちます。Figma のデザイン構造を分析し、コードベースから一致するコンポーネントを検索して、デザインとコードの一貫性を保つマッピングを設定します。

スキルの適用範囲

• get_code_connect_suggestions と send_code_connect_mappings のワークフローには、このスキルを使用してください。
• Plugin API スクリプトで Figma キャンバスに書き込む必要がある場合は、figma-use に切り替えてください。
• コードや説明から Figma の全ページ画面を作成または更新する場合は、figma-generate-design に切り替えてください。
• Figma からプロダクトコードを実装する場合は、figma-implement-design に切り替えてください。

前提条件

• Figma MCP サーバーに接続でき、アクセス可能であること
• ユーザーがノード ID を含む Figma URL を提供すること：https://figma.com/design/:fileKey/:fileName?node-id=1-2
  • 重要： Figma URL には node-id パラメーターが必要です。これがないと Code Connect のマッピングに失敗します。
• または figma-desktop MCP を使用する場合：ユーザーが Figma デスクトップアプリでノードを直接選択できること（URL は不要）
• 重要： Figma コンポーネントはチームライブラリに公開されている必要があります。Code Connect は公開済みのコンポーネントまたはコンポーネントセットでのみ動作します。
• 重要： Code Connect は Organization プランと Enterprise プランでのみ利用できます。
• コンポーネントのスキャンに必要なプロジェクトのコードベースへのアクセス

必須のワークフロー

以下の手順を順番に実行してください。手順を省略しないでください。

ステップ 1：Code Connect の候補を取得する

get_code_connect_suggestions を呼び出し、マッピングされていないすべてのコンポーネントを一度の操作で特定します。このツールは以下を自動的に行います。

• Figma のシーングラフからコンポーネント情報を取得する
• 選択範囲内の公開済みコンポーネントを特定する
• 既存の Code Connect マッピングを確認し、すでに接続されているコンポーネントを除外する
• マッピングされていない各コンポーネントの名前、プロパティ、サムネイル画像を返す

オプション A：figma-desktop MCP を使用する場合（URL が提供されていない場合）

figma-desktop MCP サーバーに接続されていて、ユーザーが Figma URL を提供していない場合は、すぐに get_code_connect_suggestions を呼び出してください。URL の解析は不要です。デスクトップ MCP サーバーが、開いている Figma ファイルで現在選択されているノードを自動的に使用します。

注： ユーザーは Figma デスクトップアプリを開き、ノードを選択している必要があります。fileKey はパラメーターとして渡しません。サーバーは現在開いているファイルを使用します。

オプション B：Figma URL が提供されている場合

URL を解析して fileKey と nodeId を抽出し、get_code_connect_suggestions を呼び出します。

重要： Figma URL からノード ID を抽出する際は、形式を変換してください。

• URL 形式ではハイフンを使用します：node-id=1-2
• ツールではコロンを使用します：nodeId=1:2

Figma URL を解析する：

• URL 形式：https://figma.com/design/:fileKey/:fileName?node-id=1-2
• ファイルキーを抽出：:fileKey（/design/ の後のセグメント）
• ノード ID を抽出：URL から 1-2 を取得し、ツール用に 1:2 に変換

get_code_connect_suggestions(fileKey=":fileKey", nodeId="1:2")

応答を処理する：

• ツールが 「No published components found in this selection」 を返した場合 → ユーザーに伝えて終了します。先にコンポーネントをチームライブラリに公開する必要がある可能性があります。
• ツールが 「All component instances in this selection are already connected to code via Code Connect」 を返した場合 → すべてのマッピングが完了していることをユーザーに伝えます。
• それ以外の場合、応答にはマッピングされていないコンポーネントの一覧が含まれ、各コンポーネントについて次の情報が提供されます。
  • コンポーネント名
  • ノード ID
  • コンポーネントのプロパティ（プロパティ名と値を含む JSON）
  • コンポーネントのサムネイル画像（目視確認用）

ステップ 2：コードベースを検索して一致するコンポーネントを探す

get_code_connect_suggestions が返した未マッピングのコンポーネントごとに、コードベースを検索して一致するコードコンポーネントを探します。

確認する項目：

• Figma コンポーネント名と一致する、または類似するコンポーネント名
• Figma の階層と一致するコンポーネント構造
• Figma のプロパティ（バリアント、テキスト、スタイル）に対応するプロパティ
• 一般的なコンポーネントディレクトリ（src/components/、components/、ui/ など）にあるファイル

検索方法：

1. 一致する名前のコンポーネントファイルを検索します
2. 候補ファイルを読み、構造とプロパティを確認します
3. コードコンポーネントのプロパティを、ステップ 1 で返された Figma コンポーネントのプロパティと比較します
4. プログラミング言語（TypeScript、JavaScript）とフレームワーク（React、Vue など）を特定します
5. 以下を考慮して、構造上最も一致する候補を特定します：
   • プロパティ名と Figma プロパティとの対応関係
   • Figma のデフォルト値と一致するデフォルト値
   • CSS クラスまたはスタイルオブジェクト
   • 意図を明確にする説明コメント
6. 複数の候補が同程度に適している場合は、プロパティインターフェースが最も近いものを選び、ツールを呼び出す前に 1～2 文のコメントで判断理由を記述します

検索パターンの例：

• Figma コンポーネントが「PrimaryButton」の場合は、Button.tsx、PrimaryButton.tsx、Button.jsx を検索します
• 一般的なコンポーネントパスを確認します：src/components/、app/components/、lib/ui/
• Figma のバリアントに一致する variant、size、color などのプロパティを探します

ステップ 3：一致候補を提示する

調査結果を提示し、どのマッピングを作成するかユーザーに選んでもらいます。ユーザーは、提案されたマッピングのすべて、一部、またはなしを選択できます。

次の形式で一致候補を提示します：

The following components match the design:
- [ComponentName](path/to/component): DesignComponentName at nodeId [nodeId](figmaUrl?node-id=X-Y)
- [AnotherComponent](path/to/another): AnotherDesign at nodeId [nodeId2](figmaUrl?node-id=X-Y)

Would you like to connect these components? You can accept all, select specific ones, or skip.

コンポーネントに完全一致するものが見つからない場合：

• 最も近い候補を 2 つ表示します
• 相違点を説明します
• どのコンポーネントを使うか確認するか、正しいパスを提示するようユーザーに尋ねます

ユーザーがすべてのマッピングを拒否した場合は、その旨を伝えて終了します。これ以上ツールを呼び出す必要はありません。

ステップ 4：Code Connect マッピングを作成する

ユーザーが選択を確定したら、受け入れられたマッピングのみを指定して send_code_connect_mappings を呼び出します。このツールは、すべてのマッピングを 1 回の呼び出しで一括作成します。

例：

send_code_connect_mappings(
  fileKey=":fileKey",
  nodeId="1:2",
  mappings=[
    { nodeId: "1:2", componentName: "Button", source: "src/components/Button.tsx", label: "React" },
    { nodeId: "1:5", componentName: "Card", source: "src/components/Card.tsx", label: "React" }
  ]
)

各マッピングの主なパラメーター：

• nodeId：Figma ノード ID（コロン形式：1:2）
• componentName：接続するコンポーネントの名前（例：「Button」、「Card」）
• source：コードコンポーネントファイルへのパス（プロジェクトルートからの相対パス）
• label：この Code Connect マッピングのフレームワークまたは言語のラベル。有効な値は次のとおりです：
  • Web：'React'、'Web Components'、'Vue'、'Svelte'、'Storybook'、'Javascript'
  • iOS：'Swift UIKit'、'Objective-C UIKit'、'SwiftUI'
  • Android：'Compose'、'Java'、'Kotlin'、'Android XML Layout'
  • クロスプラットフォーム：'Flutter'
  • ドキュメント：'Markdown'

呼び出し後：

• 成功時：ツールがマッピングの作成を確認します
• エラー時：ツールが、失敗したマッピングとその理由（例：「コンポーネントはすでにコードにマッピングされています」、「公開済みのコンポーネントが見つかりません」、「権限が不足しています」）を報告します

処理後に概要を提示します：

Code Connect Summary:
- Successfully connected: 3
  - Button (1:2) → src/components/Button.tsx
  - Card (1:5) → src/components/Card.tsx
  - Input (1:8) → src/components/Input.tsx
- Could not connect: 1
  - CustomWidget (1:10) - No matching component found in codebase

例

例 1：ボタンコンポーネントの接続

ユーザー：「この Figma ボタンをコードに接続してください：https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15」

アクション：

1. URL を解析：fileKey=kL9xQn2VwM8pYrTb4ZcHjF、nodeId=42-15 → 42:15 に変換

2. get_code_connect_suggestions(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42:15") を実行

3. レスポンスには、variant（primary/secondary）と size（sm/md/lg）プロパティを持つ Button コンポーネント（未マッピング）とサムネイル画像が表示される

4. コードベースで Button コンポーネントを検索：src/components/Button.tsx が見つかる

5. Button.tsx を読み、variant と size の props があることを確認

6. ユーザーに提示：

   I found a match:
   - [Button](src/components/Button.tsx): Button at nodeId [42:15](https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15)
   
   Would you like to connect this component?
   

7. ユーザーが確認：「はい」

8. TypeScript の React コンポーネントであることを検出

9. send_code_connect_mappings(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42:15", mappings=[{ nodeId: "42:15", componentName: "Button", source: "src/components/Button.tsx", label: "React" }]) を実行

結果： Figma のボタンコンポーネントが、コード内の Button コンポーネントに接続されました。

例 2：一部選択での複数コンポーネントの接続

ユーザー：「このフレーム内のコンポーネントを接続してください：https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Components?node-id=10-50」

アクション：

1. URL を解析：fileKey=pR8mNv5KqXzGwY2JtCfL4D、nodeId=10-50 → 10:50 に変換

2. get_code_connect_suggestions(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10:50") を実行

3. レスポンスには、未マッピングのコンポーネントが 3 つ表示される：ProductCard、Badge、CustomWidget

4. コードベースを検索：

   • ProductCard：src/components/ProductCard.tsx が見つかる（props が一致）
   • Badge：src/components/Badge.tsx が見つかる（props が一致）
   • CustomWidget：一致するコンポーネントが見つからない

5. ユーザーに提示：

   The following components match the design:
   - [ProductCard](src/components/ProductCard.tsx): ProductCard at nodeId [10:51](https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Components?node-id=10-51)
   - [Badge](src/components/Badge.tsx): Badge at nodeId [10:52](https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Components?node-id=10-52)
   
   I couldn't find a match for CustomWidget (10:53).
   
   Would you like to connect these components? You can accept all, select specific ones, or skip.
   

6. ユーザー：「ProductCard だけ接続して、Badge はいったんスキップしてください」

7. send_code_connect_mappings(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10:50", mappings=[{ nodeId: "10:51", componentName: "ProductCard", source: "src/components/ProductCard.tsx", label: "React" }]) を実行

結果： ユーザーの選択に従い、ProductCard のみが接続されました。

例 3：コンポーネントの作成が必要な場合

ユーザー：「このアイコンを接続してください：https://figma.com/design/8yJDMeWDyBz71EnMOSuUiw/Icons?node-id=5-20」

アクション：

1. URL を解析：fileKey=8yJDMeWDyBz71EnMOSuUiw、nodeId=5-20 → 5:20 に変換
2. get_code_connect_suggestions(fileKey="8yJDMeWDyBz71EnMOSuUiw", nodeId="5:20") を実行
3. レスポンスには、color と size のプロパティを持つ CheckIcon コンポーネント（未マッピング）が表示される
4. コードベースで CheckIcon を検索：一致するものが見つからない
5. 汎用の Icon コンポーネントを検索：他のアイコンがある src/icons/ ディレクトリが見つかる
6. ユーザーに報告：「CheckIcon コンポーネントは見つかりませんでしたが、src/icons/ にアイコンのディレクトリが見つかりました。次のいずれかを行いますか？
   • 先に新しい CheckIcon.tsx コンポーネントを作成してから接続する
   • 別の既存アイコンに接続する
   • CheckIcon が別の場所にある場合は、そのパスを指定する」
7. ユーザーがパスを提示：「src/icons/CheckIcon.tsx」
8. ファイルから言語とフレームワークを検出
9. send_code_connect_mappings(fileKey="8yJDMeWDyBz71EnMOSuUiw", nodeId="5:20", mappings=[{ nodeId: "5:20", componentName: "CheckIcon", source: "src/icons/CheckIcon.tsx", label: "React" }]) を実行

結果： CheckIcon コンポーネントが Figma のデザインに正常に接続されました。

ベストプラクティス

積極的なコンポーネントの発見

ユーザーにファイルパスを尋ねるだけでなく、コードベースを積極的に検索して、一致するコンポーネントを見つけます。これにより、より良い体験を提供し、マッピングできる可能性を見つけられます。

正確な構造の照合

Figma のコンポーネントとコードのコンポーネントを比較するときは、名前だけでなく、以下も確認します。

• props が一致している（variant の型、size の選択肢など）
• コンポーネントの階層が一致している（ネストされた要素）
• コンポーネントが同じ目的を果たしている

明確なコミュニケーション

マッピングを提案するときは、以下を明確に説明します。

• 見つかったもの
• なぜ適切な一致なのか
• マッピングによって何が行われるのか
• props がどのように接続されるのか

曖昧さへの対処

一致する可能性のあるコンポーネントが複数ある場合は、推測せずに候補を提示します。どのコンポーネントに接続するかは、ユーザーが最終的に判断できるようにします。

適切な代替策の提示

完全に一致するものが見つからない場合は、次に取るべき手順を提示します。

• 類似する候補を表示する
• コンポーネントの作成を提案する
• ユーザーに指示を求める

よくある問題と解決策

問題：「この選択範囲に公開済みコンポーネントが見つかりません」

原因： Figma のコンポーネントがチームライブラリに公開されていません。Code Connect は公開済みコンポーネントでのみ動作します。 解決策： ユーザーは Figma でコンポーネントをチームライブラリに公開する必要があります。

1. Figma で、コンポーネントまたはコンポーネントセットを選択します
2. 右クリックして「ライブラリに公開」を選択するか、チームライブラリの公開モーダルを使用します
3. コンポーネントを公開します
4. 公開後、同じノード ID で Code Connect のマッピングを再試行します

問題：「Code Connect は Organization プランおよび Enterprise プランでのみ利用できます」

原因： ユーザーの Figma プランには Code Connect の利用権が含まれていません。 解決策： ユーザーは Organization プランまたは Enterprise プランにアップグレードするか、管理者に問い合わせる必要があります。

問題：コードベース内に一致するコンポーネントが見つからない

原因： コードベースの検索で、名前または構造が一致するコンポーネントが見つかりませんでした。 解決策： 別の名前または場所にコンポーネントが存在するかどうかをユーザーに確認します。まずコンポーネントを作成する必要があるか、予期しないディレクトリに配置されている可能性があります。

問題：「公開済みコンポーネントが見つかりません」（CODE_CONNECT_ASSET_NOT_FOUND）

原因： ソースファイルのパスが正しくない、コンポーネントがその場所に存在しない、または componentName が実際のエクスポート名と一致していません。 解決策： ソースパスが正しく、プロジェクトルートからの相対パスであることを確認します。指定した componentName と完全に一致する名前で、コンポーネントがファイルから正しくエクスポートされていることを確認します。

問題：「コンポーネントはすでにコードにマッピングされています」（CODE_CONNECT_MAPPING_ALREADY_EXISTS）

原因： このコンポーネントには、すでに Code Connect のマッピングがあります。 解決策： コンポーネントはすでに接続されています。ユーザーがマッピングを更新する場合は、まず Figma で既存のマッピングを削除する必要があります。

問題：「マッピングを作成する権限が不足しています」（CODE_CONNECT_INSUFFICIENT_PERMISSIONS）

原因： ユーザーには Figma ファイルまたはライブラリの編集権限がありません。 解決策： ユーザーには、コンポーネントを含むファイルへの編集アクセス権が必要です。ファイルの所有者またはチーム管理者に問い合わせてください。

問題：URL エラーにより Code Connect のマッピングに失敗する

原因： Figma URL の形式が正しくないか、node-id パラメーターがありません。 解決策： URL が必須の形式に従っていることを確認します：https://figma.com/design/:fileKey/:fileName?node-id=1-2。node-id パラメーターは必須です。また、ツールを呼び出す際は 1-2 を 1:2 に変換してください。

問題：類似するコンポーネントが複数見つかった

原因： コードベースに、Figma コンポーネントと一致する可能性のあるコンポーネントが複数あります。 解決策： ファイルパスとともにすべての候補をユーザーに提示し、接続するものを選んでもらいます。異なるコンポーネントが異なるコンテキストで使用されている場合があります（例：Button.tsx と LinkButton.tsx）。

Code Connect について

Code Connect は、デザインとコードの双方向リンクを確立します。

デザイナー向け： Figma コンポーネントを実装するコードコンポーネントを確認できます 開発者向け： Figma のデザインから、それを実装するコードに直接移動できます チーム向け： コンポーネントのマッピングを信頼できる唯一の情報源として維持できます

作成したマッピングにより、こうしたつながりが明確になり、見つけやすくなるため、デザインとコードの同期を保ちやすくなります。

追加リソース

Code Connect の詳細については、以下を参照してください。

• Code Connect のドキュメント
• Figma MCP サーバーのツールとプロンプト