Grammar and mechanics

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 merchants need 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 (“the item was purchased by the customer”)
• Past tense verbs (“was added”, “was created”, and so on)
• Forms of the verb “to be” (“was”, “is”, “were”, and so on)

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.

Headings

Use sentence case for all headings:

• Capitalize the first word of a heading
• Capitalize proper or trademarked nouns (names of products, countries, or 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 (such as blogs, navigation, pages). If it’s unique to Shopify and marketable as its own product, capitalize it (such as Shopify Payments, or 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. When referring to a job title without referencing a name, don’t capitalize the job title.

Letters following slashes

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

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 readability and encourages 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 (names of products, countries, or people)
• Lowercase for everything else

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, such as step-by-step instructions.

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.

These guidelines are for American English, which is the language we use as a base before translating to other languages. However, dates, numbers, and addresses may be formatted differently in other languages. You can use helpers to ensure they are localized automatically.

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 (1st, 2nd, 3rd, and so on).

Time:

• Use the 12-hour clock, followed by am or pm.
• Include a space after the last number, for example, “Your package will arrive at 12:35 pm”. Adding the space helps with formatting for English-speaking markets outside of North America, so we use it for North American usage as well.
• 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:00 pm NZDT.
• To show a time range, use an en dash and include the am/pm after both times, for example, 3:00 pm–4:00 pm.
• If indicating both the date and time, separate them with the word “at”, rather than with a comma.

For all other languages, the time format will be automatically localized by the Intl.DateTimeFormat within JS.

Use consistent timestamp formats by following these examples:

Currency

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

Numbers

In general, use numerals. If the number is below 10 and not integral to the sentence, spell it out in full.

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” or “or more”.

For downward ranges, be specific.

Units of measurement

For storage and memory sizes, 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.

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), use the abbreviated form without punctuation.

Things to watch out for:

• Don’t use colloquial forms of a nation or state name, for example, America instead of the United States
• Search online to see whether nations commonly use “the” before their name, for example, the Philippines or 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.

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 such as hers or his.

Always use apostrophes, not vertical (straight) quotes.

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 of 3 or more items (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

Always use the ellipsis character, not three periods.

Truncation

Consider constraints of the space in the interface when deciding to use truncation. Think about what part of the string merchants 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.

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 merchants have provided (such as a product title or contact information).

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

Addressing merchants

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

In some cases (such as getting merchant consent or granting permissions) you should refer to merchants 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).