Icons are the small graphic elements that most apps and web pages use to quickly convey meaning or add context to interfaces. Used on their own (as in a toolbar or bottom nav, for example), icons can fit several actions in a small area. When used with a button, link, or other component, icons help set and reinforce user expectations.

Most of Forge’s icons are based on global iconography best practices, so they’ll be familiar to users. Some were designed especially for use in healthcare settings; these are more specific and less familiar. It's important to consistently use all icons according to this guidance across athenahealth.

This page provides designer and developer guidance for our icon set. You’ll also learn how to browse and use the library and how to create your own icons to contribute to the library.

• Icons represent common items, concepts, or actions.
• Use them to communicate or reinforce meaning for users. Don’t use them just to make designs more visually appealing.
• If you can’t find the right icon, don’t use another in its place. It’s easy to create and contribute athenahealth icons.
• Designers can access the icons for their designs in Figma or download them for use in other design tools.
• Developers can access the icons as a standalone package for use in their code, separate from Forge itself. This means the icons can be used outside of Forge.

Icons add visual cues to web page text, making it easier to scan. Our icon set is used across every athenahealth app and product, so it’s important to consistently use our icons according to these guidelines for the best user experience and a strong brand identity.

Using icons incorrectly can introduce visual complexity or confusion without improving usability, so use icons:

• To convey information in small spaces where extra text doesn’t fit, like Table cells
• To add a visual element that helps users understand copy quickly
• To visually differentiate items in a list
• To trigger an action like print or close (when used with Button)

Don’t use icons:

• Just to make a page more visually appealing. Icons are for context, not decoration.
• For large sections where an illustration or image would work better. Our icons are designed for display at specific sizes and are too small for a large container.
• For uses that aren’t aligned with the icon’s definition, like using the ModalPopup icon to represent a copy action (see the icon table for names and usage).

When considering using icons in your design, ask yourself which communication is better for users: an icon or text? If it takes more than a few seconds to think of the right icon for your use case, you probably shouldn’t use one. If you decide to use an icon, look for it in the icon table. If you can’t find it, you might not need one. Don’t try to force it with an icon that isn’t designed for your use case.

Size

24px is recommended for most use cases and in icon-only tertiary Buttons. Use 16px for inline icons and icons in another Forge component.

Color

Icons variants come in 4 colors:

• Dark gray #373738 (Font/default) is the default color for icons that aren’t interactive.
• Blue #0466B4 (Interaction/default) should be used for icons that are interactive (e.g., if it should trigger an action, like a Tooltip).
• Light gray #B6B7B7 (Font/disabled) should be used for icons that are normally interactive but whose interaction is currently disabled.
• White #FFFFFF (Font/invert) should be used for icons on a dark background.

When an icon is used in another interactive component (like a tertiary Button), that component’s colors and states are applied automatically.  

Icons can accept colors from alert, font, and interaction semantic color categories.

Alignment

All icons should have 2 or 4px of padding top and bottom, depending on usage. Related components or text elements should be placed 8px away from large icons and 4px away from small icons.

There are 6 Forge icons that have special styling designated for alerts:

• Success
• Attention
• Critical
• Help
• Info
• New

These icons have fill colors that correspond to the Forge alert types. They’re built into many of our alert components, like Banner and Toast.

• The Success, Attention, and Critical icons can be used on their own, outside of components where they’re built in, but the alert fill colors should be used for alert messaging only.
• The Help, New, and Info icons can be used to trigger a Tooltip on hover. They’re often placed to the right of form labels, to explain what the form field is for.

Each alert icon has a corresponding version without the colored background. These are designed for use in Buttons and other non-alert scenarios where it’s acceptable to reduce their visual impact.

Many icons have meanings that are commonly understood (like the Home icon for a home page), but some icons that seem familiar can actually convey different meanings in different apps (think of a Heart or Star icon). For this reason, we strongly recommend using most icons with a descriptive text element, like Button label copy or a Menu item name.

In the icon table, Label Required? indicates whether the icon can be used on its own without any text:

• Yes: Always use a label with this icon. The meaning might be unclear, the icon might not be commonly used, or it might be unique to athenahealth.
• Maybe: We recommend a label for this icon. It’s commonly used but not always understood. If there’s no room for a label, there are two options:
  • By default, on hover, every icon displays the icon’s name in a tiny popup (the native browser <title> tag). You can customize this text for your use case. Users typically need to hover for a moment before the popup appears.
  • For instant feedback on hover, add a Tooltip to your icon. The Tooltip should state the icon’s purpose, or for a Button or link, the action or destination. Use this approach for icon-only Buttons, which don’t have the <title> hover behavior built in.
• No: This icon doesn’t need a label (though it might still be helpful). It’s commonly used and easily understood on its own.

These are athenahealth UX best practices and are not enforced by the code. 

Icons can be set to function as a button or a link when clicked, as in a mini toolbar of actions represented by just icons. For this use case, use an icon-only tertiary Button or ComboButton. These include all of Button’s interactive states and can be set to act as a button or link, which is important for accessibility and semantically correct HTML.

The one limitation of this approach is that it removes the icon’s ability to display the icon name on hover. If users might not know what your interactive icon does, add a Tooltip.

If using icons for items in a collection (like a List or Menu), apply them consistently to all items in the list or section.

In interactive contexts, like tertiary buttons, most icons are blue #0466B4 (Interaction/default) to catch attention. However, specific icons, such as Close or Expand/Collapse, are meant to be less prominent and maintain gray #373738 (Font/default) within the interactive tertiary button. Nevertheless, they still change color on hover and click to provide visual feedback.

To reduce the overall size of Forge (when deployed on Nimbus), we’ve separated Forge icons into their own package. This means that installing Forge doesn’t automatically install the new Forge icon set.

To import the new Forge icons, enter this in your command line interface (CLI):

npm install @athena/forge-icons

Then, to add a specific icon to your project, use this import statement:

import AddAppointmentLarge from '@athena/forge-icons/dist/AddAppointmentLarge';

This import guidance is different from how we advise importing components from 'athena/forge'. Importing from 'athena/forge-icons' forces your application to package the entire ~700KB library, even if your application needs only a single icon. Nimbus is working on Webpack 5 improvements that will allow Nimbus users to take advantage of this feature (tree shaking).

For 24px icons (recommended for most use cases and in icon-only tertiary Buttons), use the Large size. For 16px icons (recommended for inline icons and icons in another Forge component), use the Small size.

To insert the icon into the page, specify the icon in code like this:

<AddAppointmentLarge />

For additional functionality, see the props table. For example, for interactive icons, use this:

<AddAppointmentLarge variant="interactive" />

The icon table’s Label Required? column indicates which icons should have descriptive text (because their meaning isn’t always clear enough for the icon to stand alone, without text). This isn’t enforced in code. This is UX guidance and relies on teams to design and build with these recommendations in mind.

When using an icon in another component, check whether the component has a prop for setting an icon. Some Forge components (like Button) have an icon option built in, so you don’t have to pass it in as children.

While our new icon set is broader and more flexible, there may still be reasons to use the previous icon set. The older icons can still be used in projects, as long as Forge is a dependency of that project. 

There are two ways to recolor icons. Using Javascript and CSS.

Javascript

If your icon is not interactive, and doesn't need to restyle based on hover/focus/active state then changing its color through Javascript props is the easiest approach. There are 4 colors that are most common for recoloring an icon: 'default', 'interactive', 'disabled', 'inverted'.

<AddAppointmentLarge semanticColor="disabled" />

Or you can set the color by semantic color (a single string representing category and name) like 'category-name':

<AddAppointmentLarge semanticColor="alert-attention" />

Only 'alert', 'brand', 'font', and 'interaction' categories are whitelisted for the semanticColor prop, as those are the color categories that have been determined to best fit with an icon's intent.

CSS

If your icon is interactive, it should restyle based on hover, focus, and active states. This is best accomplished through CSS. The Button component recolors its icons using the forge-icons-interaction mixin. To use, import with @use '@athena/forge-icons/src/forge-icons' as forgeIcons;. The forge-icons-interaction mixin is intended to be called for each state that you want to recolor. For example, if you have a <button> with the .my-interactive-button class, you should call this mixin like so:

.my-interactive-button {
  forgeIcons.forge-icons-interaction(interactive);
  
  &:active {
    forgeIcons.forge-icons-interaction(interactive, active);
  }
  
  &:focus {
    forgeIcons.forge-icons-interaction(interactive, focus);
  }
  
  &:hover {
    forgeIcons.forge-icons-interaction(interactive, hover);
  }
}

Do not set the icon's color through Javascript as well because the implementation of the mixin only recolors fill and stroke attributes which match the default icon color.

This mixin is intended to be called multiple times so as not to assume that the variant will remain constant. For example, the secondary Button variant changes its background on hover, causing its icon to flip from being interactive to inverted.

Forge designs new icons and adds them to the set for use across athenahealth. If your team needs a specific icon for a current project, follow these guidelines to create your own icon and contribute it to Forge:

• Develop the broadest icon you can for your use case (don’t use an image of a steak to indicate all foods).
• Develop the simplest icon structurally (don’t add leaves to a tree icon).
• Use whole numbers wherever possible. Half pixels are okay but not ideal. Use quarter pixels only to center or align objects inside the icon.
• If your icon uses a shape that already exists as part of another icon (like a checkmark or strikethrough), copy that element from the existing icon for consistency. 

Size

Forge icons are available in two sizes: 24px and 16px. This means that the longest dimension of your icon should fit inside a 24px frame for large icons, or a 16px frame for small icons. For example, the Large Document icon is 24px tall and 16px wide.

When designing a new icon, start with the large (24px) size. Once you’re happy with it, create the small version. Don’t just scale down the large icon: reduce the visual complexity and increase the abstraction, while still trying to convey what the icon is meant to represent. A good example of this is the Translate icon, which reduces the visual complexity while maintaining the icon’s meaning.

Stroke

Use strokes to build your icon. Strokes should be 2px wide, center aligned, with rounded end caps. Don’t flatten or expand strokes; keep the icon editable. 

For an icon with a triangular or other non-square corner (like Star or Alert), use a fill and a 2px stroke, so you can set the corner radius value to a whole number. For dots or other objects where a 2px stroke is too big, use a fill with no stroke applied.

Icons related to “remove” or “undo” actions must have a strikethrough from the top left corner to the bottom right corner, and 1px of white space along the top side of the strikethrough to improve readability.

Shape

If the imagery is based on a rectangular shape (like Clipboard or Document), the bottom right corner should have a 3px corner radius, and the other corners should use mitered joins. If your icon isn’t based on a rectangle (e.g., Vaccine or Send), all corners should use rounded joins.

In all instances, maintain the same numerical corner radius between the 24px and 16px versions instead of reducing it so they appear proportionally similar.

Typography

If an icon contains a letter, number, or symbol character, use Source Sans Pro, Semibold. Don’t reduce a large font size to fit: instead, use font sizes that are appropriate for the final sizes (24px and 16px) of your icon.

Once you’re happy with the design, flatten or expand the font (the icon must contain only vector objects). Adjust the shapes to round pixel dimensions to whole numbers, but don't modify the letterforms beyond that.

Color

Final icons should be submitted in 3 Forge colors:

• #373738 (Font/default)
• #0466B4 (Interaction/default)
• #B6B7B7 (Font/disabled)

1. Submit initial icon concepts as an unmet need request, using the Forge contribution process.
2. Icons can be designed in Figma or Illustrator but must be imported into Figma to be considered for review.
3. In Figma, go to the Forge Design System library. Create a branch and name it with the name of your icon and the Jira contribution story number you received when the CRiB approved your request (for example, “AddPage UXDS-0123"). You can either create your icon in this branch or create it in your own Figma file and paste it into this branch when it’s ready.
4. Build your icon:
   1. Create both 24px and 16px icons (set in frames) in the Font/default color. Duplicate and recolor each icon in Interaction/default and Font/disabled colors by linking it to the Forge color styles.
   2. Convert each icon variation into its own component, and then combine them as variants. Create size and color variant properties and confirm that there are no conflicts.
   3. Make sure each variant has auto layout enabled and is set to center alignment. Frames should be set to hug contents, with any padding required to keep the icon container square.
      Note: You may need to use Figma’s union command to make the icon; otherwise, auto layout may reorder your icon elements.
   4. On the Icons page, place your icon set above the alphabet row. Arrange your icon variants in a variant box, in the same order as the other icons on the page.
5. Final contributions must meet Forge’s Design Definition of Done, which is:
   1. The icon meets the criteria in the Principles and Guidelines for creating new icons.
   2. The component contains all variations, using Figma’s variants feature.
   3. The component links to Forge color styles in Figma.
6. Submit your branch for review:
   1. In the text field, enter the usage for your icon (“Use to...”; see the Icons Table for examples).
   2. Assign the review to a Forge designer.
7. If the Forge team has any recommendations, we will return your branch to you with comments. Iterate your design and resubmit.
8. Following approval, the Forge design team will merge and publish your branch, and your Figma component will be available in the Forge Design System library. The Forge team will also add your contributed icon to code and the Forge guide.

• Icon Usability: https://www.nngroup.com/articles/icon-usability/

• Icons in Figma: https://www.figma.com/file/DBlEpYaRcA4ml13izQV044/%F0%9F%94%A5-Forge-Design-System?node-id=9936%3A7558
• Icons in Storybook: http://go/forge-storybook