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.
14 min readFree
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.
Key words
- 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.
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?
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 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?
Sources
- Mailchimp Content Style Guide: Voice and Tone
- Mailchimp Content Style Guide: Grammar and Mechanics
- Mailchimp Content Style Guide: TL;DR
- Atlassian Design: Style, grammar, and punctuation
- Atlassian Design: Error messages
- Atlassian Design: Empty state
- Atlassian Design: Warning messages (writing guidelines)
- Atlassian Design: Writing guidelines overview
- UX Content: How to create a UX content style guide
- Deliveroo Design: How to use voice and tone in UX writing
- 14 golden rules of UX writing (Design Bootcamp)
- Product with Mustache: Voice and Tone in UX Writing
- Technical Writer HQ: Technical writer style guides (Atlassian section)
Last updated on 17 November 2026
Related lessons
- Design systemsGuidelines: The Written Rules That Keep Design System Parts Used Well
- Design systemsMicrocopy Guidelines: Documented Rules for the Small Words That Guide Users
- Design systemsContribution Guidelines: How Anyone Proposes and Ships a Design System Change
- Design systemsCommit Guidelines: Write Clear, Small Commit Messages for Your Design System
Learn with me
Every lesson is free. I add new ones as I learn. Have a question, or want help with your own work? Book a short call.