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
- If you are adding an icon:
- Copy and rename the icon template files
- Add the exported icon SVG to the.svg
file
- Add the icon metadata to the.yml
file - If you are editing an existing icon:
- Replace the existing icon SVG in the.svg
file
- Update the relevant metadata in the.yml
file - Run
yarn changeset
to 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:
- Adddeprecated: true
to the icon’s.yml
file. -
If you are deprecating an icon with replacement:
- Rename the icon’s.svg
and.yml
files.
- Adddeprecated_aliases
to the.yml
file.
- List each of the icon’s previous names. For example, if you were to renameOldMajor
toNewMajor
, you would add these lines toNewMajor.yml
:Exampledeprecated_aliases: - OldMajor
-
Run
yarn changeset
to 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.