Figma Code Connect CLIの設定とGitHub連携手順｜アクセストークン発行からpublish自動化まで

Figma Code Connect は、Figma 上のコンポーネントと GitHub リポジトリにある実装コードを対応づけ、Dev Mode の Inspect パネルに自社のコードそのものを表示させる仕組みです。この記事では、CLI のインストールからアクセストークンの発行、figma.config.json の記述、GitHub Actions での自動公開までを、コマンドと設定ファイルの実物で追える形にまとめます。あわせて、2026年8月17日に区切りが来るフレームワーク別パーサーの保守終了と、テンプレートファイルへの移行手順も扱います。Code Connect そのものの位置づけや Dev Mode での見え方はFigma Code Connectの使い方とは？設定手順・対応フレームワーク・Dev Modeでの仕組みを解説で整理しているため、本記事は環境構築と運用に絞ります。

まとめ：Code Connect CLI導入とGitHub連携の要点

先に結論だけ押さえておきます。詰まりやすいのはトークンの種類と設定ファイルの階層で、この2点さえ外さなければ公開までは短時間で到達できます。

• 導入要件は Node.js 18 以上と、Organization または Enterprise プランの Design もしくは Dev Mode シートです。Professional プラン以下では利用できません。
• CLI は npm install --global @figma/code-connect@latest で入れます。2026年8月7日時点の最新版は 1.5.2 です。
• 個人アクセストークンには「Code Connect」を Write、「File content」を Read で付与します。有効期限は最長90日です。
• CI で使うなら、プランアクセストークンの中でも「Figma CLI」タブで発行したものを選びます。REST API タブのトークンは Code Connect の公開に必要なスコープを持ちません。
• figma.config.json は設定を codeConnect キーの中に入れます。この階層を省くと CLI 1.5.2 は解析エラーで停止します。
• GitHub Actions で figma connect publish を回す場合、公式ドキュメントのワークフロー例にはリポジトリを取得するステップが含まれていないため、そのままでは公開対象が見つかりません。
• 2026年8月17日以降、React・SwiftUI・Jetpack Compose などのフレームワーク別パーサーは更新もサポートも受けられなくなります。figma connect migrate でテンプレートファイルへ移しておきます。

以降の章では、この順に手順と根拠を追います。Code Connect そのものの位置づけや Dev Mode でスニペットがどう見えるかを先に確認したい場合は、Figma Code Connectの使い方とは？設定手順・対応フレームワーク・Dev Modeでの仕組みを解説から読み始めてください。

Code Connect CLIの導入要件とインストール

プラン条件とNode.jsのバージョン

Code Connect は Organization プランと Enterprise プランでのみ利用でき、さらに Design シートか Dev Mode シートのフル席が必要です。Professional プラン以下は対象外なので、CLI の導入に手を付ける前にプランと自分のシート種別を確認してください。ここを飛ばすと、環境構築を終えてから使えないと判明する手戻りになります。

実行環境は Node.js 18 以上が要件です。npm パッケージ @figma/code-connect の 1.5.2 も engines に node >=18 を宣言しています。Node.js 16 系が残っている CI イメージでは、CLI の起動そのものが失敗します。

グローバルインストールとnpx実行の使い分け

公式が案内する導入方法はグローバルインストールです。

npm install --global @figma/code-connect@latest

一方、ドキュメント中の実行例は一貫して npx figma connect ... の形をとっています。グローバルに入れていれば figma connect ... だけでも動きますが、CI ではバージョンを固定したいので、package.json の devDependencies に入れて npx 経由で呼ぶ方が事故が起きません。グローバル導入は手元の試行用、リポジトリへの依存追加は継続運用用、と分けて考えると整理できます。

CLI が提供するコマンドは 1.5.2 時点で次の6つです。

このうち migrate と preview は、後述するテンプレートファイルへの移行と、その結果の検証を担う中核です。手元の CLI で --help を叩いてこの2つが出てこなければバージョンが古いので、先に更新してください。

アクセストークンの発行とスコープ設定

個人アクセストークンの発行手順と必要スコープ

個人アクセストークン（PAT）は、Figma のファイルブラウザ左上のアカウントメニューから「Settings」を開き、「Security」タブの Personal access tokens セクションで「Generate new token」を押して作成します。モーダルで有効期限とスコープを指定し、生成後に一度だけ表示される値を控えます。再表示はできません。

Code Connect で必要なスコープは2つです。「Code Connect」を Write、「File content」を Read に設定します。片方だけでは公開時にコンポーネント情報の取得か書き込みのどちらかで失敗するため、両方を必ず指定してください。Security タブではトークン名にカーソルを合わせると付与済みスコープと最終使用日時を確認でき、身に覚えのない利用があればその場で失効させられます。失効は即時反映されます。

トークンは X-Figma-Token ヘッダーで REST API にも使えます。Figma の API 側でトークンやレート制限をどう扱うかはFigma APIの使い方｜レート制限・トークン・Variables APIのEnterprise条件で詳しく扱っています。

CI向けのプランアクセストークンと選択基準

PAT には運用上の弱点があります。発行した個人に紐づくため退職や異動で失効し、その人がアクセスできる範囲すべてに権限が及び、有効期限が最長90日です。90日ごとにローテーションが発生するパイプラインは現実的に破綻します。

そのため CI ではプランアクセストークン（PLANT）が推奨されています。組織管理者が https://www.figma.com/developers/tokens で発行し、プランに紐づくので個人の異動と無関係に動き続けます。有効期限は最長365日で、アクセス可能なリソースを許可リストで絞ることもできます。発行には管理者の多要素認証設定が前提となる点に注意してください（SSO ログインを必須化している組織は除きます）。

渡し方はどちらも同じで、--token オプションか環境変数 FIGMA_ACCESS_TOKEN です。PLANT へ切り替えてもパイプライン側の記述は変わりません。

REST APIタブのトークンでは公開できない制約

プランアクセストークンの発行画面には「REST API」「npm registry」「Figma CLI」の3タブがあり、既定では REST API タブが選ばれています。ここで発行したトークンを Code Connect に使うと公開に失敗します。REST API 用のプランアクセストークンは、file_code_connect:write スコープを必要とするエンドポイントを対象外としているためです。

Code Connect の公開には「Figma CLI」タブで発行したトークンを使います。こちらは Code Connect とコードベースのアップロードに必要なスコープが固定で付与された専用のトークンで、汎用の REST API トークンではありません。既定タブのまま発行して権限エラーに突き当たるのは、PLANT 導入時に最も踏みやすい落とし穴です。

figma.config.jsonの記述と設定項目

codeConnectキーの省略で起きる解析エラー

設定ファイルはプロジェクトのルート、つまり package.json や .xcodeproj と同じ階層に figma.config.json という名前で置きます。設定値は必ず codeConnect キーの下に入れます。

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

ここで一点、公式ドキュメント内に記述の揺れがあります。テンプレート移行ガイドの検証用サンプルは codeConnect キーを省いた平坦な形で書かれていますが、CLI 1.5.2 はこの形を受け付けません。実際に平坦な設定を置いて figma connect parse を実行すると、次のように停止します。

Error: Error parsing config file: /path/to/figma.config.json
    at parseOrDetermineConfig (.../dist/connect/project.js:440:15)

エラー文言が「解析できない」としか言わないため、JSON の構文ミスを疑って時間を溶かしがちです。設定を書いたのに CLI が読んでくれないときは、まず codeConnect の階層があるかを確認してください。

include・exclude・label・languageの指定

include と exclude は Code Connect ファイルを探す glob で、設定ファイルの位置からの相対パスで書きます。テンプレートファイルは .figma.ts（または .figma.js）の拡張子を使うため、include もそれに合わせます。

label は Dev Mode のスニペットに表示される見出し文字列で、既定はプロジェクト種別から推測されます。language はシンタックスハイライトの言語指定で、jsx・typescript・swift・kotlin・html・dart など20種類から選びます。両方を指定した場合、ハイライトは language、ラベル表示は label が使われます。

このほか、リポジトリの既定ブランチ名を自動検出できないときに指定する defaultBranch、対話セットアップで使う Figma ファイルを固定する interactiveSetupFigmaFileUrl、公開先ファイルを差し替える documentUrlSubstitutions があります。documentUrlSubstitutions は本番ライブラリと検証用ライブラリを切り替える用途で効きます。

複数フレームワークを1コンポーネントに並べる構成

同じ Figma コンポーネントに React 版と Web Components 版のスニペットを両方出したい場合は、フレームワークごとにテンプレートファイルを分け、先頭の // url= コメントに同じ URL を書きます。そのうえで設定ファイルもフレームワークごとに用意し、それぞれ固有の label と、そのフレームワークのファイルだけを拾う include を持たせます。分け方はディレクトリを推奨します。react-*.figma.ts のような接頭辞方式も動きますが、対応フレームワークが3つ以上に増えたときに glob が入り組み、どの設定ファイルがどのファイルを拾っているのかを追いづらくなります。公開時は --config で設定ファイルを切り替えます。

GitHub連携：Actionsでの自動公開とリポジトリ接続

mainマージ時にpublishするワークフロー

手元で公開できるようになったら、CI へ移します。Code Connect ファイルが変更されたときだけ動かすのが基本形です。

on:
  push:
    paths:
      - "src/components/**/*.figma.ts"
    branches:
      - main

jobs:
  code-connect:
    name: Code Connect
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx figma connect publish --exit-on-unreadable-files
        env:
          FIGMA_ACCESS_TOKEN: ${{ secrets.FIGMA_ACCESS_TOKEN }}

公式ドキュメントのワークフロー例には actions/checkout のステップがありません。GitHub Actions のランナーは空のワークスペースで起動するため、チェックアウトを入れないとリポジトリのファイルが1つも存在せず、公開対象ゼロで正常終了してしまいます。エラーにならないぶん気づきにくいので、コピーして使うなら必ず補ってください。

もう1点、公式例の paths はパーサー時代の拡張子 *.figma.tsx で書かれています。テンプレートファイルへ移行済みなら *.figma.ts に読み替えてください。ここがずれていると、変更してもワークフローが起動しません。

トークンはリポジトリの Settings から Secrets へ登録し、FIGMA_ACCESS_TOKEN として環境変数で渡します。ワークフローファイルに直書きしないのは当然として、前述のとおり CI ではプランアクセストークンを選ぶのが運用上の正解です。paths のフィルタも重要で、これを外すと Code Connect と無関係な PR すべてでジョブが走ります。

Code Connect UIからGitHubリポジトリを接続する手順

GitHub 連携にはもう1つ、Figma 側の Code Connect UI からリポジトリを接続する経路があります。CLI での公開とは目的が異なり、こちらは対応づけを作る作業そのものを支援するものです。

接続するとコンポーネントの対応づけ欄でリポジトリ内のファイルパスやコンポーネント名が補完されるようになります。さらに、対応づけ済みコンポーネントは Figma MCP サーバーへ実装コードへの参照を渡せるようになり、コンポーネントごとに「Add instructions for MCP」から独自の指示文を持たせられます。AI エージェントが生成するコードを自社の実装パターンへ寄せたいときに効く機能です。

手順は、ライブラリファイルで Code Connect UI を開き、設定アイコンから「Connect to GitHub」を選び、GitHub アカウントでログインしてアクセス範囲を指定する流れです。組織で管理者権限を持っていれば「Install and Authorize」で完了しますが、権限がない場合は「Request access」で管理者の承認待ちになります。操作できるのはファイル所有者か組織管理者に限られます。

GHES非対応と1ライブラリ1リポジトリの制約

この UI 連携には2つの制約があります。1つは GitHub Enterprise Server（自社ホスト版）が対象外であること。オンプレミスで GitHub を運用している組織はこの経路を使えないため、CLI と CI での公開に寄せる設計が必要です。

もう1つは、1つのライブラリファイルに接続できるリポジトリが1つだけであることです。デザインシステムのコンポーネント実装が複数リポジトリに分散している構成では、補完が効くのは接続した1リポジトリの範囲に限られます。モノレポにまとめられないなら、ライブラリファイル側を分けるか、UI 連携を諦めて CLI 運用に統一するかの判断になります。連携そのものはあくまで補助機能なので、後者を選んでも公開自体には支障ありません。

パーサー保守終了に向けたテンプレートファイル移行

2026年8月17日のパーサー保守終了と影響範囲

ここが現時点で最も重要な変更点です。Code Connect は当初、React・iOS・Android・Web Components といったフレームワーク別のパーサーを前提としていました。この方式は 2026年8月17日をもって更新とサポートの提供が終了し、以後はテンプレートファイルが唯一の保守対象になります。

旧方式は Code Connect ファイルを「実行せずに文字列として扱う」設計だったため、三項演算子や switch がそのまま出力に混ざり、文字列操作もできませんでした。テンプレートファイルは文字列を返す関数として実行されるので、条件分岐も文字列補間も普通の JavaScript として書けます。フレームワークに依存しなくなったのはこの設計変更の副産物です。

期限を過ぎても旧 CLI を固定していればパーサーは動き続けます。ただしセキュリティ修正や互換性対応が止まるため、実質的には移行前提で計画を立てるべきです。新規に書き始めるならテンプレートファイル一択と考えて構いません。テンプレートファイルは次のような形です。

// url=https://www.figma.com/design/abc123/DS?node-id=1-2
import figma from 'figma'

const label = figma.selectedInstance.getString('Label')

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

先頭のコメントで Figma のコンポーネントと結びつけ、figma.selectedInstance のメソッドでプロパティを読み、export default でスニペット・import 文・識別子を返します。プロパティ読み出しの主なメソッドは getString・getBoolean・getEnum・getInstanceSwap で、型を問わず生の値を取る getPropertyValue もあります。上のファイルは CLI 1.5.2 の figma connect parse を通過し、ラベル React・言語 jsx の JSON へ変換されます。

migrateコマンドとオプション

既存資産の移行には専用コマンドが用意されています。プロジェクト全体を解析して Code Connect オブジェクトを取り出し、テンプレートファイルとして保存する決定的な変換です。

npx figma connect migrate --javascript --delete

TypeScript を許可していない組織は --javascript を使います。--include-props が必要になるのは React の .getProps() や .render() 修飾子を使っている場合と、他のテンプレートから executeTemplate().metadata.__props を読んでいる場合に限られます。該当しなければ既定のまま削除させて構いません。

--batch は既定が auto で、Code Connect ドキュメントを10個以上含むファイルだけを一括変換の対象にします。すべてのソースファイルを一括で処理させたいなら all、1ファイルずつ確実に処理させたいなら none を指定します。大規模なデザインシステムでは変換の粒度が結果の追いやすさに直結するため、最初は none で数件試してから広げると差分を確認しやすくなります。

移行後に手を入れるべき箇所

変換結果はそのまま本番に出せる状態ではなく、出発点として扱うのが前提です。Figma 上の表示は変わりませんが、コードとしては冗長になります。

特に整理が必要なのはバリアント制限です。旧方式で同一 URL に対して複数の figma.connect を書き分けていたコンポーネントは、1ファイル内の if / else if / else 分岐へ変換されます。この分岐は getPropertyValue() による文字列比較で書かれているため、getBoolean() や getEnum() の型付きメソッドへ置き換えるとぐっと読みやすくなります。プロパティ値によって別コンポーネントを描画するケースは三項演算子で十分収まりますし、複数のバリアントを AND で連結した条件は getEnum() とマッピングオブジェクトへ畳めることが多いはずです。

移行時に自動挿入される figma.helpers も、出力される型が確定している必須プロパティなら外して問題ありません。放置しても動きますが、次に触る人が読む量が増えるだけです。

一時ラベルでの検証公開

移行結果を Figma 上で確かめるときは、既存の Code Connect を壊さないよう label を一時的な値にし、include で新しいファイルだけを拾う設定ファイルを別に用意します。

npx figma connect publish --config figma.test.config.json
npx figma connect unpublish --config figma.test.config.json

この方法なら本番ラベルの表示に触れずに検証でき、確認後は同じ設定ファイルで取り下げられます。移行が完了したら、パーサー時代の *.figma.tsx などを削除し、設定ファイルからも parser・importPaths・paths・imports・xcodeprojPath・sourcePackagesPath・importMapping といったパーサー固有の項目を消してください。

公開前の検証とエラー対処

preview・parse・dry-runの使い分け

公開して初めて崩れに気づく事故を避けるための手段が3つあります。役割が違うので、順に使うと無駄がありません。

figma connect preview は、Dev Mode に出る見た目そのものをローカルで描画します。TypeScript や JSX など Prettier が扱える言語なら構文検証まで走るため、壊れたスニペットを公開前に落とせます。--inspect はコンポーネントのプロパティとバリアントを一覧するだけで描画を行わず、--props Variant=Primary は特定の組み合わせ1つだけを描画します。全組み合わせの総当たりが --all です。

npx figma connect preview src/components/Button.figma.ts --inspect
npx figma connect preview src/components/Button.figma.ts --props Variant=Primary
npx figma connect preview src/components/Button.figma.ts --all --max-combinations 20

総当たりの件数は --max-combinations で絞れます。既定値も上限値も500件で、501以上を渡すとエラーで停止します。出力形式は --output で table（既定）か json を選べるため、CI で結果を機械処理するなら後者を指定してください。

ここで一点、注意が要ります。公式の CLI リファレンスには、重複する出力を1件に畳んで表示する --unique が掲載されています。しかし npm で配布されている 1.5.2 にこのオプションは実装されておらず、実行すると error: unknown option '--unique' で停止します。前述の figma.config.json の件とは逆に、ここではドキュメントが実装を先取りしています。リファレンスにあるフラグが動かないときは --help で実際の対応状況を確認するのが確実です。

figma connect parse は解析結果を JSON で吐きます。用途は設定の答え合わせです。include が意図したファイルを拾えているか、label と language が想定どおりかをここで確かめられます。--outFile でファイルへ落とせるので、差分を取って構成変更の影響を見ることもできます。

--dry-run は全サブコマンド共通のフラグで、publish と unpublish では実際の書き込みをせずに対象一覧を出します。ただし対象の検証で Figma API を参照するため、トークンは必要です。認証なしで動く確認手段ではない点に注意してください。

トークン未設定時のエラーと解消

最も頻繁に出るのがトークン関連のエラーです。環境変数もフラグも無い状態で公開しようとすると、設定の読み込み結果まで表示したうえで次のメッセージで停止します。

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"
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 を設定するか --token を付ければ解消します。逆に、このメッセージまで到達しているなら include の glob とテンプレートファイルの記述は正しく解釈されている、という切り分けにも使えます。

なお公開対象そのものの一覧は --dry-run を付けたときだけ出ます。そこに並ぶコンポーネント名は、テンプレートファイルの場合 undefined と表示されます。名前の欄がパーサー方式の解析結果に由来するためで、異常ではありません。

CIでexit-on-unreadable-filesを付ける理由

--exit-on-unreadable-files は、解析できない Code Connect ファイルが1つでもあれば異常終了させるフラグです。既定では読めないファイルを飛ばして処理を続けるため、テンプレートの書き間違いに気づかないまま「成功」で終わり、Dev Mode に古いスニペットが残り続けます。公式も CI での使用を推奨しており、パイプラインでは付けない理由がありません。あわせて --dry-run を PR 側のジョブで走らせておくと、マージ前に公開対象の増減を確認できます。

Figma MCPサーバーとの役割分担

Code ConnectとMCPが担う範囲の違い

AI エージェントで実装する流れが一般化したことで、Code Connect と Figma MCP サーバーの関係を整理しておく必要が出てきました。両者は競合せず、担当が違います。Code Connect は「この Figma コンポーネントは実装ではこのコードだ」という対応づけの定義そのもので、MCP サーバーはその定義を含む Figma のデータをエージェントへ渡す経路です。対応づけが無ければ、エージェントは自動生成された汎用コードしか受け取れません。

前述の GitHub リポジトリ接続を済ませておくと、MCP 経由で渡る情報に実装コードへの参照が加わります。MCP サーバー側の料金や対応クライアントはFigma MCPサーバーとは？料金・使い方・対応クライアントを徹底解説に、キャンバスへの書き込みまで踏み込んだ挙動はuse_figmaとは？Figma MCPでAIがキャンバスに書き込む仕組みと制限にまとめています。

figma-code-connectスキルでのテンプレート生成

テンプレートファイルの作成自体をエージェントに任せる経路も用意されています。Figma MCP サーバーに接続したエージェントで figma-code-connect スキルを使うと、Figma のコンポーネント URL を渡すだけで .figma.ts が生成されます。スキルは URL を解析し、まだ対応づけの無いコンポーネントを特定し、プロパティ定義を取得し、リポジトリ内の該当コンポーネントを探してマッピングまで書き込みます。

前提は4つあります。Figma MCP サーバーを設定したエージェント、スキル本体（IDE 向け Figma プラグインに同梱されています）、CLI と figma.config.json、そしてチームライブラリへ公開済みのコンポーネントです。最後の条件は見落としやすく、ライブラリ未公開のコンポーネントの URL を渡してもスキルは対象を特定できません。

ただし生成物はあくまで下書きです。Figma のプロパティとコード側のプロパティの対応が妥当かは人が確認すべきで、確認を飛ばすと誤った対応づけがそのまま Dev Mode に出ます。公開自体は手書きのファイルと同じく figma connect publish で行います。

よくある質問

Figma CLIとCode Connect CLIは別物ですか？

実体は同じです。npm パッケージ @figma/code-connect をインストールすると figma というコマンドが使えるようになり、その connect サブコマンド群が Code Connect の操作を担います。「Figma CLI」はこのコマンド全体の呼称で、プランアクセストークンの発行画面にも「Figma CLI」タブとして同じ名前で登場します。

個人アクセストークンの有効期限が切れたらどうなりますか？

公開が認証エラーで失敗するようになります。個人アクセストークンは最長90日なので、CI に組み込んでいる場合は90日ごとに差し替えが必要です。これを避けるために、組織管理者が発行する最長365日のプランアクセストークンへ切り替える方法が用意されています。トークンは生成時に一度しか表示されないため、更新のたびに Secrets 側も同時に差し替えてください。

グローバルインストールとnpxのどちらを使うべきですか？

手元で試す段階はグローバルインストールが手軽です。継続運用するリポジトリでは devDependencies に追加して npx 経由で呼ぶ方をおすすめします。CLI のバージョンがリポジトリに記録され、手元と CI でコマンドの挙動がずれません。migrate や preview のように後から追加されたコマンドがあるため、バージョン差は実害になります。

GitHub Actionsでプライベートリポジトリを扱うのに追加設定は必要ですか？

Figma 側の追加設定は不要です。必要なのは、リポジトリを取得する actions/checkout のステップと、Secrets に登録した FIGMA_ACCESS_TOKEN の2つだけです。CLI はローカルのファイルを読んで Figma へ送るだけなので、Figma からリポジトリを覗きに行くわけではありません。なお、Figma 側の Code Connect UI からリポジトリを接続する機能の方は GitHub Enterprise Server に対応していません。

SwiftUIやJetpack Composeでもテンプレートファイルへ移行できますか？

できます。テンプレートファイルはフレームワークに依存しない形式なので、React や Web Components と同じく figma connect migrate の対象です。移行後は設定ファイルから xcodeprojPath・sourcePackagesPath・importMapping といった SwiftUI 固有の項目を削除します。フレームワーク別パーサーは2026年8月17日以降更新されないため、iOS や Android のデザインシステムでも移行の判断は同じです。

関連記事

• Figma Code Connectの使い方とは？設定手順・対応フレームワーク・Dev Modeでの仕組みを解説
• Figma MCPサーバーとは？料金・使い方・対応クライアントを徹底解説
• Figma APIの使い方｜レート制限・トークン・Variables APIのEnterprise条件
• use_figmaとは？Figma MCPでAIがキャンバスに書き込む仕組みと制限