Button

How to test a button

Gherkin Condensed Design

Given that I am on a page with a button

1 Keyboard for mobile & desktop

WHEN I use the tab key to move focus to a button I SEE focus is strongly visually indicated
Then when I use the spacebar and/or enter key to activate the button I SEE the intended action occurs

2 Desktop screenreader

WHEN I use a desktop screenreader (NVDA, JAWS, VoiceOver) AND I use the tab key to move focus to a button
- I HEAR Its purpose is clear
- I HEAR It identifies its role of button
- I HEAR It indicates if it has popup for listbox or menus
- I HEAR It expresses its state if applicable (pressed, expanded, disabled)
Then when I use the spacebar and/or enter key to activate the button I HEAR the intended action occurs

3 Mobile screenreader

WHEN I use a mobile screenreader (Talkback, VoiceOver) AND I swipe to focus on a button
- I HEAR Its purpose is clear
- I HEAR It identifies its role of button
- I HEAR It indicates if it has popup for listbox or menus
- I HEAR It expresses its state if applicable (pressed, expanded, disabled)
Then when I doubletap with the button in focus I HEAR the intended action occurs

1 Keyboard & screen reader actions

When I use	I see/hear
Tab	Focus visibly moves to the button.
Spacebar	Activates the button.
Enter	Activates the button.

2 Mobile screenreader gestures

When I use	I hear
Swipe	Focus moves to the element, expresses its state
Doubletap	Activates the button

3 Screenreader output for all devices

Reads	I hear
Name	Its purpose is clear
Role	It identifies its role of button
Group	It indicates if it has popup for listbox or menus
State	It expresses its state if applicable (pressed, expanded, disabled)

A button must meet these design principles.

1Perceivable

Is easy to identify as interactive
Color is not used as the only means of conveying information (error, success, pressed, expanded, etc)

2Operable

The click/tap target area is no smaller than 44x44px
The disabled and focus states have a 3:1 minimum contrast ratio against default
Toggle pressed or expanded states have a 3:1 minimum contrast ratio against default
The focus indication has a 3:1 minimum contrast ratio against adjacent elements
The focus indication has a minimum area equal to the width of the element and 2px in height

3Understandable

Its purpose is clear in the context of the whole page
It has the correct semantic meaning. If it goes somewhere, it’s a link (that can look like a button). If it does something, it’s a button (that can look like a link)

4Robust

Meets criteria across platforms, devices and viewports

Video examples

iOS Voiceover Safari

Android Talkback Chrome

Windows Jaws Chrome

Windows NVDA Chrome

Code examples

Use semantic HTML

This semantic HTML contains all accessibility features by default.
It uses CSS pseudo attributes to create the arrow indicator, no Javascript.

<button>
  Continue
</button>

Focusable disabled button

The preferred method is to use aria-disabled="true" so screen reader users can find the button, click submit and be notified of errors in the form.

<button aria-disabled="true">
  Continue
</button>

Fully disabled button

A button that uses the disabled attribute will not be focusable, but it is still discoverable by the screen reader while browsing.

<button disabled>
  Continue
</button>

When you can’t use semantic HTML

This custom button requires extra attributes and JS event listeners. Adding tabindex="0" makes it focusable.

<div role="button" tabindex="0">
  Continue
</div>

When there’s no inner text that text doesn’t make sense

As a last resort, aria-label can be used.
aria-label will (typically) replace the inner text of the button for the screen reader output.
DO NOT repeat the inner text in the aria-label as some screenreaders will read both.

<div role="button" tabindex="0" aria-label="Continue">
  <!-- icon but no text -->
</div>

<div role="button" tabindex="0" aria-label="Add iPhone 17 to cart">
  Buy now <!-- Ambiguous text doesn't describe the intent -->
</div>

When there are repeating buttons

Sometimes the design will call for multiple buttons with the same text label. In a case like this, aria-label can be used to name each control’s purpose.

<button aria-label="Edit payment date">
  Edit
</div>
<button aria-label="Edit payment amount">
  Edit
</div>

Developer notes

Name

Inner text should describe the purpose of the button.
aria-label="Button purpose" can also be used (as a last resort)

Role

Native button identifies as button by default
Use role="button" for custom elements

Group

Use aria-haspopup="true" for menu, listbox or modal
aria-controls="popupId" is not well supported

State

Toggle buttons aria-pressed="true/false"
Menus or expanders use aria-expanded="true/false"
Use the disabled state for completely inactive buttons that shouldn’t be focusable
Use aria-disabled="true/false" state for inactive custom elements

Focus

Focus must be visible
Custom elements (like <div>) need tabindex="0" to be focusable