Version 5.2.0

Button

Buttons allow users to perform an action or to navigate to another page. They have multiple styles for various needs, and are ideal for calling attention to where a user needs to do something in order to move forward in a flow.

Anatomy#


Diagram illustrating through labels the component parts of a button including the label.

Options#


Key example of call-to-action button, label Enable. Primary button, label Continue.

Label#

All buttons require a label for accessibility. Unlike action buttons, these buttons should never be icon-only.

Key example of call-to-action button, label Action. Uses solid static-blue-600 background and bold static-white label.

Call to action variant#

The call to action button communicates strong emphasis and is reserved for actions that are essential to an experience. There should only be one visible call to action button per section. There is no quiet style for this button because it is meant to be intentionally prominent.

Key example of primary button, label Action. Has a 2px border in gray-800.

Primary variant#

The primary button is used for medium emphasis. It should be used in place of a call to action button when the action requires less prominence, or if there are multiple primary actions of the same importance on the page.

Key example of secondary button, label Action. Has a 2px border in gray-700.

Secondary variant#

The secondary button is for low emphasis. It is meant to be paired with other button types to surface less prominent actions, and should never be the only button in a group.

Key example of negative button, label Action. Has a 2px border in red-600.

Negative variant#

The negative button is for emphasizing actions that can be destructive or have negative consequences if taken. It should be used sparingly.

Key example of over-background button on top of a teal colored background, label Action. Has a 2px border in static-white.

Over background variant#

When a button needs to be placed on top of a colored background or a visual, use the over background button. This button appears in static white regardless of color theme. Make sure the background offers enough contrast for the button to be legible.

Key example of three buttons with icons, labeled Share. A call-to-action button, a primary button, and a quiet primary button.

Icon#

Icons can be used in buttons when additional clarity is required. Icons should not be used for decoration.

Key example of primary, secondary, negative, and over background buttons, labeled Action, in both standard and quiet styles.

Quiet#

By default, buttons have a visible stroke. Quiet buttons do not have this visible stroke and should only be used for secondary actions within a button group. An exception to this is the call to action variant, which does not have a quiet style because it is meant to be intentionally prominent.

Key example of disabled button, label Action.

Disabled#

A button in a disabled state shows that an action exists, but is not available in that circumstance. This state can be used to maintain layout continuity and to communicate that an action may become available later.

Table of options#

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework.

PropertyValuesDefault Value
label
text
variant
call to action / primary / secondary / negative / over background
call to action
icon
icon / nothing
nothing
is quiet
yes / no
no
is disabled
yes / no
no

Behaviors#


Button with placeholder label, all to action variant, in focus.

Keyboard focus#

A button can be navigated using a keyboard. The keyboard focus state takes the button’s visual hover state and adds a blue ring to the button in focus.

Key example of 3 call-to-action buttons with different widths based on labels Agree, Get started, Start experience.

Flexible width#

The width of a button automatically adjusts to fit the text. The padding on each side of the button is equal to half its height.

Key example of call-to-action button's minimum width of size-900, label OK. Quiet primary button without minimum width, label OK.

Minimum width#

Standard buttons have a minimum width of 2.25× the height of the button. This guarantees that small buttons retain an identifiable shape. Quiet buttons do not have a minimum width; their width depends exclusively on the length of the text.

Key examples of text wrapping for buttons. Call-to-action button and primary button, label Information about Creative Cloud in German in two lines of center-aligned text.

Text overflow#

When the button text is too long for the horizontal space available, it wraps to form another line.

Key example of button in Windows “high contrast black” theme with label “action” and disabled button with label “disabled”.

Windows high contrast mode#

In Windows high contrast mode, buttons should be displayed using the high contrast theme-specified colors for buttons. By default, borders should be same as the button text color. In hover and keyboard focus states, a border should display as the button border color. In the disabled state, border, and text color should display as the disabled color.

Button (Windows high contrast mode) UI kit

Usage guidelines#


Be concise#

Button text should be concise: 1 or 2 words, no longer than 4 words, with fewer than 20 characters including spaces. Don’t use punctuation marks such as periods or exclamation points.

Key example showing correct usage of concise button label. Call-to-action button, label Start experience.
Key example showing incorrect usage of concise button label. Call-to-action button, label Start the  experience right now!

Use clear text#

Button texts should be clear about the outcome of the action. Most buttons should start with a verb. For example, use “Agree” instead of “Yes” in a dialog or use “Sign Up” instead of “Submit” in a form.

Key example showing correct usage of clear button label. Call-to-action button, label Agree.
Key example showing ambiguous button label. Call-to-action button, label Yes.

Use sentence case#

Button text should always be in sentence case. Capitalization should never be used to give more prominence to a specific button.

Key example showing correct usage of sentence case in button label. Call-to-action button, label Get started.
Key examples showing incorrect usage of sentence case in button label. Call-to-action buttons, label get started in all-caps, all lowercase, and title case.

Don't override color#

Do not use custom colors for buttons. The colors of different button variations have been designed to be consistent and accessible.

Key example showing incorrect button background color in yellow.

Use icons only when necessary#

Icons can be used in buttons when additional clarity is required and the icon is highly relevant to the action. Icons should not be used for decoration.

Key example showing correct usage of icon in button. Call-to-action button with icon, label Share.
Key example showing incorrect usage of icon in button, where icons don't add clarity. Primary button with icon, label Cancel. Call-to-action button with icon, label More. Call-to-action button with icon, label Submit.

Display a popover when featuring subsequent options#

In some instances, it is possible to have a call to action button display a popover (or tray) to feature subsequent options for the action. These options should extend a single action, and should not contain arbitrary menu items.

Key example showing correct usage of popover menu featuring subsequent options. Call-to-action button, label New. Popover menu with 3 menu options labeled Document, Collection, Project.
Key example showing incorrect usage of popover menu featuring subsequent options. Call-to-action button, label More. Popover menu with 3 menu options that are not related to each other labeled Settings, Help and FAQ, Terms and conditions.

Internationalization#


Key example of a mirrored call to action button with icon on the right and label Share in Arabic on the left.

RTL#

For RTL (right-to-left) languages, the layout of the button is mirrored. The icon is placed on the right side of the text.

Keyboard interactions#


KeyInteraction
Space or EnterExecutes the button action. The focus remains on the button except if the button opens or closes the current container. In this case, the focus moves to the target or back to the caller.

Changelog#


DateNumberNotes
Apr 29, 20205.2.0
  • Added RTL (right-to-left) guidelines
  • Separated button group into its own component
Apr 13, 20205.1.1
  • Updated keyboard focus state to be more accessible
Aug 22, 20195.1.0
  • Added text overflow behavior
Jul 31, 20195.0.2
  • Updated text to use sentence case
Jun 13, 20195.0.1
  • Changed the text size to font size 100 (15 px to 14 px on desktop, 18 px to 17 px on mobile) and adjusted the baseline alignment. This is also reflected in components using buttons: coach mark, dialog, and toast.
Apr 20, 20195.0.0
  • This component is now individually versioned (individual versions of existing components start at 5.0.0)
  • Added button group overflow behavior

Design checklist#


All interactive states

Includes all interactive states that are applicable (hover, down, focus, keyboard focus, disabled).

Multiple options

Includes relevant options (variant, style, size, orientation, optional iconography, decorations, selection, error state, etc.)

All color themes

Works properly across all four color themes (lightest, light, dark, darkest).

All platform scales

Includes a desktop scale (UWP, macOS, web desktop) and a mobile scale (iOS, Android, web mobile).

Defined behaviors

Includes guidelines for layout (wrapping, truncation, overflow), animation, interactions, etc.

Usage guidelines

Includes a list of dos and don’ts that highlight best practices and common mistakes.

Accessible contrast

Follows WCAG 2.0 standards for contrast (AA).

Internationalization guidelines

Works properly across various locales and includes guidelines for bi-directionality (RTL).

Keyboard interactions

Follows WCAG 2.0 standards for keyboard accessibility guidelines and includes a description of the keyboard interactions.

Design tokens

All design attributes (color, typography, layout, animation, etc.) are included in Spectrum DNA.

Generated UI kit

Includes a downloadable XD file that has been generated by code and shows multiple variations, states, color themes, and scales.

In Spectrum for Adobe XD plugin

Component is included in the Spectrum for Adobe XD plugin.