Contributing to Polaris Icons
Polaris Icons are important visual aids that help merchants understand actions and concepts across the Shopify Admin. Whether your team needs to add, modify, or deprectate an icon, all designers and developers that work at Shopify are welcome to contribute.
Before proposing a new icon, search the icon explorer. If the icon you’re looking for isn’t included, create a proposal for the new icon and work with your team to add it. Any additions or changes should also be reflected in the Figma UI Kit.
To learn about best practices for designing and using Polaris icons, read the icon design guidelines. If you have initial questions or need help, reach out in the #polaris Slack channel. If you want to start a more in-depth conversation with the system community before opening an issue, start a GitHub discussion.
Design a new icon
- Submit an icon proposal.
- Review design specs in the Polaris Icons library in Figma.
- If you are designing a new icon:
- Draft the new icon following the design language guidance in the Polaris Icon Library in Figma.
- Request feedback from a Polaris designer.
- If you need assistance designing the new icon:
- Reach out in the #polaris Slack channel requesting a new icon.
- A designer will reach out to get context and information around what you need, deadlines and other relevant information.
- A designer will work with you to design an icon that meets your team’s needs with your feedback along the way.
- Once alignment on the design is reached, follow the instructions below for adding the icon.
Add or edit an icon
- Submit an icon proposal
- Set up your development environment
- If you are adding an icon:
- Copy and rename the icon template files
- Add the exported icon SVG to the
- Add the icon metadata to the
- If you are editing an existing icon:
- Replace the existing icon SVG in the
- Update the relevant metadata in the
yarn changesetto add an entry to the change log and release notes
- Commit your changes and open a pull request in the Shopify/polaris GitHub repo
- Update the Polaris Icon Library in Figma
Deprecate an icon
Submit an icon proposal.
If you are deprecating an icon without replacement:
deprecated: trueto the icon’s
If you are deprecating an icon with replacement:
- Rename the icon’s
- List each of the icon’s previous names. For example, if you were to rename
NewMajor, you would add these lines to
deprecated_aliases: - OldMajor
yarn changesetto add an entry to the change log and release notes.
Commit your changes and open a pull request in the Shopify/polaris GitHub repo.
Update the Polaris Icon Library in Figma.