Ux Writing

---
name: ux-writing
description: >-
  UX writing and interface copy — voice and tone, button and link labels, error messages, settings labels, empty states, placeholders. INVOKE PROACTIVELY when writing or reviewing any user-facing interface text — even when nobody says "copy" or "microcopy". How copy renders: [[typography]]; error markup and announcements: [[accessibility]]; prose meant to rank in search: [[seo]]; whole-screen audits: [[interface-review]].
---

# 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 [[typography]]; error markup and announcements (`aria-invalid`, live regions) by [[accessibility]]; room for translated strings by [[layout]]. This skill owns interface copy — the words a user reads while operating the product. Prose written to rank in search (articles, landing pages, documentation) belongs to [[seo]] instead.

## Core Principles

### 1. Recon the Existing Voice

Before writing or reviewing, inspect nearby interface copy, the product's terminology, localization conventions, and any voice or content style guide. Preserve intentional brand character when it remains clear and appropriate to the stakes. Treat a difference from generic plain language as a finding only when it creates inconsistency, ambiguity, translation risk, or an inappropriate tone.

### 2. One Voice, Flexible Tone

The product has one voice, established by its existing system rather than invented during a local edit. Keep terms consistent: 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 |

### 3. Address the Reader Directly

In instructional interface copy, address the reader directly as "you" rather than "the user." Avoid “we” in errors when it creates ambiguity or reads as deflection: prefer “Unable to load content” over “We're having trouble loading this content.” Preserve an established first-person brand voice in low-stakes contexts when it remains clear. Use possessives sparingly (“Favorites” over “Your Favorites”) and never switch perspective accidentally.

### 4. 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.

### 5. 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`.

### 6. 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.

### 7. 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".

### 8. 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.

### 9. 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".

### 10. 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.

### 11. Empty States Point Forward

An empty state says what this place is and how to fill it, with one clear next action:

```html
<!-- 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.

### 12. 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 |
| --- | --- |
| Local rewrite ignores the product's established terminology or voice | Inspect nearby copy and the style guide before proposing a change |
| "The user" in instructional interface copy | Address the reader directly as "you" |
| "We're having trouble…" obscures responsibility or recovery | Use a direct status and next step: "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

Use this format only when the user asks for a standalone writing review. When [[interface-review]] orchestrates the review, provide domain evidence and findings to that skill and let its output format, severity scale, consolidation rules, cap, and verdict take precedence.

Report all confirmed findings as one markdown table ordered by severity — `| Severity | Location | Before | After | Why |`, never separate "Before:" / "After:" lines. **Location** cites `path/to/file:line` (or the exact screen and component when there are no source files); **Before / After** quote the current copy and its complete, shippable replacement — never directional advice; **Why** names the violated principle and its impact. Consolidate a repeated systemic issue into one row listing every affected location. **Severity**: `HIGH` misleads users, obscures a consequence, or prevents recovery; `MEDIUM` makes a task harder to understand; `LOW` is isolated voice or consistency polish.

After the findings: **Verification** — list the exact checks run and their observed results (the complete flow, variable interpolation, pluralization, narrow-width wrapping when applicable), and name any check not run. Then **Verdict**: `Block` if any `HIGH` finding remains, `Needs changes` if only `MEDIUM` or `LOW` findings remain, `Approve` only when no actionable findings remain. When there are no findings, omit the table, state "No actionable writing findings", report verification, and end with `Approve`.