Guinness Figma プラグイン — セットアップガイド

Summary

Guinness Figma プラグインは、現在の Figma ファイルを Guinness の組織とプロジェクトに接続します。パネルは変換の方向ごとにタブが分かれており、WF → デザイン、 デザイン → WF、コード → デザイン、コード → WF に加えて、アカウント情報と共通のワークスペースを扱う アカウント タブがあります。このガイドでは、開発版プラグインのビルドと読み込み、環境への接続、ワークスペース設定について説明します。

必要なもの

Figma デスクトップアプリと、開発用プラグインを読み込む権限
guinness-figma-plugin ソースリポジトリへのアクセス
Node.js と npm
対象の組織とプロジェクトにアクセスできる Guinness アカウント
自分の Figma パーソナルアクセストークン（サーバー側の生成が、自分が開けるファイルを読むために使用します）
選択した Guinness 環境へのネットワークアクセス
Code2Des では、署名付き画像を取得するための対象 S3 オリジンへのアクセス

Warning

ユーザーパスワードやアクセストークンなどの秘密情報を .env に記載しないでください。ユーザートークンはサインインフォームから取得します。.env に設定するのはビルド時のエンドポイント情報だけです。

依存関係をインストールする

プラグインリポジトリで実行します。

cd guinness-figma-plugin
npm install
cp .env.example .env

.env は Git の管理対象外です。他の変更を共有またはコミットする前に、未追跡であることを確認してください。

接続環境を設定する

.env に次の値を設定します。

変数	必須	用途
`VITE_BACKEND_BASE`	必須	デプロイステージを含むバックエンド URL。`/api/v1` と末尾の `/` は含めません。プラグイン UI に埋め込まれます。
`VITE_DEBUG_API_LOGGING`	任意	API 調査時は `true`、通常は `false` にします。
`WF2DES_BACKEND_DOMAIN`	必須	バックエンドのオリジンのみ。Figma のネットワーク許可リストに書き込まれます。
`WF2DES_S3_DOMAIN`	Code2Des で必須	署名付き画像 URL が使用する S3 のオリジンのみ。Figma のネットワーク許可リストに書き込まれます。

VITE_BACKEND_BASE には API Gateway のステージを含めますが、WF2DES_BACKEND_DOMAIN にはパスを含めません。現在の dev 環境の例は次のとおりです。

VITE_BACKEND_BASE=https://d5tms1w7bl.execute-api.ap-northeast-1.amazonaws.com/dev
VITE_DEBUG_API_LOGGING=false
WF2DES_BACKEND_DOMAIN=https://d5tms1w7bl.execute-api.ap-northeast-1.amazonaws.com
WF2DES_S3_DOMAIN=https://dev-guinness-backend.s3.ap-northeast-1.amazonaws.com

ビルド前に接続を確認します。

curl https://d5tms1w7bl.execute-api.ap-northeast-1.amazonaws.com/dev/api/v1/ping

期待するレスポンスは pong です。

プラグインをビルドする

完全なビルドを作成します。

npm run build

型チェック後、dist/plugin.js、dist/index.html、dist/manifest.json が生成されます。開発中に変更を監視する場合は、次を実行します。

npm run dev

環境設定や manifest の変更後は、改めてビルドしてプラグインを再読み込みしてください。

Important

環境変数はビルド時に埋め込まれます。.env を編集しても、すでにビルド済みのプラグインは更新されません。エンドポイント、ドメイン、ポート、デバッグ設定を変更した場合は、必ず npm run build を再実行してください。

Figma に読み込む

Figma デスクトップアプリでデザインファイルを開きます。
Plugins → Development → Import plugin from manifest… を選択します。
guinness-figma-plugin/dist/manifest.json を選択します。
Development プラグイン一覧から Guinness を実行します。

再ビルド後は既存のパネルを閉じて、開発版プラグインを再実行します。ネットワークドメインを変更した場合は manifest を再インポートしてください。古い設定が残る場合は、開発版プラグインの登録を削除して、生成された manifest をもう一度インポートします。

サインインしてワークスペースを選ぶ

サインインすると、サインインフォームに代わってタブが表示されます。すべてのタブが共通で使うワークスペースは アカウント タブで設定し、ヘッダーバーで確認します。

Guinness アカウントのメールアドレスとパスワードを入力し、Sign in を選択します。
アカウント タブを開きます。
Workspace → Organization に意図した組織が表示されることを確認します。組織はアカウントに割り当てられており、プラグイン内では変更できません。
生成レコードとインポート済みアセットを保存するプロジェクトを選択します。同じプロジェクトは、すべてのタブに表示されるヘッダーバーからも切り替えられます。
Figma ファイルの値を確認します。
Figma アクセス で Figma のパーソナルアクセストークンを貼り付け、トークンを保存 を選択します。

生成はサーバー側で、あなた自身の Figma トークンを使って元のフレームを読み取ります。そのため、自分が開けるファイルにのみアクセスできます。トークンは Figma の Settings → Security → Personal access tokens で作成します。保存されたトークンは書き込み専用で、プラグインは登録の有無と最終検証日時のみを表示し、値は表示しません。この項目はプロジェクトを選択するまで状態を確認できないため、手順 4 を先に完了してください。

組織内で公開された非公開プラグインでは、Figma ファイルキーが自動検出されます。ローカルでインポートした開発版プラグインでは figma.fileKey を取得できない場合があります。その場合は、 Figma ファイル URL に含まれるキーを Figma file に貼り付けます。

https://www.figma.com/design/<figma-file-key>/<file-name>
                             ^^^^^^^^^^^^^^^^

セッション、選択したプロジェクト、開いていたタブ、開発用のファイルキーは Figma client storage に保存され、次回起動時に復元されます。アカウントを変更する場合や共有端末ではサインアウトしてください。

パネルのタブ

変換の方向ごとにタブが分かれており、一度に開けるタブは 1 つです。

タブ	変換の内容	実行に必要なもの
WF → デザイン	ワイヤーフレームフレームから高精細デザインを生成します。	キャンバスで選択したワイヤーフレームフレーム 1 つ
デザイン → WF	デザインフレームからワイヤーフレームを生成します。	キャンバスで選択したデザインフレーム 1 つ
コード → デザイン	公開ページをキャプチャして、ネイティブデザインとして再構築します。	公開ページの URL、または選択中のプロジェクトの完了済みインポート
コード → WF	公開ページをキャプチャして、ワイヤーフレームとして再構築します。	選択中のプロジェクトの完了済みインポート
アカウント	変換ではありません。サインイン中のアカウント、表示言語、Figma アクセストークン、共通のワークスペースを扱います。	—

同じキャンバスに対して、逆の入力を求めるタブがあります。WF → デザイン はワイヤーフレームフレームを、デザイン → WF はデザインフレームを必要とします。フレームを選択して生成する前に、開いているタブを確認してください。

ログはアクティブなタブの下に表示され、タブを切り替えても内容が保持されるため、失敗した実行の記録を後から確認できます。

セットアップを確認する

次の状態になればセットアップは完了です。

WF → デザイン、デザイン → WF、コード → デザイン、コード → WF、アカウント のタブが表示される。
ヘッダーに意図したプロジェクトと、開いているファイルのキーが表示される。
アカウント の Workspace に、ローカルスモーク用ではなく意図した組織とプロジェクトが表示される。
アカウント に意図したサインイン中のメールアドレスが表示され、Figma アクセス がトークン登録済みと表示する。
ログに API またはネットワークドメインのエラーが表示されない。
コード → デザイン タブで完了済みインポートを表示するか、公開ページをインポートできる。
コード → デザイン の生成結果に、空のプレースホルダーではなく取得済み画像が表示される。

ページをインポートして生成する手順は、Code2Des — 使い方を参照してください。

トラブルシューティング

サインインが読み込み中のままになる VITE_BACKEND_BASE を確認します。古いトンネル用ポート、.env 内の意図しない改行、API Gateway ステージの欠落により、誤ったアドレスへのリクエストが待機することがあります。/api/v1/ping を確認し、.env を修正して、再ビルドと再読み込みを行います。

ローカルの組織が表示されたままになる 古いバンドルまたは保存済みのローカルセッションが使用されています。アカウント タブからサインアウトし、再ビルド後にパネルを閉じて、dist/manifest.json を再インポートします。

Invalid credentials と表示される メールアドレス全体と最新のパスワードを確認します。認証情報をコピーするときは email: や password: のラベルを含めないでください。パスワードを文書やチャットに貼り付けないでください。

利用できるプロジェクトがない アカウントから参照できるプロジェクトがありません。管理者にアクセス付与を依頼し、アカウント タブからサインアウトしてから再度サインインします。

Figma アクセスがトークン未登録と表示される、または生成が元のファイルを読み取れない サーバー側の生成はあなた自身の Figma トークンを使うため、トークンが未登録または失効しているとファイルを開けません。プロジェクトを選択してから、アカウント の Figma アクセス で有効なパーソナルアクセストークンを登録します。

画像が表示されない、または Figma がドメインをブロックする WF2DES_S3_DOMAIN が署名付き URL のオリジンと一致することを確認します。変更後は再ビルドして manifest を再インポートしてください。

環境設定を変えても反映されない dist/manifest.json の networkAccess.allowedDomains と、dist/index.html 内のステージ付きバックエンド URL を確認します。古い場合はプラグインを再度開く前にビルドし直してください。

セキュリティ上の注意

.env、パスワード、トークン、認証レスポンスをコミットしないでください。
サインアウトすると、Figma client storage に保存された Guinness セッションが削除されます。
Code2Des の署名付き画像 URL は一時的です。ドキュメントに貼り付けないでください。