esc
  • WorkflowsPages
  • Case studiesPages
  • Machine Learning FoundationsLearn
  • AI EngineeringLearn
  • AI Guardrails & Red TeamingLearn
  • UI/UXLearn
  • Design SystemsLearn
  • Production System DesignLearn
  • Book a callContact
  • Download ResumeContact
Let’s talk

I’ll build the agent for it.

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. 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. 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. 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. 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. 2

    Give the most likely fix in sentence one

    Atlassian advises putting the simplest solution in the first sentence.

  3. 3

    Offer a backup in sentence two

    If the problem may come back, add a second option such as contacting support.

  4. 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. 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. 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. 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. 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. 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

How is this lesson?

Last updated on 17 November 2026

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.