Web Accessibility
Pathrule2 Rules • 2 Memories • 1 Skill
A WCAG 2.2 AA pattern for frontend teams that keeps accessibility correct without slowing delivery. It enforces a semantic-HTML-first approach, reserves ARIA for genuine custom widgets, and ships a review checklist so every component is keyboard operable, properly labeled, and visibly focusable before merge.
Suggested path map
Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.
/ workspace root
web-accessibility-review
src/
Accessibility tooling and CI gates
components/
Native HTML before ARIA
Keyboard operability and visible focus
Accessible forms: labels, errors, and grouping
Rules
2Native HTML before ARIA/src/componentshighstrictUse the semantically correct native element first; add ARIA only for behavior HTML cannot express.
| 1 | Reach for the native element that already has the role, state, and keyboard behavior you need before adding any ARIA. Per the 2026 WebAIM Million report, pages with ARIA average more detectable errors than pages without it, so ARIA is a last resort, not a default. |
| 2 | |
| 3 | - Use `<button>` for actions and `<a href>` for navigation. Never attach `onClick` to a `<div>` or `<span>` to fake a control. |
| 4 | - Use `<label>`, `<fieldset>`/`<legend>`, `<nav>`, `<main>`, `<header>`, and `<footer>` instead of generic `<div>` plus `role`. |
| 5 | - Reserve ARIA for custom widgets that have no native equivalent (`role="dialog"`, `role="tablist"`, `aria-live`), and never override a native role with a redundant one such as `<button role="button">`. |
| 6 | - Any ARIA control built from non-interactive elements must add `tabindex="0"` plus keydown handlers, because ARIA declares semantics but adds zero keyboard behavior. |
Keyboard operability and visible focus/src/componentshighadvisoryEvery interactive element must be reachable, operable by keyboard, and show a clear focus indicator.
| 1 | All functionality must work with the keyboard alone, and the focused element must always be visibly distinguishable. This covers WCAG 2.2 AA 2.1.1 Keyboard, 2.4.7 Focus Visible, 2.4.11 Focus Not Obscured, 2.5.7 Dragging Movements, and 2.5.8 Target Size. |
| 2 | |
| 3 | - Never remove the focus outline with `outline: none` unless you replace it with an equally visible indicator at 3:1 contrast against adjacent colors. |
| 4 | - Maintain a logical DOM/tab order and avoid positive `tabindex` values; use `tabindex="-1"` only for programmatic focus targets. |
| 5 | - Manage focus on route changes, dialog open/close, and dynamic content so focus is never lost or trapped unintentionally. |
| 6 | - Provide a non-drag alternative for any drag-and-drop interaction, and give pointer targets at least 24x24 CSS pixels (44x44 for primary touch targets). |
Memories
2Accessible forms: labels, errors, and grouping/src/componentsHow we wire labels, required state, and error messaging so every field is programmatically understandable.
| 1 | Every input needs a programmatic label and a clear path from field to error. Placeholder text is not a label and disappears on input, so it never substitutes for `<label>`. |
| 2 | |
| 3 | - Associate labels explicitly with `<label htmlFor={id}>` matching the input `id`, or wrap the input inside the `<label>`. |
| 4 | - Mark required fields with the native `required` attribute and surface validation errors with `aria-invalid="true"` plus `aria-describedby` pointing at the error text node. |
| 5 | - Group related controls (radio sets, address blocks) in `<fieldset>` with a `<legend>`; use `aria-live="polite"` for async/inline validation summaries. |
| 6 | - Keep error text adjacent and specific ("Enter a valid email"), and move focus to the first invalid field on submit failure. |
Accessibility tooling and CI gates/srcThe lint, dev-time, and test stack we use to catch a11y regressions before merge.
| 1 | Automated checks catch roughly a third of accessibility issues, so we run them in CI and pair them with manual keyboard and screen-reader passes. The target is WCAG 2.2 AA. |
| 2 | |
| 3 | - `eslint-plugin-jsx-a11y` runs in lint and blocks the build on errors (clickable non-interactive elements, missing alt, label-less controls). |
| 4 | - `@axe-core/react` logs violations to the console in development; `jest-axe` / `axe-core` assert no violations in component tests. |
| 5 | - Color contrast must meet 4.5:1 for normal text and 3:1 for large text and UI/focus indicators; verify in design tokens, not per component. |
| 6 | - Automation never replaces manual testing: tab through every flow and verify with a real screen reader (NVDA, VoiceOver, or JAWS), since simulators are unreliable. |
Skills
1web-accessibility-review/rootPer-component WCAG 2.2 AA review checklist to run before merging any UI change.
| 1 | --- |
| 2 | name: web-accessibility-review |
| 3 | description: Run this checklist before merging any new or changed UI component to verify WCAG 2.2 AA. Covers semantic HTML, keyboard operability, focus, labels, contrast, and screen-reader output. |
| 4 | --- |
| 5 | |
| 6 | # Web accessibility review |
| 7 | |
| 8 | - [ ] Every interactive element uses a native control (`<button>`, `<a href>`, `<input>`); no `onClick` on `<div>`/`<span>`. |
| 9 | - [ ] ARIA is present only where native HTML cannot express the role or state, with no redundant or conflicting roles. |
| 10 | - [ ] All functionality is reachable and operable with the keyboard alone; tab order follows reading order. |
| 11 | - [ ] Focus is always visible (no bare `outline: none`) and meets 3:1 contrast against adjacent colors. |
| 12 | - [ ] Focus is managed on dialog open/close and route changes, and is never trapped unintentionally. |
| 13 | - [ ] Every form field has an associated `<label>`; errors use `aria-invalid` plus `aria-describedby`. |
| 14 | - [ ] Images have meaningful `alt`, or `alt=""` when decorative; icon-only buttons have an accessible name. |
| 15 | - [ ] Text contrast is at least 4.5:1 (3:1 for large text and UI components). |
| 16 | - [ ] Pointer targets are at least 24x24 CSS px and drag interactions have a single-pointer alternative. |
| 17 | - [ ] Verified with `eslint-plugin-jsx-a11y`, an axe run, and one manual screen-reader pass. |
Why this pattern
Agents reach for ARIA and div soup instead of native elements, shipping components that fail keyboard, focus, and screen-reader users.
Built for Frontend and product teams building React, Next.js, or component-library UIs to WCAG 2.2 AA..
Keeps your assistant from:
- Clickable <div> and <span> that keyboard and screen-reader users cannot operate
- Redundant or wrong ARIA that creates more errors than it fixes
- Form inputs with no programmatic label and controls with invisible focus rings
- License
- Apache-2.0
- Version
- 1.0.0
- Updated
- 2026-06-09