UX Copy — UI Text That Works

Production-ready UX copy patterns for React and Next.js applications. Every pattern includes real JSX examples — not just advice, but copy you can use directly in components.

This skill works in two modes:

• Greenfield — establishing voice, writing first copy, setting up copy architecture
• Mature codebase — auditing existing copy, fixing inconsistencies, refactoring for clarity

Architecture Overview

[Voice Definition]
    ├── Voice worksheet (4 dimensions: formality, humor, authority, warmth)
    ├── Tone spectrum map (which contexts allow flexibility)
    └── Project voice profile ("confident, precise, reassuring")
              ↓
[Component Copy Rules]
    ├── Buttons → verb-first, specific action, 2-4 words
    ├── Errors → what happened + why + what to do
    ├── Empty states → explain + guide + single CTA
    ├── Confirmations → name the action, never Yes/No
    ├── Notifications → severity determines tone and persistence
    ├── Labels → describe the field, not the format
    └── Tooltips → one sentence, answers "what is this?"
              ↓
[Writing]
    ├── Apply universal rules (plain language, don't blame, front-load)
    ├── Modulate tone to context (errors serious, onboarding flexible)
    └── Match existing voice if mature codebase
              ↓
[Review]
    ├── 3 C's test: Clear → Concise → Character
    ├── Read aloud test
    └── Consistency check (1 entity = 1 term)

Quick Reference

Decision Matrix: "What Should This Say?"

By component type

"Is this copy good?" — The 3 C's Test

1. CLEAR — Can a new user understand this without context?
   ├── YES → continue
   └── NO → rewrite in plain language, remove jargon
              ↓
2. CONCISE — Can any words be removed without losing meaning?
   ├── NO, it's tight → continue
   └── YES → cut them (especially: "please", "in order to", "simply", "just")
              ↓
3. CHARACTER — Does the tone match the project's voice AND this context?
   ├── YES → ship it
   └── NO → adjust toward the right point on the tone spectrum
             (errors → serious end, onboarding → flexible end)

Source: Nielsen Norman Group — 3 C's framework (Clarity > Concision > Character, in that priority order)

Core Principles

These 8 rules show up across the major UX writing guides. The guides do not agree on everything. Principle 2 is where they split.

1. Plain language, always

Use "buy" not "purchase." Use "start" not "initiate." Use "end" not "terminate." This applies even to formal/enterprise products — plain is not casual, it's clear.

Source: GOV.UK aims at a reading age of 9 for public content. Polaris aims at a 7th-grade reading level for merchant admin. Pick the target for the product. Microsoft: simpler is better.

2. Say what happened. Don't blame.

Instructions can address the user as "you". An error should name the problem and the fix. Don't write "you did this wrong", and don't credit the user for something the product did.

// FAIL — blames the user
<p>You didn't enter a store name.</p>

// PASS — names the problem
<p>Store name is required.</p>

// FAIL — credits the user for a system action
<p>You reset your password.</p>

// PASS — says what happened
<p>Password reset.</p>

Source: NN/g (do not use phrasing that blames users). Polaris (say what went wrong and what to do, and keep "we" out of it unless the product caused the problem). GOV.UK and Apple address the person as "you" in instructions. The six sources are NN/g, GOV.UK, Apple, Microsoft, Shopify, and Atlassian. They do not all agree on voice.

3. Front-load important information

Put the action first. People scan the start of a line.

// FAIL — buries the action
<p>In order to access your dashboard, you need to verify your email first.</p>

// PASS — leads with what matters
<p>Verify your email to access your dashboard.</p>

Source: GOV.UK (inverted pyramid)

4. One idea per copy unit

A button names one action. An error covers one problem. A tooltip answers one question.

The 3 I's are the job of the line: inform, influence, or help the action. A line can do more than one of those.

Source: NN/g — The 3 I's of Microcopy

5. Never blame the user

// FAIL — accusatory
<p className="text-destructive">Invalid email address.</p>

// PASS — helpful
<p className="text-destructive">This email needs an @ symbol.</p>

// FAIL — scolding
<p className="text-destructive">You entered an incorrect password.</p>

// PASS — guides toward the fix
<p className="text-destructive">That password doesn't match. Try again or reset it.</p>

Words to avoid in error states: "invalid", "illegal", "incorrect", "oops". "Save failed" can stay when it names what happened. "Error" on its own does not.

Source: NN/g (13 error message guidelines), Apple HIG, Shopify Polaris

6. Voice is constant, tone adapts to context

Your product's voice (personality) stays the same everywhere. Tone (emotional register) shifts based on what the user is experiencing:

Source: Apple HIG ("voice is constant; tone adapts"), Microsoft, Atlassian

7. One entity = one term

If you call it "project" in the sidebar, don't call it "workspace" in the settings page and "space" in the empty state. Pick one term per concept and use it everywhere.

Source: Kinneret Yifrah, Microsoft ("use one word for a concept consistently; avoid synonyms for the same feature")

8. Read it aloud

If it sounds unnatural spoken, rewrite it. This catches robotic phrasing, excessive formality, and awkward constructions faster than any other method.

Source: Apple HIG, Microsoft, Shopify Polaris ("Read it out loud. Does it sound like something a human would say? Ship it.")

Anti-Patterns Checklist

When reviewing UI code, watch for these copy problems:

• "Submit" buttons — replace with specific action: "Create account", "Send message", "Save changes"
• "Click here" links — replace with descriptive text: "View pricing", "Read the docs"
• "Are you sure?" dialogs — replace with specific consequence: "Delete 3 projects?"
• Yes/No/OK buttons on dialogs — replace with action labels: "Delete" / "Keep", "Send" / "Cancel"
• "An error occurred" — replace with what happened and what to do about it
• "Invalid [field]" — replace with what's actually wrong: "Email needs an @ symbol"
• "No data" empty states — replace with what goes here and how to add it
• "Please" in instructions — usually unnecessary: "Enter your email" not "Please enter your email"
• "Loading..." without context — say what's loading: "Loading your dashboard..."
• Mixed terminology — same concept called different names in different places
• Blame in errors — "You didn't enter a store name" → "Store name is required"
• Jokes on errors people can hit again — they go stale. A full outage is the exception.
• ALL CAPS text — harder to read, signals shouting
• Jargon or internal terms — "token expired" → "Your session ended. Log in again."
• Vague success messages — "Success!" → "Payment sent" (name what succeeded)
• Long paragraphs in UI — break into bullets, shorten sentences, let whitespace work

When Reviewing Code

Run this checklist on any component with user-facing text:

• Every button label starts with a verb and names the specific action
• Error messages explain what went wrong AND what to do about it
• Empty states explain what belongs here AND offer a CTA to get started
• Confirmation dialogs name the destructive action in the button label (not "OK")
• The same concept uses the same term everywhere (check nav, headings, buttons, empty states)
• Placeholder text shows format or example, not the label ("name@company.com" not "Enter email")
• Success toasts are about 3 words. An error the user must act on stays on the page. A 3-word status ("You're offline") can be a toast.
• No instances of "invalid", "illegal", "incorrect", "click here", "submit", or "are you sure"
• Sentences under 25 words, paragraphs under 3 sentences in UI text
• Copy reads naturally when spoken aloud
• Tone matches context (serious for errors, flexible for onboarding, brief for success)
• No hardcoded strings that should be in content constants or i18n files