RFC-81: Upcoming changes to Iconography

[AkshaySaini]

RFCs are a way for Atlassian to share what we’re working on with our valued developer community.

It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.*

Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!

Project Summary

At Team '24 we announced a visual refresh to evolve and modernise the user interface of our products to enhance visual appeal. Please review this overview of the project: A visual refresh of our UI foundations is coming

We’re updating our iconography as part of this visual refresh, with our icons playing a significant role in defining user interface experiences.

The new icons can be previewed on the Atlassian design website.

• Publish: 10 January 2025
• Discuss: 31 January 2025
• Resolve: 14 February 2025

Problem

In order to update our iconography, we need to replace the existing set with a new collection that offers greater consistency in weight and style.

This initiative aims to ensure optical balance across the UI while providing clearer representations of various concepts, ultimately leading to a more cohesive and engaging experience for our users.

We’re seeking feedback from our Marketplace partners to ensure we build the best possible solution for apps to adopt the improved look and feel.

Proposed Solution

These new icons will replace the existing set; while many icons have been updated, some have been removed, and others have designated migration paths to their new counterparts. In conjunction with the icon updates, the props for these icons has been modified, resulting in the removal and renaming of certain properties.

When these icons are released in Atlassian products, Marketplace apps also need to be updated to ensure a consistent appearance between the product and app user interfaces.

Our objective is to facilitate a seamless transition to these icons for the Forge UI Kit, Forge Custom UI, and Connect applications, thereby ensuring a uniform look and feel across all Atlassian products.

The migration pathway for legacy icons

Upon the release of the new icon set, we will deprecate the legacy icons. A migration mapping is available for legacy icons that have a corresponding equivalent in the new icon set.

As such, legacy icons can be classified into three distinct categories.

• Updated: An update for this icon is available in the new icon set.
• Migrated: The icon has changed but there is a recommended migration pathway
• Removed: The icon is no longer present in the current icon set, and there is no automatic migration path available: [billing, billing-filled, camera-rotate , camera-take-picture , canvas, dropbox, folder-filled, following, googledrive, gsuite, highlights, hipchat/chevron-double-down, hipchat/chevron-double-up, hipchat/media-attachment-count, image-border, issue-raise, list, mention, notification-all, pdf, person-with-circle, person-with-cross, portfolio, presence-active, presence-busy, presence-unavailable, status, vid-audio-muted, vid-backward, vid-camera-off, vid-connection-circle, vid-forward, vid-hang-up, vid-hd-circle, vid-raised-hand, vid-share-screen, vid-speaking-circle, editor/addon, editor/advanced, editor/file-preview, editor/image-border, editor/remove-emoji, editor/strikethrough, editor/table-display-options, editor/text-color, editor/underline, emoji/atlassian, bitbucket/builds, bitbucket/clone, bitbucket/compare, bitbucket/forks, bitbucket/output, bitbucket/pipelines, jira/failed-build-status, media-services/annotate, media-services/arrow, media-services/blur, media-services/brush, media-services/button-option, media-services/line-thickness, media-services/no-image, media-services/open-mediaviewer, media-services/oval, media-services/pdf, media-services/rectangle, media-services/text, media-services/unknown, media-services/zip]

To view the migration pathways for each icon, see the “New icon” field in the legacy icon explorer.

What does this mean for Forge UI Kit?

To facilitate the migration of Forge UI Kit marketplace apps to the new icons, the proposal is to implement a temporary icon facade that will automatically transition icons wherever feasible.

In addition, the glyph property in the Forge UI Kit Icon component will be updated to include the new icons. The legacy icons that do not have an exact name equivalent in the new icon set will be deprecated and ultimately removed upon the conclusion of the deprecation period.

What does this mean for Forge Custom UI and Connect?

Marketplace apps built using Connect or Forge Custom UI are able to access Atlassian Design System icons through Atlaskit.

For now applications are able to continue to use the legacy icons by importing from @atlaskit/icon/glyph/*. These icons will be deprecated and removed from the @atlaskit/icon package in a later version of the package.

To facilitate the early adoption of the new icons, @atlaskit/icon includes a set of temporary migration entry points, that allow for feature-flagging between the old and new icon components when a migration pathway exists. These entry points have the following format:

• @atlaskit/icon/core/migration/<new-icon>--<legacy-icon>
  • For example, @atlaskit/icon/core/migration/add--add-circle
• @atlaskit/icon/utility/migration/<new-icon>--<legacy-icon>
  • For example, @atlaskit/icon/utility/migration/success--check-circle

In some cases, legacy icons may have a few migration pathways available. For example the legacy document-filled icon can be migrated to either file or page. As such there are two migration entry points:

• @atlaskit/icon/core/migration/file--document-filled
• @atlaskit/icon/core/migration/page--document-filled.

Atlassian products control which icons display when the migration entry point is used, depending on the roll-out of the visual refresh for a given instance or user. This will be transparent and require no extra effort from marketplace apps.

It is important to note that importing the new icons directly from the @atlaskit/icon/core/* and @atlaskit/icon/utility/* entry points is strongly discouraged until General Availability. These entry points are not feature-flagged and will lead to inconsistencies in appearance between the product user interface and Marketplace apps. After General Availability, you can migrate using only these entry points for the new icons.

The migration entry points are intended to be temporary and will be removed along with the legacy icons once the deprecation period concludes. We will provide tooling to automatically clean up /migration entrypoints. Prior to this removal, we will provide communications to inform Marketplace partners that the use of @atlaskit/icon/core/* or @atlaskit/icon/utility/* is available, and that marketplace apps should begin updating their imports to transition away from the temporary migration entry point.

For example, @atlaskit/icon/core/migration/add--add-circle will need to be modified to @atlaskit/icon/core/add.

Changes to the Icon props in Atlassian Design System

The recent updates to the Atlassian Design System have resulted in changes to props accepted by the new icons, including the deprecation of certain props and the introduction of new ones.

New Props

• spacing - Allows you to apply padding directly to the icon, helpful for matching the size of the old icons during migration. none is the default, and is our recommended value going forward.
• color - Renamed from primaryColor, and restricted to accessible color tokens and currentColor.

Further information about the new props, can be found here on the Atlassian Design website.

Deprecated Props

• size - The updated icon system removes the ability to scale icons, which previously led to inconsistencies in sizes, stroke widths, and padding. Icons are now fixed in size, ensuring uniformity across product experiences.
  • By default, core icons are 16px in size
  • A reduced set of utility icons are available with 12px dimensions, for cases where smaller icons are still needed. See further information about these icons.
• primaryColor - Renamed to color, see above.
• secondaryColor - Removed as the new icons no longer have filled regions.

What does this mean for Forge UI Kit?

To maintain consistency with the Atlassian Design System, the prop changes above will be reflected in the Forge UI Kit Icon props:

• glyph: string — expanded
• label: string — unchanged
• size?: 'small' | 'medium' | 'large' — deprecated
• primaryColor: string — replaced with color
• secondaryColor: string— deprecated

When referenced as the glyph, new icons in the set will support only the new props, while updated icons will support both old and new props. Note that whenever the new props are used, the new design will always be shown to users regardless of whether facade is on or off.

To help facilitate a seamless transition, we propose a icon facade that, where possible, will temporary perform this migration behind-the-scenes, allowing the new icons to be shown to end-users before you perform any manual migration of props or glyph names. This facade is only temporary — and will be removed along with the old properties after the deprecation period.

We recommend switching from deprecated (removed) icons now, as well as unsupported primaryColor values, and the large and xlarge sizes. After this, you can rely on the facade to display the correct icons during the roll-out period, and then migrate permanently once we’re in General Availability.

What does this mean for Forge Custom UI and Connect?

When Forge Custom UI and Connect apps swap from the old @atlaskit/icon/glyph entrypoints to the new icons from @atlaskit/icon/core/migration or @atlaskit/icon/utility/migration, their usage of icon props will also need to be updated.

When using these migration entrypoints, we plan to allow control of the deprecated icon props via a number of LEGACY props, such as:

• LEGACY_size
• LEGACY_primaryColor
• LEGACY_secondaryColor
• LEGACY_margin

It is important to note that these props are for migration purposes only; they will be deprecated along with the migration entrypoints, when the new icons are officially released.

Forge UI Kit Icon Facade

To help Forge UI Kit marketplace apps migrate icon usages, we intend to provide a temporary icon facade that, where possible, displays the new icons in place of the old icons before any manual migration is performed.

This allows for rapid testing and delivery of the new icons in apps - however manual intervention will be eventually required to update deprecated property usage and address the removal of legacy icons across your app before the deprecation window closes.

• Legacy icons that fall into the updated or migrated category will automatically switch to their new icon equivalent.
• Legacy icons that fall into the removed category will continue to show the legacy icon.
• Icons with a size of small will be automatically adjusted to none spacing.
• Icons with a size of medium will be automatically adjusted to spacious spacing.
• Icons with a size of large or xlarge will not be automatically migrated and will continue to display the legacy icon.
• The deprecated primaryColor prop will map to the new color prop. If the color is unsupported, the legacy icon will be shown.
• The facade will be an automatic opt-in, but will have the ability to opt-out to let ecosystem apps continue to display legacy icons with the deprecated props until they convert all icons to the new icon set and API.

The icon facade is temporary and is intended to remain in place until the deprecation window for the properties has concluded. Following this period, both the deprecated properties and the icon facade will be removed.

Asks

While we would appreciate any reactions you have to this RFC (even if it’s simply giving it a supportive “Agree, no serious flaws”), we’re especially interested in learning more about:

Forge UI Kit

• How do you feel about the temporary icon facade designed to assist in migrating icon usage? Do you think it will effectively streamline the migration process for your applications?

Forge Custom UI / Connect Apps

• Would you be keen to start adopting the new icons via the migration endpoint?
• What factors would influence your decision to adopt these changes early?

General

• Are there any concerns or suggestions regarding the changes to icon properties, such as the deprecation of size, primaryColor, and secondaryColor props?
• Do you have any other suggestions or concerns regarding the proposed changes to the iconography and its impact on your applications?
• Roughly when would you consider fitting this work on to your app’s roadmap?

Amendments

ESLint auto-fixer to assist with migration

A new no-legacy-icons lint rule has been introduced that helps identify instances of @atlaskit/icon/glyph that haven’t been migrated to the new icon API and automatically fixes them by replacing them with the relevant icon from the migration endpoints where possible.

In the case where automatic migration is not possible, a manual migration lint error will be shown with additional guidance.

When the new Iconography reaches GA it will also facilitate the migration of icons from the migration endpoint to the final “core” and “utility” icons from @atlaskit/icon, which automates the final step of migration.

[tobias.viehweger]

Hi @AkshaySaini,

please understand my comments with the knowledge that I’m actually someone who cares deeply about consistency and is usually on the forefront when it comes to adopting new UI things, to match the Atlassian design system well (e.g. dark mode in all our apps, etc.).

This proposal however, is not something we are going to do, I’m afraid, as it basically creates a huge overhead in terms of development for us, only to achieve consistency for a few months (if at all). We are not currently using codemods in any capacity, because the size of the codebase currently does not justify the investment, so for us, all of this means adjusting all icons manually.

I just checked, and we currently have 650 uses of Atlaskit icons at the moment. I have a hard time imaging a solution that would be more effort for us, than what you are proposing, this is by far the worst outcome - sorry to be so blunt.

A way better solution would’ve been you transparently switching the old implementation to use the migration components internally and allow us to use the migration by just upgrading the package.

Example:

// Current implenmentation in our code (@atlaskit/icon: ^22.24.1)
import ChevronDownIcon from '@atlaskit/icon/glyph/chevron-down';

...
<ChevronDownIcon label="Login" size="small" />

Now, could you not release a new major icon package version which just switches the internal exports to the migration one? E.g. in @atlaskit/icon/glyph/chevron-down.ts you do:

// Code in @atlaskit/icon/glyph/chevron-down.ts
import ChevronDownIconMigr from "@atlaskit/icon/core/migration/down--chevron-down";

const migratedIcon = props => {
return <ChevronDownIconMigr 
              LEGACY_size={props.size}
              LEGACY_primaryColor={props.primaryColor
              LEGACY_secondaryColor={props.secondaryColor}
              LEGACY_margin={props.margin}
              ...props
     />;
}

export default migratedIcon;

And release this as a new major icon version? Or as a separate package (@atlaskit/icon-new)? Why does every single consumer need to do this mapping and then remove it a month later again? This is what breaking/major update in packages are meant for. If there is no simple 1:1 mapping, you could remove these icons and we could go ahead and fix them manually, but this would be still at least factor 10 less effort than adjust everything.

Reiterating: If this proposal goes through as is, we will not use the migration components but switch to the new icons only at some point, accepting there will be inconsistencies along the way - the effort to migrate everything twice is just not justifiable for us, considering all the other initiatives (Forge etc) we need to be tackling right now (see Taking the Ecosystem Forward: An Update on the Future of Connect).

If your aim is indeed widespread consistency, also in the in-between rollout phase, I would strongly suggest reconsidering the approach, I have a hard time imaging that this will see the broad adoption you are aiming for (which a simple package update would make much easier).

Thanks for the detailed write-up!

Best
Tobi

[JariSanders1]

I’m assuming the removal of the size property has something to do with consistency in interfaces. I’m a big fan of consistency and think it is important to strive for consistency throughout all Atlassian products, but I’m afraid removing the size prop is going to result in chaos, rather than consistency.

In our case, if the size prop is going to be deprecated, we will either opt for a custom icon set, or create our custom icon component. Both will result in more inconsistency.

The current state of the icons is chaotic due to differences in sizing and padding within the containing frame. Adding a spacing prop will allow for the same type of differences, but instead of the issue being in the image file, it will be moved to the code. Adding the right amount of padding consistently across all icons has been, and is the industry standard, please do not ruin the upcoming update by adding the same chaos that we currently deal with.

The introduction of the facade makes absolutely no sense, as the need for it is self-inflicted. Continue supporting the size prop and there will not be any need for the temporary facade.

As for primary color and secondary color: I’m biased, because as far as I’m aware we do not use secondaryColor. Transitioning from primaryColor to color seems like a good cleanup from my perspective.

In conclusion, I think the migration should be reconsidered. Our time as developers is precious, adapting/moving to forge is already a huge slap in the face considering it is simply not ready for use for many apps, asking developers to spend time on updating icons would feel like a knife in our backs.

Suggestion:

• Fix padding, spacing and sizing in the actual svg files of the icons.
  -Leave size? unchanged, but add custom: X as an accepted value so developers can determine the right size for their use case. (For example, a large icon for an empty state page).
• Deprecate secondaryColor
• Replace primaryColor with color

To finish things off positively: I’m very happy Atlassian is investing in proper icons across all their products. I hope we can start using them in the near future, let’s hope we do not have to create our own custom component to be able to use different sizes.

[AkshaySaini]

Hi Tobias,

This is all very helpful feedback and really would like to thank you for taking the time to clearly identify the flaws you see in this approach. I want to clarify that the migration endpoints are optional if you wish to maintain consistency with your app and product when the icons are officially released in Atlassian products. You always have the option to migrate to the new icons once they reach General Availability (GA), as we recognise that this approach may not suit everyone.

This detail should have been included in the RFC, but unfortunately, it was overlooked. We have a no-legacy-icons linting rule that helps identify instances of @atlaskit/icon/glyph that haven’t been migrated to the new icon API and automatically fixes them. It can also facilitate the migration of icons using the migration endpoint to the final “core” and “utility” icons from @atlaskit/icon or @atlaskit/icon-lab, which eliminates the need for a second manual migration.

It’s worth noting that we have seen great success with the auto-fixing feature, successfully migrating 75% of our icon usage in Jira.

Cheers!

[AndreasRutzK15t]

Hi Atlassian team,

Thanks for sharing this RFC. I think the refresh is a great step towards improving visual consistency and clarity across your products.

That said, I have a couple of thoughts: The removal of the icon size property will impact various UIs in several ways. While aligning with Atlaskit guidelines is important, it might be helpful to provide some flexibility for developers to make intentional adjustments in cases where strict adherence isn’t practical. Couldn’t specifying the recommended sizes in your documentation and setting them as default values be enough? If the size property is removed, we’re going to look for an alternative solution. Fixed icon sizes are sometimes just not practical.

Additionally, the proposed upgrade path looks a bit cumbersome to me. Like already mentioned in another comment: Why do we need to migrate twice? Why can’t you do the upgrade just internally? We definitely want to keep consistency, but upgrading twice is quite a trade-off.

[AkshaySaini]

Hi @JariSanders1 (and @AndreasRutzK15t),

Thank you for taking the time to share your suggestions. We’d would love to hear more about the specific scenarios in which you are using the size prop.

Our design goal for this project has been to improve consistency for iconography by preventing scaling of icons, which has lead to the inconsistent stroke widths and visual weights that currently exist when using the old system. The spacing prop provides an optional convenience for adding padding around an icon, and does not change the rendered size of the glyph. Regarding the size prop, we recommend replacing larger icons with illustrations in views like empty states and error states - if there are other use cases where these new sizing restrictions aren’t feasible for your apps, we’d welcome your feedback.

In terms of the two step migration for Forge Custom UI and Connect apps, the two-part migration is optional if you want your app to switch between the old and new icon designs while the visual refresh rolls out in Atlassian products. We have included a new no-legacy-icons lint rule which can automate these migration steps where possible. We have amended this RFC to include details about this eslint auto-fixer.

Cheers!

[JariSanders1]

@AkshaySaini

Our design goal for this project has been to improve consistency for iconography by preventing scaling of icons, which has lead to the inconsistent stroke widths and visual weights that currently exist when using the old system.

I’m not sure if I understand this statement. Scaling, if done proportionally will not cause any differences in stroke widths or visual weights. Forcing people to start using other icon libraries and components will cause that.

if there are other use cases where these new sizing restrictions aren’t feasible for your apps, we’d welcome your feedback.

There are, and I did share my feedback, at least, that was my intention with my previous message.

Getting rid of the size prop is like forcing everyone to use <p> and get rid of all headings. The fact this does not make any sense is proven in your own UI, in the Navbar alone, there are 3 icon sizes, and for good reason! There are even more if you include the sidebar.

Sizing of any type of element is essential to good user experience. Have you discussed this proposal with designers at Atlassian?

[AkshaySaini]

Thank you for sharing, could you share some specific situations where scaling is essential for your app? Feel free to share screenshots etc

The screenshot you provided of the Atlassian UI actually highlights how our icons maintain a consistent size across all Atlassian products. While the padding surrounding the icons may differ—an implementation detail—the icons themselves are standardised at either 16px for core icons or 12px for utility icons. The 32x32 element you referenced is not an icon, which explains the size discrepancy.

[JariSanders1]

I don’t think it makes sense to be sarcastic with your comment. If you really do want more feedback I’m happy to help but I feel like you’re messing with me now.

[MattDoar]

Not how I read the reply.

[JariSanders1]

Assuming there was no sarcasm involved in the comment shared earlier, I’ve gone ahead and went through some of the Atlaskit components to try to explain why I’m surprised by the proposal.

I could share screenshots of our apps of other apps on the marketplace, but I think the fact Atlaskit contains varying icon sizes shows us how in some cases it’s simply necessary to do so.

[AkshaySaini]

Apologies if my response seemed sarcastic, that was not my intention at all. I was trying to correct some misunderstanding around the icons in your screenshot.

Thank you for providing those new screenshots, I can see they are from our Figma community library. The new iconography is still in beta and we haven’t switched over the icon usage in our Figma library just yet, as such the icons shown are our old icons. With the new icon set, each of these examples can be replaced with a new icon from the utility or core set. The spacing prop may be required to ensure the icon is correctly spaced inside the icon slot.

For example the 16px cross, lock-filled and cross-circle icons you have identified will move to 12px utility icons with a spacing prop value of compact which provides a 2px padding, resulting in a container size of 16px. The backlog, warning, star-unstarred and image icon will use the 16px core icons with a spacing prop value of spacious which provides a 4px padding, resulting a container size of 24px. This will allow us to migrate without causing any layout issues in our Atlaskit components.

I appreciate you providing these screenshots, as they do highlight some of the steps involved to migrate from the old to new icons, and where the spacing prop may be required during this migration period to match the container size of the new icons when composed into other components. Do you have any additional examples you can provide where these spacing props are insufficient, and you require the ability to scale the SVG glyph up or down from the provided utility (12px) and core (16px) sizes?

[JariSanders1]

Can you elaborate on the thinking behind requiring spacing in order to make icons look well-proportioned in a specific context?
Are there any other use cases, interfaces, companies, experiences that could explain this unorthodox way of working, rather than just making sure icons have consistent spacing and have the context determine padding around the icon box?

The way it’s explained now, it seems like we would have to adjust spacing based on the content rather than context, which would mean extra work each time you’d add an icon to a component.

I’m repeating myself here but I’m really interested to find out if this was discussed with designers within Atlassian at all.