clarify

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: 1. **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 2. **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: email-address" **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: 1. **Be specific**: "Enter email" not "Enter value" 2. **Be concise**: Cut unnecessary words (but don't sacrifice clarity) 3. **Be active**: "Save changes" not "Changes will be saved" 4. **Be human**: "Oops, something went wrong" not "System error encountered" 5. **Be helpful**: Tell users what to do, not just what happened 6. **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.