Icon

Icons at GitHub are called Octicons, which are available in various implementations including React, Figma, Rails, and Styled System.

An image of multiple icons placed in a grid

Library

At Primer, we utilize the Octicons icon library. This package is available in Ruby, Jekyll, JavaScript, React and Styled System.

Usage

Icons are most appropriate for representing simple, recognizable concepts or actions. When choosing icons for your design system, consider the following guidelines:

  1. Where possible use icons to supplement text, rather than replacing it.
  2. Make sure that the meaning of icons is clear when used without accompanying text.
  3. Choose icons that are easy to recognize and accurately depict the concept or action.
  4. Maintain consistency in the use of icons across your product or brand.
  5. Avoid using icons for complex or abstract concepts that may be confusing to some users.
  6. Adhere to predetermined icon sizes to ensure legibility and ease of recognition.
  7. Test the effectiveness of your icons with users to ensure that they are understood and useful in navigating the interface.

Color

To ensure that icons are effective and legible in different color modes, it is recommended to use our functional foreground colors.

Many of our components are designed to automatically set the color of icons to a predetermined color. For example, flash banners are configured to set the icon to the matching role color by default.

A flash banner showing a warning icon in orange with the text 'Your password was reset recently.'

Some icons should always be shown in a specific colors when used within a specific context. This helps to effectively convey their intended meaning and provide a consistent user experience. Here are a few examples:

ExampleIconColor variableUsage
infofg.accentImportant information
checkfg.successSuccessful, passing, or positive result
xfg.dangerError, danger, or negative result
alertfg.attentionWarning

Specific use cases

Certain Octicons are designed for specific use cases and their meaning should not be changed. Most icons also have a predefined color variable, those should not be changed unless placed on colorful/dark backgrounds like buttons. In this case the fg.onEmphasis color can be used. Please refer to the table below for icons with specific guidelines.

ExampleIconContextColor variableUsage
git-commitCommitfg.mutedIndividual or groups of commits.
issue-openedIssuefg.successA newly opened issue that needs attention.
issue-closedIssuefg.doneA done/closed issue.
issue-reopenedIssuefg.successA reopened issue.
issue-draftIssuefg.mutedA draft issue.
git-pull-requestPull requestfg.successA new unmerged pull request that needs attention.
git-pull-request-closedPull requestfg.dangerA closed pull request that wasn't merged.
git-pull-request-draftPull requestfg.mutedA draft pull request.
git-mergePull requestfg.doneA merged request.
repoRepositoryfg.mutedA public repository.
repo-lockedRepositoryfg.attentionA private repository. Not to be confused with lock.
mark-githubBrandingfg.defaultSee our GitHub brand guidelines.
logo-githubBrandingfg.defaultSee our GitHub brand guidelines.

Sizes

The x-circle icon shown in three different sizes.

Octicons are available in three sizes: 12px, 16px and 24px. To maintain consistency in stroke width and legibility, it is important to use these icons only at their designated sizes.

The smaller set of 12px icons is available for use in specific, condensed user interface contexts. These icons are listed below and should only be used in the appropriate context.

ExampleIconUsage
alert-fillFor cautionary messaging or to inform the user that an action requires attention
check-circle-fillFor positive messaging to inform the user that an action is successful, complete, or that they may continue through a workflow
no-entry-fillIndicate an ending or that the user is blocked and cannot continue
x-circle-fillFor negative messaging to inform the user that an error has occurred as a result of an action or an action is unavailable
chevron-downIndicates that a collapsible section is currently open
chevron-rightIndicates that a collapsible section is currently closed

Maintaining the original size of icons is important for visual consistency, legibility, accessibility, and simplifying the design process. Resizing icons should be avoided.

Do
A pencil icon shown in their original 16px and 24px size.

Keep icons in their original size.

Don’t
A pencil icon scaled up from 16px to 24px demonstrating how the stroke increased while upscaling. Another pencil icon is scaled down from 24px to 16px and demonstrates how the stroke became too thin.

Don't resize icons.

System vs user-selectable

There are two types of icons: system and user-selectable icons.

System are used to represent core actions and concepts within the user interface. These icons are typically used consistently throughout the product and are an important part of our visual language. Examples of system icons might include a trash icon for deleting items, or a plus-circle icon for adding new items.

User-selectable icons, on the other hand, are used to allow users to customize their experience or make a personal connection with the product. User-selectable icons are typically less central to the functionality of the user interface and may be changed by the user as desired.

At GitHub we currently use emojis as user-selectable icons as they are widely recognized and understood, making them an effective way to convey emotions or personality. One benefit of using emojis as user-selectable icons is that they are visually distinct from the system icons used in the design system. This helps users to easily understand that the emojis are optional and can be selected by the user, rather than being a part of the core functionality of the user interface.

Using Octicons as user-selectable icons is strongly discouraged as that could create a confusing experience when used in the wrong context. For example, a user could pick a issue-closed icon and use the label In progress.

Do
A navigation side bar with multiple items including 'To do', 'Learning' and ''Ready to go. Each item has a emoji assigned and is displayed on the left of the text.

Use emojis as user-selectable icons.

Don’t
A navigation side bar with multiple items including 'To do', 'Learning' and ''Ready to go. Each item has an octicon assigned that is displayed on the left of the text.

Don't use Octicons for user-selectable icons.

States

To display the state of an action, use a stroke and fill icon combination or its opposite version if available. For "off" or "empty" states, use the outline icon.

Predefined pairs

ExampleIconsUsage
/ heart / heart-fillSponsor / Sponsoring
/ star / star-fillStar / Unstar
/ check-circle / x-circle-fillPass / Fail
/ file-directory-open-fill / file-directory-fillDirectory open / Directory closed
/ bell / bell-slashSubscribe / Unsubscribe
/ bookmark / bookmark-slashSave / Unsave
/ eye / eye-closedWatch / Unwatch
/ cloud / cloud-offlineCloud online / Cloud offline

Maintaining consistency by adhering to the predefined pairs is important to avoid inconsistencies, as demonstrated in the following examples

Do
A completed 'upload artifacts' block with a check-circle icon and a failed 'upload artifacts' with a x-circle-fill icon.

Stick to predefined icon pairs.

Don’t
A completed 'upload artifacts' block with a check-circle icon and a failed 'upload artifacts' with a x icon.

Create your own icon pairs.

Do
Two examples of correct off states for buttons. A 'Save' button with a outline bookmark icon and 'Unsave' button with a bookmark-slash icon. A 'Subscribe' button with a bell icon and 'Unsubscribe' button with a bell-slash icon.

For "off" or "empty" states, use the slash icon.

Don’t
Two examples of wrong off states for buttons. A 'Save' button with a bookmark icon and 'Unsave' button with a bookmark-filled icon. A 'Subscribe' button with a outline bell icon and 'Unsubscribe' button with a filled bell-filled icon.

Don't use filled icons for representing "off" or "empty states".

Creating new icons

If you are unable to find the icon you need in our Octicons library, you may want to create a new icon. Follow our Octicons design guidelines for guidance on creating a new icon that fits with the visual language of our design system. Keep in mind that new icons should be added only when they are necessary and meet the guidelines for use.

Accessibility and usability expectations

If the icon is purely decorative and does not convey any meaning (for instance, if adjacent text already provides all the necessary information/context), it is hidden from screen readers.

If the icon does convey meaning, the component exposes a role="img" so that its purpose will be described by assistive technologies, and the component's aria-label contains the accessible name / text alternative for the icon.

The accessible name or decision to make it decorative should be included in the design annotation.

Unless the icon is purely decorative, it must have a contrast ratio of at least 3:1 against the background color.

Built-in accessibility features

If the author does not include an aria-label, the component is assumed to be decorative, and will automatically be given an aria-hidden="true" attribute.

If the author includes an aria-label, the component exposes a role="img", and the aria-label attribute is passed to the rendered component.

Implementation requirements

  • If the icon is decorative, omit the aria-label attribute.
  • If the icon is used to convey information or meaning, make sure to add an appropriate aria-label that provides the text equivalent for the icon.

Authors can choose the color used for the icon, so it is important to ensure that it has a contrast ratio of at least 3:1 against the background color. It is recommended to use our functional foreground colors.

How to test the component

Integration tests

  • The icon has a contrast ratio of at least 3:1 against the background color.

Component tests

  • If the icon has been given an aria-label attribute, the <svg> has a role="img" and the aria-label is exposed
  • If no aria-label attribute has been given, the icon is presentational and the <svg> is hidden from screen readers using aria-hidden="true".

Known accessibility issues (GitHub staff only)

View open accessibility issues related to this component