bdsanxz/figma-access

Figma アクセス

あなたは1つのコマンドラインツールを通じて Figma を操作します。このツールは KDL を出力し、データファイルを .kdl として保存します（1ノード1行、ノードのプレーンフィールドは キー=値 形式）。そのため grep、awk、sed が直接使えます。例外は spec（1行1ノードのテキスト概要を出力）、daemon log（デーモンのログ行をそのまま出力）、render、screenshot、image-fills、compare（画像ファイルを保存し、stdout へのサマリーは引き続き KDL）です。アクセス方法は2つあります:

• REST (file、node、spec、render、image-fills、api): ユーザーのトークンを使って URL から任意のファイルを読み取ります。ファイルを開いておく必要はありません。読み取りはローカルにキャッシュされ、レート制限時にはリトライされます。
• プラグイン (exec、screenshot、selection、logs、changes、call): バックグラウンドデーモンが Figma Desktop で動作する Desktop Bridge プラグインと通信します。これがファイルを変更する唯一の方法です。主なツールは exec で、ファイル内で Figma プラグイン API の JavaScript を実行します。

references/tips.md には実際の実行から得られた教訓が状況別に保存されています。これらは指針でありルールではありません。該当する状況のセクションを読み、適宜適応させてください。

ルール

• トークンを決して表示しないこと。 トークンを出力、ログ、エコーしてはいけません。テストには figma-access api /v1/me を使用します。
• 何かを変更する前と後には必ず確認すること。 目に見える結果はすべて、それを生成したコードではなく画像で判断します。
• 値を推測せずに読み取ること。レンダリング結果が優先されます。 色、サイズ、間隔、フォント、テキストはファイルから取得し、画像から目視で判断してはいけません。ファイルのデータとレンダリング結果が異なる場合、ユーザーが見るのはレンダリング結果です。
• ユーザーが依頼したものだけを変更すること。 読み取りは常に問題ありません。リクエストに明示されていない限り、ユーザーの既存の作業を削除したり上書きしたりしないでください。
• タイムアウトは失敗ではありません。 Figma は実行中のスクリプトを停止できません。再実行する前に logs とファイルを確認してください。

ワークフロー

1. セットアップ

1. <skill> はこの SKILL.md のディレクトリです。ツールは bun <skill>/scripts/figma-access.js コマンド ... として実行します。このファイルでは figma-access コマンド ... と記載しています。Bun で動作するため、必ず bun で起動し、node では起動しないでください。また、自作の JavaScript や TypeScript ヘルパーも bun で実行してください。コマンドを短縮するには、各シェル呼び出しの最初にシェル関数を定義します（fa(){ bun <skill>/scripts/figma-access.js "$@"; }; fa ...）。変数は使用しないでください（zsh は変数を単語に分割しません）。URL とノード ID は必ず引用符で囲んでください。?、&、; はシェルで特殊な意味を持ちます。bun がない場合は、ユーザーに https://bun.sh からインストールするよう伝え、停止してください。
2. figma-access --help を1回、そして各コマンドを初めて使う前に figma-access <コマンド> --help を実行してください。終了コード: 0=正常、1=Figma がエラーを報告、2=引数エラー、3=デーモン・プラグイン・トークンが利用不可。「出力の読み方」については references/tips.md でフォーマットと検索方法を説明しています。
3. リクエストに応じてパスを選択します（references/tips.md の「パスの選択」を参照）: URL があり読み取り専用のジョブ → REST、ファイルへの変更が必要 → プラグイン。両方を併用することも可能です。

2a. REST 経由で接続

1. figma-access api /v1/me を実行します。「トークンがありません」と表示された場合は、ユーザーが設定した場所を見つけ、同じコマンド内で読み込みます（references/tips.md の「トークン」を参照）。どこにも設定されていない場合にのみ、ユーザーにトークン（Figma: 設定 > セキュリティ > パーソナルアクセストークン、ファイル内容の読み取り権限）を要求します。
2. figma-access file <URL> を実行してページとトップレベルのフレームを確認します。references/tips.md の「適切なノードの見つけ方」に従い、作業するノードを選択します。

2b. プラグイン経由で接続

1. figma-access status を実行します。必要に応じてデーモンを起動します。
   • ファイルが表示された場合: 次に進みます。
   • ファイルがない場合: figma-access files を実行し、プラグインを待機します。終了コード3で終了した場合は、figma-access setup を実行し、その steps を平易な言葉でユーザーに伝えます。出力されたマニフェストパスからプラグインを一度インポートし、ファイル内で プラグイン > 開発 > Figma Desktop Bridge を実行し、そのウィンドウを開いたままにするよう指示します。プラグインが動作していることをユーザーに確認してもらい、その後 figma-access files を再実行します。
2. 複数のファイルが接続されている場合: 以降のすべてのコマンドで --file <ファイルキー> を指定します。

3. デザインの理解

1. 質問に答える最小のビューを読み取ります。最初にアウトラインを確認し、作業する部分だけ詳細を確認します:
   • 構造: figma-access node <URL|キー> <ID> --outline 2（REST）、または references/plugin-api.md のページアウトラインレシピ（プラグイン）
   • コードに必要なすべての情報（表示ノードあたり1行）: figma-access spec <URL|キー> <ID> -o <ファイル>。大きなフレームの場合は、一度 node ... -o <ファイル> で保存し、以降の spec では --from <ファイル> を指定します（references/tips.md の「レート制限とキャッシュ」を参照）
   • ユーザーが「これ」や「選択中のもの」と呼ぶもの: figma-access selection
   • 見た目: figma-access render <キー> <ID>（REST、正確なサイズ）または figma-access screenshot <ID>（プラグイン）、その後画像を開きます。
2. node の reports（フォント、画像フィル、非表示レイヤーの削除数）を読みます。references/tips.md の「非表示レイヤー」「デザイン画像の読み方」も参照してください。
3. コンポーネント、バリアント、変数、スタイルについては、変更やコピーを行う前に実際の構造を読み取り、重複を作成せずに既存のものを再利用します。

4. 作業の実行

デザインをコードで実装する。 コードを書く前に、references/tips.md の「デザインからコードへ」を参照してください。最初のビルド後に残る違い（画像のトリミング、フォント、テキストのオフセット、ページ幅）のほとんどはそこでカバーされています。コードは、ユーザーまたはそのプロジェクトが指定する場所（ユーザーが指定したパス、またはプロジェクト独自の構造）に記述します。_swe/figma-access/ には、レンダリング、保存したノードファイル、スペック、スクリーンショット、スクリプトなどの作業成果物のみを保存します。

1. フレームをスケール1でレンダリングし参照画像とします。フレームが縦長の場合は分割して読み取ります。
2. フレームの spec をファイルに書き出し、--origin でページコンテンツが始まるコーナーを指定し、すべての値をそこから取得します。アイコンやマスク画像は、再構築せずにレンダリング画像を使用します。オートレイアウトフレームは、spec が出力する方向、ギャップ、パディング、サイズから構築し、格納されたボックスからは構築しません。グループやオートレイアウトなしのフレームの子は、そのボックスに配置します。すべてのノードを格納されたボックスに絶対配置しないでください（手動でもジェネレーターでも）。そのページは古いボックスをコピーするだけで、テキストが長くなると壊れ、ウィンドウに適応できません。LAYOUT DRIFT とマークされた部分はレンダリングと照合してください。
3. すべてのウェイトを含むフォントをリストアップします。公開されていないフォントファミリーのファイルをプロジェクト内で探し、まだ見つからないものやファイルから取得できないものについて、一度のメッセージでユーザーに尋ねます。それらが到着するまで、または尋ねられない場合は、代用フォントを使用しその旨を伝えます。
4. デバイスやブラウザのクロームは除外し、ページがウィンドウに適応するようにします。フレームの幅は描画された画面の幅であり、背景や区切り線はウィンドウ幅いっぱいに、コンテンツカラムは中央に配置します（ユーザーが固定幅を要求した場合を除く）。
5. セクションごとに構築し、その後 figma-access compare <参照画像.png> <ページ> --nodes <ノードファイル> --wide <px> でページを参照画像と比較します。このコマンドはページをキャプチャし、フレームのセクションごとに異なるピクセルとそれを説明するシフト、各テキストスタイルとノードの位置ずれ、欠落しているノードを出力し、差分画像を書き出し、より広いウィンドウでもチェックします。--nodes を指定すると、フレーム自身の子からセクションを取得し、フレームの影で広がった参照画像をクロップします。キャプチャと差分画像も確認し、各セクションが一致するまで繰り返します。ユーザーがピクセルパーフェクトや1:1の結果を求め、かつそのためのスキルがセッションにリストされている場合は、これらのレンダリングをデザイン画像としてそのスキルを使用します。

ファイルを変更する。 プラグイン経由:

1. 変更をプラグイン API コードとして記述し、figma-access exec で実行します。references/plugin-api.md で API が強制する内容と配置を確認してください。長いコードは作業ファイル（例: _swe/figma-access/ の下）に保存し、exec -f で実行します。次に必要な ID は必ず return で返します。長時間の作業には --timeout 30s 以上を追加します。
2. 既製のプラグインルーチン（コンポーネントセット、リント・アクセシビリティ監査、画像フィル、注釈、FigJam・スライドヘルパー）で対応できるジョブには、figma-access call <メソッド> '<json>' を使用します。figma-access methods <フィルター> でパラメータ一覧を表示できます。
3. 毎回出力を確認します。ok #false の場合は原因を修正し、再試行前に部分的な作業を削除します。resultAnalysis の下に warning がある場合は ID と名前を確認します。スクリプト自身のトレースについては figma-access logs --since 2m を実行します。
4. 作成または変更したすべてのノードのスクリーンショットを撮り（小さいノードは --scale 2）、リクエストと照合します。修正して再スクリーンショットを撮ります。3回試してもまだ合わない場合は、残っているものとその理由をユーザーに伝えます。

references/tips.md の「プラグインでの作業」では、ここでよく起こる問題をカバーしています。

5. 報告

読み取った内容や変更した内容を、ノード名と ID、書き出したレンダリングやスクリーンショット・ファイルのパスとともにユーザーに伝えます。実行しなかったこと、行った仮定（代替フォント、スキップした非表示レイヤー、除外したクロームなど）、検証できなかったことを明記します。

トラブルシューティング

• 「レート制限を超過しました」(429): CLI はすでに待機しリトライしました。references/tips.md の「レート制限とキャッシュ」に従い、次の大きな読み取りまで1分待ちます。
• 終了コード3、ファイルが接続されていない: プラグインがそのファイルで実行されていないか、まだ検索中です（数秒ごとにチェックします）。ユーザーにプラグインを再実行するよう依頼します。figma-access daemon log で接続の発生を確認できます。
• 別のツールが同じプラグインを使用している（例: figma-console-mcp）: 両方とも並行して動作します。figma-access status でこのデーモンがファイルを保持しているか確認できます。
• スキル更新後に動作が古い: figma-access setup を再実行し、ユーザーに Figma でマニフェストを再インポートしてもらい、その後 figma-access daemon restart を実行します。
• 「プラグインが応答する前に切断されました」: ユーザーがプラグインまたはファイルを閉じたか、プラグインがリロードされました。変更を繰り返す前にファイルを確認してください。