Microcopy

/microcopy

Write the small strings that decide whether users figure your product out — or churn. Bad copy makes good visuals fail; good copy carries average visuals.

When to use

• Designing or reviewing any user-facing text — buttons, errors, empty states, tooltips, confirmations, form labels, onboarding.
• After a UX review flagged unclear messaging.
• When a feature ships with placeholder strings ("Submit," "Error," "Loading…") and needs real ones.
• When localizing — the source strings need to be localizable in the first place.

Operating method

1. Establish voice

Read 5–10 existing strings from the product before writing new ones. Identify:

• Tone — professional / friendly / playful / clinical. Most B2B is professional-with-warmth; consumer varies wildly.
• Person — second person ("Save your changes") almost always. First-person plural ("We saved your changes") for system updates only.
• Verb usage — direct ("Save"), polite ("Please save"), or playful ("Stash it"). Pick one and stick with it.
• Punctuation — sentence case vs title case for buttons. Periods at end of error messages or not.
• Emoji — used or not. (Default: not. Add only if the product already uses them.)

If no existing strings exist, default to: direct, second person, sentence case for buttons, periods on full sentences, no emoji.

2. Apply the four rules

Verbs over nouns on buttons. Buttons do something. Use the verb.

Specific errors with recovery. Tell the user what went wrong AND what to do.

Empty states have CTAs. Don't leave the user stranded with "No results."

Honesty in confirmations. Don't trick users into clicking yes.

3. Forbidden phrases

These signal lazy or hostile copy. Refuse to write them; replace if you find them.

4. Localization-friendly writing

Write strings that translate cleanly:

• No idioms. "Bite the bullet" doesn't translate. "Confirm the change" does.
• No concatenation. Don't write "You have " + count + " messages" — different languages put numbers in different positions, and some require plural forms beyond singular/plural.
• Use ICU MessageFormat or your framework's i18n library for plurals, gender, and number formatting.
• Don't bake numbers into strings. "5 items" → {count, plural, one {# item} other {# items}}.
• Render dates and currencies in user locale, not source locale.
• Leave 30% room for expansion. German strings are often 30–40% longer than English.

5. Cover all the moments

For every screen or component, walk the moments:

• Default — the standard view. What does it say?
• Loading — what's communicated while waiting?
• Empty — first-time-use copy + CTA.
• Success — confirmation message.
• Error — per failure mode (network, validation, permission, server).
• Disabled — why is this thing disabled? Tooltip explains.
• Confirm — destructive actions get a clear "do X / cancel" choice.
• Onboarding — first 3 actions for a new user.

6. Save patterns to memory

If the product establishes a copy convention (e.g., "always say 'Save changes' not 'Save'"), save it to .claude/memory/feedback/copy-conventions.md so future sessions follow the same voice.

Output format

For a copy spec:

# Microcopy: <screen / feature>

## Voice
- Tone: <professional with warmth>
- Person: second
- Case: sentence (buttons), title (page headers)
- Punctuation: full sentences end with periods; buttons no periods

## Strings

### Page header
<copy>

### Primary CTA (button)
<copy>

### Secondary action
<copy>

### Form fields
| Field | Label | Placeholder | Help text | Error: blank | Error: invalid |
|---|---|---|---|---|---|
| Email | "Work email" | "you@company.com" | "We'll send sign-in links here." | "Email is required." | "Email must include an @ symbol." |

### States
| State | Copy |
|---|---|
| Loading | "Sending invite…" |
| Success | "Invite sent ✓" |
| Error: network | "Couldn't send the invite — check your connection or retry." |
| Error: already invited | "Already invited — resend or remove." |
| Empty | "No invites sent yet. Send your first below." |

### Confirmation dialog (destructive)
- Title: "Remove team member?"
- Body: "They'll lose access to all projects. This can't be undone."
- Confirm button: "Remove member"
- Cancel button: "Keep member"

### Tooltips
| Element | Tooltip |
|---|---|
| Disabled "Send" button | "Add at least one recipient to send" |
| ⚠ icon next to plan | "Card on file expires in 7 days" |

For a copy review:

## Verdict: GREAT | NEEDS WORK | REWRITE

## Issues by category

### Specificity (N issues)
- error.tsx:18 — "Something went wrong" → "Couldn't save changes — check your connection and retry."

### Voice consistency (N issues)
- onboarding.tsx:42 — Uses first-person ("We've saved your work") but the rest of the product uses second person.

### Forbidden phrases (N issues)
- billing.tsx:91 — "Simply enter your card" → "Enter your card."

### Empty states (N issues)
- inbox.tsx:5 — "No messages" with no CTA → "Your inbox is empty. Connect an account to start."

### Localization-readiness (N issues)
- list.tsx:30 — `"You have " + count + " items"` → use ICU plural format.

## What's working
- <thing>
- <thing>

## Recommended next moves
1. <highest-leverage>

Boundaries

• Don't write for a voice the product doesn't have — read existing copy first.
• Don't write copy that's marketing-speak when the product is utilitarian, or vice versa.
• Don't recommend dark patterns. Refuse, name them, offer honest alternatives.
• Don't translate yourself — flag strings for translator review when localizing.
• Don't write copy without knowing the state. "Submit" with no context is meaningless.
• Always cover all relevant moments (loading / empty / error / success).