UX Writing

Auto-generate your docs

Make every word earn its place. Don’t repeat information users can already see.

The Button Label Problem

Never use “OK”, “Submit”, or “Yes/No”. These are lazy and ambiguous.

Use specific verb + object patterns:

Bad	Good	Why
OK	Save changes	Says what will happen
Submit	Create account	Outcome-focused
Yes	Delete message	Confirms the action
Cancel	Keep editing	Clarifies what “cancel” means
Click here	Download PDF	Describes the destination

For destructive actions, name the destruction:

“Delete” not “Remove” (delete is permanent, remove implies recoverable)
“Delete 5 items” not “Delete selected” (show the count)

Error Messages: The Formula

Every error message should answer:

What happened?
Why?
How to fix it?

<!-- Good -->
<p class="error">
  Email address isn't valid. Please include an @ symbol.
</p>

<!-- Bad -->
<p class="error">Invalid input</p>

Error Message Templates

Situation	Template
Format error	”[Field] needs to be [format]. Example: [example]“
Missing required	”Please enter [what’s missing]“
Permission denied	”You don’t have access to [thing]. [What to do instead]“
Network error	”We couldn’t reach [thing]. Check your connection and [action].”
Server error	”Something went wrong on our end. We’re looking into it. [Alternative action]“

Don’t Blame the User

Reframe errors:

✅ "Please enter a date in MM/DD/YYYY format"
❌ "You entered an invalid date"

✅ "Password must be at least 8 characters"
❌ "Your password is too short"

Empty States Are Opportunities

Empty states are onboarding moments:

Acknowledge briefly
Explain the value of filling it
Provide a clear action

<!-- Good -->
<div class="empty-state">
  <h3>No projects yet</h3>
  <p>Create your first project to start organizing your work.</p>
  <button>Create project</button>
</div>

<!-- Bad -->
<div class="empty-state">
  <p>No items</p>
</div>

Voice vs Tone

Voice is your brand’s personality—consistent everywhere. Tone adapts to the moment.

Moment	Tone Shift
Success	Celebratory, brief: “Done! Your changes are live.”
Error	Empathetic, helpful: “That didn’t work. Here’s what to try…”
Loading	Reassuring: “Saving your work…”
Destructive confirm	Serious, clear: “Delete this project? This can’t be undone.”

Never use humor for errors. Users are already frustrated. Be helpful, not cute.

Writing for Accessibility

Link Text

Must have standalone meaning:

<!-- Good -->
<a href="#">View pricing plans</a>

<!-- Bad -->
<a href="#">Click here</a>

Alt Text

Describes information, not the image:

<!-- Good -->
<img src="chart.png" alt="Revenue increased 40% in Q4">

<!-- Bad -->
<img src="chart.png" alt="Chart">

<!-- Decorative images -->
<img src="divider.png" alt="">

Icon Buttons

Need aria-label for screen reader context:

<button aria-label="Close dialog">
  <svg><!-- X icon --></svg>
</button>

Writing for Translation

Plan for Expansion

German text is ~30% longer than English. Allocate space: | Language | Expansion | |----------|-----------|| | German | +30% | | French | +20% | | Finnish | +30-40% | | Chinese | -30% (fewer chars, but same width) |

Translation-Friendly Patterns

Keep numbers separate:

✅ "New messages: 3"
❌ "You have 3 new messages"

Use full sentences as single strings (word order varies by language):

✅ "Your account was created successfully"
❌ "Your" + "account" + "was created successfully"

Avoid abbreviations:

✅ "5 minutes ago"
❌ "5 mins ago"

Give translators context about where strings appear.

Consistency: The Terminology Problem

Pick one term and stick with it:

Inconsistent	Consistent
Delete / Remove / Trash	Delete
Settings / Preferences / Options	Settings
Sign in / Log in / Enter	Sign in
Create / Add / New	Create

Build a terminology glossary and enforce it. Variety creates confusion.

Avoid Redundant Copy

If the heading explains it, the intro is redundant. If the button is clear, don’t explain it again. Say it once, say it well.

<!-- Redundant -->
<h2>Delete Account</h2>
<p>This will delete your account.</p>
<button>Delete Account</button>

<!-- Better -->
<h2>Delete Account</h2>
<p>This action cannot be undone. All your data will be permanently removed.</p>
<button>Delete account</button>

Loading States

Be specific:

✅ "Saving your draft..."
❌ "Loading..."

For long waits, set expectations:

"Generating report... This usually takes 30 seconds"

or show progress:

"Processing 47 of 120 files..."

Confirmation Dialogs: Use Sparingly

Most confirmation dialogs are design failures—consider undo instead. When you must confirm:

Name the action
Explain consequences
Use specific button labels

<!-- Good -->
<dialog>
  <h2>Delete project?</h2>
  <p>This will permanently delete "Website Redesign" and all its files. This can't be undone.</p>
  <button class="danger">Delete project</button>
  <button>Keep project</button>
</dialog>

<!-- Bad -->
<dialog>
  <p>Are you sure?</p>
  <button>Yes</button>
  <button>No</button>
</dialog>

Form Instructions

Show format with placeholders, not instructions:

<!-- Good -->
<label>Phone number</label>
<input type="tel" placeholder="(555) 123-4567">

<!-- Avoid -->
<label>Phone number (format: 555-123-4567)</label>
<input type="tel">

For non-obvious fields, explain why you’re asking:

<label>Date of birth</label>
<input type="date">
<p class="help-text">We use this to verify your age</p>

Guidelines

DO

Use specific verb + object button labels
Answer what happened, why, and how to fix in error messages
Design empty states that teach and motivate
Write link text that makes sense out of context
Build a terminology glossary
Be specific in loading states

DON’T

Use jargon without explanation
Blame users (“You made an error” → “This field is required”)
Write vague errors (“Something went wrong”)
Vary terminology for variety
Use humor for errors
Repeat information users can already see

⌘I

Frontend Design

Quality & Refinement

Enhancement

Structure & Flow

Setup

The Button Label Problem

Error Messages: The Formula

Error Message Templates

Don’t Blame the User

Empty States Are Opportunities

Voice vs Tone

Writing for Accessibility

Link Text

Alt Text

Icon Buttons

Writing for Translation

Plan for Expansion

Translation-Friendly Patterns

Consistency: The Terminology Problem

Avoid Redundant Copy

Loading States

Confirmation Dialogs: Use Sparingly

Form Instructions

Guidelines

DO

DON’T

​The Button Label Problem

​Error Messages: The Formula

​Error Message Templates

​Don’t Blame the User

​Empty States Are Opportunities

​Voice vs Tone

​Writing for Accessibility

​Link Text

​Alt Text

​Icon Buttons

​Writing for Translation

​Plan for Expansion

​Translation-Friendly Patterns

​Consistency: The Terminology Problem

​Avoid Redundant Copy

​Loading States

​Confirmation Dialogs: Use Sparingly

​Form Instructions

​Guidelines

​DO

​DON’T

The Button Label Problem

Error Messages: The Formula

Error Message Templates

Don’t Blame the User

Empty States Are Opportunities

Voice vs Tone

Writing for Accessibility

Link Text

Alt Text

Icon Buttons

Writing for Translation

Plan for Expansion

Translation-Friendly Patterns

Consistency: The Terminology Problem

Avoid Redundant Copy

Loading States

Confirmation Dialogs: Use Sparingly

Form Instructions

Guidelines

DO

DON’T