Ux Writing

UX writing

Interface copy is read mid-task by someone who did not come to read. Every word is either doing work — naming an outcome, removing a doubt, offering the next move — or it is in the way.

When this fires

A screen's strings are being written, reviewed or translated; an error, empty state or confirmation is unclear; a control's label does not match what it does. It does not fire for prose the user chose to read: docs, marketing pages, release notes.

Procedure

1. Collect the actual strings. Grep the component, route or feature for every user-visible

string, including the ones not on screen right now — error branches, empty results, disabled reasons, toast text. Copy you never saw is copy you never fixed.

1. Name the reader and the moment. What were they doing one action ago, what do they already

know, and what do they need to decide next. Write to that person, not to a persona.

1. Fix labels first. A label names the outcome in the reader's words, not the mechanism in

yours: "Save changes", not "Submit"; "Delete project", not "Confirm". Avoid Yes/No button pairs — a button that repeats the verb can be answered without re-reading the question.

1. Rewrite errors to be actionable. Say what happened, why when you actually know, and what

the reader can do. Never blame the reader, never show a raw exception or bare status code as the whole message, and keep any support-quotable identifier alongside plain words rather than instead of them. Do not promise a retry, a saved draft or a notification that the code does not perform.

1. Separate the three empty states. Nothing yet (say what will appear here and give one way

to start), filtered to nothing (name the filter and offer to clear it), and failed to load (that is an error, not an empty state — do not let it read as "you have none").

1. Make confirmations specific. State the object by name, state the consequence, and repeat

the verb on the primary button. For anything destructive, say what is lost and whether it can be undone — if the code has no undo, the copy must not imply one. When the copy and the code disagree about reversibility, stop and raise it; do not paper over it with softer wording.

1. Cut the words carrying no information. Padding ("please", "simply", "just"), fake cheer

("Oops!"), exclamation marks, and restating the screen's own title. Then check the result still sounds like the rest of the product — consistency beats each string being individually clever.

1. Check every string against what the code does. A label that describes behaviour the

function does not have is a bug report, not a copy edit. Report it as a bug.

1. Check the string survives contact with reality. Longest plausible value, truncation,

sentence-case consistency with neighbours, and an accessible name for every icon-only control. If the product is localized, note that changed strings need re-translation and that other languages run longer.

Checklist

• [ ] Every user-visible string in the changed surface was listed, including unrendered branches
• [ ] Buttons name outcomes; no ambiguous Yes/No pair
• [ ] Each error says what happened and what to do, with no raw exception as the message
• [ ] Empty, filtered-empty and failed-to-load are distinguishable
• [ ] Destructive confirmations name the object and state reversibility truthfully
• [ ] Copy matches actual code behaviour; mismatches reported, not smoothed over
• [ ] Icon-only controls have accessible names
• [ ] Translation and length impact noted where it applies

Failure handling

• The right words depend on behaviour you cannot determine — read the handler. If it is still

ambiguous, write the copy that is true of both branches and flag the question rather than inventing the more reassuring version.

• Legal, consent, pricing, security or privacy wording — propose, do not replace. These are

approved text somewhere; stop and ask before changing them.

• The string is a translation key or appears in many places — check every use before editing.

A label reworded for one screen can be wrong on three others.

• The real problem is the flow, not the sentence — say so. Copy that has to apologize for an

interaction is a design finding; writing around it hides the defect.

Evidence to report

The before and after of each changed string, with the file and the state it appears in; the mismatches you found between copy and code; the strings you deliberately left alone and why; and anything that needs approval or re-translation. "Improved the microcopy" with no strings quoted is not evidence.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nahid-sparktales
• Source: nahid-sparktales/agent-dispatcher
• License: MIT

Install and usage instructions live in the source repository linked above.