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.

<principles>

<semantic-html-first>
Start with the correct HTML element. `<button>` for actions, `<a>` for navigation, `<nav>` for navigation regions, `<main>` for primary content. Native semantics are free, reliable, and require zero ARIA. Only reach for ARIA when HTML alone cannot convey the meaning.
</semantic-html-first>

<keyboard-is-mandatory>
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.
</keyboard-is-mandatory>

<never-color-alone>
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.
</never-color-alone>

</principles>

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).