Accessibility UI Design

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 => 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 => 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
    </dialog>
  );
};