hexjasur/AGENTS.md / skills/web-accessibility
web-accessibility
UnverifiedBuild and audit accessible web pages and components against WCAG 2.2 AA with semantic HTML, keyboard support, focus management, form errors, contrast, and screen-reader-friendly states. Use for UI work, dialogs, menus, navigation, forms, custom widgets, and accessibility audits or bug reports.
Web Accessibility
Start with native semantics. Add ARIA only when HTML cannot express the behavior, and make every interaction work without a pointer. Target WCAG 2.2 AA unless the project states otherwise.
Procedure
- [ ] 1. Identify the user task and the semantic structure
- [ ] 2. Keyboard pass: tab order, visible focus, Esc, no traps or dead ends
- [ ] 3. Names, roles, states, errors, and live updates
- [ ] 4. Visual pass: contrast, zoom/reflow, motion, target size
- [ ] 5. Automated scan, then manual confirmation
- [ ] 6. Re-test failure and empty states, plus mobile viewport
- Map landmarks (
header,nav,main,footer), oneh1and a logical heading order, lists, tables, and controls. - Tab through the whole flow. Order must match visual order; focus must always be visible;
Esccloses overlays; focus returns to the trigger on close. - Every control has an accessible name, role, and state. Errors are text, associated with the field, and announced. Dynamic updates use a live region or move focus deliberately.
- Check contrast, 200% text zoom and 320 px reflow without two-dimensional scrolling,
prefers-reduced-motion, and target size. - Run an automated scan (axe, Lighthouse), which finds only a fraction of issues, then confirm manually. Use
references/accessibility.mdfor the WCAG 2.2 checklist and widget patterns.
Guardrails
- Use
<button>for actions and<a href>for navigation. Never a clickabledivorspan. - Every input needs a programmatic
<label>. A placeholder is not a label. - Never remove outlines without replacing them with a visible focus style (at least 3:1 contrast against adjacent colors). Prefer
:focus-visible. - Do not rely on color, hover, sound, or animation alone to convey meaning. Hover-only content must also be reachable by keyboard and dismissible.
- Prefer
<dialog>,popover,<details>, and native form controls over custom widgets. A first rule of ARIA applies: no ARIA is better than bad ARIA. - Provide a
langattribute, a descriptive<title>, and a skip link when the page has repeated navigation.
WCAG 2.2 additions to check
- Focus Not Obscured (2.4.11): sticky headers and cookie banners must not cover the focused element.
- Target Size, Minimum (2.5.8): interactive targets at least 24×24 CSS px, or adequately spaced.
- Dragging Movements (2.5.7): every drag interaction has a single-pointer alternative.
- Consistent Help (3.2.6) and Redundant Entry (3.3.7): do not make users re-enter information already given.
- Accessible Authentication (3.3.8): do not require a cognitive test; allow paste and password managers.
Gotchas
aria-labelon adivwith no role is ignored by many screen readers. Name interactive elements, not generic containers.display: noneandvisibility: hiddenremove content from the accessibility tree;aria-hidden="true"on a focusable element creates an invisible tab stop.- Toasts and inline errors that appear silently are missed by screen readers. Use
role="status"(polite) orrole="alert"(urgent) in a container that already exists in the DOM before the update. - Custom selects, comboboxes, and tabs are easy to get wrong. Follow the ARIA Authoring Practices Guide patterns exactly or use a native control.
- SPA route changes do not move focus or update the title for assistive tech; manage both.
- Icon-only buttons need a text name (visually hidden text or
aria-label), and decorative images needalt="".
Report format
For each issue: location, WCAG criterion, user impact, and the fix. Group by severity, and state what was and was not tested (for example, "keyboard and axe only; no screen reader pass").
Read references/accessibility.md for the checklist, widget patterns, and sources.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |