# Microcopy Guidelines: Documented Rules for the Small Words That Guide Users

> Learn how design systems write down rules for button labels, error messages, hints and empty states so every screen sounds clear and consistent.

**In short:** Microcopy guidelines are written rules for the small words in a product, like button labels, error messages, hints and empty states, so every screen sounds clear and consistent.

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

## What you will learn

Microcopy is the short text inside a product. It tells people what to tap, what went wrong, and what will happen next. A design system writes down rules for this text so every screen sounds like the same product. Those written rules are called microcopy guidelines. This lesson shows you what they contain, how to write them, and how to store them so other designers and writers can use them without guessing.

By the end, you will be able to name the places where microcopy appears, apply four core writing rules, document do and don’t pairs and copy patterns for each component, and rewrite weak text such as ‘Invalid input’ and ‘Submit’.

- **Microcopy:** The small pieces of text inside an interface, such as a button label, a hint, an error or a confirmation.
- **Microcopy guideline:** A written rule about how to word that small text, with examples that show the rule in use.
- **Copy pattern:** A reusable sentence shape, such as ‘verb plus outcome’, that a team fills in for each case.
- **Button label:** The words printed on a button, such as ‘Save changes’.
- **Error message:** Text that tells the user a step failed and what to do next.
- **Empty state:** What a screen shows when there is no content yet.
- **Do and don’t pair:** A good example and a bad example placed side by side, with a short reason.

## What is microcopy and where does it appear?

Microcopy is the text that guides a person through a product, one small step at a time. The word ‘micro’ means each piece is short. A single word can still carry a lot of meaning. Good microcopy often goes unnoticed, because the user understands it at once. Bad microcopy makes the user stop, reread and guess.

- **Labels:** A label names a field, such as ‘Card number’, so the user knows what to type. Labels should stay visible on the screen. A placeholder should never replace a label.
- **Placeholders and helper text:** A placeholder is faint example text inside an empty field. Helper text is a short hint under a field, such as the format a date needs. Helper text should appear before the user makes a mistake.
- **Button labels:** A button label says what the button does when pressed.
- **Error messages:** An error message says that something failed and how to fix it. It appears at the exact moment trust is either kept or lost.
- **Confirmations:** A confirmation tells the user that an action worked, such as ‘Changes saved’. A confirmation before a risky action names the consequence, so the user knows what will happen.
- **Empty states:** An empty state explains why a screen has no content and offers a next step, such as a button that starts the first task.

Microcopy shapes usability because users read it at the points where they must act. A clear label lets them finish a task. A vague label makes them hesitate, retry or leave. A design can look perfect and still fail when its words are unclear. Words, not only visuals, decide whether a screen works.

> **Tip:** If the same error appears for many users, the wording may not be the real problem. Microcopy can only carry so much. Treat a frequent error as a sign that the design or the flow needs work.

## What core writing rules should you document?

A microcopy guideline starts with a few rules that apply to every component. Write these at the top of the page, before any component-specific examples. Each rule should be short enough that a busy designer can remember it.

- **Be clear, concise and specific:** Use short sentences and one idea per string. Choose exact words over general ones. ‘Confirm cancellation’ tells the user more than ‘Confirm’, even though it is longer.
- **Use action-oriented labels:** Start button labels with a verb and name the result. Avoid vague labels such as ‘Submit’, ‘OK’ and ‘Continue’ when a more exact verb is available.
- **Write errors that explain and fix:** Say what went wrong, say what to do next, and avoid blaming the user. Keep technical codes out of the main message.
- **Keep style and terms consistent:** Pick one capitalization style, one punctuation habit and one word for each action. Do not switch between ‘Save’, ‘Update’ and ‘Apply’ for the same job.

The next three sub-topics explain how to apply these rules in practice. Each one should appear in your system’s guideline page with examples.

### What are action-oriented labels?

Action-oriented means the label tells the user what will happen. A label such as ‘Delete account’ is clearer than ‘Submit’, because the user knows the result before pressing. Many guides suggest keeping labels short, often two to four words. Shortness must not remove the meaning. Destructive actions, such as deleting, should look and sound different from safe actions, such as cancelling. A user should never have to guess which button removes data.

### What makes an error message helpful?

A helpful error message names the problem and the fix. ‘Invalid input’ says that something is wrong but not what. ‘Enter a card number with 16 digits’ says what is wrong and what to do. Avoid words that blame the user, such as ‘You entered this wrong’. Avoid codes such as ‘Error 500’ in the main text. If support staff need a code, place it in small text below the message. Avoid ‘Oops’ in an error when real data is at risk, because it can feel too light.

### Consistency in capitalization, punctuation and terms

Consistency means the same thing looks and reads the same everywhere. Choose one term for each action and one term for each object, and list them in a shared glossary. Naming rules for tokens and components belong to a different lesson, but the same habit of one name per idea applies here.

## How do you document microcopy guidelines in the system?

Rules alone are not enough. Teams need examples they can copy. A good microcopy page in a design system has three parts: do and don’t pairs, copy patterns for each component, and ready-to-reuse strings. Together they remove guesswork.

### Do and don’t pairs

A do and don’t pair shows one weak choice and one strong choice, with a short reason. Pairs make the rule easy to see. Place the pair next to the component it governs, so the writer finds it while working.

- **Primary button:** Don’t use ‘Submit’. Do use a verb with the result, such as ‘Place order’. The reason: the user learns what happens next.
- **Form error:** Don’t use ‘Invalid input’. Do name the field and the fix, such as ‘Enter a card number with 16 digits’. The reason: the user can act without guessing.
- **Destructive confirmation:** Don’t use ‘Are you sure?’ alone. Do name the consequence, such as ‘Permanently delete this account?’. The reason: the stakes are visible before the click.
- **Step navigation:** Don’t switch between ‘Continue’ on one step and ‘Next’ on another. Do pick one word and use it on every step. The reason: consistent words reduce doubt.

### Copy patterns per component

A copy pattern is a sentence shape the team reuses. Each component gets one or two patterns. Writers fill in the blanks for each case, so new text follows the same structure. The patterns below are common in published content guidance.

- **Button:** Use verb plus outcome. For example: ‘Pay $42.00’ or ‘Send invite’.
- **Error:** Use problem plus fix. For example: ‘Password must have at least 12 characters’. A second line can add the fix when needed.
- **Hint:** Say the required format before the user types. For example: ‘Use the format DD/MM/YYYY’.
- **Empty state:** Use what is missing plus the next step. For example: ‘No projects yet. Create your first project.’
- **Confirmation:** Use what changed. For example: ‘Changes saved’. Keep it to the facts.

### Ready-to-reuse strings

Ready-to-reuse strings are finished sentences that a team can paste into a component. Store them with the component name and the screen where they appear. Add a note when a string depends on data, such as an amount or a date. Writers should not invent new wording for a case that already has an approved string. When a new case appears, add a new string to the page after review.

> **Tip:** Write the copy during design, using real error cases, not at the end of a build. A string filled in from a placeholder at build time often ends up vague.

## Worked example: a checkout form

Imagine a checkout form for an online shop. The total for the order is $42.00. The form has a card number field and a payment button. Testers report two problems. The card error says ‘Invalid input’. The button says ‘Submit’. Follow the steps below to fix both and record the fixes in the system.

1. **Find the vague error:** The card field shows ‘Invalid input’ when the number is too short. The message names no problem and no fix. It also sounds like a judgment of the user.
2. **Name the specific problem and the fix:** Rewrite it as ‘Enter a card number with 16 digits’. It says what is needed and how to correct it. It does not blame anyone or show a code.
3. **Check the new text against the rules:** The message is short and specific. It uses plain words. It uses the same sentence style as the other field errors. Nothing in it is technical.
4. **Rewrite the button:** Change ‘Submit’ to ‘Pay $42.00’. The label starts with a verb, names the result and shows the amount. The user knows what will happen before the click.
5. **Record the error as a pattern:** On the text field error page, add the pattern ‘problem plus fix’. Add the pair ‘Invalid input’ as the don’t example and ‘Enter a card number with 16 digits’ as the do example. Note that the digit count comes from the rules for that card field.
6. **Record the button rule:** On the button page, add the rule ‘payment buttons start with Pay and show the total’. Add ‘Submit’ as the don’t example and ‘Pay $42.00’ as the do example. Note that the amount must update if the total changes.

> **Tip:** A rule is only useful if a writer can find it. Link each rule from the component page where the text appears, not only from a general writing page.

## Check your understanding

**Quick check:** A signup form shows ‘Error 422: Request failed’ when the password is too short. The button under the form says ‘OK’. Which pair of rewrites best follows microcopy guidelines?

A. ‘Error 422: Try again.’ and ‘Submit’
B. ‘Choose a password with at least 12 characters.’ and ‘Create account’
C. ‘Something went wrong.’ and ‘Continue’
D. ‘Invalid password!’ and ‘Okay!’

**Answer:** B. The better error names the problem and the fix in plain words, without a code. The minimum length here is only an example; your product rules set the real number. The better button uses a verb and names the result of the action. The other options keep a code, a vague phrase, a generic button word or an exclamation mark that does not help the user.

Scenario: a team is building a ‘Delete project’ dialog. The first draft asks ‘Are you sure?’ with buttons ‘Yes’ and ‘No’. A reviewer wants the dialog to follow the guidelines. The project has 14 files that will be lost.

**Quick check:** Which confirmation and button pair is the best fit for this dialog?

A. ‘Are you sure?’ with ‘Yes’ and ‘No’
B. ‘Done!’ with ‘OK’
C. ‘Permanently delete this project and its 14 files?’ with ‘Delete project’ and ‘Cancel’
D. ‘Project update’ with ‘Apply’ and ‘Close’

**Answer:** C. The best option names the consequence and the number of files. Its destructive button repeats the exact action, and the safe button is clearly different. The ‘Are you sure?’ option makes the user work out the stakes. ‘Done!’ and ‘Project update’ do not describe the action. Those choices also reuse vague words such as ‘OK’ and ‘Apply’ that the guidelines avoid.

## Common mistakes to avoid

- **Using a placeholder as the label:** A placeholder disappears when the user types. The user then forgets what the field asks for. Keep a visible label, and use the placeholder only for an example.
- **Writing too politely:** Use it rarely, and let clear verbs do the work.
- **Using jargon and codes:** Words such as ‘null’ or ‘constraint’ mean little to most users. Use the words your user already knows.
- **Adding humour to errors:** A joke can add stress when the user is already blocked. Keep errors calm and direct.
- **Writing for one language only:** Keep strings in a shared file so they can be translated, and avoid idioms that do not travel well.

> **Tip:** Test important strings with real users. Focus first on primary buttons, field labels, errors and empty states. These carry the most load.

## Summary

Microcopy guidelines turn a brand’s voice into small, repeatable rules. Start with four core rules: be clear and specific, use action labels, write errors that explain and fix, and keep style and terms consistent. Then document them with do and don’t pairs, copy patterns for each component, and ready-to-reuse strings. The checkout example shows the full cycle: find the vague text, rewrite it, and record the new pattern and rule. The next lessons cover tone, component anatomy and accessibility in more depth.

## Sources

- [Microcopy writing guidelines, Open edX Design System Documentation](https://openedx.atlassian.net/wiki/spaces/BPL/pages/1966375321/Microcopy+writing+guidelines)
- [How to Fix AI-Generated Microcopy, UX Team](https://www.uxteam.com/ai-copy-fixes/)
- [UX Microcopy Rules, Markdowners](https://markdowners.com/m/markdowners/ux-microcopy-rules)
- [UX Writing and Microcopy: Rules That Reduce Errors, FNA Technology](https://fnatechnology.com/blog/ux-writing-microcopy-best-practices)
- [Microcopy in UX Writing: 7 UI Elements with Examples, Product With Mustache](https://productwithmustache.com/ux-writing-microcopy/)
- [Microcopy: a complete guide to improving the user experience, Then Agency](https://then.agency/en/articoli/microcopy)
- [UX writing and microcopy: words that guide users, Ceptiv](https://ceptiv.net/guides/ux-writing-microcopy)
- [Microcopy & Content: UX principle, Better Design](https://better-design.com/principles/ux/microcopy)
- [Getting Practical With Microcopy, Smashing Magazine](https://www.smashingmagazine.com/2016/07/getting-practical-with-microcopy/)
- [Microcopy: Definition, Examples & Best Practices, Docsie](https://www.docsie.io/blog/glossary/microcopy/)
- [UX Microcopy: Examples, Formulas & Best Practices for SaaS, Kompassify](https://kompassify.com/blog/ux-microcopy-guide)
- [Writing for apps, Medway Council](https://www.medway.gov.uk/info/200674/writing_for_apps)
- [How do I write clear button and error messages, eChai Starting Up](https://echai.ventures/startingup/product-design-ux/how-do-i-write-clear-button-and-error-messages-so-users-know-exactly-what-to-do-next)
