Frontend A11y
Accessibility patterns for React and Next.js — semantic HTML, ARIA attributes, form labeling, keyboard navigation, focus management, and screen reader support. Use when building or reviewing forms, modals, dropdowns, tooltips, or tabs, fixing a11y lint or code-review findings, or wiring up keyboard navigation and focus management.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Frontend A11y when an AI agent needs a reusable SKILL.md workflow for this job: Accessibility patterns for React and Next.js — semantic HTML, ARIA attributes, form labeling, keyboard navigation, focus management, and screen reader support. Use when building or reviewing forms, modals, dropdowns, tooltips, or tabs, fixing a11y lint or code-review findings, or wiring up keyboard navigation and focus management.
When not to use it
Skip Frontend A11y when the task is outside the creativity category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/frontend-a11y # Save SKILL.md to ~/.claude/skills/frontend-a11y/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/frontend-a11y/SKILL.md. For a shared project, commit the folder at .claude/skills/frontend-a11y/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Frontend A11y skill for this task: Use Frontend A11y when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 72/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Frontend Accessibility Patterns
Practical accessibility patterns for React and Next.js. Covers the issues most commonly flagged in code review: missing form labels, incorrect ARIA usage, non-semantic interactive elements, and broken keyboard navigation.
## When to Activate
- Building or reviewing form components (`<input>`, `<select>`, `<textarea>`) - Creating interactive elements (modals, dropdowns, tooltips, tabs) - Using `<div>` or `<span>` with `onClick` - Adding `aria-*` attributes to any element - Implementing keyboard navigation or focus management - Receiving accessibility feedback from code review tools (CodeRabbit, ESLint a11y) - Building components that must support screen readers
## Form Accessibility
Missing `htmlFor` / `id` pairing and disconnected error messages are the most common issues flagged in code review.
### Label Connection
```tsx // BAD: label has no connection to input — screen readers cannot associate them <label>Email</label> <input type="email" />
// GOOD: htmlFor matches input id <label htmlFor="email">Email</label> <input id="email" type="email" /> ```
### Required Fields
```tsx // BAD: visual-only asterisk conveys nothing to screen readers <label htmlFor="email">Email *</label> <input id="email" type="email" />
// GOOD: required enables native browser validation; aria-required signals it to screen readers <label htmlFor="email"> Email <span aria-hidden="true">*</span> </label> <input id="email" type="email" required aria-required="true" /> ```
### Error Messages
```tsx // BAD: error text exists visually but is not linked to the input <input id="email" type="email" /> <span className="error">Invalid email address</span>
// GOOD: aria-describedby connects input to its error message // aria-invalid signals the invalid state to screen readers <input id="email" type="email" aria-describedby="email-error" aria-invalid={!!error} /> {error && ( <span id="email-error" role="alert"> {error} </span> )} ```
### Complete Accessible Form
```tsx interface LoginFormProps { onSubmit: (email: string, password: string) => void; }
export function LoginForm({ onSubmit }: LoginFormProps) { const [email, setEmail] = useState(''); const [password, setPassword] = useState(''); const [errors, setErrors] = useState<{ email?: string; password?: string }>({});
const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); const newErrors: typeof errors = {}; if (!email) newErrors.email = 'Email is required'; if (!password) newErrors.password = 'Password is required'; if (Object.keys(newErrors).length) { setErrors(newErrors); return; } onSubmit(email, password); };
return ( <form onSubmit={handleSubmit} noValidate> <div> <label htmlFor="email"> Email <span aria-hidden="true">*</span> </label> <input id="email" type="email" value={email} onChange={e => setEmail(e.target.value)} aria-required="true" aria-describedby={errors.email ? 'email-error' : undefined} aria-invalid={!!errors.email} autoComplete="email" /> {errors.email && ( <span id="email-error" role="alert"> {errors.email} </span> )} </div>
<div> <label htmlFor="password"> Password <span aria-hidden="true">*</span> </label> <input id="password" type="password" value={password} onChange={e => setPassword(e.target.value)} aria-required="true" aria-describedby={errors.password ? 'password-error' : undefined} aria-invalid={!!errors.password} autoComplete="current-password" /> {errors.password && ( <span id="password-error" role="alert"> {errors.password} </span> )} </div>
<button type="submit">Log in</button> </form> ); } ```
## Semantic HTML
Use the element that matches the intent. Screen readers and keyboard users depend on native semantics.
```tsx // BAD: div has no role, no keyboard support, no accessible name <div onClick={handleClick}>Submit</div>
// GOOD: button is focusable, activates on Enter/Space, announces as "button" <button type="button" onClick={handleClick}>Submit</button> ```
```tsx // BAD: non-semantic navigation <div onClick={() => navigate('/home')}>Home</div>
// GOOD: anchor supports right-click, middle-click, and keyboard navigation <a href="/home">Home</a> ```
```tsx // BAD: heading hierarchy skipped (h1 to h4) <h1>Dashboard</h1> <h4>Recent Activity</h4>
// GOOD: sequential heading levels <h1>Dashboard</h1> <h2>Recent Activity</h2> ```
## ARIA Attributes
Use ARIA only when native HTML semantics are insufficient. Wrong ARIA is worse than no ARIA.
### aria-label vs aria-labelledby
```tsx // aria-label: inline string label — use when no visible label text exists <button aria-label="Close modal"> <XIcon /> </button>
// aria-labelledby: references another element's text — use when a visible label exists <section aria-labelledby="section-title"> <h2 id="section-title">Recent Orders</h2> {/* content */} </section> ```
### aria-describedby
```tsx // Provides supplementary description beyond the label <button aria-describedby="delete-warning" onClick={handleDelete} > Delete account </button> <p id="delete-warning">This action cannot be undone.</p> ```
### aria-live for Dynamic Content
```tsx // Use aria-live to announce content that updates without a page reload // polite: waits for user to finish current action before announcing // assertive: interrupts immediately — use only for urgent errors
export function StatusMessage({ message, isError }: { message: string; isError?: boolean }) { return ( <div role="status" aria-live={isError ? 'assertive' : 'polite'} aria-atomic="true"> {message} </div> ); } ```
### aria-expanded and aria-controls
```tsx export function Accordion({ title, children }: { title: string; children: React.ReactNode }) { const [isOpen, setIsOpen] = useState(false); const contentId = useId();
return ( <div> <button aria-expanded={isOpen} aria-controls={contentId} onClick={() => setIsOpen(prev => !prev)}> {title} </button> <div id={contentId} hidden={!isOpen}> {children} </div> </div> ); } ```
## Keyboard Navigation
Every interactive element must be reachable and operable by keyboard alone.
### Custom Dropdown
```tsx export function Dropdown({ options, onSelect }: { options: string[]; onSelect: (value: string) => void }) { const [isOpen, setIsOpen] = useState(false); const [activeIndex, setActiveIndex] = useState(0); const listId = useId();
if (!options.length) return null;
const handleKeyDown = (e: React.KeyboardEvent) => { switch (e.key) { case 'ArrowDown': e.preventDefault(); setActiveIndex(i => Math.min(i + 1, options.length - 1)); break; case 'ArrowUp': e.preventDefault(); setActiveIndex(i => Math.max(i - 1, 0)); break; case 'Enter': case ' ': e.preventDefault(); if (isOpen) onSelect(options[activeIndex]); setIsOpen(prev => !prev); break; case 'Escape': setIsOpen(false); break; } };
return ( <div role="combobox" aria-expanded={isOpen} aria-haspopup="listbox" aria-controls={listId} tabIndex={0} onKeyDown={handleKeyDown} onClick={() => setIsOpen(prev => !prev)} > <span>{options[activeIndex]}</span> {isOpen && ( <ul id={listId} role="listbox"> {options.map((option, index) => ( <li key={option} role="option" aria-selected={index === activeIndex} onClick={() => { onSelect(option); setIsOpen(false); }} > {option} </li> ))} </ul> )} </div> ); } ```
## Focus Management
Focus must move logically when UI state changes — especially for modals and route transitions.
### Modal Focus Restoration
> This example covers initial focus and restoration. For a full focus trap (Tab/Shift+Tab cycling within the modal), use a library like [`focus-trap-react`](https://github.com/focus-trap/focus-trap-react) which handles edge cases like dynamic content and nested portals.
```tsx export function Modal({ isOpen, onClose, title, children }: { isOpen: boolean; onClose: () => void; title: string; children: React.ReactNode }) { const modalRef = useRef<HTMLDivElement>(null); const previousFocusRef = useRef<HTMLElement | null>(null);
useEffect(() => { if (isOpen) { // Save currently focused element and move focus into modal previousFocusRef.current = document.activeElement as HTMLElement; modalRef.current?.focus(); } else { // Restore focus to the element that opened the modal previousFocusRef.current?.focus(); } }, [isOpen]);
if (!isOpen) return null;
return ( <div ref={modalRef} role="dialog" aria-modal="true" aria-labelledby="modal-title" tabIndex={-1} onKeyDown={e => e.key === 'Escape' && onClose()}> <h2 id="modal-title">{title}</h2> {children} <button onClick={onClose}>Close</button> </div> ); } ```
## Images and Icons
```tsx // BAD: decorative icon announced as unlabeled image <img src="/icon.svg" />
// GOOD: decorative image hidden from screen readers <img src="/decoration.png" alt="" aria-hidden="true" />
// GOOD: meaningful image with descriptive alt text <img src="/chart.png" alt="Monthly revenue increased 23% from January to March" />
// GOOD: icon button with accessible label <button aria-label="Delete item"> <TrashIcon aria-hidden="true" /> </button> ```
## Reduced Motion
Respect users who have requested reduced motion in their OS settings.
```tsx export function useReducedMotion(): boolean { const [prefersReduced, setPrefersReduced] = useState(false);
useEffect(() => { const mq = window.matchMedia('(prefers-reduced-motion: reduce)'); setPrefersReduced(mq.matches); const handler = (e: MediaQueryListEvent) => setPrefersReduced(e.matches); mq.addEventListener('change', handler); return () => mq.removeEventListener('change', handler); }, []);
return prefersReduced; }
// Usage export function AnimatedCard({ children }: { children: React.ReactNode }) { const reduceMotion = useReducedMotion();
return ( <div style={{ transition: reduceMotion ? 'none' : 'transform 300ms ease' }} > {children} </div> ); } ```
## Anti-Patterns
```tsx // BAD: onClick on non-interactive element with no keyboard support <div onClick={handleClick}>Click me</div>
// BAD: aria-label on a div that has no role <div aria-label="Navigation">...</div>
// BAD: placeholder used as a substitute for label <input placeholder="Enter your email" />
// BAD: positive tabIndex creates unpredictable tab order <button tabIndex={3}>Submit</button>
// BAD: aria-hidden on a focusable element — keyboard users get trapped <button aria-hidden="true">Open</button>
// BAD: role="button" on div without keyboard handler <div role="button" onClick={handleClick}>Submit</div> // Missing: tabIndex={0}, onKeyDown for Enter/Space ```
## Checklist
Before submitting any interactive component for review:
- [ ] Every `<input>`, `<select>`, and `<textarea>` has a connected `<label>` via `htmlFor`/`id` - [ ] Error messages are linked with `aria-describedby` and marked `role="alert"` - [ ] No `onClick` on `<div>` or `<span>` without `role`, `tabIndex`, and `onKeyDown` - [ ] Icon-only buttons have `aria-label` - [ ] Decorative images use `alt=""` and `aria-hidden="true"` - [ ] Modals restore focus on close (for full focus trapping with Tab/Shift+Tab cycling, use a library like `focus-trap-react`) - [ ] Dynamic content updates use `aria-live` - [ ] `prefers-reduced-motion` is respected for animations
## Related Skills
- `frontend-patterns` — general React component and state patterns - `design-system` — design token and component consistency - `motion-foundations` and `motion-patterns`: animation patterns with accessibility considerations
Intended uses
- Use Frontend A11y when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.