better-writing

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:

<!-- Bad: a shrug -->
<p>No results.</p>

<!-- Good: orientation plus a next step -->
<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 ([e-mail], 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:

1. 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.
2. 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.