1# UX Writing
2 
3## The Button Label Problem
4 
5**Never use "OK", "Submit", or "Yes/No".** These are lazy and ambiguous. Use specific verb + object patterns:
6 
7| Bad | Good | Why |
8|-----|------|-----|
9| OK | Save changes | Says what will happen |
10| Submit | Create account | Outcome-focused |
11| Yes | Delete message | Confirms the action |
12| Cancel | Keep editing | Clarifies what "cancel" means |
13| Click here | Download PDF | Describes the destination |
14 
15**For destructive actions**, name the destruction:
16- "Delete" not "Remove" (delete is permanent, remove implies recoverable)
17- "Delete 5 items" not "Delete selected" (show the count)
18 
19## Error Messages: The Formula
20 
21Every error message should answer: (1) What happened? (2) Why? (3) How to fix it? Example: "Email address isn't valid. Please include an @ symbol." not "Invalid input".
22 
23### Error Message Templates
24 
25| Situation | Template |
26|-----------|----------|
27| **Format error** | "[Field] needs to be [format]. Example: [example]" |
28| **Missing required** | "Please enter [what's missing]" |
29| **Permission denied** | "You don't have access to [thing]. [What to do instead]" |
30| **Network error** | "We couldn't reach [thing]. Check your connection and [action]." |
31| **Server error** | "Something went wrong on our end. We're looking into it. [Alternative action]" |
32 
33### Don't Blame the User
34 
35Reframe errors: "Please enter a date in MM/DD/YYYY format" not "You entered an invalid date".
36 
37## Empty States Are Opportunities
38 
39Empty states are onboarding moments: (1) Acknowledge briefly, (2) Explain the value of filling it, (3) Provide a clear action. "No projects yet. Create your first one to get started." not just "No items".
40 
41## Voice vs Tone
42 
43**Voice** is your brand's personality, consistent everywhere.
44**Tone** adapts to the moment.
45 
46| Moment | Tone Shift |
47|--------|------------|
48| Success | Celebratory, brief: "Done! Your changes are live." |
49| Error | Empathetic, helpful: "That didn't work. Here's what to try..." |
50| Loading | Reassuring: "Saving your work..." |
51| Destructive confirm | Serious, clear: "Delete this project? This can't be undone." |
52 
53**Never use humor for errors.** Users are already frustrated. Be helpful, not cute.
54 
55## Writing for Accessibility
56 
57**Link text** must have standalone meaning: "View pricing plans" not "Click here". **Alt text** describes information, not the image: "Revenue increased 40% in Q4" not "Chart". Use `alt=""` for decorative images. **Icon buttons** need `aria-label` for screen reader context.
58 
59## Writing for Translation
60 
61### Plan for Expansion
62 
63German text is ~30% longer than English. Allocate space:
64 
65| Language | Expansion |
66|----------|-----------|
67| German | +30% |
68| French | +20% |
69| Finnish | +30-40% |
70| Chinese | -30% (fewer chars, but same width) |
71 
72### Translation-Friendly Patterns
73 
74Keep numbers separate ("New messages: 3" not "You have 3 new messages"). Use full sentences as single strings (word order varies by language). Avoid abbreviations ("5 minutes ago" not "5 mins ago"). Give translators context about where strings appear.
75 
76## Consistency: The Terminology Problem
77 
78Pick one term and stick with it:
79 
80| Inconsistent | Consistent |
81|--------------|------------|
82| Delete / Remove / Trash | Delete |
83| Settings / Preferences / Options | Settings |
84| Sign in / Log in / Enter | Sign in |
85| Create / Add / New | Create |
86 
87Build a terminology glossary and enforce it. Variety creates confusion.
88 
89## Avoid Redundant Copy
90 
91If the heading explains it, the intro is redundant. If the button is clear, don't explain it again. Say it once, say it well.
92 
93## Loading States
94 
95Be specific: "Saving your draft..." not "Loading...". For long waits, set expectations ("This usually takes 30 seconds") or show progress.
96 
97## Confirmation Dialogs: Use Sparingly
98 
99Most confirmation dialogs are design failures; consider undo instead. When you must confirm: name the action, explain consequences, use specific button labels ("Delete project" / "Keep project", not "Yes" / "No").
100 
101## Form Instructions
102 
103Show format with placeholders, not instructions. For non-obvious fields, explain why you're asking.
104 
105---
106 
107**Avoid**: Jargon without explanation. Blaming users ("You made an error" → "This field is required"). Vague errors ("Something went wrong"). Varying terminology for variety. Humor for errors.
108