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, icon, and hide label#
Buttons should always have a label for accessibility. They can also have an optional icon. An icon should only be used in a button when it's absolutely necessary and when it has a strong association with the label text. Icons should not be used only as decoration.
The label can be hidden to create an icon-only button. If the label is hidden, an icon is required and the label will appear in a tooltip on hover. Icon-only buttons are best for common, readily recognizable actions.
Accent variant#
The accent button communicates strong emphasis and is reserved for actions that are essential to an experience. Don’t use more than 3 accent buttons in the same view. These give extra prominence to important actions and are meant to establish a clear hierarchy.
Primary variant#
The primary button is for medium emphasis. Use it 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 in the same view.
Secondary variant#
The secondary button is for low emphasis. It’s 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. Use it sparingly.
Static color#
When a button needs to be placed on top of a color background or a visual, use the static color option. Static color buttons are available in outline or fill styles, in black or white, and don't change shades or values depending upon the color theme.
Use static black on light color or image backgrounds, and static white on dark color or image backgrounds, regardless of the color theme.
Static color buttons can appear in static white or black, regardless of color theme. The static color option allows for these to be placed on top of a custom background that is not part of a Spectrum color theme while still providing optimal contrast.
Style#
Buttons are available in either fill or outline styles. A button in the fill style has a solid background, since it’s meant to be intentionally more prominent than a button in the outline style.
An outline style button has a visible stroke and no background color, and should only be used for secondary actions.
Size#
Buttons come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page.
Justified#
A button can become justified. By default, it is not justified since the button size depends on the label and/or icon inside of each button. When a button is justified, it takes up the entire available container width.
Pending#
Buttons can indicate that a quick progress taking place (e.g., saving settings on a server). In this case, the label and optional icon disappear and a progress circle appears. The progress circle always shows an indeterminate progress.
Use the pending state for a button sparingly. It should be reserved only for when the progress is supposed to be quick (taking 5 seconds or less), and when there is no better way to communicate as such.
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 | – |
| hide label | text | – |
| icon | icon / nothing Icon must be present if the label is hidden. | nothing |
| variant | call to action / primary / secondary / negative | call to action |
| static color | none / white / black | none |
| style | fill / outline | fill |
| size | small / medium/ large / extra-large | medium |
| justified | yes / no | no |
| is pending | 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.
Tooltip when the label is hidden#
When the button label is hidden, a tooltip is shown on hover that displays the label text and, if appropriate, a keyboard shortcut.
Flexible width#
The width of a button automatically adjusts to fit the label text. The padding on each side of the button is equal to half its height.
Minimum width#
Buttons have a minimum width of 2.25× the height of the button. This ensures that small buttons retain an identifiable shape.
Text overflow#
When the button text is too long for the horizontal space available, it wraps to form another line.
Cursor direction#
Buttons use the default arrow cursor for all states, including hover and down. The only exception occurs on the web; if the button is using the href property it will display the pointer cursor instead.
Delay before pending state#
Some progress can be very quick. In order to avoid showing a progress circle for a fraction of a second, which results in an unpleasant flickering, there is a delay of 1 second before the pending state appears. During this delay, the button continues to visually respond to interactive events (e.g., hover), but additional clicks do not result in repeated submissions.
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#
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.
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.
When to use static black and static white#
To ensure maximum contrast with the background, use static black for light backgrounds and images, and use static white for dark backgrounds and images. Avoid placing static components on top of busy images with a lot of variance in contrast.
Don't use the pending state for long progress#
The pending state should be reserved for indeterminate actions that are expected to take 5 seconds or less. For determinate or longer actions, use a progress bar or progress circle outside of the button.
Use a button group to show additional actions#
Instead of a single split button (now a deprecated component), use a button group to show any additional actions related to the most critical action.
Display a popover when featuring subsequent options#
In some instances, it's possible to have a call to action button display a popover (or tray) to feature subsequent options. These options should extend and parallel the action of the button. Do not include arbitrary or unrelated options.
Content standards#
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.
Write labels as verbs#
A button represents an action, so its label needs to reflect the action that a user is taking — which is a verb. Labels written as nouns or adjectives tend to be unclear and disorienting.
Clearly state the action#
Make sure that a button’s label clearly states the outcome of the action. Use the same word or phrase as found elsewhere in the experience.
For example, when designing a form for people to sign up for a trial offer, use “Sign up” as the call to action for completing the form. Phrases like “Start trial” skip the sign up step. Words like “Submit” or “Enter,” while technically correct, focus on the action of finishing filling out the form itself, rather than what the user is actually doing by filling it out (signing up for something).
Use sentence case#
Button text should always be in sentence case. Never use capitalization to emphasize a specific button.
Be aware of tone#
Emoji and exclamation points aren’t appropriate for the functional, utilitarian nature of buttons. Keep the label to just text, with no punctuation or extra decoration.
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 |
|---|---|---|
| Nov 01, 2021 | 6.0.0 |
|
| 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).
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).
Accessible use of color
Color is not used as the only visual means of conveying information (WCAG 2.0 1.4.1).
Accessible contrast for text
Text has a contrast ratio of at least 4.5:1 for small text and at least 3:1 for large text (WCAG 2.0 1.4.3).
Accessible contrast for UI components
Visual information required to identify components and states (except inactive components) has a contrast ratio of at least 3:1 (WCAG 2.1 1.4.11).
Content design
UI language and information design considerations have been incorporated into component design.
Defined options
Includes relevant options (variant, style, size, orientation, optional iconography, decorations, selection, error state, etc.)
Defined behaviors
Includes guidelines for keyboard focus, layout (wrapping, truncation, overflow), animation, interactions, etc.
Usage guidelines
Includes a list of dos and don'ts that highlight best practices and common mistakes.
Writing guidelines
Includes content standards or usage guidelines for how to write or format in-product content for the component.
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 available as design tokens.
UI kit
Includes a downloadable XD file that shows multiple options, states, color themes, and platform scales.
Generated UI kit
Includes a downloadable XD file, generated by code using design tokens defined in Spectrum DNA, and shows multiple options, states, color themes, and platform scales.
In Spectrum for Adobe XD plugin
Component is included in the Spectrum for Adobe XD plugin.
Action group