- Guidelines
- React API Reference
- Blazor API Reference
Buttons are used for interface actions.
Limiting button text length ensures scannability and encourages providing context in surrounding elements on the page. Title-case styling helps users quickly identify and understand actions.For comprehensive guidelines on writing effective button text, refer to our Call to Action content guidelines.
General Guidelines
Keep these general principles in mind when using buttons:| Guideline | Best Practice |
|---|---|
| Usage | Use buttons for in-page actions only. Do not use buttons for navigation for in-page actions to avoid confusion. |
| Alignment | Center-align text within buttons for a consistent, balanced appearance. Groups of buttons should be right aligned. |
| Capitalization | Use title-case for button text (e.g., “Submit Form”, “View Account Details”). |
| Abbreviations | Use abbreviations only if they are widely recognized (e.g., “FAQ”) and won’t confuse users. |
Primary Button
The primary button represents the most crucial action on a page.| Aspect | Best Practice |
|---|---|
| Usage | Use exactly one per view. It drives the main task—Save, Submit, Continue. |
| Content | Use verb-first phrases connected to the page title. For example, “Submit Request” after a heading like “Request Access.” See Call to Action guidelines for detailed content recommendations. |
| Style | Filled brand color, white text, 17.04 : 1 contrast ratio. |
| Visual Hierarchy | Right-most (or bottom) in a group and first in the tab order. |
Secondary Button
Secondary buttons are used as a fallback, or when there isn’t a single, flow-advancing primary action. Can also be used for small sets of actions.| Aspect | Best Practice |
|---|---|
| Usage | Use when a primary action is not available, when the view doesn’t move a flow forward, and for small grouped actions. |
| Content | Dismissive or completion verbs. |
| Style | Soft gray background. |
| Visual Hierarchy | Lower emphasis than Primary. Avoid pairing more than one Secondary. |
Secondary uses a filled surface, so a row of them carries more visual weight than Outline. If a group of Secondary buttons starts to look heavy—pulling attention before content forming a dense “gray band”—convert the group to Outline to lower emphasis.
Outline Button
Outline buttons are used for alternate or cancel actions.| Aspect | Best Practice |
|---|---|
| Usage | The default partner to Primary. Handles alternate or cancel actions—Cancel, Back, Preview. |
| Content | Neutral verbs that don’t move the flow forward. |
| Style | 1 px border, solid background. |
| Visual Hierarchy | Sits immediately left of the Primary; lighter stroke makes it clearly second in line. |
Destructive Button
Destructive buttons are used for irreversible actions.| Aspect | Best Practice |
|---|---|
| Usage | Irreversible actions—Delete, Remove, Reset. Always follow with confirmation. |
| Content | Lead with a danger verb. Ensure the text is descriptive and actionable, e.g., “Delete User Group” rather than “Delete” |
| Style | Filled with destructive token. |
| Visual Hierarchy | Close weight as Primary. Place away from affirmatives. |
Ghost Button
Ghost buttons are used for less important actions.| Aspect | Best Practice |
|---|---|
| Usage | Tertiary or inline controls where chrome must stay light—toolbar icons, card actions. |
| Content | One-word verbs or icons. |
| Style | Transparent, borderless. Provide 4.5 : 1 contrast on hover/focus. |
| Visual Hierarchy | Quietest option; rely on surrounding layout to cue importance. |
Link Button
Link buttons are used for navigation.| Aspect | Best Practice |
|---|---|
| Usage | For navigation that needs button styling—e.g., a “Learn more” call-to-action next to other buttons, or a hero banner CTA. |
| Content | Noun phrases like “Learn more”, “Docs”. |
| Style | Standard link styling; underline on hover/focus. |
| Visual Hierarchy | Button-style links carry the same weight as Outline or Ghost buttons—use them where a full-width or grouped action is needed but the outcome is purely navigational. |
Do’s and Don’ts
| Do | Don’t |
|---|---|
| Keep buttons concise (3 words or less). | Overload buttons with lengthy instructions. |
| Use title case to help buttons stand out. | Use all caps or sentence case for actions, which can reduce scannability and consistency. |