公開2024.08.20更新2026.09.29 ツール

Figma Code Connectの使い方｜UIとCLIの始め方とDev Mode表示・CLI v2移行

Q: ネットの手順どおりにfigma.connect()で書いたのにエラーになるのはなぜですか？

2026年8月18日の CLI 2.0.0 で、 figma.connect() を使うフレームワーク別パーサー方式が migrate と unpublish 以外で使えなくなったためです。 npx figma connect migrate でテンプレートファイル（ .figma.ts ）へ変換し、 figma.config.json の include を .figma.ts だけに絞り（旧 .figma.tsx を外す）、 parser 設定も外してください。

Figma Code Connectの使い方｜UIとCLIの始め方とDev Mode表示・CLI v2移行

Figma Code Connect は、Figma のデザインコンポーネントと、リポジトリにある実装コンポーネントを対応づける機能です。CLI で対応づけておくと、Dev Mode で開発者が見るコードが「Figma が自動生成した汎用コード」から「自社のデザインシステムのコード」に変わります。UI と CLI のどちらで対応づけても、Figma MCP サーバー経由で AI エージェントに同じ対応づけが渡ります。

始め方は、Figma の画面上で対応づける Code Connect UI と、テンプレートファイルを書いて端末から公開する Code Connect CLI の2通りです。この記事では、両者の違いと選び方、それぞれの最小手順、2026年8月18日の CLI v2.0.0 で旧来のパーサー方式が止まった変更への対処までを扱います。CLI の実行結果は、2026年9月29日に CLI 2.0.1 をインストールして確認したものです。

まとめ：Figma Code Connectの使い方と要点

使えるのは Organization プランと Enterprise プランで、Full シートか Dev シートが必要です。Starter と Professional では使えません。
Code Connect UI は Figma 内で完結し、ライブラリのコンポーネントにファイルパスとコンポーネント名を登録します。ただし Dev Mode の Inspect パネルにコードスニペットは出ず、ファイル名とコンポーネント名の表示にとどまります。
Inspect パネルに自社コードのスニペットを出したいなら CLI を使います。.figma.ts のテンプレートファイルを書き、npx figma connect publish で公開します。
CLI 2.0.0（2026年8月18日）から、React 用などのフレームワーク別パーサーは migrate と unpublish 以外で使えません。figma.connect() で書いた旧来のファイルは figma connect migrate でテンプレートファイルへ移します。
UI と CLI のどちらで作った対応づけも Figma MCP サーバーに渡り、AI エージェントが生成するコードを自社コンポーネントに寄せられます。
「Figma コネクト」「connected projects」で探しているのが組織間のフォルダ共有なら、それは Code Connect ではなく「接続フォルダ（Connected folders）」という別機能です。

Figma Code Connectの仕組みとDev Modeでの表示

接続前後で変わるInspectパネルのコード

Dev Mode の Inspect パネルは、何も設定していなければ Figma がレイヤーから推測した CSS や SwiftUI などのコードを表示します。これは見た目を再現するためのコードで、社内のボタンコンポーネントを使う書き方にはなりません。

CLI で対応づけたコンポーネントを選ぶと、この自動生成コードの代わりに、テンプレートファイルで定義したスニペットが表示されます。Figma 側で「Size=Large」「Disabled=true」のようにプロパティを切り替えると、スニペット内の props もそれに合わせて変わります。開発者はデザイン上のバリアントを、自社コンポーネントの props に読み替える作業を省けます。

一方、Code Connect UI で対応づけた場合、Inspect パネルにスニペットは出ません。公式ドキュメントは「Components connected using Code Connect UI do not display code snippets in the Inspect panel」と明記しており、Inspect に表示されるのは登録したファイル名とコンポーネント名で、AI 生成スニペットのプレビューは Code Connect UI の画面で確認できます。UI は主に MCP サーバーへ文脈を渡すための経路だと考えると、両者の役割の違いが分かりやすくなります。

利用に必要なプランとシート

ヘルプセンターの可用性表示は「Available on the Organization and Enterprise plans」「Requires a Full or Dev seat」です。Dev Mode 自体は Professional でも使えますが、Code Connect はその上位の2プランに限られます。Collab シートや閲覧のみのユーザーは対象外です。

UI を使う場合は、公開済みのコンポーネントを含むライブラリファイルが必要です。CLI を使う場合は Node.js 18 以上と、Code Connect スコープを Write、File content スコープを Read にした個人アクセストークンを用意します。トークンの発行手順と CI 向けトークンの選び方はFigma Code Connect CLIの設定とGitHub連携手順｜アクセストークン発行からpublish自動化までで扱っています。

Code Connect UIとCLIの違いと選び方

公式の比較ページでは、両者はどちらも同じ MCP 基盤に対応づけを渡すものの、作業する場所と渡せる情報が違うと整理されています。

比較項目	Code Connect UI	Code Connect CLI
作業場所	Figma の Dev Mode 内	ローカルのリポジトリと端末
インストール	不要	npm で CLI を導入
Inspect のスニペット	表示されない	テンプレートの内容を表示
プロパティの対応づけ	未対応	対応
MCP に渡る情報	パス・名前・指示文・コード側の文脈	パス・名前・props・スニペット
主な操作者	デザイナー・開発者	開発者

UIとCLIを使い分ける判断基準

Dev Mode を見て実装する開発者に、自社コンポーネントの正しい書き方をそのまま見せたいなら CLI 一択です。UI ではスニペットが出ないため、この目的は満たせません。

反対に、目的が「Claude Code や Cursor などのエージェントに、どのコンポーネントを使うべきかを伝えること」で、props の細かい対応づけまでは要らないなら、UI から始めるのが早道です。インストールも npm のパッケージ管理も不要で、デザイナーがライブラリを整備する流れのまま登録できます。まず UI で主要コンポーネントを対応づけ、スニペットを出したいコンポーネントだけ CLI に移す、という段階的な導入もできます。なお、CLI で作った対応づけは UI にも表示されますが、編集は CLI からしかできません。

導入を見送るべきケース

Code Connect は「Figma のライブラリと、コードのコンポーネントライブラリが両方ある」ことを前提にした機能です。ライブラリとして公開したコンポーネントが無いファイルや、案件ごとに画面を描き起こして使い回すコンポーネントが無い体制では、対応づける相手がありません。その段階なら、先にデザインシステムとは？構成要素・作り方とデザインガイドラインとの違いを解説で整理している構成要素から揃える方が先です。Professional プランのまま使いたい場合も対象外なので、プラン変更の費用と釣り合うかを先に判断してください。

Code Connect UIの使い方：Figma上で対応づける手順

ライブラリファイルから対応づけ画面を開く手順

公開済みのデザインコンポーネントを含むライブラリファイルを開きます。
ツールバーで Dev Mode に切り替えます。
ファイル名の横のメニューから「Library」→「Connect components to code」を選びます。
ライブラリの公開済みコンポーネントが一覧で表示されるので、各行にコード側のファイルパス（例：src/components/Button.tsx）と、必要ならコンポーネント名（例：Button）を入力します。

作業中のフレームから始めることもできます。Dev Mode の Inspect パネルで「Connect components」を押すと、そのフレームに含まれる未接続のコンポーネントを対象に同じ画面が開きます。登録した対応づけは、その時点から MCP サーバーの文脈に使われます。

GitHubリポジトリ接続の条件と制約

GitHub 接続は任意です。つながなくてもパスと名前の手入力で対応づけられます。接続すると、入力欄でリポジトリ内のファイルパスとコンポーネント名が補完され、GitHub 上のコンポーネントを検索して選べるようになります。

接続操作ができるのは、そのファイルの所有者か組織の管理者だけです。設定アイコンから「Connect to GitHub」を選び、GitHub 側で管理者権限があれば「Install and Authorize」、無ければ「Request access」で管理者の承認を待ちます。制約は2つあります。自社ホストの GitHub Enterprise Server には対応していないことと、1つのライブラリファイルに接続できるリポジトリが1つだけであることです。実装が複数リポジトリに分かれている場合、補完が効くのは接続した1つの範囲に限られます。

複数フレームワークへの対応づけとMCP向けの指示文

1つのデザインコンポーネントに、React・SwiftUI・Jetpack Compose・Vue など複数の実装を対応づけられます。接続済みの行にカーソルを合わせると追加ボタンが出るので、フレームワークごとにファイルパスとコンポーネント名を登録します。CLI でも、フレームワークごとにテンプレートと設定ファイル（label を分ける）を用意すれば同じことはできますが、UI なら設定ファイルを増やさずに画面上で登録できます。

接続済みのコンポーネントには「Add instructions for MCP」から指示文を付けられます。「アイコンのみのボタンでは aria-label を必須にする」「variant は primary と secondary だけを使う」のように、props の使い方やアクセシビリティ上の決まりを書いておくと、MCP サーバーがその文面を AI エージェントに渡します。同じ画面でプロパティを切り替えながら AI 生成スニペットをプレビューできますが、公式ドキュメントは、プレビューは実際のリクエストとは別の文脈で生成されるため結果が多少異なりうると注記しています。

Code Connect CLIの使い方：テンプレートファイルで公開する手順

CLIのインストールとfigma.config.jsonの配置

CLI は npm で入れます。2026年9月29日時点の最新版は 2.0.1（2026年9月10日公開）です。

npm install --global @figma/code-connect@latest
figma --version
# 2.0.1

プロジェクトのルート（package.json と同じ階層）に figma.config.json を置きます。設定は必ず codeConnect キーの中に書きます。公式の移行ガイドにあるテスト用設定例はこのキーが無く、そのままでは Error parsing config file で止まります。label は Dev Mode で表示されるタブ名、language はシンタックスハイライトの言語です。

{
  "codeConnect": {
    "include": ["src/**/*.figma.ts"],
    "label": "React",
    "language": "jsx"
  }
}

TypeScript で書く場合は、tsconfig.json の compilerOptions.types に "@figma/code-connect/figma-types" を加えると、テンプレート内の API が補完と型チェックの対象になります。

テンプレートファイル（.figma.ts）の書き方

テンプレートファイルは、1つのデザインコンポーネントに1つ作り、実装コンポーネントの近くに置きます。Figma でコンポーネントを右クリックして「Copy link to selection」を選び、そのURLを先頭のコメントに書きます。

// url=https://www.figma.com/design/abc123XYZ/SDS?node-id=4185-3778
import figma from 'figma'

const instance = figma.selectedInstance
const label = instance.getString('Label')
const disabled = instance.getBoolean('Disabled')
const size = instance.getEnum('Size', {
  Large: 'large',
  Medium: 'medium',
  Small: 'small',
})

export default {
  example: figma.code`
    <Button size={${size}} disabled={${disabled}}>
      ${label}
    </Button>
  `,
  imports: ['import { Button } from "components/Button"'],
  id: 'button',
}

構成は3つです。先頭の // url= コメントが Figma 上のどのコンポーネントかを指し、figma.selectedInstance の getString・getBoolean・getEnum で Figma のプロパティを読み、export default の example が Inspect パネルに出るスニペットになります。getEnum の左辺は Figma 側のバリアント名、右辺はコードに入る値なので、表記が違っていてもここで吸収できます。この書き方は React 以外でも同じで、SwiftUI なら example に Swift のコードを書き、figma.config.json の label を "Swift"、language を "swift" にします。

テンプレートファイルを手で書く代わりに、Figma MCP サーバーにつないだエージェントで figma-code-connect スキルを使う方法もあります。コンポーネントのURLを渡すと、未接続のコンポーネントを特定し、プロパティ定義を読み、リポジトリ内の該当コンポーネントを探して .figma.ts を書き出します。スキルは IDE 向けの Figma プラグインに同梱されており、生成結果は出発点として確認してから publish します。

parseで確認してからpublishする流れ

公開前に parse で、設定とテンプレートが読めているかを確かめます。parse はトークン無しで動き、公開される内容を JSON で出力します。上のファイルで実行すると、次のように isParserless: true（テンプレートファイルとして扱われた印）と CLI の版が返りました。

$ npx figma connect parse
Config file found, parsing /path/to/project using specified include globs
/path/to/project/src/components/Button.figma.ts
Using label "React"
Using language "jsx"
[
  {
    "figmaNode": "https://www.figma.com/design/abc123XYZ/SDS?node-id=4185-3778",
    "templateData": { "nestable": true, "isParserless": true },
    "language": "jsx",
    "label": "React",
    "metadata": { "cliVersion": "2.0.1" }
  }
]

出力は主要な項目だけを抜粋し、パスは置き換えています。Figma 上の見え方を確かめる preview と、実際に公開する publish はトークンが必要です。未設定のまま preview を実行するとCouldn't find a Figma access token. Please provide one with --token <access_token> or set the FIGMA_ACCESS_TOKEN environment variable と表示されて止まります。環境変数 FIGMA_ACCESS_TOKEN を設定してから公開します。

export FIGMA_ACCESS_TOKEN=<個人アクセストークン>
npx figma connect publish --dry-run   # 公開せずに内容だけ確認
npx figma connect publish

公開に成功すると、コンポーネント名と Figma 上のノードへのURLが一覧で返ります。リンク先で Dev Mode に切り替え、Inspect パネルにスニペットが出ていれば完了です。取り消すときは npx figma connect unpublish --node=<ノードURL> --label=React を使います。--node を省くと、設定ファイルの対象になっている全コンポーネントの公開が取り消されるので注意してください。GitHub Actions での自動公開はCode Connect CLIの設定記事の手順を使ってください。

CLI v2で止まる旧パーサー方式と移行手順

v2.0.0で動かなくなるファイルとエラー表示

2024年から2025年にかけて書かれた Code Connect の解説記事の多くは、Button.figma.tsx の中で figma.connect(Button, url, { props, example }) を呼ぶ書き方を紹介しています。これはフレームワーク別パーサー（React・HTML・SwiftUI・Jetpack Compose）を使う方式です。

Figma は 2026年8月17日でこのパーサーの更新と保守を終え、翌18日の CLI 2.0.0 で、パーサー方式を使えるコマンドを migrate と unpublish の2つに絞りました。figma.config.json に "parser": "react" を書いた旧来のプロジェクトで CLI 2.0.1 の parse を実行すると、次の表示で終了コード1になります。publish --dry-run も同じ表示で止まります。

Framework-specific parsers are no longer supported in Code Connect CLI v2.

Run `figma connect migrate` to convert parser-based Code Connect to template files:
https://developers.figma.com/docs/code-connect/templates-migration-guide/

Alternatively, if you're not able to migrate right now, continue using Code Connect v1:
npm install --save-dev @figma/code-connect@1

If this project has already been migrated, remove the `parser` setting from figma.config.json or update its `include` patterns to match only template files.

CI で @latest を指定していた場合、コードを何も変えていないのに8月18日以降の実行から公開ジョブが失敗するようになります。原因がデザインシステム側に無いため気づきにくい変更です。

figma connect migrateでテンプレートファイルへ移す手順

移行は figma connect migrate で機械的に変換できます。旧来の設定ファイルがあるディレクトリで実行すると、.figma.tsx と同じ場所に .figma.ts が生成されます。

$ npx figma connect migrate
Found 1 component(s) to migrate
✓ Migrated to /path/to/project/legacy/Button.figma.ts

Migration complete: 1 migrated, 0 skipped

生成されたファイルは、// url= と // component=Button のコメント、figma.selectedInstance.getString("Label") によるプロパティ読み出し、figma.helpers.react.renderChildren() を使った example で構成されていました。主なオプションは次の4つです。

--delete：移行に成功した元ファイルを削除する
--javascript：.figma.ts でなく .figma.js で出力する
--include-props：React の .getProps() や .render() を使っている場合に __props メタデータを残す
--batch <mode>：大きなファイルをバッチテンプレート（.figma.batch.json と .figma.batch.ts）へ移す方式を選ぶ。既定の auto は定義10個以上のファイルで試み、all で全ファイル、none で無効

移行後は、figma.config.json から parser と、include の *.figma.tsx を外します。include が旧 .figma.tsx に当たったままだと、parser を消しても package.json から React パーサーが自動判定され、移行済みでも上のエラーが出続けます。SwiftUI の xcodeprojPath や React の importPaths などパーサー固有の設定も不要になります。すぐに移行できない場合は npm install --save-dev @figma/code-connect@1 で v1 に固定できますが、パーサーはもう更新されないため、固定は移行までのつなぎにとどめるべきです。

Figma MCPサーバーとCode Connectの関係

Code Connect は「この Figma コンポーネントは、コードではこのコンポーネントだ」という対応表で、Figma MCP サーバーはその対応表を含む Figma のデータを AI エージェントへ渡す経路です。対応づけ済みのコンポーネントを含むフレームを MCP サーバーに読ませると、コンテキストの中に CodeConnectSnippet という目印のコンポーネントが入り、現在のプロパティ値・import 文・スニペット・指示文がまとめて渡ります。

渡る中身は作り方で変わります。CLI で作った対応づけでは、テンプレートの example と imports がそのまま入ります。UI で作った対応づけでは、登録したパスと名前から import 文が自動生成され、スニペットはコンポーネント名と現在のプロパティから組み立てられます。公式ドキュメントは、UI の場合は既定では完全なコードスニペットを含まないとしており、その差を埋めるのが「Add instructions for MCP」の指示文です。

MCP サーバーには Code Connect 用のツールもあります。get_code_connect_map は選択中のインスタンスごとに、コード側のコンポーネント名・場所・スニペット・対応づけの出どころ（UI か CLI か）を返し、add_code_connect_map はエージェントから対応づけを追加します。Claude Code や Codex から Figma を扱う設定と料金はFigma MCPサーバーとは｜料金・レート制限・対応クライアント17種と使い方【2026年9月時点】、エージェントがキャンバスに書き込む側の機能はuse_figmaとは？Figma MCPでAIがキャンバスに書き込む仕組みと使い方・制限にまとめています。

名前が近いConnected folders（旧connected projects）との違い

「Figma コネクト」「figma connected projects」で検索している場合、探しているのは Code Connect ではなく、組織の外の相手とフォルダを共有する機能かもしれません。この機能は「connected projects」と呼ばれていましたが、Figma の「プロジェクト」が「フォルダ」へ呼び替えられるのに合わせて、現在は「Connected folders（接続フォルダ）」になっています。ヘルプセンターによると、呼び替えは2026年8月3日から順次展開されています。

Connected folders は、制作会社と発注元のように別々のチームや組織が、それぞれ自分のプランの有料シートのまま1つのフォルダで作業する仕組みです。両者とも有料プランであることが条件で、Education プランでは使えず、設定できるのは管理者だけです。コードとの対応づけとは関係が無いため、デザインとコードをつなぎたいなら Code Connect、社外の相手とファイルを共同編集したいなら Connected folders、と目的で切り分けてください。

「Figma のデザインからコードを書き出したい」という目的なら、Code Connect ではなく Figma Make や MCP サーバーを使う方法が近く、その比較はFigmaをReactに変換する4つの方法｜HTML書き出しの可否とLocofy・Figma Make・MCPの使い分けで扱っています。Code Connect は既にあるコンポーネントを指し示す仕組みで、新しいコードを生成する機能ではありません。

よくある質問

Figma Code Connectとは何ですか？

Figma のデザインコンポーネントと、リポジトリの実装コンポーネントを対応づける Figma の機能です。CLI で対応づけると Dev Mode の Inspect パネルに自社コードのスニペットが表示され、UI と CLI のどちらで対応づけても Figma MCP サーバー経由で AI エージェントに対応関係が渡ります。

無料プランやProfessionalプランでCode Connectは使えますか？

使えません。Code Connect は Organization プランと Enterprise プランが対象で、さらに Full シートか Dev シートが必要です。Dev Mode は Professional でも使えますが、Code Connect はその上位プランに限られます。

VueのプロジェクトでもCode Connectを使えますか？

使えます。Code Connect UI は Vue の実装へも対応づけられ、1つのデザインコンポーネントに React と Vue の両方を登録することもできます。CLI のテンプレートファイルはフレームワークに依存しない形式なので、example に Vue のテンプレート記法を書き、label を "Vue" にすれば Dev Mode のタブ名も Vue になります。

Claude CodeやCodexからCode Connectの対応づけを使えますか？

Figma MCP サーバーを Claude Code や Codex に接続すれば使えます。対応づけ済みのコンポーネントを含むフレームを読ませると、コンテキストに実装コンポーネントの import 文とスニペットが含まれ、get_code_connect_map で対応表を直接取得することもできます。

ネットの手順どおりにfigma.connect()で書いたのにエラーになるのはなぜですか？

2026年8月18日の CLI 2.0.0 で、figma.connect() を使うフレームワーク別パーサー方式が migrate と unpublish 以外で使えなくなったためです。npx figma connect migrate でテンプレートファイル（.figma.ts）へ変換し、figma.config.json の include を .figma.ts だけに絞り（旧 .figma.tsx を外す）、parser 設定も外してください。