awwwards-section-loop

Awwwards Section Loop — セクションごとに構築し、検証して、固定する

ページ全体を一度に構築すると、注意が8つのセクションに分散し、初期のミスが後続のすべてのセクションへ気づかないうちに波及し、フィードバックが届くのはすべてが完成した後になってしまいます。その時点では、ずれの原因となった判断をたどるには遅すぎます。セクションループは、この3つすべてを解決します。1つのセクションに集中し、次のセクションに進む前に各セクションを検証して固定し、ずれが始まった場所で検知します。

このループを実行するツールはすでに揃っています。このスキルは、それらを実行する順序と、ツールの出力だけでは判断できない点を示します。

プロファイルに関する注意： このスキルのツールは、analyze_page_structure、 capture_component、analyze_stack、capture_pose_3d、 analyze_scroll_map、analyze_hover_census、audit_url、analyze_bundle、 build_gsap_stub、および既存の build_project / verify_build です。以下の例では1.xの名前（デフォルトは full）を使用しています。AWWWARDS_MCP_PROFILE=v2 では、inspect_page {request:{kind:"structure", url}}、 capture_page {request:{kind:"component", url}}、 inspect_page {request:{kind:"stack", url}}、 capture_page {request:{kind:"pose", url}}、 analyze_motion {request:{kind:"scroll", url}}、 analyze_motion {request:{kind:"hover", url}}、 audit_page {request:{kind:"performance", url, compact:true}}、 audit_page {request:{kind:"bundle", url}}、および build_motion {request:{kind:"gsap_stub", scrollCensus}} を使用します。build_project と verify_build はフラットな形式のままです。build_motion には compact:false のスクロール・センサスを渡してください。対応関係の全一覧は、v2-routing.md を参照してください。

ループ

PLAN          analyze_page_structure(reference)   → band map = section plan
FOR EACH      capture_component(section selector) → section pack (recipe)
              build that section                  → in your output, fully
              gate that section                   → geometry + screenshots + checks
              iterate until every check passes    → then LOCK it
NEXT SECTION  (do not touch locked sections again)
FINALLY       whole-page verify_build             → aggregate + coherence pass

ステップ0 — バンドマップから計画する

最初に analyze_stack を実行します（1回の呼び出し）。サイトのフレームワーク、CSSフレームワーク、マーカーライブラリを確認します。WebflowまたはWordPress由来のソースは、スタイルを再適用するための規約を示します。Next由来のソースなら、コンポーネントの形状を模倣できます。次に analyze_page_structure を実行すると、top、height、bg、テキストのスニペットを含むバンドが順番に返されます。バンドの一覧を構築順として扱います。

• 数が少なく、高さも妥当（1つあたり約3,000 px以下）→ バンドを構築するセクションに1対1で対応させます。
• 巨大なバンドが1つ（5,000 px以上）→ 複数の実際のセクションが1つのバンドにまとまっています（繰り返し現れる <section class="…"> の兄弟要素が原因になることがあります）。1つの巨大なコンポーネントとして構築してはいけません。ページの生HTMLを確認し、実際のセクションごとに明示的なセレクター（.section、[role=…]、header、footer、または #id）を選びます。キャプチャで見つかった例：高さ20,631 pxのバンドにメインコンテンツ領域全体が含まれていましたが、その中の実際の4つのセクションは、クラスを使って問題なくキャプチャできました。
• 複数のバンドにまたがる共有キャンバス／WebGLのヒーロー → ページを分割できません。 そのキャンバス領域を1つの単位として扱います。キャンバスのフレームと合成されたカメラのガイダンスには capture_pose_3d を使い、単一のコンポーネントとして再構築した後、その続きは通常どおりループを実行します。Three.jsのシーンでは、adapters:["three"] を指定した capture_scene_3d によって、到達可能なノード／カメラ／ライトのみを追加で取得できます。build_scene_stub は、対応するプリミティブのサブセットとキャプチャしたカメラ行列を正確に再現しますが、親のトランスフォームは失われ、コントロールは再現されません。シェーダーの証跡には、adapters:["spector"] を指定すると、コマンド数と上限付きのシェーダーソースを含む1フレーム分の描画をキャプチャできます。引数、状態、生のキャプチャは含まれません。共有キャンバスのページをセクションごとのキャプチャに分割すると、各セクションが自分では所有していないキャンバスを参照することになります。

ステップ 1 — セクションごとにキャプチャする

バンドの順序に従って、セクションごとに capture_component(selector) を実行します。セレクターの選び方（実際のキャプチャから得た優先順位）：

1. バンド／HTML にあるセクションのクラスまたは ID（.process、.pricing、.footer）— 最も信頼できます。
2. role 属性（[role="banner"]、[role="contentinfo"]）。
3. タグ名（header、footer、nav）— 最後の手段：実際のサイトでは <header> 要素が存在しないことがよくあります（実際に Webflow サイトをキャプチャした際、nav と .footer は機能した一方で selector not found: header が返されました）。

セレクターが見つからない場合は、計画を縮小する前に代替候補を試してください。 selector not found によるキャプチャ失敗は、セクションが存在しないという意味ではなく、セレクターに問題があるということです。

ステップ 2 — セクションを完全に作り上げる

パックを基準にセクションを構築します。レイアウトはパックのジオメトリを、トークン（フォント／色／間隔）はキャプチャした計算済みスタイルを、モーションはセクションに範囲を絞った調査結果（awwwards-motion-study に従い、analyze_scroll_map と analyze_hover_census を使用）を参照します。コンテンツは自由に作成できます。一致させるのは構造、モーション、トークンです。

完成させてください。 作りかけのセクションは、次の検証に悪影響を及ぼします。確定しようとしているセクション内に、「後で対応する」プレースホルダーブロックを残さないでください。

ステップ 3 — キャプチャを基準にセクションを判定する

セクションごとの判定のために verify_build を待つ必要はありません。これは 2 つのページ全体を比較し、バンドのスコアを 1 つだけ集計して返します — bands: { score, matched, refOnly, buildOnly } — バンドごとのスコアではありません。セクション N だけを分離できず、セクションごとに実行しても、まだ構築していないセクションの評価が大半を占めます。

セクション N は、そのセクションに限定した根拠に基づいて判定します。

• ジオメトリ： バンドマップ（analyze_page_structure）からセクションの offsetTop、height、background を取得し、セクションパック（capture_component）からルートと子要素の rect（x、y、w、h）および計算済みスタイルを取得します。ビルドでも同じノードを測定し（Playwright の getBoundingClientRect ／ evaluate）、許容範囲内であることをアサートします。たとえば、セクションの高さは ±2％、子要素の位置と列数は完全一致とします。これにより、ページ全体の平均では見えない、高さが 3 倍になるバグやバンドが潰れるバグを検出できます。
• スクリーンショット： 参照セクションとビルドを同じビューポートで、セクションの中心に固定してキャプチャし、並べて比較します。ページの割合だけで一様に切り取ると、トランジションの途中に当たってしまい、何の根拠にもなりません。
• トークンとモーション： キャプチャした計算済みスタイル（フォント、色、間隔）と、構築時に参照したセクション限定の調査値（トリガー、時間、イージング、スタッガー）を確認します。
• 明示的なチェック： 構築する前に、このセクションの合格条件（高さの許容差、列数、表示される子要素、モーションの動き）を書き出し、それぞれの合否を記録します。「近い感じがする」では判定になりません。

セクション N は、すべてのローカルチェックに合格した場合にのみ確定します。数セクションを構築した後と最後に、verify_build を集計的な根拠として使用します。bands.score はページ全体の類似度を示し、matched ／ refOnly ／ buildOnly は一致した、または欠落しているバンドラベルを示します。また、モーションスコア、perf: 行（fps=… dropped=… longTasks=…）、anti-patterns: の件数も、ページレベルの根拠です。パフォーマンスにドロップフレームが表示される場合、通常の原因はアニメーションの負荷です。filter: blur のトランジション、無限ループ、またはレイアウトプロパティのアニメーションが該当します。スコアではなく、問題のプロパティを修正してください。集計スコアが良くてもセクション N のローカルな品質は証明されず、ローカルチェックに合格してもページ全体のまとまりは証明されません。

セクションごとの判定が重要な理由： 判定基準なしでセクションごとに作業しても、推測を小分けにしているだけです。セクションごとのジオメトリとスクリーンショットを使えば、「近い感じがする」を具体的な数値とセクションごとの合否に置き換えられます。そのうえで verify_build が、ローカルな判定ができるかのように装うことなく、ページレベルの数値を示します。

Step 4 — 次のセクションに進む前にロックする

ロックとは、このセクションのマークアップ／スタイル／モーションを確定することです。後続のセクションで、ロック済みのセクションを変更する必要が本当に生じた場合は、明示的に再オープンして変更します。修正し、そのセクションのゲートを再実行してから、再度ロックしてください。別のセクションを構築しながら、ロック済みのセクションをこっそりごまかして変更してはいけません。

Step 5 — 最終的な一貫性チェック

最後のセクションをロックしたら、ページ全体のverify_buildを実行し、集約エビデンスを確認します。bands.score、matched／refOnly／buildOnly、モーションスコア、パフォーマンス、アンチパターンの各行を確認してください。バンドごとのスコアは報告されないため、集約比較で問題が指摘されたセクションは、セクションごとのジオメトリとスクリーンショットを使って特定します。また、compare: "mobile"を指定してanalyze_page_structureを一度実行します。mobileBandsとdiff（bandsAdded、bandsRemoved、reordered、heightDelta）から、390×844でのみ存在するセクションや、順序が変わったセクションが分かります。デスクトップのみの再構築は、モバイルのスモークテストより先にここで検出できます。ここでは、セクションごとのループでは確認できない、セクション間の余白のリズム、ヘッダーの一貫した動作、スクロールの連続性、セクション全体で統一されたイージング（または意図的な切り替え）を確認します。一貫性の問題は、セクションを再オープンするのではなく、トークンや共通CSSなど、ページレベルで修正してください。ただし、集約バンド比較でリグレッションが示された場合は別です。その場合は、refOnly／buildOnlyのラベルと独自のジオメトリを使って、該当するセクションを特定してください。

Step 6 — ユーザーが求めた場合のみ変換する

単一ファイルでの再構築は、引き渡し可能な成果物です。ユーザーがプロジェクトを求めるか、フレームワークを選んだ場合に変換します。ロック済みのセクションは、build_project --target vite|astro|nextにそのまま必要なもので、バンドの分割がコンポーネントになります。ユーザーが作成したモーションも求める場合は、--authored --motion census.jsonを追加し、セクションごとに作成します（motion-authoringを参照）。ロックの手順は同じです。セクションNを作成し、そのセクションのゲートを再実行してロックし、次に進みます。最後に、デスクトップ全体と390px幅のモバイルで表示が一致していることを確認します。

このスキルが防ぐ失敗

失敗	発生する問題	防止するルール
巨大な折りたたみバンドを1つのコンポーネントとして構築する	6つのサブレイアウトを持つ「セクション」が1つでき、どれも中途半端になる	Step 0の明示的なセレクター分割
セレクターの見落としをセクション欠落とみなす	再構築で領域全体がスキップされる	Step 1の代替手段の段階的な試行
共有キャンバスのページを分割する	各セクションが、どこにも描画されないキャンバスを前提とする	Step 0の単位を1つにするルール
「完成済み」セクションにプレースホルダーを残す	セクションのゲートに合格しない	Step 2の仕上げルール
ページ全体でズレが積み重なる	セクションを進めるたびに、少しずつ再現度が低下する	Steps 3–4のゲート＋ロック
ロック済みセクションをこっそり変更する	ロック済みセクションのリグレッションが見逃される	Step 4の明示的な再オープン
セクションごとの仕上がりに統一感がない	ページ全体がスクリーンショットをつなぎ合わせたように見える	Step 5の一貫性チェック

補助ツール

• awwwards-motion-study — セクションごとのモーション手順（記録 → 棚卸し → 構築 → 再記録）。
• verify_build — 証拠をまとめます（手順 3 と 5）。セクションごとの ゲートではありません。ページ全体のバンドスコア（bands.score と matched／refOnly／buildOnly ラベル）、モーションスコアに加え、 計測したパフォーマンス（fps、ドロップフレーム、長時間タスク）と、 計測用のライブプローブから得られるアンチパターンの件数を示します。 実際のブラウザーを実行するため、1 回の呼び出しに約 2 分かかります。 共有 WebGL キャンバスでは、オプトインの scene3d により、 capture_scene_3d パックをビルドのキャンバス上で再生し、独立した ゲートとして固有のステータス／判定を付与します。このゲートが従来の バンド合格判定を引き上げることはありません。不安定なキャプチャ フレームは拒否され、ビルド URL はパブリックに解決可能である必要が あります（ループバックは拒否されます）。従来のスキャンの前に両方の URL を事前チェックし、どちらかがプライベートな場合はリクエストを 一切行いません。期限は、再生するチェックポイントの待機時間に 10 秒の 余裕を加えた値（下限 15 秒、上限 45 秒）です。また、キャンバスには 実行ごとのマーカーを付けるため、重複したデコイや事前にマーカーが 付いたデコイは拒否されます。
• audit_url compact:true — 詳細な証拠ではなく概要だけが必要な場合の、 パフォーマンスとアンチパターンの簡易チェックです。
• capture_pose_3d - 共有キャンバスのユニット向けのキャンバスフレームと 合成カメラガイダンス（手順 0）です。カメラ変換は復元されず、生成される スタブは同じインデックスのフレーム読み込みを重複排除し、古いデコードを 破棄します。
• capture_scene_3d + build_scene_stub - 共有キャンバス向けのオプトイン Three.js アダプターです。到達可能なグローバルのみを対象に、プリミティブ、 標準／基本マテリアル、および正確な行列から再構築した透視カメラを扱います。 キャプチャされたコントロールは再作成されず、未解決のままです。モジュール ローカルのシーン、親の変換、バインドされていないテクスチャは失われます。 scene.json のフレーム参照は、Windows または POSIX パスから抽出された ベース名です。
• capture_scene_3d spector アダプター - オプションの [email protected] を使用します。コマンド数／ステータスと、長さを制限した シェーダーソースを含む WebGL フレームを 1 つキャプチャします。描画中の フレームが必要です。引数／状態／生のキャプチャは転送せず、パッケージが 見つからない場合はアダプターの機能が制限されるだけです。
• analyze_scroll_map / analyze_hover_census - 構築の基礎となる、 セクションごとのモーション調査です。analyze_scroll_map の各行には、 キーフレームの値ペアとサイト全体の gsapTriggers リスト（数値のピクセル 単位の開始／終了位置、ライブの進行状況、トゥイーン変数）が含まれるように なりました。推測した値ではなく、計測値をもとに構築してください。ホバーの サンプルには、ホバー中にキャプチャされたアニメーション（activeAnims） も含まれます。これにより、イベント駆動のトゥイーンを確認できます。
• build_gsap_stub - キャプチャした調査結果を、実行可能な GSAP+ScrollTrigger スタブに変換します（デュレーション、イージング、 スクラブ／ピン、capture_pose_3d から合成したカメラガイダンス、 モーション低減ガード）。手順 2 のモーション配線を生成します。
• build_project — 構築 → 変換 → モーションを自分で実装： --target vite|astro|next はネイティブな構成（セクションコンポーネント、 シェル、分割 CSS、順序付けされたライブラリ）を生成します。 --authored --motion census.json はサイトのロジックを除外し、 実装時の土台となる motion.manifest.json と、セクション／ページごとの モーションフックを出力します（motion-authoring と組み合わせてください）。 変換後は必ず再検証してください。
• analyze_bundle - メカニズムの復元（手順 2 の代替手段）です。セクションの 効果を調査結果から説明できない場合は、セクションのサイトのスクリプト バンドルからメカニズムに関するキーワードを grep します。調査結果は 何がアニメーションするかを示し、バンドルはどのようにアニメーションするかを 示します。