Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add design guidelines #497

Merged
merged 19 commits into from
Oct 22, 2020
Merged

Add design guidelines #497

Show file tree
Hide file tree
Changes from 18 commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
335251f
Start design guidelines
colebemis Sep 10, 2020
d8b0609
Merge remote-tracking branch 'origin/master' into guidelines
colebemis Sep 10, 2020
fce3747
Add more guidelines
colebemis Sep 16, 2020
e73d8b1
beginning usage guidelines
ashygee Sep 16, 2020
f1f3953
add link to icons in sidenav
ashygee Sep 16, 2020
a30e4a4
Design guidelines edits
colebemis Sep 17, 2020
cb0a7f2
Update docs/content/guidelines/design.mdx
colebemis Sep 23, 2020
22e9394
Update docs/content/guidelines/design.mdx
colebemis Sep 23, 2020
906c592
Update docs/content/guidelines/design.mdx
colebemis Sep 23, 2020
4c6b979
Add usage guidelines to sidebar
colebemis Sep 23, 2020
1c5dc19
Small edits in usage guidelines
yaili Sep 23, 2020
da0bb6c
Update docs/content/guidelines/design.mdx
colebemis Sep 23, 2020
8b1a77d
add more usage docs and update nav
ashygee Sep 29, 2020
46559c4
add docs for status
ashygee Oct 1, 2020
3fc1485
Update doctocat
colebemis Oct 1, 2020
f375b88
Removed usage guidelines for now
ashygee Oct 22, 2020
203fc8a
Update doctocat
colebemis Oct 22, 2020
f48cff5
Merge branch 'master' into guidelines
colebemis Oct 22, 2020
83ee83b
Update docs/content/guidelines/design.mdx
colebemis Oct 22, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
303 changes: 303 additions & 0 deletions docs/content/guidelines/design.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,303 @@
---
title: Design guidelines
---

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

These are guidelines to use as a reference when designing new octicons. If you're looking for guidance on how to use octicons in your design, see our [Usage guidelines](/guidelines/usage).
colebemis marked this conversation as resolved.
Show resolved Hide resolved

## 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>
colebemis marked this conversation as resolved.
Show resolved Hide resolved
</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 16x16 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.
colebemis marked this conversation as resolved.
Show resolved Hide resolved
colebemis marked this conversation as resolved.
Show resolved Hide resolved

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
colebemis marked this conversation as resolved.
Show resolved Hide resolved

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?
78 changes: 78 additions & 0 deletions docs/content/guidelines/usage.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
---
title: Usage guidelines
---

import {Caption, Do, Dont} from '@primer/gatsby-theme-doctocat'
import {Grid, Flex, Box} from '@primer/components'

# Octicons usage guidelines

The following guidelines are to be used as a reference for how to use octicons.

## General guidelines:

These are general guidelines to follow when using octicons across various platforms:

1. Octicons should be used to _emphasize_ meaning, not replace.
2. Adding an octicon should be intentional.
3. Not everything needs an icon. Consider a text label before adding an icon.
4. Octicons should be kept at their 1:1 aspect ratio

### Sizing

Octicons are available at 16px and 24px frame sizes. While they can be resized we recommend you use octicons at their original sizes to maintain consistency in stroke width.

[TODO: Add image]

### Spacing

When used in groups, octicons should have a minimum of 4px space between each icon.

[TODO: Add image]

## Specific icon usage

### Octicons custom to `git`

The following should only be used for their specific meanings:

- Commits: The commit icon is represented as a circle on a line. This is to symbolize a point (the circle) along the version history timeline in which changes were made. This icon should be used in views to represent individual or groups of commits. These views include 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 to communicate different states of an issue: a checkmark for a closed issue and 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.

### Octicons custom to GitHub brand

- Octoface: Represents the user. Conveys connection between GitHub and the user. Similar to the octocat generator.
- GH mark: Brand logo use only. Follow brand guidelines.

## Outline vs fill: What's the difference?

By default, octicons have been designed in an outline style where filled shapes create small details (e.g. the repo icon where the book is outlined and the bookmark is filled). The use for using a fill style icon instead of an outline icon has been intentional and for the following use cases:

- To aid in contrast when in relation to another icon [TODO: Screenshot of repo files view folder icon vs file icon]
- For use in GitHub's native mobile apps [TODO: Screenshot of navbar and swipe actions (iOS)]
- To show state [TODO: Screenshot of star and sponsor social buttons]

### Status

To show the status or completion of an action (e.g. an action running), the filled check and filled x icons can be used.

[TODO: Show image of Actions]

## Icon states

The state of an icon can be displayed using outline/fill icon pairs or by using an icon's slash variant. Read below to understand the difference.

### Outline and fill pairings

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

[Example from mobile nav bar]
[Example from sponsors button]

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

Examples: The subscribe button and save actions in notifications are special cases where a `slash` version of the icon is used for the "off"/"empty" state.
Loading