code-connect-components

Code Connect コンポーネント

概要

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

前提条件

• Figma MCP サーバーが接続され、アクセス可能である必要があります
  • 続行する前に、Figma MCP ツール（例：get_code_connect_suggestions）が利用可能かどうかを確認し、Figma MCP サーバーが接続されていることを確認してください。
  • ツールが利用できない場合、Figma MCP サーバーが有効になっていない可能性があります。プラグインに含まれている Figma MCP サーバーを有効にするようユーザーに案内してください。その後、MCP クライアントの再起動が必要になる場合があります。
• ユーザーがノード ID を含む Figma URL を提供する必要があります：https://figma.com/design/:fileKey/:fileName?node-id=1-2
  • 重要： Figma URL には node-id パラメーターが必要です。これがないと、Code Connect のマッピングは失敗します。
• 重要： Figma コンポーネントはチームライブラリに公開されている必要があります。Code Connect は公開済みのコンポーネントまたはコンポーネントセットでのみ機能します。
• 重要： Code Connect は Organization および Enterprise プランでのみ利用できます。
• コンポーネントのスキャンに必要なプロジェクトのコードベースへのアクセス

必須のワークフロー

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

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

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

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

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. ユーザーに提示します：「一致するものが見つかりました：

   • Button：nodeId 42:15 の Button

   このコンポーネントを接続しますか？」

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. ユーザーに提示します： 「デザインに一致する以下のコンポーネントが見つかりました：

   • ProductCard：nodeId 10:51 の ProductCard
   • Badge：nodeId 10:52 の Badge

   CustomWidget（10:53）に一致するものは見つかりませんでした。

   これらのコンポーネントを接続しますか？すべて承認するか、特定のものを選択するか、スキップできます。」

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 のコンポーネントとコードのコンポーネントを比較する際は、名前だけでなく、次の点も確認してください。

• プロパティが一致している（バリアントの種類、サイズの選択肢など）
• コンポーネントの階層が一致している（ネストされた要素）
• コンポーネントの用途が同じである

明確な説明

マッピングの作成を提案する際は、次の点を明確に説明してください。

• 見つかった内容
• 適切な一致候補である理由
• マッピングでできること
• プロパティの接続方法

曖昧さへの対応

一致する可能性のあるコンポーネントが複数ある場合は、推測せずに候補を提示してください。どのコンポーネントを接続するかは、ユーザーが最終的に決められるようにしてください。

適切な代替案の提示

完全に一致するものが見つからない場合は、次のような有用な対応を提示してください。

• 近い候補を示す
• コンポーネントの作成を提案する
• ユーザーに希望を尋ねる

よくある問題と解決策

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

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

問題：Code Connect のマッピングが URL エラーで失敗します

原因： 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 Server のツールとプロンプト