tsh-ensuring-accessibility

name	tsh-ensuring-accessibility
description	WCAG 2.1 AA compliance, semantic HTML, ARIA patterns, keyboard navigation, focus management, screen reader support, and color contrast requirements. Use when implementing accessible components, auditing UI for accessibility issues, reviewing frontend code for a11y compliance, or building inclusive forms and interactive widgets.
user-invocable	false

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.

Start with the correct HTML element. `` for actions, `` for navigation, `` for navigation regions, `` for primary content. Native semantics are free, reliable, and require zero ARIA. Only reach for ARIA when HTML alone cannot convey the meaning. Every interaction available to a mouse user must be available to a keyboard user. Tab, Escape, Enter, Space, Arrow keys — these are the vocabulary of keyboard interaction. Missing keyboard support is not a minor issue — it is a blocker for many users. Color must never be the sole means of conveying information. Error states need icons + text, not just red borders. Status indicators need labels, not just colored dots. Always pair visual indicators with non-visual alternatives.

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

Element	Minimum contrast ratio	Examples
Normal text (< 24px)	4.5:1	Body text, labels, captions, small links
Large text (≥ 24px / 18pt, or ≥ 19px / 14pt bold)	3:1	Headings, large labels, prominent links
Interactive component boundaries	3:1	Button borders, input outlines, toggle tracks
Non-text content conveying information	3:1	Status icons, chart segments, badges

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

Need	HTML Solution	ARIA Fallback (only if HTML insufficient)
Button	<button>	role="button" + tabindex="0" + key handlers
Link	<a href>	role="link" (rare)
Navigation region	<nav>	role="navigation"
Main content	<main>	role="main"
Dialog	<dialog>	role="dialog" + aria-modal="true"
Live update	—	aria-live="polite" on container
Expand/collapse	<details> / <summary>	aria-expanded on trigger
Icon-only button	—	aria-label on the button
Form error	—	aria-invalid + aria-describedby
Current page	—	aria-current="page" on nav link
Progress	<progress>	role="progressbar" + aria-valuenow

Contrast Requirements

Element	Minimum ratio	Example
Normal text (< 24px)	4.5:1	Body text, labels, captions
Large text (≥ 24px / 18pt, or ≥ 19px / 14pt bold)	3:1	Headings, large labels
Interactive component boundaries	3:1	Button borders, input outlines
Non-text (icons conveying info)	3:1	Status icons, chart segments

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

Rule	Description
Use logical CSS properties	margin-inline-start instead of margin-left; padding-inline-end instead of padding-right
Let layout engine handle direction	Set dir="rtl" on root; avoid manual transforms for standard layout
Icons may need flipping	Directional icons (arrows, progress bars) may need transform: scaleX(-1) in RTL
Test both directions	Verify layout, alignment, and text truncation in both LTR and RTL

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)