---
title: Usage guidelines
---
import {Caption, Do, Dont} from '@primer/gatsby-theme-doctocat'
import {Grid, Flex, Box} from '@primer/components'
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.
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.
Example | Color variable | Usage
:--: | :--: | :--:
| icon-info | Used to indicate important information
| icon-success | Used to indicate a successful, passing, or positive result
| icon-danger | Used to indicate an error, danger, or negative result
| icon-warning | Used to indicate warning
## Sizing
Octicons are primarily available in two sizes: 16px and 24px. They should only be used at their dedicated sizes to maintain consistency in stroke width and legibility.
A limited set of 12px icons are available for specific usage within condensed UI and are listed below.
| Icon | Name | Usage
| :--: | :--: | :--: |
| ![12px alert fill icon](https://user-images.githubusercontent.com/10384315/138614527-c7d8aedb-e608-4768-9443-687fc1d5ed23.png) | [`alert-fill`](https://primer.style/octicons/alert-fill-12) | For cautionary messaging or to inform the user that an action requires attention |
| ![12px check circle icon](https://user-images.githubusercontent.com/10384315/138614538-b4f5c1d0-6705-4a08-bc8c-2ce553acb4d6.png) | [`check-circle-fill`](https://primer.style/octicons/check-circle-fill-12) | For positive messaging to inform the user that an action is successful, complete, or that they may continue through a workflow |
| ![12px no entry icon](https://user-images.githubusercontent.com/10384315/138614561-7ddc158b-932c-4f2f-854e-abba316676d9.png) | [`no-entry-fill`](https://primer.style/octicons/no-entry-fill-12) | Indicate an ending or that the user is blocked and cannot continue |
| ![12px x circle icon](https://user-images.githubusercontent.com/10384315/138614582-72db2bad-ca03-4741-aaf9-c30095a831e7.png) | [`x-circle-fill`](https://primer.style/octicons/x-circle-fill-12) | For negative messaging to inform the user that an error has occurred as a result of an action or an action is unavailable |
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
| Icon | Metaphor | Usage |
| :--: | :--: | :--: |
| | **Commits** | The `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
| | **Issues** | The `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 requests** | The `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)
| | **Repos** | A 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
**GitHub mark**
Brand logo use only. Follow [GitHub's brand guidelines](https://brand.github.com/) 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:
Use a filled icon to aid in contrast when in relation to another icon
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.
| Metaphor | Icon 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`
Use outline and fill pairings to show the state of an action
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.
| Metaphor | Icon pairing |
| :--: | :--: |
| Subscribe/Unsubscribe | / |
| Save/Unsave | / |
| Watch/Unwatch | / |
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.