Accessibility

Accessibility Audit

Accessibility isn't a feature - it's a quality bar. If it doesn't work with a keyboard, a screen reader, or low vision, it's broken.

Quick Checks (Do These First)

1. Keyboard Navigation

• [ ] Tab through the entire page - can you reach every interactive element?
• [ ] Tab order follows visual order (no jumping around)
• [ ] Focus indicator is visible on every focused element
• [ ] Escape closes modals/popups and returns focus to trigger
• [ ] Enter/Space activates buttons and links
• [ ] Arrow keys work in menus, tabs, and custom widgets
• [ ] No keyboard traps (can always Tab away from any element)

2. Screen Reader

• [ ] Every image has alt text (or alt="" for decorative images)
• [ ] Form inputs have associated `` elements
• [ ] Buttons and links have descriptive text (not "Click here")
• [ ] Page has a single ``, heading hierarchy doesn't skip levels
• [ ] Dynamic content changes announced (ARIA live regions)
• [ ] Custom components have appropriate ARIA roles and states

3. Visual

• [ ] Text contrast ratio ≥ 4.5:1 (normal text) or ≥ 3:1 (large text)
• [ ] Information not conveyed by color alone (add icons, patterns, text)
• [ ] Text resizable to 200% without loss of content
• [ ] UI functional at 320px width (mobile) without horizontal scroll
• [ ] Animations respect prefers-reduced-motion

Semantic HTML

Use the right element. It gets you keyboard and screen reader support for free.

| Need | Use | NOT | |------|-----|-----| | Navigation | ` | | | Button | | or | | Link (navigate) | | or | | List | / | Divs with bullet characters | | Heading | - | | | Form field | + | | | Table data | + | Divs in a grid layout | | Main content | | ` |

Rule: If you're adding ARIA attributes to make a ` behave like a button, you should just use a `.

ARIA Usage

ARIA is a last resort, not a first choice. Semantic HTML first.

When ARIA Is Needed

• Custom widgets with no HTML equivalent (tabs, combobox, tree view)
• Dynamic content updates (live regions)
• Relationships between elements that markup can't express

Common Patterns

  Tab 1
  Tab 2

Content 1

  Modal Title
  

  
  3 items added to cart

  ⏳ Loading...

Focus Management

| Scenario | Focus Should Go To | |----------|-------------------| | Modal opens | First focusable element inside modal | | Modal closes | Element that triggered the modal | | Item deleted from list | Next item in list (or previous if last) | | Page navigation (SPA) | Page heading or main content | | Error on form submit | First field with an error | | Accordion expands | The expanded content |

Color Contrast

| Element | Minimum Ratio | Check | |---------|--------------|-------| | Normal text (< 18px) | 4.5:1 | Required | | Large text (≥ 18px bold or ≥ 24px) | 3:1 | Required | | UI components (borders, icons) | 3:1 | Required | | Decorative elements | No requirement | - |

Tools: Chrome DevTools (Inspect → color picker shows ratio), axe DevTools extension, WebAIM Contrast Checker.

Testing Tools

| Tool | What It Catches | |------|----------------| | axe DevTools (browser extension) | ~30-40% of WCAG issues automatically | | Lighthouse Accessibility | High-level score + common issues | | Keyboard (manual) | Navigation, focus, traps | | Screen reader (manual) | Content order, announcements, labels | | Zoom to 200% (manual) | Layout issues at larger text sizes |

Automated tools catch < 50% of issues. Manual testing with keyboard + screen reader is required.

Output

[CRITICAL] - [element/page] - [issue] - [WCAG criterion] - [fix]
[SERIOUS]  - [element/page] - [issue] - [WCAG criterion] - [fix]
[MODERATE] - [element/page] - [issue] - [WCAG criterion] - [fix]
[MINOR]    - [element/page] - [issue] - [WCAG criterion] - [fix]

Source & license

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

• Author: pvnarp
• Source: pvnarp/agent-skills
• License: MIT

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