pageweave/resources

UX Writing & Microcopy

Write clear, actionable microcopy for every UI state: buttons, errors, empty states, onboarding, notifications, and form validation.

· .md · source ↗

Every word in an interface is a design decision. Button labels, error messages, empty states, onboarding steps — they all teach the user how the product works. Generic copy teaches nothing.

The Principles

  1. Clear over clever. "Submit" is clearer than "Let's go." "Save changes" is clearer than "Done." Users scan — they don't read. Make the scan work.
  2. Action-oriented. Start with the verb. "Create project" not "Project creation." "Delete account" not "Account deletion."
  3. Specific over vague. "Your file report.pdf is too large (max 10MB)" beats "File too large." "Enter your work email" beats "Enter email."
  4. One idea per message. Error messages explain ONE problem and ONE fix. Not three possible causes.
  5. Match the tone to the context. Error messages: empathetic, solution-focused. Empty states: encouraging, action-oriented. Success: brief, celebratory (but not over-the-top).

Button Labels

The Rule

The button label should complete the sentence "I want to ___"

Button User thinks
Save changes I want to save changes ✓
Continue I want to continue ✓
Create project I want to create project ✓
Submit I want to submit... what? ✗
Click here I want to click here... why? ✗
OK I want to OK... what does this do? ✗

Primary vs. Secondary

Never Use

Instead: "Create account", "Download report", "View pricing", "Read the guide".

Error Messages

The Formula

[What went wrong] + [Why, if useful] + [What to do next]

Bad Good
Error 404 Page not found. Check the URL or go back to the homepage.
Invalid input Email address is missing an @ symbol. Use format: name@example.com
Something went wrong We couldn't save your changes. Check your connection and try again.
Payment failed Your card was declined. Update your payment method or try a different card.

Rules

  1. Never blame the user. "You entered the wrong password" → "Incorrect password. Try again or reset it."
  2. Never show raw error codes without human explanation. "Error 500" means nothing to users.
  3. Never leave the user stuck. Every error message must suggest a next action.
  4. Be specific about what failed. "Couldn't upload avatar.jpg" beats "Upload failed."
  5. Keep it short. One sentence for the problem, one for the fix. Max.

Empty States

Empty states are the first thing new users see. They should teach, not just inform.

The Formula

[What goes here] + [Why it's empty] + [What to do about it]

Context Bad Good
No projects No projects yet. You don't have any projects yet. Create your first project to get started. [Create project]
No search results No results. No projects match "quarterly." Try a different search or browse all projects.
No notifications Nothing here. You're all caught up! New notifications will appear here.
No messages No messages. Start a conversation with your team. [New message]

Rules

  1. Always include a call-to-action if there's something the user can do.
  2. Use the empty state to teach what the feature does.
  3. Keep the tone encouraging — empty states shouldn't feel like failures.
  4. Show an illustration or icon to make the state feel intentional, not broken.

Form Validation

Inline Validation

Validate on blur (when user leaves the field), not on every keystroke. Keystroke validation feels like being watched.

Field Bad Good
Email (invalid) Invalid email Enter a valid email address, like name@example.com
Password (weak) Weak password Use at least 8 characters with one number and one uppercase letter
Required (empty) This field is required Enter your full name
URL (invalid) Invalid URL Enter a valid URL, like https://example.com

Success States

After form submission:

Onboarding

The Progressive Disclosure Pattern

Don't explain everything upfront. Teach one concept at a time, in context.

  1. Welcome screen: one sentence about what the product does. One CTA.
  2. First action: guide the user to their first success (create a project, invite a teammate).
  3. Contextual tips: show tips when the user reaches the relevant feature, not before.
  4. Checklist: for complex products, a progress checklist ("3 of 5 steps complete") motivates completion.

Onboarding Copy Rules

Notifications & Toasts

Type Duration Tone Example
Success 3–5s Brief, positive "Project created"
Info 5s Neutral "3 new comments on your post"
Warning Until dismissed Cautionary "Your trial ends in 3 days"
Error Until dismissed Empathetic + actionable "Couldn't save. Check your connection."

Rules

Voice & Tone

The Four Dimensions

Dimension Range Example
Formal ↔ Casual "We apologize for the inconvenience" ↔ "Oops, something went wrong"
Serious ↔ Playful "Your data has been securely encrypted" ↔ "Your secrets are safe with us 🔒"
Authoritative ↔ Collaborative "Update required" ↔ "Let's update your settings"
Enthusiastic ↔ Restrained "Amazing! You did it! 🎉" ↔ "Changes saved."

Rules

  1. Pick a lane and stay in it. Don't mix formal error messages with playful empty states.
  2. Match the stakes. Error messages should be more serious than success messages.
  3. Cultural sensitivity matters. Humor doesn't translate. When in doubt, be restrained.
  4. The product's audience determines tone. A banking app is more formal than a game.

Localization Considerations

Anti-Patterns

← all skills