Writing for product

Component-specific copy lives in each component's own design docs, in its Content section. This page covers the patterns that span components: the message types and interaction moments that show up across the product.

Accessibility and alt text

Alt text makes images accessible to people who use screen readers and provides context when images don't load. Every informative image needs alt text, and decorative images should use alt="" so screen readers skip them.

Good alt text describes meaning and context rather than visual detail, and stays within the character guidance. Don't open with "Image of" (screen readers already announce that it's an image), and don't repeat the caption. Use the same word choices as the nearby body text and captions so the image and the copy around it read as one description.

Alt text in Customer.io contexts

Empty state illustrations are usually decorative. If the heading and body copy already convey the message, use alt="". Charts and data visualizations are the opposite case: describe the key insight, not the structure, as in "Open rates peaked at 42% in March, driven by the re-engagement campaign." For complex charts, note the general pattern and link to the underlying data.

Buttons and action labels

A button label starts with a verb, stays short (see character guidance), and is specific enough to be self-explanatory without its surrounding context. Generic verbs like "Submit", "Confirm", and "OK" require people to hold that context in their heads to understand what will happen. Specific verbs like "Delete campaign" and "Send newsletter" let people act with confidence. This matters most for destructive actions, where a vague label can have significant consequences. If a label uses the word "Yes", pair it with the action that will take place: "Yes, delete snippet".

Prefer "Cancel" for a plain dismiss, but a specific dismiss verb is better when it clarifies what staying or leaving does ("Keep my account", "Go back"). Never use "No", "Never mind", or "Close". When a button opens a dialog or requires additional input before the action completes, add an ellipsis (…); see Ellipses for the full rule.

Types

Character guidance

These are recommended maximums. Treat them as a ceiling, not a target; shorter is usually better.

Component-specific content

For copy examples specific to a component, see that component's own design documentation:

• Badge
• Button
• Confirmation modal
• Empty state
• Form
• Modal
• Page loader
• Snackbar
• Spinner
• Text field
• Tooltip

Confirmation dialogs

Confirmation dialogs pause a destructive or consequential action long enough for the person to confirm it deliberately.

The title is in sentence case, ends with a question mark, and names the object being acted on. Generic titles like "Are you sure?" or "Delete?" force the person to look elsewhere to work out what they're confirming. The body states the consequence: if the action is irreversible, say so explicitly, and if it's reversible within a time window, state the window. The confirm button follows the button rules and restates the action. Cancel is always present and visually de-emphasized.

Empty states

An empty state tells the person what's missing and, when there's a next step, gives them a way to take it. The heading is in sentence case with no period; the body is written in full sentences, with periods, and stays within the character guidance. Include a primary action whenever one exists, and don't apologize for the emptiness. Vague filler like "Nothing to see here." or "There is no content available at this time." tells the person nothing about what belongs here or what to do next.

Be mindful of what you put here. Critical information that disappears once the state is populated belongs somewhere permanent.

No data

No data exists yet. Tell the person what will appear here and give them a clear action to get started.

No results

Data exists, but nothing matched. Echo the query so the person can see what was searched, and suggest a way to recover.

Promotional

A promotional empty state introduces a feature the person hasn't used yet. The tone is benefit-led and outcome-first, closer to marketing copy than product copy, and it pairs with a hero image depicting a stylized future state.

Errors and system feedback

Error states are high-anxiety moments. Vague errors ("Something went wrong") make people feel helpless, and blame-framed errors ("You entered an invalid value") create frustration. A good error message turns a moment of friction into a moment of guidance. It is often the difference between a person recovering independently and submitting a support ticket.

To get there, answer as many of these as you can:

1. What happened? State the problem plainly.
2. Why? Give context when it's honest and useful.
3. What now? Give a specific next step, and always offer a recovery path when one exists.

Never say "Oops", and never use exclamation points in an error.

Destructive warnings (before action)

State the consequence. If the action is reversible within a time window, say so. It's more informative and less alarming than stating only that something will be deleted.

Payment and account errors

Use passive voice in payment, security, and account errors where active voice would imply blame or cause alarm. "Your payment was declined" reports a fact; "We declined your payment" picks a fight.

Permission errors

Name what the person can't do and who can help. A bare "Access denied" leaves them with no way forward.

Success messages

Confirm what happened and keep it brief, with no editorializing. A warm tone belongs to genuine milestones (a welcome, a thank-you), not routine confirmations; see Exclamation points.

System errors (something failed)

Say what didn't happen and what the person can try. "An error occurred" is technically true and practically useless.

Validation errors (inline, adjacent to field)

Frame validation errors as instructions, not accusations. Tell the person what a valid value looks like rather than only that theirs isn't.

Onboarding

Lead each step with the task rather than background information, and give one instruction per step. Always show progress ("step X of Y" or an equivalent) so the person knows how much is left. When they finish, confirm completion explicitly: say what was set up and what they can do now. "Setup complete!" celebrates without informing.