Better Writing

--- name: better-writing description: Writes and reviews your interface copy, from labels and errors to empty states and confirmations, so it matches your product's voice and tells people what to do next. --- # Writing This skill writes and reviews interface copy such as labels, errors, empty states and confirmations, along with the terms that run through them. It matches the product's existing voice and flags copy that misleads people or leaves them without a way forward. A deliberate brand voice is not a defect. Raise a departure from plain language only when it creates inconsistency, ambiguity, translation risk or a tone the stakes don't support. Rewording that merely suits your taste is not a finding. How copy renders, including `text-transform`, truncation and smart punctuation, belongs to `better-typography`. Error markup, announcements and the attributes that carry accessible names belong to `better-accessibility`. Room for translated strings belongs to `better-layout`. ## Inventory the existing strings first Before writing or reviewing, find where the copy lives and read the copy around the change: 1. Search for the translation call (`t(`, `i18n.`, ` Notifications > Email". ## Errors say how to fix, next to where it broke An error is an instruction, and it belongs beside the field that failed: | Bad | Good | | --- | --- | | That password is too short | Choose a password with at least 8 characters | | Invalid date | Enter a date as DD/MM/YYYY | | Oops! Something went wrong. | Unable to save. Check your connection and try again. | No blame, no "oops" and no exclamation marks. Phrase hints positively, as in "Use at least 8 characters" rather than "Don't use fewer than 8". Show a known requirement as helper text before input, not only in the error. When the same error keeps firing, redesign the interaction so it cannot happen. ## Undo beats confirmation Prefer undo when the action can be reversed and people perform it often, such as archiving, moving or deleting into a trash. Act at once and offer undo in the result: "Project archived. Undo". Confirm before acting when the action cannot be reversed, affects other people or destroys many items at once. The confirmation repeats the consequence, so the dialog is answerable without reading the body: - The title names the action and the object, "Delete 'Q3 report'?", never "Are you sure?". - The body says what is lost and what cannot be recovered, with counts where they apply. - The buttons are verb plus object, `Delete project` and `Cancel`, never `Yes` and `No`. - For an account, a workspace or a repository, ask the person to type the object's name. Templates are in [patterns.md](patterns.md#destructive-flows). The destructive button's distinct color is `better-colors`'. ## Empty states point forward An empty state says what this place is and how to fill it, and offers one clear next action: ```html

No results.

No projects yet

Projects keep your tasks and files together.

Create a project ``` A filtered empty state names the query and offers an exit: "No results for 'quarterly'. Clear filters". Never park persistent information in an empty state. It disappears the moment content exists. Loading, saving and success copy is in [patterns.md](patterns.md#status-copy). ## Placeholders show an example A placeholder shows a realistic example in the format the field accepts, `[email protected]` or `DD/MM/YYYY`, never an instruction. Whether the field also needs a visible label is `better-accessibility`'s. ## Before you finish | Detection pattern | Fix | | --- | --- | | `Click here`, a link reading `here` or two identical `Learn more` links | Name the destination | | `Oops`, `Something went wrong` or `!` in an error string | Say what failed and the next step | | `" + n + "`, a template literal holding a sentence fragment, or `=== 1 ? "" : "s"` | One ICU message with a plural argument | | `>OK<`, `>Yes<` or `>No<` on a dialog button | Verb plus object | | `Are you sure` | Name the action and the object | | `successfully` | Cut it: "Changes saved" | | `Please` in a routine instruction | Cut it | | A toggle label starting `Don't`, `Disable` or `Hide` | Describe the ON state | | `aria-label="Trash"`, `"Close icon"` or `"X"` | Name the action: "Delete project", "Close dialog" | | `toLocaleDateString()` with no locale, or a date built from `getMonth()` | `Intl.DateTimeFormat` with the user's locale | | `Save Changes` beside `Discard changes` | One case per element type | ## Reporting **Severity.** `HIGH` misleads the user or hides how to recover from an error. An error that names no way to recover is always `HIGH`, as is a destructive action with neither confirmation nor undo. `MEDIUM` breaks voice, terminology or capitalization consistency. `LOW` is isolated wording polish. **Verification.** Check every label against the action it invokes, every error for a stated fix and every term against the inventory. Read locale files as well as components. Report strings supplied by the server or a CMS that you could not see as `Not verified`. **Format.** Group findings under the principle each violates, ordered by severity, one row per root cause listing every location it appears in: | Severity | Location | Before | After | Why | | --- | --- | --- | --- | --- | `Location` is `path/to/file:line`. `Why` names the principle and the user impact. End with `Block` when any `HIGH` remains, `Approve` otherwise, leaving the rest in the table as work to do. Never `Approve` coverage you did not inspect. With nothing to report, state "No actionable writing findings" and report verification.