Grammar and mechanics

Basics

Active voice

You should (almost) always write in the active voice:

• Subject (person/thing acting) verb (the action) object (receives the action)

Use the active voice if the merchant needs to do something. It should be clear that the subject is the one doing the action.

Passive voice

To tell if you’re using the passive voice, look out for:

• When the object comes before the subject (e.g. the item was purchased by the customer)
• Past tense verbs (e.g. “was” added, “was” created, etc.)
• Forms of the verb “to be” (e.g. was, is, were, etc.)

You should almost always write in the active voice, but here’s when to use the passive voice:

• To avoid referring to yourself or Shopify
• To make it clear that you didn’t personally take an action or make a decision
• If the object (thing being done) is more important than the subject (person doing the thing)

Contractions

Contractions are abbreviated words. We use them to set a light and casual tone in the interface. The goal is to sound human, so avoid contracting verbs that sound awkward when you say them out loud, or have been phased out of modern day speech.

Plain language

Use words and language that our merchants use. Avoid jargon or technical terminology. Make sure each sentence has a single focus and keep them short. Aim for a Grade 7 reading level.

Buttons, links, and other actions

Buttons and links need to be clear and predictable. People should be able to anticipate what will happen when they select a button or link. Never deceive someone by mislabeling a button or link.

Buttons

Clear and predictable: merchants should be able to anticipate what will happen when they click a button. Never deceive a merchant by mislabeling a button.

Action-led

Buttons should always lead with a strong verb that encourages action. To provide enough context to merchants use the {verb}+{noun} format on buttons except in the case of common actions like Save, Close, Cancel, or OK.

Scannable

Avoid unnecessary words and articles such as the, an, or a.

Links

Always use descriptive link text for links. Link text needs to describe where users will go or what they’ll see when they select a link. It’s important to give context so people know where a link will take them.

Never use “click here” or “here” as link text.

Actionable language

Start sentences with imperative verbs when telling a merchant what actions are available to them (especially something new). Don’t use permissive language like “you can”.

Select vs. choose

Use the verb “select”:

• When telling merchants to pick something from a limited number of options of the same kind
• When merchants need to make an easy or obvious decision that doesn’t require deep reflection or analysis
• For defined lists and dropdown menus

Use the verb “choose” when:

• Encouraging merchants to make a decision that is more subjective, strategic, emotional, or open-ended
• Merchants have to pick from a large inventory of items, like themes, or options that require strategic decision making, like pricing plans

Create vs. add

Use the verb “create” when you’re encouraging the merchant to generate something from scratch, like a collection.

Use the verb “add” when you’re encouraging the merchant to bring something that already exists into Shopify, like a product.

View vs. see

Use the verb “view” when you’re encouraging the merchant to go to a specific page or section for more details, or to reveal more information. Use “view” in buttons, calls to action, and link text.

Use the verb “see” in more general, conversational descriptions without a specific call to action.

Need vs. must

Use the verb “need” when you’re telling the merchant something they’re required to do or should do.

Export vs. download

Use “export” as the call to action when a merchant needs to transfer data from Shopify and convert it into a different format.

Use “download” as the call to action when merchants need to copy data (of the same format) from Shopify to a computer system.

Import vs. upload

Use “import” as the call to action when a merchant needs to transfer data and convert it into a different format so it can be used in Shopify.

Use “upload” as the call to action when merchants need to copy data of the same format from a computer system into Shopify.

Capitalization

Headings

Use sentence case for all headings:

• Capitalize the first word of a heading
• Capitalize proper or trademarked nouns (e.g. names of products, countries, people)
• Lowercase for everything else

Product and feature names

In general, if a feature or product isn’t unique to Shopify, don’t capitalize it (e.g. blogs, navigation, pages). If it’s unique to Shopify and marketable as its own product, capitalize it (e.g. Shopify Payments, Frenzy).

For all terms and definitions, check our full vocabulary list.

Job titles

Job titles should be capitalized when they come before or after a person’s name (e.g. Content Strategist Jane Smith or Jane Smith, Content Strategist). When referring to a job title without referencing a name, don’t capitalize the job title (e.g. Jane Smith is a content strategist at Shopify.)

Letters following slashes

The first letter following a slash shouldn’t be capitalized.

Headings and subheadings

Basic structure

Group related ideas together using descriptive headings and subheadings. Keep headings concise and easy to scan.

Articles in headings and subheadings

The use of articles (the, a, an) in headings depends on whether the message is conversational or action-based microcopy.

Conversational headings and subheadings

In more conversational sections of the interface, like Home cards, sell pages, and empty states, use articles. It makes the language more approachable and helps understanding when introducing new, complex concepts.

Microcopy headings and subheadings

In labels and microcopy, be concise and don’t use articles. It increases scannability and encourage immediate action.

Punctuation in headings and subheadings

• Don’t use periods at the end of headings
• Commas (,), colons (:), and semicolons (;) are ok but not encouraged

Capitalization in headings and subheadings

Use sentence case (first word capitalized, the rest lowercase) for all headings:

• Capitalize the first word of a heading
• Capitalize proper nouns (e.g. names of products, countries, people)
• Lowercase for everything else

Lists

Bulleted

Use a bulleted list when items are related but sequence or priority doesn’t matter.

Numbered

Use a numbered list when item sequence or priority does matter (procedures, etc.).

Dropdown menus

Actions in a menu

Menu lists give users a horizontal set of actions when space is limited. The order of actions is often based on logic such as most popular actions.

Actions in a menu follow a {verb}+{noun} pattern. If there’s enough context, only a verb might be required.

Nouns in a menu

Menu lists give users a horizontal set of nouns when space is limited. The order of nouns is often based on logic such as most recent orders.

Nouns in a menu should be concise but still give the user enough information so they can easily find and accurately select the item they want.

Capitalization

• List items always start with a capital letter.
• Capitalization and punctuation rules apply to both bulleted and numbered lists.

Punctuation

• Introduce bulleted lists with a colon or a heading.
• Don’t use commas at the end of list items (for bulleted or numbered lists).
• If any list item contains two or more sentences, punctuate all list items.
• If all list items are one sentence or fragments, don’t punctuate.
• Never put a comma or semicolon at the end of a bulleted or numbered list item. Treat each list item as a self-contained piece of information.

Helper text and descriptions

If your list contains helper text, only the description below the list item should contain punctuation.

Dates, numbers, and addresses

Date

When possible, use the month’s full name, for example, October. If there are space constraints, use 3-letter abbreviations, for example, Oct. Don’t write dates numerically, for example, 07-02-14.

Don’t use ordinal indicators, which are words representing position or rank in a sequential order (e.g. 1st, 2nd, 3rd, 4th).

Time:

• Use the 12-hour clock, followed by am or pm
• Don’t put a space after the last number, for example, “Your package will arrive at 12:35pm”
• Use the browser time of the logged in user
• If indicating a time zone is necessary, use the time zone’s abbreviation and write it after am or pm, for example, 4:00pm NZDT
• To show a time range, use an en dash and include the am/pm after both times, for example, 3:00pm–4:00pm

Use consistent timestamp formats by following these examples:

Currency

When including currency with a price, the currency comes after the dollar amount.

Numbers

Use numerals in Shopify:

Use commas for numbers with four or more digits. Whenever possible, don’t truncate numbers:

Use hyphens when writing phone numbers. Don’t use brackets, spaces, periods, or plus signs:

Use an en dash without a space on either side for number ranges:

Use “to” instead of an en dash if a number range is preceded by “from” in a phrase. Use “and” if a range is preceded by “between”.

For undefined upward ranges, use “and up”.

For downward ranges, be specific.

Units of measurement

For storage and memory sizes (e.g. kB, GB), the unit of measurement should be uppercase. Include a space between the number and unit of measurement.

For dimensions and weights, the unit of measurement should be lowercase. Include a space between the number and unit of measurement.

For dimensions and weights, use decimals instead of fractions:

When listing out dimensions in a row, put the unit of measurement at the end instead of after each number and include a space.

In all cases, include a space between the number and the unit.

Address

Lay out address forms in the following format:

First name             Last name
Address
Apartment, suite, etc. (optional)
City
Country            Province           Postal code

Please note, “optional” in Apartment, suite, etc. (optional) means that the field is optional for customers to complete, but we should always include it in the form.

Places, names, and formal nouns

Country, province, and state names

Use a nation’s proper name when referring to it as a noun.

When using a country as an adjective (such as when referring to currency), you may use an abbreviated form without punctuation.

Things to watch out for:

• Don’t use colloquial forms of a nation or state name (e.g. Your store must be located in America)
• Look up online if nations commonly use “the” before their name (e.g. in the United States, in France, in Ukraine, in the Falkland Islands)

Trademarks

Respect the usage guidelines of any third-party intellectual property. For example, in US communications, Apple Pay requires you to include the trademark symbol (™) the first time Apple Pay appears in body copy.

Review the third party’s brand usage guidelines to make sure you are using the company’s name and logo correctly.

Punctuation

Ampersands

Don’t use ampersands (&). They attract attention to the least important part of the sentence. Spell out the word “and”.

Apostrophes

Use apostrophes to represent omitted letters or numbers:

• Omitted numbers (’40s)
• Omitted letters (don’t, can’t, won’t)
• Verb contractions (it’s, you’re, we’re)

Use apostrophes to form possessives:

• Singular nouns: add ’s, even if they end in s (merchant’s, bus’s)
• Plural nouns that don’t end in s: add ’s (women’s, men’s)
• Plural nouns that end in s: add an apostrophe (boxes’, customers’)

Don’t use apostrophes to form possessive pronouns (hers, his, etc.).

Colons

Avoid using colons in sentences. If you need to use one, don’t capitalize the first word after the colon unless it’s a proper noun.

Don’t use colons to introduce radio buttons or checkboxes.

Introduce bulleted lists with a colon.

Commas

Use the oxford comma (also known as the serial comma) in sentences. There should be a comma after every list item (unless you’re using a bulleted or numbered list).

Don’t use commas to separate bulleted or numbered list items.

Ellipses

The ellipses (…) can be used in place of a missing piece of text (most commonly to show the deletion of words from a direct quotation). Avoid using ellipses in text.

Use ellipses for:

• Truncation in the center of a title bar

Don’t use ellipses for:

• Placeholder copy
• Trailing off a sentence

Truncation

Consider constraints of the space in the interface when deciding to use truncation. Think about what part of the string the merchant needs most. It’s usually the beginning or end, which means you might have to truncate the middle of the string.

Ellipses button component

A button with an ellipsis icon (not the same as text) is used to expand more actions. It’s typically used in cards, or for horizontal sets of actions when space is limited. Android uses a vertical version (vertically stacked dots).

En-dashes and em-dashes

Use an en dash with no spaces in between (–) for a fixed range of numbers

Use an em dash only if you can’t make your message clearer by splitting it into two sentences. Use an em dash without a space on either side (—).

Depending on the font or appearance, you may want to include a hair space on either side of the en or em dash. HTML entity code for hair space is   or  .

Tip: On Mac the keyboard shortcuts are option - for en dash and shift option - for em dash.

Exclamation marks

Avoid exclamation marks—only use them for really really exciting things. If you absolutely have to, limit yourself to one exclamation mark per page.

Hyphens

Use hyphens to:

• Form compound modifiers: two words that combine to modify or describe the noun that follows

• Join prefixes and suffixes only if there are two vowels beside each other. Never use hyphens in the words ecommerce and email.

Periods

Periods often end up in places they shouldn’t, and are omitted at strange times. In general, don’t use periods in interface copy unless it’s a full sentence description.

When to use periods:

Periods for bulleted, numbered, and lists of links

Question marks

Avoid question marks wherever possible. Reword into affirmative statements wherever you can, but there are exceptions:

It’s okay to use question marks if you don’t know the result of the question:

• “Did you forget your password?”
• “Do you need to add a shipping rate?”

Don’t use question marks if:

• It’s the only option available: “Reset password”
• It’s an on/off option: “Show quantity box”

Quotation marks

Use quotation marks to:

• Define words (“growth-hacking”)
• Quote text

Place commas and periods inside quotation marks.

Always use smart (curly) quotes, not vertical (straight) quotes.

Semicolons

Avoid semicolons if possible. If you really need them, use semicolons to:

• Connect two closely related ideas, as long as they are both independent clauses (full sentences that could stand on their own).
• Replace a comma or the word “and” between two closely related ideas.

Spelling and formatting

American spelling

Use American spelling for all external-facing Shopify content. When in doubt, check the Merriam-Webster dictionary for the preferred spelling of specific terms.

Tip: it’s easy to miss Canadian spelling. Switch your laptop language settings to American English and turn spell check on. It will highlight any Canadianisms you might have missed.

Bold

When in doubt, don’t bold.

Use bold sparingly and only where strong emphasis is required. In the interface, bold should be reserved to emphasize input a merchant has provided (e.g. product title, contact information).

Don’t use bold to emphasize proper nouns, create a heading, or emphasize a checkbox title.

You, we, and other personal pronouns

Addressing merchants

Always refer to the merchant as “you”. Don’t put words in the merchants’ mouths with phrases that use “I” or “my”.

In some cases (such as getting merchant consent or granting permissions) you should refer to the merchant as “I”.

Referring to Shopify

Always refer to Shopify as “we,” but avoid inserting Shopify into the content as much as possible (except when a human is taking action, such as reviewing a request.)