Creating custom icons

Creating custom PatternFly icons

Why do we need guidelines?

Most designers have higher pixel density (aka Apple Retina) displays, which is great, but also masks problems that might be seen when users have older or lower resolution displays. Older displays won’t render the icons as cleanly as you hope. When creating new custom icons, if we follow some basic icon design guidelines, we can ensure that folks on lower quality screens will be able to see icons in the best way possible, given the limitations of their displays.

Examples of clarity on lower-quality displays

What better way to show that with a few examples? These are lower-quality display screen captures of the live icons rendered in a web browser @ 16px canvas height (400% zoom). The examples compare when an icon is not aligned with the grid (Before) and when an icon is aligned with the grid (After). As you can see, legibility for those on lower-quality displays will benefit greatly from following the guidelines in this document. The difference is remarkable.

Basic icon source file specs

File format & artboard specs

1. Work in/deliver in vector (SVG) format.

2. Adobe Illustrator is a better overall vector drawing tool compared to Sketch. That’s why we recommend drawing in Illustrator and just pasting the final vector shape into a Sketch file at the end for export.

3. Generally start on a 16 x 16 unit artboard where each unit in the artboard is 64px square. This gives us a starting point artboard size of 1024px wide x 1024px tall.

4. The artboard should always be 1024px tall. In some cases (depending on the design), the width of the icon may be wider or narrower than 1024px. Reference table for artboard units/pixel equivalents:

Unit	Pixel equivalent
1	64
2	128
3	192
4	256
5	320
6	384
7	448
8	512
9	576
10	640
11	704
12	760
13	832
14	896
15	960
16	1024 - always this height
17	1088 - wider than standard
18	1152 - wider than standard
19	1216 - wider than standard
20	1280 - wider than standard

Grid setup and usage

One of the most important technical aspects when designing icons is aligning vector paths and anchors to the 16 x 16 unit grid whenever possible. You can set up the visible grid in Illustrator to help with this. To set up:

1. Illustrator > Preferences > Guides & Grid:

• Gridline every: 64px
• Subdivisions: 4
• Grids in Back and Show Pixel Grid (Above 600% Zoom) should be checked

2. Click OK
3. Command-“ to show the grid. Note: Each dark grid line is a multiple of 64px while each light gridline is a multiple of 16

Your 1024px x 1024px artboard should look like this @ 50%. Darker lines represent each of the 16 units (@64px) while the lighter lines represent the 4 x 16px subdivisions within each grid unit:

By default, if your grid is not aligned with the canvas 0,0 coordinates:

1. Command-R to show rulers (if hidden)
2. Shift-O to switch to the artboard tool, be sure the artboard is selected
3. Double click in upper left corner in ruler bar to set the 0,0 point to the upper left corner of your canvas
4. Click any tool or ESC to exit the artboard tool and proceed.
5. Grid should now be aligned with the rulers to the 0,0 coordinates

Aligning vector paths with the grid

Generally, horizontal and vertical paths should align with the unit grid wherever possible to ensure they render crisply, even on lower-res screens (see first section of this document).

Aligning paths and anchors

Use the white arrow/direct select tool (A) to select individual anchor points to work with, then use the x and y axis text boxes to be sure the vector points align with the grid at multiples of 64px. Curves and angles don’t need to be aligned with the grid, but try to align apexes of curves, straight edges and corners to the grid wherever possible.

Important: In Illustrator, if you are working with grouped paths or paths that are part a compound path, you should ungroup or release the compound path before working with the individual anchor points. Otherwise, Illustrator won’t always keep the anchors at whole coordinates (you may end up with a coordinate like 448.01px). That small fraction will render the icon fuzzy on lower-quality displays. To fully remove groups and compound paths before adjusting single anchor points:

• Be sure to Object > Ungroup (until you no longer can)
• Object > Compound Path > Release (until you no longer can)

Once you’ve finished the work with individual anchors, select all and create the compound path again. Verify that groups have not been inadvertently been created.

Keeping anchor handles inside the canvas

Similar to path anchor points and the paths themselves, the handles that drive the shape and severity of the curves can skew the size of an SVG. Essentially, this means if you have an anchor with handles on the edge of your canvas, wherever those handles fall, they will “extend” the canvas if they sit outside the bounds of the canvas. In order to keep your canvases to the size intended, you must be sure the handles fall completely within the desired canvas.

These situations can be handled pretty easily if anchors are added to the place where curves touch the edge of the canvas. Once added, be sure the handles sit perfectly straight along the edges of the canvas.

Vertical alignment of icons shorter than 16 units

If the final height of your icon is an odd number of grid units (15/960px, 13/832px, etc), be sure to vertically align it to your canvas on the grid, which means you will have uneven spacing above and below the icon. For example, a 15-unit icon on a 16 unit-high canvas would have 1 unit above and align with the bottom of the canvas. Otherwise, the icon will sit on a ½ unit which will render the horizontal lines in the icon fuzzy on lower-quality displays.

Exceptions to the above guidelines

Generally, wherever you can have an anchor point or a path sitting on a horizontal and/or vertical grid line, you’ll get better rendering results for those users on lower quality screens. There are some cases where you can bend the rules if need be:

• If the stroke of an element looks too thin at 1-unit (64px) and too thick at 2-units (128px), try 1.5-units (96px) instead. However if you do, make sure one edge of that stroke sits perfectly on the grid. That way, one edge of the stroke will be crisp and one edge will be fuzzy. It’s not perfect, but it will appear better than both edges of that stroke rendering fuzzy.

• Curves and angles are generally more forgiving, even if they don’t sit on the grid. However, try to align connection points at either end of an angle or apexes of curves to the grid.

• Don’t ever exceed the 16-unit (1024px) height for an icon (including anchor handles). However, the width can be wider or narrower than 16-units. For the web and desktop fonts, we resize the icons based on their canvas height. As long as they all have the same canvas height of 1024, they will all scale properly in relation to one another and to Font Awesome icons.

Adding icon to Icon Exporter.sketch

Preparing the vector paths in Illustrator

Once you have finished with the icon in Illustrator:

1. Select all, then Object > Ungroup until you no longer can.

2. Make note of the icon size. Its dimensions should generally be a multiple of 64. It’s top left placement should also be on 0 or a multiple of 64 (select top left reference point - see below).

• In the X/Y coordinates boxes, if you have anything other than 0 or a multiple of 64, adjust the vector properly. Sometimes icons with lots of curves or angles may not have a top left reference point that sits at 0 or a multiple of 64.

• In the W/H dimensions boxes, if you have any height/width measurements that aren’t a whole number (preferably a multiple of 64), find the problematic parts of the path and correct them to make the path’s dimensions a whole number (no decimals). Use the guidelines that preceded this section.

Important: In Illustrator, if you are working with grouped paths or paths that are part a compound path, you should ungroup or release the compound path before working with the individual anchor points. Otherwise, Illustrator won’t always keep the anchors at whole coordinates (you may end up with a coordinate like 448.01px). That small fraction will render the icon fuzzy on lower-quality displays. To fully remove groups and compound paths before adjusting single anchor points:

• Be sure to Object > Ungroup (until you no longer can)
• Object > Compound Path > Release (until you no longer can)
• Once finished with adjustments, with everything selected, Object > Compound Path > Make which makes your vector path one path in the SVG code. Verify that the paths were not also grouped when making the compound path. If so, Object > Ungroup them.

3. To check that the compound path is working, you should be able to select the entire icon with the standard selection tool (V)

4. Resize the artboard’s width to the nearest multiple of 64, so the space on either side of the icon is minimized and all paths, anchors and anchor handles fit within the artboard.

5. Draw a box the same size as the artboard: 1px border and no fill. Be sure the top left placement is 0,0. This will be used to precisely place your icon on the Sketch canvas as designed. Make note of the size of the artboard.

6. Select > All (command-A), then Edit > Copy (command-C) everything.

Working in the Icon Exporter file

1. Download and open the Icon Exporter.sketch file. The artboards are listed in alphabetical order in the layer panel and on the canvas where all the artboards live.

2. In layer panel, select the artboard that will alphabetically appear after your new icon.

3. Create a new artboard and name it the name of the icon you are creating (“zone” in this example). Adjust its size to match the canvas size you ended with in Illustrator (the artboard height is always 1024px, even if the icon is not. Widths will vary.) Your new artboard should appear above the artboard you selected in the layer list and on the canvas area.

4. Move the new artboard on the canvas so it is placed alphabetically within the existing grid. This may require you to shuffle around existing artboards. These are laid out alphabetically to make it easier to find an icon. In this example, we’re conveniently adding “zone” which is at the end of the list.

5. With the new artboard still selected, Edit > Paste the icon and box you copied in Illustrator. If you matched the size of your artboard in Sketch with the size of the box that you copied with the icon in Illustrator, pasting it in should result in precise placement and need no X/Y adjustment.

6. IMPORTANT: select the placement box and delete it from the artboard.

7. Sometimes, a shape can come into Sketch (from Illustrator) inside a group folder. If so, you must make a change to the layer structure so it exports correctly.

• Grab the icon shape layer called “Fill 1” and drag it up and into the containing artboard. In this example, “Zone”

• The shape now appears outside the group folder. Delete the group folder (this should delete the “Fill 1” layer as well)

• The shape now appears by itself in the artboard.

Exporting the SVG from source Sketch file

1. Once the icon is placed properly in the artboard per the previous instructions, select the canvas for the new icon. In the Inspector panel, select “SVG” from the presets dropdown (if necessary) and click the Export Selected… button.

2. Choose your destination and click Save.

3. Provide the newly created SVG to development for integration into the PatternFly custom font by opening an issue in the patternfly repo on GitHub and attaching your file. The placement you established on the canvas should be preserved when they bring the SVG path code into the JSON file.

4. Update the Icon Exporter.sketch master file and the new icon to the patternfly-design repo on GitHub by opening a new pull request (PR) to update the /resources/patternfly-icons-svgs folder. This folder contains two files which should be updated by a single PR:

• icon-exporter.sketch - the Icon Exporter file described above
• patternfly-icons.zip - the downloadable zip file linked to patternfly.org

To update the .zip file, simply add your new icon to the /resources/patternfly-icon-svgs/patternfly-icons folder, re-zip the folder, and replace the old patternfly-icons.zip file. Once your PR is merged, the patternfly-design repo will be updated to include your latest changes.