Web Accessibility A11y

Web Accessibility (a11y)

A practical guide to building digital products that work for everyone, regardless of ability.

Accessibility is not an afterthought—it's a foundational design principle. This skill covers the technical standards (WCAG 2.1) and practical patterns for building inclusive web experiences.

Why Accessibility Matters

Legal: WCAG 2.1 compliance is increasingly required (ADA, ATAG, EN 301 549, UK EQA).

Business: ~15% of the global population has a disability. Accessible design benefits everyone (captions help in noisy environments, voice control helps people with mobility issues, clear navigation helps users with cognitive disabilities).

Technical: Accessible patterns are often better for SEO, performance, and maintainability.

---

Core Principles: WCAG 2.1

WCAG (Web Content Accessibility Guidelines) has four principles, abbreviated as POUR:

1. Perceivable

Information must be perceivable—users must be able to see, hear, or otherwise sense it.

Guidelines:

• Text alternatives — Images need alt text
• Captions & transcripts — Audio/video needs text
• Adaptable content — Info not lost when zoomed or reflow
• Distinguishable — Text is readable (4.5:1 contrast, font size ≥12px)

2. Operable

Interfaces must be operable—users must be able to navigate and interact.

Guidelines:

• Keyboard accessible — All functions available via keyboard
• Enough time — Users can pause auto-playing content
• Seizure prevention — No flashing/flickering (3+ times/second)
• Navigable — Clear landmarks, skip links, heading hierarchy

3. Understandable

Content and operation must be understandable.

Guidelines:

• Readable — Clear language, short sentences, defined jargon
• Predictable — Consistent navigation, no surprises
• Input assistance — Form errors are identified and labeled clearly

4. Robust

Code must be robust—compatible with assistive technologies.

Guidelines:

• Valid HTML — Correct use of semantic elements
• ARIA correctly — Only use ARIA when HTML can't do it
• Naming, role, value — Every interactive element has a label (name), is understood (role), and exposes state (value)

---

Semantic HTML: The Foundation

Semantic HTML means using HTML elements for their intended purpose. This is 80% of accessibility.

Correct Element Usage

Don't:

Submit
Page Title
Click me

Do:

Submit
Page Title
Click me

Essential Semantic Elements

| Element | Purpose | Screen Reader Announces | |---------|---------|------------------------| | ` | Clickable action | "Button: [label]" | | | Navigation link | "Link: [label]" | | – | Headings (hierarchy) | "Heading level 1: [text]" | | | Navigation region | "Navigation" | | | Main content region | "Main" | | | Self-contained content | "Article" | | | Thematic grouping | "Region" | | | Sidebar/supplementary | "Complementary" | | , | Page regions | Landmarks | | | Form label (paired to input) | "Label: [text]" | | & | Group related form inputs | "Group: [legend]" | | , , | Lists | "List, X items" | | , , , | Data tables (not layout) | Headers + cells announced | | & ` | Images with captions | "Figure: [caption]" |

Landmark Navigation

Users of screen readers navigate by landmarks (regions). Provide at least:

• One `` — Contains primary content
• One `` — Contains navigation
• Optional `, , `

---

Form Accessibility

Forms are the most common source of accessibility issues.

Labeling

Every input needs a label, associated via for/id:

Email address

Not this:

Placeholder text vanishes when you start typing — users with memory issues won't know what the field was for.

Required Fields

Indicate required fields clearly in label + legend text:

Name *

Error Handling

When validation fails:

1. Announce the error immediately (use aria-live="polite")
2. Identify which field failed
3. Describe the error (not "Invalid" but "Phone number must be 10 digits")
4. Suggest correction

Phone

Phone must be 10 digits, e.g., 415-555-0123

Fieldsets & Legends

Group related inputs (radio buttons, checkboxes) with ` and label with `:

  Select your experience level
   Beginner
   Intermediate
   Expert

---

Keyboard Navigation

All interactive elements must be keyboard accessible. Users without mice rely entirely on keyboard.

Tab Order

Use the natural tab order (HTML source order). If visual order differs from source order, fix the source:

Bad:

Button 2
Button 3
Button 1

Good:

Button 1
Button 2
Button 3

Focus Management

• Never remove focus outline — Users need visual feedback of where they are
• Focus should be visible on all interactive elements (buttons, links, inputs, custom controls)
• Custom focus style must have ≥3px visible area, 3:1 contrast

button:focus-visible {
  outline: 2px solid #2563eb;
  outline-offset: 2px;
}

Keyboard Traps

Avoid situations where keyboard users can't escape using keyboard. Test: Press Tab repeatedly — can you reach every element and move past it?

Example trap:

Open Modal

Fix:

Open Modal

  Close Modal
  
  

Keyboard Shortcuts

If you define custom keyboard shortcuts (Ctrl+S, etc.):

• Avoid single-key shortcuts (break form inputs)
• Allow users to disable or remap shortcuts
• Document all shortcuts in Help

---

ARIA (Accessible Rich Internet Applications)

ARIA adds accessibility information to HTML. Use semantic HTML first; ARIA only when HTML can't do it.

Golden Rules of ARIA

1. No ARIA is better than bad ARIA — Incorrect ARIA breaks things for screen reader users
2. ARIA doesn't change DOM — role="button" on a ` doesn't make it keyboard accessible; still need tabindex="0" and onkeydown`
3. ARIA is for exceptions — 90% of a11y is semantic HTML

Common ARIA Attributes

| Attribute | Use | Example | |-----------|-----|---------| | role="" | Tells AT the element's purpose | ` (only if not semantic element) | | aria-label="" | Visible label missing | × | | aria-labelledby="" | Connect to visible heading | Title | | aria-describedby="" | Additional description | + | | aria-required="true" | Field is required | | | aria-invalid="true" | Field has error | | | aria-expanded="false" | Toggle button state | Menu | | aria-hidden="true" | Hide from AT | → | | aria-live="polite" | Announce content changes | 3 items added` |

When to Use ARIA

Don't use ARIA for:

• Semantic HTML does it already (`, , `, etc.)
• Simple styling or layout (just use CSS)

Do use ARIA for:

• Custom components without semantic HTML (tabs, accordion, tooltip)
• Live regions that update (chat, notifications, search results)
• Hidden/collapsed content state (aria-expanded)
• Relationships between non-adjacent elements (aria-labelledby, aria-describedby)

---

Testing & Validation

Automated Tools (Catch ~30% of issues)

• axe DevTools (browser extension) — Fast, reliable
• WebAIM Contrast Checker — Verify color contrast
• WAVE — Visual accessibility feedback
• Lighthouse (Chrome DevTools) — Performance + accessibility audit

Manual Testing (Required for remaining 70%)

Keyboard-only navigation:

• Unplug your mouse
• Navigate entire site with Tab, Enter, Shift+Tab, Arrow keys
• Identify any keyboard traps or missing focus

Screen reader testing:

• NVDA (Windows, free)
• JAWS (Windows, paid)
• VoiceOver (Mac, free — press Cmd+F5 to enable)
• TalkBack (Android, free)
• Test with real AT — browser extensions don't replicate the experience

Zoom testing:

• Zoom to 200% — text should reflow, no horizontal scroll
• Zoom to 400% — should still be readable

Colorblind testing:

• Simulator: Coblis
• Ensure information conveyed by color also uses icons, text, patterns

Accessibility Audit Checklist

See bundled resources for comprehensive WCAG 2.1 AA checklist.

---

Common Mistakes & Fixes

Missing Alt Text

Problem: Images have no alt text. Fix: Every image needs alt="" (can be empty if decorative, but must be present). Describe content concisely: alt="Coffee cup on wooden table" not alt="image.jpg".

Color-Only Indicators

Problem: Red = error, green = success (no other differentiation). Fix: Add icons, text labels, or patterns alongside color.

No Focus Visible

Problem: outline: none applied globally to remove focus ring. Fix: Never remove focus outline. Customize it: outline: 2px solid blue; outline-offset: 2px.

Inaccessible Modals

Problem: Modal opens; focus stays on background; keyboard user can't close it. Fix: Move focus into modal on open. Trap Tab within modal. Move focus back to trigger on close.

Incorrect Heading Hierarchy

Problem: h1, then h3, skipping h2. Fix: Use sequential hierarchy (h1 → h2 → h3). Users rely on heading structure to navigate.

Placeholder ≠ Label

Problem: Form fields use only placeholder; label removed "for clarity." Fix: Always use ``. Placeholder disappears when user types.

Unlabeled Buttons

Problem: ← or ` (no text). **Fix:** Add visible text or aria-label="Back" / aria-label="Menu"`.

---

Reference Files & Further Reading

Bundled resources:

• wcag-2-1-checklist.md — WCAG AA compliance checklist
• aria-patterns-guide.md — Common ARIA patterns (tabs, accordion, tooltip, etc.)
• keyboard-navigation-guide.md — Keyboard interaction patterns

---

When to Use This Skill

✅ Do use for:

• WCAG compliance review and audit
• Form accessibility design and testing
• Keyboard navigation and focus management
• ARIA attribute selection and implementation
• Alt text strategy for images
• Modal, tooltip, popover, tab panel accessibility
• Color contrast compliance
• Heading hierarchy and landmark review
• Error handling and form validation
• Screen reader testing strategies

❌ Don't use for:

• CSS styling details (see design-fundamentals)
• Framework-specific implementation (see appropriate framework skill)
• Performance optimization (see web-performance-optimization)
• Design system component creation (see design-systems-architecture)

Source & license

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

• Author: plugin87
• Source: plugin87/full-stack-design-skills
• License: MIT

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