UX Microcopy skill for Claude Code

Microcopy is done when every label says exactly what will happen, every message tells users what to do next, the same thing has the same name everywhere, and the strings survive translation and screen readers. Clever copy that makes users pause is a defect.

Ground rules

• Clear before clever. Delight only where nothing is at stake (empty states, success), never in errors, billing, security, or destructive actions.
• Name actions with a verb + object: “Delete project”, “Send invoice”. Never “OK”, “Submit”, “Yes” for anything consequential.
• Use the user’s words, not internal ones (from support tickets, search logs, interviews).
• Front-load: the most important word first. “Payment failed: card expired” not “We’re sorry, but unfortunately there was an issue processing…”.
• Sentence case for all UI text (buttons, titles, menus) unless the design system says otherwise. Title Case Everywhere Slows Reading.
• One term per concept, enforced by a glossary.

Workflow

- [ ] 1. Inventory strings (i18n files or grep) and the flows they appear in
- [ ] 2. Build or update the terminology glossary
- [ ] 3. Rewrite by component pattern (below)
- [ ] 4. Check length, i18n, and accessibility
- [ ] 5. Review in context (screenshots or running app), not in a spreadsheet only

1. Inventory

# common i18n locations
ls src/locales/ public/locales/ messages/ 2>/dev/null
# hard-coded strings in JSX (rough)
grep -rnoE '>[A-Z][a-z]+[^<{]{3,}<' src --include='*.tsx' | head -50
# inconsistent terms
grep -rhoiE '\b(remove|delete|archive|trash)\b' src/locales/en*.json | sort | uniq -c

2. Glossary (decide once)

| Use | Don't use | Meaning |
|---|---|---|
| workspace | org, team, account | Top-level container a customer pays for |
| delete | remove, trash | Permanent; requires confirmation |
| archive | hide, deactivate | Reversible; restorable from Archived |
| sign in / sign out | log in, login (as verb) | Session actions |
| member | user, seat (in UI) | Person in a workspace |

Patterns by component

Buttons and links

Before	After	Why
OK	Save changes	Says what happens
Submit	Create account	Names the outcome
Yes / No (in a dialog)	Delete 3 files / Cancel	Buttons readable without the question
Click here	Download the invoice (PDF, 120 KB)	Link text works out of context (screen readers list links)
Learn more	Learn how billing works	Specific destination

• Primary button 1–3 words; up to ~25 characters before translation.
• Keep the label stable across the flow: if the page CTA says “Start free trial”, the form button says “Start free trial”, not “Continue”.

Form labels, hints, placeholders

• Label always visible; placeholder is an example, never the label.
• Hint text states format or constraints before the user errs: “8+ characters, including a number.”
• Mark optional fields “(optional)” rather than starring required ones when most are required.

Error messages: what happened + why + how to fix

Before	After
“Invalid input.”	“Enter a date in the future.”
“Error 403.”	“You need admin access to change billing. Ask a workspace admin.”
“Password does not meet requirements.”	“Add at least one number to your password.”
“Oops! Something went wrong :(”	“We couldn’t save your changes. Check your connection and try again.”
“You entered an invalid email.”	“Enter an email like [email protected].” (no blame)
“Upload failed.”	“This file is 32 MB. The limit is 25 MB. Compress it or upload a smaller file.”

• Place the message next to the field; summarize at the top for long forms.
• Never blame (“you failed to”), never joke, never expose stack traces; include a reference ID for support on server errors.

Confirmation dialogs (destructive actions)

Title:   Delete "Q3 Forecast"?
Body:    This permanently deletes the project and its 24 files for everyone in the
         workspace. You can't undo this.
Buttons: [Cancel]  [Delete project]   ← destructive style, named action

• Title is a question naming the action and the object.
• Body states consequences specifically (what, who is affected, reversibility).
• Prefer undo over confirmation for reversible actions: “Project archived. [Undo]”.

Empty states

Type	Example
First use	“No invoices yet. Create your first invoice or import from CSV.”
No results	“No results for ‘acme’ in Paid invoices. Try All statuses or check the spelling.”
Cleared	“You’re all caught up.” (with next step if one exists)

See empty-error-states for layout and states.

Success and notifications

• Confirm the specific result: “Invoice sent to [email protected]” not “Success!”.
• Toasts ≤ ~80 characters; include Undo or View when useful; no toasts for actions whose result is already visible.
• Notification emails/pushes: lead with the change and who caused it: “Marco commented on Q3 Forecast”.

Loading and progress

• Short waits: no text. Long waits: say what is happening and how long: “Importing 1,240 contacts. About 2 minutes. You can leave this page.”

Tooltips

• Tooltips explain; they do not label. If an icon needs a tooltip to be understood, it probably needs a visible label.
• ≤ 1–2 short sentences; never put essential information only in a tooltip (not reachable on touch, easy to miss).

Voice and tone

Voice stays constant; tone shifts with the user’s state.

Context	Tone	Example
Onboarding, success	Warm, brief	“Your workspace is ready.”
Routine UI	Neutral, efficient	“Save changes”
Errors	Calm, direct, helpful	“We couldn’t connect to your bank. Try again in a few minutes.”
Destructive, security, billing	Precise, serious	“This permanently deletes all data for 12 members.”

Avoid: “Oops”, “Uh-oh”, exclamation marks in errors, “simply/just/easy”, “please” in every sentence, double negatives, Latin abbreviations (e.g., i.e.) in UI.

Internationalization and accessibility

• Never concatenate strings ("Delete " + name + "?"); use full messages with placeholders and ICU plurals:

{ "files.deleteConfirm": "{count, plural, one {Delete # file?} other {Delete # files?}}" }

• Leave room for 30–40% expansion (German, Finnish); avoid fixed-width buttons.
• Avoid idioms and wordplay that do not translate.
• Give translators context: a description per key with where it appears and max length.
• Screen readers: icon-only buttons need an aria-label written like a button label; status messages go in a live region; link text must make sense alone.
• Numbers, dates, and currencies through Intl formatting, not baked into strings.

Gotchas

• Changing a term in one place creates two names for one thing; update the glossary and search all locales.
• Copy reviewed in a spreadsheet looks fine and breaks in the UI (truncation, line wraps, wrong context). Review screenshots.
• Generic “Are you sure?” dialogs train users to click through.
• Humor in error messages reads as mockery when someone just lost work.
• Placeholder-as-label disappears on typing and fails contrast in most designs.

Verification

• Every button in the flow passes the “readable alone” test: someone seeing only the button knows what it does.
• Every error states what to do next.
• Glossary check: grep locales for banned synonyms; zero hits.
• Pseudo-localization or a long-language pass (German) shows no truncation.
• Screen reader pass on key flows: link and button names make sense out of context.

Output contract

| Key | Location / context | Before | After | Chars | Notes |
|---|---|---|---|---|---|
| billing.cancel.confirm | Cancel subscription dialog, primary | Yes | Cancel subscription | 19 | Destructive style |
Glossary changes: "remove" → "delete" (12 strings), "org" → "workspace" (7 strings)