• June 1, 2025

ARIA Command Elements Must Have Discernible Text

Rule ID: aria-command-name
Ruleset: axe-core 4.10
User Impact: Serious
Guidelines: WCAG 2.1 (A), WCAG 2.0 (A), WCAG 2.2 (A), Trusted Tester, EN 301 549

How to Fix the Problem

Interactive elements that use ARIA roles such as link, button, or menuitem must have accessible, descriptive text so assistive technologies like screen readers can properly announce their purpose.

To meet compliance:

✅ Use inner text that clearly describes the purpose:

✅ Use a non-empty aria-label:

✅ Use aria-labelledby to reference another element with discernible text:

✅ Use the title attribute as a fallback (less preferred but still acceptable):

❌ Avoid the following incorrect patterns:

• Empty inner text:

• Empty aria-label:

• aria-labelledby pointing to non-existent or empty elements:

Ensure that the name provided is both meaningful and perceivable by screen reader users. It should describe the element’s function clearly.

Why it Matters

Screen reader users rely on accessible names to understand the purpose of interactive elements. Without descriptive text or labels:

• Users may hear only “button” or “link” without context, making navigation confusing.

• Tasks such as submitting forms, opening menus, or navigating to different pages become inaccessible.

• Poorly labeled elements diminish the usability and accessibility of your interface, violating legal standards and best practices.

Moreover, in more complex widgets or interactive structures, it’s essential that the relationships between elements (like parent/child in a menu or tree) are clear—either through DOM structure or ARIA attributes like aria-owns.

Rule Description

Elements that use ARIA command roles—button, link, or menuitem—must include a name that is discernible by assistive technology. This name should describe what the element does or where it will lead.

The Algorithm (in Simple Terms)

1. Find all elements with roles: button, link, or menuitem.

2. Check if they have:

   • Non-empty inner text, or

   • An aria-label with non-empty value, or

   • An aria-labelledby attribute that references another element with readable text, or

   • A title attribute with a meaningful string.

3. If none of the above exist, flag the element as a failure.