Skip to content
Primer Design System

Primer Design System

On this page

Design guidelines

On this page

These are guidelines to use as a reference when designing new octicons.

Grid sizes

Always design two versions of each icon: a 16px version and a 24px version.

16x16 grid

24x24 grid

12px icons are special and should only be created if there is a specific use case where a 16px icon can't be used.

Stroke

Use a consistent stroke width of 1.5px for both 16px and 24px icons.

1.5px stroke on 16px icon

Reference shapes

Use the following shapes as sizing references to ensure that the "optical volume" of your icon is consistent with the rest of the set. See the "Grid and Optical Volume" section of Nucleo's Icon Guidelines to learn more about "optical volume."

Circle

Circle on 16x16 grid

Circle on 16x16 grid example

Circle on 24x24 grid

Circle on 24x24 grid example

Square

Square on 16x16 grid example

Square on 16x16 grid example

Square on 24x24 grid

Square on 24x24 grid example

Rectangle

Rectangle on 16x16 grid

Rectangle on 16x16 grid example

Rectangle on 24x24 grid

Rectangle on 24x24 grid example

Caps and joins

Use round caps and joins.

Round caps and joins

Corners

Use 1px radius for corners unless a different radius makes the icon more recognizable (e.g. repo).

1px radius on 16px icon

1px radius on 24px icon

Use 0.25px radius for small filled elements inside icons, like filled arrowheads.

0.25px radius on arrowhead

0.25px radius on bookmark in repo icon

Gaps

Use a 1px gap to separate overlapping objects.

1px gap in comment-discussion icon

Use a 1.5px gap around modifier elements, like lines and arrows.

1.5px gap in bookmark-slash icon

1.5px gap in package-dependencies icon

Perspective

Use 2D perspective unless depth makes the icon more recognizable.

Do

Use 2D perspective

Don’t

Don't add unnecessary depth

Do

Use depth when it adds meaning

Don’t

Don't use a 2D perspective if it makes the icon unrecognizable

Pixel alignment

Align the outer edge of shapes to pixel boundaries when possible.

Do

Align the outer edge of shapes to pixel boundaries

Don’t

Don't align the inner edge of shapes to pixel boundaries

Arrowheads

Use line arrowheads unless there is not enough room.

Line arrowhead in sign-out icon

Filled arrowhead in link-external icon

Contributing

Creating a pull request

If you work at GitHub, you can use the Octicons Push Figma plugin to start an Octicons pull request from Figma.

Here's how it works:

  1. Select the icon frames you want to commit. Make sure the frames are either 16x16 or 24x24 and that you've outlined all strokes.
  2. Open the Octicons Push plugin.
  3. Select the branch you want to commit to. You can choose an existing branch or create a new branch.
  4. Press "Commit." The plugin will then export, commit, and push the selected icons to the branch you chose. If you chose to create a new branch, the plugin will give you a link to where you can start a new pull request with your branch.

After you create a pull request, a member of the design systems team will triage and review your contribution.

demo showing how to create a pull request using the Octicons Push Figma plugin

Review questions

Here are a few questions we'll ask when reviewing new octicons. Keep these in mind as you're designing:

  • Where will this icon be used in the context of GitHub UI?
  • Is an icon necessary in that context?
  • Could we use an existing icon?
  • Is the icon trying to represent too many ideas?
  • Does it follow the design guidelines?