Button
Buttons allow users to perform an action or navigate to another page. They have multiple variants for various needs and are ideal for calling attention to where a user needs to act.
Anatomy
- 1 Container — provides the hit target, border, and fill
- 2 Label — describes the action the button performs
Options
Variants
The solid variant communicates strong emphasis and is reserved for primary actions. Outline is for medium emphasis. Ghost is for low-emphasis or tertiary actions and should never be the only button in a group.
Disabled
A disabled button shows that an action exists but is not available in the current state. Use it to maintain layout continuity and communicate that the action may become available later.
Table of options
| Property | Values | Default |
|---|---|---|
| label | text | — |
| variant | solid / outline / ghost | solid |
| type | button / submit / reset | button |
| disabled | true / false | false |
| start icon | icon name / none | none |
Behaviors
Flexible width
The width of a button automatically adjusts to fit the label text. Padding on each side is equal to half the button height.
Text overflow
When the button text is too long for the available horizontal space, it wraps to form another line.
Keyboard focus
A button can be navigated using a keyboard. The keyboard focus state takes the hover state and adds a visible focus ring to the button.
Variant hierarchy
Solid, outline, and ghost variants create a visual hierarchy. Use solid for the primary action, outline for secondary, and ghost for tertiary.
Disabled state
A disabled button shows that an action exists but is not available. It is removed from the tab order and communicates its state to assistive technology.
Usage guidelines
Use the right variant for the emphasis level
Do
Use solid for the primary action and outline or ghost for secondary actions.
Don't
Don't use multiple solid buttons at the same emphasis level — it removes hierarchy.
Don't override color
Do not use custom colors for buttons. The token-driven colors are designed to be consistent and accessible across brands and modes.
Do
Use the default token-driven button colors.
Don't
Don't hardcode custom background colors on buttons.
Use a button group for related actions
Use ButtonGroup to keep related actions visually and semantically grouped.
Do
Group related actions in a ButtonGroup to show their relationship.
Don't
Don't scatter related actions without a grouping container.
Button group markup
<div
class="button-group"
role="group"
aria-label="Travel dates"
data-orientation="horizontal"
data-attached="false"
data-justify="start"
>
<button class="button outline" type="button">Day 1</button>
<button class="button outline" type="button">Day 2</button>
<button class="button outline" type="button">Day 3</button>
</div>
orientation:"horizontal"(default) or"vertical"attached:false(default) removes shared borders/gaps whentruejustify:"start"(default) or"stretch"
Content standards
Be concise
Button text should be 1–4 words, fewer than 20 characters including spaces. Don't use punctuation.
Write labels as verbs
A button represents an action, so its label needs to be a verb. Labels written as nouns or adjectives tend to be unclear.
Do
Use a verb that describes the outcome of the action.
Don't
Avoid vague labels that don't describe the specific action.
Use sentence case
Button text should always be in sentence case. Never use all-caps or title case to emphasize a button.
Keyboard interactions
| Key | Interaction |
|---|---|
| Space or Enter | Executes the button action. Focus remains on the button unless it opens or closes a container. |
| Tab | Moves focus to the next focusable element. |
| Shift + Tab | Moves focus to the previous focusable element. |
Accessibility
- Use
<button>for actions and<a>for navigation — never style a link as a button for an action. - Every button must have a visible text label or an
aria-labelwhen icon-only. - Disabled buttons use the native
disabledattribute, which removes them from the tab order and communicates the state to assistive technology. - Focus indicators meet 3:1 contrast against the surrounding background.
- Color is not the only means of distinguishing variants — shape, border, and fill provide additional differentiation.
Theming
Button adapts automatically across brands and color modes through component tokens. Use the hero preview switches above to see it in action.
For the full theming architecture — brands, modes, and how tokens cascade — see Foundations: Theming.