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.
11 min readFree
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’.
Key words
- 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?
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?
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
- How to Fix AI-Generated Microcopy, UX Team
- UX Microcopy Rules, Markdowners
- UX Writing and Microcopy: Rules That Reduce Errors, FNA Technology
- Microcopy in UX Writing: 7 UI Elements with Examples, Product With Mustache
- Microcopy: a complete guide to improving the user experience, Then Agency
- UX writing and microcopy: words that guide users, Ceptiv
- Microcopy & Content: UX principle, Better Design
- Getting Practical With Microcopy, Smashing Magazine
- Microcopy: Definition, Examples & Best Practices, Docsie
- UX Microcopy: Examples, Formulas & Best Practices for SaaS, Kompassify
- Writing for apps, Medway Council
- How do I write clear button and error messages, eChai Starting Up
Last updated on 17 November 2026
Related lessons
- Design systemsGuidelines: The Written Rules That Keep Design System Parts Used Well
- Design systemsCommit Guidelines: Write Clear, Small Commit Messages for Your Design System
- Design systemsWriting Guidelines: Teaching Every Screen to Speak With One Voice
- Design systemsContribution Guidelines: How Anyone Proposes and Ships a Design System Change
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.