Accessibility Patterns

Accessibility Patterns

Build for everyone from the start.

Core Principles (POUR)

| Principle | Meaning | Example | |-----------|---------|---------| | Perceivable | Users can perceive content | Alt text, captions, contrast | | Operable | Users can interact | Keyboard access, enough time | | Understandable | Users can comprehend | Clear language, predictable | | Robust | Works with assistive tech | Valid HTML, ARIA |

---

WCAG Levels

| Level | Description | Target | |-------|-------------|--------| | A | Minimum | Must have | | AA | Standard | Industry standard, legal requirement | | AAA | Enhanced | Nice to have |

Target Level AA for most projects.

---

Semantic HTML

Use the Right Element

| Instead of | Use | |------------|-----| | ` | | | | | | | | | | | | | | | for emphasis | | | for emphasis | ` |

Document Structure

  Descriptive Page Title

  Skip to main content
  
  
    
      
    
  
  
  
    Page Title
    
    
    
      Section
      Subsection
    
  
  
  
    
  
  
  
    
  

Heading Hierarchy

h1 - Page title (one per page)
  h2 - Major sections
    h3 - Subsections
      h4 - Sub-subsections

Never skip levels (h1 → h3)

---

Images & Media

Alt Text

  
  
    Detailed description of the system architecture...
  

  

Alt Text Guidelines

| Image Type | Alt Text Strategy | |------------|-------------------| | Informative | Describe content and function | | Decorative | Empty alt="" | | Functional | Describe the action | | Complex | Brief alt + longer description | | Text in image | Include all text |

Video & Audio

  
  
  

  

Read transcript

---

Forms

Labels

Email address

  Email address
  

  Name *
  (required)

Error Handling

  Please fix the following errors:
  
    Email is required
  

Email

Please enter a valid email address

Form Groups

  Shipping Address
  
  Street
  
  
  City
  

---

Keyboard Navigation

Focus Management

/* Never remove focus outline without replacement */
:focus {
  outline: 2px solid #005fcc;
  outline-offset: 2px;
}

/* Custom focus style */
:focus-visible {
  outline: 3px solid #005fcc;
  outline-offset: 2px;
}

/* Hide outline for mouse users */
:focus:not(:focus-visible) {
  outline: none;
}

Tab Order

First
Second
Third

Custom interactive element

Modal content

Skip Links

Skip to main content

.skip-link {
  position: absolute;
  top: -40px;
  left: 0;
  padding: 8px;
  background: #000;
  color: #fff;
  z-index: 100;
}

.skip-link:focus {
  top: 0;
}

Keyboard Patterns

| Component | Keys | |-----------|------| | Buttons | Enter, Space | | Links | Enter | | Menus | Arrows, Enter, Escape | | Tabs | Arrows, Tab | | Modals | Tab (trapped), Escape to close |

---

ARIA

When to Use ARIA

1. First, use semantic HTML
2. Then, add ARIA if needed
3. "No ARIA is better than bad ARIA"

Common ARIA Patterns

Content updates will be announced
Urgent updates interrupt

Menu
...

  Home
  About

Loading...

👍

×
...

  Section Title

ARIA Roles

Header
Nav
Main
Sidebar
Footer

Custom button
Modal
Tabs
Error message

---

Color & Contrast

Contrast Requirements

| Text Size | Level AA | Level AAA | |-----------|----------|-----------| | Normal text (Error

⚠️ Error: Please enter a valid email

### Testing Tools

- WebAIM Contrast Checker
- Chrome DevTools color picker
- Stark (Figma plugin)
- axe DevTools

---

## Testing

### Automated Testing

```javascript
// Using jest-axe
import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

it('should have no accessibility violations', async () => {
  const { container } = render();
  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

Manual Testing Checklist

• [ ] Navigate entire page with keyboard only
• [ ] Test with screen reader (VoiceOver, NVDA)
• [ ] Check color contrast
• [ ] Zoom to 200% - still usable?
• [ ] Disable CSS - still understandable?
• [ ] Check all images have alt text
• [ ] Verify form labels and errors
• [ ] Test focus visibility
• [ ] Check heading structure

Screen Reader Testing

| OS | Screen Reader | Browser | |----|---------------|---------| | macOS | VoiceOver | Safari | | Windows | NVDA | Firefox | | Windows | JAWS | Chrome | | Mobile | TalkBack | Chrome | | iOS | VoiceOver | Safari |

---

Common Patterns

Modal Dialog

  Confirm Action
  Are you sure you want to proceed?
  
  Cancel
  Confirm

Focus management:

1. Move focus to modal on open
2. Trap focus inside modal
3. Return focus to trigger on close

Tabs

  
    General
  
  
    Security
  

  General settings content

  Security settings content

---

References

• references/wcag-checklist.md - Full WCAG 2.1 checklist
• references/aria-patterns.md - Common ARIA patterns
• references/testing-tools.md - Testing tool setup

Source & license

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

• Author: organvm
• Source: organvm/a-i--skills
• License: Apache-2.0
• Homepage: https://organvm.github.io/a-i--skills/

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