Contributing to Polaris

Polaris exists to make a product worked on by many, feel like it was created by one person. The design system needs to stay in sync with new solutions so merchants always have a seamless experience. This is why Polaris thrives on contribution and community support.

Anyone, regardless of discipline, is encouraged to contribute. No contribution is too small. We welcome everything from bug fixes or new components, to new UX guidelines. So if you find something to contribute, we hope you feel empowered to go for it. The Polaris team is here to help you along the way.

Who can contribute

Contribution to Polaris looks different depending on whether you work at Shopify. Shopify employees can contribute to any Polaris project, including the Figma UI Kit. Open source contributions are welcome for Polaris React components and their documentation.

When to contribute

Contributions can seem intimidating, but they don’t have to be! Here are some common scenarios for deciding when to contribute:

Use the systemExtend the systemBuild a custom solution
When available resources can solve a design problemWhen a change or addition can solve a shared problemWhen a unique problem requires a unique solution
Read Designing with a system Read When to contribute new patterns Share ideas in #admin-ux (Shopify employees)
Review App Design Guidelines Create GitHub issue Build with Polaris tokens

What makes a good contribution

By sticking to a few principles, we can ensure that all contributions made to Polaris are of high quality, meaningful work for Shopify teams and contributors, and valuable to merchants.

Preparing contributionsSubmitting contributions
🧠 Keep the merchant in mind
Polaris is for building merchant admin experiences. If the value to merchants isn’t clear, reconsider the contribution.
πŸ’‘ Provide solutions
Contributions should both identify a problem and provide a solution. If you found a bug, have a question, or want to open a discussion, you can submit those via GitHub.
🀝 Collaborate with other disciplines
A good contribution addresses the needs and perspectives of design, content, and code. Consult a diverse group of disciplines when drafting your contribution.
πŸͺŸ Work in the open
Public discussion is crucial for contribution visibility and feedback. Submit contributions using GitHub. Shopify employees can request assistance via the #polaris Slack channel.
πŸ“… Include contribution in project cycles
Contributing close to a project deadline creates blockers. Include contribution in project retros, or involve Polaris early in a project cycle. Read Working with Polaris.
πŸ” Check your work
Double check your contribution to make sure it meets standards for things like accessibility and performance. Following the guidance for each contribution type is also a great way to meet quality standards.
πŸ—οΈ Consider the impact on the system
Contributions to Polaris should apply to multiple admin surfaces. They should not be unique solutions with only one use case. Read Designing with a system, and reach out to the Polaris team for system advice or guidance.
πŸ”¬ Be clear and detailed
Submit a short summary of your contribution, along with relevant links, artifacts, and context. State your expectations, understanding that we must prioritize certain business and system needs. If you can ship in collaboration with another product team, tag them and let the Polaris team know. Capture contribution details with GitHub issue templates.

Where to get help

If you get stuck or want help strategizing a larger contribution, bring it up in GitHub discussions. The Polaris team and other members of the systems community will help you out. If you see a discussion where you could guide another member of the community, we welcome you to join the conversation.