はじめに

Figma Code Connect、導入していますか？
Figmaコンポーネントと Reactコードを直接紐付けられる非常に強力な機能ですが、いざ実装を始めると「ドキュメント通りに書いたはずなのに動かない」「どのAPIを使えばいいのか分からない」といった壁にぶつかることも少なくありません。

この記事では、実際に導入する際によく遭遇する「詰まりポイント」と、その「解決策」をQ&A形式でまとめました。
エラーが出たときの辞書代わりに活用してください。

目次：どんなエラーで困っていますか？

まず、直面している問題に近いものをクリックしてください。

Q. どのAPIを使えばいいか分からない（enum? instance? children?）
Q. figma.instance() や figma.children() でエラーが出る
Q. Error: The node-id points to a variant... というエラーが出る
Q. Error: Property "xxx" not found というエラーが出る
Q. 特定のバリアントだけコードが表示されない
番外編：コードをきれいに書くためのTips

Q1. どのAPIを使えばいいか分からない

Code Connectには似たようなAPIがいくつかあり、最初は迷います。
「Figma側でどう設定されているか」を確認して、以下の表と照らし合わせてください。

Figma側の設定	使うAPI	具体例
バリアント (Variant) 選択肢から選ぶタイプ	`figma.enum()`	Size: Small/Medium/Large State: Default/Hover
インスタンススワップコンポーネントを差し替える機能	`figma.instance()`	アイコンの差し替えスロットの中身
ただのレイヤーネストされた子要素	`figma.children()`	ボタン内のアイコンレイヤーカード内のコンテンツエリア
テキストプロパティ文字を変更できる箇所	`figma.string()` `figma.textContent()`	ラベルの文字列見出しのテキスト
ブーリアン (Boolean) スイッチ (ON/OFF)	`variant: { }` ※APIではない	アイコンの表示/非表示（マッピングで分岐させる）

基本パターン: `figma.enum()`

一番よく使うのがこれです。「Figmaの選択肢」を「Reactのpropsの値」に変換します。

import figma from '@figma/code-connect'
import { Button } from './Button'

figma.connect(Button, 'https://www.figma.com/...', {
  props: {
    // 第1引数: Figmaのプロパティ名
    // 第2引数: マッピング定義 { Figmaの値: Reactの値 }
    size: figma.enum('Size', {
      Small: 'sm',
      Medium: 'md',
      Large: 'lg',
    }),
  },
  example: ({ size }) => <Button size={size}>Label</Button>,
})

Q2. instanceとchildrenの違いと使い分け

ここが最もハマりやすいポイントです。
「子要素を取りたい」という目的は同じでも、Figmaの作りによって明確に使い分ける必要があります。

`figma.instance()` を使うケース

Figma上で「インスタンススワッププロパティ (Instance Swap)」として定義されている場合に使います。
Figmaの右サイドバー（プロパティパネル）で、ひし形（◇）のアイコンが付いているのが目印です。

// Figmaで「Start Icon」がInstance Swapの場合
props: {
  icon: figma.instance('Start Icon'),
}

`figma.children()` を使うケース

プロパティとしては定義されていないが、レイヤー構造の中にある子要素を取得したい場合に使います。例えば、スロットとして用意された空のフレームなどが該当します。

// 「ContentLayer」という名前のレイヤーの中身を取得
props: {
  content: figma.children('ContentLayer'),
}

Q3. node-idの指定ミス

エラー内容

Error: The node-id points to a variant, not a component set

原因と解決策

URLに含まれる node-id が、「個別のバリアント」 を指しています。
Code Connectには、「コンポーネントセット全体（親フレーム）」 のIDを指定する必要があります。

正しいURLの取得方法

Figmaキャンバス上で、紫色の点線枠（Component Set）を選択する。
- ※中のボタン単体を選ばないように注意！
右クリックして「リンクをコピー (Copy link)」を選択。
そのURLを使用する。

Q4. プロパティが見つからないエラー

エラー内容

Error: Property "size" not found on component

原因と解決策

プロパティ名の大文字・小文字が一致していない ことが原因です。
コード上では小文字（camelCase）を使いたくなりますが、第1引数にはFigma上の表記そのままで指定する必要があります。

間違い例

Figma上: Size (大文字始まり)
コード: figma.enum('size', ...)

正しい例

// 第1引数はFigmaの表記と完全一致させる
size: figma.enum('Size', { 
  Small: 'sm',
  Large: 'lg'
})

Q5. コードが出力されないバリアントがある

現象

figma connect publish は成功したのに、Dev Modeで見ると特定のバリアントだけコードが出ない（あるいはデフォルトのコードが出る）。

原因と解決策

variant プロパティで指定した組み合わせが、Figma上に存在しません。

Figmaのコンポーネントセット内に実際に存在する組み合わせと、コードの定義を一致させる必要があります。

// NG例 - Figmaには「Secondary」の「Large」が存在しない場合、これ書いても無視されます
figma.connect(Button, url, {
  variant: { 
    Type: 'Secondary', 
    Size: 'Large' 
  },
  // ...
})

番外編：コードをきれいに書くためのTips

1. デフォルト値は `undefined` を活用する

ReactコンポーネントのデフォルトPropsと同じ値の場合、figma.enum のマッピングで undefined を返すと、最終的なコード出力をシンプルにできます。

これは、JSX（およびCode Connect）の仕様として、prop={undefined} が記述された場合、そのプロパティはレンダリング結果（出力コード）から省略されるためです。

// SegmentControl.figma.tsx の例
figma.connect(SegmentControl, '[https://www.figma.com/](https://www.figma.com/)...', {
  props: {
    variant: figma.enum('Color', {
      Default: undefined, // 1. ここで undefined を指定
      Simple: 'simple',
    }),
  },
  // 2. example関数には { variant: undefined } が渡される
  // 3. <SegmentControl variant={undefined} /> と評価される
  example: ({ variant }) => <SegmentControl variant={variant} />,
})

出力結果

Default選択時: <SegmentControl /> (variantプロパティ自体が省略される)
Simple選択時: <SegmentControl variant="simple" />

デフォルト値を明示的に variant="default" と書きたくない場合に有効なテクニックです。

2. URLを定数化する

一つのコンポーネント定義ファイル内で、URLを何度もコピペするのはミスの元です。定数化しておきましょう。

const BUTTON_URL = '[https://www.figma.com/design/xxx?node-id=123-456](https://www.figma.com/design/xxx?node-id=123-456)'

figma.connect(Button, BUTTON_URL, {
  variant: { Type: 'Primary' },
  // ...
})

figma.connect(Button, BUTTON_URL, {
  variant: { Type: 'Secondary' },
  // ...
})

Figmaのデザインを複製した場合、Code Connectの情報は引き継がれません。
https://www.figma.com/design/ の後のファイルID xxxを置き換え、再度 publish することで反映されます。

まとめ

Code Connectのエラー解決フローチャートです。

URLチェック：node-idは親フレーム（コンポーネントセット）を指しているか？
APIチェック：instance（◇アイコン）とchildren（レイヤー）を混同していないか？
名前チェック：Figmaのプロパティ名と一字一句（大文字小文字）合っているか？

これらを確認すれば、大半のエラーは解決できるはずです。
Code Connectを活用して、デザインとコードの乖離をなくしていきましょう！

参考リンク