Suspicious Accessible Name Audit

Screen readers announce a control by its accessible name. When that name comes from an aria-label, title or placeholder that was filled in from a class name, a script variable or a template that never rendered, screen reader users hear “quantity dash selector”, “undefined” or “curly brace curly brace title”, while sighted users see a perfectly good label. Every check that only asks whether a name exists passes these, because the name is there.

The audit reports results against WCAG 2.4.6 Headings and Labels for form fields, buttons, landmarks and dialogs, 1.1.1 Non-text Content for icon-only buttons and links and for iframes, whose name stands in for what they show, and 2.4.4 Link Purpose (In Context) for links with no surrounding text.

Turning it on

This audit is experimental: it is off by default while we validate it against more real-world sites. To enable it, open a site’s Settings, and switch on Include experimental audits under Scan settings. The setting is per-site, and applies to every scheduled and manual scan of that site from the moment you save it.

How the audit works

The audit reads every rendered button, link, form field, tab, menu item, dialog, labelled landmark and iframe, including those in open shadow roots, and works out each one’s accessible name and where it came from. Images are left to the filename alt text audit, and elements with no name at all are left to the existing name audits.

These are reported as violations:

• Script value, template or placeholder: a name from aria-label, title or placeholder is a leftover script value such as undefined, null or [object Object], an unrendered template token such as {{title}} or %s, lorem ipsum, or a stock placeholder such as TODO or button.
• The element’s own identifier: the name is the element’s id, one of its classes, its name or a data-* value, and that value looks like code, such as quantity-selector or qtyInput.

These are reported for you to review:

• Looks like an identifier: the name is shaped like code, such as add-to-cart-button or product_card_cta, without matching the element’s own attributes.
• Numbered placeholder: the name is a word like banner, slide or item followed by a number, such as banner1 or btn-3.
• Repeats the role: a name from aria-label, title or placeholder ends with the element’s role, such as “Disclaimer button”, which screen readers announce as “Disclaimer button, button”. Role words are matched in English, Swedish and Norwegian, following the page’s lang. This is best practice rather than a WCAG failure.

Names in the visible text of a button or link are not checked for script values or role words, so a link reading “Report a broken link” passes. That is a matter of content rather than naming.

Reading the results

To fix a violation, give the element a name that says what it is or does, in the words a person would use. Check that the attribute is not being filled in from a class name, an ID or a template variable that failed to render.

Some review results are correct names. A carousel’s “Slide 1” is a numbered name that may be exactly right, and a brand or product name can look like an identifier. You can ignore individual elements you have reviewed and accepted using the same ignore feature you use for other issues.

Limitations

The audit catches names that are code or placeholders. It does not judge whether a fluent name describes the element, such as a button labelled “Submit” that opens a menu, and it does not check names in the wrong language. It works out names itself rather than reading the browser’s accessibility tree, so names from <fieldset> legends, CSS generated content or aria-owns are not followed. Elements inside iframes and closed shadow roots are not checked.