In one paragraph
Buttons must have discernible text means a tested button did not expose a usable accessible name under the rule. Give the control a name describing its action, preferably with clear visible text or an appropriate icon-button label. Check the computed accessibility name and keyboard operation together. Adding an ARIA label can name a control, but cannot repair every broken interaction or misleading action.
Why it matters
Users need to identify a button before activating it. An unexplained icon can be ambiguous visually and can leave a screen-reader or voice-input user without useful context. Naming should distinguish actions such as Close dialog, Search, or Save changes, not merely describe a circle or cross.
Visible action text is often the most robust starting point. When a design genuinely needs an icon-only button, aria-label or an appropriate aria-labelledby relationship can provide its accessible name. If visible text exists, keep the name consistent with that text for voice interaction.
Native buttons provide semantics and keyboard behaviour that an arbitrary element does not acquire simply by receiving role="button". Names, states, focus handling, and actual activation are related but separate responsibilities.
How WebAuditOS evaluates this finding
The supplied button-name integration concerns applicable native button elements. Input buttons and custom ARIA command controls have neighbouring rules. It recognises several naming or applicability paths, including text and supported ARIA relationships; a title fallback can also affect the result.
The supplied critical axe impact maps to high severity. A presentational-role exception is not a recommended fix for a real interactive button, and focusable semantics can prevent such a role from taking effect. A pass does not evaluate whether the action description is accurate or whether every state works.
How to fix it
- Inspect the flagged element in the rendered DOM and accessibility tree. Confirm it is the button you intend, rather than an input or another component covered elsewhere. Read its computed name, not only its source attributes.
- Prefer clear visible wording where practical:
<button type="button">Save changes</button>Choose the correct type: a button within a form can otherwise default to submission when you intended a local action.
- For an icon-only control, provide a concise action name and keep decorative artwork out of that name. For example:
<button type="button" aria-label="Close dialog"><svg aria-hidden="true" focusable="false" viewBox="0 0 20 20"><path d="M4 4L16 16M16 4L4 16" stroke="currentColor"/></svg></button>This illustrates naming, not a complete dialog implementation. The actual button must still close the intended dialog and restore focus appropriately.
- If visible labelling already exists, use a correct labelled-by relationship where appropriate rather than overriding it with unrelated hidden wording. Keep referenced IDs unique and present in the tested state.
- Use aria-describedby for supplementary help instead of overloading the name with paragraphs. Required states such as expanded or pressed need their own appropriate semantics and correct updates.
- Avoid relying solely on a hover tooltip as the persistent explanation. title can contribute to some naming paths, but its availability across interaction methods is not a robust visible-label strategy.
- Test Tab, Enter, Space, focus visibility, and action completion in relevant contexts. Use native button behaviour where possible and follow a complete keyboard pattern for custom widgets.
- Rescan and review icon sets, dialogs, responsive views, and disabled or loading states manually. A generic name such as Button can pass a presence test without making the interface understandable.
What the fix can break
Adding aria-label can override useful descendant text in the computed name. Inspect the result so a visible Save button is not announced as an unrelated internal command.
Changing an element to a native button can alter styling or form submission. Preserve layout and explicit types while gaining native semantics.
Do not remove role or focus solely to suppress a finding on a control that must remain usable. That can trade an unnamed action for an undiscoverable one.
Questions
Does an icon button need visible text?
Not always, but it needs an accurate accessible name and understandable design. Visible text often helps a broader audience.
Does role=button implement keyboard activation?
No. A custom widget still needs its behaviour implemented. A native button is usually simpler.
Is a title-only pass sufficient evidence?
No. Evaluate persistent clarity, computed naming, and interaction rather than a fallback's mere presence.
Which related checks help?
Review image alternatives and the automation limits guide.
What severity does this get in the report?
High. Severity for an axe rule comes 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 critical in axe-core, so a failure arrives as high. That is why the facts panel above states a conformance level rather than a severity - for other axe rules the value depends on what failed.