Skip to main content
TestAccessibility

Issue guide

Common finding

ARIA mistakes

Use ARIA sparingly; prefer native HTML.

Invalid or misused ARIA makes custom widgets confusing—roles and states do not match what the browser exposes to assistive tech.

See this on your site

Run a scan, then match rule names in your report to the sections below.

At a glance

Instructional

Stable, unique identifiers

Duplicate IDs and broken ARIA relationships confuse assistive tech when it resolves references.

Why this matters

  • Broken roles can silence controls or announce the wrong type.
  • Native HTML often needs less ARIA, not more.

Where this shows up

Use this list to spot the same pattern on your templates and key URLs.

Buttons and icons

  • div with role=button but no keyboard support

Navigation

  • Menus missing aria-expanded

Modals

  • Dialogs missing required attributes for the dialog pattern

Fix priority — address first

  • Custom components on primary flows.
  • Design-system primitives used everywhere.

Fix priority — can follow

  • Legacy widgets scheduled for replacement (still fix if user-facing).

Who is affected

Keyboard-only users, switch users, and people using screen readers with custom components.

Fix this in your platform

Stack-specific steps, pitfalls, and verification. Core issues link under /wordpress, /shopify, /react, or /nextjs; all issues also have /fix/… URLs.

Guidance

Fix invalid combinations reported by automated tools; validate with browser accessibility inspectors.

Examples (bad vs good)

  • Bad

    `role="button"` on a div with no `tabIndex={0}` or key handlers.

    Good

    Use `<button type="button">` or add full keyboard support + focus.

How to fix

  1. Read the specific rule message from the scan.
  2. Prefer native `<button>`, `<input>`, `<select>` where possible.
  3. If custom, implement keyboard support and ARIA per the WAI-ARIA pattern.
  4. Remove invalid attributes; rescan.

Platform-specific notes

Where this often comes from on common stacks—and what to change.

React
Prop spread onto DOM can inject conflicting roles—lint and type helper components.

Common mistakes

  • Adding redundant roles to native elements incorrectly.
  • Mixing conflicting roles and attributes from copy-paste snippets.

How to verify the fix

  1. Inspect the accessibility tree for role and state.
  2. Run keyboard tests required for the pattern.
  3. Rescan after fixes.

Related: 4.1.2 Name, Role, Value.

Related guides

Run another scan

After you ship a fix, rescan the same URL and keep both report links to compare.

Broader topics

Principles on these pages overlap with HTML issues: PDFs for documents and downloads, mobile for touch, contrast, and small screens.

Related issues

Next steps

Keep the scan, fix, rescan loop going

Ship a fix, then run another scan on the same URL. Each run gets its own report link so you can compare before and after.

Open scan