RFC-81: Upcoming changes to Iconography

General Request for Comments (RFC)
, , , , ,
1

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.
  • 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?
3 Likes
2

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

12 Likes
3

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.

8 Likes