web-accessibility

Web Accessibility

A skill for incorporating a11y into the design and implementation flow, rather than treating it as a retrofitted audit, during product implementation and UI review.

When to Use

• When implementing a new Web UI
• When fixing keyboard / focus / form / ARIA / contrast issues in an existing UI
• When reviewing the behavior of Dialog, navigation, table, toast, validation, etc.
• When you want to review including the framework quirks of React / Next.js, Angular, and Vue
• When you receive a request like "I want you to look at it from an a11y perspective before merge"

Not the Best Fit

• Changes centered on extension host / CLI that are not Web UI
• Cases that have already been reproduced in the browser, where the main purpose is collecting runtime evidence and verification
  • In that case, prioritize a runtime verification agent such as Accessibility Runtime Tester
• Accessibility improvements for Markdown documents only

Operating Principles

• Native HTML first. div role="button" than <button> prioritize
• Severity first. CRITICAL after eliminating IMPORTANT, and finally SUGGESTION look at
• Keyboard first. A UI that has only been checked with a mouse is considered incomplete
• Make name / role / state clear. It is not enough for meaning to be conveyed by appearance alone
• To make it easy to go back and forth between review and fix, bundle findings by component and by flow

Workflow

1. Scope the surface Check the target page / flow / component, main tasks, input methods, and user constraints.
2. Hit the blocking issues first Prioritize semantics, keyboard, focus, label, error identification, and accessible name.
3. Check the UI pattern Check requirements for each pattern such as form, dialog, navigation, table, media, and notification.
4. Apply framework-safe fixes Fix fragile areas in React / Next.js, Angular, and Vue according to the framework's conventions.
5. Re-check responsive and visual access Review contrast, 320px reflow, reduced motion, and color-only signaling.
6. Close with a verification note Briefly leave notes on what was fixed, unverified runtime risks, and remaining items.

Decision Points

• If it can be solved with native elements, do not add ARIA
• If you want confirmed focus trap, route announce, and hover/focus popup behavior in the browser, switch to runtime verification
• For a quick review request, review checklist run first
• If you are implementing, common UI failures first eliminate defects that are easy to fix

Escalation Paths

• If a deep design review or a broad inventory from a WCAG perspective is needed,WCAG priority map conduct the inventory criterion by criterion based on
• Do not finalize keyboard flow, dialog, focus return, or live region in a static review; operate them in a real browser and leave evidence (operation steps, screenshots, screen reader results)
• The readability of Markdown documents and document a11y on GitHub are outside the scope of this skill

Expected Output

• List the main blocking issues in order of severity
• When fixing, fix them together by component / flow
• Do not treat unverified runtime behavior as "complete by guesswork"; state it explicitly
• When real-browser confirmation is needed, also include possible static guards and a checklist

Reference Map

• Priority and legal baseline: references/wcag-priority-map.md
• Common defects and fixes: references/common-ui-failures.md
• Framework notes: references/framework-patterns.md
• Final pass checklist: references/review-checklist.md

Done Criteria

• The main flow can be operated with keyboard alone
• Focus is visible and returns properly from closed dialogs and overlays
• Interactive element has an accessible name / role / state
• Form labels, required, error, and status messages are associated
• No oversights in contrast, reflow, color-only signaling, or motion
• Checked for framework-specific a11y regressions
• Any unverified runtime behavior was made explicit