Skip to content

hexjasur/AGENTS.md / skills/web-accessibility

web-accessibility

Unverified

Build 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
  1. Map landmarks (header, nav, main, footer), one h1 and a logical heading order, lists, tables, and controls.
  2. Tab through the whole flow. Order must match visual order; focus must always be visible; Esc closes overlays; focus returns to the trigger on close.
  3. 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.
  4. Check contrast, 200% text zoom and 320 px reflow without two-dimensional scrolling, prefers-reduced-motion, and target size.
  5. Run an automated scan (axe, Lighthouse), which finds only a fraction of issues, then confirm manually. Use references/accessibility.md for the WCAG 2.2 checklist and widget patterns.

Guardrails

  • Use <button> for actions and <a href> for navigation. Never a clickable div or span.
  • 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 lang attribute, 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-label on a div with no role is ignored by many screen readers. Name interactive elements, not generic containers.
  • display: none and visibility: hidden remove 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) or role="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 need alt="".

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.

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: 467kUpdated Claude CodeCodexVerifiedInstall
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: 467kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 193kUpdated Claude CodeCodexVerifiedInstall