Button hierarchy and states

01Four levels of buttons

A button hierarchy tells people which action matters most. Use one primary action per view, so the main choice is never in doubt.

• Primary

  Solid fill, strongest colour. The main action, such as Save.

• Secondary

  Outline or soft fill. Supporting actions, such as Cancel.

• Tertiary or text

  Text only. Low-priority actions, such as Learn more.

• Destructive

  Usually red. Actions that delete or cannot be undone. Add a confirmation step.

When two actions have equal weight, such as Yes and No in a simple dialog, give them matching styles instead of forcing a primary.

02Design every state

Each button needs more than a default look. Define:

• Default, hover and active (pressed).
• Focus, with a visible indicator for keyboard users. Never remove the outline without a replacement.
• Disabled, clearly less prominent.
• Loading, with a spinner or changed label such as Saving, and a blocked second click.

Before finalising a screen, review its buttons with this list. It takes a minute and catches most inconsistencies.

1. Is there exactly one primary button in the view?
2. Do secondary and tertiary buttons look clearly less prominent?
3. Does each button have a visible focus style?
4. Is a destructive action separated from the primary one and confirmed?
5. Are touch targets at least 24 by 24 CSS px, as WCAG 2.2 requires, and preferably larger on touch screens?
6. Do labels start with a clear verb?

Use a loading state to prevent double submissions and tell people that the action is in progress.

03Be careful with disabled buttons

A disabled button gives no reason. People cannot tell what is missing, and many assistive technologies skip it. Where possible, keep the button active and explain the problem when it is pressed, or show a message such as: Enter an email address to continue.

04Size, placement and semantics

• Keep heights, padding and corner radius consistent across the product.
• Place actions in the same order every time, for example primary first in the reading direction.
• Use a <code>button</code> element for actions that do something on the page, and a link (<code>a</code>) for navigation to another place.
• Write labels as verbs: Save changes, Delete account.

Consistency lets people learn once. If Save is the filled button on one screen, it should not become an outline on the next. Document the four levels in the design system and name them by role so teams apply them the same way.

Group related buttons and keep a clear gap between a primary and a destructive action, so a slip of the finger or the pointer does not cause damage.

05Sources

• W3C. Web Content Accessibility Guidelines (WCAG) 2.2. https://www.w3.org/TR/WCAG22/
• MDN Web Docs. The button element. https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button