architecture-viz-studio

アーキテクチャ可視化スタジオ

ソフトウェアのアーキテクチャやアイデアを、ただ図にするのではなく、体感できるページを作成します。目指すのは、見る人に「自社の仕事がこんなふうに見えるのは初めてだ」と思わせる、洗練された、アニメーションを取り入れたプロフェッショナルな成果物です。AI が作ったような雑なものではありません。このスキルには、長期にわたる実際の構築で培ったコードとセンスが詰まっているため、ゼロから試行錯誤するのではなく、実証済みのパーツを組み合わせて作成できます。

2つの成果物（多くの場合、1ページに組み合わせます）

1. スクロールストーリー — 固定されたローポリの 3D ワールド（Three.js）の中を、ユーザーのスクロールに合わせてカメラが進みます（GSAP ScrollTrigger）。リクエスト／オブジェクトがワールドを移動し、その上にセクションが表示されます。プロダクトをステークホルダーに体感してもらうためのものです。→ assets/scene/ と assets/scroll/ のテンプレートを使用します。
2. アーキテクチャマップ — 切り替え可能なオーバーレイレンズ（1つのマップで N 個の観点：システム／データフロー／所有権／信頼性など）、クリックするとコンポーネント図を掘り下げられるノード、データモデルの ERD を備えた、ダークな「設計図」スタイルの SVG システムマップです。アーキテクトが探索するためのものです。→ assets/diagrams/ を使用します。

どちらもデザインシステムに対応しており、提供されたブランドカラー／フォント／ロゴに合わせて調整されます（ない場合は、洗練されたニュートラルなデフォルトに調整されます）。また、assets/edit-mode/ の編集モードも搭載しています。

ワークフロー

次の流れで進めます：ストーリーをブレインストーミング → 足場を用意 → テンプレートから組み立て → 磨き上げ → 検証 → 編集モードを有効化。

1. システムを理解し、メタファーを選びます。 ユーザーが提供した設計ドキュメントや PRD を確認します。スクロールストーリーで何を描くか（1つのエンティティがシステム内を進む旅は、有力なデフォルトです）、またアーキテクチャマップのノードやレンズを決めます。3D の「ワールド」というメタファーがその領域に合わない場合は、そのことを伝え、2D 図を中心に進めます（references/diagram-catalog.md →「3D world metaphor: lands vs gimmicky」を参照してください）。

2. 構築を始める前にデザインシステムを確立します。決めつけずに尋ねましょう。 一貫したビジュアルは、最初にトークンを決めておくことで実現できます。ユーザーがすでにブランド／デザインシステムを提供している場合を除き、最初に尋ねてください（短く具体的なヒアリングにとどめ、仕様書を書かせないでください）。

   • ブランドカラーはありますか？ メインカラー／アクセントカラーの HEX 値、または参照できるロゴ／サイトを尋ねます。（ない場合は、アクセントカラーを1色に絞り、ニュートラルなグレーと組み合わせた案を提案します。）
   • フォントはありますか？ 見出し用と本文用の組み合わせ、またはブランドフォントを尋ねます。（ない場合は、洗練された組み合わせを提案します。AI が作ったように見える「どこでも Inter」は避けます。）
   • ロゴ／ワードマークはありますか？ ナビゲーションに配置します。
   • どのような美しさを目指しますか？ この用途でプロフェッショナルに見えるのは、ダークな「設計図」スタイル（アーキテクチャマップ）と淡いローポリ 3D ワールド（スクロールストーリー）の2つです。どちらか、または両方にするか確認します。
   • デザインを合わせたい既存のページ／スクリーンショットはありますか？ 一貫性を保つ最も手早い方法です。配色、文字のスケール、間隔、角丸を抽出して反映します。

   ユーザーから何も情報がない場合は、何も伝えずにデフォルトを決めないでください。具体的なデザインシステム案（アクセントカラーとフォントの組み合わせ）を提示して承認を得るか、方向性を選べるよう references/finding-layout-inspiration.md を案内します。その後、コンポーネントを作成する前に、合意したトークンを assets/page-shell/styles.css の :root ブロック（--primary-500、--neutral-*、フォント変数）に設定します。そうすれば、最初の行からすべてのパーツに一貫性を持たせられます。今すぐ references/styling-and-anti-slop.md を読んでください。プロフェッショナルな仕上がりと雑な成果物を分ける重要な資料で、ここを間違えるのは簡単です。決定内容をページと同じ場所にある簡潔な DESIGN-SYSTEM.md に記録し、後の編集時や次のセッションでも一貫性を保てるようにします。トークンのチェックリストは references/styling-and-anti-slop.md →「Design-system intake」を参照してください。

3. ページシェルを土台に構築し、まずサンプルを確認してください。 sample/ には、小規模ながら完全に実装され、十分にデバッグ済みのスクロールストーリーページがあり、すべての規約が正しく適用されています（オンデマンドでレンダリングする3Dシーン、すべてのテキスト要素へのタグ付け、背景への vizSelectable:false の設定、編集モードとマニフェストの接続、アンチスロップなスタイリング）。構築を始める前に読んでください。各要素がどう連携するかを確認する最速の方法であり、references/gotchas-and-lessons.md にある不具合もすでに回避しています。その後、assets/page-shell/index.html と styles.css をひな形としてコピーし（セクション構造、importmap、モーダルの骨組み、トークンブロック）、必要なモジュールだけを取り込みます。

   • 3Dワールド → assets/scene/scene-setup.js、primitives.js、render-loop.js。これらはデフォルトでスタジオ品質です。 scene-setup.js には、Biggest-5 のライティング基盤がすでに組み込まれています（sRGB+ACES、PMREM／RoomEnvironment IBL、リムライトを含む3点照明リグ、FogExp2、アクセント用の glowMat()、奥行きのあるムーディーなデフォルトパレット）。単一の太陽光＋環境光だけに簡略化しないでください。平坦なライティングは、素人っぽさが最も目立つ要因です。数値（ワールドサイズに合わせたフラスタム、ブランドに合わせたパレット）は調整し、構造は維持してください。
   • ⭐ ポストプロセッシング（Biggest-5 #3） → assets/scene/post-processing.js — 選択的ブルーム＋グレイン＋ビネット＋SMAAを任意で追加できます。setComposer() で接続します（3行の接続方法は page-shell のインポートグラフを参照してください）。postprocessing のimportmapエントリが必要です（page-shell/index.html にはすでにあります。/+esm ではなく、生の build/index.js を指定してください。そうしないとthreeが2つ取り込まれ、ブルームが動作しなくなります）。これが「すごい」と感じさせる最後の20%です。ヒーローシーンには追加し、軽量なページでは省略してください。
   • スクロールの演出 → assets/scroll/scroll-journey.js — デフォルトで Lenis のスムーズスクロールレイヤーが組み込まれています（lenis のimportmapエントリは page-shell/index.html にすでにあります）。これにより、マウスホイールでのスクロールが引っかかったり停止したりせず、滑らかに動きます。scrub だけでは解決しません。操作感に合わせて duration を調整してください。視差効果を抑える設定が有効な場合は無効になります。理由については、プレイブックの「スムーズスクロール」を参照してください。
   • アーキテクチャマップのレンズ → assets/diagrams/overlay-lens-system.js（initOverlays → drill フラグ）
   • コンポーネント図のドリルダウン → assets/diagrams/component-detail-modal.js（initDrill — data-drill ノード）
   • ERD → assets/diagrams/erd-diagram.js（initErd — data-erd ノード。開閉／二重 rAF での描画／一時停止のライフサイクル一式をまとめているため、自分で組み立て直す必要はありません。スキーマに合わせるには intro／columns を渡します）
   • あらゆる図のパン／ズーム → assets/diagrams/pan-zoom-viewport.js
   • 選択可能な矢印 → assets/diagrams/edge-hit-proxies.js（tagSvgEdges）。細いSVGのエッジすべてに広い透明なヒット領域を設け、編集モードでクリックできるようにします（そうしないと、2pxの矢印はほぼ選択できません）。各SVGにつき1回呼び出します（メインマップと、各ドリル／ERDモーダルで、レンダリング後に呼び出してください）。 これらはそれぞれ1行で接続できます。assets/page-shell/index.html のインポートグラフと、完全な汎用化済み実装例がある sample/ を参照してください（中立的なCDNドメインを使っています。接続方法をコピーし、文言とデータを差し替えてください）。

4. **最初からAIで調整しやすい規約に従って作成します。**これは任意の仕上げではなく、ページを後から修正可能にするための仕組みです。**すべてのDOMコンポーネントにdata-viz-id="dotted.name"を付け、すべての3DオブジェクトにregisterVizObject(obj, 'scene.name')を設定します。**コンテナーだけでなく、すべてのテキスト要素にタグを付けます。見出し、段落、ナビゲーションリンク、フッター／ヘッダーのテキスト、バッジや数値にも、それぞれ独自のドット区切りID（card.audit.title、footer.copyrightなど）を付けます。編集モードで選択できるのは、自分自身のIDを持つノードだけです。そのため、タグのないテキストは指定できず、ポイントするとカード全体が選択されます。オブジェクトごとに名前付きの小さなビルダー関数を使い、レイアウト定数は冒頭にまとめ、深い入れ子よりも設定オブジェクトを使います。references/ai-collaboration-protocol.mdを読んでください。理由は、後からユーザーがフィードバックを伝えたとき、編集モードツールが正確なIDを提示するため、それぞれのIDを対応するビルダーに直接割り当てられ、どの「ボックス」を指しているのか推測せずに済むからです。

5. **レイアウトは意図的に選びます。**汎用的な配置をデフォルトにしないでください。図ごとにreferences/diagram-catalog.mdを参照してください。状況に適したレイアウトが記載されています（例：ERD → 線が交差しないハブ＆スポーク型、パイプライン → 注釈を下に配置する水平帯型、システムマップ → 領域レーン＋オーバーレイレンズ）。エッジのルーティング規則（アンカーを均等に分散する、「多」側にカラス足記号を付ける、端点にカーディナリティを表示する、矢印に沿ってラベルを配置する）もこのドキュメントにあります。これらの規則は多くの修正を重ねて培われました。

6. **実際のブラウザーで確認し、チェックも実行します。**これは必須です。これらのページは視覚的で、アニメーションのタイミングにも左右されるため、コードを読むだけでは確認できません。ローカルでサーバーを起動し（python3 -m http.server）、chrome-devtoolsツールで操作します。各スクロール状態と各オーバーレイ／モーダルのスクリーンショットを撮り、コンソールに問題がないことを確認します。次に、スクリーンショットでは見落とす客観的なレイヤーを対象とした、同梱のチェックを実行します。

   • node scripts/verify.mjs <url> --out report.json --shots shots/ — コンソール、3つのビューポートでのレイアウト検査（はみ出し／重なり／テキストのクリッピング）、axe-coreによるアクセシビリティ＋コントラストのJSON、WebGLキャンバスが実際に描画されたことのチェック、スクロール時のカクつき／CPU使用率（fpsではありません。ヘッドレス環境のfpsは代表的な指標ではないため）。
   • node scripts/slop-lint.mjs <url> --json slop.json — AIのスロップを示す機械的な兆候（anti-slop barを参照）。
   • node scripts/text-audit.mjs <url> — 独自のdata-viz-idを持たないテキスト要素があると失敗します（ユーザーがコンテナーだけでなく、すべての見出し／段落／フッター行を指定できるようにするため）。⚠️ この検査で確認できるのは静的なページだけです。ドリルダウン／ERDモーダルは開かないため、JavaScriptで描画された本文にタグがなくても問題なしと報告されます。ポップアップも実際に監査します（各モーダルを開き、独自のIDを持たないテキストノードがないか調べます。ドリルのタブによっては、異なるレールビルダーが使われている場合があります）。visual-verificationを参照してください。
   • 3Dジオメトリの不具合（先端から頭部がずれている、隙間がある、キャップが覆っていない、オブジェクトの配置がずれている）がある場合、スクリーンショットを目視するだけにしないでください。実際に動作しているシーンにアクセスし、測定します（ページの{THREE,scene,camera,renderer}コンテキストを取得し、ワールド／スクリーン座標を比較します。カスタムカメラを配置する前に描画ループを停止します）。手法はreferences/visual-verification.mdの「Reaching INTO the live scene」にあります。これにより、推測と試行錯誤の繰り返しを終わらせられます。
   • ハードリロード（キャッシュを無視した再読み込み）で再確認します。ページはmain.js／styles.cssをキャッシュするため、通常の再読み込みでは古いバンドルが読み込まれ、適用したばかりの修正が反映されていないように見えます。 チェックがすべて通る状態は最低ライン（「機械的な問題がなく、スロップの兆候がない」）であり、到達点ではありません。比喩が伝わるか、プレミアムな印象があるか、動きが上品かといったセンスに関わる判断には、あなた自身とユーザーの目が必要です。正確なスタックと、人間による判断が必要な範囲についてはreferences/visual-verification.mdを読んでください。（スクリプトにはPlaywrightが必要です：npm i -D @playwright/test axe-core && npx playwright install chromium。） ページに Three.js シーンがある場合、完了とする前に 2 つのチェックリストを必ず確認してください：

   ⭐ （a）WOW 品質ゲート（references/wow-quality-bar.md → 「The Biggest-5」）。「バグがない／検証済み」は最低条件であり、合格基準ではありません。ユーザーが期待しているのは、プロの 3D デザイナーが公開できるような、人々を驚かせるものです。正しくても平坦なシーン（アンビエントライトのみ、素の MeshStandardMaterial、デフォルトのリニアレンダリング、ポストプロセスなし、リニアカメラ）は、学生の練習課題のように見え、不合格です。少なくとも Biggest-5 を適用してください：（1）トーンマッピング＋sRGB＋DPR≤2、（2）PMREM 経由の HDRI／RoomEnvironment IBL、（3）pmndrs/postprocessing — 選択的ブルーム＋被写界深度、（4）リムライトを加えた 3 点照明＋ソフトなコンタクトシャドウ、（5）イージング付きの段階的なGSAP リビール＋FogExp2。次に実際に見てください。本当に「すごい」と感じられますか？普通に見えるなら、まだ完成ではありません。これは、あなた（そしてユーザー）が判断すべき美的な評価です。

   ⚡ （b）パフォーマンスチェックリスト（references/gsap-threejs-playbook.md → 「Mandatory performance checklist」）。パフォーマンスを損なう WOW は WOW ではありません。オンデマンドレンダリングでアイドル時の GPU 使用率をほぼ 0 にしてください（または、常時アニメーションするシーンの場合は、ステージが画面外にあるとき／タブが非表示のとき／モーダルが開いているときに一時停止してください。固定キャンバス自体ではなく、その上をスクロールしていくコンテンツを確認してください）。GSAP の単一ティッカーで fps を 60 に制限し、DPR ≤2、繰り返し使用するメッシュはインスタンス化し、ポストプロセスチェーンは 1 つの EffectPass に統合し、シャドウマップは ≤2048 にし、静的なものはベイクし、フレームごとのアロケーションは避けてください。計測してください（verify.mjs がジャンクを報告します）。「滑らかに見える」という感覚を決して信じないでください。美しいのにカクつくシーンは（b）で不合格、滑らかなのに平坦なシーンは（a）で不合格です。

7. viz-manifest を生成する（任意ですが推奨）。 node scripts/gen-viz-manifest.mjs <pageDir> --as-js を実行して、すべての data-viz-id／userData.vizId を {file, line, builderFn, cssRule} に対応付ける viz-manifest.json（＋ .js）を出力します。edit-mode の前に読み込んでください。これは「ユーザーが指し示したもの」から「それを作るコード」への 1 ホップの橋渡しであり、Three.js オブジェクトには grep できる DOM ノードがないため、これが唯一の橋渡しです。edit-mode は各コメントに source を記録し、window.__viz（assets/edit-mode/viz.js）を使うと、実行時に ID をクエリできます。

8. 編集モードを有効にして引き継ぎます。 assets/edit-mode/edit-mode.js と .css を組み込みます（3 段階の組み込み手順については、ファイルのヘッダーを参照してください）。必要に応じて assets/edit-mode/viz.js も含めます。ユーザーには、✎ ボタンまたは e で切り替えられることを伝えます。ツールバーには Normal/Expert ビュー（Normal ではホバー時にコンポーネントの矩形と ID を表示し、Expert ではすべての ID を一度に表示します。どちらも DOM オブジェクトと 3D オブジェクトが対象です）と、4 つのツールがあります。Pointer（ページを通常どおり操作します。ハイライトは表示されず、クリックはそのまま通過します。ツールバーを表示したままページを操作したい場合に使います）、Select（要素をクリックしてコメントに追加します。ctrl/⌘+クリックで複数選択を作成できます。ctrl/⌘+クリックを続けて追加し、もう一度 ctrl/⌘+クリックして削除します。その後、Enter または通常のクリックで、選択したすべての要素を対象にした 1 つのコメントを作成します）、Snip（ドラッグして矩形を描画します）、Brush（フリーハンドで領域を塗ります）。コメントは（ドラッグ可能な）サイドパネルに集約されます。 フィードバックを受け取る方法 — ブリッジによって機能が強化された「Copy for AI」ボタンを使います。

   • scripts/serve.sh で配信する場合（推奨）： ./scripts/serve.sh <pageDir> を実行すると、ページサーバー（8800）と feedback-bridge（8910）が同時に起動します。ページが稼働している間はブリッジも常に稼働するため、別プロセスの起動を忘れる心配がありません。編集モードを { bridge: 'http://localhost:8910' } で初期化します。すると 「Copy for AI」 はマークダウンをコピーすると同時に、バッチと Snip の PNG をブリッジに POST し、ブリッジが /tmp/viz-edit/ に保存します。ユーザーには「フィードバックを読んで」と言ってもらうだけで大丈夫です。edit-feedback.json（各コメントに絶対パスの imagePath が含まれています）と PNG を直接読み取ります。ブリッジが停止している場合、「Copy for AI」は通常のクリップボードへのコピーに自動でフォールバックします。（代替手段：node scripts/feedback-bridge.mjs と python3 -m http.server を自分で実行します。）
   • ブリッジを使わない場合： 「Copy for AI」はチャットに貼り付けるマークダウンをコピーします。ID やテキストのコメントには使えますが、Snip の画像は含まれません。または Download を使って（edit-feedback.json + snip-N.png）ダウンロードし、node scripts/receive-feedback.mjs を実行すると、JSON に記載されたパスで /tmp/viz-edit/ に保存できます。 バッチを処理するには、各 ID からビルダーを特定し（source フィールドを確認するか、ID を grep します）、視覚的なコンテキストを把握するために imagePath があれば読み取り、sceneContext を使って正確な 3D の状態を再現します。

9. 共有用のスタンドアロン HTML をエクスポートします。 サーバーなしで送信または開ける単一ファイルのエクスポートを必ず提案します。node scripts/bundle-standalone.mjs index.html を実行すると、ローカルの CSS/JS がすべて 1 つの .html にインライン化されます。編集モードはデフォルトで除外されます（エクスポートは公開用の成果物です）。完全なオフラインファイルにするには --vendor を追加して CDN ライブラリ（three/gsap）もインライン化し、作成ツールを残すには --keep-edit を追加します。

運用知識（必要に応じて読む）

• references/gotchas-and-lessons.md — ⚠️ まずこれを読んでください。 以前のビルドで、デバッグを一巡余計に必要とした実際のバグをまとめています。SVG の .hidden が何もしない問題、[hidden] が display クラスに負ける問題、contains(window) が例外を投げる問題、DOM が 3D のホバーを横取りする問題、レイキャストできない細いチューブ、登録されていない vizId オブジェクト、GPU がアイドル状態でもレンダリングループが回る問題、readPixels が黒を返す罠、機能しない swiftshader フラグ、ESM モジュールの解決、すべてのテキストにタグを付けるルールなどです。編集モードの配線、3D 選択、レンダリングループ、検証スクリプトを書く前にざっと目を通してください。避けられる手戻りの中で、最もコストが低いものです。
• references/gsap-threejs-playbook.md — GSAP + Three.js の手法と注意点です。ScrollTrigger のスクラブ、区分的なカメラパラメーターの再マッピング、getPointAt（弧長）と getPoint の違いと使い分け、チューブを描画する方法、InstancedMesh、キャンバステクスチャのラベル、ベジェ接線に沿ったラベルの回転、そして パフォーマンス／レンダリング一時停止パターン（3D ステージが画面外にあるとき、またはモーダルが開いているときはループを一時停止します。CPU／GPU の負荷を大幅に削減できます）について説明しています。シーンやスクロールのロジックを書く前に読んでください。
• references/wow-quality-bar.md — ⭐ スタジオ品質の基準です。「バグがない」だけでは不十分で、「すごい」と思わせる必要があります。 プロ品質の 3D ヒーローと学生の練習作品を分ける要素として、トーンマッピング／sRGB パイプライン、HDRI／PMREM 環境ライティング、pmndrs/postprocessing（選択的ブルーム + DOF + 色調補正）、3 点ライティング + リムライト + ソフトな接地影、GSAP によるイージング付きの段階的なカメラワークと要素の登場演出、雰囲気づくり（フォグ／パーティクル／ゴッドレイ）、そして優先順位順の 最大の 5 項目を取り上げています。ヒーローシーンは、最大の 5 項目をクリアするまで完成ではありません。3D シーンを構築する前と後に読んでください。
• references/styling-and-anti-slop.md — センスと節度、粗雑さを防ぐチェックリスト、デザインシステムの取り入れ方について説明しています。スタイリングの前に読んでください。
• references/diagram-catalog.md — 図ごとのレイアウトパターン、共通のエッジ経路設定ルール、オーバーレイレンズのモデルについて説明しています。図をレイアウトする前に読んでください。
• references/finding-3d-models.md — 汎用的な箱を積み重ねず、実際のディテールがあるオブジェクトをモデリングしてください（サーバーなら、立方体 3 個ではなく、ラック + スリット + LED です）。プロシージャル作成を優先する判断ツリー、ライセンスごとの公開ルールを含む、検証済みの無料モデルソース一覧（Kenney／Quaternius／KayKit CC0、Poly Pizza、Sketchfab、Poly Haven の HDRI、three.js-examples は MIT ライセンスではないという注意点）、AI 生成ツール（ライセンスはプランによって異なります）、GLTFLoader → 色変更 → glTF-Transform による最適化のパイプラインを紹介しています。3D オブジェクトの作成／インポート時や、オンラインでモデルを探すときに読んでください。
• references/finding-layout-inspiration.md — オンラインでスクロールストーリーや図の参考例を見つける方法（Awwwards、vectrfl／Stripe／Linear のスクロールテリングのジャンル、C4、Oxygen-Not-Included のオーバーレイのメタファー）と、見た目ではなく構造を取り入れる方法を説明しています。
• references/ai-collaboration-protocol.md — data-viz-id／userData.vizId の規約、読みやすいコード構造、編集モードのツールが出力する正確な JSON／Markdown の契約について説明しています。これにより、フィードバックの取り込み方がわかります。コンポーネントを書く前や、編集モードのフィードバックを受け取ったときに読んでください。
• references/visual-verification.md — ページを機械のように読み取り、検証する方法について説明しています。scripts/verify.mjs の構成（レイアウトの検査、axe によるコントラスト検査、キャンバスの描画チェック、GSAP の .progress() によるフレーム固定、ジャンク／CPU の検査）、scripts/slop-lint.mjs のルールセット、viz-manifest のラウンドトリップ、そして人間による確認が今も必要な項目の正直な一覧を取り上げています。検証の前や、マニフェスト／window.__viz を配線するときに読んでください。

同梱テンプレートライブラリ（書き換えずにコピー）

assets/ 内のファイルはすべて、丁寧に作り込まれた約30ラウンドの実際のビルドから抽出され、構文チェック済みです。各ファイルには、内容、依存関係、組み込み方を説明するヘッダーコメントがあります。汎用化された内容には EXAMPLE／PLACEHOLDER と記されています。コピーする前に、ファイルのヘッダーを読んでください。 数学的な処理は忠実に再利用してください。特に、ERD のグリフのジオメトリ、カーソル位置を基準にしたパン／ズーム、カメラのリマップ、レンダリング一時停止ループは、ゼロから実装すると微妙な間違いが起きやすい部分です。

sample/            ← a COMPLETE working reference page (read this first — all conventions applied correctly)
                     includes a filled-in DESIGN-SYSTEM.md worked example
assets/
├── page-shell/    index.html · styles.css · DESIGN-SYSTEM.md   ← start here: skeleton + token block + intake template
├── scene/         scene-setup · primitives · render-loop · post-processing   ← the Three.js world (studio-grade defaults)
├── scroll/        scroll-journey                  ← GSAP ScrollTrigger choreography
├── diagrams/      overlay-lens-system · component-detail-modal · erd-diagram · pan-zoom-viewport · edge-hit-proxies
└── edit-mode/     edit-mode.js · edit-mode.css · viz.js   ← visual-feedback tool (Pointer/Select+multi-select/Snip/Brush) + window.__viz query API
scripts/           ← run these to verify and to wire the id→source round-trip (need Node; verify/lint/audit need Playwright)
├── verify.mjs           console · layout probes · axe a11y/contrast · canvas-rendered · jank/CPU
├── slop-lint.mjs        the mechanical AI-slop tells (DOM + computed styles)
├── text-audit.mjs       flags any text element missing its own data-viz-id (the tag-every-text rule)
├── gen-viz-manifest.mjs build-time vizId → {file,line,builderFn,cssRule} map (the one-hop bridge)
├── bundle-standalone.mjs  inline the page into ONE shareable .html (edit-mode STRIPPED by default)
├── feedback-bridge.mjs    makes "Copy for AI" also write comments+snips to /tmp/viz-edit (read by absolute path)
├── receive-feedback.mjs   offline fallback: move downloaded edit-feedback.json + snips into /tmp/viz-edit
└── serve.sh               start the page server + the feedback-bridge together (so the bridge is always up)

Playwright スクリプトの実行に関する注意：ESM はスクリプトの場所から node_modules を解決します（NODE_PATH は適用されません）。そのため、テスト対象のプロジェクトに scripts/ をコピーし、node_modules の隣で実行してください。インストールは一度だけ行います：npm i -D @playwright/test axe-core pngjs && npx playwright install chromium。

編集モードのフィードバックを受け取ったとき（修正ループ）

ユーザーは次のような項目をまとめて貼り付けます：

## 1. component: hero.title
   make this 20% smaller and tighten the line height
## 2. area snip — components inside: arch.node.api, arch.edge.cdc
   (screenshot snip-2.png attached)
   these two are too close, add breathing room
## 3. object: scene.service-core
   make it taller and more imposing

各項目について、ID から対応するビルダー関数／CSS ルールを特定し（安定した ID は必ず1か所だけに対応します）、変更を加えたら、ブラウザーで該当箇所を再確認してください。項目全体に変更を適用したら、影響を受ける領域のスクリーンショットを撮ります。この規約が実現する最短ルートです。「指摘された箇所」から「それを作っているコード」まで、1ステップでたどれます。

基準（最も重要なポイント）— 2つの柱：粗雑さを排し、感動を生む

第1の柱 — 粗雑な仕上がりにしない（2D／ページ）。 ありきたりな AI 生成ページのような仕上がり（すべてを中央揃えにする、紫のグラデーション、絵文字の見出し、グラスモーフィズム、デフォルトの余白、ノードごとに色を変えるなど）になったら失敗です。基準を守ってください。アクセントカラーは1色に絞り、それ以外はニュートラルなグレーにすること。明確な文字サイズの段階、ゆとりある余白、フラットなクローム、控えめな動き、統一された角丸とシャドウを用いること。 詳細は references/styling-and-anti-slop.md を参照してください。

第2の柱 — WOW を生み出す（3D／ヒーロー）。 粗雑さを避けるのは最低条件です。目指すのは、プロの3Dデザイナーが誇れる、見た人を驚かせる出力です。 単に正しいだけの3Dシーン（フラットな環境光、加工されていないマテリアル、デフォルトのリニアレンダリング、ポストプロセスなし、リニアカメラ）は、バグがまったくなくても 学生の課題 のように見え、失敗です。基準となるのは references/wow-quality-bar.md の Biggest-5 です。トーンマッピング／sRGB パイプライン、HDRI／PMREM 環境ライティング、選択的なブルーム＋被写界深度によるポストプロセス、柔らかなコンタクトシャドウを伴う3点照明＋リムライト、そしてイージングを用いた段階的な GSAP モーションです。WOW を生み出すのはジオメトリではなく、光、奥行き、雰囲気、そしてグレーディングされた最終画像です。この基準は、粗雑さを避ける基準と同じ厳しさで守ってください。

どちらの場合も、ここで目指すプロフェッショナルな見た目は、ダークな「ブループリント」建築の美学と、淡いローポリの3D世界の2つです。どちらも WOW の基準を満たしてください。これらすべてを守ることで、「こんなに良いものが作れるなんて知らなかった」と言ってもらえる仕上がりになります。

人の目で確認する前に、機械的な粗雑さの兆候を見つけるには、node scripts/slop-lint.mjs <url> を実行します。色相250～300°のインディゴ／バイオレット系 CTA、グラデーションテキストのヒーロー、ネオングローのシャドウ、均一すぎる角丸／パディング、中央揃えの Inter ヒーロー、色パレット／文字サイズの段階の乱立、グラスモーフィズム、絵文字のナビゲーション／見出し、同一のアイコンカードグリッド、コントラストの低いダークカラーの本文テキストを検出します。lint がクリーンであることは必要条件ですが、十分条件ではありません。「明らかな粗雑さの兆候がない」という意味であり、「優れたデザイン」という意味ではありません。良し悪しを判断するには、やはり自分の目とユーザーの目が必要です。