Anatomy
Use the button anatomy examples to understand how labels, icons, and visual hierarchy work together. The visuals in the Figma frame show the default structure and the most common button arrangements.
Properties
Action Type
Button variants are designed to communicate action type through color and emphasis. Keep those colors intact so the hierarchy stays clear and accessible.
Icons and Labels
Use a leading or trailing icon when it helps clarify the action. For icon-only buttons, provide a tooltip so the action is still understandable.
Disabled
Use disabled state to show that an action exists but is not currently available. Preserve the layout so the action remains discoverable.
Loading
Loading is a custom implementation for now. When an action is in progress, update the label so users can see that the action is being carried out.
Links
Buttons can act as links when a text link does not carry enough prominence. Use this pattern only when the button treatment improves clarity.
Behaviour
Interaction States
Hover, press, focus, and keyboard interaction should all provide visible feedback. The Figma examples show the same interaction logic for mouse and keyboard users.
Best Practices
Use only one Primary button per screen
Use a single primary action to preserve hierarchy. Multiple primary buttons on one screen make the most important action harder to identify.
Use spacing.8 between buttons in a group
Keep grouped buttons consistently spaced so action clusters read as a set.
Provide a tooltip label for Icon only buttons
Icon-only buttons need an explicit label in a tooltip so users can still understand the action.
Don’t use Icons as decoration
Use icons only when they add meaning. Decorative icons weaken the label and make the action harder to read.
Don’t use Ghost Buttons on neutral backgrounds or images
Ghost buttons need enough contrast to remain legible. Avoid placing them on neutral base backgrounds or busy imagery.
Do disabled Buttons need contrast?
Disabled elements do not have the same contrast requirement as active UI, but the state should still be clear and communicated through semantics.
Additional Do and Don’t Examples
Content Guidelines
Use Title Case for button labels.
Content
Write concise, action-oriented labels. Prefer verbs such as Create, Add, Move, Publish, Save, Back, or Cancel when they match the user flow.
Keep labels short, avoid unnecessary words, avoid ending punctuation, and use a trailing ellipsis for loading states when the action is still in progress.
Usage Examples
Use the primary button for the main action in a screen header, such as Delete or Create, and keep the secondary action clearly subordinate.
Use a trailing icon when the icon reinforces the button label, such as an action that opens another destination or expands a menu.
