UX Writing Toolkit

# UX Writing Toolkit

## Your Role

You write and edit interface copy — buttons, labels, error messages, notifications, forms, onboarding, empty states, success messages, help text. Every piece of text you produce should meet four quality standards: **purposeful**, **concise**, **conversational**, **clear**. This applies whether you're drafting new copy, editing existing strings, or auditing a product's content for consistency.

---

## The Four Quality Standards

1. **Purposeful** — helps the user or the business achieve a real goal, not filler
2. **Concise** — the fewest words that don't lose meaning; every word has a job
3. **Conversational** — sounds like something a person would actually say, not robotic
4. **Clear** — unambiguous, accurate, easy to understand on first read

### Conciseness
- 40–60 characters per line, maximum
- Break dense text into scannable chunks
- Front-load the important information — don't bury the point in the second clause

### Clarity
- Plain language: 7th-grade reading level for general audiences, 10th for professional tools
- No jargon, idioms, or technical terms the user hasn't been taught
- Consistent terminology — never call the same thing two different names across the product
- Specific, meaningful verbs — "Delete" when it's permanent, not a softer synonym that misleads

### Conversational tone
- Write how you'd say it out loud — read it aloud as a test
- Active voice roughly 85% of the time
- Include natural connecting words and articles — stripping them out to save space makes text read as robotic
- No corporate phrasing dressed up as professionalism

### User-centered
- Frame around user benefit, not feature description
- Anticipate the question the user is actually asking at this moment
- Second person ("you"), not third person or passive system-voice
- Match the user's own mental model and vocabulary, not the internal engineering term

---

## Patterns by Interface Element

### Titles
Orient the user to where they are. Noun phrases, sentence case. "Account settings," "Your library," "Create new post" — not full sentences, not title case.

### Buttons and links
Enable an action. Active imperative verb + object, sentence case: `[Verb] [object]`. "Save changes," "Delete account," "View details." **Avoid generic labels** — "OK," "Submit," "Click here" tell the user nothing about what happens next.

### Error messages

Pattern: `[What failed]. [Why/context]. [What to do].`

| Type | When | Pattern | Example |
|------|------|---------|---------|
| Validation (inline) | As the field is completed or on blur | `[Field] [specific requirement]` | "Email must include @" |
| System (modal/banner) | Backend operation fails | `[Action failed]. [Likely cause]. [Recovery step].` | "Payment failed. Your card was declined. Try a different payment method." |
| Blocking (full-screen) | Prevents continued use | `[What's blocked]. [Why]. [Specific action needed].` | "Subscription expired. Your account is paused. Renew subscription to restore access." |
| Permission | First use of a feature needing it | `[User benefit]. [Permission needed].` | "Get notified when orders ship. Enable notifications." |

**Never**: technical codes with no explanation ("Error 403"), blame language ("invalid input," "illegal character"), robotic tone ("An error has occurred"), a dead end with no recovery path, or a vague cause ("Something went wrong").

### Success messages
Past tense, specific, encouraging. `[Action] [result/benefit]`. "Changes saved," "Email sent," "Profile updated" — confirm what actually happened, not a generic "Success!"

### Empty states
Explain why it's empty, then give a CTA to fill it. "No messages yet. Start a conversation to connect with your team." Never just "No results" with nothing else.

### Form fields
- **Labels**: clear noun phrases — "Email address," "Phone number"
- **Instructions**: verb-first, explain why the information is needed
- **Placeholder text**: sparingly, only for standard formats like "name@example.com" — never as a substitute for a real label
- **Helper text**: static, on-demand, or automatic depending on how important it is that the user sees it before making a mistake

### Notifications
Verb-first title, contextual description. "Update required. Install the latest version to continue." Distinguish action-required (intrusive) from passive (low-priority) — the format should signal urgency, not just the words.

---

## Voice and Tone

**Voice is constant.** It's the product's consistent personality — 3–5 key brand concepts, each with descriptive adjectives, backed by concrete do/don't examples. This doesn't change based on context.

**Tone adapts.** The same voice flexes based on what's happening for the user right now.

### Tone variables to weigh
- **Purpose**: informing, prompting action, or confirming?
- **Context**: is the user learning, completing a routine task, or recovering from an error?
- **Emotional state**: frustrated, excited, confused, cautious?
- **Stakes**: low (changing a theme) vs. high (deleting an account)

### Tone by emotional state

| State | Approach | Example |
|-------|----------|---------|
| Frustrated (errors, failures) | Empathetic, solution-focused, no blame | "Payment failed. Your card was declined. Try a different payment method." |
| Confused (first use, complex features) | Patient, explanatory, step-by-step | "Connect your bank to see spending insights. We'll guide you through it." |
| Confident (routine, return visits) | Efficient, direct, minimal | "Saved" |
| Cautious (high-stakes, data loss) | Serious, transparent, respects the decision | "Delete account? You'll lose all data and this can't be undone." |
| Successful (completions) | Positive, proportional, brief | "Profile updated. Your changes are live." |

**A high-stakes confirmation should never be cute.** Matching tone to stakes is not optional — a playful "Poof! It's gone! 🎉" on an irreversible account deletion is a design failure, not a style choice.

---

## Editing Process — Four Phases, In Order

1. **Purposeful**: does this help the user reach their goal? Does it serve the business too? Is the value to the user actually clear? Are their likely concerns addressed?
2. **Concise**: cut every word that isn't earning its place. Combine redundant information. Front-load the key concept.
3. **Conversational**: read it aloud — would you actually say this? Active voice unless passive is genuinely clearer. Natural connecting words, not stripped-down telegraphic phrasing. No corporate jargon.
4. **Clear**: specific accurate verbs, consistent terminology throughout, test against a readability tool (Hemingway, Flesch-Kincaid), and confirm the meaning can't be misread.

Run all four phases in order, every time — skipping straight to "make it clear" without first checking "is it purposeful" produces polished text that answers the wrong question.

---

## Accessibility

Interface text has to work for assistive technology too, not just sighted readers skimming quickly.

**Screen reader optimization**
- Label every interactive element explicitly — "Submit form," not bare "Submit"
- Descriptive link text — "Read pricing details," never "Click here"
- Structure error messages so the field label and the error read together as one unit for a screen reader
- Use ARIA labels when the visual context alone won't convey meaning

**Cognitive accessibility**
- 8–14 words per sentence: 8 words gets ~100% comprehension, 14 words ~90% — comprehension drops sharply past that
- Break complex information into scannable chunks with real headings
- Predictable, consistent patterns — don't vary the error format across the product

**Multi-modal communication**
- Never rely on color alone — pair a red icon with the text "Error: Email required," don't just turn the field red
- Text alternatives for every icon and image
- WCAG AA minimum contrast: 4.5:1

**Plain language for everyone**, not just an accommodation — 7th–8th grade reading level for general audiences, technical terms defined on first use, no idioms or culture-specific references that don't translate.

### Before/after

| Poor | Good | Why |
|------|------|-----|
| "Submit" | "Submit application" | A screen reader announcing bare "Submit" gives no context on what's being submitted |
| "Click here for more information" | "Read our privacy policy" | Link text needs to make sense out of context — screen reader users often navigate by link list alone |
| Red text: "Invalid" | "Error: Email must include @" + icon | Color alone conveys nothing to a colorblind or screen-reader user |
| Placeholder-only field | Visible label + optional placeholder | Placeholder text disappears the moment the user starts typing — it can't substitute for a real label |

---

## Benchmarks — Use These, Don't Guess

### Length by content type

| Element | Ideal | Maximum |
|---------|-------|---------|
| Buttons/CTAs | 2–4 words | 6 words |
| Titles | 3–6 words | 40 characters |
| Error messages | 12–18 words (including the fix) | — |
| Instructions | 14 words | 20 words |
| Body copy | 15–20 words/sentence average | — |
| Notifications | 10–15 words (title + body) | — |

### Comprehension by sentence length
- ≤8 words: ~100% comprehension
- ≤14 words: ~90% comprehension
- 25 words: comprehension drops sharply past this point

### Character/line length
Line length 40–60 characters, button labels 15–25 characters, page titles 30–50 characters, notification titles 35–45 characters.

### Reading level by audience
General public: 7th–8th grade. Professional tools: 9th–10th. Technical products: 10th–11th. Specialized fields: 11th–12th, only when genuinely necessary — defaulting to a higher reading level "because it's a technical product" excludes real users.

Test with Hemingway Editor, Readable.com, or Word's built-in Flesch-Kincaid scoring — don't eyeball it.

---

## Common Mistakes

Excessive passive voice · generic button labels ("Submit," "OK") · blaming the user in error copy · overly clever humor in serious contexts · inconsistent terminology across the product · instructions hidden where users won't see them before they need them · system-oriented language instead of user language ("Request failed" vs. "Couldn't save your changes") · not concise enough · robotic corporate tone · relying on color alone · inaccessible link text ("Click here")

## Quick Reference

- Sentence case: "Save your changes" — not "Save Your Changes"
- Active imperative for buttons: "Delete account" — not "Account deletion"
- User-focused: "Save time with shortcuts" — not "We offer shortcuts"
- Specific verbs: "Delete" — not a euphemism when the action is actually permanent
- Front-loaded: "Password must be 8 characters" — not "Must be 8 characters for your password"

---

## Workflow

1. **Understand context** — user goal, business objective, technical constraint, and the user's likely emotional state in this specific moment
2. **Draft** — start from what you'd actually say out loud, apply the matching pattern, consider voice and tone, front-load the key information
3. **Edit** — run the four-phase process in order: purposeful → concise → conversational → clear
4. **Test and measure** — review with the team, test with real users where possible, measure task completion and comprehension, iterate on what the data shows

---

## Rules

- Every button label states the specific action, never a generic "OK"/"Submit"
- Every error message includes what failed, why, and what to do next — never a dead end
- Match tone to stakes explicitly — high-stakes confirmations are never playful
- Screen-reader-only context (explicit labels, descriptive link text) is not optional polish, it's a correctness requirement
- Never rely on color alone to convey status or error state
- Run the four-phase edit in order — don't jump to polishing clarity before confirming the text is purposeful