Community
December 18, 2021

Lessons From Polaris  -  Our First Embedded Shopify App

This is part five in a series of articles documenting the process of building our first Shopify app. Click here for part four.

What is Polaris?

For those unfamiliar, Polaris is the name of the guidelines, values and framework Shopify provide to app/theme developers. It isn’t a set of requirements, but they are extremely well thought-out guidelines and recommendations to follow when designing a customer experience.

At Shopside, we want our apps to feel part of the Shopify experience, and Polaris was instrumental in helping us achieve this.

Their values include being:

  • Considerate: Show care for your customers, make their lives easier
  • Empowering: Give customers confidence to achieve their goals, no matter their experience level
  • Crafted: Through thoughtful details and small touches, make your customers experience feel well-designed and professionally crafted
  • Efficient: Help customers achieve their goals quickly, accurately and with minimal effort
  • Trustworthy: Be genuine and transparent to show customers you’re always acting in their best interest
  • Familiar: Make customers feel comfortable using your tools, and ensure they act the same way and fit together seamlessly

These values closely align with our own, and after reading through the wealth of information the Polaris guidelines offer, we found some interesting recommendations that we hadn’t even considered. More on that in a bit.

Embedded App Design using Polaris Components

There are two major benefits to using Polaris components within your embedded app.

  1. Your app feels like a part of the Shopify admin experience.
  2. You have a huge library of pre-built components to use, saving you time.

We aimed to use Polaris components for our entire app if we could, only using custom UI elements where absolutely necessary. The result is a seamless and familiar experience for merchants, so they can focus on using our app, instead of trying to figure out how.

Check out the full list of components and options to get started.

Beyond the UI — Changes We Made Retroactively

We were well on our way to finishing our Bloom date picker app, when we reviewed our content and user experience and found some areas we could improve to align closer to the Polaris guidelines.

For the record, we didn’t make these changes begrudgingly because we felt like we had to; we made them because they seemed like good ideas to us as well and helped us create a more consistent and integrated experience for store owners.

The content guidelines for Polaris are thorough, and include recommendations around voice and tone, accessible/inclusive language, grammar, naming, help documentation, app release notes, vocabulary and more.

Here are a few examples of changes we made to our app to keep in line with these suggestions:

Accessible Content and Language

This was an interesting example of a change we decided to make, which we hadn’t considered before. As part of Shopify’s “accessible content”, they point out that your language and messaging should not be ableist, racist or sexist, and there are some commonly used terms and phrases that fall under these categories.

  • Instead of using the words “enabled” or “disabled”, we have changed our language to say “activated” and “deactivated”.
  • Instead of having a “whitelist”, we have a “VIP list”.
  • Instead of using gendered language, we use “your” or “they/them/theirs”.

There are many other examples Polaris outlines. We recommend reading through them and considering making changes accordingly.

Grammar and Naming

This change probably took the longest, and involved us reviewing each label and piece of messaging in our app to try to stick to these guidelines and create a uniform experience. This involved things like:

  • Using the “active voice”, instead of the “passive” voice, e.g. “Add details to the product” instead of “Details were added to the product”.
  • Using contractions to set a light and casual tone, e.g. “You can’t have products with negative weights”.
  • Consistent capitalisation (only capitalising the first word of a heading or a proper/trademarked noun), e.g. “Create purchase order” instead of “Create Purchase Order”.

There are a lot of recommendations Polaris makes in this section, so it’s worth exploring yourself to see how you can apply these to your own apps.

Hopefully these examples are enough to give you an idea of the sorts of changes we made, though it’s not a complete list.

Looking Forward

This is by no means a finished process for us. We are constantly working on improving our app experience and will continue to implement Polaris as much as we can for any future apps.

We would love to hear any examples of how you’ve used Polaris in your own apps, or if you’ve chosen not to, why you made that decision.

We’re close to wrapping up development on our first app, so look forward to the release of Bloom very soon!

Part six of this series is now available, introducing the final product of our efforts, our finished app Bloom!

Recent Articles