web-design-guidelines

Web Interface Guidelines

読み込むタイミング

• トリガー：UI 監査、アクセシビリティチェック、レスポンシブデザインレビュー、UX のベストプラクティス評価
• スキップ：UI コンポーネントを含まないバックエンドのみの作業

Web インターフェースをレビューするための自己完結型ガイドラインです。UI コードを監査する際に、これらのルールを適用してください。

出力形式

次の形式で問題を報告してください：file:line — [RULE_ID] description

例：src/Button.tsx:12 — [A11Y-01] アイコンボタンに aria-label がありません

1. アクセシビリティ（A11Y）

A11Y-01：セマンティック HTML

• アクションには <button>、ナビゲーションには <a>、データ入力には <input> を使用します
• インタラクティブ要素に <div onClick> や <span onClick> を使用しないでください
• ランドマークには <nav>、<main>、<aside>、<header>、<footer> を使用します

A11Y-02：ARIA ラベル

• すべてのインタラクティブ要素に、アクセシブルな名前を設定する必要があります
• アイコンのみのボタンには、必ず aria-label を設定します
• フォーム入力には、対応する <label> または aria-label を設定する必要があります
• 画像には alt テキストが必要です（装飾画像の場合は alt=""）

A11Y-03：キーボード操作

• すべてのインタラクティブ要素に Tab キーで移動できる必要があります
• カスタムコンポーネントには、適切な role、tabIndex、キーイベントハンドラーが必要です
• フォーカスを視認できるようにします（代替手段なしで outline: none を使用しないでください）
• モーダル／ダイアログではフォーカスをトラップし、閉じたときにフォーカスを元の位置に戻す必要があります

A11Y-04：色とコントラスト

• テキストのコントラスト比は最低 4.5:1（大きなテキストは 3:1）にします
• 意味を色だけで伝えないでください（アイコン、テキスト、パターンを追加します）
• 200% のズームでも UI を使用できるようにします

A11Y-05：スクリーンリーダー

• 動的コンテンツの変更には aria-live 領域が必要です
• 読み込み状態には aria-busy="true" を設定します
• エラーメッセージは aria-describedby で入力欄に関連付けます

2. パフォーマンス（PERF）

PERF-01：画像の最適化

• next/image または srcset を使ったレスポンシブ画像を使用します
• レイアウトシフトを防ぐため、width と height を指定します
• ファーストビューより下の画像は遅延読み込みします：loading="lazy"
• フォールバックを用意したうえで WebP／AVIF を使用します

PERF-02：バンドルサイズ

• バレルインポートは使用しません：import { Button } from 'lib' ではなく import Button from 'lib/Button' を使用します（または optimizePackageImports を有効にします）
• CSS をツリーシェイクします：CSS モジュール、または Tailwind の content 設定（v3）／自動検出（v4）を使用します
• ルートと大きなコンポーネントは遅延読み込みします：React.lazy() または動的インポートを使用します

PERF-03：レンダリング

• レイアウトスラッシングを避けます：ループ内で DOM の読み取りと書き込みを繰り返さないでください
• will-change は必要な場合に限って使用します（アニメーションが明確に分かっている場合のみ）
• JS アニメーションより CSS アニメーションを優先します
• 60fps のアニメーションには transform と opacity を使用します（コンポジターのみで処理）

PERF-04：Core Web Vitals

• LCP < 2.5s：最大の画像／テキストを最適化し、重要なリソースをプリロードします
• INP < 200ms：メインスレッドで長時間タスクを実行せず、重要でない JS は後回しにします
• CLS < 0.1：画像／埋め込みコンテンツに寸法を指定し、ファーストビューより上にコンテンツを挿入しないようにします

3. レスポンシブデザイン（RD）

RD-01：モバイルファースト

• モバイル向けの基本スタイルを設定し、その後 @media (min-width) で大きな画面向けのスタイルを追加します
• タッチターゲットは最小 44x44px にします
• どのビューポートでも横スクロールが発生しないようにします

RD-02：流動的なレイアウト

• タイポグラフィには px ではなく rem／em を使用します
• 流動的なタイポグラフィには clamp() を使用します：font-size: clamp(1rem, 2.5vw, 2rem)
• 固定幅より Flex／Grid を優先します
• コンテンツの最大幅は、読みやすさを考慮して max-width: 65ch にします

RD-03：ブレークポイント

• デバイスではなく、コンテンツに応じたブレークポイントを設定します
• 一般的な設定：640px（sm）、768px（md）、1024px（lg）、1280px（xl）
• 320px、375px、768px、1024px、1440px、1920px でテストします

4. コンポーネントのパターン（CP）

CP-01：フォーム

• 入力欄の横にインラインでバリデーションエラーを表示します
• モバイルキーボード向けに type="email"、type="tel"、inputmode="numeric" を使用します
• 送信中は送信ボタンを無効にします（二重送信を防止）
• エラー時もフォームの状態を保持します（入力欄をクリアしないでください）

CP-02：読み込み状態

• コンテンツ領域ではスピナーよりスケルトン画面を表示します
• 時間のかかる処理では進行状況を示します（スピナーよりプログレスバーを優先）
• 読み込み中はインタラクティブ要素を無効にします
• 読み込み中のコンテナには aria-busy="true" を設定します

CP-03: エラー状態

• 実行可能なエラーメッセージを必ず表示します（単に「エラー」と表示するのではなく、「再試行」ボタンを用意します）
• 技術的なエラーをユーザーに表示しないでください（内部でログに記録し、わかりやすいメッセージを表示します）
• React コンポーネントツリーにエラーバウンダリーを設定します
• ネットワーク障害に対する再試行ロジックを実装します

CP-04: 空の状態

• 空白のページを表示せず、役立つ空の状態を用意します
• 行動を促すメッセージを含めます：「まだ項目がありません。最初の項目を作成してください。」
• イラストは控えめに使用します（バンドルサイズが増加します）

CP-05: モーダルとダイアログ

• <dialog> 要素、または適切な role="dialog" を使用します
• モーダル内にフォーカスを閉じ込めます
• Escape キーと背景のクリックで閉じるようにします
• 閉じたときに、トリガー要素へフォーカスを戻します
• 開いている間は body のスクロールを防ぎます

5. CSS のプラクティス（CSS）

CSS-01: 詳細度

• ID セレクターや要素セレクターよりもクラスセレクターを優先します
• !important は避けます（詳細度またはカスケードレイヤーを使用します）
• テーマ設定には CSS カスタムプロパティを使用します
• 余白の方向を統一します。margin-top よりも margin-bottom を優先します

CSS-02: レイアウト

• 1 次元レイアウトには Flexbox、2 次元レイアウトには Grid を使用します
• レイアウトには position: absolute を避けます（オーバーレイにのみ使用します）
• Flexbox や Grid の子要素間の余白には、マージンよりも gap を使用します
• 高さ全体を使うレイアウトには、100vh ではなく min-height: 100dvh を使用します

CSS-03: ダークモード

• prefers-color-scheme メディアクエリーを使用します
• すべての色を CSS カスタムプロパティとして定義します
• 両方のモードをテストし、どちらもコントラストを確認します
• 色を単純に反転するのではなく、ダークモード向けに意図的にデザインします

6. セキュリティ（SEC）

SEC-01: コンテンツセキュリティ

• サニタイズせずに dangerouslySetInnerHTML を使用しないでください
• ユーザー生成コンテンツは、レンダリング前にサニタイズします
• target="_blank" を指定した外部リンクには rel="noopener noreferrer" を使用します

SEC-02: フォームと入力

• すべてのフォームで CSRF 対策を行います
• フォーム送信をレート制限します
• クライアントとサーバーの両方で検証します

7. 国際化（I18N）

I18N-01: テキスト

• 文字列をハードコードせず、i18n ライブラリまたは定数を使用します
• RTL レイアウトに対応します。logical properties を使用し（margin-left よりも margin-inline-start を優先します）
• テキストを切り詰めないでください。デザインはテキストが 40% 増えることを想定する必要があります
• <html> タグに lang 属性を使用します

レビューチェックリスト

ファイルを監査する際は、次の順序（最初に CRITICAL）で確認します。

1. CRITICAL：A11Y-01、A11Y-02、SEC-01 — セマンティック HTML、ARIA、XSS 対策
2. HIGH：PERF-04、A11Y-03、CP-01 — Core Web Vitals、キーボード操作、フォーム
3. MEDIUM：RD-01、CSS-02、CP-02、CP-03 — レスポンシブ対応、レイアウト、読み込み／エラー
4. LOW：CSS-03、I18N-01、CP-04 — ダークモード、i18n、空の状態