| name | design-content |
| source | botcore |
| description | Guides UX writing for user-facing interface text. Covers UI labels, button text, error messages, empty states, tooltips, dialog copy, headings, capitalization rules, voice and tone, and product terminology. Use when writing or reviewing any user-facing text in a prototype or production UI, crafting error messages, defining empty state copy, choosing button labels, or enforcing consistent terminology. Triggers: content design, UX writing, UI text, error message, button label, empty state, tooltip, dialog text, capitalization, terminology, microcopy, voice and tone.
|
| version | 1.0.0 |
| triggers | ["content design","UX writing","UI text","error message","button label","empty state","tooltip","dialog text","capitalization","terminology","microcopy","voice and tone","sentence case","copy review"] |
| portable | true |
Design Content
Write clear, consistent, human-sounding text for every surface of a user interface.
Capabilities
- Voice and Tone --- Apply a warm, crisp, helpful voice across all UI text
- UI Labels --- Write button labels, headings, menu items, and navigation text
- Error Messages --- Compose error text that explains what happened and what to do next
- Empty States --- Write first-use, no-results, and error empty state copy
- Tooltips and Dialogs --- Draft concise help text, confirmation dialogs, and inline guidance
- Terminology --- Enforce correct product names and avoid ambiguous synonyms
- Capitalization and Grammar --- Apply sentence case, contractions, active voice, and present tense
Core Principles
1. Warm and Relaxed
Write conversationally, not formally. The interface should sound like a knowledgeable colleague, not a legal document.
2. Crisp and Clear
Use simple words and short sentences. If a shorter word works, prefer it. Remove filler.
3. Ready to Lend a Hand
Be helpful without being condescending. Guide the user toward their next action.
4. User-Addressed
Always address the user as "you" and "your." Never refer to "the user" in UI text.
5. Action-Led
Lead with verbs for actions. Use "Save" not "Click Save." Use "select" not "click" or "tap."
Quick Reference
Essential Rules
| Rule | Do | Don't |
|---|
| Sentence case | "Create a new item" | "Create A New Item" |
| Contractions | "it's", "you'll", "don't" | "it is", "you will", "do not" |
| Second person | "You can create..." | "A project can be created..." |
| Verb-led actions | "Save" | "Click Save" |
| Use "select" | "Select a workspace" | "Click a workspace" |
| No "please" | "Enter your name" | "Please enter your name" |
| Present tense | "File saves" | "File will be saved" |
| Active voice | "You can export..." | "The report can be exported..." |
Button Labels
Write button labels with verbs first. Keep them under three words. Match the action the button performs.
| Do | Don't |
|---|
| Save | Save changes |
| Delete | Delete item |
| Create project | Create a new project |
| Cancel | Go back |
| Try again | Retry operation |
Error Messages
Follow the pattern: [What happened] + [What to do about it].
| Do | Don't |
|---|
| "Couldn't load workspaces. Check your connection and try again." | "Error: Network request failed (ERR_NETWORK)" |
| "You don't have access to this workspace. Ask the owner for permission." | "403 Forbidden" |
| "Something went wrong. Try again in a few minutes." | "An unexpected error has occurred. Please contact your administrator." |
Guidelines:
- Use contractions ("couldn't" not "could not")
- Never expose technical codes or stack traces to the user
- Always include a recovery action or next step
- Keep the tone calm and reassuring
Empty States
Follow the pattern: [Title: What's missing] + [Body: Why + what to do].
| Scenario | Title | Body |
|---|
| First use | "No items yet" | "Create your first item to get started." |
| No results | "No results found" | "Try different search terms or remove filters." |
| Error | "Couldn't load items" | "Check your connection and try again." |
Guidelines:
- Title describes what is absent, not what went wrong
- Body gives a clear action the user can take
- First-use empty states should be encouraging and orient the user
Tooltips
- Keep to one sentence when possible
- Describe what the control does, not how to use it
- Do not repeat the label text
Dialog Text
- Title: State the action or decision ("Delete this item?")
- Body: Explain consequences concisely
- Primary button: Verb matching the action ("Delete")
- Secondary button: "Cancel"
Workflow
Writing New UI Text
- Identify the surface --- Is it a button, heading, error, empty state, tooltip, or dialog?
- Draft --- Write the text following the pattern for that surface type
- Apply rules --- Check sentence case, contractions, active voice, verb-led actions, second person
- Check terminology --- Verify product names against the terminology table
- Review --- Read the text aloud; if it sounds stiff or robotic, rewrite
Reviewing Existing Text
- Scan for Title Case --- Convert any Title Case headings or labels to sentence case
- Scan for passive voice --- Rewrite "X can be done" as "You can do X"
- Scan for "please" --- Remove from instructions
- Scan for jargon --- Replace technical codes and internal terms with user-friendly language
- Check error messages --- Ensure each includes a recovery action
Terminology
Use official product names consistently. When the product context is ambiguous, spell out the full name on first mention.
| Correct | Avoid |
|---|
| Workspace | Project, folder |
| Dashboard | Report page, analytics view |
| Settings | Preferences, options, config |
Note: Replace these example entries with your product's canonical terms. The key principle: pick one name per concept and use it everywhere.
Checklist
Before finalizing any user-facing text:
When to Escalate
- Legal, compliance, or regulatory text that requires review by a legal team
- Accessibility-specific text (alt text, ARIA labels) --- defer to an accessibility specialist or skill
- Localization and translation concerns that affect meaning across languages
- Brand voice conflicts between product teams requiring a cross-team decision
- Terminology disputes where multiple product names exist for the same concept
