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. Most of the time, we use the "Default" button type, but other types of buttons may be used to indicate something special about the button's hierarchy or functionality. The following table catalogues a quick glance at how we use buttons at GitHub:
|Default||The go-to style to render a button|
|Outline||To downplay a button, for navigation buttons, or for filter buttons|
|Primary||To emphasize the highest priority action on a view|
|Danger||To warn that an action is potentially dangerous or destructive|
|Invisible||A subtle style used for actions that are of lower priority in a view's button hierarchy|
When designing buttons, keep the label as concise as possible. Buttons are to be understood by their type and text. If further clarity is required, consider adding an Octicon or adding a caption.
Use sentence case
Don't use all-caps or other text formats
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 unnecessary, redundant text descriptions
|Medium||The default button size|
|Small||Decrease button size when space is limited and the action is of lesser significance.|
|Large||Increase button size to bring prominence to buttons that have major impact. Use large buttons sparingly, as layouts should generally have only one large button.|
Use Octicons in conjunction with buttons to clarify an action if text alone is not enough to explain its functionality.
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.
Most of the time, a button will have an icon and a label for clarity.
In some cases, an action can be understood without using just an icon. Icon-only buttons can help save space in a cramped area.
Buttons that only use an icon should still have a label that is invisible to sighted users, but accesssible to assistive technology (for example: read aloud by a screenreader).
Counters can be added in appropriate scenarios to provide context. For example, showing social proof by displaying the number of people watching a repo.
A count can be displayed inside of a button using a CounterLabel.
A count can be displayed as a separate element that is attached to a button. Only display a count as separate element that is attached to a button when the button uses the "small" size variant and the button type is "Default" or "Outline".
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
When a button is used to toggle a dropdown, it should have a visual cue to help users understand the functionality.
Group a button with a dropdown button in instances where a primary action allows for variants on the primary action. For example, there are different merge strategies a user can choose from when merging a pull request.
Use button groups to organize similar functionality. Only "Default" and "Outline" button types can be used in button groups. This modifier can also be used as a filtering pattern.
Group buttons with closely related functionality
Group buttons just because they're close together
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 #primer channel on Slack.