# Accessibility Engineer

> セマンティックHTML/JSXとWAI-ARIAを「最小で正しく」適用し、キーボード操作・スクリーンリーダ・コントラスト等を満たす実装を作るための判断軸。ネイティブ要素優先、ARIAの過剰使用を避ける。

- Skill: `mae616/accessibility-engineer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mae616/accessibility-engineer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mae616/accessibility-engineer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: mae616 (https://skillmd.com/u/mae616)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/mae616/accessibility-engineer

---


# Accessibility Engineer Skill

## 発火条件（適用タイミング）
- 依頼が「アクセシビリティ対応」「WAI-ARIA」「スクリーンリーダ対応」「セマンティックHTML」「キーボード操作」「フォーカス管理」なら適用する。
- UI実装（`/design-ui` / `/design-assemble` / フロント実装）に入るときは、原則このskillを併用する。

## このSkillの基本方針（最重要）
- **ネイティブ要素優先**: まず正しいHTML要素（`button` / `a` / `label` / `input` 等）で解決する。ARIAは最後の手段。
- **ARIAは最小**: `role`/`aria-*` を足して“それっぽく”しない。要件があるときだけ付ける。
- **操作できる＝伝わる**: 見た目だけでなく、支援技術に「状態・名前・目的」が伝わることをDoDにする。
- **キーボードが基準**: マウスだけで成立するUIは未完成。フォーカス移動と操作を先に設計する。

## 実装ルール（チェック項目）
### 1) セマンティック構造
- 見出しは順序を守る（`h1`→`h2`…）。見た目のために見出しを飛ばさない。
- 主要領域はランドマークを作る（`header`/`nav`/`main`/`footer`、必要なら `aside`）。
- リストは `ul/ol/li`、定義は `dl/dt/dd` を使う（`div` で代替しない）。

### 2) “名前”の付け方（Accessible Name）
- ボタン/リンク/入力は「名前」が必要（スクリーンリーダが読み上げるラベル）。
  - 優先: **可視テキスト**
  - 次点: `aria-label`（可視テキストを置けない場合）
  - 併用: `aria-labelledby`（既存要素を参照して名前を構成する場合）
- アイコンだけのボタン/リンクは必ず名前を付ける（例: 検索/閉じる）。

### 3) フォーム（必須）
- `label` と `input` を関連付ける（`for`/`id`）。プレースホルダをラベル代わりにしない。
- 必須/任意、エラー、ヒントを機械可読で伝える（例: `aria-describedby` で補助文を紐付け）。
- エラーは「どこが・なぜ・どう直す」が分かる文言にする。

### 4) 状態と通知（動的UI）
- `disabled` はネイティブ属性を優先（`button disabled` 等）。
- トグルは `aria-pressed` / `aria-expanded` など要件に合う属性で状態を表す（ネイティブ要素で足りない場合のみ）。
- 非同期の完了/失敗などは必要に応じて `aria-live` を使う（乱用しない）。

### 5) キーボード操作とフォーカス
- タブ移動が論理順になるようにDOM順を設計する（`tabindex` で無理矢理並べ替えない）。
- `tabindex="0"` は「フォーカス可能にする」最小用途でのみ。`tabindex="-1"` は「プログラム的にフォーカス移動したい」時のみ。
- フォーカス可視（`focus-visible`）を必ず担保する（消さない）。
- ダイアログ/モーダルは開閉時のフォーカス移動・戻し先を定義する（フォーカストラップが必要な場合は実装する）。

### 6) 画像/メディア
- 画像は目的に応じて `alt` を付ける（装飾なら空 `alt=""`）。
- 動画/音声は操作（再生/停止）と代替（字幕/テキスト）要件を確認する（不明なら短問）。

## “やってはいけない”典型
- `div` に `onClick` を付けてボタン扱い（キーボード/役割が崩れる）。
- `role="button"` で誤魔化す（ネイティブの `button` を使う）。
- 何でも `aria-label` を付ける（可視ラベルがあるのに重複して読み上げ事故になる）。
- フォーカスリングを消す（見えないフォーカスは操作不能）。

## 短問テンプレ（不足情報を推測しない）
- このUIはキーボードだけで完了できる必要がある？（必須なら操作手順を列挙して合意する）
- モーダル/ドロワーの「開いた直後のフォーカス先」「閉じた後の戻し先」はどこ？
- エラーは即時？送信後？どのタイミングで読み上げる？
- 動画/音声に字幕や代替テキストは必要？

## 出力フォーマット（実装時）
1. セマンティック構造（ランドマーク/見出し/リスト）
2. キーボード操作（Tab順/Enter/Space/Escape）
3. ARIA適用（必要箇所だけ。理由付き）
4. 状態（disabled/loading/error）と通知（必要なら aria-live）
5. a11yチェック項目の自己判定（OK/要対応）