Skip to content

Latest commit

 

History

History
94 lines (57 loc) · 5.27 KB

creating-icons.md

File metadata and controls

94 lines (57 loc) · 5.27 KB
Raw

Creating icons

OUI provides an ever-growing set of icons, but our set can be incomplete. If you find you need an icon that does not exist, create a new issue and tag it with the icons label. A designer from the OUI team will respond to discuss your needs.

If you are willing and able to design the icon yourself, this document describes the guidelines for designing a new icon, cleaning up the SVG, and getting it added to OUI. While designers on the OUI team are available to assist, we greatly appreciate your contributions and pull requests.

If you read through these guidelines or begin designing your icon and realize you're in too deep, then create an issue in this repo and request assistance. An OUI team member will reply and discuss options.

Note: The OuiIcon component accepts external references to icon files, so you have the option to maintain the icon in your consuming application.

Design the icon

From a content perspective, we've taken an approach of being open to many types of icons so long as they don't duplicate an icon that already exists. Stylistically, we have more stringent requirements outlined below.

Content

While we're pretty much open to all requests, we ask that you first try to use an existing icon as this helps us avoid having multiple versions of the same glyph. Likewise, if there is a universally known icon that represents an action, we recommend leveraging those existing patterns (e.g. a scissors for cut).

Finding and sharing reference icons is a great way to get moving if you're uncertain of the general shape. Post these examples to your issue and we'll provide feedback.

Lastly, we reserve the right to reject any icons that do not fit the OUI style or may be deemed inappropriate.

Style

This is where things get more opinionated. To maintain a cohesive, high quality icon set, we require that all new glpyhs adhere to the following guidelines:

  • Use an outline style with a 1 pixel width stroke, straight edges, rounded corners and ends
  • Adhere to an overall 16 pixel square shape

Dimensions

  • Center the glyph in the square leaving a 1 or 2 pixel trim area, where possible
  • Align vertical and horizontal paths to a 16x16 pixel grid

Guides

For Sketch users

As a reference, you can download and view the icons.sketch file via the Sketch libraries link atop the OUI documentation site site. The Symbols page within this file contains artboards for the vast majority of OUI glyphs.

For non-Sketch users

While we use Sketch to maintain our internal design library, you can use any design tool to produce the SVG file.

Add the icon to the OUI repo

Once you've designed your new icon, the last step is adding it to the OUI repo.

Clean the SVG

OUI provides SVG icon formats only. After exporting your icon as an SVG from your design tool, open it in a code or text editor and remove any unnecessary elements and attributes, such as:

  • <def>...</def>
  • <use>...</use>
  • id: <value>
  • fill: <value>
  • fill-rule: <value> or fillRule: <value>

Note: Sketch users can use the SVGO plugin to remove any extraneous code added by Sketch. Once installed, this plugin will run automatically any time an SVG is exported from Sketch.

Prepare the pull request

Create a new feature branch against this repo and make the following changes:

1. Add your glyph to the OuiIcon component

  • Add your SVG file to the /src/components/icon/assets folder
  • Add a reference in the /src/components/icon/icon.tsx file (in alphabetical order)

2. Display the icon in the docs

  • Add the icon name to /src-docs/src/views/icon/icons.js *

3. Compile and test

  • Run yarn compile-icons
  • Preview your icon locally at http://localhost:8030/#/display/icons **
  • Switch the docs to dark mode and verify that the icon is visible (all paths should be filled with the reverse color)
  • Run yarn run test-unit icon -u to create/update the jest snapshots

If everything looks good, then commit your changes, push up your branch, and open a PR! 🙌

Opening a PR will notify the OUI team that your work is ready for review. Please include a screenshot in the description and reference the issue that your PR fixes.

Ship it

Once your PR is approved, you will be able to merge it and give yourself a well-deserved pat on the back. Finally, stay tuned for the next release of OUI at which point your icon will become available to the masses and appear on the OUI docs site.

🏆 Welcome to the Official OUI Icon Design Club 🍻

* The Icons page actually contains several sections. In most cases, you will be adding your icon to the base set. However, if your icon should appear in a different set, then add it to the appropriate section file in /src-docs/src/views/icon.

** Run yarn && yarn start to view the OUI docs site locally.