Use button hierarchy when a view, card, or dialog has more than one action. Apply a different button style based on importance so people can immediately see which action to take first.
Anatomy
- Primary action The most important action in the view. Use at most one per view or card. Rendered as a filled Button (variant=Primary) in the brand color. Examples: Save, Create trigger.
- Secondary action An alternative to the primary action. A view can have more than one; group related ones with Button group. Rendered as an outlined Button (variant=Default). Examples: Cancel, Save as draft.
- Tertiary action The lowest-priority, supporting action. Rendered as a Link, not a button, to give it less visual weight than the primary and secondary actions. Examples: Learn more, Do this later.
Alignment
- Regular views: Left-aligned, with the primary action first (leftmost). Keep the order fixed: primary → secondary → tertiary.
- Table rows: Right-aligned. This separates content from actions and makes the action column easier to scan across rows.
Guidelines
- Only one primary button per view. Using several side-by-sides makes it hard to tell which one actually matters (Practical UI, ch. 8).
- Don't rely on color alone to show hierarchy. Filled, outlined, and link styles differ in shape as well as color, so the hierarchy still reads for colorblind users or in grayscale.
- Add only the actions you need. Start with the primary action, and add secondary or tertiary actions only when they're genuinely needed.
Icon-only button
In most cases, follow the button system above (Primary/Secondary/Tertiary). Icon-only buttons are the exception, and should only be used when:
- There isn't enough space for a text label
- The action is universally recognizable from the icon alone, such as copy, export, or save