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
- For example,
@atlaskit/icon/utility/migration/<new-icon>--<legacy-icon>
- For example,
@atlaskit/icon/utility/migration/success--check-circle
- For example,
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 fromprimaryColor
, and restricted to accessible color tokens andcurrentColor
.
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 tocolor
, 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
— expandedlabel: string
— unchangedsize?: 'small' | 'medium' | 'large'
— deprecatedprimaryColor: string
— replaced withcolor
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 tonone
spacing. - Icons with a size of
medium
will be automatically adjusted tospacious
spacing. - Icons with a size of
large
orxlarge
will not be automatically migrated and will continue to display the legacy icon. - The deprecated
primaryColor
prop will map to the newcolor
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
, andsecondaryColor
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?