web-rules

React 19 + Next.js 16 + Tailwind CSS のベストプラクティス

React 19、Next.js 16 App Router、Tailwind CSS 4 で構築するウェブアプリ向けの、厳格なルールをまとめた包括的なリファレンスです。6 つのカテゴリにわたる 34 のルールが含まれています。各ルールは、定量化された効果、誤った例、正しい例とともに、必ず／決してという指示形式で記載されています。

スタックの前提条件

すべてのガイダンスは、以下を前提としています。

• React 19。デフォルトではサーバーコンポーネントを使用し、インタラクティブ性が必要な場合にのみクライアントコンポーネントを使用します（先頭に 'use client' を記述）
• Next.js 16 App Router。app/ ディレクトリ、layout.tsx、page.tsx、loading.tsx、error.tsx、not-found.tsx、並列ルート、インターセプトルートを使用します
• Server Actions を変更処理に使用します（'use server'）。データ取得に useEffect を使うことは決してありません
• Tailwind CSS 4。@theme ディレクティブ、dark: バリアント、コンテナクエリ、標準の 4pt 間隔スケールを使用します
• アイコンシステムには lucide-react を使用します
• CSS-in-JS は使用しません（styled-components、emotion は使用しません）。Tailwind ユーティリティクラスのみを使い、条件付きクラスには clsx と tailwind-merge の cn() を使用します
• ダイアログ、ポップオーバー、ドロップダウン、ツールチップ、トーストには shadcn/ui プリミティブ（Radix ベース）を優先します

適用する場面

以下の場合に、これらのルールを参照してください。

• ユーザー向けのルート、レイアウト、コンポーネントを構築するとき
• デザイン、UX、アクセシビリティのリグレッションについて PR をレビューするとき
• 表示形式（ダイアログ、ポップオーバー、全画面ページ）を選ぶとき
• Server Actions と useFormState ／ useOptimistic を使ってフォームを実装するとき
• ローディングおよびエラーバウンダリを設定するとき
• オンボーディング、権限、設定のフローを設計するとき
• ダークモード、フォーカス管理、キーボード操作が一貫して機能することを確認するとき

優先度別ルールカテゴリ

優先度	カテゴリ	影響	プレフィックス
1	ナビゲーション	CRITICAL	nav-
2	インタラクションデザイン	CRITICAL	inter-
3	アクセシビリティ	CRITICAL	acc-
4	ユーザーフィードバック	HIGH	feed-
5	UX パターン	HIGH	ux-
6	ビジュアルデザイン	HIGH	vis-

クイックリファレンス

1. ナビゲーション（CRITICAL）

• nav-primary - 上部ナビゲーション（3～7 セクション）またはサイドバーを使用します。デスクトップでハンバーガーメニューのみを使うことは決してありません
• nav-app-router - App Router のレイアウト、並列ルート、<Link> を使って、すべての内部ナビゲーションを実装します
• nav-page-actions - 主要なアクションはページヘッダーに配置します。スクロールしないと見つからない場所に置くことは決してありません

2. インタラクションデザイン（CRITICAL）

• inter-touch-targets - タッチターゲットは最小 44×44 px にします（WCAG 2.5.5）
• inter-pointer-patterns - 標準的なホバー／クリック／長押しのパターンを使用します。新しいパターンを独自に考案することは決してありません
• inter-microinteractions - インタラクションを視覚的なフィードバックで必ず 100ms 以内に確認できるようにします
• inter-keyboard-navigation - すべてのインタラクティブ要素にキーボードで到達し、操作できるようにします
• inter-drag-drop - ドラッグ操作を提供する場合は、キーボードでアクセスできる代替手段を用意します
• inter-revalidation - 変更処理の後に revalidatePath／revalidateTag を使用します。クライアントの更新に頼ることは決してありません
• inter-row-actions - リストごとに 1 種類の「行アクション」パターン（ケバブメニュー、ホバーアクション、スワイプのいずれか）を使用します
• inter-search - 検索入力を 200～300ms デバウンスし、クエリを URL に反映します

3. アクセシビリティ（重大）

• acc-labels - すべてのインタラクティブ要素に、アクセシブルな名前を設定します
• acc-text-scaling - ブラウザーのズームを200％にしても、すべてのテキストが拡大され、横スクロールが発生しないようにします
• acc-color-contrast - WCAG AA：本文テキストは4.5:1、大きなテキスト／UIは3:1のコントラスト比を確保します
• acc-reduce-motion - prefers-reduced-motion: reduce を尊重します
• acc-color-independent - 意味を伝える際に、色だけに頼らないでください
• acc-focus-management - 常に視認できるフォーカスリングを表示し、モーダル内にフォーカスを閉じ込めます
• acc-relative-units - テキストと間隔には rem を使用し、テキストサイズを px で固定しないでください
• acc-responsive-layout - すべてのレイアウトが、横スクロールなしで幅320 pxに対応するようにします

4. ユーザーフィードバック（高）

• feed-loading-states - 最終レイアウトに合ったスケルトンを使い、必ず loading.tsx または <Suspense> を使用します
• feed-error-states - すべてのルートセグメントに、再試行アクションを備えた error.tsx を用意します
• feed-toasts - トーストは、ブロックを伴わないアクションの確認にのみ使用します
• feed-success-confirmation - 破壊的または取り消せないアクションには、明示的で視認できるフィードバックを必ず表示します
• feed-empty-states - 空の状態では、その理由を説明し、次のアクションを提示します

5. UXパターン（高）

• ux-onboarding - オンボーディングは3画面以内にし、必ずスキップ可能にします
• ux-permissions - ブラウザーの権限はページ読み込み時ではなく、必要な場面でリクエストします
• ux-modality - コンテンツの重要度に応じてダイアログ／ポップオーバー／全画面ページを選び、モーダルを重ねないでください
• ux-destructive-confirmation - 破壊的なアクションには、入力による確認、または取り消し可能な猶予期間が必要です
• ux-data-entry - Server Actionsとプログレッシブエンハンスメントを使用し、入力中に送信を無効化しないでください
• ux-undo - 日常的な操作では、確認より取り消しを優先します
• ux-settings - 設定は変更時に自動保存し、保存ボタンを必須にしないでください

6. ビジュアルデザイン（高）

• vis-dark-mode - CSSカスタムプロパティと dark: バリアントを使用し、text-black／bg-white をハードコードしないでください
• vis-icon-system - lucide-reactを使い、標準サイズには 1.5px の線幅と size-4／size-5 を使用します
• vis-spacing - Tailwind 4のptスケールとコンテナクエリを使用し、場当たり的な px マージンは使わないでください

使用方法

詳しい説明とコード例については、各リファレンスファイルを参照してください。

• セクションの定義 - カテゴリー構成と影響度
• ルールのテンプレート - 新しいルールを追加するためのテンプレート

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリーの定義と順序
assets/templates/_template.md	新しいルール用のテンプレート