インタラクティブサイトアーキテクチャは何をしますか？

成果物

コンテンツ、ナラティブ、ビジュアルアイデンティティ、およびインタラクションの品質が重視される、プロダクション向け公開Next.jsサイトを作成します。これはコンテンツ主導のサイトのための汎用アーキテクチャです：ブランド・マーケティングサイト、SaaS・プロダクトサイト、ランディングページ、エディトリアルプロパティ、ポートフォリオ、コミュニティ、カンファレンス、ドキュメントサイト、没入型ショーケースなどに対応します。

コアは固定です：

サーバーレンダリングされたコンテンツ;
狭いクライアントアイランド;
検証済みのコンテンツ契約;
共有デザイン・モーショントークン;
ネイティブブラウザ動作;
サーバーレスポンス内のSEOとアクセシビリティ;
ルートスコープのパフォーマンス予算。

製品が必要とするモジュールを選択します：

モジュール	使用する場面
コンテンツ収集と詳細	サイトにプロジェクト、記事、製品、人物、イベントなどのレコードがある場合
ポートフォリオまたはケーススタディ	組織が実績による証明を必要とする場合
没入型アーカイブ	ビジュアル探索が主要なプロダクトサーフェスである場合
ストア	サイトがデジタル製品または物理製品を販売する場合
CMSアダプター	編集者がリリースとは独立して公開する必要がある場合
お問い合わせフォーム	メールリンクやカレンダーだけでは不十分な場合

必要なモジュールを必要としないサイトに強制しないでください。

典型的なプロファイルは同じコアを再利用します：

SaaSまたはプロダクト：ランディング、オファー、機能、コンテンツ収集、ドキュメントまたはチェンジログ。
ブランドまたはローンチ：キャンペーンナラティブ、製品発表、ウェイトリスト、社会的証明。
エディトリアル：コレクションインデックス、記事詳細、著者、トピック、検索。
コミュニティまたはカンファレンス：スピーカー、スケジュール、セッション、会場、チケット。
ポートフォリオ：プロジェクトインデックス、ケース詳細、ビジュアルアーカイブ、お問い合わせ。
コマース：カタログ、製品詳細、チェックアウト、ダウンロードまたはフルフィルメント。

行動前の確認

ビルド、リデザイン、またはアーキテクチャ変更のたびに references/architecture-contract.md を読んでください。
フォルダ、契約、サービス、アダプター、またはサーバーアクションを作成する前に references/code-architecture.md を読んでください。
依存関係のインストール、アップグレード、または削除の前に references/dependency-matrix.md を読んでください。
新しいアプリケーションの場合は references/build-playbook.md に従ってください。
新しいルート、コンテンツタイプ、アイランド、アーカイブ、ストア製品、またはマイグレーションの場合は references/evolve-playbook.md に従ってください。
承認またはリリースの前に references/quality-gates.md に従ってください。

再利用可能なテンプレートは assets/templates/ にあります。選択したアーキテクチャに一致する場合のみ、それらから開始してください。すべてのテンプレートを盲目的にコピーしないでください。

非交渉の不変条件

デフォルトではページ構成とプライマリコンテンツをServer Componentsに保持します。
use client は最も小さな実行可能なリーフに配置します。可能な場合は、クライアントラッパーを介してサーバーレンダリングされた子をアニメーション化します。
TypeScriptデータ契約を、すべてのコンテンツエンティティ、メタデータレコード、ギャラリー、サイトマップエントリの真実の源泉として扱います。
すべてのオーバーレイインタラクションに、クライアント状態、JavaScript、またはハッシュなしで動作する実際のルートを提供します。
ネイティブHTML動作を優先します：リンク、ボタン、フォーム、<dialog>、フォーカス管理、ブラウザ履歴。
シークレットはサーバー専用モジュールに保持します。NEXT_PUBLIC_* を使用できるのは公開識別子のみです。
コマースが存在する場合、価格、権利決定、支払い確認、保護されたダウンロードをサーバーに保持します。
prefers-reduced-motion、キーボードナビゲーション、可視フォーカス、セマンティック見出し、およびスクリプトなしでの可読性を尊重します。
あるルートのコンテンツを別のルートの初期クライアントバンドルに含めないようにします。クライアントシェルがカウントやラベルを必要とする場合、サーバーから小さなサマリーを渡します。
薄いルートアダプター、所有するフィーチャーモジュール、明示的なポート、および単一の構成境界を持つモジュラーモノリスを使用します。
安定した依存関係を優先します。未検証のReactビルドで新しいプロダクションアプリを開始しないでください。

デフォルトスタック

サイトに文書化された理由がない限り、依存関係マトリックスで検証された正確なバージョンを使用します。

Node 26 LTSファミリーとpnpm。
Next.js App Router、React、React DOM、TypeScript。
Tailwind CSS 4（トークン、リセット、ユーティリティレイアウト用）。
CSS Modules（ルートまたはコンポーネント固有のコンポジション用）。
Motion for React（オーケストレーションとジェスチャー用）。
ネイティブdialog、Canvas、SVG、CSS、Web Animations API（それらで十分なインタラクション用）。
Lucideアイコン（個別にインポート）。
Zod（コンテンツと外部入力の境界用）。
Vercel（デプロイ、分析、画像配信用）。
Stripe Embedded Checkoutとサーバーアクション（コマースが必要な場合）。

作業順序

公開サーフェスを棚卸しします：ランディングページ、コンテンツインデックス、詳細ルート、コンバージョンパス、法務ルート、検索、アーカイブ、コマース。
実装前にルートマニフェストとクライアント境界マップを確定します。
ファイルを作成する前に、機能所有者、ポート、ルートアダプター、外部アダプターを割り当てます。
セクションを構築する前に、コンテンツエンティティと必要なメディアをモデル化します。
グローバルトークン、タイポグラフィ、スペーシング、状態、モーション削減動作、画像規約を確立します。
サーバーシェル、ナビゲーション、ルートフォールバック、SEOメタデータを構築します。
クライアントアイランドを一度に1つ追加します。それぞれがクライアントサイドでなければならない理由を記録します。
ネイティブダイアログとURL状態を使用してオーバーレイを構築します。同時に正規のページルートを追加します。
複雑なビジュアルは、そのデータ、フォールバック、モーション削減動作、パフォーマンス境界が定義された後に追加します。
CMS、コマース、アカウント、または永続化は、運用モデルがそれらを必要とする場合にのみ追加します。
アーキテクチャ境界チェック、構造監査、フォーカステスト、品質ゲート、プロダクションプレビュー承認を実行します。
実装された動作、検証されたエビデンス、および未検証の制限事項を別々に報告します。

決定ルール

ホバー、フォーカス、プレス、表示、マーキー、および単純な状態変更にはCSSトランジションを使用します。
調整されたバリアント、レイアウトトランジション、ドラッグ、プレゼンス、およびスクロールリンクオーケストレーションにはMotionを使用します。
CanvasまたはWebGLは、DOM、SVG、CSSで視覚を確実に表現できない場合にのみ使用します。表示一時停止、DPR制限、クリーンアップ、モーション削減動作、静的フォールバックを追加します。
コンテンツコレクションはサーバーレンダリングに保ちます。カウント、ラベル、または選択されたレコードのみをクライアントオーバーレイシェルに送信します。
プレビューやシートには、同じコンテンツに正規ページがある場合はネイティブ<dialog>を使用します。深く、長く、または独立してリンクされたコンテンツには専用ルートを使用します。
アプリとともにリリースする小規模チームには、検証済みコードコンテンツを使用します。編集者が独立した公開を必要とする場合は、リポジトリアダプターの背後にCMSを導入します。
ストアが即時購入とダウンロードのみを必要とする場合は、ステートレスなStripeセッションを使用します。製品が権利、返金、アカウント、注文履歴、またはリトライを必要とする場合は、データベースと検証されたウェブフックを追加します。
Radix、shadcn、またはその他のコンポーネントライブラリは、それが所有するプリミティブを特定した後にのみ追加します。ネイティブ要素とサイト所有のプリミティブがベースラインです。
ポートフォリオ、アーカイブ、ストアはモジュールとして扱います。これらはコアのコンテンツ、ルート、スタイル、モーション、セキュリティ契約を再利用します。

必要なビルドアーティファクト

以下のサイトレベルアーティファクトを作成し維持します：

docs/architecture.md：ルートマップ、クライアント境界、コンテンツ所有権、外部サービス、パフォーマンス予算。
src/features/*/domain および src/features/*/application：検証済み契約と機能。
src/platform/*：外部アダプターとサーバー専用コンポジションルート。
src/shared/*：実績のあるクロスフィーチャー契約とデザインプリミティブ。
src/components/*：明示的な名前を持つサーバーコンポジションとクライアントアイランド。
src/app/*：ページ、レイアウト、メタデータ、サイトマップ、robots、ルートハンドラー。
.env.example：名前と目的、実際のシークレットは決して含めません。
コンテンツ検証、クライアント状態マシン、サーバーアクション、重要なブラウザジャーニーに対するテスト。
プレビュー、ブラウザ、アクセシビリティ、パフォーマンス、SEO、および条件付きコマースのエビデンスを含むリリースチェックリスト。

構造監査

スキャフォールディング後およびリリース前に、アーキテクチャ境界チェックとバンドル監査を実行します：

pnpm arch:check
node scripts/audit_site.mjs --root /path/to/app

警告が失敗とみなされる場合は、CIで --strict を使用します。このスクリプトは、依存関係の存在、ルートとコンテンツ構造、クライアント/サーバーシークレットの危険性、ダイアログとモーションの保護、テスト、SEOファイル、ソースマップの公開をチェックします。これはテストを補完するものであり、置き換えるものではありません。

完了契約

以下の条件をすべて満たした場合にのみ、ビルドは完了とみなされます：

ルートと境界マップが実装と一致していること;
依存関係グラフに循環がなく、arch:check が成功すること;
ルートがフィーチャーの公開APIを使用し、コンポジションルートが配線を所有していること;
アプリがカナリアまたはピア依存関係の驚きなしにビルドされること;
重要なコンテンツがサーバーHTMLに表示されること;
オーバーレイ、メニュー、キーボードパスが機能し、フォーカスを復元すること;
モーション削減とスクリプトなしのフォールバックが検証されていること;
メタデータ、サイトマップ、robots、正規URL、ソーシャル画像が存在すること;
初期ルートJSと画像ペイロードが文書化された予算内に収まること;
コマースが存在する場合、サーバー所有の価格、サーバー側確認、保護されたダウンロードが使用されていること;
プレビューとプロダクションのエビデンスが別々に記録されていること。

インタラクティブサイトアーキテクチャ