PolarisContributing 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 system | Extend the system | Build a custom solution | ||
|---|---|---|---|---|
| When available resources can solve a design problem | When a change or addition can solve a shared problem | When 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 contributions | Submitting 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.