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.

5) Keyboard Operation and Focus

• Design DOM order so tab sequence is logical. Don't force reorder with tabindex.
• tabindex="0": minimal use to make something focusable.
• tabindex="-1": only for programmatic focus movement.
• Always preserve visible focus (focus-visible). Never hide it.
• Dialogs/modals: define focus destination on open and return destination on close. Implement focus trap if needed.

6) Images and Media

• Use alt based on purpose (decorative images get empty alt="").
• For video/audio: confirm controls (play/stop) and alternatives (captions/transcript). Ask if unclear.

Anti-Patterns (Never Do This)

• div with onClick acting as button (breaks keyboard/role).
• Using role="button" as a workaround (use native button).
• Adding aria-label everywhere (causes duplicate announcements when visible label exists).
• Removing focus ring (invisible focus = inoperable).

Clarification Questions (Don't Assume)

• Must this UI be completable with keyboard only? (If yes, enumerate operation steps and agree.)
• For modal/drawer: what gets focus on open? What gets focus on close?
• When are errors announced? Immediately? After submit?
• Does video/audio need captions or text alternatives?

Output Format (For Implementation)

1. Semantic structure (landmarks, headings, lists)
2. Keyboard operation (Tab order, Enter, Space, Escape)
3. ARIA usage (only where needed, with justification)
4. States (disabled/loading/error) and announcements (aria-live if needed)
5. Accessibility checklist self-assessment (OK / needs work)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mae616
• Source: mae616/design-skills
• License: MIT

Install and usage instructions live in the source repository linked above.