Paste

Design System

Product style guide

Core principles, punctuation, grammar and formatting in Product content.


Content principles#

Identify your user and speak directly to them#

  • Consider who you're writing for and their technical level. Use words the user is familiar with.
  • Address the user as you, refer to Twilio as we.

Write for the reading level of a 10-13 year old#

  • Use simple, short sentences and common words.
  • Explain technical terms and write acronyms in full the first time a user sees them.

Using readability tools

Sites offering free readability tools like this one can be useful for assessing the "reading age" of long content (more than 150 words). However, they're not great at testing short UI content that might only contain two or three words. Use them with caution. Look for a simpler word whenever you can to improve the readability of your content.

Be inclusive of people and devices#

  • Avoid click, tap, touch instructions as not every device supports touch.
  • Instead, use select to instruct a user to interact.
  • Avoid relying on directional or color-based cues to the right, the blue button. These are problematic for responsive products or users who see colors differently.
  • Instead, write the main menu or the dropdown menu. Name the component or area you’re referencing.

Write as if the user is in a rush#

  • Avoid repetition and padding.
  • Phrases we use when writing formally or presenting please note, so, in fact, in other words should be cut.
  • Chunk content and use headings to help the user scan for what they need.

Be direct and straightforward#

  • Lead with the reason (why), by front-loading messages with words that address the user’s needs.
  • Leave the user with a clear instruction of how to address that need.
  • Avoid relying on company/industry jargon, idioms, or cultural references to communicate what you mean.
  • Use the words that are most familiar to the user.

It’s ok to bend grammatical rules to sound natural#

  • End sentences with prepositions of, with, for if it sounds less awkward.
  • And you can start sentences with But or And.
  • Use contractions with pronouns it’s, there’s, you’ll, we’ll, you’re to sound conversational.

Exception: avoid contractions in error messages

Avoid contractions in negative scenarios. When a user is stressed, their comprehension suffers. Often users will read can’t as can, missing the -’t at the end. Write out error messages or destructive action warnings in full.

Punctuation#

Ampersands &#

Avoid using ampersands. In exceptional circumstances, if space is unavoidably restricted or it's part of a product/brand name, use "&".

Do use "and" instead of an ampersand (&).

  • Voice and messaging
  • Create and submit a Regulatory Bundle.
  • Messages sent from AT&T to Twilio numbers are not impacted.

Don't use "&" just to make content shorter. IF space is an issue, address the content and design together.

Why?

Using "and" rather than the ampersand symbol (&) supports localization and users with lower literacy or cognitive impairments. Some screen readers can’t interpret the code behind an ampersand, which obscures the meaning for the user.

Apostrophes '#

Do use an apostrophe to indicate possession or belonging.

  • The APIs of Twilio > Twilio's APIs
    • The phone number's prefix.
    • Choose from one of SendGrid's responsive email designs.

Do use an apostrophe to indicate missing letters.

  • You are > you're
    • You're not logged in.

Don't use apostrophes to make a plural. We should never see Upgrade to buy phone number's, Install plugin's, or SID's.

Commas ,#

Do use the serial or 'Oxford' comma in a list of 3 or more items.

  • You can customize the agent desktop, channels, interaction routing, and reporting.

Exclamation marks !#

Do use a single exclamation mark to support a celebration. But never more than one at a time (!!)

  • Congratulations, you sent your first email!

Don't use exclamation marks to draw attention to or emphasise an error message or alert. Exclamation marks can increase anxiety or sound like shouting. Unless it's a clear moment of success, don't use them.

Hyphens and dashes -

Do use hyphens (-) to create compound words.

  • Hyphens never have a space either side.
    • Add-on feature

Do use en-dashes () indicate a range of values (time, dates, numerical amounts.)

  • En-dashes never have a space either side.
    • 0-50 agents
    • Tip: If your system does not support en-dashes, use a hyphen to indicate range.

Avoid using em-dashes () to create an emphatic pause.

  • Tip: It's ok to write a very short sentence to emphasise its meaning. We might use em-dashes with friends and colleagues in email and chat to signify an added thought, but the user needs clarity over what's important. Give the thought a sentence or restructure your syntax.

Parentheses ( )#

Do use parentheses to provide an example or explanation.

  • Password must contain a special character (&, @, %, $, ^)

Do use parentheses to note an acronym the first time a user encounters it.

  • Transport Layer Security (TLS) is a mechanism for securing your SIP connections.
    • In this example, the user is familiar with the term "SIP" but not "TLS."

Periods .#

Do end every full sentence with a period

  • Enable Flex Dialpad in Console.
  • Sign up for a free account.

Don't use periods at the end of fragments or incomplete sentences.

Quotation marks " "#

Do use quotation marks to pick out words from a component or a file name.

  • Select "Apply changes"
  • We recommend using dedicated accounts for your development environments, like "Flex Production" and "Flex Development."

Do put punctuation inside quotation marks, if necessary.

  • To create a new project, select "Create My Flex Project."

Don't use quotation marks to refer to products or features. Products and features are proper nouns and should be capitalized to differentiate them.

Semicolons ;#

Avoid using semicolons. In formal writing, semicolons are useful. In product content, they can be messy and confusing.

  • If you feel your sentence needs a semicolon, simplify it or create two sentences.

Do use punctuation and conjunctions (and, but, so) to separate thoughts.

  • List complex items that already contain a comma using bullet points. For example, state capitals
    • Montgomery, Alabama
    • Juneau, Alaska
    • Phoenix, Arizona

Grammar and formatting#

Abbreviations#

Coming in the next release

Acronyms#

Do write the phrase in full, followed by the acronym in parentheses the first time a user encounters it.

  • Transport Layer Security (TLS) is a mechanism for securing your SIP connections.
    • In this example, the user is familiar with the term "SIP" but not "TLS."

American English#

Do use American English spellings throughout products.

  • Behavior, dialed, color, artifact, center, license (for both verb and noun), -ize endings, program (for all meanings)

Bold and italics#

Coming in the next release

Capitalization#

Do capitalize proper nouns – products, people, places.

  • If a brand or product name uses a mix of upper and lower case (TwiML, eBay) use the name's convention.
  • Products include features, programs, or systems that Twilio has given a specific name to.
  • People are named individuals or identifiable roles.
    • Kris Brunner, Chief Engineer
    • Contact your System Administrator

Don't capitalize general terms (email, contact center, platform)

  • Tip: If it's something Twilio has created or owns, it takes a capital.

Code snippets#

Coming in the next release

Dates#

Coming in the next release

I/You/We/Us#

Do refer to the user as you and to Twilio as we.

  • Tip: If the user has agency or ownership, use ‘I’ or ‘my’.
    • If you still can’t connect, contact our support team.
    • I understand. (This usage is almost exclusively for consent.)
    • To access billing information, select My Account.

Lists (all)#

Do start each list item with the same part of speech – usually a noun or verb – to make the list "parallel."

  • Punctuate the end of each item with a period if it is a complete sentence.
  • Be consistent within the list. If one item takes a full point, all items should.

Don't punctuate the end of an item in a vertical list with a comma or elipsis "..."

Lists (bullet points)#

  • Do use bulleted lists for items linked by a topic. Make the list topic clear in the sentence or heading that precedes it.

Lists (numbered)#

  • Do use numbered lists for items to be done or understood in a sequence.
  • Avoid listing more than 7 items.

Lists (sentence)#

Do use a sentence list if you’re explaining a short process, noting up to four options, or highlighting up to four key points. You just read a sentence list.

  • Sentence lists should be used for no more than four items. Over four? List with bullet points.
  • Use the Oxford comma before the last item in a sentence list.

Numbers#

Coming in the next release

Sentence case#

Do use sentence case everywhere unless specifically guided otherwise. Sentence case makes content feel more human and it's generally easier to scan.

  • This is sentence case. (Use this.)
  • This is Title Case. (Rarely use this, and only if directed.)
  • THIS IS ALL CAPS. (Don’t use this.)

Time#

Coming in the next release

  • Static time
  • Time span
  • Ongoing time

Common errors#

e.g./i.e.#

  • e.g. = for example
    • Create a memorable name for your Flex Project, e.g. "Flex Training 2020."
  • i.e. = that is
    • Tip: i.e. usually precedes a simpler way of saying something. Say it simply the first time. Avoid writing i.e. if you can.

Every day/everyday#

  • Every day = each day
    • Twilio supports thousands of customers every day.
  • Everyday = ordinary/usual
    • Twilio supports everyday customer needs, like call routing.

It's/its#

  • It's = contraction of "it"+"is"
    • It's now possible to view real-time queue stats.
    • Tip: Can you say it is instead of the word you want? Does the sentence make sense? You want it's.
  • Its = possessive pronoun (belonging to it)
    • The company and its customers.

Log in/login#

  • Log in = verb
    • To access your account, please log in.
  • Login = noun
    • Enter your login details.

Set up/setup#

  • Set up = verb
    • Set up your profile.
  • Setup = noun/adjective
    • System setup information can be found in the user guide.

Sign up/sign-up#

  • Sign up = verb
    • Sign up for a free account.
  • Sign-up = noun/adjective
    • Visit the sign-up page for more information.

Their/there/they're#

  • Their = plural possessive pronoun (belonging to them)
    • The main priority for agents is reducing their wrap-up time.
  • There = adverb meaning existing in/at that place
    • There is a new version available.
  • They're = contraction of "they"+"are"
    • Users are important. They're our top priority.

Who/that#

  • Who = refers to people
    • Team leads who manage multiple business areas can use queues to assign tasks.
  • That = refers to things
    • Companies that require security should enable Secure Media.

Support

If you need support, please open a new issue in our GitHub repository. Please try to provide as much detail as possible in your issue.

Contributing

The Paste design system is open source and contributions are welcome. Check out the project on GitHub to learn more about contributing.

Copyright © 2020 Twilio, Inc.