clarify

clarify

Identify and improve unclear, confusing, or poorly written interface text to make the product easier to understand and use.

MANDATORY PREPARATION

Use the frontend-design skill — 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 Installs17.9KRepositorypbakaus/impeccableGitHub Stars10.2KFirst Seen14 days agoSecurity AuditsGen Agent Trust HubPassSocketPassSnykPassInstalled oncodex17.7Kopencode17.6Kgithub-copilot17.6Kgemini-cli17.5Kcursor17.5Kamp17.5K