Writing guidelines

Use these guidelines as a source of truth, for best practices and patterns when writing messages.

Humans care about how products talk to them. Whether you look at giants like Google and Apple, or upstarts like Trello, GitHub, and Slack, these products all have a distinct voice, tone and personality. They engage us, manage to make us feel at home, capture our attention, and earn our loyalty.

Poor messaging contributes to a poor user experience, which in turn leads to frustration, dissatisfaction, and abandonment. On the other hand, good copy reflects our products' voice (personality), and enables us to build a relationship with our audience.

In short, good messaging may not be a reason people stay in our products, but bad messaging could be a reason they decide to leave.

What can you do

Use the guidelines and table below to inform your copywriting, calibrate your tone, and maintain consistency in your content. The following guidelines have information on specific message types:

  • Error messages

  • Success messages

  • Info messages

  • Warning messages

  • Feature discovery

The table below will help you pick out what component to use to express a certain message. For example, if you want to show off a new feature to a user, investigate patterns and recommendations for spotlights, benefits modals, and empty states. Or if you want to tell someone they've accomplished a task successfully, check out the patterns and recommendations for flag messages.

MessageInfoLoadingSuccessWarningErrorFeature discovery
Empty stateYesYesYes
BannerYesYesYes
FlagYesYesYesYesYes
Section messagesYesYesYes
Inline messagesYesYesYesYesYes
ModalYesYes
Benefits modalYes
SpotlightYes

Was this page helpful?
We use this feedback to improve our documentation.