These guidelines summarize how GitHub implements buttons across our products. We have standardized buttons documented on Primer CSS and Primer Components, and these docs which serve as the source of truth for development implementation. This article serves to supplement our technical docs with proper guidance on design implementation.
At GitHub, buttons are a fundamental building block of our products. The following table catalogues a quick glance at how we use buttons at GitHub:
|Secondary||For secondary or less important actions||Should be considered as the go-to style when designing new buttons||Octicons, Size, Full-width, Button-Groups, Counter|
|Outline||For general actions, navigation, and filtering||Should be used independently and not in conjunction with other button styles||Octicons, Size, Full-width, Button-Groups, Counter|
|Primary||To indicate the primary action on a page or view||Avoid using multiple primary buttons in a single view||Octicons(limited), Size, Full-width|
|Danger||To indicate potentially dangerous, or destructive actions||Only use this button when necessary||Octicons(limited), Size, Full-width|
Use sentence case
Don't use all-caps or other text formats
When designing buttons, keep the text as short but descriptive as possible. Buttons are to be understood by their type and text; if further clarity is required, consider adding an octicon or adding a text description.
In certain scenarios, it may make sense to use full-width buttons that extend to the width of their container. Use this style sparingly, but some appropriate use-cases include:
Use this pattern to confirm important actions
Don't misuse this modifier by extending buttons full-width unnecessarily
In certain scenarios, buttons require supporting text to give the user more context. Use text labels sparingly, as buttons should generally be able to be understood on their own.
Keep text brief, specific, and descriptive
Don't use unnecesary, redundant text descriptions
Use octicons in conjunction with buttons to clarify an action if text alone is not enough to explain its functionality. Octicons can also be used to signal an interaction, for example, the
triangle-down octicon to open a dropdown.
In some cases, Octicons are used to create an identifiable visual indicator for a common action or paradigm. For example, the repo icon is used next to repo links, the new repo button, and repeated in the new repo flow. This repetition and continuity helps people learn and identify our visual language.
Organize buttons together in button groups to show their similar functionality. Keep in mind that only default and outline buttons can be used as button groups. This modifier can also be used as a filtering pattern as well.
Counters can be added as numerical aid in appropriate scenarios. They should generally only be used with “small” buttons, and only be used where a it is providing valuable context.
Increase button size to bring prominence to buttons that have major impact. Decrease button size when space is limited and the action is of lesser significance. Use this modifier sparingly, as layouts should generally have only one large button.
Only use one primary button on the page, whenever possible, to indicate its emphasis relative to other actions. Primary buttons have top priority in visual hierarchy, and using too many of them on a single view dilutes their effectiveness.
When a secondary button is placed in conjunction with a primary button, the primary button should always be placed on the outermost alignment, or on top and extended full-width if stacked.
Follow this principle to align your buttons accordingly
Don't ignore this principle and misalign primary buttons
Outline buttons are mainly used for secondary actions such as filtering. Don't use in conjunction or place in close proximity of other button styles
If you have any questions while implementing buttons, or are looking for feedback, please reach out to the #design-systems channel on Slack.