The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat(skills): add frontend accessibility skill (#2048)
HJ8fb728d7eb48
diff --git a/skills/frontend-a11y/SKILL.md b/skills/frontend-a11y/SKILL.mdnew file mode 100644index 000000000..08763c1c2--- /dev/null+++ b/skills/frontend-a11y/SKILL.md@@ -0,0 +1,446 @@+---+name: frontend-a11y+description: >+ Accessibility patterns for React and Next.js — semantic HTML, ARIA attributes,+ form labeling, keyboard navigation, focus management, and screen reader support.+ Use when building any interactive UI component or form.+origin: community+---++# 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-ui` — animation patterns with accessibility considerations