# Button Hierarchy: What Design Systems Recommend

> What do Apple, Google, IBM, GitHub, Microsoft and Adobe's design systems recommend for button hierarchy? One primary, order, destructive actions, labels.

Source: https://omergulcicek.com/en/blog/button-hierarchy-design-systems

When three primary buttons sit side by side on a page, you are offering the user three different "main actions." They have to stop and think about which one to press, because the interface isn't telling them what comes next.

Button hierarchy solves exactly this: it ranks buttons by visual weight and shows the user **which action is the main one and which ones are secondary**. In this post I've gathered what the design systems of Apple, Google, IBM, GitHub, Microsoft, Adobe, Atlassian, Shopify and GOV.UK recommend. The goal isn't to crown one "right" system; it's to see where the sources agree, where they part ways, and to pull out the core idea.

## Levels of emphasis

Each system names its levels differently, but they all describe the same idea: how much attention a button draws tells you how important its action is.

| System | Strongest to weakest |
| :--- | :--- |
| Google · Material 3[^m3-button] | Filled, tonal, elevated, outlined, text |
| IBM · Carbon[^carbon] | Primary, secondary, tertiary, ghost |
| Atlassian[^atlassian-button] | Primary, default, subtle |
| Shopify · Polaris[^polaris-button] | Primary, secondary, tertiary |
| GitHub · Primer[^primer-button] | Primary, secondary (the most common) |
| Apple HIG[^apple] | Prominent style and the primary role, everything else regular |

Emphasis comes from color, fill and borders. A filled button draws the most attention, an outlined one less, a text-only one the least. Apple adds an important detail here: set the preferred option apart **with style, not size**. Buttons in the same group should be the same size; the style should carry the difference.[^apple]

There's also something most people overlook: according to Primer, most buttons should be secondary.[^primer-button] Primary is the exception, not the default.

## Where the sources agree: one primary

Nearly every source says the same thing: an area has a single main action. What differs is how big that "area" is.

| System | Rule |
| :--- | :--- |
| IBM · Carbon[^carbon] | One primary per screen; the app header, modals and side panels don't count toward it |
| GitHub · Primer[^primer-button] | One primary per page where possible |
| Atlassian[^atlassian-button] | One primary per area |
| Microsoft · Fluent 2[^fluent] | One primary per layout |
| GOV.UK[^govuk] | One button for the page's main call to action |
| Shopify · Polaris[^polaris-button] | Use primary sparingly |
| Apple HIG[^apple] | One or two prominent buttons per view at most |
| Adobe · Spectrum[^spectrum] | Up to 3 accent buttons per view |

Apple and Spectrum being more flexible doesn't break the rule; both set a limit to protect the hierarchy. Apple states the reason plainly: the more prominent buttons there are, the harder people have to think to make a choice.[^apple]

Fluent says something worth remembering: if more than two buttons are equally important, don't make any of them primary; **leave them all neutral**.[^fluent] Primary is how you say "this one matters more." If no action matters more, there is no primary.

GOV.UK points at the root of the problem: if a page has too many calls to action, the fix isn't more button styles; it's simplifying the page or splitting it up.[^govuk]

## What secondary is for

It's common to think of secondary as "the second most important button," but Carbon gives a sharper definition: secondary is **the action that opposes the primary one**. Cancel, Back, Discard. That's why, in Carbon, secondary isn't used on its own and isn't used for a positive action.[^carbon] Atlassian likewise recommends a subtle button next to the primary for side actions like Cancel.[^atlassian-button]

Minor but independent actions, say "Export" in a page header, go to weaker levels: tertiary or ghost in Carbon,[^carbon] a text button in Material.[^m3-button]

## Where the sources split: order

The real debate is where the primary button goes. Below you can see the same two actions laid out by each system's own rule, both on a page and in a dialog. Where a system has no rule for a context, the demo says so; I didn't fill the gaps with guesses.

As you can see, in dialogs most of them put the primary on the right: Apple,[^apple-alerts] Material,[^m3-dialog] Carbon,[^carbon] Primer,[^primer-dialog] Atlassian[^atlassian-modal] and Spectrum.[^spectrum-group] Windows does the opposite; OK sits to the left of Cancel.[^nng] On a page, Carbon, Fluent, GOV.UK and Spectrum put the primary on the left, aligned with the content.

Two different logics sit behind this split:

- **Reading order:** In a left-aligned form the eye starts at the left, so the main action comes first. Spectrum makes this an explicit rule: order follows text alignment; in a left-aligned layout the most important button is on the left, in a right- or center-aligned one it's on the far right.[^spectrum-group]
- **End of the flow:** In dialogs and wizards the user moves "forward," and forward is on the right. So the confirming button goes last.

NN/g puts this debate to rest nicely: the order of OK and Cancel is a small detail that rarely affects usability. On desktop, follow the platform's convention; on the web, follow the platform most of your users use. The real mistake is using different orders on different screens of the same product.[^nng]

## Destructive actions

Irreversible actions like deleting need extra care, and here the sources complement each other:

- **Apple:** Don't give a destructive action the primary role, even when it's the most likely choice. People sometimes press the prominent button without reading it.[^apple]
- **GOV.UK:** Use the warning button only for serious actions that can't easily be undone. Use a regular button on the first step and the warning button on the final confirmation. Don't rely on red alone to signal danger; the button text should spell out the consequence.[^govuk]
- **Carbon:** A destructive action that is the required or main step of a flow gets the primary danger style; one that is just one of several options gets the tertiary or ghost danger style.[^carbon]
- **Shopify · Polaris:** Use the critical tone only for destructive actions that are hard or impossible to undo.[^polaris-button]

Adam Silver also corrects a common mistake: a "Remove" link that leads to a confirmation step **shouldn't be hard to find; the action itself should be hard to trigger by accident**. Hiding the link at the bottom of the page doesn't protect the user; it only makes their job harder. Protection comes from the confirmation step.[^silver]

## Labels

Every source wants a label that says what the button does. Instead of "OK," the action itself:

- **Apple:** Start with a verb, for example "Add to Cart."[^apple]
- **GOV.UK:** Verbs that describe the action, like "Save and continue" or "Save as draft."[^govuk]
- **Carbon:** A verb and a noun; common actions like Cancel or Delete can stay one word.[^carbon]
- **Fluent:** Dialog buttons should match the title: a dialog titled "Delete this file?" gets a "Delete" button.[^fluent]

## Disabled buttons

GOV.UK recommends avoiding disabled buttons: their contrast is low and they confuse users.[^govuk] Primer offers a middle ground: an "inactive" button that looks muted but explains why it doesn't work when clicked.[^primer-button] What both have in common is not leaving the user facing a wall with no explanation.

## The core idea

All of these rules boil down to one question: **what do I most want the user to do on this screen?**

1. If the answer is a single action, that's the primary.
2. If other actions oppose it (Cancel, Back), they're secondary.
3. If they're independent and minor, they're tertiary, ghost or text buttons.
4. If the answer is "both are equal," both stay neutral.
5. If the action is destructive, it isn't primary; it's protected by a confirmation step.
6. For order, pick your platform's and product's own rule, then keep it the same everywhere.

Hierarchy isn't a styling decision; it's a priority decision. The button's color is the result of that decision.

## Summary

- Button hierarchy tells the user what to do next.
- Almost every system recommends one primary per area; Apple allows one or two, Spectrum three accent buttons.
- Secondary is the action that opposes the primary; it isn't used on its own.
- Equally important actions stay neutral.
- Whether the primary sits on the left or the right varies by system; what matters is consistency.
- Destructive actions aren't primary and are protected by a confirmation step.
- A label is a verb that says what the button does.

[^m3-button]: [Android Developers: Buttons (Material 3)](https://developer.android.com/jetpack/compose/components/button)
[^carbon]: [IBM Carbon: Button usage](https://carbondesignsystem.com/components/button/usage)
[^atlassian-button]: [Atlassian Forge UI Kit: Button](https://developer.atlassian.com/platform/forge/ui-kit/components/button)
[^polaris-button]: [Shopify Polaris: Button](https://shopify.dev/docs/api/app-home/polaris-web-components/actions/button)
[^primer-button]: [GitHub Primer: Button guidelines](https://primer.style/product/components/button/guidelines/)
[^apple]: [Apple Human Interface Guidelines: Buttons](https://developer.apple.com/design/human-interface-guidelines/buttons)
[^fluent]: [Microsoft Fluent 2: Button usage](https://fluent2.microsoft.design/components/web/react/core/button/usage)
[^govuk]: [GOV.UK Design System: Button](https://design-system.service.gov.uk/components/button/)
[^spectrum]: [Adobe Spectrum: Button](https://spectrum.adobe.com/web/rsp/components/button)
[^apple-alerts]: [Apple Human Interface Guidelines: Alerts](https://developer.apple.com/design/human-interface-guidelines/alerts)
[^m3-dialog]: [Android Developers: Dialog (Material 3)](https://developer.android.com/develop/ui/compose/components/dialog)
[^primer-dialog]: [GitHub Primer: Dialog guidelines](https://primer.style/product/components/dialog/guidelines/)
[^atlassian-modal]: [Atlassian: Modal dialog usage](https://atlassian.design/components/modal-dialog/usage)
[^spectrum-group]: [Adobe Spectrum: Button group](https://spectrum.adobe.com/web/rsp/components/button-group)
[^nng]: [NN/g: OK–Cancel or Cancel–OK?](https://www.nngroup.com/articles/ok-cancel-or-cancel-ok/)
[^silver]: [Adam Silver: Should destructive buttons be hard to find?](https://adamsilver.io/blog/should-destructive-buttons-be-hard-to-find/)