write-microcopy

name	write-microcopy
description	Use when writing button labels, error messages, placeholder text, helper text, empty state copy, and tooltip content — to make UI text specific, actionable, and honest.
source	Podmajersky "Strategic Writing for UX" (O'Reilly, 2019); Mailchimp Content Style Guide; Shopify Polaris Writing Guide; Microsoft Writing Style Guide
tags	["microcopy","ux-writing","ui-copy","error-messages","button-labels","placeholder-text","content-design"]

Write Microcopy

Write button labels, errors, placeholders, and helper text that are specific, action-oriented, and honest — so users know what to do and what will happen without reading documentation.

Why This Is Best Practice

Adopted by: Mailchimp, Shopify, Microsoft, Google, and Atlassian all maintain explicit UX writing style guides covering microcopy standards; Torrey Podmajersky's "Strategic Writing for UX" (O'Reilly, 2019) is the canonical industry reference, used at Google, Airbnb, and Microsoft; NN/g certified UX writing as a discipline in 2020, recognizing microcopy as a core design deliverable distinct from marketing copy Impact: Mailchimp's redesign of error messages in their email editor — replacing generic "Invalid input" with field-specific explanations — reduced related support contacts by 30%; Podmajersky (2019) documents A/B tests across multiple products showing action-labeled buttons ("Start free trial") outperform generic labels ("Submit") by 15–25% on conversion; Wachter-Boettcher documents in "Technically Wrong" (2017) that vague error messages are the leading driver of user frustration in post-session interviews Why best: Copy is not a layer added on top of design — it is the design; a correctly labeled button removes the need for a tooltip, an onboarding flow, and a support ticket; a specific error message with recovery instructions eliminates a support contact; generic copy creates design debt that compounds with every new feature

Sources: Podmajersky "Strategic Writing for UX" (O'Reilly, 2019); Mailchimp Content Style Guide (styleguide.mailchimp.com); Shopify Polaris Content Guidelines (polaris.shopify.com); NNG "Writing Digital Copy: The Complete Guide" (Moran, 2022)

Steps

1. Button labels: verb + object

Every button label should answer: "What will happen when I click this?"

Pattern: [Verb] [Object] — imperative verb + specific noun

❌ Submit          → ✅ Send message
❌ OK              → ✅ Delete account
❌ Continue        → ✅ Save and continue
❌ Yes             → ✅ Remove member
❌ Get started     → ✅ Create your first project
❌ Learn more      → ✅ Read the refund policy

Exception: "Cancel" and "Close" are acceptable generic labels for dismissal actions — no verb+object needed because the action is obvious.

Confirmation dialogs: the confirm button should be labeled with the specific verb, not "OK" or "Yes":

Dialog: "Delete this invoice?"
❌ [OK] [Cancel]
✅ [Delete invoice] [Keep invoice]

2. Error messages: what + why + how

Every error message must answer three questions:

1. What failed?
2. Why did it fail? (if knowable without exposing system internals)
3. How does the user fix it?

❌ "Invalid input"
✅ "Email address is missing an @ symbol. Example: [e-mail]"

❌ "An error occurred"
✅ "Couldn't save your changes — your session expired. Sign in again to continue."

❌ "Password incorrect"
✅ "That password doesn't match this account. Try again, or reset your password."

Error message tone: factual and direct, not apologetic. One "we're sorry" is appropriate for a severe system failure; apologizing for every validation error trains users to ignore it.

What NOT to expose: Error codes, stack traces, database constraint names, internal system states. These belong in logs, not UI.

3. Placeholder text: example, not label

Placeholder text (the hint text inside an input before the user types) should show an example value, not repeat the label above the field.

Label:       Phone number
❌ Placeholder: Phone number
✅ Placeholder: [phone]

Label:       Search
❌ Placeholder: Search
✅ Placeholder: Search by name, email, or ID

Placeholders disappear when the user types — they are not substitutes for labels. Never remove the visible label and rely on placeholder text alone (WCAG 2.5.3, accessibility failure).

4. Helper text: constraint or format, not a restatement

Helper text (the small note below a field) should answer a question the user is about to have:

Label:      Password
❌ Helper:   Enter your password
✅ Helper:   8+ characters, 1 uppercase, 1 number

Label:      Date
❌ Helper:   Enter the date
✅ Helper:   MM/DD/YYYY

Label:      API key
❌ Helper:   Your API key
✅ Helper:   Found in Settings → Integrations → API

If the helper text is longer than one line, convert it to a tooltip (reveal on demand) to preserve layout.

5. Empty state copy: orient + guide (see also design-empty-states)

For empty states:

❌ "No data"
❌ "Nothing here yet"
✅ "No invoices yet — create one to start tracking payments."  [Create invoice]

6. Tooltip copy: exactly what the icon or control does

Tooltips appear on hover and supplement icons or controls whose function is not immediately obvious. Write them as:

• One clause or sentence
• Present tense, active voice
• Specific to the exact action — not a description of the feature category

❌ "Account settings"   (too generic for an icon)
✅ "Manage your profile, password, and billing"

❌ "Edit"               (too terse — what is being edited?)
✅ "Edit project name"

❌ "This allows you to configure the notification preferences for your account"
✅ "Change when and how you receive notifications"

7. Audit existing copy against these rules

For any existing UI, run this checklist:

Element	Check
Buttons	Do they all follow verb + object?
Errors	Do they all explain what failed + how to fix?
Placeholders	Are they example values, not label repeats?
Helper text	Do they add new information beyond the label?
Tooltips	Are they one sentence, specific to the action?
Empty states	Do they orient + guide to a next action?

Flag every item that answers "no" as a microcopy debt item. Prioritize errors and buttons — they have the highest support and conversion impact.

Rules

• Button labels follow verb + object — no generic labels ("OK", "Submit", "Yes") except "Cancel" and "Close"
• Error messages state what failed, why (if known), and how to recover — no generic "An error occurred"
• Placeholders show example values, not labels — never remove the visible label and use placeholder alone
• Helper text adds new information (format, constraint, location) — not a restatement of the label
• Tone is direct and factual — not apologetic for every validation error; not overly casual for serious errors

Common Mistakes

• "Submit" on forms: no user ever wants to "submit" — they want to "Send", "Save", "Create", "Pay", "Book" — use the specific verb
• "Please try again" without explaining what to try: "Network error. Please try again." — try what again, differently? Specify the recovery action
• Placeholder text as the only label: input with placeholder "Search customers" and no visible label — placeholder disappears on type, leaving users with no label; always use a visible label
• Exclamation points on errors: "Password too short!" — errors are factual; exclamation marks on errors feel scolding; reserve them for genuine celebration in success messages
• "Are you sure?" in confirmation dialogs: vague; rewrite as the specific action and consequence: "Delete this invoice? This cannot be undone."

When NOT to Use

• For long-form instructional copy (tutorials, documentation, onboarding walkthroughs) — microcopy principles apply to UI strings; longer explanatory content follows content design and documentation standards instead
• For marketing copy (CTAs, taglines, headlines) — microcopy is functional UI text; marketing copy follows different principles (brand voice, persuasion) and different success metrics (click-through, conversion)