🇺🇸English
Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use.
MANDATORY PREPARATION
Invoke /frontend-design — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding — if no design context exists yet, you MUST run /teach-impeccable first. Additionally gather: audience technical level and users' mental state in context.
Assess Current Copy
Identify what makes the text unclear or ineffective:
-
Find clarity problems :
- Jargon : Technical terms users won't understand
- Ambiguity : Multiple interpretations possible
- Passive voice : "Your file has been uploaded" vs "We uploaded your file"
- Length : Too wordy or too terse
- Assumptions : Assuming user knowledge they don't have
- Missing context : Users don't know what to do or why
- Tone mismatch : Too formal, too casual, or inappropriate for situation
-
Understand the context :
- Who's the audience? (Technical? General? First-time users?)
- What's the user's mental state? (Stressed during error? Confident during success?)
- What's the action? (What do we want users to do?)
- What's the constraint? (Character limits? Space limitations?)
CRITICAL : Clear copy helps users succeed. Unclear copy creates frustration, errors, and support tickets.
Plan Copy Improvements
Create a strategy for clearer communication:
- Primary message : What's the ONE thing users need to know?
- Action needed : What should users do next (if anything)?
- Tone : How should this feel? (Helpful? Apologetic? Encouraging?)
- Constraints : Length limits, brand voice, localization considerations
IMPORTANT : Good UX writing is invisible. Users should understand immediately without noticing the words.
Improve Copy Systematically
Refine text across these common areas:
Error Messages
Bad : "Error 403: Forbidden" Good : "You don't have permission to view this page. Contact your admin for access."
Bad : "Invalid input" Good : "Email addresses need an @ symbol. Try: name@example.com"
Principles :
- Explain what went wrong in plain language
- Suggest how to fix it
- Don't blame the user
- Include examples when helpful
- Link to help/support if applicable
Form Labels & Instructions
Bad : "DOB (MM/DD/YYYY)" Good : "Date of birth" (with placeholder showing format)
Bad : "Enter value here" Good : "Your email address" or "Company name"
Principles :
- Use clear, specific labels (not generic placeholders)
- Show format expectations with examples
- Explain why you're asking (when not obvious)
- Put instructions before the field, not after
- Keep required field indicators clear
Button & CTA Text
Bad : "Click here" | "Submit" | "OK" Good : "Create account" | "Save changes" | "Got it, thanks"
Principles :
- Describe the action specifically
- Use active voice (verb + noun)
- Match user's mental model
- Be specific ("Save" is better than "OK")
Help Text & Tooltips
Bad : "This is the username field" Good : "Choose a username. You can change this later in Settings."
Principles :
- Add value (don't just repeat the label)
- Answer the implicit question ("What is this?" or "Why do you need this?")
- Keep it brief but complete
- Link to detailed docs if needed
Empty States
Bad : "No items" Good : "No projects yet. Create your first project to get started."
Principles :
- Explain why it's empty (if not obvious)
- Show next action clearly
- Make it welcoming, not dead-end
Success Messages
Bad : "Success" Good : "Settings saved! Your changes will take effect immediately."
Principles :
- Confirm what happened
- Explain what happens next (if relevant)
- Be brief but complete
- Match the user's emotional moment (celebrate big wins)
Loading States
Bad : "Loading..." (for 30+ seconds) Good : "Analyzing your data... this usually takes 30-60 seconds"
Principles :
- Set expectations (how long?)
- Explain what's happening (when it's not obvious)
- Show progress when possible
- Offer escape hatch if appropriate ("Cancel")
Confirmation Dialogs
Bad : "Are you sure?" Good : "Delete 'Project Alpha'? This can't be undone."
Principles :
- State the specific action
- Explain consequences (especially for destructive actions)
- Use clear button labels ("Delete project" not "Yes")
- Don't overuse confirmations (only for risky actions)
Navigation & Wayfinding
Bad : Generic labels like "Items" | "Things" | "Stuff" Good : Specific labels like "Your projects" | "Team members" | "Settings"
Principles :
- Be specific and descriptive
- Use language users understand (not internal jargon)
- Make hierarchy clear
- Consider information scent (breadcrumbs, current location)
Apply Clarity Principles
Every piece of copy should follow these rules:
- Be specific : "Enter email" not "Enter value"
- Be concise : Cut unnecessary words (but don't sacrifice clarity)
- Be active : "Save changes" not "Changes will be saved"
- Be human : "Oops, something went wrong" not "System error encountered"
- Be helpful : Tell users what to do, not just what happened
- Be consistent : Use same terms throughout (don't vary for variety)
NEVER :
- Use jargon without explanation
- Blame users ("You made an error" → "This field is required")
- Be vague ("Something went wrong" without explanation)
- Use passive voice unnecessarily
- Write overly long explanations (be concise)
- Use humor for errors (be empathetic instead)
- Assume technical knowledge
- Vary terminology (pick one term and stick with it)
- Repeat information (headers restating intros, redundant explanations)
- Use placeholders as the only labels (they disappear when users type)
Verify Improvements
Test that copy improvements work:
- Comprehension : Can users understand without context?
- Actionability : Do users know what to do next?
- Brevity : Is it as short as possible while remaining clear?
- Consistency : Does it match terminology elsewhere?
- Tone : Is it appropriate for the situation?
Remember: You're a clarity expert with excellent communication skills. Write like you're explaining to a smart friend who's unfamiliar with the product. Be clear, be helpful, be human.
Weekly Installs
28.3K
Repository
pbakaus/impeccable
GitHub Stars
13.4K
First Seen
Mar 4, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex27.7K
opencode27.5K
github-copilot27.5K
gemini-cli27.5K
cursor27.4K
amp27.4K
