cloning-websites-to-weaverse

Weaverse へのウェブサイトのクローン作成

概要

このリポジトリ固有のワークフローを使って、参照ウェブサイトを保守しやすい Weaverse ページに変換します。一度限りのスクリーンショットの再現ではなく、再利用可能なセクション、正確なセクションの対応付け、明確なスキーマ境界を重視してください。

ソースは Figma ファイルですか？ その場合は、代わりに figma-to-weaverse を使用してください。Firecrawl による抽出を Figma MCP に置き換え、Figma 固有の手順を追加します。以下のセクション対応付け、マニフェスト、プレビューに関するルールは引き続き適用されます。

優先順位： ビジュアルの競合がある場合、ブランドガイドラインはソースウェブサイトより優先されます。ページ構成、コンテンツの流れ、インタラクションパターン、マーチャンダイジングのロジックには、ソースウェブサイトを反映します。

競合ルール

.guides/brand-guideline.md を信頼できる唯一の情報源とします。

公開中のサイトがブランドガイドラインと競合する場合は、必ずブランドガイドラインに従ってください。 これは、次の場合でも必須です。

• 関係者から make it look like the live site と言われた場合
• 経営陣がスクリーンショットを比較する場合
• 公開中のサイトのほうが新しい、または洗練されているように見える場合

次のルールに従ってください。

1. 競合しない部分では、ソースサイトに合わせます。
2. 競合する部分では、ブランドガイドラインに従います。
3. 判断に迷った場合は、ブランドガイドラインを優先します。

競合がある場合は、次のように明確に述べてください：I will match the live site where possible, but the brand guideline is the source of truth for conflicting decisions.

使用する場面

• マーケティングページ、ホームページ、ブランドハブをこのリポジトリにクローンする場合
• 公開中のページを app/sections/ と Weaverse で再構築する場合
• 既存のセクション、新しいセクション、app/styles/app.css、app/weaverse/schema.server.ts のどれを使うか決める場合
• 参照サイトのセクションシステムを、このリポジトリに登録されている Weaverse コンポーネントに対応付ける場合

小規模な文言のみの修正や、単独のバグ修正には使用しないでください。

必要な入力

• 移行する参照 URL または元のサイト
• .guides/brand-guideline.md
• sections.md
• app/weaverse/components.ts

必要な出力

• クローンプレビューのルート：クローンしたページ全体を React + Tailwind でレンダリングする単一の Hydrogen ルート（app/routes/clone-preview.$page.tsx）。セクションの分解を始める前に、ユーザーの承認を得る必要があります
• デザイン仕様：セクションの対応付け、インタラクションモデル、スキーマ境界、実装方針
• コンテンツマニフェスト：セクションごとの実際のアセット URL、テキストコンテンツ、リンク先、Shopify の参照情報、メディアタイプをまとめた表。すべて Firecrawl のスクレイピング結果を情報源とします

クローンプレビューのルートは検証のチェックポイントです。デザイン仕様とコンテンツマニフェストを合わせたものが、generating-weaverse-project-json への完全な引き継ぎ資料になります。

信頼できる情報源

必要な情報	情報源
色、書体、ロゴ、形状の表現、法的ルール	.guides/brand-guideline.md
セクションの順序、コンテンツの階層、CTA の流れ、マーチャンダイジング	クロールした参照ウェブサイト
既存の再利用可能なセクションとの対応と子ブロックの制約	sections.md
現在利用可能な Weaverse コンポーネントのレジストリ	app/weaverse/components.ts
共有トークンと複数セクションで繰り返し使われるスタイル	app/styles/app.css
サイト全体で編集可能なコントロール	app/weaverse/schema.server.ts
セクション固有のコンテンツとコントロール	app/sections/* 内のセクション schema

ワークフロー

1. まず .guides/brand-guideline.md を読んでください。

2. セクションのマッチングを行う前に、sections.md が存在し、信頼できることを確認してください。

3. Firecrawl を使い、Markdown と HTML の両方の形式を1回の呼び出しで指定して、元ページをスクレイピングしてください。

   firecrawl scrape "<url>" --format markdown,html -o .firecrawl/<site>-<page>.json
   

   これにより、コンテンツ抽出用の整形済み Markdown と、レイアウトやメディアの分析用の生 HTML の両方が、1回のリクエストで返されます。JavaScript によってコンテンツがレンダリングされるページでは、--wait-for 3000 を追加してください。

4. ページからセクションシステムに影響するサブページへのリンクがある場合は、それらもクロールしてください。

   firecrawl crawl "<url>" --include-paths <relevant-paths> --limit 10 --max-depth 1 --wait -o .firecrawl/<site>-crawl.json
   

5. Markdown と HTML の出力から、ソースページの特性を抽出してください。

   • デザイントークン：色、タイポグラフィ、間隔、角丸、コンテナ幅
   • ページ構造：セクションの順序、繰り返しパターン、CTA の流れ、マーチャンダイジングの流れ
   • コンテンツアセット：見出し、コピーのブロック、画像、動画、商品／コレクションのモジュール
   • メディアソース：HTML から <video>、<source>、<iframe>、<embed> の URL を抽出します（「Firecrawl Rules」→「Media source extraction」を参照）。

6. コンテンツマニフェストを作成してください（下記の「Content Manifest」セクションを参照）。これは必須の成果物です。これがないとデザイン仕様は未完成です。

7. クローンプレビューのルートを生成してください（下記の「Clone Preview Route」セクションを参照）。スクレイピングしたページを、app/routes/clone-preview.$page.tsx に単一の Hydrogen ルートとして変換し、ページ全体を React + Tailwind でレンダリングしてください。これは、すべてのビジュアルブロックをインラインでレンダリングする単一ファイルとし、別のコンポーネントファイルは作成しません。デスクトップとモバイルに対応したレスポンシブスタイルを含めてください。このルートでは、リポジトリの Tailwind 設定を使用し、元ページのデザインと視覚的に忠実に再現する必要があります。元ページのスタイルとブランドガイドラインが競合する場合は、ブランドガイドラインのトークンを適用してください。セクション分解の境界として使用するため、各ビジュアルブロックの区切りを、明確なコメント付きのセクションマーカー（例：{/* === HERO === */}、{/* === PRODUCT GRID === */}）で示してください。

8. ユーザー承認のチェックポイント — ここで作業を止めて待ちます。 ユーザーに以下を提示してください。

   • プレビュー URL（例：http://localhost:3456/clone-preview/<page-slug>）
   • クローンがカバーする内容の概要（セクション数、主要なビジュアルブロック、判明している不足点、適用したブランドガイドラインの上書き内容）
   • 次の指示を明示します。「上記の URL でクローンプレビューを確認してください。ソースページと一致していることを確認できたら、「approved」または「proceed to sections」と返信して続行してください。問題がある場合は、修正が必要な点を説明してください。」

   ユーザーが明示的に承認するまで、ステップ9には進まないでください。

   ユーザーから変更の依頼があった場合：

   • プレビュールートを更新します
   • URL を再提示して、承認を求めます
   • 承認されるまで繰り返します

9. ソースページをセクション単位のブロックに分割します。各ブロックについて、以下を分類します。

   • 主なメディアタイプ：static-image、video、animation、product-media、collection-image、external-embed。
   • 構成：テキストとメディアの関係 — background-overlay（全面メディアの上にテキストを配置）、side-by-side（列でテキストの横にメディアを配置）、stacked（メディアの上または下にテキストを配置）、card-grid（画像とテキストを含むカードの繰り返し）、card-slider（カルーセルで一度に1枚のカードを表示）。
   • レイアウト方式：single-full-bleed、split-columns、grid、slider/carousel、overflow-rail、flex-wrap、marquee/ticker。
   • インタラクション：static、autoplay-carousel、snap-scroll、arrow-navigation、fade-transition、auto-scroll-marquee。 これらの分類は生のHTML出力に基づきます。スライダーコンポーネント（Swiper、Flickity、Slick、カスタムの<slider-component>、data-slider）、グリッドクラス、フレックスパターン、<video>要素、絶対位置指定されたテキストオーバーレイを探します。

10. 各ブロックを、sections.mdのレイアウト照合の優先順位に従って比較します。

11. まず構成で照合します（オーバーレイ、横並び、縦積み、カードグリッド、カードスライダー）。

12. 次にレイアウト方式で照合します（全面表示、スライダー、グリッド、レール、分割）。

13. その次にインタラクションで照合します（静的、カルーセル、スクロール）。

14. 最後にコンテンツモデルで照合します（商品、コレクション、手動コンテンツ）。 そのうえで、次のように分類します。 - REUSE_EXISTING - ADAPT_EXISTING - CREATE_NEW_REUSABLE_SECTION ソースブロックの構成、レイアウト方式、またはメディアタイプが候補セクションと一致しない場合は、別のセクションを選ぶか、適応が必要であることを明記して、その不一致を解消する必要があります。より適したセクションがないか、セクションのレジストリ全体を検索する前に、レイアウトの不一致を「トレードオフ」として受け入れてはなりません。 詳細な構造検証（REUSE または ADAPT に分類するたびに必須）： ブロックを分類した後、候補セクションのソースコード（app/sections/<section>/index.tsx とその子ファイル）を読み、スキーマ設定で元ブロックが求める視覚的な出力を正確に実現できることを確認します。以下を確認してください。 - アスペクト比の列挙値 — スキーマに元ブロックで使われている比率（例：9:16、3:2）が含まれているか、または比率がハードコードされているか - レスポンシブ画像のサポート — セクションがモバイル用とデスクトップ用の個別画像に対応しているか、単一の画像フィールドしかないか - 分割比率 — 画像とテキストの比率を元ブロックに合わせられるか（例：75/25）、または最大幅がそれより小さく制限されているか - 子ブロックの種類 — セクションが元ブロックに必要な子ブロック（例：ボタン、バッジ、カウントダウンタイマー）を受け入れるか - アニメーション／インタラクション機能 — セクションが元ブロックで使われているマーキー、視差効果、トランジション効果に対応しているか - テキストの可読性を高める機能 — 画像上にテキストを配置するレイアウトで、背景グラデーション、オーバーレイ、テキストシャドウに対応しているか スキーマ機能がひとつでも不足している場合は、分類を REUSE_EXISTING から ADAPT_EXISTING に変更し、具体的な不足点を記録してください。複数の機能が不足している場合は、代わりに CREATE_NEW_REUSABLE_SECTION を検討してください。

15. 現在のセクションシステムでは、ぎこちない妥協をせずに対象の構造やデータモデルをサポートできない場合に限り、新しいセクションを作成します。

16. 明確に分離されたスキーマを使って実装します。

    • グローバル共有トークン → app/styles/app.css
    • サイト全体で編集可能なコントロール → app/weaverse/schema.server.ts
    • セクション固有のコンテンツとコントロール → セクションの schema

17. 新しいセクションはすべて app/weaverse/components.ts に登録します。

18. ランディングページからサブページに拡張する前に、デスクトップとモバイルの両方で検証します。

19. Weaverse ページの検証と動作確認が完了したら、プレビュールートをクリーンアップします。 プレビュールートは一時的な成果物です。セクションの構築中は並べて参照できる状態にしておき、最終的に Weaverse でレンダリングされたページが承認済みプレビューと一致したら削除します。このルートでは通常、$page を介して複数のページを提供しています。完成したページの分岐とそのデータだけを削除し、ルートに残るページがなくなった場合に限り、app/routes/clone-preview.$page.tsx（および app/routes.ts の該当エントリー）を削除します。

コンテンツマニフェスト

コンテンツマニフェストは、このスキルと generating-weaverse-project-json をつなぐものです。これがないと、JSON ジェネレーターはコンテンツを推測し、プレースホルダーだらけで元のソースと一致しないエクスポートを生成します。

ソースページの DNA をクロールして抽出した後、セクションのマッチングを行う前に、セクションごとの具体的な表を作成します。マニフェストには、ソースページ上のすべての視覚的なブロックを含める必要があります。

必須列

列	説明
ブロック番号	ページ上の順番
ブロック名	短いラベル（例：「Hero」、「Netflix promo」、「Connect CTA」）
メディアの種類	static-image、video、animation、product-media、collection-image、external-embed のいずれか
画像／動画の URL	クロール結果から直接取得した、そのブロックの実際のアセット URL をすべて記載します。メイン画像、セカンダリ画像、ロゴのオーバーレイ、背景画像をすべて含めます。クロール結果に記載されている完全な CDN URL を使用します。
テキストコンテンツ	見出し、小見出し、本文、CTA ラベルなど、ソースにある正確な文言
リンク先	ブロックがリンクするすべての URL（内部パスまたは外部 URL）
Shopify 参照情報	ブロックが商品またはコレクションに基づく場合の商品ハンドル／ID、またはコレクションハンドル／ID
備考	外部埋め込み、外部リンク付きのパートナーロゴ、動画の自動再生など、特記事項

ルール

• 画像 URL は記憶や推測ではなく、Firecrawl のスクレイプ出力（Markdown 形式）から取得してください。Markdown 出力には <img> の src 属性と表示される画像 URL が含まれています。必ずその値をそのまま使用してください。
• video または external-embed ブロックの場合、画像／動画 URL 列には、HTML 形式の出力から抽出した実際の動画ソース URL（MP4、WebM、HLS、YouTube 埋め込みなど）を記入してください。ポスター画像やサムネイル画像は使用しないでください。サムネイルも役立つ場合（フォールバックなど）は、明確なラベル（Video (MP4): ...、Thumbnail: ... など）を付けて両方記載してください。
• ブロックに複数の画像が含まれる場合（ライフスタイルのヒーロー画像と商品画像を含む商品カードなど）は、ラベルを付けてすべて記載してください。
• クロール結果に利用可能な URL がない場合は、そのセルに MISSING — [describe what should be here] と記載してください。JSON 生成時に、プレースホルダーへ黙って置き換えるのではなく、不足として検出できるようにします。
• マニフェストは、このスキルで必須の成果物です。設計仕様（セクションの対応付け、スキーマの境界、インタラクションモデル）とコンテンツマニフェストを合わせて、generating-weaverse-project-json への完全な引き継ぎ資料となります。
• 同じ概念（例：「Connect」）がページ内の複数箇所に異なるビジュアル表現で登場する場合、それぞれの出現箇所をマニフェストの別々の行と、対応するマッピング内の別々のセクションブロックとして記載してください。

保存場所

コンテンツマニフェストは設計仕様ファイル（例：design.md）内のセクションとして追加するか、同じ仕様フォルダー内に別ファイル content-manifest.md として保存してください。

クローンプレビューのルート

クローンプレビューのルートは、スクレイピングからセクション分解へ進む間の検証チェックポイントです。Weaverse のマッピング作業を始める前に、クローンの正確さをユーザーが視覚的に確認できます。

概要

app/routes/clone-preview.$page.tsx にある単一の Hydrogen ルートファイルで、クローンしたページ全体を React + Tailwind としてレンダリングします。特徴は以下のとおりです。

• 単一ファイル — すべてのビジュアルブロックをインラインで記述し、コンポーネントファイルを分けません
• レスポンシブ — 元ページのブレークポイントに合わせた、デスクトップおよびモバイル向けのレイアウトです
• セクションマーク付き — 各ビジュアルブロックをコメントマーカーで区切り、後で分解できるようにします
• ブランド調整済み — 元ページと競合する部分にブランドガイドラインのトークンを適用します（色、フォント、ロゴの使用方法）
• 一時的 — セクション構築中の参照用に保持し、Weaverse ページの検証後に削除します

ルート構造

import type {MetaFunction} from '@remix-run/react';

export const meta: MetaFunction = () => {
  return [{title: 'Clone Preview — <page name>'}];
};

export default function ClonePreview() {
  return (
    <div className="clone-preview">
      {/* === HERO === */}
      <section className="relative w-full h-screen ...">
        {/* hero content */}
      </section>

      {/* === PRODUCT GRID === */}
      <section className="max-w-7xl mx-auto py-16 ...">
        {/* product grid content */}
      </section>

      {/* === NEWSLETTER CTA === */}
      <section className="bg-primary text-white py-12 ...">
        {/* CTA content */}
      </section>
    </div>
  );
}

ルール

• すべてのコンテンツはコンテンツマニフェストから取得してください。 ステップ 6 で記録したアセット URL、テキスト、リンクをそのまま使用します。プレースホルダー画像や lorem ipsum は使わないでください。このプレビューの目的は、見た目を忠実に再現することです。
• リポジトリの Tailwind 設定を使用してください。 プレビューでは、リポジトリで利用可能なものと同じ Tailwind クラスとカスタムテーマトークンを使用します。単発の CSS ファイルやインラインの <style> ブロックは追加しないでください。
• ブランドガイドラインの上書きを適用してください。 元サイトの色、タイポグラフィ、ロゴの扱いが .guides/brand-guideline.md と異なる場合は、プレビューには元サイトではなくブランドガイドラインに沿ったバージョンを反映してください。これにより、ユーザーが後で変更される内容を承認してしまうのを防ぎます。
• すべてのビジュアルブロックに印を付けてください。 {/* === BLOCK NAME === */} コメントで、各セクションサイズのブロックを区切ります。これらのマーカーは、ステップ 9（セクション分割）の境界として使われます。ブロック名は、コンテンツマニフェストの「Block name」列と一致させてください。
• 可能な場合はインタラクティブな動作を含めてください。 元サイトにカルーセルがある場合は、基本的な Swiper または scroll-snap 版を実装してください。動画が自動再生される場合は、autoplay を指定した <video> タグを含めてください。プレビューで操作性をピクセル単位まで完全に再現する必要はありませんが、ユーザーが動作を確認できるよう、主要な挙動を示してください。
• Weaverse コンポーネントをインポートしないでください。 このルートは Weaverse セクションシステムから独立しています。プレーンな React + Tailwind を使用します。Weaverse セクションは承認後に作成します。
• ルートパラメーターごとに 1 ページにしてください。 複数のページを複製する場合は、それぞれに独自の $page スラッグを割り当てます（例：/clone-preview/homepage、/clone-preview/about）。複数のページを 1 つのルートにまとめないでください。

承認チェックポイント

プレビュールートを生成したら、停止してユーザーの確認を待ってください。

1. プレビュー URL とアクセス方法をユーザーに伝えます
2. プレビューに含まれる内容を要約します：ビジュアルブロックの数、主要なセクション、既知の不足点、適用したブランドガイドラインの上書き
3. 次のように明示的に尋ねます：「クローンプレビューを確認してください。問題がなければ「approved」または「proceed to sections」と返信してください。修正が必要な場合は、問題の内容を説明してください。」
4. ユーザーが明示的に承認するまで、セクション分割（ステップ 9）に進まないでください
5. ユーザーから変更の依頼があった場合は、ルートを更新して、再度承認を求めてください

ライフサイクル

フェーズ	プレビュールートの状態
ステップ 1〜6（スクレイピング + マニフェスト）	まだ存在しません
ステップ 7（プレビュー生成）	app/routes/clone-preview.$page.tsx に作成されます
ステップ 8（承認チェックポイント）	ユーザーが確認し、修正を依頼できます
ステップ 9〜14（セクション分割 + 構築）	参照用として並べて保持されます
ステップ 15（クリーンアップ）	Weaverse ページの検証後に削除されます

Firecrawl のルール

• スクリーンショットや記憶に頼らず、元サイトの取得には Firecrawl の scrape を使用してください。
• 1 回の scrape 呼び出しで、markdown と HTML の両方の形式を必ずリクエストしてください（--format markdown,html）。 markdown はコンテンツ抽出に、HTML はレイアウトの分類とメディアソースの抽出に使います。
• ランディングページからリンクされている関連サブページには、--include-paths を指定した Firecrawl crawl を使い、関連パスに範囲を絞ってください。
• 繰り返し使用されるレイアウト、ナビゲーションパターン、CTA の配置、コンテンツ階層を記録してください。
• Firecrawl の出力は参照サイトの構造を把握するための情報源として扱い、ブランドトークンの情報源としては扱わないでください。
• 出力は .firecrawl/ ディレクトリに、内容がわかる名前で保存してください（例：.firecrawl/example-homepage.json）。

メディアソースの抽出

Markdown 出力では、<video>、<source>、<iframe>、<embed> 要素が除外されます。これらは Markdown では表示されませんが、重要なアセット URL を含んでいます。このため、両方の形式が必要です。

HTML 形式の出力から、次の要素を抽出します。

• <video> と <source src="..."> — MP4、WebM、HLS ストリームの URL
• <iframe src="..."> — YouTube、Vimeo、その他の埋め込み URL
• メディアコンテナにある data-src、data-video-url、その他の遅延読み込み属性

HTML 内で .mp4、.webm、.m3u8、youtube.com/embed、vimeo.com、player. などのパターンを検索し、Markdown 出力で見落とされた動画ソースを見つけます。

セクション単位のブロックに、HTML では動画または埋め込みがあるのに、Markdown 出力では画像（サムネイル／ポスター）のみがある場合、そのブロックの主なメディアタイプは static-image ではなく video または external-embed です。サムネイルではなく、実際の動画／埋め込み URL をコンテンツマニフェストに記録します。

レイアウト構造の抽出

HTML 形式の出力から、各セクションのレイアウト構造も抽出します。

• スライダー／カルーセルコンポーネント：Swiper、Flickity、Slick、またはカスタムスライダー要素（<slider-component>、data-slider、data-slider-fullwidth、data-dots、JSON 属性内の自動再生オプション）を確認します。
• グリッドパターン：CSS グリッドのクラス、列数の変数（--COLUMNS）、レスポンシブブレークポイントのクラスを確認します。
• フレックス／ブリックレイアウト：brick__section、幅分割クラス（brick__block--three-quarters）、順序を反転するクラスを確認します。
• オーバーレイと横並び：メディアの上に重なるテキストコンテナの絶対位置指定と、独立したグリッド／フレックス列を確認します。
• マーキー／ティッカー：<ticker-bar>、マーキーの自動再生属性、連続スクロールの動作を確認します。

この HTML 分析は必須です。Markdown 出力だけからレイアウトの動作を分類しないでください。スライダー、オーバーレイ、またはインタラクティブなコンポーネントを含むページでは、Markdown 出力だけでは決して不十分です。

sections.md のルール

sections.md は、このリポジトリにある既存の Weaverse セクションから最適なものを選ぶための移行ガイドです。

登録済みの Weaverse セクションシステムと子ブロックについて、次の項目を網羅する必要があります。

• 目的
• 視覚的な構造
• 最適な用途と不適切な用途
• 実際のスキーマに基づくオプション
• レイアウトとデータの制約

sections.md がない場合は、ソースセクションのマッピングを行う前に作成します。

sections.md が古い、または不完全な場合は、再利用の判断を行う前に、実際のレジストリファイルとスキーマファイルを参照して更新します。

現在のスタイルだけからセクションの機能を推測しないでください。実際のスキーマと構成上の制約を使用します。

移行分析モデル

app/skill.md の次の分析手順を使用します。

1. 原子的な分析とトークン化

• ソースサイトのデザイントークンとグローバルなレイアウト定数を抽出します。
• 移行の判断に重要なものだけを記録します。色の使用方法、タイポグラフィの挙動、余白のリズム、コンテナ幅、ボタンのスタイル、角丸のスタイルを記録します。

2. セマンティックなセクション分割

• ソースページを、論理的に再利用できるブロックに分割します。
• 各ブロックについて、レイアウト、コンポーネント、コンテンツタイプ、想定されるデータソースを特定します。
• 各ブロックの主要メディアタイプを static-image、video、animation、product-media、collection-image、external-embed のいずれかに分類します。この分類により、対応するセクションがブロックを変更なしでサポートできるかどうかが決まります。
• 各ブロックの構成を background-overlay、side-by-side、stacked、card-grid、card-slider のいずれかに分類します。HTMLを見て判断します。テキストがメディア上に絶対配置されたオーバーレイ内にあるのか、メディアの横にある独立したフレックス／グリッド列内にあるのか、メディアの上または下に積み重ねられているのかを確認します。
• 各ブロックのレイアウト機構を single-full-bleed、split-columns、grid、slider/carousel、overflow-rail、flex-wrap、marquee/ticker のいずれかに分類します。HTML内のスライダーコンポーネント、グリッドCSS、フレックスのパターン、スクロールコンテナを確認します。
• 各ブロックのインタラクションを static、autoplay-carousel、snap-scroll、arrow-navigation、fade-transition、auto-scroll-marquee のいずれかに分類します。自動再生属性、ナビゲーション矢印／ドット、scroll-snap CSSを確認します。
• 同じコンセプトがページ内に異なる視覚的処理で複数回登場する場合（例：グリッド内の「Connect」ハブカードと、後半にある全幅の「Connect」CTAバナー）、それぞれを別個のセクションブロックとして扱います。

3. インテリジェントなスキーママッチング

• 各ソースブロックを sections.md と照合します。
• sections.md で定義されたレイアウト照合の優先順位に従って照合します。
  1. 構成を最優先 — セクションの構成フィールドはブロックと一致していますか？background-overlay ブロックを side-by-side セクションに照合してはいけません。
  2. 次にレイアウト機構 — セクションは同じレイアウトタイプを使用していますか？slider/carousel ブロックを grid セクションに照合してはいけません。
  3. 次にインタラクション — セクションはそのインタラクションに対応していますか？autoplay-carousel ブロックには、静的なグリッドではなく、Swiperベースのセクションが必要です。
  4. 最後にコンテンツモデル — セクションはそのデータタイプ（商品、コレクション、手動）に対応していますか？
• 構造、コンテンツモデル、制約がすでに一致している場合は、再利用を優先します。
• セクションとの適合性は高いものの、スキーマやスタイルの拡張が必要な場合は、適応を選択します。
• 現在のシステムでは適切に対応できない場合に限り、新しいセクションを選択します。
• メディアタイプのゲート：ソースブロックの主要メディアタイプ（ステップ2で判定）が照合先のセクションでサポートされていない場合、その不一致を許容せず、次の手順に進みます。
  1. sections.md と app/weaverse/components.ts を検索し、そのブロックのメディアタイプに対応する別のセクションを探します（例：ブロックが video の場合、videoURL、video、react-player対応のあるセクションを探します）。
  2. 一致するセクションが見つかった場合は、そのセクションを使用します。
  3. メディアタイプに対応するセクションがない場合は、適応が必要であること、またはセクションの新規作成／拡張が必要な理由として明示します。
  4. レジストリに動画対応のセクションが存在する場合、動画を静止画像に暗黙的に置き換えてはいけません。
• レイアウトのゲート：ソースブロックの構成またはレイアウト機構が候補のセクションと一致しない場合、その不一致を許容してはいけません。レジストリを検索し、レイアウトの動作が一致するセクションを探します。例：
  • card-slider（ナビゲーション付きで一度に1項目を表示）は、product-spotlight-rail（グリッド）ではなく、slideshow に照合する必要があります。
  • background-overlay（全幅画像上にテキストを配置）は、image-with-text（横並び）ではなく、hero-image または promotion-grid に照合する必要があります。
  • stacked レイアウト（画像の下にテキストを中央揃えで配置）では、image-with-text（デスクトップでは横並び）ではなく、columns-with-images またはリッチテキストセクションが適する場合があります。

3b. 詳細な構造比較

スキーマの照合で候補セクションを特定したら、採用を決める前に、セクションの実際のソースコード（app/sections/<section>/index.tsx および子ファイル）を確認してください。以下の各項目を、元ブロックの要件と照らし合わせて確認します。

確認項目	確認内容
アスペクト比のサポート	スキーマにアスペクト比セレクターがあり、元ブロックで使われている比率が含まれていますか？多くのセクションでは、単一の比率（例：aspect-square）がハードコードされています。
メディアタイプの一致	画像専用のセクションを動画ブロックの代わりに使うことはできません。videoURL、<video>、またはプレーヤーコンポーネントをサポートしているか確認します。
レスポンシブな画像バリエーション	元ブロックで、モバイルとデスクトップ用に個別の<source>要素を持つ<picture>を使用している場合、単一のimageフィールドでは一致しません。imageMobile、imageDesktop、またはレスポンシブなブレークポイントのロジックを確認します。
分割比率	スキーマの幅の制約を確認します。元ブロックで画像とテキストを75/25に分割しているのに、セクションで画像幅が60%までに制限されている場合は、調整が必要です。
子ブロックの種類	セクションのchildTypesまたはinspector.childrenで、元ブロックが必要とするブロック（ボタン、バッジ、カウントダウンタイマー、評価の星など）が許可されていることを確認します。
アニメーション／インタラクション	静的なセクションでは、マーキーのスクロール、視差効果、自動切り替えトランジションを再現できません。アニメーション用のprops、Swiperの設定、またはCSSアニメーションのサポートを確認します。
テキストの読みやすさを高める機能	元ブロックで、グラデーションの背景やカラーオーバーレイの上にテキストを配置している場合、セクションはoverlayColor、overlayOpacity、または同等の機能をサポートする必要があります。オーバーレイのない単純な画像セクションは一致しません。

いずれかの項目を満たさない場合、そのセクションをREUSE_EXISTINGに分類することはできません。具体的な不足点を記録したうえでADAPT_EXISTINGに再分類するか、複数の項目を満たさない場合はCREATE_NEW_REUSABLE_SECTIONに分類してください。

4. コンポーネントの合成とデータ生成

• 再利用するセクションでは、ソースコンテンツを既存のWeaverseスキーマにマッピングします。
• 新しいセクションでは、ページ全体を単一の専用コンポーネントに複製するのではなく、再利用可能なセクションのコードとスキーマを作成します。
• コンテンツマニフェスト（ワークフロー内で作成）は、すべてのコンテンツフィールドのデータソースです。記憶に頼ってコンテンツを入力せず、マニフェストの正確なURL、テキスト、リンクを使用してください。

判断ルール

• 既存のパターンがあり、スタイル、コンテンツ、またはスキーマの調整だけで対応できる場合は、既存のセクションを再利用します。
• パターンが視覚的または構造的に異なり、今後も繰り返し使われる可能性が高い場合は、新しいセクションを作成します。
• スタイルをapp/styles/app.cssに配置するのは、変数、フォントフック、繰り返し使用する背景処理、再利用可能なユーティリティなど、共有プリミティブに限ります。
• 設定をapp/weaverse/schema.server.tsに配置するのは、ストアフロント全体で編集可能にする場合に限ります。
• ページ固有の余白、コピー、CTA、トグルは、該当セクションのスキーマ内に保持します。
• まずランディングページに取り組みます。サブページを複製する前に、基本となるセクションシステムを安定させてください。
• 可能な限り実際のサイトに合わせますが、ブランドに関する判断が競合する場合は、ブランドガイドラインを正とします。

リポジトリ内の関連箇所

• app/routes/clone-preview.$page.tsx（一時的 — プレビューのチェックポイント）
• app/sections/
• app/weaverse/components.ts
• app/styles/app.css
• app/weaverse/schema.server.ts
• sections.md

危険な兆候

• ライブサイトの内容が .guides/brand-guideline.md と矛盾しているのに、ライブサイトに従う
• ページ全体をひとつの巨大な専用セクションで構築する
• ページ固有のスタイルを app/styles/app.css にまとめて追加する
• セクション固有のコントロールを app/weaverse/schema.server.ts に入れる
• Firecrawl によるスクレイピングとマッピングを省略し、スクリーンショットだけを基に作業する
• sections.md を確認せず、どのセクションが最も近いかを推測する
• ランディングページの基盤が機能する前に、すべてのサブページに着手する
• スクリーンショットとの一致を、ブランドルールを上書きする許可とみなす
• コンテンツマニフェストを省略し、具体的なアセット URL を含まないデザイン仕様を引き渡す
• クロール結果に実際のアセット URL が含まれているのに、汎用のプレースホルダー画像を使う
• メディアタイプの不一致を明示せず、動画ブロックを画像専用セクションに割り当てる
• スライダー／カルーセルをグリッドセクションに割り当てる（例：全画面スライドショーに product-spotlight-rail を使用する）
• 全幅のオーバーレイヒーローを左右分割セクションに割り当てる（例：画像の上にテキストを重ねた全幅ヒーローに image-with-text を使用する）
• 縦積みレイアウトを左右並びのセクションに割り当てる（例：画像の下にテキストを中央配置するブロックに image-with-text を使用する）
• 元のページで別々だったセクションをひとつにまとめる（例：背景のみの動画ヒーローと独立したテキストブロックを、テキスト付きヒーローひとつにまとめる）
• 生の HTML の取得を省略し、レイアウトの分類に Markdown 形式のクロール結果だけを利用する
• セクションのスキーマのソースコードを読まずに、ブロックを REUSE_EXISTING に分類する — セクション名と sections.md の概要で分かるのは目的であり、すべての機能ではありません
• 画像専用セクションで動画背景を扱えると思い込む — videoURL またはプレーヤーコンポーネントのサポートを確認する
• 元ページのアニメーション要素を、見落としの指摘なしに静的セクションへ割り当てる — マーキー、視差効果、自動切り替えには、専用のコンポーネントサポートが必要です
• クローンのプレビュー用ルートを省略する — プレビューを生成してユーザーの承認を得る前に、セクションの分解へ進む
• ユーザーの明示的な確認なしに承認チェックポイントを通過する — エージェントが「妥当に見える」と判断しても、ユーザーが実際にレンダリングされたページを確認することの代わりにはなりません
• プレビュー用ルートでプレースホルダーコンテンツを使用する — プレビューには、lorem ipsum やストック画像ではなく、コンテンツマニフェストの実際のアセット URL を使う必要があります
• プレビューにセクションマーカーを付け忘れる — {/* === BLOCK NAME === */} コメントがないと、プレビューをセクション分解の参照として使えません
• プレビュー用ルートをリポジトリに残し続ける — これは一時的な成果物であり、Weaverse ページの検証後に削除する必要があります
• ページタイプが異なるのに、特定のページ専用セクションを割り当てる — 候補スキーマの enabledOn を確認する（例：collection-filters は COLLECTION ページでのみ実行され、コレクションルートのローダーを読み込みます）。CUSTOM ランディングページでは、独自のデータを読み込むセクションを使うか構築してください
• アプリ全体にフォーマッターを実行する — biome check --write app/ は無関係なファイルまで再フォーマットし、本来の差分を分かりにくくします。変更したファイルだけをフォーマットし、コミット前にフォーマッターだけによる不要な変更を元に戻してください
• 適応時にセクションの既存のデフォルト値を変更する — 新しい設定は現在のレンダリングをデフォルトにする必要があります。他のページは引き続き、以前のスキーマを前提としたデータを保持しています

合理化の確認

言い訳	実際のところ
「経営陣はスクリーンショットを比較します」	スクリーンショットの一致は、リポジトリのブランドルールより優先されません。レイアウトは参照元サイトに合わせ、トークンはブランドガイドラインに合わせます。
「公開中のサイトのほうがガイドラインより新しいです」	リポジトリのガイダンスが更新されない限り、.guides/brand-guideline.md が引き続き実装上の唯一の信頼できる情報源です。
「まず公開中のサイトの色をコピーして、あとで整えます」	これでは多くの場合、不適切なグローバル設定が残ります。まず適切なトークンを設定し、そのうえで各セクションのスタイルを調整します。
「UIを見れば、どのセクションに一致するか分かります」	見た目が似ているだけでは不十分です。sections.md と実際のスキーマ制約を確認してください。色の見え方だけでなく、構成、レイアウトの仕組み、インタラクションを確認してください。
「スクレイピングは不要で、スクリーンショットだけあれば十分です」	スクリーンショットの記憶だけでは、階層構造、繰り返し使われるモジュール、リンク先ページのパターンを把握できません。まず Firecrawl で参照元サイトをスクレイピングしてください。
「実際の画像はあとで入れます」	JSON ジェネレーターは、取得していないアセット URL を復元できません。今、スクレイピングの出力からコンテンツマニフェストを作成してください。
「このセクションに必要なのは画像だけで、動画はあればよい程度です」	参照元のブロックが動画なら、一致させるセクションは動画に対応している必要があります。対応できない場合は、不一致として明示してください。メディアの種類を黙って格下げしないでください。
「同じコンセプトなので、セクションは1つで十分です」	同じコンセプトがページ上で異なる視覚的な表現で使われている場合は、別々のセクションブロックが必要です。
「基本的にはグリッドで、スタイルが違うだけです」	矢印やドットで1つずつ項目を表示するスライダーは、「基本的にはグリッド」ではありません。レイアウトを分類する前に、HTMLにスライダーコンポーネントがないか確認してください。
「image-with-text は画像とテキストがあるものなら何にでも使えます」	image-with-text は、左右に分割して並べるレイアウト専用です。全幅のオーバーレイ、縦に積み重ねるレイアウト、カードグリッドには使えません。まず構成を一致させてください。
「参照元のセクションは隣り合っているので、統合できます」	参照元に別々の HTML セクション（例：背景動画と独立したリッチテキストブロック）が2つある場合は、Weaverse セクションも2つに分けてください。統合するとレイアウトの動作が変わります。
「セクション名が一致しているので、使えるはずです」	セクション名が示すのは用途であり、対応機能ではありません。縦横比、レスポンシブ画像、分割幅、子要素の種類、アニメーション対応など、視覚上の要件をすべて満たすか、スキーマのソースコードを読んで確認してください。
「セクションに画像フィールドがあるので、画像に対応しています」	画像フィールドが1つあるだけでは、レスポンシブ画像に対応しているとは限りません。参照元でレスポンシブな画像バリエーションが使われている場合は、モバイル用とデスクトップ用の画像フィールドが別々にあるか、<picture> 要素に対応しているかを確認してください。
「プレビューは十分似ているので、ユーザー承認は省略します」	承認のチェックポイントがあるのは、エージェントには人間のように視覚的な忠実度を判断できないためです。必ず作業を止め、明示的な確認を待ってください。
「セクションのマッピング後にプレビューを生成します」	プレビューはセクションの分解より前に行う必要があります。誤った前提に基づくセクションマッピングを確定する前に、スクレイピングのエラー、コンテンツの欠落、ブランドの不整合を見つけることが目的です。
「プレビューではプレースホルダーで問題ありません。実際の URL はあとで差し替えます」	プレビューは忠実度を確認するためのものです。プレースホルダーのコンテンツでは目的を果たせず、ユーザーは正確さを検証できません。コンテンツマニフェストにある実際の URL を使ってください。

例

ステークホルダーの要望：公開中のサイトのように見せてください。

適切な回答：可能な限り公開中のサイトに合わせますが、ブランドに関する判断が競合する場合は .guides/brand-guideline.md を信頼できる情報源とします。

よくある間違い

• Exact screenshot thinking → 構造や雰囲気を合わせつつ、実装は再利用可能な状態に保ちます。
• Global junk drawer → あるセクションが所有するものは、そのセクション内に置きます。
• Over-customizing old sections → 調整が難しくなったら、既存のセクションをカスタマイズしすぎず、新しいセクションを作成します。
• Skipping registration → 新しいセクションは app/weaverse/components.ts に追加する必要があります。
• Ignoring the registry → 新しいセクションを作成する前に、sections.md と app/weaverse/components.ts を確認します。
• Missing content manifest → セクションごとに、クロールで取得した実際のアセット URL、テキスト、リンクを記載した表がなければ、デザイン仕様は不完全です。これがないと、JSON ジェネレーターがプレースホルダーを埋め込みます。
• Media type blindness → 動画のヒーローを画像専用のセクションに割り当てたり、アニメーション付きブロックを静的なセクションに割り当てたりする場合は、その不一致を明示します。
• Concept merging → 同じコンセプトが視覚的に異なる形で使われている箇所を、1 つのセクションブロックにまとめます。
• Layout blindness → 構成（オーバーレイ、横並び、縦積み）、レイアウトの仕組み（スライダー、グリッド、全幅表示）、インタラクション（静的、カルーセル、スクロール）を確認せず、コンテンツタイプだけで照合します。これは、セクションが元のページとまったく異なる見た目で表示される最も一般的な原因です。
• Section merging → 元ページの別々のセクション（例：背景のみの動画と独立したテキストブロック）を 1 つの Weaverse セクションにまとめ、視覚的な階層を変えてしまいます。
• Skipping HTML analysis → Markdown のクロール結果だけからレイアウトを分類します。Markdown では、スライダーコンポーネント、グリッドクラス、オーバーレイの配置、インタラクティブ要素が失われます。レイアウトを正確に分類するには、生の HTML が必要です。
• Name-matching without schema verification → 「hero-image」という名前のセクションでも、あらゆるヒーローレイアウトを再現できるとは限りません。セクションのソースコードを読み、スキーマ設定（アスペクト比、レスポンシブ画像フィールド、オーバーレイオプション、子要素のタイプ）を確認してから、REUSE に分類します。
• Assuming aspect ratios are configurable → 多くのセクションではアスペクト比がハードコードされています（例：aspect-square）。そのセクションで元ページの比率を再現できると思い込まず、実際のスキーマの enum 値や CSS クラスを確認します。
• Ignoring responsive image requirements → 元ページがモバイル用とデスクトップ用の <source> 要素を分けた <picture> を使用している場合、単一の image フィールドを持つセクションは一致しません。セクションには imageMobile／imageDesktop フィールド、または同等の機能が必要です。
• Skipping the preview checkpoint → クローンのプレビュー用ルートは、セクションの分解を始める前にユーザーが問題を見つけられるように用意されています。これを省略すると、Weaverse のマッピング作業がかなり進んでからレイアウトの誤りに気づくことになります。
• Auto-approving the preview → エージェントは、自身の判断を承認として扱ってはいけません。ユーザーが明示的に「承認しました」「進めてください」などと回答した場合にのみ、セクションの分解に進みます。
• Preview without section markers → {/* === BLOCK NAME === */} コメントを忘れると、プレビューを分解ガイドとしても活用できません。必ず追加します。
• Zombie preview route → Weaverse ページの確認後に app/routes/clone-preview.$page.tsx を削除し忘れます。これは一時的な成果物であり、恒久的なルートではありません。