web-design-guidelines

Web Design Guidelines

すべての人が利用できるウェブインターフェースのための、WCAG アクセシビリティ、セマンティック HTML、キーボードナビゲーション、フォーム、パフォーマンスのパターンです。4 つのカテゴリーにわたる 23 のルールを収録しています。コーディングの参考資料と監査モードの両方に対応しています。

メタデータ

• バージョン： 2.1.0
• ルール数： 4 つのカテゴリーにわたる 23 のルール
• ライセンス： MIT

監査方法

ユーザーから「アクセシビリティを監査して」「WCAG 準拠を確認して」「アクセシビリティをレビューして」と依頼された場合は、以下のチェックリストをコードベースに適用してください。

ステップ 1：対象範囲を決定する

• 引数が指定されている場合（$ARGUMENTS）：指定されたファイルまたはコンポーネントのみを監査します
• 引数が指定されていない場合：コードベース内のすべての UI コンポーネントとページを監査します

ステップ 2：技術スタックを検出する

プロジェクト内で次のファイルを確認します：

• .tsx／.jsx ファイル → React
• .vue ファイル → Vue
• .blade.php ファイル → Laravel Blade
• .html ファイル → 静的 HTML

ステップ 3：アクセシビリティチェックリストを実行する

以下の各項目を確認します。それぞれについて、次のいずれかを出力してください：

• PASS — 検証した内容を簡潔に確認します
• FAIL — 正確な file:line、問題の説明、修正の推奨事項を示します
• N/A — チェック項目がこのプロジェクトに該当しない場合

セマンティック HTML と構造

• ページでセマンティック要素（<header>、<main>、<nav>、<footer>、<article>、<section>）を使用している — <div> だらけにしない
• 見出しの階層が順序どおり（h1 → h2 → h3）である — レベルを飛ばさない
• ページごとに <h1> が 1 つある
• ナビゲーションをスキップするためのスキップリンクがある（<a href="#main-content">Skip to content</a>）
• ランドマーク領域が重複している場合、ラベルが付いている（複数の <nav> 要素に aria-label を指定）

キーボードナビゲーション

• すべてのインタラクティブ要素に Tab キーで移動できる
• フォーカス順序が視覚的な順序に従っている（正の値の tabindex を使用しない）
• すべてのフォーカス可能な要素でフォーカスインジケーターが見える（代替手段なしに outline: none で削除しない）
• モーダルダイアログがフォーカスをトラップし、閉じたときにフォーカスを元に戻す
• カスタムコンポーネント（ドロップダウン、タブ、アコーディオン）が想定されるキーボード操作（矢印キー、Escape、Enter）に対応している

画像とメディア

• すべての <img> 要素に alt 属性がある — コンテンツ画像には説明を付け、装飾画像には空（alt=""）を指定する
• 複雑な画像（グラフ、図）に詳細な説明がある
• 動画コンテンツに字幕または文字起こしがある

色とコントラスト

• テキストが WCAG AA のコントラスト比を満たしている（通常のテキストは 4.5:1、大きなテキストは 3:1）
• 情報を色だけで伝えていない（例：エラー状態は赤色だけでなく、アイコンとテキストも使用する）
• UI コンポーネントとフォーカスインジケーターが背景に対して 3:1 のコントラスト比を満たしている

フォーム

• すべての入力欄に対応する <label> がある（プレースホルダーテキストだけにしない）
• 必須フィールドを視覚的な手がかりと aria-required="true" の両方で示している
• エラーメッセージが aria-describedby を通じて入力欄に関連付けられている
• エラーメッセージが role="alert" または aria-live="assertive" を使用し、スクリーンリーダーに通知される
• 入力欄に適切な type 属性を指定している（email、tel、url、number）
• 一般的なフィールド（氏名、メールアドレス、住所、クレジットカード）に autocomplete 属性がある

ARIA とスクリーンリーダー

• アイコンのみのボタンに ARIA ラベルがある（aria-label="Close"）
• 動的コンテンツの更新に aria-live 領域を使用している
• 読み込み状態がスクリーンリーダーに通知される（aria-busy="true"、ステータスメッセージ）
• 装飾要素をスクリーンリーダーから隠している（aria-hidden="true"）

モーションとアニメーション

• prefers-reduced-motion に対応している — アニメーションを無効化または軽減する
• ユーザーが操作できない自動再生の動画や音声がない
• 1 秒間に 3 回を超えて点滅するコンテンツがない

ステップ 4：要約

監査の最後に、次を出力してください：

## Accessibility Audit Summary
- **PASS**: X checks
- **FAIL**: X checks
- **N/A**: X checks
- **WCAG Level**: AA / Partial AA / Below AA
- **Top Priority Fixes**: (list the 3 most impactful FAIL items)

---

適用する場面

次のような場合に、これらのガイドラインを参照してください：

• コードベースのアクセシビリティ監査を実施するとき
• アクセシビリティ（WCAG 準拠）の観点から UI コードをレビューするとき
• フォームやインタラクションを実装するとき
• キーボードナビゲーションが機能することを確認するとき
• ARIA ラベルやライブ領域を追加するとき
• 画像の読み込みとレイアウトの安定性を最適化するとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	接頭辞
1	アクセシビリティ	CRITICAL	a11y-
2	フォーム	HIGH	form-
3	アニメーションとモーション	CRITICAL	motion-
4	パフォーマンスと UX	MEDIUM	perf-

クイックリファレンス

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

• a11y-semantic-html - セマンティックな HTML 要素を使用する
• a11y-heading-hierarchy - 適切な見出し階層を維持する
• a11y-screen-reader - スクリーンリーダーとの互換性を最適化する
• a11y-skip-links - ナビゲーション用のスキップリンクを提供する
• a11y-keyboard-nav - キーボードだけで完全にナビゲーションできるようにする
• a11y-focus-management - キーボードフォーカスを適切に管理する
• a11y-aria-labels - インタラクティブな要素に ARIA ラベルを追加する
• a11y-color-contrast - 十分な色のコントラストを確保する（WCAG AA）
• a11y-alt-text - 画像に意味のある代替テキストを設定する
• a11y-error-messages - エラーメッセージをアクセシブルにする
• a11y-form-labels - ラベルをフォーム入力欄に関連付ける
• a11y-live-regions - 動的なコンテンツをスクリーンリーダーに通知する

2. フォーム（HIGH）

• form-autocomplete - autocomplete 属性を使用する
• form-input-types - 適切な入力タイプを使用する
• form-error-display - フォームのエラーを明確に表示する
• form-validation-ux - ユーザーフレンドリーなバリデーションを設計する
• form-inline-validation - スマートなインラインバリデーションを実装する
• form-multi-step - 効果的なマルチステップフォームを設計する
• form-placeholder-usage - プレースホルダーを適切に使用する
• form-submit-feedback - 送信後のフィードバックを明確に提供する

3. アニメーションとモーション（CRITICAL）

• motion-reduced - prefers-reduced-motion を尊重する（WCAG AAA）

4. パフォーマンスと UX（MEDIUM）

• perf-image-loading - UX を考慮して画像の読み込みを最適化する
• perf-layout-stability - 累積レイアウトシフトを防ぐ

基本ガイドライン

セマンティック HTML

// ❌ Div soup
<div className="header"><div className="nav"><div onClick={handleClick}>Home</div></div></div>

// ✅ Semantic HTML
<header><nav aria-label="Main"><a href="/">Home</a></nav></header>
<main><article><h1>Title</h1><p>Content</p></article></main>

フォームのアクセシビリティ

<label htmlFor="email">Email <span aria-hidden="true">*</span></label>
<input id="email" type="email" required aria-required="true" aria-describedby="email-error" autoComplete="email" />
{error && <p id="email-error" role="alert">{error}</p>}

モーションの軽減

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

使用方法

詳しい説明については、個々のルールファイルを参照してください。

rules/a11y-semantic-html.md
rules/form-autocomplete.md
rules/motion-reduced.md
rules/perf-image-loading.md

参考資料

• WCAG 2.2 クイックリファレンス
• WAI-ARIA 作成者向けプラクティス
• web.dev アクセシビリティ
• MDN アクセシビリティ
• The A11Y Project

コンパイル済みドキュメント全文

すべてのルールを詳しく記載した完全なガイドはこちらです：AGENTS.md