Guidelines
When to use
- To trigger actions: Use Button for actions that allow users to interact with the page, like submitting forms, creating an entity, confirming choices, canceling, opening filters, etc.
When not to use
- Navigation: Do not use buttons to navigate between pages. Use Links instead.
- Form controls: Do not use buttons to replace form fields, such as Select, Number Input, etc.
Best Practices
- One Primary Button per screen: As a general rule, a page should have only one Primary Button, making it clear that other buttons have less importance in the hierarchy.
Use only one Primary Button.
Don't use two Primary Buttons together.
Button variants
- Primary: A Primary Button is used for the most important action of the page. Only one Primaty Button should be visible on the screen to keep visual balance and avoid overwhelming the user.
- Secondary: Secondary Buttons are typically used for additional actions, complementing a group that already includes a Primary and a Tertiary Button, such as the Export action on Side Panels.
- Tertiary: Tertiary Buttons have a more subtle design and are ideal for pairing together without cluttering the layout. They can be used multiple times in scenarios like Page Headers or alongside other Button variants. They are commonly used to complement the Primary Button, like canceling actions in Dialogs.
- Ghost: Ghost Buttons have no fill or outline. They are best used for subtle actions that generate minimal visual noise. Use with caution, as sometimes they may not be perceived as buttons, which can affect accessibility.
- Destructive: Destructive Buttons represent critical actions, such as deleting or removing content. They're typically used in Dialogs for irreversible confirmations.
Combining variants
Variant names were defined based on style, not usage. This means that grouping buttons won’t follow their naming convention.
A general rule is to pair a high-emphasis button with a lower-emphasis button. Typically, it means combining a Primary Button with the Tertiary variant. Secondary Buttons, while less prominent than the Primary, use accent colors that can be visually heavy, so they are not the first variant choice of pairing different Buttons.
Common combinations
- Multiple actions: In layouts requiring multiple actions, such as page headers, data lists, or dashboards, it’s best to group low-emphasis buttons together to maintain visual balance. For such cases, we usually use Tertiary Buttons.
- Dialogs and Panels: Use a Primary Button for confirmation and a Tertiary Button for actions like canceling or going back. Secondary Buttons should only be used when an extra action is necessary, such as Export.
Combine the same variant of a low-empashis button when multiple actions are needed.
The Tertiary variant is the preferred option when combining a Primary Button with another Button.
Sizes
The Medium variant is the default size for desktop screens, and the Extra Large is used for touch devices.
- Small: Ideal for dense UIs with a lot of content and actions, such as Table actions.
- Medium: The default size for most desktop actions, commonly used in Dialogs, Panel footers, Page Headers, Forms confirmation, etc.
- Large: Best for layouts that require more space. Also used for touch devices like tablets.
- Extra Large: Primarily used for mobile screens, offering the largest touch area for improved accessibility.
Position
The position of a button depends on its context and whether it’s contained within another component or element.
Full Page
The Primary Button is typically aligned to the left when used alone on full-page designs. This positioning aligns with the user’s natural reading direction, making it the focal point, especially on larger screens.
Within an Element
When part of a composition or component, the Primary Button is usually aligned to the right, like in Page Headers, Dialogs, Cards, Progress Indicators, and Data Tables.
When paired with a Tertiary Button (for actions like canceling or going back), the Tertiary Button is typically aligned to the left. This is common in elements such as Side Panels, Dialogs, and Page Footers.
Icons
An optional Icon property is available to add context and help users understand the button's action. To use an icon, enable the Start Icon option. The End Icon should only be used on Dropdown Buttons.
Use the Start Icon to emphasise the button's content.
Don't use the End Icon on regular buttons.
Content
Start with a verb
Use clear, specific verbs that describe what the button does.
✅ Save, Send invoice, Add guest
Keep it short
Aim for 1–3 words. Buttons should be quick to scan.
✅ View details
🚫 Click here to view more information
Be specific
Avoid vague labels like Submit or Confirm. Make the outcome clear.
✅ Request booking
🚫 Submit
Use sentence case
Only capitalize the first word.
✅ Create policy
🚫 Create Policy
Connect to the content around it
You might use the same words at the page or dialog title to help guide the user to follow through with their intended action.
Think globally
Remember that most other languages are longer than English.