Any designer within Shopify can contribute to the Polaris UI Kit for Figma. If you find a bug to fix or have new work your team is contributing to Polaris, you should feel empowered to contribute that to the UI kit. No need to ask for permission—go for it. If you need help or have questions, reach out in the #polaris Slack channel.
How to contribute
Create branch
Create a branch in the Polaris Components Figma library
Name branch
Give your branch a descriptive name. If it has a corresponding GitHub Issue, use that number in your branch name so it's easy to track.
Add change notes
Document all changes in the Changelog page.
Request review
Request for a Polaris designer to review the changes on your branch. If you aren't sure who to add, reach out in the #polaris channel and ask for a review.
Merging and publishing (for maintainers)
Review work
Open the branch, read the changelog entry and test everything to make sure it works
Request changes (if necessary)
If changes are needed select “Request changes” on the approval screen. Detail what issues need to be fixed before the contribution can be merged.
Approve and merge
If changes are approved, select “Approve and merge” to merge changes into the main branch.
Save to version history
Manually add a to the file version history noting the branch and changes merged.
Guidelines and best practices
Contributing to the UI Kit doesn’t need to be scary. Here are a few tips, tricks and best practices to keep in mind that will help you make a quality contribution.
Use auto layout
Even when it may not seem totally necessary, things in Figma just work and scale better when auto layout is utilized. Figma has some great documentation if you need to brush up on it.
Name your layers and frames
Naming things makes it so much easier for others when they use the file or components from it down the road.
Align naming with React component
Align naming with the corresponding property or component in the Polaris React repo. Doing this helps designers and developers speak the same language and removes barriers to collaboration.
Save to version history
Use “File -> Save to Version History” to keep track of what you have done. Using this feature allows you to hard save your work at a specific moment and add notes about what has changed. This takes the guess work out of remember things and gives you a safe spot to revert back to if something goes wrong later on.
Follow formatting conventions
Do your best to follow the layout and labeling conventions already in the UI Kit. This makes it easier to maintain over time and keeps our quality standards high.
Test your changes
It isn’t always clear how an component change will effect an existing component instance in someones file. One way to get a better sense of this is to drag out a few instances to the side of your canvas before you start working. Changing some of the overrides is also a good idea. This way if a channge you make is going to break a component you will see it happen.