Skip to main content
Accessibility Pro
Startscanning

Fix guides · WCAG 2.2

Fixing label-in-name mismatches

2.5.3 Label in Name · Level A W3C: Understanding 2.5.3

When a control has visible text, its accessible name must contain that text. The sample button shows "Pay now" but aria-label replaces its name with "Complete purchase", so a voice control user who says "click Pay now" gets nothing.

Who this affects: People who use voice control, and screen reader users who hear a name that differs from what sighted colleagues see.

The failing markup

<button type="submit" aria-label="Complete purchase">Pay now</button>

How to fix it

  1. Remove the aria-label if the visible text is already a good name. This is usually the right fix.
  2. If extra context is needed, keep the visible text at the start of the name: "Pay now, complete purchase".

The change

Removed: <button type="submit" aria-label="Complete purchase">Pay now</button>Added: <button type="submit" aria-label="Pay now, complete purchase">Pay now</button>

Verified by the scanner

On 2026-09-13 both versions of this sample were run through Accessibility Pro's scan pipeline with arc-style, axe-core, ibm-equal-access, pa11y, focus-graph. The failing markup was reported as:

  • ibm-equal-access: ibm-label_name_visible, WCAG 2.5.3

The fixed markup produced no findings at all. To run the same check on every pull request, use the accessibility GitHub Action; how accurate the scanner is overall is in the published benchmark.

Worth knowing

  • Composite links such as product cards often have a name like "Blue shirt, 29 euros" that contains the heading but not every word shown. The scanner re-checks those on the live page and routes them to manual review instead of failing them.