danielhall/agent-skills

ウェブサイト → Figmaデザインファイル

実行中のウェブアプリを、デザイナーが実際にリデザインできるFigmaファイルに変換します。実テキスト、実アイコン、ライト/ダークモード対応のカラー＆スペーシング変数、テキストスタイル、再利用可能なコンポーネント、そしてそれらのコンポーネントのインスタンスから構築された各ページで構成されます。スクリーンショットはあくまでも参照用であり、成果物ではありません。

このスキルは、Figmaプラグインのスキル群の上に位置します。use_figmaを呼び出す前に必ずfigma-useとfigma-generate-designを読み込み、コンポーネントや変数を作成する際はfigma-generate-libraryを読み込んでください。

使用するタイミング

• 「サイトをFigmaに取り込んでリデザインしたい」
• 「これらのページをFigmaで再現してほしい」/「このアプリをFigmaにプッシュして」
• この方法で構築されたFigmaファイルにモバイルフレームや新しいページを追加する場合

手順

1. 信頼できる情報源を読み取る

• 実行中のアプリとグローバルスタイルシートが、デザインドキュメントよりも優先されます。ドキュメントはリデザイン中に乖離することがあります。不一致を見つけた場合はその旨を伝えてください。
• 収集するもの: テーマトークン（ライト/ダーク）、フォントファミリーとウェイト、レイアウトグリッド（ガター、レール、カラム幅）、各ページセクションの背後にあるコンポーネントファイル。
• スタイルを書き込む前に、figma.listAvailableFontsAsync()でフォントがFigmaに存在するか確認してください。黙ってInterにフォールバックしないでください。

2. Playwrightで参照用スクリーンショットを撮影する（ページキャプチャは使わない）

scripts/ref-screenshots.mjs を各ターゲット幅（例：1440と390）で使用します。このスクリプトは reducedMotion: "reduce" を設定するため、スクロールリビールやエントランスアニメーションでコンテンツが隠れることがありません。

generate_figma_design のページキャプチャはこの用途には信頼性が低いです。ビュー内アニメーションの背後にあるコンテンツは空白でキャプチャされ、バックグラウンドブラウザタブで開かれたキャプチャは pending 状態のままになることがよくあります。どうしても使用する場合は、一度に1タブだけ開き、参照として使用したらすぐにキャプチャを削除してください。キャプチャスクリプトをアプリに注入した場合は、後で必ず削除してください。

3. コードベースから実データとアイコンをエクスポートする

使い捨ての tsx スクリプト（リポジトリの外に作成するか、使用後に削除）を作成し、アプリ独自のデータモジュールをインポートし、アイコンコンポーネントを react-dom/server の renderToStaticMarkup でSVG文字列にレンダリングします。その後:

• currentColor を実際の色に置き換え、すべてのSVGに明示的な width/height を設定します。アイコンライブラリは 1em を出力することが多く、Figmaではサイズ設定できません。
• パスデータに基づいてアイコンの重複を排除します。ブランドマップでは、多くの名前が1つのロゴにエイリアスされていることがよくあります。
• CMSクライアントを使用してCMSコンテンツ（タイトル、抜粋、カテゴリ）を取得し、再入力しないようにします。

4. 基盤を先に構築する

各呼び出しで作成されたすべてのIDを返します:

1. ページ: 基盤、コンポーネント、ブレークポイントごとに1ページ。
2. 変数コレクション: テーマカラー（ライト/ダークモード）、カテゴリまたはブランドカラー、レイアウトトークン（デスクトップ/モバイルモード）。明示的な scopes とWEBコードシンタックスを設定します。
3. すべてのタイプロールのテキストスタイル。さらに、ディスプレイサイズのモバイルバリアント。
4. 共有シャドウ用のエフェクトスタイル。

5. コンポーネントを最小単位から構築する

アイコン → プリミティブ（ボタン、リンク、タイル、バッジ、チップ） → 複合（ヘッダー、フッター、ヒーロー、カード）の順に作成します。TEXT、BOOLEAN、INSTANCE_SWAPのプロパティを公開し、インスタンスをデタッチせずにページを埋められるようにします。レスポンシブなパーツには、インスタンス上でサイズをオーバーライドする代わりに Breakpoint バリアントを用意します。各グループを一度スクリーンショットし、次のグループに進む前に問題を修正します。

6. インスタンスからページを組み立てる

• ページごとに1回の use_figma 呼び出し。固定のキャンバス位置に配置し、ページを並行して構築できるようにします。
• 絶対位置ではなく、オートレイアウトのパディング（例：レールとガター）でCSSグリッドをミラーリングします。
• 行内のカードの高さを明示的に均等にします。FigmaはCSSグリッドのように兄弟要素を自動的に引き伸ばしません。
• 各ページの総高さとスクリーンショットを参照画像と比較します。高さが数パーセント以内の差であれば、スペーシングは正しいと判断します。

7. コンポーネントをコードにリンクする

Code ConnectはOrganizationおよびEnterpriseプランでのみ機能します。最初に whoami で確認してください。他のプランの場合は、ソースパス、コンポーネント名、プロップマッピングを各コンポーネントの description に書き込み、documentationLinks にGitHub上のファイルを設定します。Devモードでは両方が表示されます。公開できないリポジトリに .figma.ts ファイルを追加しないでください。Code Connectパッケージがないと tsc が壊れます。

8. クリーンアップ

参照用キャプチャを削除し、注入したスクリプトがあれば削除し、起動した開発サーバーを停止し、git status がクリーンであることを確認します。

注意点

コンポーネントやページのスクリプトを作成する前に、references/plugin-api-pitfalls.md を読んでください。最も時間を費やす障害とその修正方法がリストされています。バウンドペイントの不透明度、resize() によるオートレイアウトサイズのロック、プロパティキーの再キー付け、クローンバリアントでの参照喪失、1回の呼び出しサイズ制限などです。

references/helpers.md には、すべてのページ構築スクリプトの先頭に貼り付ける価値のある小さなヘルパー関数があります。