In one paragraph
ARIA commands must have an accessible name means an applicable custom command role did not expose a name the rule accepts. Use meaningful visible text or a correct naming relationship, and prefer native buttons or links when they provide the intended function. A role and label alone do not add focus, keyboard activation, navigation behaviour, or a complete menu interaction model.
Why it matters
A command name identifies the action before activation. Close dialog, Download invoice, and Open account settings communicate different outcomes; a generic Icon label does not explain them even if it passes a non-empty test.
Custom controls made from div or span require behaviour native controls already supply. A link role without a real navigation contract can lose expected browser features, while a button role without keyboard handling can remain unusable despite a perfect name.
Visible wording and the computed accessible name should remain coherent, including for voice use. ARIA precedence can override descendant text, so adding another label is not always an improvement. Check the final name rather than counting attributes.
How WebAuditOS evaluates this finding
The supplied aria-command-name rule covers its applicable button, link, and menuitem roles on custom elements, with native and specialised elements handled through other naming rules. Text and supported ARIA or title naming paths can satisfy the check.
Serious impact maps to high severity. It checks name presence in the rendered state, not meaningfulness or full operation. Commands that appear only after opening a menu or dialog may be absent from the initial sampled state.
How to fix it
- Identify the intended action or navigation destination. Choose a native button for an action and an href-based link for navigation when those fit the task. Do not use a generic role to avoid styling a real control.
- Provide concise truthful wording. For an ordinary action, a starting point is:
<button type="button">Download invoice</button>Connect it to the actual supported behaviour. This naming example alone does not implement the download or all success and error feedback.
- For a legitimate icon-only control, supply an accurate accessible name and keep decorative artwork from creating redundant announcements. Preserve visible label text in the name where the interface has such wording.
- If the widget must remain custom, implement its complete keyboard and focus pattern. A button-like action normally needs expected Enter and Space behaviour, while a link and an application menu have different interaction contracts.
- Use aria-labelledby when an appropriate visible label exists and keep IDs stable and unique. Do not rely on a detached tooltip or nearby visual text that is not actually connected.
- Review state and description separately. Expanded, pressed, disabled, and other applicable properties must reflect real behaviour. A long name should not become a container for every instruction and status update.
- Test initial, open, loading, error, and completion states using keyboard and supported assistive technology. Check focus after a command removes content or opens a dialog.
- Rescan the relevant states and review native naming rules too. Replacing a custom element can move responsibility to another rule without changing the user's need for a clear name and usable action.
What the fix can break
Replacing a div with a button can alter CSS defaults or trigger unintended form submission unless type is chosen deliberately. Test appearance and event handlers after the semantic repair.
Changing names can affect voice commands, analytics selectors, and tests. Update dependencies without sacrificing useful human wording.
Do not remove focus or the command role solely to hide the finding while leaving an unexplained click handler. That can make the action less discoverable rather than more accessible.
Questions
Does role=button supply keyboard handling?
No. Native buttons supply much of that behaviour; a custom widget must implement its own complete interaction.
Can a generic non-empty name pass?
It can satisfy this presence test without explaining the action. Review name quality manually.
Is a tooltip automatically the command's name?
No. Inspect the computed relationship. A visible tooltip is not necessarily part of the accessible name.
Which related checks help?
Review native buttons, link names, and the automation limits guide.
What severity does this get in the report?
High. An axe finding takes its severity from the impact axe reports for the element that failed, and the report maps critical and serious to high, moderate to medium, minor to low. This rule is declared serious in axe-core 4.13.0, so every failure arrives as high.