Icons

Overview

Consistent iconography in any user interface is critical to creating a product that is highly accessible across all different levels of literacy. Icons may need to be localized for different cultures and languages.

Good icons use simple, graphic shapes so they can be understood even at a small size. They have little detail. They are as universal as possible, consistent with other platforms.

Primary vs Secondary Icons

Primary icons are used for navigation or interaction. Primary icons are interactive, they change the surround environment or data. They likely don’t need to be coupled with text.

Secondary icons provide clarity. Secondary icons are used before text to communicate topical information.

Most of HQ's icons come from FontAwesome. All icons in FontAwesome are already built into HQ. Other icons have been custom created for HQ.

Custom Icons

HQ has its own set of icons custom created to communicate HQ-specific concepts. The majority of these icons are found in App Builder and Form Designer.

Creating New Icons

If a suitable icon doesn't exist in FontAwesome or HQ's custom set, it might be necessary to create one and add it to our custom set of icons.

The instructions below assume you have a Mac. If you are running a different operating system, consider reaching out to someone with a Mac to help you—unless you are adventurous and want to add to this documentation. If you are not comfortable with vector graphics, please reach out to someone who is.

Creating an Icon

Before you modify the CommCare HQ font, you first need to make sure you have a vector icon ready to copy-paste the vector data into the Glyphs file.

You can create a new icon from scratch, or you can start from an existing vector icon, like the ones found in The Noun Project.

You can open vector files (ie .svg, .eps, .ai) in either Adobe Illustrator, Inkscape, or similar vector graphics editor. Once open, edit the graphic as necessary to make the icon fit the style of the other icons available to the CommCare HQ Font.

When you have finished preparing the icon, ensure that you keep the file open while you follow the next steps to add a new glyph to the CommCare HQ font.

Adding a New Glyph

First, open CommCareHQFont.glyphs in Glyphs Mini. Glyphs Mini is a less expensive, reduced version of Glyphs you can find in the App Store.

If you scroll down in the window, you will see a section of glyphs called "Private Use". This is where we will want the new icon/glyph to eventually live.

The fastest way to add a new glyph is to select the last glyph in the list and go to Glyph > Duplicate in the menu.

Next, you can double-click to open the duplicated glyph. From here, rename the glyph to a memorable slug to describe the glyph (it's helpful if you use the same name when adding it to HQ). After that you can select and delete the old vector data from the duplicated glyph. From there, you can paste the new vector information for the new glyph (from an opened SVG or other vector image file), and resize to fit.

Rename

Delete Old

Paste, Resize New

Then, you can resize the canvas of the new glyph to fit the new vector image. It's a good idea to use other similarly shaped glyphs in the font as a sizing reference. Then you can horizontally position the glyph as seen in the gif below. Note that the number being entered in to center the glyph is half the value of the width of the glyph canvas.

Resize Canvas

Center Horizontally

Finally, vertically center the font as shown below. Again, now is a good time to reference values set for other similarly shaped and sized glyphs.

Center Vertically

When you are done editing the glyph and return to the main window, you will now see your new icon created. However, it is now appearing in the "Other" section rather than "Private Use". This is because you need to set the unicode value for this new glyph. Setting the unicode value is also very important so that we can reference it in the font stylesheet later.

Unfortunately, Glyphs Mini doesn't let you edit the unicode value for a glyph directly (you need the more expensive full version for this). However, there is a workaround. If you close Glyphs Mini and open the .glyphs file in a text editor you can add the unicode value after the new glyph definition.

First, find the glyph right before your new glyph, and copy the line with the unicode value, then paste it at the end of the new glyph definition and increment the hexadecimal value by one. Finally, add the slug for the new glyph in the list of glyphs. The images below illustrate each step, but you can also view this example commit as a template for how your changes should look.

Copy Previous

Paste & Increment

Add to List

When you are done editing the .glyphs file directly, you can open it again in Glyphs Mini. The new icon should now appear at the end of the "Private Use" list. You can also double-click to view the new glyph and verify that the new unicode value is shown next to the name/slug.

Final List

Verify Unicode

Saving the Edited Glyphs File

After the new glyph is properly added to CommCareHQFont.glyphs, it must be exported as an Open Type (.otf) font file.

The image below shows the settings in Glyphs Mini after going to File > Export. Save the final *.otf font to corehq/apps/hqwebapp/static/hqwebapp/font/CommCareHQFont-Regular.otf.

Prepping for Cross Browser Compatibility

To make the font universally readable across most browsers, you'll need to have an eot, svg, ttf, and woff version of it. Use the Font Squirrel Webfont Generator to do this.

You will need to use the generator in "Expert Mode" with the following settings:

Click to enlarge this image:

Adding the New Glyph to the Stylesheet

First, add a reference to the icon's font unicode value as a variable in corehq/apps/style/static/hqwebapp/less/font-commcare/variables.less.

Then, add the :before styling for the class of the icon in corehq/apps/style/static/hqwebapp/less/font-commcare/icons.less.

Update the list of icons in this document to show the new icon.

Example Commit

Here is an example of what a commit would look like when adding a new icon to our CommCare HQ font.