Spectrum
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.
Table of contents#
Options#
Label#
All buttons require a label for accessibility. Unlike action buttons, these buttons should never be icon-only.
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.
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.
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.
Negative variant#
The negative button is for emphasizing actions that can be destructive or have negative consequences if taken. It should be used sparingly.
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.
Icon#
Icons can be used in buttons when additional clarity is required. Icons should not be used for decoration.
Size#
Buttons come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequent option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page.
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.
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.
| Property | Values | Default Value |
|---|---|---|
| label | text | – |
| variant | call to action / primary / secondary / negative / over background | call to action |
| icon | icon / nothing | nothing |
| size | small / medium/ large / extra-large | medium |
| is quiet | yes / no | no |
| is disabled | yes / no | no |
Behaviors#
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.
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.
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.
Text overflow#
When the button text is too long for the horizontal space available, it wraps to form another line.
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.
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.
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.
Use sentence case#
Button text should always be in sentence case. Capitalization should never be used to give more prominence to a specific button.
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.
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.
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.
Internationalization#
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#
| Key | Interaction |
|---|---|
| Space or Enter | Executes 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#
| Date | Number | Notes |
|---|---|---|
| Sep 29, 2020 | 5.3.0 |
|
| Apr 29, 2020 | 5.2.0 |
|
| Apr 13, 2020 | 5.1.1 |
|
| Aug 22, 2019 | 5.1.0 |
|
| Jul 31, 2019 | 5.0.2 |
|
| Jun 13, 2019 | 5.0.1 |
|
| Apr 20, 2019 | 5.0.0 |
|
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.
Action group