Writing

Components

Last updated: October 2021

Some of our design components have specific writing guidelines. These guidelines help to make the content more consistent and repeatable.


Alerts

Copy elements: title, body, action(s)

Decision alert

  • Title: Format as a question. Avoid “Are you sure?” When possible, reiterate the user’s prior action in the format of “[Verb] [object]?”
  • Body: Provide quick context or key details
  • Actions: Primary action: “Yes, [verb from title]". Secondary action: “Never mind”

Informational alert

  • Title: Format as a statement
  • Body: Provide quick context or key details
  • Action(s): Primary/Single action: “OK”, “Got it”, etc. Secondary action (when applicable): “No thanks”

Buttons

Copy elements: label

  • All buttons should use verbs except when the user is:
    • Navigating: “Next”, “Continue”, “Back”, “Back to [product/section]”. Don’t use “Go back to [product/section]”
    • Speaking directly to us: “Never mind”, “No thanks”
  • Use a verb that matches the verb preceding it
  • Use “Cancel” only as a singular action outside of an alert. Don’t use “Cancel” as a primary or secondary action in a destructive decision alert. For actions to use within alerts, see Alerts
  • Use “Quick [verb]” to indicate immediacy or finality when the user might otherwise expect additional steps (and microcopy is unavailable)
  • Don’t use the same verb to start and complete a flow, or to indicate other distinct actions within a flow

Empty states

Copy elements: title, body, action (when applicable)

  • Use the opportunity to be more whimsical than in more conversion-driven contexts
  • Title: Say what data isn’t available, what action the user hasn’t taken, or what went wrong
  • Body: Say when the data will be available, what action the user needs to take, or how to correct what went wrong. Even if there’s no action in the form of a button, try to suggest an action within the body

Notifications

Copy elements: title (optional), body, action (when applicable)

  • Frontload the most important/relevant words in case the notification gets cut off

Select fields

Copy elements: label, placeholder, helper text (optional)

  • Format labels as nouns and placeholders as actions. Placeholders should align with labels, not duplicate them

Text fields

Copy elements: label, placeholder (when necessary), helper text (optional)

  • Format labels as nouns (not actions)
  • Avoid using placeholders, especially to replace labels. If you need to provide more information or direction outside of the label, use helper text