accessibility-engineer

Accessibility Engineer Skill

When to Apply

Apply this skill when the request involves:

• Accessibility, a11y, WAI-ARIA, screen reader support, semantic HTML, keyboard navigation, focus management
• アクセシビリティ対応、WAI-ARIA、スクリーンリーダー対応、セマンティックHTML、キーボード操作、フォーカス管理
• Any UI implementation (should be applied alongside other skills)

Core Principles (Most Important)

• Native elements first. Solve with proper HTML elements (button, a, label, input, etc.) before reaching for ARIA.
• ARIA is minimal. Don't add role/aria-* to make things "seem" accessible. Only add when there's a real requirement.
• Operable = Communicable. Not just visually—assistive tech must receive state, name, and purpose. This is the Definition of Done.
• Keyboard is the baseline. Mouse-only UI is incomplete. Design focus movement and operations first.

Implementation Rules

1) Semantic Structure

• Maintain heading order (h1 → h2 → ...). Don't skip levels for styling.
• Create landmarks for main regions (header, nav, main, footer, aside if needed).
• Use ul/ol/li for lists, dl/dt/dd for definitions—not div substitutes.

2) Accessible Names

• Buttons, links, inputs need "names" (labels read by screen readers).
  • Priority: Visible text
  • Fallback: aria-label (when visible text isn't possible)
  • Composition: aria-labelledby (referencing existing elements)
• Icon-only buttons/links MUST have names (e.g., "Search", "Close").

3) Forms (Required)

• Associate label with input (for/id). Never use placeholder as the only label.
• Communicate required/optional, errors, hints machine-readably (e.g., aria-describedby for helper text).
• Errors must explain: what's wrong, why, and how to fix.

4) States and Announcements (Dynamic UI)

• Use native disabled attribute first (button disabled, etc.).
• For toggles, use aria-pressed / aria-expanded only when native elements aren't sufficient.
• Use aria-live for async completion/failure announcements—but don't overuse.