figma-to-weaverse

Figma to Weaverse

Figma のデザインを、保守しやすい Weaverse ページに変換します。これは Figma 入力アダプター です。cloning-websites-to-weaverse の兄弟スキルですが、ソースとしてライブ URL の代わりに Figma ファイルを使用します。どちらのアダプターも、後続の同じスキル generating-weaverse-project-json に引き継ぎます。

Figma file / frame ─→ figma-to-weaverse ─→ generating-weaverse-project-json ─→ import / content API
   (Figma MCP)        (tokens + manifest + preview)        (project JSON)

2 つのアダプターでは、後続のルールが共通です。セクションの照合、スキーマの詳細な検証、コンテンツマニフェスト、クローンプレビューのルート、ブランドガイドラインの競合ルールは、cloning-websites-to-weaverse と 同一 です。照合ロジックの詳細は、そのスキルを参照してください。このスキルで置き換えるのは 抽出レイヤー（Firecrawl の代わりに Figma MCP を使用）だけで、Figma 固有の注意点も追加します。

使用する場合

• figma.com の URL（ファイル、フレーム、選択範囲）がページやストアフロントのソースである場合
• 「このデザインを Weaverse で実装して」「Figma からホームページを作成して」
• 複数の Weaverse ページに対応する複数フレームのフロー

ライブウェブサイトのクローン作成（cloning-websites-to-weaverse を使用）や、小規模なコピーの編集には使用しないでください。

必要な入力

• node-id（ページ／フレーム）を含む Figma URL、または現在の選択範囲。ファイルのみの URL では不十分です。ノードへのリンクを依頼してください。
• .guides/brand-guideline.md
• sections.md
• app/weaverse/components.ts
• 対象のページタイプとルート（Preflight を参照）
• 納品の場合：Weaverse プロジェクト ID と WEAVERSE_API_KEY（weaverse-content-api を参照）

事前確認（抽出を始める前に）

以下を確認しないと、いずれも全面的なやり直しが必要になります。

1. ページタイプとルート。 デザインがホームページ（INDEX）、ランディングページ（CUSTOM、例：/disney）、または特定のハンドル向けのリソーステンプレート（COLLECTION／PRODUCT）のどれになるのかを確認してください。これによって使用できるセクション（enabledOn）とデータの読み込み方法が決まります。ナビゲーションのリンクから推測しないでください。
2. 正しいストアフロント。 .env の PUBLIC_STOREFRONT_ID が .shopify/project.json のストアフロントと一致している必要があります。.env が一致していないと、ローカルでは別のブランドの販売チャネルが表示され、公開済みのコレクションが見つからないように見えます。npx shopify hydrogen env pull で修正してください。
3. 正しいブランドガイドライン。 .guides/brand-guideline.md にこのブランドが記載されていることを確認してください（リポジトリは同系列の別ブランドからクローンされていることがよくあります）。一致しない場合は Figma のトークンに従い、その旨を仕様に記載したうえで、ガイドラインの差し替えをユーザーに依頼してください。
4. Weaverse プロジェクトの状態。 プロジェクトのページ（pages <projectId>）を読み込んでください。空の COLLECTION／PRODUCT テンプレートは、それらのルートでヘッダーとフッターのみを表示します。その旨を指摘してください。これは作成したページが原因ではありません。
5. 既存のメモ。 リポジトリ内の以前の .figma/*.md 仕様を読み込んでください。ヘッダー／フッター／メニューの作業やトークンの決定が、すでに記録されている場合があります。

必須の成果物

ウェブサイトのクローン作成スキルと同じ 3 つの成果物に加え、ライブページも必要です。

1. コンテンツマニフェスト — セクションごとの表。実際のアセット URL（Figma からのアセットエクスポートを使用し、後で Shopify CDN の URL に置き換えます）、テキスト、リンク、Shopify の参照、メディアタイプを記載します。
2. クローンプレビューのルート — app/routes/clone-preview.$page.tsx に $page 分岐を設け、セクションを明示し、ブランドに合わせて調整したデザイン全体を React + Tailwind で描画します。セクションに分解する前に、ユーザーの承認を得てください。
3. デザイン仕様 — セクションのマッピング、注釈テーブル、スキーマの境界、インタラクションモデル、トークンのマッピング。
4. ライブ Weaverse ページ — Content API 経由でプッシュし、デプロイ済みのストアフロントで検証します。ページ JSON は .clone/<page>/ に保持します。
5. ビジュアルチェックの合格 — .figma/<page>.visual.json と .figma/ref/<page>/ 内の Figma 参照スクリーンショットを用意し、最終的な scripts/visual_check.mjs のレポートで Result: PASS と表示される必要があります（例外がある場合は列挙します）。これがなければページは完成ではありません。

Figma MCP による抽出（MCP 優先）

Figma MCP ツールを使用します。ツールから返されるのは構造化されたデザインデータです。トークンやレイアウトについてはスクレイピングした HTML よりも正確ですが、実際のインタラクションについては情報が限られます（静的なデザインには実行時の動作がありません）。

get_design_context の前に figma-design-to-code を読み込み、use_figma による書き込み呼び出しの前に figma-use を読み込んでください。

1. ページフレームに対する get_design_context が主要な呼び出しです。 1 回の呼び出しで、参照コード、スクリーンショット、アセット URL、使用されているテキスト／カラーのスタイル、コンポーネントの説明が返されます。応答が途中で切れている場合は、何かを書き始める前に、保存された出力から省略された部分を読み取ってください。Code Connect について尋ねられた場合は、ユーザーにそのまま尋ね、回答に従ってください。
2. 注釈をすべて収集します。 デザイナーのメモは data-development-annotations（意味：H1/H2/H3、「見出しではなくリンクです」）および data-interaction-annotations（メニュー、リンク先、ホバー時の動作）として返されます。すべてを仕様書の注釈テーブルに抽出し、それぞれを要件に対応付けてください。長い応答では見落としやすいためです。Figma のコメントは MCP から読み取れません。必要であればユーザーに尋ねてください。
3. トークン。 ファイルで変数が使われている場合は get_variable_defs を使用します。それ以外の場合は、get_design_context の応答末尾にあるスタイル一覧を使用します。project.config.theme に対応付けるのはサイト全体に適用する値だけにし、ページ固有の色はセクション設定として扱います。
4. 構造。 get_metadata は位置関係の把握（ノードの選択、フレームの検索）にのみ使用します。セクションの境界は、デザインコンテキスト内の最上位フレームです。
5. インタラクションのヒント。 レイヤー名には意図が含まれています（例：Grows Upward — Demo (hover to test)、Carousel Demo、Sort Dropdown (Grows Downwards)）。これらを記録し、示されていない動きを創作しないでください。
6. アセット。 デザインコンテキストにはアセット URL（figma.com/api/mcp/asset/...）が記載されています。これらは約 7 日後に有効期限が切れます。早めにデータをダウンロードし、内容を確認してください（単色の SVG、装飾用マスク、反転／切り抜き表示を想定した画像の場合があります）。
7. 共通パーツ。 ヘッダー、ナビゲーション、メニューのドロップダウン、フッターは、通常すべてのフレームに含まれています。ページセクションではなく、レイアウト／テーマの作業（テーマ設定、Shopify メニュー、レイアウトコンポーネント）として扱ってください。
8. プレースホルダー。 デザイナーが灰色のボックス、$00.00 と表示されたサンプル商品カード、キャンバス外のラベルを残していることがあります。マニフェストでは MISSING／プレースホルダーとして記載し、プレースホルダーを再現するのではなく、ブロックを実データ（コレクションの商品、Instagram フィード）に対応付けてください。

プラグインによる代替手段

MCP がファイルにアクセスできない場合や、特定のアセットをエクスポートできない場合（例：フラット化されたグループ、特殊なエクスポート設定）は、Figma エージェントプラグインでエクスポートし、出力ファイルを読み取ってください。基本の手段は MCP とし、具体的な不足を補う場合に限ってプラグインを使用し、代替手段で取得したアセットをマニフェストに記録してください。

ワークフロー

1. 事前確認（上記）。.guides/brand-guideline.mdを読み、sections.mdが最新であることを確認します。
2. デザインを抽出（上記の手順）。仕様書とマニフェストを.figma/<brand>-<page>.mdに保存します（トークン表、注釈表、コンテンツマニフェスト、ギャップ）。ノード ID を確認できるうちに、すべてのブロックフレームの Figma スクリーンショットを.figma/ref/<page>/<block>.pngに保存します（get_screenshot → curl。URL は短時間で無効になります）。これらはビジュアルチェック用の参照画像です。
3. コンテンツマニフェストを作成します。複製スキルと同じ列とルールを使用します。
4. app/routes/clone-preview.$page.tsxに複製プレビューのルートを生成します。ページごとに$pageの分岐を1つ設け、React + Tailwind、実際の Figma アセット、{/* === BLOCK NAME === */}マーカーを使用します。ヘッダーとフッターは含めません。
5. ユーザー承認のチェックポイント — ここで停止して待ちます。 プレビュー URL（推測したポートではなく、npm run devが出力した開発サーバーのポート）、ブロック数、ブランド固有の上書き、ギャップを提示します。ユーザーが承認するまで調整を続けます。
6. 承認後すぐにアセットを Shopify に移動します。レスポンシブなバリエーション（デスクトップ／モバイル）をトリミングし、デザインに合わせて反転／回転してから、weaverse-content-api → uploadでアップロードします。返されたメディアオブジェクトは.clone/<page>/shopify-assets.jsonに保存します。Figma のアセット URL を本番環境に含めてはいけません。
7. 分解して照合します。各ブロック（メディアタイプ、構成、レイアウトの仕組み、インタラクション）を分類し、複製スキルの優先順位と詳細な構造検証に従って照合します。また、事前確認で把握したページタイプと各候補のenabledOnも確認します。
   • 監査を並行して進めます。候補セクションごとに読み取り専用の調査担当を1人割り当て、要件ごとの SUPPORTED/GAP と file:line を報告させます。
   • 次に、セクションごとに実装担当を1人割り当てます。全員が同じ契約に従います。すべての新しい設定は現在のレンダリングをデフォルトとし、担当範囲外のレジストリ／sections.md／共有ファイルは編集せず、ビルド／フォーマットの実行もしません。登録、ドキュメント、lint、ビルドはインテグレーターが担当します。
   • 同じヘッダーを複数のセクションに手作業で追加するより、小さな共有ブロック（例：見出し＋リンクのヘッダー）を優先します。
8. 統合します。新しいセクションを登録し、sections.mdを更新し、変更したファイルだけフォーマッターを実行して、型チェックを行い、変更前のエラー基準と比較したうえで、CI と同じ方法でビルドします。
9. generating-weaverse-project-jsonを使ってページ JSON を生成します（Shopify メディアオブジェクトを使い、デフォルト値は含めず、プリセットを明示的に記述）。検証も行います。
10. Content API で配信します（weaverse-content-api）。CUSTOM／template ページにはcreate-pageを使用します（INDEX はすでに存在します）。次に、ルートのmainを再リンクし、すべてのアイテムを作成する PATCH を1回実行します。サイト全体の値にはtheme-updateを使用し（古い値を先にバックアップ）、メニューには管理者プロキシ（menuUpdate）を使用します（古いメニューをバックアップ）。ページにまだデプロイされていないコードが必要な場合は、その直後にデプロイするか、それまでは公開ページが壊れた状態になることをユーザーに伝えます。
11. Playwright で実際のルートを検証し、PASS になるまで繰り返します。 .figma/<page>.visual.jsonを作成します（セクションごとにブロックを1つ記述し、[data-wv-id]セレクターと参照画像を指定します。データ駆動またはプレースホルダーブロックの場合に限り、mode: "structure"とnoteを使用します）。ストアフロントのリポジトリからnode <this skill>/scripts/visual_check.mjs .figma/<page>.visual.jsonを実行します。仕様の形式、セットアップ、修正手順についてはreferences/visual-check.mdを参照してください。
    • report.mdを読み、すべての❌について、ブロックのスクリーンショット、参照画像、.diff.pngを開き、原因を1つだけ修正します（Content API でセクション設定を変更するか、セクションのコードを変更）。--only <block>を付けて再実行します。デスクトップとモバイルの全体実行でResult: PASSが出るまで繰り返します。
    • 閾値を上げたり、実際のデザイン差を隠すためにブロックをstructureに切り替えたりして、合格扱いにしてはいけません。
    • ブロックが3回の反復後も改善しない場合、または手元にない判断やアセットが必要な場合は、差分画像を添えてユーザーにエスカレーションします。
    • このスクリプトでは、JS エラー、画像の読み込み失敗、オーバーフロー、H1 の数、セクションの順序、角丸要素のクリッピングを検査します。それでも、インタラクションは手動で確認します。ホバー効果、URL と結果数が変わるフィルター、並べ替え、さらに読み込む操作、リンク先を解決できるメニューを確認します。商品数はローダーの JSON ではなく、レンダリングされた DOM で数えます。
    • デプロイ後、同じ仕様をデプロイ済み URL に対して再実行します（--url https://<storefront>/<path>）。
12. 後片付けして引き渡します。 ページのプレビューブランチを削除し、ビジュアル仕様と参照画像を含めてコミットします（生成された.figma/visual/の出力は未追跡のまま残してもかまいません）。プッシュし、このストアフロントのデプロイワークフローを監視します（同じリポジトリ内の別ブランドのワークフローが、無関係な理由で失敗する場合があります）。最終的なビジュアルチェックの結果、受け入れた例外、Studio 側で引き続き必要な対応（ページ SEO、不足しているコレクション／リンク、未公開のリソース）を報告します。

Web サイトのクローン作成と Figma の固有の違い

項目	Web サイト（Firecrawl）	Figma（MCP）
デザイントークン	CSS／計算済みスタイルから推定	get_variable_defs で明示される — テーマに直接マッピング
セクション境界	HTML のセクションマーカー、スライダー／グリッドのクラス	get_metadata の最上位フレーム／オートレイアウトコンテナー
構成	HTML の配置から読み取る	オートレイアウトの方向／折り返し／間隔から読み取る
アセット	HTML 内の画像／動画 URL	download_assets でエクスポート。実際の動画 src はない
インタラクション	HTML 内の実際の実行時の動作	実行時には存在しない — フレーム名、プロトタイプのリンク、デザイナーの注記から推測する。デザインが示していないインタラクションを作り出さない
レスポンシブバリエーション	<picture>／ブレークポイントクラス	デザイナーが用意している場合はデスクトップ／モバイルの別々のフレーム、それ以外は 1 つのフレーム

要注意事項

• 承認チェックポイントを省略する — Web サイトのクローン作成と同じルールです。セクションを分解する前に、ユーザーがクローンプレビューを承認する必要があります。
• インタラクションを作り出す — 静的な Figma フレームには、プロトタイプや注記に記載がない限り、カルーセルの自動再生やスクロール動作はありません。複数のカードが表示されているだけで、そのフレームをスライダーに分類しないでください。プロトタイプのリンクかフレーム名で確認してください。
• Figma の変数を無視する — get_variable_defs は、得られるなかで最も明確なトークンの情報源です。変数があるのに色やサイズをハードコードすると、Figma の最大の利点を捨てることになります。
• アセット URL を推測する — 実際のアセットを download_assets でエクスポートしてください。エクスポートに失敗した場合は、代替のプレースホルダーを使わず、マニフェストに MISSING — [describe] と記載してください。
• フレームごとに巨大な独自セクションを 1 つ作る — 再利用可能なセクションに分解し、まずレジストリを再利用してください。
• マッチングルールを再導出する — セクションのマッチング優先順位と詳細なスキーマ検証は cloning-websites-to-weaverse に記載されています。それに従い、より緩いルールを独自に作らないでください。
• モバイル／デスクトップのフレームを 2 つのページとして扱う — これらは同じセクションのレスポンシブバリエーションです。別々のページではなく、imageMobile／imageDesktop またはブレークポイントロジックにマッピングしてください。
• プレビュー用のルートをリポジトリに残す — Weaverse のページを検証した後、削除してください。
• ページの種類を確認する前に構築する — COLLECTION テンプレートとして構築したページを CUSTOM ページとして作り直す必要がありました。また、コレクション専用のセクションはほかでは実行できないため、商品グリッドのセクションも変更する必要がありました。
• .env のストアフロントが誤った状態でデータをデバッグする — 「コレクションが見つかりません」は、ローカルトークンが別ブランドのチャネルに属しているだけかもしれません。公開の問題を疑う前に、事前確認項目 2 を確認してください。
• Figma のアセット URL を Weaverse に渡す — URL は数日で期限切れになり、一部の画像変換は URL をブロックします。先に Shopify にアップロードしてください。
• 注釈を省く — 見出しレベル、リンク先、メニュー、ホバー動作に関するデザイナーの注記は要件です。注釈の表を残し、最後に確認済みとしてチェックしてください。
• デザイナーのプレースホルダーを再現する — グレーのボックスやサンプルカードは、実データの代わりに置かれたものです。コンテンツではありません。
• 古い開発サーバーのまま成功を宣言する — PATCH の後は npm run dev を再起動してください。古いプロセスが、同じ ID で以前のアイテムデータを配信し続けることがあります。
• PASS のビジュアルチェックなしでページの完成を宣言する — スクリーンショットを目視しただけでは、チェックで no clipped rounded elements ❌ と報告されるタイルの角の切れを見逃しました。デスクトップとモバイルの両方で、チェックが PASS になるまで繰り返してください。
• ページを修正せずにチェックを緩める — threshold を上げたり、ブロックを削除したり、実際の差異をなくすために structure としてマークしたりしないでください。

関連スキル

• cloning-websites-to-weaverse — ウェブサイト入力アダプターです。このスキルが再利用するセクションのマッチング、マニフェスト、プレビューの共有ルールを管理します。
• generating-weaverse-project-json — 後続のスキルです。このスキルの仕様とマニフェスト、トークンテーブルをインポート可能な JSON に変換します。
• weaverse-content-api — インポート後、ライブプロジェクトにコンテンツをプッシュまたは更新します。
• figma-use / figma-generate-design — Figma MCP プラグインのスキルです。use_figma の書き込み呼び出しを行う前に、figma-use を読み込みます。