Grammar and mechanics

Plain language

• Write for all users: Use words and language that our users use. Avoid jargon or technical terminology Aim for a Grade 7 reading level.
• Be clear and concise: Some people will read every word you write. Others will just skim. Create a hierarchy of information. Lead sentences with the main point.

Spelling and formatting

American spelling

Use American spelling for all external-facing content.

Bold and italics

• Use bold sparingly and only where strong emphasis is required. Don’t use italics and quotation marks.
• Use for:
  • Headings and titles
  • Referring to UI elements

✅

• Visit the My Account page to update your avatar.
• Data source demo2 is invalid.

❌

• Visit the “My Account” page to update your avatar.
• Data source “demo2” is invalid.

Abbreviations

Spell out an acronym on first use and include it in parentheses.

• Period-over-period comparison (PoP)
• Two-factor authentication (2FA)

Use the abbreviation or acronym if it’s well-recognized, like SQL or API.

Active and passive voice

Use active voice in most cases and use passive voice sparingly.

• With active voice, sentences are simpler, shorter, clearer, and more conversational.
• With passive voice, you can soften and provide distance in select situations (e.g., notification of a disabled account).

Active voice

Generally, write in the active voice: Subject (person/thing acting) verb (the action) object (receives the action)

✅ Susan commented on your dashboard

❌ Your dashboard was commented on by Susan

Passive voice

In some cases when active voice comes across too harshly, use passive voice:

• Separates the actor from the action to soften a sentence.
• If the object (thing having action done to it) is more important than the subject (person doing the thing)

✅ Your payment has been declined

❌ We declined your payment.

Contraction

Contractions make sentences shorter and easier to read. Use commonly understood contractions to keep sentences from feeling out-of-touch, robotic, or overly formal.

✅

• Can’t run query
• This feature isn’t available for your version
• You’re all set up
• An error occurred and your changes couldn’t be saved

❌

• Cannot run query
• This feature is not available for your version
• You are all set up
• An error occurred and your changes could not be saved

Capitalization

• Use sentence case capitalization in most cases:
  • Capitalize the initial letter of the first word of a sentence, heading, title, or description.
  • Capitalize proper nouns and trademarked nouns. View the Word list
  • Use lowercase for everything else.
• Don’t capitalize the word after a slash or hyphen if the first word isn’t capitalized.
• Don't use all uppercase for emphasis. It hinders readability and may appear rude to users. Use bold instead.
  • Only use all uppercase when asking users to type to confirm. Example: Type DELETE to confirm bulk delete

Emoji

• Don’t use emoji in product UI copy: labels, buttons, alerts, tooltips, and messages.
• Use them sparingly and deliberately in promotional and onboarding content, such as a welcome tour or a release announcement.

Date and time

Date

Use the American English date format. When possible, use the month’s full name. If there are space constraints, use 3-letter abbreviations.

• Wednesday, May 15, 2015
• May 13, 2015
• May 15

Use date with numerals only in cache or refresh status:

• 2015-05-13 14:00:00 GMT+07:00

Time

• When using the 12-hour time, write in numerals, with am or pm, and a space in between.

  ✅ 2:00 pm

  ❌ 2PM

• When using the 24-hour time, always use at least 4 digits:

  ✅ 2015-05-13 08:25:00 +07:00

  ❌ 2015-05-13 8:25 +07:00

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

Numbered

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

Capitalize the first word of the sentence.

Dropdown and select menus

• Actions in a menu: Actions in a menu follow a {verb}+{noun} pattern. If there’s enough context, only a verb might be required.
• Nouns in a menu: 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.

List punctuation

Don’t add a comma or semicolon at the end of a bulleted or numbered list item.

Numbers

• Use the numeral in the UI copy:
  • Deleted 3 fields successfully
  • We found 20 search results
• Use commas for numbers over 3 digits:
  • 123 users
  • 1,234 users
• Use an en dash without a space on either side for number ranges
  • The process might take 1–3 days

Punctuation

Ampersands &

Use “and” instead of “&” in UI copy. It reads more clearly and is easier to translate.

Apostrophes ’

Use apostrophes to represent omitted letters:

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

Use apostrophes to form possessives:

• Singular nouns: add ’s, even if they end in s (dashboard’s, field’s)
• Plural nouns that don’t end in s: add ’s (women’s, men’s)
• Plural nouns that end in s: add an apostrophe (types’, users’)

Asterisks *

Use asterisks ( * ) to indicate form fields as required.

Colons :

• Colons are helpful when introducing lists of items or steps in a workflow.
• Don’t use a colon at the end of a label for a form field.
• 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.

Commas ,

Use the Oxford comma (also known as the serial comma) when writing a list with 3 or more items.

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

Ellipses …

✅ Use ellipses for:

• Truncation
• Communicate in-progress status: “Loading…”
• Placeholder copy: “Input field name…”

❌ Don’t use ellipses for:

• Trailing off a sentence: “Welcome to Holistics…”

Exclamation marks !

• Don’t use exclamation marks. They can come across as too excited and easily overused.

Hyphens -

Use hyphens without spaces before and after to link words into a single phrase.

Form compound modifiers: 2 words combining to modify or describe the following noun.

Periods .

• Use periods in full-sentence description:
  • Modal’s description with more than 1 sentence
  • A list item with more than 1 sentence
• Don’t use periods in UI elements’ copy, such as:
  • Button
  • Inline link
  • Notification
  • Alert, Banner
  • Headings, Titles
  • Tooltip
  • Placeholder
  • Radio button, checkbox
  • A list item with only 1 sentence

Question marks ?

✅ Use question marks if you don’t know the result of the question:

• Can’t access your authenticator app?
• Do you want to proceed?

❌ Don’t use question marks if:

• It’s the only option available: “Reset password?”
• It’s an on/off option: “Enforce Two-factor Authentication?”