Iconography

Icons are visual representations of commands, devices, directories, or common actions.

Icons should be used to maximize comprehension and reduce cognitive load when you need to call attention to a particular action, command, or section. Our icons are designed with our brand personality baked in.

You can view all design system icons in the icon explorer.

Icon usage guidelines

Use icons infrequently – if you’re questioning an icon’s use, it probably doesn’t need to be used at all.

As a general rule, icons should be used in combination with meaningful text to support users progressing through the product in an accessible manner.

Do

Use icons with meaningful text labels.

Don’t

Icons without labels can be unclear.

Avoid using icons solely for decoration or visual interest, as it detracts from their intention elsewhere. Consider the surrounding context of icons too; if icons are cluttered and not spaced well, it can lead to visual noise and confusion.

Do

Use a single icon for clarity.

Don’t

Too many icons in UI create visual noise.

Icons can represent a single concept such as + which always represents ‘add’, or be thematic in concept such as ☆ which might represent "favorite", "like", "star" etc. Using an icon appropriately allows our users to create a connection to a concept, so don’t over-extend what an icon represents.

Do

Use a single icon per concept.

Don’t

Multiple icon variations should not be used for the same concept.

Accessibility

There are very few widely recognized icons, so whenever possible, use a label or supporting text to ensure the icon's meaning is understood. If an icon is used without a visible label, an aria-label must be used for the icon.

However, don't use aria-labels if you are rendering the icon with a visible text label to prevent accessibility label duplication.

Find out more about writing meaningful text in our accessibility guidelines.

Combining unfamiliar icons with text could confuse users depending on how they recognize the supporting icon, so make sure the icon and text label are coupled. To help enhance usability further, ensure the icon color has at least a Web Content Accessibility Guidelines (WCAG) 2.1 AA standard color contrast ratio.

Internationalization

Always consider icons from a global perspective. Whenever possible, use an internationally recognized icon in place of a locally recognized icon that may only apply to a specific background or culture such as a local currency symbol, € ¥ £, rather than always using $.

Platform specifics

Our icons can be used across web, iOS, Android, and macOS to represent similar concepts. Some icons, however, are already established conventions on specific platforms. In these cases, follow the conventions for the operating system using the OS-specific guidance.

Icon types

You can search for icons by filename or by usage in our icon explorer. There are three types of icons in our design system:

Standard icons

Standard sized icons are used as visual representations of common actions and commands to provide additional context and enhance usability. These icons can be scaled up or down in size if necessary.

Object icons

Object icons are specifically used to represent an object specific to an Atlassian product, such as ‘bug’ in Jira or ‘pull request’ in Bitbucket. These icons are different from standard icons and file type icons.

File type icons

Files type icons are often used in the same context as most other Object icons. There are common file types (txt, mp3, mov, etc), and third party integrations' file types (docx, ai, sketch, etc).

Style

Variations

Our icons have variations to work within a given context. There will be a line version, which can be accompanied by a filled version. Use the line version of our icon in most cases as they are visually balanced, so more than one can be used when close together.

Often, a filled version can be used to represent an action or command that has been carried out, such as using a filled star when a post has been “favorited“. You can use color to further reinforce this interaction and change.

Size

There are three icon sizes in our design system:

16px (small)

Small icons are best used when space is limited. We use small icons in our components such as a chevron-down in the select component or a cross-circle-filled in populated text fields.

24px (medium)

Medium icons are used in the majority of our interface. These are our standard size.

32px (large)

Large icons are used sparingly to emphasize a concept or when space is plentiful. Wherever it’s used, consider the fidelity of the icon in the space it’s being used. (If there's plenty of room, a spot illustration might be more appropriate).

In general, consider the context of the icon when adjusting the size such as the size of other icons surrounding it and the balance of other UI elements.

Color

To see a full list of icon colors available, go to the design tokens list.

Server

AUI icons use different sizing and certain icons may not be available. See the AUI documentation on icons.

  • View all design system icons in our icon explorer


Was this page helpful?
We use this feedback to improve our documentation.