Accessibility (a11y) UI Design

Purpose

Accessible interfaces are NOT optional extras—they're legal requirements (ADA, WCAG). This skill ensures web interfaces work for everyone: keyboard users, screen reader users, color-blind users, and users with cognitive disabilities. Accessible design is better design for all users.

When to use

• Writing HTML markup for UI components
• Designing complex interactive widgets (modals, dropdowns, tabs, date pickers)
• Auditing existing user interfaces for WCAG compliance
• Building custom form controls
• Creating data tables or other structured content

When NOT to use

• Visual design (separate concern)
• Component styling (use CSS appropriately)
• Performance optimization (different concern)

Inputs required

• HTML or JSX markup
• List of interactive behaviors
• Understanding of WCAG 2.1 AA standards
• Accessibility testing tools (axe, Lighthouse, NVDA)

Workflow

1. Use Semantic HTML First: Use native elements (<button>, <nav>, <dialog>, <form>) instead of building from <div>
2. Keyboard Navigation: Ensure ALL interactive elements are reachable via Tab key and operable via Enter or Space
3. Manage Focus: Trap focus inside modals; return focus to trigger after close
4. Add ARIA Only When Needed: Apply aria-* attributes ONLY when native HTML is insufficient
5. Test Color Contrast: Verify foreground/background colors meet WCAG AA 4.5:1 ratio for text
6. Provide Text Alternatives: Add alt attributes to images; provide captions for videos
7. Label Form Controls: Explicitly associate <label> elements with form inputs
8. Test with Assistive Tech: Test with screen reader (NVDA, JAWS) and keyboard only

Rules

• MUST use semantic HTML elements (button, nav, form, fieldset, legend, etc.)
• MUST make all interactive elements keyboard accessible (no mouse-only interactions)
• MUST NOT remove focus outlines without providing custom focus states
• MUST provide alt text for all images (including empty alt="" for decorative images)
• MUST label all form inputs with <label> elements
• MUST use ARIA only to supplement, never replace, semantic HTML
• MUST achieve at minimum WCAG AA color contrast (4.5:1 for body text)
• MUST NOT rely solely on color to communicate information
• MUST support screen readers (test with real screen readers, not just tools)

Anti-patterns

• Div Buttons: Using <div onClick={...}> instead of <button>
• Relying on Color Alone: Communicating error states purely through red text (add icon or text indicator)
• Missing Labels: Form inputs without associated <label> elements
• Removed Focus: outline: none; without providing custom focus states
• Placeholder as Label: Using placeholder attribute instead of <label> element
• Inaccessible Modals: Modals without focus trap or escape key support
• Overuse of ARIA: Using role="button" on divs instead of <button>

Failure conditions

• Images missing alt attributes
• Color contrast fails WCAG AA (< 4.5:1 for text)
• Interactive elements not keyboard accessible
• Focus trap not working in modals
• Screen reader cannot identify form inputs
• No way to skip repetitive content (navigation)

Validation checklist

• [ ] All interactive elements use semantic HTML (button, link, form)
• [ ] All elements reachable and operable via keyboard (Tab, Enter, Space, Escape)
• [ ] Focus visible and visible focus state (no outline: none)
• [ ] All images have alt text (or alt="" if decorative)
• [ ] All form inputs have associated <label> elements
• [ ] Color contrast meets WCAG AA 4.5:1 (or 3:1 for large text)
• [ ] Focus trap works in modals (cannot tab outside)
• [ ] Escape key closes modals and returns focus
• [ ] Modals announced to screen readers
• [ ] No keyboard traps (can always escape)
• [ ] Tested with keyboard only (no mouse)
• [ ] Tested with screen reader (NVDA, JAWS, VoiceOver)
• [ ] Automated tools pass (axe, Lighthouse)

Output format

• HTML structure: Semantic elements with proper nesting
• Focus management: Visible focus states, focus traps in modals
• ARIA attributes: Applied only when semantic HTML insufficient
• Color usage: Contrast-compliant, not sole communication method
• Form structure: Labels explicitly associated, error messages linked
• Validation: Automated tool results + manual screen reader testing

Security considerations

• Alt text MUST NOT leak sensitive information unnecessarily
• ARIA attributes MUST NOT expose hidden security features
• Focus management MUST prevent keyboard traps
• ARIA live regions MUST NOT expose private user data

Agent execution notes

• Agent MAY: Add semantic HTML, add ARIA when needed, add alt text, fix color contrast, add focus management
• Agent MUST NEVER: Remove focus indicators, use role="button" on divs, use placeholder for labels, trap keyboard
• Agent MUST ASK: Before adding complex ARIA, before removing focus indicators, before major interactive behavior changes
• Agent MUST VALIDATE: Keyboard navigation works, color contrast passes, screen reader can understand content

Example

❌ Anti-pattern (Non-semantic, no labels, color-only error, no focus):

// BAD: DIV button, no accessibility
<div onClick={() => submit()} style={{ outline: 'none', cursor: 'pointer' }}>
  Submit
</div>

// BAD: Input without label
<input type="email" placeholder="Email address" />

// BAD: Error shown only in red
<div style={{ color: 'red' }}>Password too short</div>

// BAD: Modal with focus trap
<div role="dialog">
  <input />
  {/* User can Tab outside modal */}
</div>

✅ Correct pattern (Semantic, labeled, accessible errors, focus managed):

// GOOD: Semantic button
<button onClick={() => submit()} type="button">
  Submit
</button>

// GOOD: Label explicitly associated
<label htmlFor="email-input">Email address</label>
<input id="email-input" type="email" required />

// GOOD: Error shown with icon and text (not just color)
<div className="error" role="alert" aria-live="polite">
  <Icon name="error" />
  Password too short (minimum 8 characters)
</div>

// GOOD: Modal with focus trap and keyboard handling
const Modal = ({ isOpen, onClose, children }) => {
  const modalRef = useRef(null);
  
  useEffect(() => {
    if (!isOpen) return;
    
    const handleKeyDown = (e) => {
      if (e.key === 'Escape') onClose();
    };
    
    // Focus first interactive element in modal
    const firstFocusable = modalRef.current?.querySelector('button, [href], input');
    firstFocusable?.focus();
    
    window.addEventListener('keydown', handleKeyDown);
    return () => window.removeEventListener('keydown', handleKeyDown);
  }, [isOpen]);
  
  return (
    <dialog
      ref={modalRef}
      open={isOpen}
      role="dialog"
      aria-modal="true"
      aria-labelledby="modal-title"
    >
      <h1 id="modal-title">Modal Title</h1>
      {children}
      <button onClick={onClose}>Close</button>
    </dialog>
  );
};