designcommunication

UX Copy Guidelines

Create UX copy guidelines — defining voice, tone, microcopy patterns, error messages, empty states, CTAs, and terminology standards that make interfaces clear and consistent.

UX-copymicrocopyvoice-toneerror-messagesCTAsguidelines

Works well with agents

Copywriter Agent Product Designer Agent UI Designer Agent

Works well with skills

Brand Guidelines Component Design Spec PRD Writing

$ npx skills add The-AI-Directory-Company/(…) --skill ux-copy-guidelines

ux-copy-guidelines/

SKILL.md

Markdown

1
2	# UX Copy Guidelines
3
4	## Before you start
5
6	Gather the following from the user before writing:
7
8	1. What product or feature does this cover? (Entire product, a specific flow, or a new feature launch)
9	2. Who are the users? (Technical developers, non-technical consumers, enterprise admins — vocabulary differs drastically)
10	3. Does a brand voice already exist? (Brand guidelines, tone documentation, or "we have nothing")
11	4. What are the top usability complaints? (Confusing error messages, unclear CTAs, inconsistent terminology)
12	5. What platforms does the UI span? (Web, mobile, CLI, email — constraints differ per surface)
13
14	If the user says "make our copy better," push back: "Better how? Are users confused by error messages, dropping off at specific steps, or contacting support because the UI does not explain what to do next?"
15
16	## UX copy guidelines template
17
18	### 1. Voice and tone principles
19
20	Define 3-5 voice attributes that stay constant, then show how tone shifts by context.
21
22	Voice is the personality (constant). Tone is the mood (varies by situation).
23
24	```Voice attributes:
25	- Clear over clever — say it plainly, skip the wordplay
26	- Confident, not arrogant — guide without lecturing
27	- Helpful, not hand-holdy — respect the user's intelligence
28	- Human, not corporate — write like a knowledgeable colleague
29	```
30
31	Tone shifts by context:
32
33	\| Context \| Tone \| Example \|
34	\|---\|---\|---\|
35	\| Success state \| Warm, brief \| "Project created. You're ready to invite your team." \|
36	\| Error state \| Direct, calm, solution-first \| "That email is already registered. Try signing in instead." \|
37	\| Destructive action \| Serious, specific about consequences \| "This will permanently delete 12 projects and all their data. This cannot be undone." \|
38	\| Empty state \| Encouraging, action-oriented \| "No projects yet. Create your first project to get started." \|
39	\| Loading/waiting \| Reassuring, informative \| "Setting up your workspace. This takes about 30 seconds." \|
40
41	### 2. Microcopy patterns
42
43	Define reusable patterns for common UI elements:
44
45	Buttons and CTAs
46	- Use specific verbs: "Save changes," "Send invite," "Create project" — not "Submit," "OK," or "Done"
47	- Primary action matches the page title: if the page says "Create project," the button says "Create project"
48	- Destructive buttons state the action: "Delete account" not "Continue" or "Confirm"
49
50	Form labels and help text
51	- Labels state what to enter: "Work email address" not "Email"
52	- Help text answers the question the user is about to ask: "We'll use this to send login codes" not "Enter your email"
53	- Placeholder text is an example, never an instruction: placeholder "jane@company.com" not "Enter your email here"
54
55	Confirmation dialogs
56	- Title states the action: "Delete this project?"
57	- Body states the consequence: "This will permanently delete 'Acme Dashboard' and its 47 files."
58	- Buttons are the action and the escape: "Delete project" and "Keep project" — never "Yes" and "No"
59
60	### 3. Error message framework
61
62	Every error message must answer three questions:
63
64	1. What happened? (State the problem in plain language)
65	2. Why did it happen? (Brief cause, if it helps the user)
66	3. What should the user do next? (Specific action to resolve it)
67
68	Bad: "Error 422: Validation failed" / Good: "That password is too short. Use at least 8 characters."
69	Bad: "Something went wrong. Please try again later." / Good: "We couldn't save your changes because the connection dropped. Check your internet and try again."
70
71	Rules:
72	- Never blame the user: "Invalid email" becomes "That doesn't look like an email address."
73	- Never use technical jargon: no HTTP codes, no stack traces, no database field names
74	- Always include a next step: even if it is "Contact support at help@example.com"
75
76	### 4. Empty states
77
78	Every empty state must include:
79
80	- What this area will contain once there is data
81	- Why it is empty (first use vs filtered to zero vs error)
82	- A CTA to create the first item or adjust filters
83
84	- First-use: Heading "No team members yet" / Body "Invite your team to collaborate on projects together." / CTA "Invite team members"
85	- Filtered-to-zero: Heading "No results match your filters" / Body "Try adjusting your date range or removing some filters." / CTA "Clear all filters"
86
87	### 5. Terminology standards
88
89	Create a terminology table for every domain-specific term. Enforce it across all surfaces.
90
91	\| Preferred term \| Avoid \| Reason \|
92	\|---\|---\|---\|
93	\| Project \| Workspace, repo, space \| One word for one concept \|
94	\| Team member \| User, collaborator, colleague \| Consistent across UI and docs \|
95	\| Sign in \| Log in, login, authenticate \| "log in" is the verb, "login" is the noun — avoid ambiguity \|
96	\| Delete \| Remove, destroy, erase \| Unambiguous and expected by users \|
97
98	Rules: one concept, one word — never alternate. If a term needs explanation on first encounter, add a tooltip. Maintain the terminology table in a shared location and update it when new concepts are introduced.
99
100	## Quality checklist
101
102	Before delivering the guidelines, verify:
103
104	- [ ] Voice attributes are defined with do/don't examples, not abstract adjectives
105	- [ ] Tone shifts are documented for at least: success, error, destructive action, empty state, and loading
106	- [ ] Button and CTA patterns use specific verbs, not generic "Submit" or "OK"
107	- [ ] Error message framework requires what happened, why, and what to do next
108	- [ ] Empty states distinguish first-use from filtered-to-zero and include a CTA
109	- [ ] Terminology table lists preferred terms with rejected alternatives and rationale
110	- [ ] Every pattern includes a concrete before/after or good/bad example
111	- [ ] Guidelines are specific enough that two writers would produce similar copy for the same screen
112
113	## Common mistakes
114
115	- Defining voice with vague adjectives. "Friendly and professional" describes every brand. Show the boundary: "We say 'Couldn't save your file' not 'Oopsie! Something went wrong.'"
116	- Ignoring destructive actions. "Are you sure?" with "OK" and "Cancel" buttons is a dark pattern. Name the action in the button and state what will be lost.
117	- Placeholder text as instructions. Placeholders disappear on focus — users who tabbed into a field cannot see them. Use labels and help text for instructions; placeholders for format examples only.
118	- Inconsistent terminology. Calling it "project" on one page and "workspace" on another doubles cognitive load. Pick one term and enforce it everywhere.
119	- Writing error messages after development. Copy guidelines must be part of the design process, not a polish pass after the UI is built. Retrofit copy is always worse than designed copy.
120	- Skipping the tone spectrum. Voice without tone guidance means writers default to one register everywhere. A success message and a data-deletion warning should not sound the same.
121