Buttons guidelines

Allow people to take action, make choices, and move forward.

The following documentation is common for all the Buttons.

Maturity

FYQ2 target

♼ Care

Overview

Types

There are two different types of Button components depending on their purpose. Each has different hierarchy levels, properties, elements, and uses. Here is a summary:

Name	Emphasis	When to use	Preview
Action Button	Secondary	Most actions	One or many, inline with the content
	Tertiary	Low emphasis actions: (More) Actions menu toggle
CTA Button	Primary	The next best action: Move forward or finish a main flow (One per region max.)	One or two, at the end of the region
	Tertiary	Dismissive actions: 1. Cancel 2. Skip Complementary actions: Use sparingly

Buttons vs. links

The standard rationale for when to use buttons or links is: A button does something; a link goes somewhere. However, we want to remain flexible.

In certain circumstances, the Action Button or CTA Button can be used as hyperlinks to content on other pages or websites. This means it has the look of feel of an Action Button or CTA Button but works like a link. For instance, if the link performs an action, like updating a user’s data, saving some edited content, or deep-linking to a dialog, it makes sense to have the button as a link.

To do this, either pass a href prop to a Button directly and it will work as a link and allow for any props that an <a> should allow for:


                                                        
                                                        
                                                            <ActionButton href="/preview" icon="preview">Preview</ActionButton>

Or if you are using a framework like NextJS, wrap the button with the NextJS Link:


                                                        
                                                        
                                                            import Link from 'next/link';
                                                        
                                                        <Link href="/preview" passHref legacyBehavior>
                                                          <ActionButton href="/preview" icon="preview">Preview</ActionButton>
                                                        </Link>

Further reading

Should I Use a Button or a Link? | Ashlee M Boyer

Despite being answered time and time again, the button vs. link question prevails.

https://ashleemboyer.com/blog/should-i-use-a-button-or-a-link

Anatomy

Properties

The following properties are jointly defined by design, engineering, and UX writing to speak a common language:

Name	Values	Default
Size Visual size of the Button	SM MD	SM
Destructive Signifies this action will cause data loss and can’t be undone	Boolean	False
Emphasis The hierarchy level that defines its visual prominence	Primary (CTA Button) Secondary (Action Button) Tertiary	Primary (CTA Button) Secondary (Action Button)
Disabled Disables interaction and focus and signifies it	Boolean	False
Waiting Signifies the action is taking place and can not be interacted with until it finishes	Boolean	False
Icon Only (Action Button) Hides the text label from the button. It will be displayed as a tooltip on hover/focus	Boolean	False

How to use

Hierarchy

Our three-level emphasis system

We have created a holistic emphasis system to create focus and hierarchy in our designs. We use visual properties such as color, size, space, and alignment. But there must be a direct relationship between the visible and the semantics to guarantee a good experience. Our system uses purpose as the cornerstone of our visual decisions.

Our Secondary Buttons will introduce an inconsistency temporarily.

Related content

Product Expression

The personality, essence, and approach we take when we create experiences.

Product Color

Guide the experience with coherence and emotion.

Destructive variant

Destructive actions permanently cause data loss. Because they can’t be undone, they will always require user confirmation. They are available on both components using the Destructive property.

De-emphasizing destructive actions

When a destructive action isn’t the next best, we might want to reduce the Action’s emphasis to Secondary to reduce its visual prominence and avoid distractions.

Button Label

The goal of a Button Label is to clearly communicate the action taken by a person. It should be predictable, explicit, consistent, and scannable.

Related content

UI text patterns

Reusable pieces of content to establish thoughtful, scalable, and consistent language

Clarity and conciseness

Write maximizing meaning with minimum wordiness. Be mindful of the space and the impact in translations.

⛔️ Avoid being vague

Labels should be concise but never unclear. People should immediately understand what will happen next.

✅ Use verb + noun combination

This will precisely express the action taken.

⛔️ Avoid getting wordy

In most cases, a one to three-word label is enough. Long labels are too long and harder to scan and read.

✅ Skip punctuation and articles

Removing punctuation marks and articles (”a,” “the”) shortens a label and makes it readable.

Capitalization

Overdoing labels is unnatural and more difficult to understand for everyone.

⛔️ Avoid title case or all caps

In title case capitalization and all caps, every word stands out too much. It means people might have difficulties scanning the text.

✅ Use sentence case capitalization

Sentence case capitalization feels natural and is easy to scan.

Accessibility and inclusion

Always recognize diversity in individuals’ needs and abilities, being self-aware of biases.

⛔️ Avoid being generic

Context may be invisible or harder to understand for some people.

✅ Be explicit

Clearly state what will happen if a person interacts with a button.

⛔️ Avoid referencing specific abilities and behaviors.

Use vision-related words such as "see" and "view" with caution, as they imply that people experiences the product in a visual way.

✅ Describe an action instead of a behavior.

When writing a label, think about an action a person is performing ("a person is opening a report"), not the behavior ("a person sees the report").

Conversational Labels

Labels should be practical rather than engaging.

⚠️ A precise and predictable button label will be the best choice for most cases.

If a label is vague, people may not understand the intended action and make a mistake.

⚠️ You can take a conversational approach when appropriate

In some experiences, such as onboarding or announcing new features, we can opt for a chatty, relaxed label that will mimic a natural conversation between two people.

Most common Button Labels

Add	Use add when a person puts an object in a new place or experience (for example, a prototype) and when they add objects one by one or in bulk (cards, blocks, etc.). → See also: Create, Invite
Apply	Immediately puts changes into effect without closing the window, for example, when using filters.
Cancel	Use when a person decides to undo an action. Don’t use undo.
Create	Use it when a person is about to make something new from scratch, especially when it’s a multi-step process, such as creating a maze or a project. Avoid using New, especially when it’s not accompanied by a noun. → See also: Add
Delete	Removes objects so they’re no longer available and can’t be restored. Don’t use in relation to people, for example, delete participant or delete user. In cases like that, it’s better to change the perspective to avoid the dehumanizing tone (delete profile, delete user data, etc).
Get started	Avoid. Get started is generic and ambiguous. Choose a more explicit button label.
Go to	Directs people to a particular place (for example, Go to Reach). When directing to the homepage, use Return instead. When referring to objects, use verbs (for example, write View report instead of Go to report).
Invite	Use invite when people want others to join Maze as it feels more human and conversational. Avoid using add.
OK, Done, Got it	Whenever possible, use context-specific, explicit labels led with verbs. Don’t use OK it as a label when informing about maintenance breaks or new features, and when explaining how things work. Use Got it instead. Don’t use OK or Done as a label when a person is about to confirm changes made. Use Save instead.
Remove	To remove something means we take away an object from the context or experience. The object isn’t deleted—it still exists. For example, we remove team members from a team. → See also: Delete
Save as	Use Save as when creating a new object from existing content or data, for example a segment created based on applied filters, or a template based on maze. → See also: Create

Further reading

UI Copy: UX Guidelines for Command Names and Keyboard Shortcuts

Labels for commands should be brief, informative, rely on verbs and adjectives, and avoid branded terms. Command shortcuts must limit the number of modifiers and follow standard conventions.

https://www.nngroup.com/articles/ui-copy/

Arrangement

Currently in definition—more details soon.

Typically, we use the F pattern to arrange our buttons.

⛔️ Don’t place Primary CTAs at the end

✅ Place the main action first on intrinsic width buttons

Sizing and Spacing

We use standard sizing and spacing for all interactive controls to improve the experience depending on the information density and make our interface more accessible, predictable, and easy to use.

Related content

Product Size

Create balance and uniformity with a predefined height scale.

Product Space

Create balance, organize information, and make our designs easier to scan and use.

Width

The width of our Buttons is intrinsic, which means that the Button doesn't stretch to fit the width of its container. The width depends on the length of the Button Label, plus the Icon—if present—plus the padding on either side of the Button. In Figma, this is called Hug contents in auto layout.

⛔️ Avoid full-width Buttons

Full-width buttons are a mobile pattern intended to support a coarse, low-precision pointer. Defining an ad-hoc size for each context is arbitrary and complex without supporting rules.

✅ Leverage the Button's intrinsic size

Intrinsically sized buttons simplify our code and usage rules and promote a consistent application across all use cases.

We have defined a min-width to ensure our Buttons have a generous and accessible target size regardless of the Button label's length.

Behavior

States

The state of a component can depend on properties set before people can interact with it. We call them state properties. Differentiating them from the user-triggered states allows us to combine them, creating richer states that cover the whole interaction spectrum.

Related content

Interaction States

Make the interactive components’ behavior predictable and explicit

Product Color

Guide the experience with coherence and emotion.

Default variants

Default buttons use the Awake color role in three emphasis levels explained in the hierarchy section

Destructive variants

Destructive buttons use the Critical color role in three emphasis levels explained in the hierarchy section

Disabled Buttons considerations

There may be good reasons for disabling Buttons. Sometimes we want to make it harder for our users to make mistakes and avoid unnecessary layout jumps between error messages. Or sometimes, we want to point out something important is missing before moving on to the next step.

But disabled buttons only communicate that something is wrong; they don't explain why. As a result, many users—especially non-tech-savvy ones—often get stuck wondering what's missing or what they've done wrong and end up frustrated. We are not helping them fix the problem and move forward, which should be our priority.

They also pose various accessibility problems. The most important one is that disabled buttons are usually not focusable and, therefore, cannot be accessed by users with a keyboard.

Recommendations

By default, show the Resting button; if the person presses it and there are remaining actions to perform, provide them with a meaningful in-context error message. This will remove complexity and avoid confusing people for unknown reasons.

⛔️ Avoid disabling by default

Disabled buttons can be confusing. People must figure out how to activate them instead of focusing on their tasks.

✅ Provide meaningful error messaging

Let people freely hit the button and provide meaningful in-context error messages to help them resolve their problems.

Related content

Error messaging

A good error message explains what’s going on, describes the reason for it, and guides people to resolve their problems.

Sometimes, people don't have permission to perform an action. In those cases, instead of showing a disabled button, consider hiding the action itself. Components have specific variants that provide more meaningful context.

⛔️ Avoid adding disabled buttons to indicate that a field is read-only

We are raising expectations by hinting that that button might be activated at some point and adding unnecessary complexity.

✅ Use the Readonly property to indicate that a field cannot be edited

You can directly indicate it in the field and spare the button when the edit action is unavailable.

When people need to perform other out-of-context actions or tasks to unlock an essential one, disabled buttons can be helpful. In these cases, ensure you provide enough context to unlock this action.

Responsive considerations

When a group of actions is displayed horizontally, the buttons will take the available container space. If the container gets smaller, the buttons will progressively conceal under a “More options” Tertiary button.

Acknowledgements

“Next Best Action” — a simple way to ensure user engagement, by H Locke

Uber Base: Buttons, by Uber design

Frustrating Design Patterns: Disabled Buttons, by Vitaly Friedman