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 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 the following signs:

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

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 having action done to it) is more important than the subject (person doing the thing)

Contractions

Contractions are abbreviated words, such as "can't", "aren't", and "you're", and help set a light and casual tone. While you should use contractions in most cases, 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.

Capitalization

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, such as blogs, navigation, or pages, then don’t capitalize it. If it’s unique to Shopify and marketable as its own product, such as Shopify Payments or Frenzy, then capitalize it.

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're using the company’s name and logo correctly.

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.

Headings and subheadings

Review the content guidelines for headings and subheadings in the actionable language section.

Lists

Bulleted

Use a bulleted list when items are related but sequence or priority doesn’t matter. Introduce the list with a full sentence and a colon.

Capitalize the first word of the bullet.

If at least one of the bullet points requires a period due to having two sentences, then include punctuation on all the bullets. Avoid lists that have both single words and sentences as bullet points.

Numbered

Use a numbered list when item sequence or priority does matter. Introduce the list with a full sentence and a colon.

If at least one of the numbered bullet points requires a period due to having two sentences, then include punctuation on all the bullets. Avoid lists that have both single words and sentences as bullet points.

Capitalize the first word of the bullet.

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 that they can easily find and accurately select the item that 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. This doesn't apply to procedural steps, which should end with punctuation.
• 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.

Dates, numbers, and measurements

Dates, numbers, and measurements are often formatted automatically according users’ local preferences, and they may be formatted differently in other languages. You can use helpers to ensure they are localized automatically. These guidelines are for manually formatting in American English, which we use as a base before translating to other languages.

Date

When possible, use the month’s full name. If there are space constraints, use 3-letter abbreviations. Don’t write dates with numerals only.

Don’t use ordinal indicators, which are words representing position or rank in a sequential order (1st, 2nd, 3rd, and so on).

Time

For all translations, the time format is automatically localized by the Intl.DateTimeFormat JavaScript object. When time must be formatted manually, follow these guidelines:

• 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.
• 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” instead of a comma.

Time zones

• Include a time zone only if it’s necessary, such as for an event listing.
• Use the time zone’s abbreviation following the am or pm, for example, 4:00 pm NZT.
• If your audience is in a single time zone, then don’t include an S (for Standard) or D (for Daylight). For example, 3:00 pm PT.
• If your audience is in a combination of time zones, then include the S (for Standard) or D (for Daylight) to avoid confusion. For example, 3:00 pm PDT.

Use consistent timestamp formats by following these examples:

Currency

When including currency with a price, the currency comes after the dollar amount. Learn more about formatting localized currency.

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

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

Never pluralize unit of measurement abbreviations.

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

For pricing by measurement, don’t add a space before or after a slash.

For units of measurement, use decimals instead of fractions:

Unit of measurement abbreviations

This table shows the standard abbreviations for commonly-used units of measurement.

Use the imperial system for the United States, Liberia, and Myanmar, and use the metric system for all other countries.

Addresses and places

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

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 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.

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

When it’s helpful to the merchant, use quotation marks to indicate input that the merchant has provided, such as a product title or file name. Use this indication only when the input appears in running text.

In general, place commas and periods inside quotation marks. When working with literal strings like typed commands or merchant inputs, place punctuation outside the 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. Don’t use bold to create a heading or emphasize:

• Proper nouns
• Merchant input
• Checkbox titles

You, we, and other personal pronouns

Addressing merchants

Always refer to merchants as “you.” Don’t speak for merchants 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).