| name | better-writing |
| description | UX writing and interface copy, from voice and button labels to error messages and empty states. Use when writing or reviewing any user-facing text: button and link labels, form errors, placeholders, settings labels, onboarding flows, notifications, or empty states. Triggers on UX writing, microcopy, interface copy, product copy, copywriting, button labels, link text, error messages, empty states, placeholder text, settings labels, capitalization, title case, sentence case, voice and tone. |
Writing that disappears into the interface
Clear and brief beats clever, consistency beats variety, and the best error message is the interaction redesigned so the error can't happen. Apply these principles when writing or reviewing any user-facing text.
How copy renders (capitalization via text-transform, truncation, smart punctuation) is covered by the better-typography skill; error markup and announcements (aria-invalid, live regions) by the better-accessibility skill; room for translated strings by the better-layout skill.
Core Principles
1. One Voice, Flexible Tone
The product has one voice: plain, direct, consistent terms for the same things. Keep a shared term list so the same action never has two names: if it's "Archive" in the menu, it isn't "Move to storage" in the toast. Tone flexes with the stakes:
| Context | Tone |
|---|
| Success, onboarding, empty states | Warm, can be light |
| Routine actions, settings | Neutral, minimal |
| Errors, destructive confirmations | Calm, plain, zero playfulness |
| Data loss, security | Serious, explicit |
2. Say "You", Never "The User"
Address the reader directly as "you". Avoid "we": it's ambiguous, and in errors it reads as deflection. "Unable to load content", not "We're having trouble loading this content". Use possessives sparingly ("Favorites" over "Your Favorites") and never switch perspective mid-app.
3. Plain Words Over Clever Ones
Choose easily understood words and delete every word that isn't needed. No idioms, colloquialisms, or humor that won't translate. Skip unnecessary gender: "Subscribers can post recipes", not "each subscriber can post his or her recipes". Match the input device: "tap" on touch, "click" with a pointer, "select" when both are possible. Never build sentences by concatenating fragments around variables ("You have " + n + " new messages"); word order changes per language, so use full templated strings with proper pluralization.
4. Verb-First Buttons
Button labels start with a verb naming the specific action: "Send", "Save draft", "Delete project". Never "OK!", "Let's go!", or bare "Yes"/"No" on consequential actions. Confirmation buttons repeat the consequence so the dialog is answerable without reading the body: "Delete this project?" offers Delete project and Cancel, not Yes and No.
5. Consistent Flow Vocabulary
Multi-step flows use one vocabulary: "Get Started" to enter, "Continue" or "Next" (pick one) to advance, "Done" to finish. Alternating synonyms across steps makes users wonder if the buttons do different things.
6. Links Describe Their Destination
Link text makes sense out of context; screen-reader users navigate by a list of the page's links. "Read the billing docs", never "Click here" (which also fails the device-verb rule on touch), and never a bare "Learn more" when several appear on one page. Suffix each: "Learn more about exports".
7. One Capitalization Policy
Pick title case or sentence case per element type (all buttons, all headings) and apply it consistently; sentence case is the safer default: calmer, no per-word case rules, localizes cleanly. "Save Changes" beside "Discard changes" reads as sloppiness.
8. Settings Describe the ON State
Label a toggle for what happens when it's on: "Send read receipts", and users infer the off state. Never label the negative ("Don't send read receipts"), which turns the toggle into a double negative. Link directly to a referenced setting instead of describing the path to it: a "Notification settings" link, not "Go to Settings > Notifications > Email".
9. Errors Say How to Fix, Next to Where It Broke
An error is an instruction, adjacent to the failing field:
| Bad | Good |
|---|
| That password is too short | Choose a password with at least 8 characters |
| Invalid name | Use only letters for your name |
| Oops! Something went wrong. | Unable to save. Check your connection and try again. |
No blame, no "oops", no exclamation marks. Phrase hints positively ("Use only letters", not "Don't use numbers or symbols") and show them before the mistake, not after. If the same error keeps firing for many users, redesign the interaction instead of rewording it.
10. Empty States Point Forward
An empty state says what this place is and how to fill it, with one clear next action:
<p>No results.</p>
<p class="font-medium">No projects yet</p>
<p class="text-sm text-zinc-500">Projects keep your tasks and files together.</p>
<button class="mt-4">Create a project</button>
Search and filter empty states name the query and offer an exit: "No results for 'quarterly'. Clear filters". Never park crucial persistent information in an empty state; it disappears the moment content exists.
11. Placeholders Are Examples, Not Labels
Placeholders show the expected format (name@example.com, DD/MM/YYYY). A placeholder is never the field's only label: it vanishes on input, and every field keeps a visible label.
Common Mistakes
| Mistake | Fix |
|---|
| "The user" in interface copy | Address the reader as "you" |
| "We're having trouble…" in an error | Drop the "we": "Unable to load content" |
OK / Yes confirming a destructive dialog | Repeat the consequence: "Delete project" |
| "Continue" on step 2, "Next" on step 3 | One flow vocabulary throughout |
| "Click here" or bare "Learn more" link | Describe the destination: "Read the billing docs" |
| "Save Changes" beside "Discard changes" | One capitalization policy per element type |
| "Don't send read receipts" toggle | Label the ON state: "Send read receipts" |
| "Oops! Something went wrong." | Say what to do, next to the failing field |
| "No results." as the whole empty state | Orient and point forward with a next action |
| Placeholder doing the label's job | Visible label; placeholder shows the format |
"You have " + n + " messages" | Full templated strings with pluralization |
Review Output Format
Present every review in two parts.
Findings
Group findings by principle. Use a markdown table with Severity, Location, Before, After, and Why columns. Include every change made or proposed, not a subset. Never use separate "Before:" / "After:" lines.
- Severity:
HIGH misleads users, obscures a consequence, or prevents recovery; MEDIUM makes a task harder to understand; LOW is isolated voice or consistency polish.
- Location: cite
path/to/file:line. If the artifact has no source files, cite the exact screen and component instead.
- Before / After: quote the current copy and its complete replacement.
- Why: name the violated principle and explain the comprehension or trust cost.
Consolidate a repeated systemic issue into one row and list every affected location. Omit principles with no findings.
Example
Errors say how to fix
| Severity | Location | Before | After | Why |
|---|
| MEDIUM | src/PasswordField.tsx:36 | "Invalid password" | "Choose a password with at least 8 characters" | The error must say how to fix the problem |
| HIGH | src/Editor.tsx:81 | "We couldn't process your request" toast | Inline "Unable to save. Check your connection and try again." | The current message neither locates the failure nor offers recovery |
Verb-first buttons
| Severity | Location | Before | After | Why |
|---|
| HIGH | src/DeleteDialog.tsx:29 | "OK" on the delete confirmation | "Delete project" | A consequential action must repeat the consequence |
| MEDIUM | src/Signup.tsx:54 | "Let's go!" | "Create account" | The label must name the action |
Verification and Verdict
After the findings:
- Verification: list the exact checks run and their observed results, including the complete flow, variable interpolation, pluralization, and narrow-width wrapping when applicable. If a check was not run, state what still needs verification.
- Verdict:
Block if any HIGH finding remains, Needs changes if only MEDIUM or LOW findings remain, and Approve only when no actionable findings remain.
When there are no findings, omit the tables, state "No actionable writing findings", report verification, and end with Approve.
