Writing and designing content in a thoughtful way makes your app usable, accessible, and readable.

Your written content’s voice and tone help you talk to merchants in a consistent, recognizable way.

Voice refers to aspects of writing that are consistent across all contexts and audiences. Tone can change based on the audience and their current context.

Learn how to apply Shopify’s voice and choose the right tone, no matter what app you’re building, by referring to the Polaris guidelines on voice and tone.

A mockup of the Puzzlify app with highlighted bits of text.

Voice and tone is important

Expressing your brand through written content shouldn’t contradict Shopify’s voice and tone. This helps maintain a cohesive experience for merchants.

The following are some principles behind writing product content for a quality merchant experience.

Various cards of the Puzzlify app showing different types of content.

Shopify merchants are located all over the world, have varying levels of literacy, and may not speak English as their first language. Content can easily be mistranslated or misinterpreted.

Structure your content in a clear, efficient way.

A card with a clearly visible heading and bulleted list.


Use headings, bullets, and short sentences to make your content more scannable.
A card with text that’s written at a seventh-grade level.


Use clear terms that are easily understood. As a benchmark, aim for a United States grade 7 reading level. You can check reading levels with tools like Hemingway App.
A card that gives the definition of ‘Interjamb’, which is puzzle industry jargon.


Be careful when using industry jargon and technical terms. Only use them if it helps clarify something for the merchant.
A card with a very long paragraph of text.


Avoid large blocks of text, as it’s hard to scan and gather the most important information quickly.
A card with a title that reads ’Beggars can’t be choosers’.


Avoid idioms and phrases with indirect or ironic meanings, as they can be misinterpreted or mistranslated.

To help merchants understand key concepts and actions, use terms in a consistent way.

One way to ensure consistency is to identify and eliminate synonyms for key concepts and actions.

A card with consistent use of the words ‘upload image’.


Use a single noun, verb, or phrase to describe a specific thing, action, or concept.
The words ‘upload images’ and ‘add photos’ used in the same card.


Don’t use multiple synonyms to describe a specific thing, action, or concept.

Merchants use Shopify to get things done for their businesses. Write content that helps merchants understand and take the most important actions.

Two buttons with strong calls to action, ‘Export templates’ and ‘Create template’.


For calls to action (CTAs), start with a strong verb that describes the action. Use active voice to clarify the subject and the action.
A numbered list of three tasks to complete.


Prioritize the most important information and tasks. Break complicated tasks into steps that focus on individual actions.

Guide, don’t prescribe

Write in a way that puts your merchant at the center and in control. Provide merchants with tools and knowledge for making the best decision.

A card that reads ‘Personalized photo puzzles make up 85% of all Puzzlify orders’.


Give merchants enough information to make the right decision on their own.
A warning banner that reads ‘Double your revenue by switching to Puzzlify Pro now’.


Don’t oversell or overpromise. This can break trust with customers.

For spelling, punctuation, and other grammatical considerations, refer to the Polaris guidelines on grammar and mechanics.

A person holding a magnifying glass over screenshots of the Polaris grammar and mechanics page.
An example of Puzzlify having to refer to itself multiple times. The message says ‘Puzzlify detected an issue with your shipment. We’ve contacted our supplier and will send you updates as we receive them.’


In other parts of the Shopify admin, Shopify will use the pronoun “we” to refer to ourselves, if necessary. To avoid confusing merchants, always first refer to your app or company by its proper name. If additional references are required within the same section of content, then you can use “we.”