Ecommerce platform. Writing rules for apps that run inside the Shopify admin
Shopify’s content guidelines for apps, annotated
Shopify’s writing rules for apps in its admin turn plain language into a reading level and a limit on exclamation marks. Its best rules, quoted with notes.
The Shopify content guidelines tell developers how to write text in apps that run inside the Shopify admin. They were part of Polaris, the Shopify design system. The old Polaris addresses now redirect, and the content pages are in the Shopify app design guidelines. Every page also has a Markdown copy. The rules turn vague goals into things that you can count.
Best parts, quoted with notes
Voice and tone
Use business casual language. Be plain-spoken, not pretentious or overly playful.
Has: where it applies. Each voice trait is paired with the ways it goes too far, here and in the heading.
Voice and tone
In reality you never know a merchant’s emotional state. Even when things seem the most positive, you can’t be sure.
Has: reason. Explains why tone follows the situation, not guessed feelings, then covers eight situations.
Voice and tone
Assume merchants are excited or celebrating. They might be annoyed if the process was long or the benefits aren’t clear, such as “Congrats! You set up your single login for Shopify.”
Has: right and wrong, reason. A do not, with the wrong sentence written out and the reason that it does not work.
Words and style
Avoid words that generalize success, such as “every,” “all,” and “most.”
Has: exact value. Names the words to avoid instead of describing a quality.
Words and style
Use clear terms that are easily understood. As a benchmark, aim for a United States grade 7 reading level.
Has: exact value. Turns 'plain language' into a reading level someone can measure.
Words and style
Don’t use ampersands. They attract attention to the least important part of the sentence. Spell out the word “and.”
Has: exact value, reason, right and wrong. Rule, reason and fix in three sentences, then 'Zones and rates' against 'Zones & rates'.
Words and style
Avoid exclamation marks. Use them only for genuinely exciting things, and limit yourself to one exclamation mark per page.
Has: exact value, right and wrong. Sets a limit that you can count, one per page, with a do and a do not.
Words and style
Avoid links where you can. Links add clutter and make your app feel less like software and more like an old-fashioned webpage.
Has: reason. Gives the reason before the rules, including never using 'click here' as link text.
What it leaves out
- No logo, color, or typography rules here. The pages cover only how app text reads. Source
- No positioning statement. The nearest is one line under the Shopify voice about a company 'built by real people'. Source
What to take from it
- Turn “plain language” into a measure, for example a reading grade level.
- Set limits that you can count. “One exclamation mark per page” is a rule, but “use sparingly” is not.
- Write the tone for situations, and not for feelings that you guess.