Button

Button is a primary UI element that can trigger an action in a flow.

Design

Web component

Is documented

Status

Healthy

Figma component

Storybook

Principles

Use when

  1. there is a request or a transaction that needs to be occur.
  2. progressing an interaction to imply any behavior or flow.
  3. enabling the common actions such as creating, canceling, resetting, deleting, archiving.
  4. enabling the CRUD (create, read, update, delete) actions.

Use don’t when

  1. redirecting to an external resource, use a link instead.
  2. as a navigation element, use a check out tab or content switcher instead.
  3. if the element doesn't trigger any action or interaction.
  4. there are informational messages or alerts where users don't need to take any immediate action.

Structure

button-structure
  1. Button label
  2. Icon
  3. Container

Variants

button-types

Primary

Primary button is the principle button and has the highest emphasis on a page. Also, it should used once on the context.

Secondary

The secondary button is used to support the main action (primary button) with secondary prominence, offering additional actions.

Outline

Outline button are ideal for less prominent actions, standalone or with a primary button for multiple calls to action, and for sub-tasks when a primary action button is present.

Ghost

The ghost button has the least emphasis on a page and is used to support primary and secondary buttons when they are used together.

Destructive

Destructive buttons are used when an action (for example: delete, remove, etc.) leads to a dangerous, destructive, irreversible outcome on users’ data or record.

Destructive-outline

Destructive-outline buttons serve the same role as destructive buttons but with lower emphasis.

Sizes

button-sizes

Small

Use when there is not enough vertical space for the default or field-sized button in areas such as modal, widgets etc.

Default

Use as primary layout actions and other standalone actions.

Large

Use for pages like login, sign-up, and password reset containing only a couple of inputs.

States

Enabled

Enabled button when it is interactive and ready to be clicked.

Hover

The hover states indicates that the button is interactive and can be clicked. On icon button, a tooltip can be used while hovering.

Focus

When the button is focused via the tab key, it is ready to be activated.

Active

Active state is the button is in the process of being activated.

Disabled

The disabled state indicates that the button is not currently interactive and communicates that an action is unavailable.

Busy

The busy state lets users know the button is on action or task, using a spinner. In this state, the button is temporarily unavailable for interaction.

Modifiers

button-modifiers

Text label

Text-only buttons, common in our products, convey actions through labels.

Storybook failed to load. Please connect to the VPN to access.

Text label with icon

Text label with icon buttons are used when action needs to be supported with an icon.

Storybook failed to load. Please connect to the VPN to access.

Icon button

An icon button expresses the action solely through its icon. Each button type (primary, secondary, outline, ghost) can be used as an icon button.

Icon buttons are typically used in areas where text or text+icon buttons don’t fit in its container, or where buttons need to be used in a toolbar format.

Storybook failed to load. Please connect to the VPN to access.
button-modifier-do

Use tooltip for the related action that represents as icon on a button.

button-modifier-don't

Avoid using icons that are difficult to describe or may be hard to predict as icon buttons, use text button with icon instead.

Behavior

Placement

Buttons should be placed in a location that is relevant to the context of the task or action they take.

Proximity to actions

button-placement-do

Ensure that when buttons are used in a group, they are positioned at the correct distance from each other on modals and cards.

button-placement-do

Buttons should be close to the content or form elements they are associated with.

Alignment

Maintain consistent alignment across similar types of buttons.

button-alignment-do

In areas where approval is required, the cancelling and approve buttons should be positioned with the main CTA on the right.

button-alignment-do

The action with greater emphasis according to the context should be used as the primary action and should also be aligned to the right.

Width

Buttons should be hug content with their labels; however, they can be used as full-width in widgets or cards.

button-width-do

In areas like login/sign-up flows, the button can be used as full-width considering the usage of other components.

button-width-do-2

When using widgets to list similar actions according to the context and their emphasis, these buttons can take the size of the container.

Icon usage

Icons should support and enhance the text label, not replace it. Exceptions include icon-only buttons in toolbars where space is limited.

Icon placement

button-icon-do

Icons should be placed to the left of the text label to maintain what is label’s express directly.

button-icon-do-2

However, the text label indicates the direction of actions such as next, proceed, add, back, or open menu. The icon should be placed to the right of the text label. Do not place the icon to the right except in these situations.

Emphasis

button-emphasis

The emphasis of buttons should be carefully considered to establish a clear visual hierarchy and guide users towards the most important actions. Different button types (primary, secondary, outline, ghost, destructive) should be used to create this hierarchy.

It's important to ensure sufficient contrast between these different button types and the background to maintain visibility and usability. This is especially crucial for primary and destructive buttons, as they often represent the most critical actions on a page.

Content

The button labels should always be simple enough to describe the action in the simplest way possible. This way, when a user interacts with a screen, the buttons on the UI will help reduce visual load.

Also, if a button is used for an action related to accounting terms, it should be labeled using terms that the user is familiar with.

button-content-do-1

Buttons are always should be sentence case.

button-content-don't-1

No ALL CAPS allowed.

button-content-do-2

Always state the action with noun+verb.

button-content-don't-2

Choose words that support the action itself, such as on create, edit, and so on.

Figma source