Skip to contentShopify logoPolaris

Contributing to Polaris

Polaris is built for merchants, by you.

Anyone, regardless of discipline, is encouraged to contribute to Polaris. We welcome everything from copy edits and bug fixes to new components.

Should I contribute?

Contributions should address a known issue or gap in the system, and they should add value at scale. Sometimes unique solutions are best for the user, but they don’t necessarily need to be in Polaris. You can still build custom solutions using Polaris tokens and best practices.

Icon contributions—like copy edits, bug fixes, and icons—are often worthwhile. They’re simple to implement, and they improve system quality and trust.

Major contributions, like patterns or some components, typically require more evaluation. This flowchart will help you decide whether or not your solution is right for Polaris. If you’re unsure, reach out to the Polaris team directly.

Contribution types

Generally, we can classify contributions as minor or major. Icon contributions can be made by an individual or a small team, and the solution is often clear and simple. Major contributions usually introduce breaking changes to the system and require greater involvement from the Polaris team.

For example:

  • Bug fixes and documentation (minor)
  • Icon additions or updates (minor)
  • Component additions or updates
    • Style changes (minor)
    • New or redesigned components (major)
    • API change (major)
  • Patterns (major)

How to contribute

With the exception of our Figma UI kits, all contributions to Polaris are made through GitHub. Check out the directions for each contribution type:

Icon or patch contributions can usually be started directly through a GitHub pull request, but if you’re unsure, you can always check with the Polaris team. For major contributions, we recommend creating a contribution proposal.

Proposing a contribution

Major contributions to Polaris should start with a proposal. When proposing a contribution, consider the following:

  • Have I used the existing Polaris patterns, components, and tokens to their limit?
  • Does my solution bring significant value to the admin and to other teams?
  • Have I verified its effectiveness?
  • What impact could my solution have on existing implementations?
  • Do I have the resources (people, time, tools, etc.) to follow through?

Use the contribution proposal template in GitHub Discussions to start a contribution proposal. Be sure to include any relevant explorations and documentation.

Getting help

If you have questions about how, what, or when to contribute, the Polaris team is here to help.

  • Use GitHub Discussions to propose solutions, discuss new ideas, or ask questions
  • If you work at Shopify, use the #polaris Slack channel for support

    On this page