Documenting in Polaris
Shopify teams create documentation for polaris.shopify.com, but open source contributors are welcome to make copy edits as well as update or add examples to component documentation.
To write effectively as a Shopify employee, use a cross-discipline lens. Make sure your content meets both UX and development needs. Before starting, check out our style guide to the style guide.
Most documentation about the design system is meant for polaris.shopify.com. However, there may be a reason for the content to live elsewhere. If you’re not sure if something should live on this site, the Polaris team can help you figure that out.
Making copy edits
Edits related to spelling, grammar, punctuation, or other typos should happen quickly and often. Both Shopify employees and open source contributors are welcome to submit copy edits.
Note: If you find copy issues in other Polaris resources, follow the steps for that resource’s contribution guidelines.
To expand or edit existing documentation:
- Draft your proposed changes in Google Docs for easy collaboration. We recommend writing in Markdown, or converting your file to Markdown when finished.
- Get feedback from subject matter experts or someone with high context around your changes, like a team member or your lead.
- Reach out to the Polaris team to review your changes for style guide alignment.
- Open a pull request in the Shopify/polaris repo GitHub repo.
Adding new documentation
New documentation in Polaris can range from component documentation, to content guidelines, to pattern guidance.
To create new documentation:
Reach out to the Polaris team. We can help find a home for your documentation, offer templates, provide asynchronous feedback, and—if you're really stuck—participate in pair writing sessions.
Draft the content in Google docs for easy collaboration. We recommend writing in Markdown, or converting your file to Markdown when finished.
Get feedback from subject matter experts, or someone with high context around your changes (team member, manager, etc.).
It’s important that inaccurate or outdated information be removed as soon as possible. This helps maintain high trust in Polaris as a source of truth for design system guidance.
To remove documentation: