Skip to content

Usage guidelines

Use octicons to symbolize metaphors and actions common to GitHub. When using octicons keep the following principles in mind:

  1. Octicons are used to emphasize meaning, not as a replacement.
  2. Adding an octicon should be intentional.
  3. Not everything needs an icon: consider a text label before adding an icon.
  4. Keep octicons at their aspect ratio.

Color

For most components, icon color has been set using our functional color variables.

Components with octicons already embedded have their color styles preset. This is an example of a flash alert where the alert icon and close icon are preset to a dark yellow.

Some use cases allow for icons to be paired with a specific color based on the intended function. Use the table below as a reference.

ExampleColor variableUsage
icon-infoUsed to indicate important information
icon-successUsed to indicate a successful, passing, or positive result
icon-dangerUsed to indicate an error, danger, or negative result
icon-warningUsed to indicate warning

Sizing

Octicons are available in two sizes: 16px and 24px. They should only be used at their dedicated sizes to maintain consistency in stroke width and legibility.

Don't
Scaling the 16px icon larger causes the stroke to become too thick. Scaling the 24px icon smaller causes the stroke to become too thin.

Scaling icons from their original size is not permitted.

Special icons

Certain octicons are intended for a specific use case. Refer to the table below for icons with specific guidelines.

Git specific

IconMetaphorUsage
CommitsThe commit icon is represented as a circle on a line. This symbolizes a point (the circle) along the version history timeline when changes were made. Use this icon in views to represent individual or groups of commits, including the timeline and the Commits tab in pull requests.
IssuesThe issue icon is represented as a circle with an ! mark. The base issue icon is extended through slight modifications that communicate different states of an issue: a checkmark for a closed issue, and by combining the sync icon with an ! for reopening an issue. These three symbols should be used exclusively with issues.
Pull requestsThe pull request icon is represented as a commit dot attached with an arrow being inserted into the history timeline (two dots connected by a line).
ReposA repository in GitHub is represented as a closed book and is explicitly named as repo. Octicons does contain a book icon which displays an open book symbol that is used for wikis, READMEs, and other use cases where the user can see a collection of information.

GitHub brand specific

IconMetaphorUsage
OctofaceRepresents the user. Conveys connection between GitHub and the user. Similar to the myOctocat generator.
GH markBrand logo use only. Follow GitHub's brand guidelines when using this octicon.

Icon styling

By default, all octicons use an outline style. Some icons have a filled version which should be used only under the following conditions:

Do
octicons-style-pairing

Use a filled icon to aid in contrast when in relation to another icon

Do
In GitHub Mobile, the active page uses the filled icon to indicate where the user is within the app. In this screenshot the home icon is filled to indicate the user is on the Home screen.

Use a filled icon to indicate navigation state in GitHub's native mobile apps

Icon states

The state of an action can be displayed either by using a stroke and fill icon pairing or using a slash version of an icon if available.

Outline and fill pairings

Use the outline icon for the "off"/"empty" state and the fill icons for "on"/"filled" states.

MetaphorIcon pairing
Sponsor/Sponsoring /
Star/Unstar /
Pass/Fail /

The exception to this rule is when conveying a "pass"/"fail" pairing which is done using the filled version of the check-circle and x-circle

Do
The file-directory icon uses a filled style to distinguish it apart from the file icons. In the example the file-directory icon is filled and blue and the file icon is outlined in light gray.

Use outline and fill pairings to show the state of an action

Do
octicon-actions

Use outline and fill pairings to indicate the status or completion of an action (for example, an action running)

Slash icons

Specific icons have a stateful pair using a slash to indicate the "off/empty" state. Use these when indicating that an action is removing or disabling a function.

MetaphorIcon pairing
Subscrib/Unsubscribe /
Save/Unsave /
Watch/Unwatch /
Do
The save and subscribe action buttons in notifications are special cases where a slash version of the icon is used for the 'off'/'empty' state.

The save and subscribe action buttons in notifications are special cases where a slash version of the icon is used for the "off"/"empty" state.

Edit this page on GitHub
2 contributorsashygeeyaili
Last edited by ashygee on January 8, 2021