# Writing Guidelines: Teaching Every Screen to Speak With One Voice

> How a design system's written rules keep button labels, error messages, and empty states clear, consistent, and in one voice.

**In short:** Writing guidelines are a design system's written rules that keep button labels, error messages and empty states clear, consistent and in one voice.

From "Design systems", a free course by Venkat R. Murty: https://designervenkat.online/learn/design-systems/writing-guidelines

## What you will learn

Almost every product is full of small pieces of text. A button says what will happen when you press it. An error message tells you that something went wrong. An empty state appears when a screen has nothing in it yet. A writing guideline is the part of a design system that sets rules for these words, so that every screen sounds as if one team wrote it.

In this lesson you will learn what writing guidelines cover, how voice and tone differ, the core style rules for interface text, and how to write for buttons, error messages, empty states, and confirmations. You will also walk through one worked example and answer three short quizzes.

- **Design system:** A shared set of parts and rules that a product team uses so that its screens look and work the same way.
- **UI copy:** The words inside a product's screens, such as labels, buttons, messages, and help text. UI is short for user interface.
- **Writing guideline:** A written rule, with examples, that tells writers and designers how to phrase a kind of text.
- **Voice:** The personality of a product's writing. It stays the same from screen to screen.
- **Tone:** How the voice sounds in one moment. It changes with the situation and the reader's feelings.
- **Empty state:** The message a screen shows when there is nothing to display, such as an empty inbox or a list with no items.
- **Call to action (CTA):** The button or link that tells the reader what to do next.

## What do writing guidelines cover?

Without a written rule, each person picks words by taste. One writer uses Sign in, another uses Log in, and a third uses Access your account. The reader then has to work out whether these three phrases mean the same thing. Writing guidelines remove that guesswork. They give writers practical rules and real examples, so the choice of words is decided once and reused.

- **Labels and buttons:** Short words that name a field, a menu item, or an action. They must say exactly what will happen.
- **Messages:** Errors, warnings, confirmations, and success notes. These appear when something has gone right or wrong, and they need the most care.
- **Screen-level text:** Empty states, tooltips (the small text box that appears when someone points at or focuses on an item), and short help text.

> **Tip:** Put the guideline where writers will look when they are stuck, such as next to the component in the design system. A rule that nobody can find does not help anyone.

## Voice and tone

Voice and tone are easy to mix up, so separate them before you write anything. Mailchimp's public style guide puts the difference in plain words: you keep the same voice all the time, but your tone changes with the people you talk to and the moment you talk to them. A product's voice answers the question of who the product is. Its tone answers how it should speak right now.

Write the voice down once, in a short list of traits. Then write the tone rules as a separate list that covers each common situation. Writers can then check a line against both lists.

### Which voice traits should you write down?

A voice needs a few traits, and each trait needs a plain meaning and an example. Mailchimp describes its voice with a small set of words, including human, familiar, friendly, and straightforward. It also says it values clarity over entertainment.

- **Clear before clever:** Say the point first. Jokes and wordplay come second, and they never hide the message.
- **Warm, not gushing:** Speak to the reader as a helpful person would, with contractions and you. Avoid over-the-top praise.
- **Calm when it matters:** When something is broken or risky, the voice stays the same but the tone becomes quieter and more direct.

Do and don't examples make a trait easy to apply. Here is one pair for the calm trait. Do: Your payment didn't go through. Check your card details and try again. Don't: Oops! Something went sideways with your payment!!

### How does tone shift with the reader?

Tone follows the reader's state of mind. Mailchimp asks writers to consider whether the reader is relieved to be finished with a task, or confused and looking for help. Its guide says you would not use the same tone with someone who is scared or upset as you would with someone who is laughing. The Deliveroo design team takes a similar route. It lists the feelings a user might have, places them on a scale, and then matches a brand tone to each point on that scale.

1. **Name the reader's feeling:** Ask what the person is likely feeling at this exact moment. Relieved, curious, worried, or stuck are common answers.
2. **Pick the tone for that feeling:** Use a celebratory tone for a success, and a calm, plain tone for an error. Keep the same voice traits in both.
3. **Write the line and read it aloud:** If the line sounds like a joke to someone who is worried, rewrite it. If it sounds flat to someone who just finished a big task, add warmth.

> **Tip:** A search snippet of Deliveroo's writing guide appears to give a simple limit: one exclamation mark per screen. It is enthusiastic without being shouty. Use a limit like this in your own guideline so that tone does not drift.

## What are the core style rules for UI text?

The rules in this part apply to almost every line of interface text. Each one is short, so a writer can remember it while typing. Together they make the product's words easy to scan.

### Plain words and active voice

Use plain language. Avoid jargon, which means special words that only experts know, and avoid slang. Mailchimp's guide asks writers to write in plain English and to use positive language rather than negative language.

Also use the active voice. In an active sentence, the subject does the action. In a passive sentence, the subject has the action done to it. Mailchimp gives a clear pair: Marti logged into the account is active, and The account was logged into by Marti is passive. Words such as was and by are a sign that a sentence may be passive, so scan for them and rewrite.

> **Tip:** Write the action first. Say Save changes, not Changes can be saved by pressing the button. Short, active lines are easier to read on a small phone screen.

### Should you use sentence case or title case?

Sentence case capitalizes only the first word of a line and any proper nouns, such as product or company names. Title case capitalizes most of the words. Atlassian's guidance asks for sentence case in titles, headings, menu items, labels, and buttons.

- **Do:** Create work item. Use this form for labels and buttons.
- **Don't:** Create Work Item. Title case makes every label look like a heading and slows reading.

### Concise labels and consistent terms

Keep labels short. Atlassian's guidance asks for call-to-action labels of one or two words in its error and empty-state pages. Articles such as a and the are often left out of buttons, so write Create password instead of Create a password.

Pick one term for each action and use it everywhere. If the sign-in button says Sign in, the banner and the help link should not say Log in. Mailchimp's translation advice also warns writers against using synonyms for the same word in a single piece of writing. Different words make people think there are two different actions.

> **Tip:** Start a word list. Mailchimp's style guide includes its own word list, and Atlassian keeps an internal vocabulary list. Your list can be a single table with the preferred term, the terms to avoid, and one example.

### Punctuation, capitals, numbers, and dates

Small details cause big inconsistency when every writer decides them alone. Settle them once in the guideline.

- **Numbers:** Atlassian's guidance uses digits in most cases, so write 8 characters, not eight characters. Show progress as Step 1 of 2, not Step 1/2.
- **Ranges:** Write the word to between numbers in most UI text, as in rows 1 to 4, unless space is tight.
- **Contractions:** Use them for a friendly tone, as in We can't load this page. Atlassian's guidance treats contractions as a conversational choice.
- **Abbreviations:** Avoid e.g., i.e., etc., and the ampersand in UI copy. Atlassian notes that they do not translate well and can confuse people who use screen readers.
- **Dates:** Choose one date format and write it in the guideline. Do not leave the choice to each writer.

> **Tip:** Spelling is a convention too. Atlassian asks for US English in UI copy. Pick one spelling variety for your product and write it down.

## How do you write by UI pattern?

The same rule works differently on each pattern. A button has to be short and exact. An error has to explain a problem. An empty state has to lead somewhere. The guideline should give one short rule and one example for each common pattern.

### Buttons

A button should name the action that happens when someone presses it. Start with an imperative verb, which is a command word such as Save, Remove, or Create. Atlassian's guidance warns against vague choices such as OK. A label such as Submit names the form, not the result, so it often leaves people unsure what will happen.

- **Before: checkout:** Submit, on a checkout page.
- **After: checkout:** Place order. The reader now knows exactly what will happen when they press it.
- **Before: delete dialog:** OK, on a dialog that deletes a file.
- **After: delete dialog:** Delete file. A cancel option sits next to it so the reader can back out.

### Error and validation messages

An error message appears after someone has taken an action and a problem has happened. Atlassian says it should tell the reader what happened, what to do next, and why if it is known. A validation message is a smaller error that checks what someone typed, such as an empty required field.

1. **Name the problem in plain words:** Say what went wrong, such as The payment didn't go through. Leave out error codes and internal terms.
2. **Give the most likely fix in sentence one:** Atlassian advises putting the simplest solution in the first sentence.
3. **Offer a backup in sentence two:** If the problem may come back, add a second option such as contacting support.
4. **Do not guess the cause:** If you do not know why something failed, say that something went wrong and offer a next step instead of inventing a reason.

Avoid please and sorry in error messages. Atlassian explains that sorry can make a problem seem more serious than it is, and that please can make a required step sound optional. Keep the message to one or two sentences, and do not repeat the title.

- **Before:** Error 402: invalid input.
- **After:** Your card was declined. Check the card number and expiry date, then try again.

### Empty states

An empty state appears when a screen has nothing to show. Atlassian describes these messages as appearing after someone finishes a task or clears data, such as an empty inbox. The message should give the reason for the empty screen and point to the next place to go. If there is nothing left to do, it can celebrate the finish.

- **Before:** No items.
- **After:** No open tasks. Nice work. Create a task to plan what comes next.
- **Rule for titles:** Use sentence case and skip end punctuation, unless the title is a question.
- **Rule for repeats:** A message that shows often should be shorter and less playful. Atlassian notes that timing and repetition matter.

### Confirmations and warnings

A confirmation asks someone to approve an action before it happens, often a delete. A warning is a close relative. Atlassian says a warning covers a condition that might cause a problem later. An error appears after the action. Give a cancel option so people feel free to back out.

- **Before:** Are you sure?
- **After:** Delete this project? All of its files will be removed and cannot be restored.
- **Cancel button:** Keep project. It tells the reader what the other choice does.

> **Tip:** Atlassian advises against winks and jokes where there could be a real problem for the reader. Save the playful lines for successes and empty states.

## How do you use inclusive and accessible wording?

Words can shut people out. Include this in your guideline with a short list of words to avoid and a better replacement for each.

Pronouns need care too. Atlassian advises using the pronoun a customer gives, and using they or their when the pronoun is unknown. Use descriptive link text, such as View billing history, not click here. Keep sentences short and scannable, and avoid jargon. Give alternative text to icons and illustrations inside messages, so screen readers can announce them.

> **Tip:** Read every message aloud before it ships. If a sentence is hard to say in one breath, it is probably hard to read on a small screen or to translate.

## Worked example: one voice, two tones

Mailchimp's Content Style Guide is public, and it shows how one brand keeps a friendly, clear voice while the tone changes. The two messages below are teaching examples written for this lesson. They are not copied from Mailchimp's product. Follow the steps to see how the guide's ideas apply to them.

1. **Fix the voice first:** Mailchimp describes its voice as human, familiar, friendly, and straightforward, and it values clarity over entertainment. Both messages must sound like the same plain, friendly product.
2. **Read the reader's state:** After a campaign is sent, the user is probably relieved and pleased. After a failed payment, the user is probably worried and needs to act. The guide asks writers to start from this feeling.
3. **Set a celebratory tone for success:** Campaign sent! Your campaign is on its way to your list. The exclamation mark is allowed because the news is good, and the message stays short.
4. **Set a calm, direct tone for the error:** Your payment didn't go through. Check your card details or try another card. No exclamation mark, no sorry, and no please. The first sentence names the problem and the second gives the fix.
5. **Check the shared rules:** Both messages use sentence case, active verbs, one word for payment, and plain words. Only the tone differs. Run every new message through this same check.

- **Stays the same:** The voice: friendly, plain, and clear, with the same vocabulary across screens.
- **Changes:** The tone: joyful for the success message, steady and direct for the failed payment.
- **Lesson for your guideline:** Write both examples into the guideline, so the next writer can copy the pattern without guessing.

## Check your understanding

Try these three short scenarios. Each one needs an idea from this lesson to answer it.

**Quick check:** Your checkout button says Submit, the cart page says Buy now, and the error message says Transaction failure: invalid input 0x4F. Which writing guidelines would fix this best?

A. Use a different button color for each page so people can tell the actions apart.
B. Use one action word for the purchase on every screen, and write the error in plain words that say what to do next.
C. Add more technical detail to the error so support staff can trace the code.
D. Make all three messages longer so that the reader understands each step.

**Answer:** B. The guideline asks for one term for one action, and for labels that name the action. It also asks for plain errors with no codes. A better error would read: Your payment didn't go through. Check your card details and try again.

Your product uses Log in on the main button, Sign in on a banner, and Access your account on a help link. The team wants one term for the same action.

**Quick check:** Which change follows the consistent-terms rule?

A. Keep all three phrases, because each screen has its own writer.
B. Choose one term, such as Sign in, and use it on the button, the banner, and the help link.
C. Use Access your account everywhere, because it sounds more formal.
D. Use the longest phrase on each screen so that no one misses the message.

**Answer:** B. Synonyms for the same action make people wonder whether there are two different actions. Pick one term, write it into the word list, and reuse it on every screen.

A user clears all of their notifications many times each day. The empty state reads: Nothing left! You crushed it, champion!!! The team wants to keep the empty state, but the message appears often.

**Quick check:** What is the best tone guidance for this repeated empty state?

A. Keep the big celebration, because users will enjoy it every time.
B. Make the message shorter and calmer, because it appears often, and keep the same friendly voice.
C. Remove all words and show only an icon, so the screen stays quiet.
D. Switch to a warning style, so that people notice the message.

**Answer:** B. Atlassian's guidance says that frequent messages should be more concise and less playful. The voice stays friendly, but the tone should be lighter and shorter for repeated moments.

## Sources

- [Mailchimp Content Style Guide: Voice and Tone](https://styleguide.mailchimp.com/voice-and-tone/)
- [Mailchimp Content Style Guide: Grammar and Mechanics](https://styleguide.mailchimp.com/grammar-and-mechanics/)
- [Mailchimp Content Style Guide: TL;DR](https://styleguide.mailchimp.com/tldr/)
- [Atlassian Design: Style, grammar, and punctuation](https://atlassian.design/foundations/content/language-and-grammar)
- [Atlassian Design: Error messages](https://atlassian.design/foundations/content/designing-messages/error-messages)
- [Atlassian Design: Empty state](https://atlassian.design/foundations/content/designing-messages/empty-state)
- [Atlassian Design: Warning messages (writing guidelines)](https://atlassian.design/content/writing-guidelines/writing-a-warning-message/)
- [Atlassian Design: Writing guidelines overview](https://atlassian.design/content/writing-guidelines/)
- [UX Content: How to create a UX content style guide](https://uxcontent.com/how-to-create-style-guide/)
- [Deliveroo Design: How to use voice and tone in UX writing](https://medium.com/deliveroo-design/how-to-use-voice-and-tone-in-ux-writing-a66981c78d20)
- [14 golden rules of UX writing (Design Bootcamp)](https://medium.com/design-bootcamp/14-golden-rules-of-ux-writing-946d37706334)
- [Product with Mustache: Voice and Tone in UX Writing](https://productwithmustache.com/tone-of-voice-ux-writing/)
- [Technical Writer HQ: Technical writer style guides (Atlassian section)](https://technicalwriterhq.com/writing/technical-writing/technical-writer-style-guide/)
