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.

To fix any copy issues on polaris.shopify.com, open a pull request in the Shopify/polaris GitHub repo.

Note: If you find copy issues in other Polaris resources, follow the steps for that resource’s contribution guidelines.

Updating documentation

To expand or edit existing documentation:

1. Draft your proposed changes in Google Docs for easy collaboration. We recommend writing in Markdown, or converting your file to Markdown when finished.
2. Get feedback from subject matter experts or someone with high context around your changes, like a team member or your lead.
3. Reach out to the Polaris team to review your changes for style guide alignment.
4. Open a pull request in the Shopify/polaris GitHub repo.

Adding new documentation

New documentation in Polaris can range from component documentation, to content guidelines, to pattern guidance.

To create new documentation:

1. 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.

2. Draft the content in Google docs for easy collaboration. We recommend writing in Markdown, or converting your file to Markdown when finished.

3. Get feedback from subject matter experts, or someone with high context around your changes (team member, manager, etc.).

4. Open a pull request in the Shopify/polaris GitHub repo.

Removing documentation

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:

1. Reach out to subject matter experts, or someone with high context around the existing content, to confirm its relevance and accuracy
2. Open a pull request in the Shopify/polaris GitHub repo