Usage
- Use to confirm an action or make a change.
- Use to move users through a sequence of screens.
- Use to take users to a different part of the browser, such as their settings.
- Don't use in place of links. Links direct a user to a new page. Buttons make a change or confirm an action.
- Don't use to navigate in-page or to new pages.
Properties
| Property | Values | Default |
|---|---|---|
| Size Variant | Default | Small | Default |
| Type Variant | Primary | Secondary | Destructive | Primary |
| State Variant | Default | Hover | Active | Focus | Default |
| Theme Variant | Light | Dark | Light |
| Disabled Variant | On | Off | Off |
Size
- Small buttons are only used for smaller UI surfaces. e.g. Infobar.
Types
Default (Secondary)
- Use for secondary actions e.g. Cancel
- Use for multiple actions of equal importance
- May appear beside a primary button or alone
High contrast mode has different themes. The examples shown below are from Windows 11.
Night Sky theme
Desert theme
Primary
- Use to call attention or highlight the preferred call to action on a screen or page
- Use a primary button only once per screen
- Not every screen requires a primary button
High contrast mode has different themes. The examples shown below are from Windows 11.
Night Sky theme
Desert theme
Destructive
- Use to deliberately create friction to warn users of the impact of an action that could be difficult or impossible to undo. e.g. deleting data.
- Most commonly found in confirmation modals
When designing for High contrast mode, we cannot use colors outside of the user's chosen palette, like the reds used in the destructive/danger button.
Use a primary or regular button instead.
Writing guidelines
Button label text should be clear, descriptive, and use active verbs so people know what to expect when they interact with the button.
- Write labels in sentence case. See iOS for specific writing guidelines.
- Lead with clear action verbs that convey outcome.
- Use Choose or Select in place of Click or Tap.
- Be consistent with terms inside the button and any instructional text.
- When possible, include labels when using icons.
- Use unnecessary words or articles, such as "the, an, or a".
- Use ellipses in a label unless it leads to additional choices
- Use “OK” as a label, button labels should always be actionable and lead to what comes next
Casing: Write button text labels in sentence case. Capitalize the first word and lowercase the rest (unless the text contains a proper noun).
Width: Set a max width for the button, designing for at least 50+ string growth compared to English. Buttons themselves should not have a hard-coded fixed width — width is determined by length of text labels.
Stacking: Allow buttons to grow as much as they need to within the max width. When you have two buttons and they don’t fit in the same line, then wrap the button component itself (not the button text). The secondary button will move to the second line. Both buttons will be the same width.
Accessibility
Changelog
|
Date |
Version |
Notes |
|---|---|---|
|
Apr 17, 2025 |
2.0.0 |
Simplified template |
|
Apr 22, 2024 |
1.3.0 |
Added Storybook link |
|
Oct 5, 2023 |
1.2.0 |
Added restructured types, states and modes |
|
Mar 28, 2023 |
1.1.0 |
Added HCM theme info, and fixed some typos |
|
Feb 15, 2023 |
1.0.0 |
Initial draft of button guidance |