GatekeeperQA

GATEKEEPERQA

How to fix buttons without an accessible name

Updated October 23, 2026 · By GatekeeperQA

Quick answer: name the action

For a native HTML button, meaningful visible text is usually the simplest accessible name: <button type="button">Save report</button>. If the button must be icon-only, supply an appropriate name such as aria-label="Close preview". A name helps explain the control; it does not prove the action works.

HTML examples · Recorded scan evidence · Retest checklist

What does “buttons must have discernible text” mean?

The button-name rule checks whether a button has a name available to assistive technology. An empty button or a decorative icon without a name can trigger it. Inspect the element in the rendered page: a CSS background image alone does not describe its action.

See Deque’s button-name rule and the W3C button pattern. Rule versions and scan scope matter; keep the engine/version with your evidence.

Two ways to fix the name

1. Prefer visible button text

This illustrative Save report button keeps a decorative icon out of its name. Use type="button" for an ordinary action inside a form; use type="submit" when submission is intended.

<button type="button">
  <span aria-hidden="true">↓</span> Save report
</button>

2. Name an icon-only button explicitly

<button type="button" aria-label="Close preview">
  <span aria-hidden="true">×</span>
</button>

The label belongs on the button, not its hidden decorative icon. Ensure sighted users can also understand the icon. If a control already has visible text, avoid overriding it with an unrelated aria-label; its accessible name should include the visible label. See W3C’s naming guidance.

Try a working, named button

The demo below opens a local message. It sends no report and makes no network request. Tab to the button and try Enter or Space.

Why the warning may remain

Do not hide an interactive button with aria-hidden just to suppress a finding. Check its computed name in browser accessibility tools, then verify its purpose and operation with a person. A generic name such as “button” can still be unhelpful even if a missing-name rule no longer fails.

Recorded example: one fix and its retest

A real CLI scan of our own local demo fixture. No client website or customer data.

Recorded September 25, 2026 with the published GatekeeperQA CLI 0.1.0. These are preserved report artifacts, not a live scan or the hosted scanner UI.

01 / FINDING

Before: FAIL

1 critical button-name finding at #checkout. The button had no accessible name.

<button id="checkout"></button>

Read the before report · JSON

02 / CHANGE

Add a visible name

We added text inside the existing native button. The action is now described to sighted users and exposed as its accessible name.

<button id="checkout">Checkout</button>
03 / RETEST

After: PASS

0 confirmed findings in the automated retest of the same fixture. The CLI exit code changed from 1 to 0.

Read the after report · JSON

Evidence and scope

Baseline report timestamp: . Retest report timestamp: . Both reports name the same local URL. The baseline records one affected element for button-name; the retest findings array is empty. The JSON artifacts above preserve the original data.

Why this change addresses the finding

A native button needs a name that explains its action. Visible text supplies that name here without replacing native button semantics. An icon-only button may need a different implementation; do not copy the word Checkout onto unrelated controls.

Repeat the method on your application

  1. Capture the page URL, state, failing element and baseline report.
  2. Make the smallest meaningful change to the affected component.
  3. Run the same scope again and preserve the retest separately.
  4. Confirm the control is still present and test its operation manually before closing the ticket.

Use the current CLI setup for a new run. The preserved September example uses CLI 0.1.0; the newer narrated demonstration uses 0.3.0 and is a separate recording. Their results should not be combined into one test run.

What the result means

The button-name finding was no longer detected after the change. A passing gate does not establish complete accessibility or WCAG conformance. The local report URL refers to a temporary demo server that is no longer running.

Retest checklist: automation plus human checks

Those manual checks are follow-up guidance, not recorded test results for this example. Record manual evidence separately.

Keep a useful retest record

Page and state: [URL and relevant state]
Element and rule: [selector / button-name]
Change: [visible text or accessible-name source]
Baseline and retest: [dated reports, same scope and version]
Automated outcome: [detected / not detected / incomplete]
Manual checks: [name, focus, Enter/Space and resulting action]
Reviewer and remaining checks: [observed facts only]

“Not detected” is meaningful only if the control was present and the relevant page state was tested. Keep incomplete runs separate from successful retests.