Accessibility

Web Accessibility

Apply W3C Web Accessibility Initiative (WAI) principles when working on web interfaces to ensure usability for people with disabilities.

When to Activate

Use this skill when:

• Designing or implementing user interfaces
• Reviewing code for accessibility compliance
• Creating or editing web content (HTML, CSS, JavaScript)
• Working with forms, navigation, multimedia, or interactive components
• Conducting code reviews with accessibility considerations
• Refactoring existing interfaces for better accessibility

Core Principles (POUR)

Web accessibility is organized around four foundational principles:

1. Perceivable

Information must be presentable to users in ways they can perceive.

Key requirements:

• Provide text alternatives for non-text content (images, icons, charts)
• Provide captions and transcripts for multimedia
• Create content that can be presented in different ways (responsive, reflow)
• Make content distinguishable (color contrast, text sizing, audio control)

Quick example:

2. Operable

User interface components must be operable by all users.

Key requirements:

• Make all functionality keyboard accessible
• Provide sufficient time for users to complete tasks
• Avoid content that causes seizures (no rapid flashing)
• Help users navigate and find content
• Support various input modalities (touch, voice, keyboard)

Quick example:

Click me  

  Custom Button

3. Understandable

Information and UI operation must be understandable.

Key requirements:

• Make text readable and understandable
• Make web pages appear and operate predictably
• Help users avoid and correct mistakes
• Provide clear labels and instructions

Quick example:

Email address

We'll never share your email

4. Robust

Content must work reliably across user agents and assistive technologies.

Key requirements:

• Use valid, well-formed markup
• Ensure compatibility with assistive technologies
• Use ARIA correctly for custom components
• Follow semantic HTML practices

Quick example:

  
    Home
  

  Dialog Title

Common Tasks

Making Forms Accessible

• Associate every label with its input (for/id or wrapping ``)
• Identify errors in text and link the message to the failing control
• Indicate required fields in the label, not by color alone
• Pair validation with specific correction guidance

Implementing ARIA

• Use semantic HTML first; add ARIA only when no native element fits
• Keep ARIA states (aria-expanded, aria-selected) in sync with component state
• Announce dynamic content with live regions (aria-live, role="status")
• Follow the ARIA Authoring Practices patterns (linked under Resources) for tabs, accordions, modals, dropdown menus, and skip links

Testing for Accessibility

• Navigate the full interface with keyboard only (Tab, Shift+Tab, Enter, Space, arrows)
• Test with a screen reader (VoiceOver, NVDA, or JAWS)
• Run automated checkers (axe, Lighthouse, WAVE) as a first pass, not a substitute for manual testing
• Check color contrast against the 4.5:1 text and 3:1 UI-component minimums

Quick Reference Checklist

Every page should have:

• [ ] Valid HTML structure
• [ ] Unique, descriptive page title
• [ ] Proper heading hierarchy (h1, h2, h3...)
• [ ] Language attribute on ``
• [ ] Sufficient color contrast (4.5:1 minimum)
• [ ] Keyboard accessibility for all interactive elements
• [ ] Visible focus indicators
• [ ] Text alternatives for images
• [ ] Form labels associated with inputs
• [ ] Semantic landmark regions

For interactive components:

• [ ] Keyboard accessible (Tab, Enter, Space, Arrow keys)
• [ ] Proper ARIA roles, states, and properties
• [ ] Focus management (modals, dynamic content)
• [ ] Descriptive labels and instructions
• [ ] Error messages linked to form controls

Key Principles

• Semantic HTML first: Use native HTML elements before adding ARIA
• Keyboard accessibility is fundamental: If it works with mouse, it must work with keyboard
• Test with actual users: Include people with disabilities in testing
• Color is not enough: Never use color alone to convey information
• Provide alternatives: Text for images, captions for video, transcripts for audio
• Make it predictable: Consistent navigation and behavior across pages
• Help users recover: Clear error messages with suggestions for correction

Resources

• WCAG 2.1 Guidelines: https://www.w3.org/WAI/WCAG21/quickref/
• ARIA Authoring Practices: https://www.w3.org/WAI/ARIA/apg/
• WebAIM: https://webaim.org/
• MDN Accessibility: https://developer.mozilla.org/en-US/docs/Web/Accessibility

Source & license

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

• Author: vinnie357
• Source: vinnie357/claude-skills
• License: MIT

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