tsh-ensuring-accessibility

Ensuring Accessibility

Provides WCAG 2.1 AA compliance patterns for building inclusive frontend interfaces with proper semantic markup, keyboard navigation, focus management, and screen reader support.

Accessibility Implementation Process

Use the checklist below and track your progress:

Progress:
- [ ] Step 1: Choose semantic elements
- [ ] Step 2: Implement keyboard navigation
- [ ] Step 3: Add ARIA where HTML falls short
- [ ] Step 4: Verify color and contrast
- [ ] Step 5: Test with assistive technology

Step 1: Choose semantic elements

Select the correct HTML element for each piece of UI:

• Interactive elements:
  • <button> — actions (submit, toggle, open menu)
  • <a href> — navigation to another page or location
  • <input>, <select>, <textarea> — form data entry
• Landmarks:
  • <header> — page or section header
  • <nav> — navigation region
  • <main> — primary content (one per page)
  • <aside> — tangentially related content
  • <footer> — page or section footer
• Structure:
  • <article> — self-contained composition
  • <section> — thematic grouping (must have a heading)
  • <details> / <summary> — native expand/collapse
• Heading hierarchy:
  • One <h1> per page
  • Logical nesting: h2 → h3 → h4
  • Never skip levels (e.g., h2 → h4)
• Lists:
  • <ul> / <ol> for collections of items
  • <dl> for key-value pairs (definition lists)

If the component library wraps these elements, verify the rendered HTML output matches expectations using browser devtools.

Step 2: Implement keyboard navigation

All interactive elements must be focusable. Native interactive elements (<button>, <a>, <input>) are focusable by default. Custom interactive elements need tabindex="0".

• Tab order must follow visual and logical reading order. Avoid tabindex values greater than 0 — they create unpredictable focus sequences.

• Custom interactive components need explicit keyboard handlers:

  Component	Keyboard behavior
  Button	Enter + Space to activate
  Menu	Arrow keys to navigate items, Escape to close, Enter to select
  Tabs	Left/Right arrows to switch tabs, Tab to leave the tab group
  Dialog / Modal	Tab trapped inside, Escape to close
  Accordion	Enter/Space to expand/collapse, Arrow keys between headers
  Combobox	Arrow keys to navigate options, Enter to select, Escape to close

• Focus visibility — never remove the focus outline (outline: none) without providing a visible replacement. Custom focus styles must have at least 3:1 contrast against adjacent colors.

• Programmatic focus management — move focus when context changes:

  • Modal opens → focus the first focusable element inside
  • Modal closes → return focus to the element that triggered it
  • Route change → focus the new page heading or main content
  • Dynamic content added → focus the new content or announce it via aria-live

Step 3: Add ARIA where HTML falls short

Rule: prefer native HTML semantics. Only add ARIA when HTML cannot express the pattern.

Common patterns requiring ARIA:

• Icon-only buttons: Add aria-label="Close" (or the appropriate action description).
• Expandable sections: aria-expanded="true" or aria-expanded="false" on the trigger element.
• Live updates: aria-live="polite" for non-urgent updates (data refreshed, filter applied). aria-live="assertive" for urgent updates (session expiring, critical error).
• Dialogs: aria-modal="true", aria-labelledby pointing to the dialog title, aria-describedby pointing to the dialog description.
• Form errors:
  • aria-invalid="true" on the invalid field
  • aria-describedby pointing to the error message element
  • Error container with role="alert" or aria-live="assertive" for immediate announcement
• Loading states: Container with role="status" for the loading message (e.g., "Loading results..."). Note: role="status" implicitly sets aria-live="polite" — no need to add both.
• Current page in navigation: aria-current="page" on the active nav link.
• Progress indicators: role="progressbar" with aria-valuenow, aria-valuemin, aria-valuemax.

Never do:

• role="button" on a <div> — use <button> instead
• ARIA that duplicates native semantics (e.g., role="heading" on an <h2>)
• aria-label on non-interactive, non-landmark elements (screen readers may ignore it)

Step 4: Verify color and contrast

Additional rules:

• Never convey information through color alone. Error states need an icon or text label in addition to color. Status indicators need a text label, not just a colored dot.
• Ensure focus indicators meet 3:1 contrast against the background.
• Test both light and dark themes if the application supports them.
• Verify disabled states are visually distinguishable but don't need to meet contrast minimums (WCAG exempts disabled controls).

Step 5: Test with assistive technology

Run through these verification steps:

1. Keyboard walkthrough:

   • Tab through the entire page. Is every interactive element reachable?
   • Is the focus order logical (matches visual layout)?
   • Is focus always visible?
   • Can you dismiss overlays with Escape? Navigate menus with arrows?

2. Screen reader verification:

   • Do headings, landmarks, buttons, links, and form fields announce correctly?
   • Are images described (alt text) or hidden (alt="" for decorative)?
   • Do dynamic changes announce via live regions?
   • Do form errors announce when they appear?

3. Zoom and reflow:

   • At 200% zoom, is text resizable without loss of content or functionality? (SC 1.4.4)
   • At 400% zoom (320px viewport width), does content reflow without horizontal scrolling? (SC 1.4.10)
   • Are touch targets generously sized? (44×44 CSS pixels recommended as best practice — not a WCAG 2.1 AA requirement)

4. Accessibility tree inspection:

   • Open browser devtools → Accessibility tab.
   • Verify the semantic structure matches the intended component roles.
   • Check that ARIA attributes are correctly applied and not conflicting.

5. Automated accessibility testing (agent-actionable):

   • Run axe-core CLI against the page: npx @axe-core/cli <URL>.
   • If the URL is not known, ask the user for the URL before running.
   • Parse the output and group violations by impact level (critical, serious, moderate, minor).
   • For each violation, report: rule ID, impact, affected elements, and recommended fix.
   • Re-run after fixes to confirm violations are resolved.

ARIA Usage Quick Reference

Contrast Requirements

Accessibility Checklist

Accessibility:
- [ ] Semantic HTML elements used (button, nav, main, etc.)
- [ ] One h1 per page, logical heading hierarchy (no skipped levels)
- [ ] All interactive elements keyboard-navigable
- [ ] Focus visible on every interactive element
- [ ] Tab order follows visual/logical layout
- [ ] Modal/dialog traps focus and returns on close
- [ ] Icon-only buttons have aria-label
- [ ] Form fields have visible labels (not placeholder-only)
- [ ] Form errors announced to screen readers (role="alert" or aria-live)
- [ ] Error states use icon/text in addition to color
- [ ] Color contrast meets 4.5:1 (normal text) / 3:1 (large text)
- [ ] ARIA landmarks present (header, main, nav, footer)
- [ ] Text resizable to 200% without loss of content (SC 1.4.4)
- [ ] Content reflows at 400% zoom / 320px width without horizontal scroll (SC 1.4.10)

RTL / Bidirectional Text Support

Connected Skills

• tsh-implementing-frontend — for component composition patterns that support accessible structure
• tsh-implementing-forms — for accessible form field patterns, labels, and error announcements
• tsh-reviewing-frontend — for accessibility spot-checks during code review
• tsh-optimizing-frontend — for performance optimizations that also impact accessibility (loading speed, interaction responsiveness)