Button

Definition

An interactive visual element that indicates an available action for the user.

Anatomy

Defining shared language for discussing the construction and structure of this component.

Key	Category	Parts
1	Shape	Border radius, border color
2	Shape	Background color
3	Shape	Padding (block [top, bottom], inline [left, right])
4	Text	Font family, size/line height, color

Usage

Storybook (previews work best on Firefox)

Buttons are for making a change to page state, submitting, or initiating an action.

When to use

Confirm an action or make a change.

When NOT to use

Don't use buttons in place of links.

Don't use buttons to navigate in-page or to new pages.

Variants

Figma library (internal only)

HCM library (internal only)

Acorn offers 3 button types in 2 sizes, with 5 states across 3 modes (themes).

Sizes

Acorn has 2 sizes for buttons, default and small.

Small buttons are only used for smaller UI surfaces. e.g. Infobar

Only Regular (Secondary) and Primary buttons may use the small size.

States

Available states are as follows: default, hover, active, focus, and disabled.

The focus and disabled states have important caveats that apply across types and modes.

Focus

:focus states are used for keyboard navigation and sometimes when clicking a focus-able element using a mouse. Focus states are vital for accessibility and may not be omitted.

The CSS pseudo class :focus does not affect visual output in iOS or Android.

Disabled

Disabled visual styles should only be applied when a button is disabled.

Disabled buttons are unusable. Disable a button to keep users from interacting with the button until conditions are met.

All images are illustrative only. For precise examples see our Figma library.

Regular (secondary)

Figma component (internal only)

Currently known as "Secondary" in our Figma library file.

A regular button may appear beside a primary button, or alone.

Use for secondary actions. e.g. Cancel

Use for multiple actions of equal importance.

Don't

Use a regular button in place of a primary button.

Examples

Additional states are represented in our Figma library.

High contrast mode has different themes. The examples shown below are from Windows 11.

Desert theme

Night Sky theme

Primary

Figma component (internal only)

Use to call attention or highlight the preferred call to action on a screen or page.

Don't

Use a primary button more than once per screen.

Use a primary button on every screen.

Examples

Additional states are represented in our Figma library.

High contrast mode has different themes. The examples shown below are from Windows 11.

Desert theme

Night Sky theme

Destructive (Danger)

Figma component (internal only)

Destructive type buttons use a different name (danger-button) in code implementations.

Most commonly found in confirmation modals.

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.

Don't

Overuse destructive buttons.

Examples

Additional states are represented in our Figma library.

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.

Behavior and interaction

Buttons are interactive elements, when a user engages a button there should be positive, non-blocking, accessible feedback that the interaction was successful.

This is possible through visual state changes on :hover, or :focus.

A button's outcome should be clear to the user before it is "pressed".

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.

Don't

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.

Localization

Avoid colloquialisms that don’t translate well or prove a barrier to understanding.

To pressure test designs, use tools like Google Translate or Transvision to see how design reacts to Chinese, English, and German.

Not sure? Check with #l10n in Slack.

Accessibility

Use a text label color that has sufficient color contrast with your button's background color. Check contrast across all states.

Use an appropriate font size for your text label, ensuring proper legibility.

Provide alternative text for all buttons.

Use a sufficient amount of padding to ensure your button is large enough to reduce frustrating click or touch scenarios.

Need guidance? Check with #accessibility in Slack.

Changelog

Date	Version	Notes
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

Status checklist

Overview of this component's status.

All States

Includes all applicable states (hover, focus, disabled, etc...)

All Themes

Works properly across all themes (theme name, theme name, etc...)

All Modes

Works properly across all modes (light, dark, high contrast)

All Desktop Environments

Works properly across all environments (Windows, MacOS, Linux)

All Mobile Environments

Works properly across all environments (iOS, Android)

Overall Accessibility

Has been tested and reviewed by A11y Team.

Color / Accessibility

All color has been tested against and passed all the latest WCAG 2.1 A & AA standards.

Text / Accessibility

All text has been tested against and passed all the latest WCAG 2.1 A & AA standards.

Contrast / Accessibility

All contrast has been tested against and passed all the latest WCAG 2.1 A & AA standards.

Interaction / Accessibility

All interactions have been tested against and passed all the latest WCAG 2.1 A & AA standards.

Content Design Review

Has been tested and reviewed by Content Design Team.

Writing Guidelines

Follows guidance for writing and language use.

Localization

Works properly across locales, and includes guidance for RTL languages.

Defined Behavior

Guidance for behavior when interacted with.

Defined Interactions

Guidance for interaction capabilities, ie. keyboard interactions.

Usage Guidelines

Includes guidance for usage, dos and don'ts, best practices.

Tokens

All attributes are available as tokens.

Figma Library

Has a reusable Figma component.

Storybook

Is documented in Storybook.

Code

Has a code counterpart.