はじめに
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を活用して、デザインとコードの乖離をなくしていきましょう！
参考リンク