Subject: Enhancing Iconography: Updates and Improvements Based on Your Feedback
Hi everyone,
First, thank you for your insightful feedback on the iconography changes shared in the RFC. Your commitment to maintaining consistency and delivering exceptional user experiences is invaluable to us.
As announced at Team ‘25, Atlassian’s new visual language refresh is now rolling out across products including Jira and Confluence, and customers have started using experiences featuring the new iconography.
We are making changes to improve the icon system based on how we’re seeing the new icons used, and based on your feedback. In this post, we’ll share what’s changing and why, and also address some of the concerns raised previously.
What’s Changing with Iconography?
- Single entry point for icons with two size options. To better align with Atlassian’s evolving design language and simplify our iconography system, we are making the following changes:
- Reintroduction of the Size Prop: We are bringing back the size prop, allowing icons to be used at both Medium (16px) and Small (12px) sizes. This change provides more flexibility and options for using small icons, which were previously limited to the utility set.
- Unified Entry Points: Utility icons (12px) will be deprecated, simplifying the entry points and allowing a more extensive range of icons to be available in both sizes. This consolidation eliminates the distinction between core and utility icons, providing a more streamlined system.
- Migration tooling:
- To help you transition, we’ve introduced tools like the no-legacy icons and the no-utility-icons lint rules, which automate much of the migration process.
Why Are We Making These Changes?
Our goals with these updates are to:
- Expand Flexibility: The reintroduction of the size prop offers more flexibility for using small icons, enabling better support for diverse use cases like compact UI elements and secondary actions.
- Ease of Use: By consolidating icons into a single system, we simplify the process for both developers and designers, making it easier to integrate and maintain icons within your applications. This change will provide a more comprehensive icon library to meet your needs.
Addressing Your Feedback
We’ve taken your concerns seriously and have made specific adjustments:
- Reinstating the Size Prop:
- We’ve reinstated the size prop and provide guidance on when to use the two sizes. Medium (16px) should remain the default in most cases, other than the specific cases mentioned above. While the focus is on fixed sizes (16px and 12px) for consistency, we welcome specific examples of scenarios where scaling is essential so we can explore potential solutions together.
- Padding and Spacing:
- The new spacing prop is designed to provide more control for aligning icons within their containers. However, please note that the spacing prop is introduced primarily to assist with migration and to offer flexibility during this transition.
- In the future, we plan to remove the spacing prop to streamline the system. We hope that many of your concerns about additional work to manage spacing have been alleviated with the reinstated size prop.
Next Steps and Support
We recommend all partners start migrating your apps from the legacy icons to the new iconography system, to match the visual language of Atlassian products.
The new iconography system as part of the Atlassian Design System will shortly transition from Beta to General Availability (GA) in late June 2025, and we will deprecate the legacy iconography system. It will be removed at the end of the 6-month deprecation window.
We are committed to supporting you through this transition:
- Migration Support for Connect and Forge Custom UI:
- Updated documentation, tooling, and lint rules are available to guide the migration process. Details on the spacing prop and new size options can be found at atlassian.design.
- The migration pathway is designed to minimise manual effort. Tools like the no-legacy icons and the no-utility-icons lint rules can automate much of the process, including migrating away from legacy icons, i.e. the
@atlaskit/icon/glyphpackage, migrating utility icons to core icons and switching to the recommended sizes. - The two-step migration (using temporary migration entry points) is no longer required. You can directly migrate to the
@atlaskit/icon/coreentry points.
- Migration support for Forge UI Kit: This will be shipping shortly alongside updated documentation, as part of the iconography system reaching GA.
- Ongoing Feedback: Your feedback is crucial. Please share any specific use cases or areas where the new system may require additional flexibility.
(If you were an early adopter and are already using the utility icons in the new iconography system, those utility icons will be also be deprecated as they are now replaced with the single entry point for icons with two size options.)
Thank You for Your Partnership
We recognise the effort these changes require and deeply appreciate your collaboration. Your feedback has been instrumental in refining our approach, and we’re committed to working with you to ensure the best outcomes for your applications and our shared users.
If you have any questions, concerns, or additional feedback, please don’t hesitate to reach out here or through our support channels. Let’s continue building a more consistent and cohesive experience together.
Warm regards,
Sim Saini