web-design-guidelines

⚠️ パフォーマンスに関する注意：この Skill には WCAG 2.2 の完全なチェックリストが含まれています。簡易レビューでは「クイックチェックリスト」のみを使用し、完全な監査では「詳細チェックリスト」を使用してください。

---

Web インターフェースガイドラインとアクセシビリティチェッカー

概要

この Skill では、2 種類のレビューを実施できます。

1. クイックレビュー：Vercel Web Interface Guidelines に基づく即時チェック
2. 完全監査：WCAG 2.2 AA 基準に基づく包括的な適合性チェック

---

クイックレビュー（Web Interface Guidelines）

ワークフロー

1. ソース URL から最新のガイドラインを取得します：

   https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
   

2. 指定されたファイルを読み込みます（または、ファイル／パターンの指定をユーザーに求めます）

3. 取得したルールに照らしてチェックします

4. 簡潔な file:line 形式で結果を出力します

使用方法

ユーザーがファイルまたはパターンのパラメーターを指定した場合：

1. 上記の URL からガイドラインを取得します
2. 指定されたファイルを読み込みます
3. すべてのルールを適用します
4. ガイドラインで指定された形式に従って結果を出力します

ファイルが指定されていない場合は、どのファイルをレビューするかユーザーに尋ねます。

---

完全監査（WCAG 2.2 AA）

WCAG 2.2 で追加された達成基準

WCAG 2.2 では、2.1 を基に 9 つの新しい達成基準が追加されています。

2.4.11 フォーカスの外観（最小）（Focus Appearance (Minimum)）- AA

要件：フォーカスインジケーターは、以下のすべての条件を満たす必要があります。

• コントラスト比：少なくとも 3:1（フォーカスと隣接する色の間）
• 面積：インジケーターの面積が、1 CSS ピクセル幅の輪の面積以上
• 他のコンテンツに隠されていない

チェックポイント：

• すべてのインタラクティブ要素（リンク、ボタン、入力欄）に、視認できるフォーカス状態がある
• フォーカスインジケーターのコントラスト比が 3:1 以上
• フォーカススタイルが他のコンテンツに隠されない

/* ✅ 合规的焦点样式 */
:focus {
  outline: 2px solid #005fcc;
  outline-offset: 2px;
}

/* ✅ 高对比度焦点 */
:focus {
  outline: 3px solid #000000;
  background: #ffff00;
}

2.4.12 フォーカスが隠されない（Focus Not Obscured）（最小）- AA

要件：フォーカスインジケーターが他のコンテンツに完全に隠されてはなりません

チェックポイント：

• 固定要素（header、nav）がフォーカスを隠さない
• モーダルを開いたときにフォーカス対象の要素が見える
• スクロール時にフォーカス対象の要素がビューポート内に維持される

2.5.7 ドラッグ操作（Dragging Movements）- AA

要件：ドラッグ操作を使用するすべての機能に、単一ポインターで操作できる代替手段を提供する必要があります

チェックポイント：

• スライダーにドラッグの代わりとなる +/- ボタンがある
• ドラッグ＆ドロップリストにドラッグの代わりとなる上／下ボタンがある
• ドラッグ操作に明確な視覚的フィードバックがある

// ❌ 不合规：只有拖动
<SortableList items={items} />

// ✅ 合规：提供替代方案
<SortableList items={items} />
<SortableList items={items} mode="buttons" />

2.5.8 ターゲットサイズ（最小）（Target Size (Minimum)）- AA

要件：タッチターゲットは少なくとも 24x24 CSS ピクセルである必要があります

チェックポイント：

• ボタンの最小サイズが 24x24px
• モバイルのタッチターゲットが 44x44px 以上（WCAG 2.2 AAA）
• ターゲット間に十分な間隔がある

/* ✅ 合规的触摸目标 */
button {
  min-height: 44px;
  min-width: 44px;
  padding: 12px 16px;
}

---

詳細な WCAG 2.2 AA チェックリスト

1. 知覚可能（Perceivable）

1.1.1 非テキストコンテンツ - すべてのテキスト

• すべての画像に alt テキストがある
• 複雑な画像に長い説明がある
• アイコンボタンに aria-label がある
• フォームに視認できるラベルがある

<img src="chart.png" alt="2024年用户增长图表，显示同比增长25%" />


<img src="chart.png" />

1.3.1 情報および関係性

• セマンティックな HTML 構造になっている
• 見出しの階層が正しい（h1 → h2 → h3）
• フォームが正しい label と関連付けられている
• リストに ul/ol を使用している

<label for="email">邮箱地址</label>
<input type="email" id="email" name="email" />


<span>邮箱地址</span>
<input type="email" aria-label="邮箱" />

1.4.3 コントラスト（最小）

テキストのコントラスト要件：

• 通常のテキスト：4.5:1
• 大きなテキスト（18px 以上、または 14px bold）：3:1
• UI コンポーネントと図形オブジェクト：3:1

チェックツール：

• Chrome DevTools > Lighthouse
• WebAIM Contrast Checker -axe DevTools

/* ✅ 合规 */
.text-primary {
  color: #1a1a1a; /* 对比度 16:1 on #ffffff */
}

.text-secondary {
  color: #5c5c5c; /* 对比度 7:1 on #ffffff */
}

1.4.4 テキストのサイズ変更

• 情報を失うことなく、テキストを 200% まで拡大できる
• 固定単位（px）ではなく相対単位（rem, em）を使用している
• text-size-adjust による制限を避けている

/* ✅ 合规 */
body {
  font-size: 1rem; /* = 16px default */
  line-height: 1.5;
}

h1 {
  font-size: 2rem; /* = 32px */
}

1.4.11 非テキストのコントラスト

UI コンポーネントのコントラスト要件：

• 枠線：3:1
• フォーカスインジケーター：3:1
• 塗りつぶし領域：3:1

/* ✅ 合规 */
.input {
  border: 1px solid #767676; /* 对比度 4.5:1 */
  background: #ffffff;
}

.input:focus {
  border-color: #005fcc; /* 对比度 4.7:1 */
}

1.4.12 テキストの間隔

コンテンツを 200% に拡大しても情報が失われないこと：

• 文字間隔が 0.12em 以上
• 単語間隔が 0.16em 以上
• 行の高さが 1.5 以上

/* ✅ 合规 */
p {
  letter-spacing: 0.12em;
  word-spacing: 0.16em;
  line-height: 1.5;
}

1.4.13 ホバー時のコンテンツ（Content Hover on Hover）

• ホバー可能なコンテンツを閉じられる
• 正確な位置指定を必要とせず、ホバーで表示できる
• ユーザーがホバー状態を起動できる

---

2. 操作可能（Operable）

2.1.1 キーボード

すべての機能をキーボードで操作できること：

• すべてのインタラクティブ要素に Tab でアクセスできる
• フォーカス順序が論理的である
• カスタムコンポーネントがキーボード操作に対応している

テスト方法：

1. マウスを外します
2. Tab、Enter、Space、矢印キーだけで操作します
3. すべての機能が使用できることを確認します

// ✅ 合规的键盘支持
<div
  role="button"
  tabIndex={0}
  onClick={handleClick}
  onKeyDown={(e) => {
    if (e.key === 'Enter' || e.key === ' ') {
      e.preventDefault();
      handleClick();
    }
  }}
>
  点击我
</div>

2.1.2 キーボードトラップなし

• Tab キーですべての領域を自由に移動できる
• Escape キーでモーダル／ドロップダウンメニューを閉じられる
• 意図しないフォーカスのループがない

2.4.1 ブロックスキップ

• 「メインコンテンツへ移動」リンクを提供している
• スキップリンクがフォーカス時に表示される

<a href="#main-content" class="skip-link">
  跳转到主要内容
</a>

<main id="main-content">
  
</main>

<style>
.skip-link {
  position: absolute;
  top: -100px;
}
.skip-link:focus {
  top: 0;
}
</style>

2.4.3 フォーカス順序

• フォーカス順序が視覚的および論理的な順序に沿っている
• DOM の順序と視覚的な順序が一致している
• tabindex で順序を調整する際に注意している

2.4.4 リンクの目的（文脈）

• リンクテキストが目的を説明している
• 「こちらをクリック」「続きを読む」を避けている
• 同じページで同じリンク先へのリンクが複数ある場合、テキストが同じである

<a href="/pricing">查看定价方案</a>


<a href="/pricing">点击这里</a>

2.4.6 見出しとラベル

• 見出しがテーマまたは目的を説明している
• ラベルが入力の目的を説明している
• ラベルの代わりにプレースホルダーを使用していない

<label for="search">搜索产品</label>
<input type="search" id="search" placeholder="输入关键词..." />


<input type="search" placeholder="搜索产品" />

2.4.7 フォーカスの可視化

• フォーカスインジケーターが常に見える
• 代替手段がない限り、outline: none を使用していない

2.5.3 名前の中のラベル（Label in Name）

• アクセシブルな名前に可視テキストが含まれている
• アイコンボタンに可視ラベルがある

<button>
  <svg aria-hidden="true"></svg>
  <span>提交</span>
</button>


<button aria-label="提交"></button>

2.5.4 動作による作動（Motion Actuation）

• 特定のジェスチャーに機能が依存していない
• 代替の操作方法を提供している

---

3. 理解可能（Understandable）

3.1.1 ページの言語

• HTML に lang 属性がある
• lang 属性の値が正しい

<html lang="zh-CN">

3.2.1 フォーカス時

• フォーカスの変化によってコンテキストが自動的に変化しない
• 自動的に移動せず、ユーザーが操作して変化させる

<select onchange="this.form.submit()">


<select onchange="confirm('确认选择？') && this.form.submit()">

3.2.2 入力時

• 入力の変更によって自動的に送信されない
• ユーザーが操作して送信する

3.3.1 エラーの特定

• フォーム送信時にエラーを特定する
• エラーがテキストで説明されている
• エラーが具体的なフィールドを示している

<label for="email">邮箱</label>
<input type="email" id="email" aria-describedby="email-error" />
<span id="email-error" role="alert">
  请输入有效的邮箱地址
</span>


<input type="email" aria-invalid="true" />

3.3.2 ラベルまたは説明

• 入力に説明がある場合、その説明が入力と関連付けられている
• aria-describedby を使用している

<label for="username">用户名</label>
<p id="username-hint">4-20个字符，可包含字母数字下划线</p>
<input id="username" aria-describedby="username-hint" />

---

4. 堅牢性（Robust）

4.1.1 構文解析

• HTML が有効で、ID が重複していない
• 検証ツールを使用してチェックする

4.1.2 名前、役割、値

• UI コンポーネントに正しい名前、役割、値がある
• カスタム ARIA ではなく、ネイティブ HTML 要素を使用している

<button>提交</button>


<div onclick="submit()">提交</div>

4.1.3 ステータスメッセージ

• 状態の変化がテキストで通知される
• aria-live 領域を使用している

<div aria-live="polite" aria-atomic="true">
  {statusMessage}
</div>

---

クイックチェックリスト（日常利用）

必須項目（必ず合格すること）

• すべての画像に alt テキストがある
• すべてのフォーム入力にラベルがある
• 色のコントラスト比が 4.5:1 以上
• すべての機能にキーボードでアクセスできる
• フォーカスインジケーターが見える
• リンクテキストが目的を説明している

推奨項目（強く推奨）

• ナビゲーションをスキップするリンクがある
• 見出しの階層が正しい
• エラーメッセージに説明がある
• ターゲットサイズが 44px 以上
• prefers-reduced-motion に対応している

---

推奨テストツール

自動化ツール

• axe DevTools：ブラウザー拡張機能。アクセシビリティの問題をリアルタイムで検出します
• Lighthouse：Chrome DevTools に組み込まれており、監査レポートを生成します
• WAVE：WebAIM が開発。問題を視覚的に表示します
• Accessibility Insights：Microsoft が開発。詳細なチェックを実施します

手动测试

• 键盘测试：拔掉鼠标，只用键盘操作
• 屏幕阅读器测试：NVDA (Windows)、VoiceOver (macOS)
• 缩放测试：放大至 200% 检查布局

---

修复优先级

P0 - 立即修复

• 关键功能键盘不可用
• 主要内容无 alt 文本
• 对比度严重不足
• 表单错误无法识别

P1 - 尽快修复

• 焦点指示符不明显
• 链接文本不明确
• 标题层级混乱
• 目标大小过小

P2 - 计划修复

• 增强色盲支持
• 优化移动端体验
• 添加更多说明文本
• 优化动画体验

---

报告模板

# 可访问性审计报告

## 概述
- **审计日期**: YYYY-MM-DD
- **审计范围**: [页面/组件/功能]
- **符合标准**: WCAG 2.2 AA

## 发现问题

### P0 - 立即修复
| 问题 | 位置 | 影响 | 建议修复 |
|------|------|------|---------|
| ... | ... | ... | ... |

### P1 - 尽快修复
| 问题 | 位置 | 影响 | 建议修复 |
|------|------|------|---------|
| ... | ... | ... | ... |

### P2 - 计划修复
| 问题 | 位置 | 影响 | 建议修复 |
|------|------|------|---------|
| ... | ... | ... | ... |

## 通过项目
- [ ] 列表
- [ ] 通过
- [ ] 的项目

## 建议
1. ...
2. ...
3. ...

## 参考资料
- [WCAG 2.2 官方文档](https://www.w3.org/TR/WCAG22/)
- [WebAIM 对比度检查](https://webaim.org/resources/contrastchecker/)
- [axe DevTools](https://www.deque.com/axe/)

---

相关 Skill

• FrontendImplementation：设计时避免可访问性问题
• ReactBestPractices：React 组件的无障碍实现
• Security Specialist：包含安全相关的可访问性要求