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