Button Hierarchy: Primary, Secondary, and Tertiary
Button hierarchy sets the main action, the secondary ones, and the destructive ones. Carbon and PatternFly rules for choosing, grouping, and placing buttons.
What levels exist?
Carbon, IBM’s design system, distinguishes several levels of emphasis (Carbon: Button usage):
| Level | What it is for, according to Carbon |
|---|---|
| Primary | The main call to action on the page. |
| Secondary | The negative action of the pair, such as “Cancel” or “Back.” Never alone or for a positive action. |
| Tertiary | Less prominent actions. It can stand alone or sit next to a primary button. |
| Ghost | The least prominent, supplementary actions. |
| Danger | Actions with destructive effects on the person’s data. |
PatternFly, Red Hat’s system, lists its styles “in order of visual hierarchy”: danger, primary, secondary, tertiary, link, icon, call to action, and progress. That danger comes first shows that systems do not agree on everything. What matters is that each team defines its order and uses it consistently.
How many primary buttons?
Carbon is clear: each page should have only one primary button, with an exception for temporary flows. The reason is that several buttons with the same visual weight compete, and the person has to think about which one to tap. PatternFly asks for the same: limit primary buttons to one per page and use calls to action sparingly, ideally one per page or a primary and secondary pair (PatternFly: Button design guidelines).
In a step-by-step wizard, the “Next” button should be primary and “Back” secondary. PatternFly adds that “Cancel” is usually a link rather than a button. That way, the only strong action is moving forward.
If you are not sure which button is primary, start with one question: what does the person want to accomplish on this screen? The answer is the main action. Everything else competes for attention and should drop a level. If several actions seem equally important, the screen probably mixes two tasks and should be split.
How are buttons grouped?
Carbon recommends groups of two or three related actions. If there are more, a menu is better. A group should not contain two high-emphasis buttons, and a secondary button is used only next to a primary one. In its style specification, Carbon places the primary button on the outside of the set and the secondary inside, with 16 pixels of spacing, and says not to mix button sizes in a group (Carbon: Button style).
PatternFly also sets 16 pixels between buttons, including danger buttons, and asks for left-aligned buttons in forms, modals, and wizards (PatternFly: Button design guidelines).
Where do destructive actions go?
Carbon reserves the danger style for actions that can have destructive effects on the person’s data, such as delete or remove. It can be applied as primary, tertiary, or ghost. The practical rule it proposes: use a danger primary when the action is a required step in the flow, and a lower-emphasis tertiary or ghost danger when it is one option among several (Carbon: Button usage).
PatternFly asks for danger buttons on potentially destructive actions, and notes that they appear mostly in modals, where they emphasize the destructive action the person is about to take.
A design judgment (not a Carbon or PatternFly rule): a destructive action should not be the default main action of a screen or sit where the person expects to move forward. If someone confirms without reading, the damage takes a second.
Where does the primary button go?
Carbon indicates that on full-page layouts the primary button sits on the left, while in wizards and dialogs it is right-aligned next to the secondary or tertiary button; in a wizard, the main action traditionally sits at the bottom right. PatternFly left-aligns the buttons of forms, modals, and wizards. Pick one convention and use it across the product.
In Carbon, when a dialog appears the primary button typically takes focus, and in a form, if focus is on a component that does not respond to Enter, pressing Enter activates the primary button. That is why the primary should be the action the person almost always wants. As an additional judgment call, if a dialog’s primary action is irreversible, it is safer to put the initial focus on the safe option.
Illustrative example
Illustrative example: a document editor shows four buttons on a file screen: “Save” (primary), “Share” (tertiary), “Download” (tertiary), and “Delete” (low-emphasis danger). In the delete confirmation dialog, “Delete” is the danger button and “Cancel” is secondary. The team decides to put the initial focus on “Cancel,” so someone who presses Enter without reading does not erase the file. It also checks that there is only one primary button per screen: if three buttons shared the same color, people would have to guess which one mattered.
If the button belongs to an error, review how to write error messages. To understand why contrast and visual weight help people decide, the article on the von Restorff effect explains how what is different draws attention. And to keep button names consistent across the product, see consistency and standards.
Common mistakes
- Having three or four primary buttons on the same screen.
- Giving “Save” and “Delete” the same visual weight.
- Placing the destructive action where people expect to move forward.
- Using a secondary button without a primary action beside it.
- Mixing button sizes within the same group.
- Letting default focus land on an irreversible action.
What you can do tomorrow
- Count the primary buttons on your most-used screen. If there is more than one, decide which action is the main one.
- Check where the delete button sits and confirm it is not the one activated by Enter.
- Ask two people to tell you the main button on the screen within three seconds.