---
title: Design guidelines
---

import {Grid, Flex, Box} from '@primer/components'

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

## Grid sizes

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

<Grid gridTemplateColumns={['1fr', null, null, null, '1fr 1fr']} gridGap={4}>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/41d55c2894e91bd7d0594d005ce51e2471292973343c01dcbbc271c34aa2d702"/>
        </Flex>
        <Caption>16x16 grid</Caption>
    </div>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/b270acfcf262364d2647cf96df17fd9b89aa891f65bc3c50c404d74531e8bb0e"/>
        </Flex>
        <Caption>24x24 grid</Caption>
    </div>
</Grid>

## Stroke

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

<div>
    <Flex bg="gray.1" justifyContent="center">
        <img width="400" alt="" src="https://compai.pub/v1/png/def9d3100c985ae397b8f0a0aa64506259449887ebc0bd362c727de3701d3fda"/>
    </Flex>
    <Caption>1.5px stroke on 16px icon</Caption>
</div>


## 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](https://blog.nucleoapp.com/nucleo-icon-guidelines-introduction-70092f8b4697) to learn more about "optical volume."

### Circle

<Grid gridTemplateColumns={['1fr', null, null, null, '1fr 1fr']} gridGap={4}>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/517fd99ef0fb4b18ec8ba2866d1c588abf723a09c5cf88ac0689489096fa1c66"/>
        </Flex>
        <Caption>Circle on 16x16 grid</Caption>
    </div>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/14df95cdfabe5942d909d93d6d0cf53559f747069c1c14b31e90ad0e3a2bb493"/>
        </Flex>
        <Caption>Circle on 16x16 grid example</Caption>
    </div>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/386489cc8ceb0f33c27bfe85fc4fc4fcd3a625034f9c1a5ba76a0441ffd6c196"/>
        </Flex>
        <Caption>Circle on 24x24 grid</Caption>
    </div>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/b1613783f96baf871bdeaf50c3353770b21437ef182f6f653b4aaa7cd7998074"/>
        </Flex>
        <Caption>Circle on 24x24 grid example</Caption>
    </div>
</Grid>

### Square

<Grid gridTemplateColumns={['1fr', null, null, null, '1fr 1fr']} gridGap={4}>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/d7f7995b17d2da448b5f7897cbdeb6852314caf644378e6a2f003f49bf93bee9"/>
        </Flex>
        <Caption>Square on 16x16 grid example</Caption>
    </div>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/528612e3b081227a9c7d637145d8efec33e2040121ece3615008bec1efab62a2"/>
        </Flex>
        <Caption>Square on 16x16 grid example</Caption>
    </div>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/50065ee42ae2dcec8fc89981c58627ebb59e0fcbeac46242d0f9129d0eb382bd"/>
        </Flex>
        <Caption>Square on 24x24 grid</Caption>
    </div>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/d0c6f1bc2e6b79e5bb7c1908f1628b684e1a34d310565424f16f768596152005"/>
        </Flex>
        <Caption>Square on 24x24 grid example</Caption>
    </div>
</Grid>

### Rectangle

<Grid gridTemplateColumns={['1fr', null, null, null, '1fr 1fr']} gridGap={4}>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/9f5be6a1ab3037035e5e3a95949dddbf0774b65ab44f07cc40df14acb493b73f"/>
        </Flex>
        <Caption>Rectangle on 16x16 grid</Caption>
    </div>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/6ae41747f6879df041fbd3c3a8bf6a1299d93fbbb94cf286b0ea003c271f4171"/>
        </Flex>
        <Caption>Rectangle on 16x16 grid example</Caption>
    </div>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/58d509fcc6462dcf1f6b302ee613af53e9d60e41df658c6c72d38ced736860c4"/>
        </Flex>
        <Caption>Rectangle on 24x24 grid</Caption>
    </div>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/2dc78cb66d06f450ab6d41136e5c72cebc36bbd0b57e870c377a8f41ca1efbf4"/>
        </Flex>
        <Caption>Rectangle on 24x24 grid example</Caption>
    </div>
</Grid>

## Caps and joins

Use round caps and joins.

<div>
    <Flex bg="gray.1" justifyContent="center">
        <img width="400" alt="" src="https://compai.pub/v1/png/fec160f7b9bad6d1f9bf15da6e9b6ece441680c81ce7d3392e90e17567db9f3e"/>
    </Flex>
    <Caption>Round caps and joins</Caption>
</div>

## Corners

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

<Grid gridTemplateColumns={['1fr', null, null, null, '1fr 1fr']} gridGap={4} mb={4}>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/48f9cd74350c40914c1aeb97a4e830bc5b5d8fa855a6125cfe791ec9b033913f"/>
        </Flex>
        <Caption>1px radius on 16px icon</Caption>
    </div>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/90a05df970a9049bae4e249cb8fab4db64311a2293154d08cca2ad46131d5e0c"/>
        </Flex>
        <Caption>1px radius on 24px icon</Caption>
    </div>
</Grid>

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

<Grid gridTemplateColumns={['1fr', null, null, null, '1fr 1fr']} gridGap={4}>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/528954ce1f6774b645b7ca04a36acb00739df168e7ba8b691050c5c223c032e0"/>
        </Flex>
        <Caption>0.25px radius on arrowhead</Caption>
    </div>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/042c23576fd22e88fc013692cc3cf0ee1b9e76fdaad7595d8f90f31113e106be"/>
        </Flex>
        <Caption>0.25px radius on bookmark in repo icon</Caption>
    </div>
</Grid>

## Gaps

Use a 1px gap to separate overlapping objects.

<Flex mb={4} flexDirection="column">
    <Flex bg="gray.1" justifyContent="center">
        <img width="400" alt="" src="https://compai.pub/v1/png/e3ff5e9bf83ff4d5fe7cf43e8f3b9cd14bb30bdfb705cfcbc30adf013b39499f"/>
    </Flex>
    <Caption>1px gap in comment-discussion icon</Caption>
</Flex>

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

<Grid gridTemplateColumns={['1fr', null, null, null, '1fr 1fr']} gridGap={4}>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/469f56437ac92380af105686fd03f5639d03c5013a965724303f2ff9aee2569f"/>
        </Flex>
        <Caption>1.5px gap in bookmark-slash icon</Caption>
    </div>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/650ecfa784e14b19635ac96be274c3e9e48f2fcf71d67fee8eaea73ff258fc0e"/>
        </Flex>
        <Caption>1.5px gap in package-dependencies icon</Caption>
    </div>
</Grid>

## Perspective

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

<Grid gridTemplateColumns={['1fr', null, null, null, '1fr 1fr']} gridGap={4}>
    <Do>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/279357826adcb80f653d8d199e6b01989a1d08daacb4e1eb9d88a6b27d7f25a4"/>
        </Flex>
        <Caption>Use 2D perspective</Caption>
    </Do>
    <Dont>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/1476c36a14d58dc6d931c9ac9e87bc3cee827c86f6a3f5a0e4ca50cf9e7577b1"/>
        </Flex>
        <Caption>Don't add unnecessary depth</Caption>
    </Dont>
    <Do>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/3aadc8fea546dd54d25198401ccd737e4199798c20b4032535c40ee6ba89feb3"/>
        </Flex>
        <Caption>Use depth when it adds meaning</Caption>
    </Do>
    <Dont>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/bbe56e09aff2a5f8b0dfa7dbbc37f1cc4d6b4f464e4f1b06d0b78dc5cf970454"/>
        </Flex>
        <Caption>Don't use a 2D perspective if it makes the icon unrecognizable</Caption>
    </Dont>
</Grid>

## Pixel alignment

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

<Grid gridTemplateColumns={['1fr', null, null, null, '1fr 1fr']} gridGap={4}>
    <Do>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/7fb5cb03a4e6d1164ad31b1ed8d3538f00c69a788c2d3bfd8ad282398b517c04"/>
        </Flex>
        <Caption>Align the outer edge of shapes to pixel boundaries</Caption>
    </Do>
    <Dont>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/39e340f63b3f8f6a8e86f3a656b53777caddfaec757ee98a0f64c8e7de245f7d"/>
        </Flex>
        <Caption>Don't align the inner edge of shapes to pixel boundaries</Caption>
    </Dont>
</Grid>


## Arrowheads

Use line arrowheads unless there is not enough room.


<Grid gridTemplateColumns={['1fr', null, null, null, '1fr 1fr']} gridGap={4}>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/d8f70676d9e78c9bf5aab2961eb65d5aa311bf8119f11be229c8056838a2cd6e"/>
        </Flex>
        <Caption>Line arrowhead in sign-out icon</Caption>
    </div>
    <div>
        <Flex bg="gray.1" justifyContent="center">
            <img width="400" alt="" src="https://compai.pub/v1/png/603edbc609906bb955775f45d0d0257b25805ab309b1ad86111b029e3b57a0fc"/>
        </Flex>
        <Caption>Filled arrowhead in link-external icon</Caption>
    </div>
</Grid>


## Contributing

### Creating a pull request

If you work at GitHub, you can use the [Octicons Push](https://www.figma.com/community/plugin/825432045044458754/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.
1. Open the Octicons Push plugin.
1. Select the branch you want to commit to. You can choose an existing branch or create a new branch.
1. 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](https://primer.style/about/#team/) team will triage and review your contribution.


![demo showing how to create a pull request using the Octicons Push Figma plugin](https://user-images.githubusercontent.com/4608155/77948730-b1a24600-727a-11ea-9c39-040be9a12963.gif)

### 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?