Holistics Design System

Grammar & 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 & Italics ​

  • Use bold sparingly and only where strong emphasis is required. Don’t use italics and quotation marks.
  • User for:
    • Headings & 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 & 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 any UI copy.
  • Use them sparingly and deliberately in promotional or onboarding content.

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

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

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 copies to be more inclusive & readable.

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?”