Better Writing

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.

Adapted from Jakub Krehel's better-writing at commit a67333399dabbc71d7778962cb9c4fb9b86a00d0.

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. 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:

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:

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:

<!-- 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

Review Output Format

Use this format only when the user asks for a standalone writing review. When studio-audit 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.

Present the standalone review in two parts.

Findings

Group all confirmed findings by principle. Use a markdown table with Severity, Location, Before, After, and Why columns. 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

Verb-first buttons

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.