Button usage

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.

Button types

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:

ButtonVisualUsageNotesModifiers
SecondarybtnFor secondary or less important actionsShould be considered as the go-to style when designing new buttonsOcticons, Size, Full-width, Button-Groups, Counter
Outlinebtn-outlineFor general actions, navigation, and filteringShould be used independently and not in conjunction with other button stylesOcticons, Size, Full-width, Button-Groups, Counter
Primarybtn-primaryTo indicate the primary action on a page or viewAvoid using multiple primary buttons in a single viewOcticons(limited), Size, Full-width
Dangerbtn-dangerTo indicate potentially dangerous, or destructive actionsOnly use this button when necessaryOcticons(limited), Size, Full-width

Usage

Use sentence case

Do: Use sentence case
Don't: Use all-caps or other text formats

Keep button text concise

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.

Adaptable full-width

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:

  • Modals with a singular call-to-action
  • Responsive behavior of buttons when scaled down
Do: Use this pattern to confirm important actions
Don't: Misuse this modifier by extending buttons full-width unnecessarily

Use text descriptions

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.

Do: Keep text brief, specific, and descriptive
Don't: Use unnecesary, redundant text descriptions

Use Octicons to clarify actions

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.

Use button groups to organize similar functionality

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.

Using social proof

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.

Hierarchy and placement

Use size to modify button hierarchy

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.

Limit primary button usage

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.

Always align primary buttons to the outermost edge

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.

Do: Follow this principle to align your buttons accordingly
Don't: Ignore this principle and misalign primary buttons

Use outline buttons independently

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

Support

Requesting feedback

If you have any questions while implementing buttons, or are looking for feedback, please reach out to the #design-systems channel on Slack.

Edit this page on GitHub
1 contributorashygee
Last edited by ashygee on August 14, 2019