Buttons

On this page

Example

Designer guidance

Developer guidance

Content editor guidance

Accessibility 

Support

Primary button

Secondary button

Designer Guidance

When to use

Use a button when you want users to take a clear, direct action. Buttons are suitable for:

• Submitting forms.
• Saving or updating data.
• Deleting or removing an item.
• Opening a modal or dialog.
• Moving to the next step is a journey.
• Starting a search or filter action.

When not to use

Avoid using a button :

• For navigation - If the action takes the user to another page, use a link instead.
• For non interactive content - Don’t use buttons to display information, or show passive or static content.
• When multiple actions compete - Avoid placing too many buttons of equal weight close together. This can confuse users and dilute the importance of the primary action.
• Disabled with no context – If you need to disable a button, make sure the interface explains why and what users need to do to activate it. In some cases, consider hiding the button until it becomes available or using inline help instead.

How to use

1. Choose Between Buttons and Links:
   Determine whether your element should guide users to another page or perform an action. Use links for navigation and buttons for interactive tasks like submitting data or activating JavaScript functions.
   
2. Choose Primary vs. Secondary Buttons:
   If you've decided on a button, consider it's importance. Is it the main action users should take on the page? If yes, use a primary button style. Otherwise, opt for a secondary button to keep it less prominent and allow primary actions to stand out. Limit primary buttons to one per page, if possible.

Behaviours

• Buttons maintain the same size across breakpoints for predictable interaction.
• Button sizing collapses to hug content, while maintaining a minimum tap target size (44x44px) for accessibility.
• Hover and focus states must provide clear visual feedback.
• Disabled buttons must look inactive and must not receive focus.

Options

Buttons are available in two variants:

• Primary: Uses a solid background with high visual emphasis. Use for the main action in a given context. Only one primary button should appear per page or section.
• Secondary: Uses an outlined style to show supporting actions. The border should match the button’s variant. Multiple secondary buttons can be used in the same context.

Both variants are available for light and dark backgrounds.

Developer Guidance

Best practices

• Use semantic HTML <button> for actions.
• Do not use <role="button"> unless absolutely necessary.
• Apply visible focus styles for keyboard users.
• Ensure visible focus states meet contrast requirements.
• Ensure buttons are operable via keyboard (Enter, Space).
• Ensure button text is programmatically accessible.
• Do not rely on colour alone to indicate state.
• Disabled buttons must not be focusable.
• The button must have a minimum target size of 44px x 44px. 

Content Editor Guidance

Best practices

• Use buttons for buttons and links for links. These have different code markup and are read differently by screen readers. 
• Use clear, concise, descriptive labels to help screenreader users understand their options. 
• Maintain clear visual hierarchy on the page by using secondary buttons for any button-actions which are not the main page CTA.
• Maintain visual contrast by using the right button style for background colour. 
• Keep button text short, ideally two or three words. 
  • Use action verbs like "buy," "submit," or "download"
  • Make sure the text clearly describes the action users will take and what will happen next, such as "search" or "subscribe." 
  • Ensure copy makes sense to screenreader users without wider context. 
  • Use sentence case without any punctuation. 
  • If including the same button multiple times, use the same copy.


Accessibility

Accessible buttons must:

• Use semantic HTML that expose correct name, role, and state.
• Have text labels that clearly describe the action
• Provide visible focus indicators for keyboard users
• Offer clear hover states
• Provide sufficient contrast for text, borders and focus styles
• Be operable with a keyboard using Enter and Space
• Maintain a minimum target size of 44x44px
• communicate disabled states programmatically.
• Not rely on colour alone to indicate interaction

WCAG success criteria

• 1.3.1 Info and Relationships (Level A)
  Buttons must be coded with the semantic <button> element (or equivalent with role="button") so their purpose and state are programmatically conveyed.
• 1.4.3 Contrast (Minimum) (Level AA):
  Button text and icons must have a contrast ratio of at least 4.5:1 against the button background.
• 2.1.1 Keyboard (Level A):
  Buttons must be operable via keyboard (using enter or space) without requiring a mouse or pointer.
• 2.4.3 Focus Order (Level A):
  Focus should move through buttons in a logical and expected sequence.
• 2.4.7 Focus Visible (Level AA):
  A visible focus indicator must be provided so users can clearly see which button is active when tabbing.
• 2.5.5 Target Size (Enhanced) (Level AAA):
  Buttons should have a minimum clickable area of 44×44px for easier touch and pointer activation.
• 3.2.4 Consistent Identification (Level AA):
  Buttons that perform the same action should use consistent text, icons, and placement across the site.

Related components

Link