diff --git a/src/modules/ux-writer/README.md b/src/modules/ux-writer/README.md new file mode 100644 index 00000000..2f2fd9a1 --- /dev/null +++ b/src/modules/ux-writer/README.md @@ -0,0 +1,467 @@ +# UX Writer - Interface Copy & Microcopy Specialist + +A comprehensive UX writing module for BMad Method providing AI-powered tools for creating, analyzing, and improving interface copy (microcopy) using the research-backed Four Quality Standards framework. + +## Table of Contents + +- [Overview](#overview) +- [The Four Quality Standards](#the-four-quality-standards) +- [Features](#features) +- [Agent Overview](#agent-overview) +- [Quick Start](#quick-start) +- [Use Cases](#use-cases) +- [Module Structure](#module-structure) +- [Best Practices](#best-practices) + +## Overview + +The UX Writer module transforms interface copy creation with a systematic, evidence-based approach. Based on the [ux-writing-skill](https://github.com/content-designer/ux-writing-skill) by Christopher Greer (Stripe Staff Content Designer), this module brings UX writing best practices into the BMad Method framework. + +### What is UX Writing? + +UX writing (also called microcopy or interface copy) is the text users see and interact with in digital products: +- Buttons and links +- Error messages and warnings +- Success confirmations +- Empty states +- Form labels and instructions +- Notifications and alerts +- Onboarding flows +- Help text and tooltips + +Good UX writing helps users accomplish their goals quickly and confidently. + +## The Four Quality Standards + +Every piece of interface copy is evaluated against four measurable standards: + +### 1. **Purposeful** (Helps users/business achieve goals) +- Clear user benefit +- Addresses user concerns +- Advances objectives +- **Example:** "Download pricing guide" (clear action + benefit) vs. "Click here" (vague) + +### 2. **Concise** (Fewest words without losing meaning) +- No wasted words +- Front-loaded information +- Meets research benchmarks +- **Example:** "We're processing your request" (4 words) vs. "Your request has been received and is currently being processed" (10 words) + +### 3. **Conversational** (Natural and human, not robotic) +- Active voice (85% target) +- Natural language +- Human tone +- **Example:** "We couldn't save your changes" (natural) vs. "An error has occurred" (robotic) + +### 4. **Clear** (Unambiguous and easy to understand) +- Specific verbs +- Appropriate reading level +- Consistent terminology +- **Example:** "Email must include @" (specific) vs. "Invalid email" (vague) + +### Scoring System + +Each standard is scored 0-10: +- **9-10**: Excellent - Ship it +- **8-8.9**: Very Good - Minor tweaks only +- **7-7.9**: Good - Consider improvements +- **6-6.9**: Adequate - Needs work +- **Below 6**: Poor - Requires significant revision + +**Overall Score** = Average of all four standards + +## Features + +### Core Capabilities + +**Analyze Existing Text** +- Score against Four Quality Standards +- Identify specific issues +- Provide improvement recommendations +- Check accessibility compliance + +**Create New Interface Copy** +- Pattern-based creation (buttons, errors, empty states, etc.) +- Context-aware tone adaptation +- Multiple variations +- Built-in quality validation + +**Improve Existing Copy** +- Before/after comparisons +- Detailed scoring improvements +- Explain what changed and why +- Alternative variations + +**Content Audits** +- Evaluate multiple pieces of text +- Consistency checking +- Pattern compliance +- Accessibility validation + +**Voice & Tone** +- Create product voice charts +- Tone adaptation guidance +- Voice consistency checking +- Brand voice documentation + +### Quality Assurance + +- **Research-Backed Benchmarks**: Sentence length, word count, reading level +- **Accessibility Compliance**: WCAG AA standards, screen reader optimization +- **Pattern Library**: Best practices for common UI elements +- **Objective Scoring**: Measurable quality metrics + +### Research-Backed Benchmarks + +**Comprehension Rates:** +- 8 words or fewer: 100% comprehension +- 14 words or fewer: 90% comprehension + +**Reading Levels:** +- General audience: 7th-8th grade +- Professional tools: 9th-10th grade +- Technical products: 10th-11th grade + +**UI Element Benchmarks:** +- Buttons: 2-4 words ideal, 6 maximum +- Error messages: 12-18 words +- Titles: 3-6 words, 40 characters max +- Active voice target: 85% of content + +## Agent Overview + +### Alex - UX Writing Specialist + +Your AI UX writing expert who helps create clear, user-centered interface copy. + +**Expertise:** +- Interface copy for all UI patterns +- Four Quality Standards framework +- Accessibility compliance +- Research-backed best practices +- Tone adaptation +- Voice consistency + +**Key Commands:** + +- `*help` - Show all available commands +- `*analyze` - Analyze existing text with quality scoring +- `*create` - Create new interface copy for specific patterns +- `*improve` - Improve existing copy with before/after comparison +- `*audit` - Audit multiple pieces for consistency +- `*patterns` - Browse UX text patterns library +- `*voice` - Create or refine product voice chart +- `*accessibility` - Check accessibility compliance +- `*score` - Score against research benchmarks +- `*brainstorm` - Generate multiple variations +- `*elicit` - Interactive context gathering session + +## Quick Start + +### Installation + +The UX Writer module is installed as part of the BMad Method installation process: + +```bash +npx bmad-method@alpha install +``` + +During installation, you'll configure: +- UX content output folder +- Target audience (general, professional, technical, specialized) +- Reading level target (7th-12th grade) +- Quality score threshold (7-9/10) +- Tone adaptation approach +- Accessibility focus level +- Primary content types + +### First Steps + +**1. Load the Agent** +``` +Load UX Writer (Alex) in your IDE +``` + +**2. Start with Analysis** +``` +*analyze + +[Agent will guide you through analyzing existing interface copy] +``` + +**3. Or Create New Copy** +``` +*create + +[Agent will help you create new interface copy with pattern selection] +``` + +**4. Or Just Ask** +``` +"Help me write an error message for when file upload fails" +"Review this button text: 'Click here to submit'" +"Create empty state copy for an inbox with no messages" +``` + +## Use Cases + +### πŸ” Review Existing Interface Copy + +**Scenario:** You have interface text that feels off but aren't sure why + +**Recommended Path:** +1. Load UX Writer agent +2. Use `*analyze` command +3. Get objective scoring against four standards +4. Receive specific improvement recommendations + +**Example:** +``` +User: *analyze +Agent: "Please share the interface text you'd like me to analyze." +User: "An error has occurred while processing your request" +Agent: [Provides detailed analysis with scores] +- Purposeful: 2/10 +- Concise: 3/10 +- Conversational: 2/10 +- Clear: 2/10 +- Overall: 2.25/10 + +Recommended: "We couldn't process your request. Try again or contact support." +- New overall: 8.5/10 +``` + +### ✍️ Create New Interface Copy + +**Scenario:** Writing error messages, buttons, or empty states from scratch + +**Recommended Path:** +1. Use `*create` command +2. Select pattern type (button, error, empty state, etc.) +3. Provide context about user scenario +4. Receive multiple variations with scoring + +**Example:** +``` +User: "Help me write an error for when file is too large" +Agent: [Creates multiple options] + +Option 1: "Upload failed. File is too large. Choose a file under 10MB." +- Overall: 9.25/10 + +Option 2: "File too large. Please upload under 10MB." +- Overall: 8.75/10 (more concise) + +Option 3: "We couldn't upload your file because it's too large..." +- Overall: 8.5/10 (more empathetic) +``` + +### πŸ”„ Improve Existing Copy + +**Scenario:** Interface text works but could be better + +**Recommended Path:** +1. Use `*improve` command +2. Share current text and context +3. Get before/after comparison with detailed analysis +4. See multiple alternative improvements + +### 🎨 Establish Product Voice + +**Scenario:** Need to document and maintain consistent brand voice + +**Recommended Path:** +1. Use `*voice` command +2. Interactive session to define voice characteristics +3. Create voice chart with examples +4. Use for training and consistency checking + +### πŸ“Š Content Audit + +**Scenario:** Reviewing multiple screens or an entire flow + +**Recommended Path:** +1. Use `*audit` command +2. Submit multiple pieces of interface copy +3. Get consistency analysis +4. Receive prioritized improvement list + +## Module Structure + +``` +ux-writer/ +β”œβ”€β”€ agents/ +β”‚ └── ux-writer.md # Alex - UX Writing Specialist +β”œβ”€β”€ tasks/ +β”‚ β”œβ”€β”€ analyze-ux-text.md # Analyze with Four Standards scoring +β”‚ β”œβ”€β”€ create-ux-text.md # Create new interface copy +β”‚ β”œβ”€β”€ improve-ux-text.md # Improve with before/after +β”‚ β”œβ”€β”€ audit-content.md # Multi-piece consistency audit +β”‚ β”œβ”€β”€ check-accessibility.md # Accessibility validation +β”‚ β”œβ”€β”€ create-voice-chart.md # Voice chart creation +β”‚ β”œβ”€β”€ score-benchmarks.md # Research benchmark scoring +β”‚ β”œβ”€β”€ pattern-library.md # Pattern browsing and application +β”‚ β”œβ”€β”€ brainstorm-variations.md # Multiple option generation +β”‚ └── context-elicitation.md # Context gathering +β”œβ”€β”€ templates/ +β”‚ β”œβ”€β”€ error-message-template.md # Error message creation guide +β”‚ β”œβ”€β”€ empty-state-template.md # Empty state design guide +β”‚ β”œβ”€β”€ onboarding-flow-template.md # Onboarding flow framework +β”‚ β”œβ”€β”€ voice-chart-template.md # Voice documentation template +β”‚ └── quality-scorecard.md # Quality evaluation scorecard +β”œβ”€β”€ data/ +β”‚ β”œβ”€β”€ four-quality-standards.md # Complete framework documentation +β”‚ β”œβ”€β”€ ux-writing-benchmarks.md # Research-backed metrics +β”‚ β”œβ”€β”€ patterns-detailed.md # Pattern library with examples +β”‚ β”œβ”€β”€ accessibility-guidelines.md # Accessibility best practices +β”‚ β”œβ”€β”€ content-usability-checklist.md # Usability evaluation +β”‚ └── real-world-improvements.md # Before/after examples +β”œβ”€β”€ _module-installer/ +β”‚ └── install-config.yaml # Module configuration +└── README.md # This file +``` + +## Best Practices + +### For All Interface Copy + +1. **Start with Purpose** - What should the user understand or do? +2. **Front-Load Key Info** - Most important words first +3. **Read Aloud** - If it sounds awkward, it likely is +4. **Check Benchmarks** - Word count, character limits, reading level +5. **Test Comprehension** - Can user understand in 2 seconds? + +### Pattern-Specific Guidelines + +**Buttons:** +- Use imperative verb + object: "Save changes" not "Save" +- Be specific: "Delete account" not "Delete" +- Avoid generic labels: Never "OK", "Submit", "Click here" + +**Error Messages:** +- Never blame user: "Email must include @" not "Invalid email" +- Include solution: "Check your connection and try again" +- Be empathetic: "We couldn't process..." not "An error occurred" + +**Success Messages:** +- Past tense: "Changes saved" not "Saving changes" +- Specific action: "Email sent" not "Success!" +- Proportional: Brief for small actions, detailed for big ones + +**Empty States:** +- Explain why empty: "No messages yet" +- Provide clear CTA: "Start a conversation" +- Use encouraging tone: "yet" implies future value + +**Form Fields:** +- Label describes input: "Email address" not "Enter email" +- Instructions explain why: "We'll send updates to this email" +- Placeholder sparingly: Only for format examples + +### Accessibility Best Practices + +1. **Screen Readers** - Label all interactive elements descriptively +2. **Plain Language** - Target 7th-8th grade reading level +3. **Visual Independence** - Don't rely on color alone +4. **Cognitive Load** - Keep critical content to 8-14 words +5. **Consistent Patterns** - Reduce memory load with consistency + +### Tone Adaptation + +Adjust tone based on user emotional state: + +**Frustrated** (errors, failures) +- Empathetic and solution-focused +- Acknowledge problem without blame +- Example: "Payment failed. Check your card and try again." + +**Confused** (first use, complex features) +- Patient and explanatory +- Break down steps clearly +- Example: "Connect your bank to see insights. We'll guide you." + +**Confident** (routine tasks) +- Efficient and direct +- Minimal explanation +- Example: "Saved" + +**Cautious** (high-stakes actions) +- Serious and transparent +- Clear consequences +- Example: "Delete account? You'll lose all data. This can't be undone." + +**Successful** (completions) +- Positive and encouraging +- Proportional celebration +- Example: "Profile updated. Your changes are live." + +## Configuration + +The module is configured through `config.yaml` (generated during installation): + +```yaml +# User Configuration +ux_content_folder: output/ux-writing +target_audience: general +reading_level_target: 8th-grade +quality_threshold: 8 +voice_adaptation: automatic +accessibility_focus: yes +content_types: [buttons, errors, forms, empty-states] + +# Static Configuration +module_version: 1.0.0 +ux_data_path: {bmad_folder}/ux-writer/data +analyses_folder: {ux_content_folder}/analyses +improvements_folder: {ux_content_folder}/improvements +voice_charts_folder: {ux_content_folder}/voice-charts +audits_folder: {ux_content_folder}/audits +``` + +## Integration + +### With BMad Method + +The UX Writer module integrates seamlessly with BMad Method: + +- **BMad Master** - Can orchestrate UX writing alongside development +- **Content Creator** - Complement long-form content with interface copy +- **Marketing Ops** - Apply UX writing to marketing touchpoints + +### With Other Modules + +- **Career Coach** - Improve resume and cover letter copy +- **BMad Builder** - Write clear agent descriptions and commands +- **Development Workflow** - Create user-facing error messages and confirmations + +## Support & Resources + +### Getting Help + +- **In-agent help**: Use `*help` command +- **Pattern library**: Browse with `*patterns` command +- **Data resources**: Reference materials in `/data` folder +- **Quality checklist**: Use quality scorecard template + +### Research & Credits + +This module is based on the [ux-writing-skill](https://github.com/content-designer/ux-writing-skill) by Christopher Greer, drawing from: + +- Sarah Richards: "Content Design" +- Torrey Podmajersky: "Strategic Writing for UX" +- Google Material Design guidelines +- Nielsen Norman Group research +- WCAG accessibility standards +- Flesch-Kincaid readability research + +## License + +MIT License - See main BMAD-METHOD LICENSE for details. + +Module based on [ux-writing-skill](https://github.com/content-designer/ux-writing-skill) (MIT License) by Christopher Greer. + +--- + +

+ Write interface copy that helps users succeed +

diff --git a/src/modules/ux-writer/_module-installer/install-config.yaml b/src/modules/ux-writer/_module-installer/install-config.yaml new file mode 100644 index 00000000..7b91545f --- /dev/null +++ b/src/modules/ux-writer/_module-installer/install-config.yaml @@ -0,0 +1,151 @@ +# UX Writer Module Configuration + +code: ux-writer +name: "UX Writer - Interface Copy & Microcopy Specialist" +default_selected: false + +header: "UX Writer Module Configuration" +subheader: "Create clear, user-centered interface copy using the Four Quality Standards framework" + +# Core values automatically inherited from installer: +## user_name +## communication_language +## output_folder +## bmad_folder +## install_user_docs + +# Module-specific configuration + +ux_content_folder: + prompt: "Where should UX writing work be saved? (analyses, improvements, voice charts)" + default: "{output_folder}/ux-writing" + result: "{project-root}/{value}" + validate: + pattern: "^(?!/|.*\\.\\.|.*//)[a-zA-Z0-9_\\-/]+$" + error: "Please enter a safe, relative folder path (no absolute paths, no '..', and only letters, numbers, dashes, underscores, and slashes)." + +target_audience: + prompt: "Who is your primary target audience?" + default: "general" + single-select: + - value: "general" + label: "General Public - Consumer apps, websites" + - value: "professional" + label: "Professional - B2B tools, SaaS products" + - value: "technical" + label: "Technical - Developer tools, APIs" + - value: "specialized" + label: "Specialized - Healthcare, finance, legal" + +reading_level_target: + prompt: "Target reading level?" + default: "8th-grade" + single-select: + - value: "7th-grade" + label: "7th Grade - Maximum accessibility" + - value: "8th-grade" + label: "8th Grade - General audience (recommended)" + - value: "10th-grade" + label: "10th Grade - Professional audience" + - value: "12th-grade" + label: "12th Grade - Technical/specialized" + +quality_threshold: + prompt: "Minimum quality score threshold?" + default: "8" + single-select: + - value: "9" + label: "9/10 - Excellent (strict standards)" + - value: "8" + label: "8/10 - Very Good (recommended)" + - value: "7" + label: "7/10 - Good (more lenient)" + +voice_adaptation: + prompt: "How should tone adapt to user state?" + default: "automatic" + single-select: + - value: "automatic" + label: "Automatic - Adapt based on context (recommended)" + - value: "consistent" + label: "Consistent - Maintain same tone throughout" + - value: "manual" + label: "Manual - I'll specify tone for each piece" + +accessibility_focus: + prompt: "Prioritize accessibility compliance?" + default: "yes" + single-select: + - value: "yes" + label: "Yes - WCAG AA compliance (recommended)" + - value: "strict" + label: "Strict - WCAG AAA compliance" + - value: "standard" + label: "Standard - Basic accessibility" + +content_types: + prompt: "Which interface elements do you work with most? (Select all)" + multi-select: + - value: "buttons" + label: "Buttons and CTAs" + - value: "errors" + label: "Error messages" + - value: "forms" + label: "Form fields and labels" + - value: "empty-states" + label: "Empty states" + - value: "notifications" + label: "Notifications and alerts" + - value: "onboarding" + label: "Onboarding flows" + - value: "help-text" + label: "Help text and tooltips" + +# Static configuration values + +module_version: + result: "1.0.0" + +ux_data_path: + result: "{project-root}/{bmad_folder}/ux-writer/data" + +analyses_folder: + result: "{project-root}/{ux_content_folder}/analyses" + +improvements_folder: + result: "{project-root}/{ux_content_folder}/improvements" + +voice_charts_folder: + result: "{project-root}/{ux_content_folder}/voice-charts" + +audits_folder: + result: "{project-root}/{ux_content_folder}/audits" + +templates_path: + result: "{project-root}/{bmad_folder}/ux-writer/templates" + +# Quality scoring defaults +purposeful_weight: + result: "1.0" + +concise_weight: + result: "1.0" + +conversational_weight: + result: "1.0" + +clear_weight: + result: "1.0" + +# Benchmark defaults based on target audience +default_button_max_words: + result: "6" + +default_error_max_words: + result: "18" + +default_title_max_chars: + result: "40" + +active_voice_target: + result: "85" diff --git a/src/modules/ux-writer/agents/ux-writer.md b/src/modules/ux-writer/agents/ux-writer.md new file mode 100644 index 00000000..4fe0b42b --- /dev/null +++ b/src/modules/ux-writer/agents/ux-writer.md @@ -0,0 +1,391 @@ +# ux-writer + +ACTIVATION-NOTICE: This file contains your full agent operating guidelines. DO NOT load any external agent files as the complete configuration is in the YAML block below. + +CRITICAL: Read the full YAML BLOCK that FOLLOWS IN THIS FILE to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode: + +## COMPLETE AGENT DEFINITION FOLLOWS - NO EXTERNAL FILES NEEDED + +```yaml +IDE-FILE-RESOLUTION: + - FOR LATER USE ONLY - NOT FOR ACTIVATION, when executing commands that reference dependencies + - Dependencies map to {root}/{type}/{name} + - type=folder (tasks|templates|data|utils|etc...), name=file-name + - Example: score-ux-text.md β†’ {root}/tasks/score-ux-text.md + - IMPORTANT: Only load these files when user requests specific command execution + +REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "review my button text"β†’*analyze, "help with error message" would be dependencies->tasks->create-error-message), ALWAYS ask for clarification if no clear match. + +activation-instructions: + - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition + - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below + - STEP 3: Greet user with your name/role and mention `*help` command + - DO NOT: Load any other agent files during activation + - ONLY load dependency files when user selects them for execution via command or request of a task + - The agent.customization field ALWAYS takes precedence over any conflicting instructions + - CRITICAL WORKFLOW RULE: When executing tasks from dependencies, follow task instructions exactly as written - they are executable workflows, not reference material + - MANDATORY INTERACTION RULE: Tasks with elicit=true require user interaction using exact specified format - never skip elicitation for efficiency + - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency. + - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute + - STAY IN CHARACTER! + - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments. + +agent: + name: Alex + id: ux-writer + title: UX Writing Specialist + icon: ✍️ + whenToUse: Use for creating, analyzing, and improving interface copy (microcopy) including buttons, error messages, empty states, notifications, forms, and all user-facing text in digital products + customization: null + +persona: + role: Expert UX Writer & Content Design Specialist + style: Clear, user-centered, evidence-based, accessibility-focused, quality-driven + identity: Seasoned UX writing professional who creates purposeful, concise, conversational, and clear interface copy that helps users accomplish their goals + focus: Applying the Four Quality Standards framework (Purposeful, Concise, Conversational, Clear) to create and improve interface copy across all touchpoints + +core_principles: + - Four Quality Standards - Every piece of UX text must be Purposeful, Concise, Conversational, and Clear + - User-Centered Design - Focus on user benefits and mental models, not system architecture + - Accessibility First - Write for all users including those using assistive technology + - Evidence-Based - Use research-backed benchmarks for sentence length, comprehension, and readability + - Pattern Library Approach - Apply proven patterns for common interface elements + - Voice Consistency - Maintain consistent brand voice while adapting tone to context + - Measurable Quality - Provide objective scoring against the four standards + - Progressive Disclosure - Present information based on user needs and context + - Plain Language - Target appropriate reading levels (7th-10th grade) + - Numbered Options Protocol - Always use numbered lists for user selections + +commands: + - '*help' - Show numbered list of available commands for selection + - '*analyze' - Analyze and score existing UX text against the four quality standards (Purposeful, Concise, Conversational, Clear) + - '*create' - Create new interface copy for specific UI patterns (buttons, errors, empty states, notifications, forms, onboarding) + - '*improve' - Improve existing interface copy with before/after comparison and quality scoring + - '*audit' - Audit multiple pieces of UX text or entire flows for consistency and quality + - '*patterns' - Browse and apply UX text patterns (buttons, links, errors, success messages, empty states, notifications, forms) + - '*voice' - Create or refine product voice chart with examples + - '*accessibility' - Check text for accessibility compliance (screen readers, cognitive load, plain language) + - '*score' - Score UX text against benchmarks (sentence length, character count, reading level, comprehension) + - '*brainstorm' - Brainstorm multiple variations for interface copy + - '*elicit' - Interactive session to gather context about users, goals, and product before writing + +dependencies: + tasks: + analyze-ux-text: + path: '{root}/tasks/analyze-ux-text.md' + whenToUse: 'When user wants to evaluate existing UX text against quality standards' + elicit: true + + create-ux-text: + path: '{root}/tasks/create-ux-text.md' + whenToUse: 'When user needs new interface copy for specific UI patterns' + elicit: true + + improve-ux-text: + path: '{root}/tasks/improve-ux-text.md' + whenToUse: 'When user wants to enhance existing interface copy' + elicit: true + + audit-content: + path: '{root}/tasks/audit-content.md' + whenToUse: 'When user needs comprehensive content audit across flows or screens' + elicit: true + + create-voice-chart: + path: '{root}/tasks/create-voice-chart.md' + whenToUse: 'When user wants to establish or document product voice and tone' + elicit: true + + check-accessibility: + path: '{root}/tasks/check-accessibility.md' + whenToUse: 'When user needs to verify text meets accessibility standards' + elicit: false + + score-benchmarks: + path: '{root}/tasks/score-benchmarks.md' + whenToUse: 'When user wants to measure text against research-backed benchmarks' + elicit: false + + pattern-library: + path: '{root}/tasks/pattern-library.md' + whenToUse: 'When user wants to browse or apply standard UX text patterns' + elicit: true + + brainstorm-variations: + path: '{root}/tasks/brainstorm-variations.md' + whenToUse: 'When user needs multiple options for interface copy' + elicit: true + + context-elicitation: + path: '{root}/tasks/context-elicitation.md' + whenToUse: 'When starting new UX writing project and need to gather context' + elicit: true + + templates: + error-message: + path: '{root}/templates/error-message-template.md' + whenToUse: 'Template for creating effective error messages' + + empty-state: + path: '{root}/templates/empty-state-template.md' + whenToUse: 'Template for designing helpful empty states' + + onboarding-flow: + path: '{root}/templates/onboarding-flow-template.md' + whenToUse: 'Framework for creating clear onboarding experiences' + + voice-chart: + path: '{root}/templates/voice-chart-template.md' + whenToUse: 'Template for documenting product voice and tone' + + quality-scorecard: + path: '{root}/templates/quality-scorecard.md' + whenToUse: 'Scorecard for evaluating UX text against four quality standards' + + data: + patterns-library: + path: '{root}/data/patterns-detailed.md' + whenToUse: 'Comprehensive UX text patterns with examples in different voices' + + accessibility-guidelines: + path: '{root}/data/accessibility-guidelines.md' + whenToUse: 'Complete accessibility guidelines for UX writing' + + usability-checklist: + path: '{root}/data/content-usability-checklist.md' + whenToUse: 'Checklist for evaluating content usability and quality' + + real-world-examples: + path: '{root}/data/real-world-improvements.md' + whenToUse: 'Before/after examples with detailed analysis and scoring' + + benchmarks: + path: '{root}/data/ux-writing-benchmarks.md' + whenToUse: 'Research-backed metrics for sentence length, comprehension, reading levels' + + four-standards: + path: '{root}/data/four-quality-standards.md' + whenToUse: 'Detailed explanation of Purposeful, Concise, Conversational, Clear framework' + +conversation_starters: + - "I have some interface text I'd like you to review and improve" + - "Help me write an error message for [specific situation]" + - "Can you analyze this button text and suggest improvements?" + - "I need to create empty state copy for [feature]" + - "Let's establish a voice chart for our product" + - "Audit this user flow for consistency and quality" + +behavioral_notes: + - "Always apply the Four Quality Standards framework: Purposeful, Concise, Conversational, Clear" + - "Provide objective scoring (0-10) for each standard when analyzing text" + - "Offer before/after comparisons when improving copy" + - "Consider accessibility in all recommendations (screen readers, cognitive load, plain language)" + - "Use research-backed benchmarks (8-14 words for comprehension, 40-60 chars per line, 7th-10th grade reading level)" + - "Apply appropriate patterns for UI elements (buttons use imperative verbs, errors include solution, etc.)" + - "Adapt tone to user emotional state (frustrated, confused, confident, cautious, successful)" + - "Always explain WHY changes improve the text (reference standards and research)" + - "When creating new copy, gather context first: user goals, emotional state, stakes, constraints" + - "Maintain consistent voice while adapting tone to specific situations" + - "Provide multiple variations when brainstorming to give users options" + - "Front-load important information in all interface copy" + - "Use active voice 85% of the time" + - "Keep critical instructions to 8-14 words for maximum comprehension" + - "Never blame users in error messages - be empathetic and solution-focused" + +quality_standards_detail: + Purposeful: + definition: "Text helps users or business achieve goals" + questions: + - "Does this help the user accomplish their goal?" + - "Does it serve a business objective?" + - "Is the value to the user clear?" + - "Are user concerns anticipated and addressed?" + scoring: + high: "9-10: Clear user benefit, addresses concerns, advances goals" + medium: "5-8: Some user benefit but could be more targeted" + low: "1-4: Unclear purpose or doesn't help user/business" + + Concise: + definition: "Uses fewest words possible without losing meaning" + questions: + - "Can any words be removed without losing meaning?" + - "Is information front-loaded?" + - "Does every word earn its space?" + - "Could this be shorter and still clear?" + benchmarks: + buttons: "2-4 words ideal, 6 maximum" + errors: "12-18 words including solution" + instructions: "14 words ideal, 20 maximum" + titles: "3-6 words, 40 characters maximum" + scoring: + high: "9-10: No wasted words, perfectly concise" + medium: "5-8: Generally concise but some redundancy" + low: "1-4: Verbose, needs significant trimming" + + Conversational: + definition: "Sounds natural and human, not robotic" + questions: + - "Would you say this out loud?" + - "Does it use active voice?" + - "Are there natural connecting words?" + - "Is it free of corporate jargon?" + guidelines: + - "Use active voice 85% of the time" + - "Include prepositions and articles" + - "Write how you speak" + - "Avoid robotic phrasing" + scoring: + high: "9-10: Natural, human, conversational" + medium: "5-8: Mostly natural with some stiffness" + low: "1-4: Robotic, corporate, unnatural" + + Clear: + definition: "Unambiguous, accurate, easy to understand" + questions: + - "Is there only one way to interpret this?" + - "Are verbs specific and meaningful?" + - "Is terminology consistent?" + - "Does it meet readability targets?" + guidelines: + - "Use plain language (7th-10th grade reading level)" + - "Avoid jargon and technical terms" + - "Use consistent terminology" + - "Choose specific, accurate verbs" + scoring: + high: "9-10: Crystal clear, unambiguous, accurate" + medium: "5-8: Generally clear with minor ambiguities" + low: "1-4: Confusing, ambiguous, unclear" + +pattern_reference: + buttons: + format: "[Verb] [object]" + style: "Active imperative verbs, sentence case" + examples: ["Save changes", "Delete account", "View details"] + avoid: ["OK", "Submit", "Click here"] + + error_messages: + format: "[What failed]. [Why/context]. [What to do]." + types: + inline: "Brief correction guidance (e.g., 'Email must include @')" + detour: "Problem + solution (e.g., 'Payment failed. Check card details and try again.')" + blocking: "Clear explanation + timeline (e.g., 'Update required. Install latest version to continue.')" + principles: + - "Never blame user" + - "Be empathetic and solution-focused" + - "Provide clear recovery path" + + empty_states: + format: "Explanation + CTA to populate" + types: + first_use: "Guide user to add first item" + user_cleared: "Celebrate completion" + no_results: "Suggest alternative search" + example: "No messages yet. Start a conversation to connect with your team." + + success_messages: + format: "[Action] [result/benefit]" + style: "Past tense, specific, encouraging" + examples: ["Changes saved", "Email sent", "Profile updated"] + + form_fields: + label: "Clear noun phrase (e.g., 'Email address')" + instructions: "Verb-first, explain why needed" + placeholder: "Use sparingly, standard inputs only" + helper: "Static, on-demand, or automatic based on importance" + +accessibility_standards: + screen_readers: + - "Label all interactive elements explicitly" + - "Write descriptive link text (not 'Click here')" + - "Structure errors to work with field labels" + - "Use ARIA labels when visual context insufficient" + + cognitive: + - "Target 8-14 words per sentence for critical content" + - "Break complex info into scannable chunks" + - "Use clear headings and logical hierarchy" + - "Provide consistent, predictable patterns" + + multi_modal: + - "Don't rely on color alone for meaning" + - "Pair visual indicators with text" + - "Provide text alternatives for icons" + - "Ensure sufficient contrast (4.5:1 minimum)" + + plain_language: + - "Target 7th-8th grade for general audience" + - "Define technical terms on first use" + - "Avoid idioms and cultural references" + - "Use common, everyday words" + +tone_adaptation: + frustrated: + context: "Errors, failures, blockers" + approach: "Empathetic and solution-focused" + example: "Payment failed. Your card was declined. Try a different payment method." + + confused: + context: "First use, complex features" + approach: "Patient and explanatory" + example: "Connect your bank to see spending insights. We'll guide you through it." + + confident: + context: "Routine tasks, return visits" + approach: "Efficient and direct" + example: "Saved" + + cautious: + context: "High-stakes actions, data loss" + approach: "Serious and transparent" + example: "Delete account? You'll lose all data and this can't be undone." + + successful: + context: "Completions, achievements" + approach: "Positive and encouraging" + example: "Profile updated. Your changes are live." + +workflow_process: + understand: + - "User goals and needs" + - "Business objectives" + - "Technical constraints" + - "Emotional state of user" + + draft: + - "Start with conversation (what would you say?)" + - "Apply appropriate pattern" + - "Consider voice and tone" + - "Front-load important information" + + edit_phases: + phase_1: "Purposeful - Does it help user achieve goals?" + phase_2: "Concise - Remove unnecessary words" + phase_3: "Conversational - Read aloud test" + phase_4: "Clear - Specific verbs, consistent terminology" + + validate: + - "Score against four standards" + - "Check accessibility compliance" + - "Verify benchmarks (length, reading level)" + - "Test with users when possible" +``` + +## Welcome Message + +Hello! I'm Alex, your UX Writing Specialist. I help create clear, user-centered interface copy (microcopy) for digital products using the Four Quality Standards framework: Purposeful, Concise, Conversational, and Clear. + +I can help you: +- **Analyze** existing UI text with quality scoring +- **Create** new interface copy for buttons, errors, empty states, and more +- **Improve** existing text with before/after comparisons +- **Audit** entire flows for consistency and quality +- **Establish** product voice and tone guidelines +- **Ensure** accessibility compliance + +Type `*help` to see all available commands, or just describe what you need help with! + +**Quick starts:** +- "Analyze this button text: [your text]" +- "Help me write an error message for [situation]" +- "Review this form for accessibility" +- "Let's create a voice chart for our product" diff --git a/src/modules/ux-writer/data/accessibility-guidelines.md b/src/modules/ux-writer/data/accessibility-guidelines.md new file mode 100644 index 00000000..60d3fc26 --- /dev/null +++ b/src/modules/ux-writer/data/accessibility-guidelines.md @@ -0,0 +1,390 @@ +# Accessibility Guidelines for UX Writing + +Writing accessible content ensures all usersβ€”including those using assistive technology, experiencing cognitive differences, or facing situational limitationsβ€”can understand and interact with your product. + +## Core Principles + +### 1. Perceivable +Users must be able to perceive the information being presented. + +**For UX Writers:** +- Provide text alternatives for non-text content +- Don't rely on color alone to convey meaning +- Ensure sufficient color contrast (WCAG AA: 4.5:1 for body text, 3:1 for large text) +- Write clear, descriptive labels for all interactive elements + +### 2. Operable +Users must be able to operate the interface. + +**For UX Writers:** +- Write clear button labels that describe the action +- Provide skip links for navigation ("Skip to main content") +- Write descriptive link text (not "click here") +- Use consistent terminology for navigation + +### 3. Understandable +Users must be able to understand the information and interface. + +**For UX Writers:** +- Use plain language (7th-8th grade reading level) +- Keep sentences short (8-14 words for critical content) +- Define technical terms on first use +- Provide clear instructions and error messages + +### 4. Robust +Content must work with current and future assistive technologies. + +**For UX Writers:** +- Write proper labels for form fields +- Structure content with clear headings +- Use semantic HTML-friendly language +- Ensure error messages are programmatically associated with fields + +--- + +## Screen Reader Optimization + +### How Screen Readers Work +Screen readers announce content linearly, reading: +1. Element type (button, link, heading, form field) +2. Label or text content +3. State (expanded, collapsed, selected, required) + +### Writing for Screen Readers + +**Buttons** +- ❌ Poor: "Submit" (context missing) +- βœ… Good: "Submit application" +- βœ… Better: "Submit job application" + +**Links** +- ❌ Poor: "Click here to learn more" +- ❌ Poor: "Read more" (about what?) +- βœ… Good: "Learn about our privacy policy" +- βœ… Good: "View pricing details" + +**Form Fields** +- ❌ Poor: Placeholder text as only label +- βœ… Good: Visible label + optional placeholder +- βœ… Example: Label: "Email address", Placeholder: "name@example.com" + +**Error Messages** +Screen readers read the field label + error message together, so write errors that make sense in that context. +- ❌ Poor: "Invalid" (announced as "Email address, invalid") +- βœ… Good: "Must include @" (announced as "Email address, must include @") +- βœ… Better: "Email must include @" (complete sentence) + +**Images and Icons** +- Write meaningful alt text that conveys purpose +- ❌ Poor: "image.png" +- ❌ Poor: "icon" +- βœ… Good: "Success" (for checkmark icon) +- βœ… Good: "Error: Payment failed" (for error icon) + +**ARIA Labels** +Use ARIA labels when visual context isn't available to screen readers: +- Search button with only magnifying glass icon: aria-label="Search" +- Close button with only X icon: aria-label="Close dialog" +- Social media links with only icons: aria-label="Visit us on Twitter" + +--- + +## Cognitive Accessibility + +### Comprehension Research +- **8 words or fewer**: 100% comprehension +- **14 words or fewer**: 90% comprehension +- **25+ words**: Comprehension drops significantly + +### Best Practices + +**Keep Sentences Short** +- Critical instructions: 8-14 words maximum +- Error messages: 12-18 words (including solution) +- General content: 15-20 words average +- Complex explanations: Break into multiple short sentences + +**Use Simple Language** +- Choose common words over complex ones + - ❌ "Utilize" β†’ βœ… "Use" + - ❌ "Purchase" β†’ βœ… "Buy" + - ❌ "Terminate" β†’ βœ… "End" +- Avoid jargon unless your audience expects it +- Define technical terms on first use + +**Create Scannable Content** +- Use clear headings (H1, H2, H3 hierarchy) +- Break content into short paragraphs (3-4 lines max) +- Use bulleted lists for related items +- Front-load important information + +**Provide Consistent Patterns** +- Use the same words for the same actions +- Place elements in predictable locations +- Follow established UI patterns +- Reduce cognitive load in high-stress moments (errors, confirmations) + +**Reduce Memory Load** +- Don't make users remember information from previous screens +- Repeat critical information when needed +- Provide context at the point of action +- Use progressive disclosure for complex flows + +--- + +## Plain Language Guidelines + +### Reading Level Targets + +**General Public** +- Target: 7th-8th grade (Flesch-Kincaid) +- Sentence length: 15-20 words average +- Word choice: Common, everyday words + +**Professional Tools** +- Target: 9th-10th grade +- Sentence length: 20-25 words maximum +- Word choice: Industry terms okay if audience expects them + +**Technical Products** +- Target: 10th-11th grade +- Sentence length: 25 words maximum +- Word choice: Technical terms with clear definitions + +### Plain Language Techniques + +**Active Voice (85% of the time)** +- ❌ Passive: "Your account was created" +- βœ… Active: "We created your account" +- ❌ Passive: "Payment will be processed" +- βœ… Active: "We'll process your payment" + +**Concrete Verbs** +- ❌ Weak: "Make a selection" +- βœ… Strong: "Choose" +- ❌ Weak: "Provide notification" +- βœ… Strong: "Notify" + +**Positive Framing** +- ❌ Negative: "Don't forget to save" +- βœ… Positive: "Remember to save" +- ❌ Negative: "You can't proceed without..." +- βœ… Positive: "To proceed, please..." + +**Avoid Idioms and Metaphors** +These don't translate well and confuse non-native speakers: +- ❌ "Get the ball rolling" +- ❌ "Think outside the box" +- ❌ "Hit the ground running" +- βœ… Use literal language instead + +--- + +## Multi-Modal Communication + +### Don't Rely on Color Alone + +**Bad Example:** +- Red text: "Email" +- (Users with color blindness can't distinguish the error) + +**Good Example:** +- "Error: Email must include @" + red icon +- (Text provides meaning independent of color) + +### Redundant Cues + +Provide multiple ways to perceive important information: + +**Status Messages** +- Color + icon + text +- Example: Green checkmark + "Success: Changes saved" + +**Required Fields** +- Asterisk + "required" label + error on submission +- Example: "Email address *" with note "* Required field" + +**Error States** +- Color + icon + error message + border +- Example: Red border + error icon + "Email must include @" + +**Links vs Plain Text** +- Color + underline (or other visual distinction) +- Ensure 3:1 contrast ratio between link and body text + +--- + +## Forms and Input Accessibility + +### Labels + +**Always Visible** +- Don't hide labels on focus +- Don't use placeholder as only label +- Keep labels adjacent to fields + +**Clear and Descriptive** +- ❌ Poor: "Name" +- βœ… Good: "Full name" +- βœ… Better: "Full name (as it appears on your ID)" + +### Instructions + +**Provide Before Input** +- Explain requirements before user types +- Keep instructions visible as user completes field + +**Be Specific** +- ❌ Vague: "Enter valid email" +- βœ… Specific: "Email must include @" +- βœ… Example: "Email (you@example.com)" + +### Error Messages + +**Pattern: [What's wrong]. [How to fix].** +- ❌ "Invalid" +- ❌ "Error" +- βœ… "Email must include @" +- βœ… "Password must be at least 8 characters" + +**Timing** +- Inline validation: Show after user completes field +- Form-level: Show on submit, with focus moved to first error +- Real-time: Only for format requirements (password strength) + +**Location** +- Place error message near the field (above or below) +- Ensure screen readers announce error with field label +- Maintain error message while user corrects input + +--- + +## Writing for Translation + +### Keep It Simple +- Short sentences translate more accurately +- Simple grammar reduces translation errors +- Common words have clearer equivalents + +### Avoid Culturally-Specific References +- ❌ "Home run" (baseball reference) +- ❌ "The ball is in your court" (idiom) +- ❌ "During the holidays" (varies by culture) +- βœ… Use universal concepts + +### Plan for Text Expansion +Text expands in translation: +- German: +30-40% +- French/Spanish: +15-20% +- Italian/Portuguese: +20-25% + +**Design Implications:** +- Buttons: Allow for 150-200% text expansion +- Titles: Plan for 130-150% expansion +- Character limits: Test with longest likely translation + +### Gender-Neutral Language +- Use "they/them" for unknown subjects +- Avoid gendered job titles + - ❌ "Policeman" β†’ βœ… "Police officer" + - ❌ "Stewardess" β†’ βœ… "Flight attendant" +- Structure sentences to avoid gender assumptions + +--- + +## High-Stress Context Accessibility + +Users experiencing stress, frustration, or urgency have reduced cognitive capacity. + +### Error Messages +- **Be immediately clear**: State the problem upfront +- **Provide quick recovery**: One-step solution when possible +- **Avoid blame**: Never use judgmental language +- **Stay calm**: Reassuring tone without being condescending + +### Time-Sensitive Actions +- **Clear deadlines**: Specific times, not "soon" +- **Visible countdown**: "5 minutes remaining" +- **Obvious actions**: Bold, clear CTAs + +### High-Stakes Decisions +- **Transparent consequences**: "You'll lose all data" +- **Reversibility**: State if action can be undone +- **Easy exit**: Clear "Cancel" or "Go back" options + +--- + +## Testing for Accessibility + +### Automated Tools +- **WAVE**: Web accessibility evaluation tool +- **axe DevTools**: Browser extension for accessibility testing +- **Lighthouse**: Built into Chrome DevTools + +### Manual Testing + +**Screen Reader Test** +- Turn on VoiceOver (Mac) or NVDA (Windows) +- Navigate using keyboard only +- Verify all content is announced meaningfully +- Check that error messages are clear when announced + +**Readability Test** +- Hemingway Editor: Highlights complex sentences +- Readable.com: Multiple readability scores +- Microsoft Word: Flesch-Kincaid scoring + +**Color Contrast Test** +- WebAIM Contrast Checker +- Verify 4.5:1 for body text +- Verify 3:1 for large text and UI elements + +**Keyboard Navigation Test** +- Unplug your mouse +- Complete all tasks using only keyboard +- Verify all interactive elements are reachable +- Check that focus order is logical + +--- + +## Quick Reference Checklist + +### Before Publishing Any UX Text + +- [ ] All interactive elements have clear, descriptive labels +- [ ] Links describe destination ("View pricing" not "Click here") +- [ ] Error messages are specific and actionable +- [ ] Color is not the only indicator of meaning +- [ ] Text has sufficient contrast (4.5:1 minimum) +- [ ] Sentences average 15-20 words or fewer +- [ ] Reading level is appropriate for audience +- [ ] No idioms, metaphors, or cultural references +- [ ] Required fields are marked with more than just color +- [ ] Form instructions appear before input fields +- [ ] Success and error states include text, not just icons + +--- + +## Resources + +### WCAG Guidelines +- [WCAG 2.1 Quick Reference](https://www.w3.org/WAI/WCAG21/quickref/) +- [Understanding WCAG Success Criteria](https://www.w3.org/WAI/WCAG21/Understanding/) + +### Testing Tools +- [WAVE Web Accessibility Evaluation Tool](https://wave.webaim.org/) +- [Hemingway Editor](http://hemingwayapp.com/) +- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) + +### Plain Language +- [PlainLanguage.gov](https://www.plainlanguage.gov/) +- [Readable.com](https://readable.com/) + +### Screen Readers +- VoiceOver (Mac/iOS): Built-in +- NVDA (Windows): Free download +- JAWS (Windows): Commercial + +--- + +**Remember**: Accessibility isn't a featureβ€”it's a baseline requirement. Writing accessibly makes your product better for everyone, not just users with disabilities. diff --git a/src/modules/ux-writer/data/content-usability-checklist.md b/src/modules/ux-writer/data/content-usability-checklist.md new file mode 100644 index 00000000..594d7967 --- /dev/null +++ b/src/modules/ux-writer/data/content-usability-checklist.md @@ -0,0 +1,158 @@ +# Content Usability Checklist + +Use this checklist to evaluate UX text quality. Rate each criterion 0-10. + +## Concise + +**Every word has a distinct job** +- No filler words like "basically", "actually", "just" +- Each word adds meaning or clarity +- Can't remove words without losing meaning + +**High information density in minimal words** +- Maximum meaning per word +- Efficient phrasing +- No redundancy + +**40-60 characters per line** +- Optimal line length for readability +- Breaks appropriately for scanning +- Not too long (causes focus loss) or too short (causes back-and-forth eye movement) + +**Short sentences and paragraphs** +- Less than 3-4 lines per paragraph +- Sentences vary in length but average ~15-20 words +- Broken into scannable chunks + +**Front-loaded with signal words** +- Most important words come first +- Action words at start of sentences +- Users see key information immediately + +**Ideas ordered by priority** +- Most critical information first +- Secondary details follow +- Nice-to-know information last + +## Purposeful + +**User goals are clear and supported** +- Text helps users complete their task +- Addresses user's "why am I here?" question +- Removes barriers to action + +**Business goals are met** +- Supports conversion, engagement, or retention +- Aligns with product objectives +- Advances organizational goals + +**Brand voice is reflected** +- Consistent with brand personality +- Recognizable as coming from this product +- Uses appropriate tone for context + +**Value proposition is evident** +- User benefit is clear +- Explains "what's in it for me?" +- Shows value before asking for action + +**Subject matter focuses on user benefit** +- Written in second person ("you") +- Emphasizes outcomes, not features +- User-centered, not company-centered + +**Active, inviting framing** +- Motivates action without being pushy +- Matches user's intention and journey stage +- Appropriate level of urgency + +## Conversational + +**Natural, spoken language** +- Sounds like something you'd say aloud +- Flows naturally when read +- Not stiff or overly formal + +**Active voice predominates** +- Subject performs the action +- Direct and energetic +- Use passive only when it's clearer (rare cases) + +**Connecting words included** +- Prepositions present ("to", "from", "with") +- Articles included ("a", "an", "the") +- Not telegraphic or robotic + +**Familiar words and phrases** +- Uses language your users use +- Based on user research and testing +- No unnecessary technical jargon + +**Personality in appropriate moments** +- Voice shines through when context allows +- Not overly serious in light contexts +- Not playful in serious moments + +## Clear + +**Accurate action words** +- Specific verbs that describe the action +- "Delete" not "Remove" for permanent deletion +- "Save" not "OK" for saving changes + +**Command forms used appropriately** +- Active imperative for buttons +- Clear, direct instructions +- Action-oriented language + +**Plain language** +- 7th grade reading level for general audience +- 10th grade for professional contexts +- Avoids complex vocabulary and sentence structures + +**Meaningful, descriptive titles** +- Titles tell you where you are +- Not generic or vague +- Provide context and orientation + +**Consistent patterns and terminology** +- Same word means same thing throughout +- UI patterns applied consistently +- Terminology documented in style guide + +## Scoring Guide + +**9-10**: Excellent β€” Best practice example +**7-8**: Good β€” Minor improvements possible +**5-6**: Adequate β€” Notable issues to address +**3-4**: Needs work β€” Significant problems +**0-2**: Poor β€” Major revision required + +## How to Use This Checklist + +1. **Review individual pieces** β€” Evaluate specific UI strings, messages, or flows +2. **Audit entire experiences** β€” Score major screens or user journeys +3. **Compare options** β€” Rate different versions to choose the best +4. **Track improvements** β€” Measure before and after edits +5. **Build rationale** β€” Use scores to explain writing decisions +6. **Focus efforts** β€” Identify lowest-scoring areas to improve first + +## Example Evaluation + +**Text**: "An error occurred while processing your request. Please try again." + +**Concise**: 6/10 β€” Wordy, could be "We couldn't process your request. Try again." +**Purposeful**: 4/10 β€” Doesn't help user fix the problem or explain what happened +**Conversational**: 5/10 β€” Somewhat robotic, "an error occurred" is system-speak +**Clear**: 5/10 β€” Vague, doesn't specify what error or why + +**Overall**: 5/10 β€” Adequate but needs significant improvement + +**Improved**: "We couldn't save your changes. Check your connection and try again." + +**Concise**: 9/10 β€” Brief, direct, no wasted words +**Purposeful**: 8/10 β€” Suggests likely cause (connection) and next step +**Conversational**: 9/10 β€” Natural, human phrasing +**Clear**: 9/10 β€” Specific about what failed and what to do + +**Overall**: 9/10 β€” Excellent diff --git a/src/modules/ux-writer/data/four-quality-standards.md b/src/modules/ux-writer/data/four-quality-standards.md new file mode 100644 index 00000000..4043a428 --- /dev/null +++ b/src/modules/ux-writer/data/four-quality-standards.md @@ -0,0 +1,468 @@ +# The Four Quality Standards Framework + +A comprehensive framework for evaluating and creating effective UX text based on four measurable quality standards. + +## Overview + +The Four Quality Standards provide an objective, research-backed framework for UX writing. Every piece of interface copy should be evaluated against these standards: + +1. **Purposeful** - Helps users or the business achieve goals +2. **Concise** - Uses the fewest words possible without losing meaning +3. **Conversational** - Sounds natural and human, not robotic +4. **Clear** - Unambiguous, accurate, and easy to understand + +## 1. Purposeful + +### Definition +Text that helps users accomplish their goals or advances business objectives. Every word should have a clear purpose. + +### Evaluation Questions +- Does this help the user accomplish their goal? +- Does it serve a business objective? +- Is the value to the user clear? +- Are user concerns anticipated and addressed? +- Does it answer the question "What's in it for me?" + +### Scoring Rubric (0-10) + +**9-10: Excellent** +- Clear, immediate user benefit +- Anticipates and addresses user concerns +- Advances both user and business goals +- Value proposition is explicit + +**7-8: Good** +- User benefit present but could be more prominent +- Addresses most user concerns +- Serves goals but could be more targeted + +**5-6: Adequate** +- Some user benefit +- Generic value proposition +- Doesn't fully address user concerns + +**3-4: Needs Work** +- Unclear purpose +- Doesn't obviously help user +- System-focused rather than user-focused + +**1-2: Poor** +- No discernible user benefit +- Creates confusion about purpose +- Purely system/business focused + +**0: Unacceptable** +- Actively hinders user goals +- No apparent purpose + +### Examples + +**Low Purposeful (3/10):** +"Click here" +- What happens when I click? +- Why should I click? +- Where does it lead? + +**High Purposeful (9/10):** +"Download pricing guide" +- Clear action (download) +- Clear benefit (get pricing info) +- Specific object (the guide) + +--- + +## 2. Concise + +### Definition +Uses the minimum number of words needed to convey meaning clearly. Every word must earn its place. + +### Evaluation Questions +- Can any words be removed without losing meaning? +- Is information front-loaded (most important first)? +- Does every word earn its space? +- Could this be shorter and still clear? +- Are there redundant phrases? + +### Research-Backed Benchmarks + +**By UI Element:** +- **Buttons/CTAs**: 2-4 words ideal, 6 word maximum +- **Titles**: 3-6 words, 40 characters maximum +- **Error messages**: 12-18 words (including solution) +- **Instructions**: 20 words maximum, 14 ideal +- **Body copy**: 15-20 words per sentence average +- **Notifications**: 10-15 words for title + body + +**Comprehension Rates:** +- 8 words or fewer: 100% user comprehension +- 14 words or fewer: 90% user comprehension +- 25 words: Maximum before significant drop + +**Character & Line Length:** +- Line length: 40-60 characters for maximum readability +- Button labels: 15-25 characters +- Page titles: 30-50 characters +- Notification titles: 35-45 characters + +### Scoring Rubric (0-10) + +**9-10: Excellent** +- No wasted words +- Perfectly concise for the pattern +- Meets or beats benchmark +- Front-loaded key information + +**7-8: Good** +- Generally concise +- Minor redundancies +- Close to benchmark +- Mostly front-loaded + +**5-6: Adequate** +- Some unnecessary words +- Could be tighter +- Slightly over benchmark +- Some buried information + +**3-4: Needs Work** +- Verbose +- Significant redundancies +- Well over benchmark +- Key info buried + +**1-2: Poor** +- Extremely wordy +- Many unnecessary phrases +- Far exceeds benchmarks +- Difficult to scan + +**0: Unacceptable** +- Incomprehensibly verbose + +### Examples + +**Low Concise (4/10):** +"Please be advised that your request has been received and is currently being processed by our team." (17 words) +- "Please be advised that" = 4 wasted words +- "currently being" = unnecessary qualifiers +- Passive voice adds words + +**High Concise (9/10):** +"We're processing your request." (4 words) +- Active voice +- No wasted words +- Clear and direct +- 76% shorter + +--- + +## 3. Conversational + +### Definition +Sounds natural and human, as if you're speaking directly to someone. Not robotic or overly formal. + +### Evaluation Questions +- Would you actually say this out loud? +- Does it use active voice? +- Are there natural connecting words (prepositions, articles)? +- Is it free of corporate jargon and buzzwords? +- Does it feel human? + +### Guidelines + +**Active vs. Passive Voice:** +- Target: 85% active voice +- Active: "We sent your email" (clear actor) +- Passive: "Your email has been sent" (no clear actor) + +**Natural Language Indicators:** +- Includes articles (a, an, the) +- Includes prepositions (to, from, with) +- Uses contractions appropriately (we'll, you're, can't) +- Avoids formal constructions ("kindly", "please be advised") + +**Anti-Patterns to Avoid:** +- "An error has occurred" +- "Your request has been received" +- "Please be advised that" +- "Kindly note that" +- "We are pleased to inform you" + +### Scoring Rubric (0-10) + +**9-10: Excellent** +- Completely natural +- Would say this in person +- Active voice throughout +- Human and warm + +**7-8: Good** +- Mostly natural +- Minor stiffness +- Mostly active voice +- Generally conversational + +**5-6: Adequate** +- Some natural elements +- Mix of active/passive +- Some corporate phrases +- Readable but not warm + +**3-4: Needs Work** +- Stiff and formal +- Heavy passive voice +- Corporate jargon +- Robotic tone + +**1-2: Poor** +- Extremely robotic +- All passive voice +- Heavy jargon +- Unnatural phrasing + +**0: Unacceptable** +- Incomprehensible jargon + +### Examples + +**Low Conversational (3/10):** +"Your payment transaction has been successfully processed and a confirmation has been sent to your registered email address." +- All passive voice +- Formal, robotic +- Wouldn't say this aloud +- Corporate tone + +**High Conversational (9/10):** +"Payment complete. We sent a confirmation to your email." +- Active voice ("we sent") +- Natural, direct +- How you'd actually speak +- Human tone + +--- + +## 4. Clear + +### Definition +Unambiguous and easy to understand. Uses specific language that's accessible to the target audience. + +### Evaluation Questions +- Is there only one way to interpret this? +- Are verbs specific and meaningful? +- Is terminology consistent with the product? +- Does it meet readability targets? +- Could it be misunderstood? + +### Reading Level Guidelines + +**By Audience:** +- **General public**: 7th-8th grade (Flesch-Kincaid) +- **Professional tools**: 9th-10th grade +- **Technical products**: 10th-11th grade +- **Specialized fields**: 11th-12th grade (only when necessary) + +**Testing Tools:** +- Hemingway Editor: Highlights complex sentences +- Readable.com: Multiple readability scores +- Microsoft Word: Built-in Flesch-Kincaid scoring + +### Clarity Best Practices + +**Use Specific Verbs:** +- ❌ Generic: "Process", "Handle", "Manage" +- βœ… Specific: "Send", "Delete", "Create" + +**Avoid Ambiguity:** +- ❌ "Update soon" (when?) +- βœ… "Update in 5 minutes" +- ❌ "Several items" (how many?) +- βœ… "3 items" + +**Plain Language:** +- Use common words over complex ones +- ❌ "Utilize" β†’ βœ… "Use" +- ❌ "Terminate" β†’ βœ… "End" +- ❌ "Purchase" β†’ βœ… "Buy" + +**Consistent Terminology:** +- Pick one term and stick with it +- Don't alternate between "remove" and "delete" +- Don't switch between "save" and "submit" + +### Scoring Rubric (0-10) + +**9-10: Excellent** +- Crystal clear +- Unambiguous +- Perfect terminology +- Ideal reading level +- Specific verbs + +**7-8: Good** +- Generally clear +- Minor ambiguities +- Good terminology +- Appropriate reading level +- Mostly specific verbs + +**5-6: Adequate** +- Understandable +- Some ambiguity +- Inconsistent terminology +- Slightly high reading level +- Some generic verbs + +**3-4: Needs Work** +- Confusing in places +- Significant ambiguity +- Poor terminology +- Too high reading level +- Generic verbs + +**1-2: Poor** +- Very confusing +- Highly ambiguous +- Jargon-heavy +- Far too complex +- Vague language + +**0: Unacceptable** +- Incomprehensible + +### Examples + +**Low Clear (4/10):** +"Please proceed to finalize your transaction at your earliest convenience." +- "Proceed to finalize" = jargon +- "At your earliest convenience" = vague timing +- "Transaction" = generic +- High reading level + +**High Clear (9/10):** +"Complete your purchase now." +- "Complete" = specific action +- "Purchase" = clear object +- "Now" = clear timing +- Simple, direct language + +--- + +## Applying the Framework + +### Step-by-Step Process + +**1. Draft the text** +- Start with conversation: what would you say? +- Don't worry about perfection yet + +**2. Edit for Purposeful** +- Is user benefit clear? +- Are concerns addressed? +- Does it advance goals? + +**3. Edit for Concise** +- Remove unnecessary words +- Front-load key information +- Check against benchmarks + +**4. Edit for Conversational** +- Read aloud: would you say this? +- Convert passive to active +- Remove corporate speak + +**5. Edit for Clear** +- Use specific verbs +- Check reading level +- Eliminate ambiguity + +**6. Score and validate** +- Score each standard 0-10 +- Average for overall score +- Target: 8+ overall + +### Overall Scoring + +**Calculate Average:** +(Purposeful + Concise + Conversational + Clear) Γ· 4 = Overall Score + +**Quality Benchmarks:** +- **9-10**: Excellent - Ship it +- **8-8.9**: Very Good - Minor tweaks only +- **7-7.9**: Good - Consider improvements +- **6-6.9**: Adequate - Needs work +- **Below 6**: Poor - Requires significant revision + +### When Standards Conflict + +Sometimes improving one standard slightly reduces another. Prioritize based on context: + +**High-stakes actions (delete, payment):** +- Prioritize: Clear > Purposeful > Concise > Conversational +- Better to be thorough than brief + +**Routine actions (save, send):** +- Prioritize: Concise > Clear > Conversational > Purposeful +- Users want efficiency + +**First-time use:** +- Prioritize: Purposeful > Clear > Conversational > Concise +- Users need guidance + +**Error states:** +- Prioritize: Purposeful > Conversational > Clear > Concise +- Users need empathy and solutions + +## Common Patterns & Expected Scores + +### Excellent Button (9/10) +"Delete account" +- Purposeful: 10/10 (clear action) +- Concise: 10/10 (2 words) +- Conversational: 8/10 (imperative form) +- Clear: 10/10 (specific verb) + +### Excellent Error (9/10) +"Payment failed. Check your card and try again." +- Purposeful: 9/10 (problem + solution) +- Concise: 9/10 (8 words) +- Conversational: 9/10 (active, empathetic) +- Clear: 9/10 (specific guidance) + +### Excellent Empty State (9/10) +"No messages yet. Start a conversation to connect." +- Purposeful: 9/10 (clear benefit) +- Concise: 10/10 (8 words) +- Conversational: 9/10 (encouraging) +- Clear: 9/10 (specific action) + +## Resources & References + +This framework is based on: +- Sarah Richards: "Content Design" +- Torrey Podmajersky: "Strategic Writing for UX" +- Google Material Design guidelines +- Nielsen Norman Group research +- WCAG accessibility standards +- Flesch-Kincaid readability research + +## Quick Reference Card + +**Purposeful:** +βœ… User benefit clear +βœ… Addresses concerns +βœ… Advances goals + +**Concise:** +βœ… No wasted words +βœ… Front-loaded +βœ… Meets benchmarks + +**Conversational:** +βœ… Natural language +βœ… Active voice +βœ… Human tone + +**Clear:** +βœ… Unambiguous +βœ… Specific verbs +βœ… Appropriate reading level diff --git a/src/modules/ux-writer/data/patterns-detailed.md b/src/modules/ux-writer/data/patterns-detailed.md new file mode 100644 index 00000000..18252303 --- /dev/null +++ b/src/modules/ux-writer/data/patterns-detailed.md @@ -0,0 +1,426 @@ +# UX Text Patterns β€” Detailed Examples + +This document provides extended examples of common UX text patterns applied across three different product voices: TAPP Transit (helpful, efficient, trustworthy), 'appee Social Game (playful, competitive, rewarding), and Sturgeon Club (sophisticated, exclusive, elegant). + +## Titles + +### Brand Title +Identifies the product/organization + +**TAPP Transit**: "TAPP" +**'appee**: "'appee" +**Sturgeon Club**: "The Sturgeon Club" + +### Content Title +Reflects what's on the screen + +**TAPP Transit**: "Your routes", "Bus schedule", "Payment methods" +**'appee**: "Your photos", "Leaderboard", "Daily challenge" +**Sturgeon Club**: "Your reservations", "Member directory", "Event calendar" + +### Category Title (Ambiguous Task) +Covers multiple related actions + +**TAPP Transit**: "Trip planning", "Account settings", "Help and support" +**'appee**: "Profile settings", "Game stats", "Photo gallery" +**Sturgeon Club**: "Membership benefits", "Venue access", "Concierge services" + +### Task Title (Single Action) +Acts as instruction for one task + +**TAPP Transit**: "Buy a day pass", "Report a problem", "Change your email" +**'appee**: "Upload a photo", "Vote on photos", "Invite a friend" +**Sturgeon Club**: "Reserve a table", "Update your preferences", "Download your invoice" + +--- + +## Buttons + +### Primary Actions + +**TAPP Transit**: +- "Buy pass" +- "Track bus" +- "Plan trip" +- "Report issue" + +**'appee**: +- "Upload photo" +- "Vote now" +- "Challenge friend" +- "Claim reward" + +**Sturgeon Club**: +- "Reserve table" +- "View details" +- "Confirm attendance" +- "Request service" + +### Secondary Actions + +**TAPP Transit**: +- "View schedule" +- "Cancel" +- "Go back" +- "Skip" + +**'appee**: +- "See rules" +- "Maybe later" +- "Pass" +- "View profile" + +**Sturgeon Club**: +- "Learn more" +- "Decline" +- "Return" +- "Not now" + +### Destructive Actions + +**TAPP Transit**: +- "Delete payment method" +- "Cancel trip" +- "Remove favorite" + +**'appee**: +- "Delete photo" +- "Leave game" +- "Remove friend" + +**Sturgeon Club**: +- "Cancel reservation" +- "Remove guest" +- "Close account" + +--- + +## Links + +### Navigational Links + +**TAPP Transit**: +- "See all routes" +- "View trip history" +- "Check real-time updates" + +**'appee**: +- "Browse all challenges" +- "See your stats" +- "View friend activity" + +**Sturgeon Club**: +- "Explore member benefits" +- "View upcoming events" +- "Access your membership card" + +### Contextual Links + +**TAPP Transit**: +- "Learn about fare options" +- "Get help with passes" +- "Contact support" + +**'appee**: +- "How scoring works" +- "Tips for better photos" +- "Report a problem" + +**Sturgeon Club**: +- "Terms of membership" +- "Dress code requirements" +- "Concierge contacts" + +--- + +## Error Messages + +### Inline Errors + +**TAPP Transit**: +- "Email must include @" +- "Card number is incomplete" +- "Pick a future date" + +**'appee**: +- "Username already taken" +- "Photo must be under 10MB" +- "Needs at least 3 characters" + +**Sturgeon Club**: +- "Email address required" +- "Valid phone number required" +- "Select a date" + +### Detour Errors + +**TAPP Transit**: +**Title**: "Can't buy pass" +**Body**: "Your payment didn't go through. Check your card details and try again." +**Action**: "Update card" + +**'appee**: +**Title**: "Upload failed" +**Body**: "Your photo couldn't be uploaded. Check your connection and try again." +**Action**: "Retry upload" + +**Sturgeon Club**: +**Title**: "Reservation unavailable" +**Body**: "This time slot is no longer available. Please select another time." +**Action**: "Choose different time" + +### Blocking Errors + +**TAPP Transit**: +**Title**: "Service temporarily unavailable" +**Body**: "We're updating our systems and will be back online in about 15 minutes. Your saved trips and passes are safe." +**Action**: "Check status" + +**'appee**: +**Title**: "Update required" +**Body**: "You need the latest version of 'appee to continue playing. Update now to access new challenges and features." +**Action**: "Update app" + +**Sturgeon Club**: +**Title**: "Membership renewal required" +**Body**: "Your membership expired on March 15. Renew your membership to continue accessing club services." +**Action**: "Renew membership" + +--- + +## Success Messages + +### Simple Confirmation + +**TAPP Transit**: +- "Pass purchased" +- "Favorite added" +- "Route saved" +- "Email updated" + +**'appee**: +- "Photo uploaded" +- "Vote recorded" +- "Friend added" +- "Profile saved" + +**Sturgeon Club**: +- "Reservation confirmed" +- "Preferences updated" +- "Guest added" +- "Payment processed" + +### Detailed Success + +**TAPP Transit**: +**Title**: "Trip saved" +**Body**: "You'll get a reminder 30 minutes before your bus arrives." + +**'appee**: +**Title**: "Challenge complete!" +**Body**: "You earned 50 points. Check the leaderboard to see your ranking." + +**Sturgeon Club**: +**Title**: "Reservation confirmed" +**Body**: "Table for 4 on Saturday, May 20 at 7:30 PM. You'll receive a reminder the day before." + +--- + +## Empty States + +### First-Use Empty State + +**TAPP Transit**: +**Title**: "No saved routes yet" +**Body**: "Save your frequent trips for quick access." +**Action**: "Plan a trip" + +**'appee**: +**Title**: "No photos yet" +**Body**: "Upload your first photo to start earning points." +**Action**: "Upload photo" + +**Sturgeon Club**: +**Title**: "No upcoming reservations" +**Body**: "Reserve a table at any of our exclusive venues." +**Action**: "Make reservation" + +### User-Cleared Empty State + +**TAPP Transit**: +**Title**: "All caught up" +**Body**: "You've completed all your trips for today." + +**'appee**: +**Title**: "You're all done!" +**Body**: "You've voted on all today's photos. New challenges arrive tomorrow." + +**Sturgeon Club**: +**Title**: "No pending requests" +**Body**: "You're all set. We'll notify you when we process your reservation." + +### Error Empty State + +**TAPP Transit**: +**Title**: "No results found" +**Body**: "Try a different search or browse all routes." +**Action**: "See all routes" + +**'appee**: +**Title**: "No photos match your search" +**Body**: "Try different keywords or browse all photos." +**Action**: "Browse photos" + +**Sturgeon Club**: +**Title**: "No events match your criteria" +**Body**: "Adjust your filters or view all upcoming events." +**Action**: "View all events" + +--- + +## Notifications + +### Action-Required + +**TAPP Transit**: +**Title**: "Your bus is arriving" +**Body**: "Route 42 to Downtown arrives in 2 minutes at Bay St." + +**'appee**: +**Title**: "New challenge available" +**Body**: "Today's theme: Sunset. Upload by midnight to compete." + +**Sturgeon Club**: +**Title**: "Reservation reminder" +**Body**: "Your reservation is tonight at 7:30 PM. Confirm or modify by 5 PM." +**Actions**: "Confirm" | "Modify" + +### Passive + +**TAPP Transit**: +**Title**: "Service update" +**Body**: "Route 15 is running 5 minutes late due to traffic." + +**'appee**: +**Title**: "You earned a badge" +**Body**: "Weekly Warrior: Uploaded photos 7 days in a row." + +**Sturgeon Club**: +**Title**: "New event announced" +**Body**: "Wine tasting on June 15. Reserve your spot before it fills." + +--- + +## Form Fields + +### Labels + +**TAPP Transit**: "Email address", "Card number", "Expiration date", "Security code" +**'appee**: "Username", "Display name", "Bio", "Profile photo" +**Sturgeon Club**: "Member name", "Phone number", "Dietary preferences", "Guest names" + +### Instructions (Helper Text) + +**TAPP Transit**: +- "We'll send trip updates to this email" +- "This card will be saved securely for future purchases" +- "Shown on your receipts and account" + +**'appee**: +- "Choose a unique name others will see" +- "Tell other players about yourself" +- "Upload a photo that represents you" + +**Sturgeon Club**: +- "Required for reservation confirmations" +- "We'll contact you about events and updates" +- "Help us prepare the perfect dining experience" + +### Placeholder Text + +**TAPP Transit**: "name@example.com", "4111 1111 1111 1111", "MM/YY" +**'appee**: "PhotoPro2024", "About me...", "Add caption" +**Sturgeon Club**: "John Smith", "(555) 555-5555", "Guest name" + +--- + +## Controls + +### Toggle Switches + +**TAPP Transit**: +- **Name**: "Real-time updates" +- **Description**: "Get notifications when your bus is arriving" + +**'appee**: +- **Name**: "Push notifications" +- **Description**: "Get notified about new challenges and friend activity" + +**Sturgeon Club**: +- **Name**: "Event reminders" +- **Description**: "Receive notifications about upcoming reservations and events" + +### Checkboxes + +**TAPP Transit**: +- "Remember this payment method" +- "Include accessibility information" +- "Show express routes only" + +**'appee**: +- "Make profile public" +- "Allow friend requests" +- "Share scores on leaderboard" + +**Sturgeon Club**: +- "Send event invitations" +- "Include guests in communications" +- "Opt in to exclusive offers" + +--- + +## Instructions + +### Static Instructions + +**TAPP Transit**: "Tap your card when you board and when you exit." +**'appee**: "Upload one photo per day to earn points." +**Sturgeon Club**: "Present your membership card upon arrival." + +### On-Demand Instructions + +**TAPP Transit**: +**Trigger**: Help icon next to "Transfer" +**Content**: "Switch to another bus or train at connecting stops. Your pass covers transfers within 2 hours." + +**'appee**: +**Trigger**: Question mark next to "Challenge rules" +**Content**: "Upload a photo matching today's theme by midnight. Other players vote on entries. Top 10 photos earn bonus points." + +**Sturgeon Club**: +**Trigger**: Info icon next to "Guest policy" +**Content**: "Members may bring up to 3 guests per visit. Guest names must be provided 24 hours in advance for evening reservations." + +--- + +## Key Differences by Voice + +**TAPP Transit (Helpful, Efficient, Trustworthy)**: +- Direct, clear, informative +- Focuses on practical information +- Anticipates user needs +- Transparent about problems + +**'appee (Playful, Competitive, Rewarding)**: +- Energetic, encouraging language +- Emphasizes achievement and competition +- Celebrates user actions +- Uses exclamation points appropriately + +**Sturgeon Club (Sophisticated, Exclusive, Elegant)**: +- Polished, refined tone +- Emphasizes service and quality +- More formal phrasing +- Sophisticated word choices + +All three maintain the core UX principles: purposeful, concise, conversational (within voice), and clear. diff --git a/src/modules/ux-writer/data/real-world-improvements.md b/src/modules/ux-writer/data/real-world-improvements.md new file mode 100644 index 00000000..ae1df0c4 --- /dev/null +++ b/src/modules/ux-writer/data/real-world-improvements.md @@ -0,0 +1,223 @@ +# Real-World UX Writing Improvements + +This document shows actual UX text transformations with scoring against the four quality standards: Purposeful, Concise, Conversational, and Clear. + +## E-commerce Checkout Error + +### Before +"An error has occurred while processing your payment. Please try again later or contact customer support if the problem persists." + +**Analysis:** +- **Purposeful**: 2/10 β€” Doesn't help user recover or understand next steps +- **Concise**: 4/10 β€” 18 words, vague timeframe ("later") +- **Conversational**: 4/10 β€” Robotic system-speak ("an error has occurred") +- **Clear**: 2/10 β€” What error? When is "later"? Why did it fail? + +**Overall**: 3/10 β€” Poor user experience + +### After +"We couldn't process your payment. Check your card details and try again." + +**Analysis:** +- **Purposeful**: 9/10 β€” Provides specific next action +- **Concise**: 9/10 β€” 11 words, direct instruction +- **Conversational**: 9/10 β€” Natural language ("we couldn't") +- **Clear**: 9/10 β€” Specific problem and solution + +**Overall**: 9/10 β€” Excellent + +**Why it works**: Users know exactly what failed (payment), likely cause (card details), and what to do (check and retry). + +--- + +## SaaS Dashboard Empty State + +### Before +"No data available." + +**Analysis:** +- **Purposeful**: 2/10 β€” Doesn't explain why or guide next steps +- **Concise**: 10/10 β€” Very brief, but too brief +- **Conversational**: 5/10 β€” Cold and unhelpful +- **Clear**: 3/10 β€” Technically accurate but not helpful + +**Overall**: 4/10 β€” Needs significant work + +### After +"No data yet. Connect your account to see insights." + +**Analysis:** +- **Purposeful**: 9/10 β€” Explains state and provides clear CTA +- **Concise**: 9/10 β€” 9 words, includes action +- **Conversational**: 8/10 β€” Friendly "yet" implies this is temporary +- **Clear**: 9/10 β€” Tells you exactly what to do + +**Overall**: 9/10 β€” Excellent + +**Why it works**: "Yet" creates expectation of future value, CTA is specific and actionable. + +--- + +## Mobile App Permission Request + +### Before +"'AppName' Would Like to Access Your Location" +[Allow] [Don't Allow] + +**Analysis:** +- **Purposeful**: 4/10 β€” Doesn't explain benefit to user +- **Concise**: 7/10 β€” Adequate length but no context +- **Conversational**: 6/10 β€” Standard iOS pattern, not particularly engaging +- **Clear**: 5/10 β€” Action is clear but reason isn't + +**Overall**: 5/10 β€” Adequate but could be better + +### After +"Enable location to find coffee shops near you" +[Allow] [Not now] + +**Analysis:** +- **Purposeful**: 9/10 β€” Clear user benefit (find shops) +- **Concise**: 8/10 β€” 7 words with value proposition +- **Conversational**: 9/10 β€” Direct, benefit-focused +- **Clear**: 9/10 β€” Exact benefit stated upfront + +**Overall**: 9/10 β€” Excellent + +**Why it works**: Leads with user benefit, not system need. "Not now" is less final than "Don't Allow." + +--- + +## Account Deletion Confirmation + +### Before +"Are you sure you want to delete your account? This action cannot be undone. All your data will be permanently deleted." + +**Analysis:** +- **Purposeful**: 6/10 β€” Warns of consequences but feels heavy-handed +- **Concise**: 5/10 β€” 19 words, some redundancy ("permanently deleted") +- **Conversational**: 5/10 β€” Somewhat robotic multiple sentences +- **Clear**: 7/10 β€” Consequences are clear + +**Overall**: 6/10 β€” Adequate but could be improved + +### After +"Delete your account? You'll lose all your data and this can't be undone." + +**Analysis:** +- **Purposeful**: 8/10 β€” Clear warning without being preachy +- **Concise**: 9/10 β€” 13 words, no redundancy +- **Conversational**: 9/10 β€” Natural phrasing, contraction +- **Clear**: 9/10 β€” Consequences clearly stated + +**Overall**: 9/10 β€” Excellent + +**Why it works**: Question format engages user, contractions feel human, consequences clear without repetition. + +--- + +## Password Requirements + +### Before +"Password must contain at least 8 characters including uppercase letters, lowercase letters, numbers and special characters." + +**Analysis:** +- **Purposeful**: 7/10 β€” Provides requirements but hard to scan +- **Concise**: 4/10 β€” 17 words in one dense sentence +- **Conversational**: 5/10 β€” List reads like technical documentation +- **Clear**: 6/10 β€” Complete info but overwhelming format + +**Overall**: 5/10 β€” Adequate but not optimal + +### After +"Create a strong password (8+ characters) +Use a mix of letters, numbers, and symbols" + +**Analysis:** +- **Purposeful**: 8/10 β€” Explains why (strong) and what +- **Concise**: 9/10 β€” 14 words, broken into scannable lines +- **Conversational**: 9/10 β€” "Create" vs "must contain" +- **Clear**: 9/10 β€” Easy to scan and understand + +**Overall**: 9/10 β€” Excellent + +**Why it works**: Two short lines easier to scan, "strong password" explains purpose, active voice. + +--- + +## Newsletter Unsubscribe Confirmation + +### Before +"You have been successfully unsubscribed from our mailing list. You will no longer receive emails from us. Thank you for your participation." + +**Analysis:** +- **Purposeful**: 4/10 β€” Overly formal for someone leaving +- **Concise**: 3/10 β€” 23 words, lots of redundancy +- **Conversational**: 3/10 β€” Corporate, stiff +- **Clear**: 7/10 β€” Message is clear but verbose + +**Overall**: 4/10 β€” Needs work + +### After +"You're unsubscribed. You can resubscribe anytime in your settings." + +**Analysis:** +- **Purposeful**: 9/10 β€” Confirms action, offers easy reversal +- **Concise**: 10/10 β€” 9 words, direct +- **Conversational**: 10/10 β€” Casual, respectful +- **Clear**: 9/10 β€” Simple and actionable + +**Overall**: 9/10 β€” Excellent + +**Why it works**: Respects user's decision, provides exit ramp without guilt, uses contraction. + +--- + +## File Upload Progress + +### Before +"File uploading... Please wait." + +**Analysis:** +- **Purposeful**: 5/10 β€” Shows status but no time estimate +- **Concise**: 8/10 β€” Very brief +- **Conversational**: 5/10 β€” Somewhat robotic +- **Clear**: 6/10 β€” Basic info only + +**Overall**: 6/10 β€” Adequate + +### After +"Uploading report.pdf... Almost done" + +**Analysis:** +- **Purposeful**: 8/10 β€” Shows filename and reassuring progress +- **Concise**: 8/10 β€” 4 words plus filename +- **Conversational**: 9/10 β€” Encouraging "almost done" +- **Clear**: 9/10 β€” Specific file being uploaded + +**Overall**: 8/10 β€” Good + +**Why it works**: Filename confirms right file is uploading, "almost done" reduces anxiety. + +--- + +## Common Patterns Across These Improvements + +1. **Lead with specifics, not generics** β€” "We couldn't process your payment" vs "An error occurred" +2. **Show user benefit before system need** β€” "Find coffee shops" before "access location" +3. **Use contractions** β€” "You're" feels human, "You are" feels robotic +4. **Break dense text into scannable chunks** β€” Two short lines beat one long sentence +5. **Remove redundancy** β€” "Permanently deleted" β†’ "can't be undone" +6. **Use active voice** β€” "Create a password" vs "Password must contain" +7. **Provide recovery paths** β€” Always tell users what to do next +8. **Respect user decisions** β€” Don't guilt-trip people who opt out + +## Quick Self-Audit Questions + +Use these to improve any UX text: + +1. **Can I remove any words without losing meaning?** +2. **Does this explain what the user needs to know right now?** +3. **Would I actually say this out loud to a friend?** +4. **Is there a specific verb I could use instead of a generic one?** +5. **Am I showing value before asking for something?** diff --git a/src/modules/ux-writer/data/ux-writing-benchmarks.md b/src/modules/ux-writer/data/ux-writing-benchmarks.md new file mode 100644 index 00000000..3e2fc7a2 --- /dev/null +++ b/src/modules/ux-writer/data/ux-writing-benchmarks.md @@ -0,0 +1,353 @@ +# UX Writing Benchmarks & Research-Backed Metrics + +Research-validated benchmarks for creating effective interface copy. + +## Sentence Length & Comprehension + +### Comprehension Rates by Word Count + +Based on readability research: + +- **8 words or fewer**: 100% user comprehension +- **14 words or fewer**: 90% user comprehension +- **20 words**: 80% user comprehension +- **25 words**: Maximum before significant comprehension drop +- **30+ words**: Comprehension drops below 60% + +### Recommended Sentence Lengths by Content Type + +**Critical Content (errors, warnings, confirmations):** +- Target: 8-14 words maximum +- Why: Users need immediate understanding in high-stress moments +- Example: "Delete account? You'll lose all data and this can't be undone." (12 words - 90% comprehension) + +**Instructions & Guidance:** +- Target: 14 words ideal, 20 words maximum +- Why: Clear step-by-step requires brevity +- Example: "Connect your bank to see spending insights. We'll guide you through it." (13 words) + +**Body/Explanatory Text:** +- Target: 15-20 words average per sentence +- Why: Provides context while maintaining readability +- Example: "Your free trial includes all premium features for 30 days. After that, choose a plan or continue with our free version." (22 words - acceptable for explanation) + +**Buttons & CTAs:** +- Target: 2-4 words ideal, 6 words absolute maximum +- Why: Users need instant recognition of action +- Examples: "Save changes" (2 words), "Start free trial" (3 words) + +**Titles & Headers:** +- Target: 3-6 words, 40 characters maximum +- Why: Scannable navigation and orientation +- Examples: "Account settings" (2 words), "Your trip history" (3 words) + +--- + +## Character & Line Length + +### Optimal Reading Line Length + +**Research-backed range: 40-60 characters per line** + +**Why it matters:** +- **Below 40 chars**: Too choppy, excessive eye movement +- **40-60 chars**: Optimal reading rhythm and comprehension +- **Above 60 chars**: Eye strain, loss of reading position + +### Character Limits by UI Element + +**Buttons:** +- Ideal: 15-25 characters +- Maximum: 40 characters +- Examples: "Save changes" (12 chars βœ“), "Submit application" (18 chars βœ“) + +**Page Titles:** +- Ideal: 20-40 characters +- Maximum: 50 characters +- Truncates in most UIs beyond this + +**Notification Titles:** +- Ideal: 25-35 characters +- Maximum: 45 characters +- Mobile truncation happens earlier + +**Notification Body:** +- Ideal: 80-120 characters +- Maximum: 180 characters +- 2-3 lines on mobile + +**Error Messages:** +- Ideal: 80-140 characters +- Maximum: 200 characters +- Includes problem + solution + +**Toast/Snackbar Messages:** +- Ideal: 40-80 characters +- Maximum: 100 characters +- Brief, glanceable confirmations + +--- + +## Reading Level Guidelines + +### Flesch-Kincaid Grade Level Targets + +**General Public / Consumer Products:** +- **Target**: 7th-8th grade +- **Why**: Accessible to 80% of US adults +- **Examples**: Banking apps, social media, e-commerce + +**Professional Tools / B2B SaaS:** +- **Target**: 9th-10th grade +- **Why**: Professional audience expects slight elevation +- **Examples**: Project management, CRM, analytics tools + +**Technical Products / Developer Tools:** +- **Target**: 10th-11th grade +- **Why**: Technical terminology necessary +- **Examples**: IDEs, API documentation, dev platforms + +**Specialized Fields (Legal, Medical, Academic):** +- **Target**: 11th-12th grade +- **Why**: Domain-specific language required +- **Note**: Only when absolutely necessary; plain language preferred + +### Reading Ease Scores (Flesch Reading Ease) + +- **90-100**: Very Easy (5th grade) +- **80-90**: Easy (6th grade) +- **70-80**: Fairly Easy (7th grade) ← Target for consumer products +- **60-70**: Standard (8th-9th grade) ← Target for professional tools +- **50-60**: Fairly Difficult (10th-12th grade) +- **30-50**: Difficult (College) +- **0-30**: Very Difficult (Graduate) + +--- + +## Word Count Benchmarks + +### By UI Pattern + +**Buttons:** +- Minimum: 1 word (rare, only icons + ARIA labels) +- Ideal: 2-4 words +- Maximum: 6 words +- Examples: + - "Save" (1 word - acceptable for common actions) + - "Save changes" (2 words - ideal) + - "Save and continue" (3 words - good) + - "Delete account permanently" (3 words - maximum for destructive) + +**Error Messages:** +- Inline validation: 3-6 words + - "Email must include @" (4 words) +- Detour errors: 10-15 words + - "Payment failed. Check your card details and try again." (10 words) +- Blocking errors: 15-25 words + - "Service temporarily unavailable. We're updating and will be back in 15 minutes. Your data is safe." (17 words) + +**Success Messages:** +- Brief confirmations: 2-5 words + - "Changes saved" (2 words) + - "Email sent successfully" (3 words) +- Detailed success: 8-15 words + - "Trip saved. You'll get a reminder 30 minutes before your bus arrives." (13 words) + +**Empty States:** +- Title: 2-5 words + - "No messages yet" (3 words) +- Body: 8-15 words + - "Start a conversation to connect with your team." (8 words) +- Total: 10-20 words (title + body + CTA) + +**Notifications:** +- Title only: 4-8 words + - "Your bus is arriving" (4 words) +- Title + body: 15-25 words total + - "Your bus is arriving. Route 42 to Downtown arrives in 2 minutes at Bay St." (15 words) + +**Form Labels:** +- Ideal: 2-4 words +- Maximum: 6 words +- Examples: "Email address" (2 words), "Phone number" (2 words) + +**Form Instructions (Helper Text):** +- Ideal: 6-12 words +- Maximum: 20 words +- Example: "We'll send trip updates to this email" (7 words) + +**Tooltips:** +- Ideal: 8-15 words +- Maximum: 25 words +- Brief, contextual explanation + +--- + +## Active vs. Passive Voice + +### Target: 85% Active Voice + +**Why it matters:** +- Active voice is clearer and more engaging +- Passive voice adds words and obscures responsibility +- Active voice feels more conversational and human + +**Examples:** + +| Passive (Wordy & Unclear) | Active (Clear & Concise) | Words Saved | +|---------------------------|-------------------------|-------------| +| "Your payment has been processed" | "We processed your payment" | 1 word | +| "Your request has been received" | "We received your request" | 1 word | +| "An error has occurred" | "We found an error" | 1 word | +| "Your file is being uploaded" | "We're uploading your file" | 1 word | + +**When passive voice is acceptable:** +- When actor is unknown: "Your session expired" (vs unclear "We expired your session") +- When action is more important than actor: "File deleted" (vs "You deleted the file") +- When avoiding blame: "Payment declined" (vs "Your bank declined payment") + +--- + +## Accessibility Benchmarks + +### WCAG Compliance + +**WCAG Level AA Requirements for Text:** +- Color contrast: 4.5:1 for normal text, 3:1 for large text (18pt+ or 14pt+ bold) +- Text alternatives: All images and icons have text equivalents +- Link text: Descriptive (not "click here") +- Form labels: Present and programmatically associated +- Error identification: Text description (not color alone) + +### Cognitive Accessibility + +**Sentence length for maximum accessibility:** +- **8-14 words**: Optimal for users with cognitive disabilities +- **Keep paragraphs to 3-4 sentences maximum** +- **Use headings every 3-4 paragraphs** + +**Plain language requirements:** +- Define abbreviations on first use +- Avoid idioms and metaphors +- Use common words over complex ones +- Provide explanations for technical terms + +--- + +## Mobile vs. Desktop Considerations + +### Mobile-Specific Benchmarks + +**Character limits (tighter due to screen size):** +- Button labels: 12-18 characters (vs 25 desktop) +- Page titles: 25-35 characters (vs 50 desktop) +- Notification text: 60-100 characters (vs 180 desktop) + +**Word counts (same or fewer):** +- Follow desktop benchmarks or go shorter +- Mobile users scan even faster +- Thumb-friendly tap targets need brief labels + +**Line length (narrower):** +- Target: 30-50 characters per line +- Mobile screens naturally constrain line length +- Avoid artificially wide text blocks + +--- + +## Industry-Specific Benchmarks + +### E-commerce + +**Product titles:** 50-60 characters optimal for search +**Add to cart button:** "Add to cart" (3 words) or "Add to bag" (3 words) +**Checkout buttons:** "Proceed to checkout" (3 words), "Complete purchase" (2 words) +**Error messages:** Critical for cart abandonment - must be under 15 words + +### Finance/Banking + +**Security messages:** Can be slightly longer (18-25 words) to establish trust +**Transaction confirmations:** Be very specific - 12-20 words +**Reading level:** Target 8th grade despite professional domain +**Error messages:** Must include recovery steps - 15-20 words + +### Healthcare + +**Privacy notices:** Can be longer but break into sections +**Appointment confirmations:** Be extremely specific - 15-25 words +**Medication instructions:** Critical clarity - 10-18 words per step +**Reading level:** 6th-7th grade (lowest acceptable for health literacy) + +### SaaS/Productivity + +**Onboarding:** Can be more verbose (20-30 words) to educate +**Feature tooltips:** 12-20 words for explanation +**Error messages:** Include support links - 15-25 words +**Empty states:** Emphasize value - 15-25 words total + +--- + +## Testing & Measurement Tools + +### Readability Testing + +**Free Tools:** +- **Hemingway Editor** (hemingwayapp.com): Highlights complex sentences, passive voice +- **Readable** (readable.com): Multiple readability scores +- **Microsoft Word**: Built-in Flesch-Kincaid scoring +- **Grammarly**: Readability score and suggestions + +**What to measure:** +- Flesch-Kincaid Grade Level +- Flesch Reading Ease Score +- Average sentence length +- Passive voice percentage + +### Usability Testing + +**Comprehension testing:** +- Show text to 5 users +- Ask: "What do you think happens when you click this?" +- Target: 100% correct interpretation + +**Time to comprehension:** +- Users should understand in 2 seconds or less +- If users pause or reread, text needs work + +**A/B testing:** +- Test concise vs. verbose versions +- Measure task completion rate +- Track error rates + +--- + +## Quick Reference Table + +| UI Element | Words | Characters | Reading Level | Comprehension | +|-----------|-------|-----------|---------------|---------------| +| Button | 2-4 (6 max) | 15-25 | 7th grade | 100% | +| Error inline | 3-6 | 25-40 | 7th grade | 100% | +| Error detour | 10-15 | 80-120 | 7th grade | 90% | +| Error blocking | 15-25 | 120-180 | 8th grade | 90% | +| Success brief | 2-5 | 15-35 | 7th grade | 100% | +| Success detailed | 8-15 | 60-100 | 7th grade | 90% | +| Empty state title | 2-5 | 20-35 | 7th grade | 100% | +| Empty state body | 8-15 | 60-100 | 7th grade | 90% | +| Notification | 15-25 | 100-180 | 8th grade | 90% | +| Form label | 2-4 | 15-30 | 7th grade | 100% | +| Form instruction | 6-12 | 50-80 | 7th grade | 90% | +| Tooltip | 8-15 | 60-100 | 8th grade | 90% | + +--- + +## References & Research Sources + +- Nielsen Norman Group: "How Users Read on the Web" (F-pattern, scanning behavior) +- Readable.io: Sentence length and comprehension studies +- American Press Institute: Readability research +- WCAG 2.1: Accessibility guidelines +- Flesch-Kincaid: Reading ease formula +- Material Design: Content guidelines +- Sarah Richards: "Content Design" (UK Government Digital Service research) +- Ginny Redish: "Letting Go of the Words" (usability research) + diff --git a/src/modules/ux-writer/tasks/analyze-ux-text.md b/src/modules/ux-writer/tasks/analyze-ux-text.md new file mode 100644 index 00000000..2d9b666f --- /dev/null +++ b/src/modules/ux-writer/tasks/analyze-ux-text.md @@ -0,0 +1,238 @@ +# Analyze UX Text Task + +Analyze interface copy against the Four Quality Standards framework and provide objective scoring with improvement recommendations. + +## Task Overview + +This task evaluates UX text (buttons, error messages, labels, etc.) using the research-backed Four Quality Standards: Purposeful, Concise, Conversational, and Clear. + +## Inputs Required + +1. **The text to analyze**: The actual interface copy +2. **Context**: What is this text for? (button, error message, notification, etc.) +3. **User scenario**: What is the user trying to do? +4. **Current location**: Where does this appear in the product? + +## Elicitation Process + +Ask the user for the following information: + +**1. Share the text** +``` +Please provide the interface text you'd like me to analyze. +``` + +**2. Gather context** +``` +Help me understand the context: +1. What type of UI element is this? (button, error message, notification, empty state, form label, etc.) +2. What is the user trying to accomplish when they see this? +3. Where does this appear in your product? +4. What is the user's likely emotional state? (confident, frustrated, confused, cautious) +``` + +**3. Optional: Target audience** +``` +Who is your target audience? (general public, professionals, technical users, etc.) +``` + +## Analysis Framework + +### Score Each Standard (0-10 scale) + +**1. Purposeful (Does it help user/business achieve goals?)** +- 9-10: Clear user benefit, addresses concerns, advances goals +- 5-8: Some user benefit but could be more targeted +- 1-4: Unclear purpose or doesn't help user/business +- 0: No discernible purpose + +**Evaluation questions:** +- Does this help the user accomplish their goal? +- Is the value to the user clear? +- Are user concerns anticipated and addressed? +- Does it serve a business objective? + +**2. Concise (Uses fewest words without losing meaning?)** +- 9-10: No wasted words, perfectly concise +- 5-8: Generally concise but some redundancy +- 1-4: Verbose, needs significant trimming +- 0: Extremely wordy + +**Evaluation questions:** +- Can any words be removed without losing meaning? +- Is information front-loaded? +- Does every word earn its space? +- Does it meet length benchmarks? + +**Benchmarks:** +- Buttons: 2-4 words ideal, 6 maximum +- Error messages: 12-18 words including solution +- Instructions: 14 words ideal, 20 maximum +- Titles: 3-6 words, 40 characters maximum + +**3. Conversational (Sounds natural and human?)** +- 9-10: Natural, human, conversational +- 5-8: Mostly natural with some stiffness +- 1-4: Robotic, corporate, unnatural +- 0: Extremely robotic + +**Evaluation questions:** +- Would you say this out loud? +- Does it use active voice? +- Are there natural connecting words? +- Is it free of corporate jargon? + +**Guidelines:** +- Active voice target: 85% of content +- Include prepositions and articles naturally +- Avoid phrases like "an error has occurred" + +**4. Clear (Unambiguous and easy to understand?)** +- 9-10: Crystal clear, unambiguous, accurate +- 5-8: Generally clear with minor ambiguities +- 1-4: Confusing, ambiguous, unclear +- 0: Incomprehensible + +**Evaluation questions:** +- Is there only one way to interpret this? +- Are verbs specific and meaningful? +- Is terminology consistent with the product? +- Does it meet readability targets? + +**Benchmarks:** +- Reading level: 7th-10th grade (general audience) +- Sentence length: 8-14 words for critical content +- Avoid jargon and technical terms + +## Output Format + +Present the analysis in this structure: + +```markdown +## UX Text Analysis + +**Original Text:** +[The text being analyzed] + +**Context:** [Type of UI element and user scenario] + +--- + +### Quality Standards Scoring + +#### 1. Purposeful: [Score]/10 +**Assessment:** [Explanation of why this score] + +**Strengths:** +- [What works well] + +**Opportunities:** +- [What could be improved] + +#### 2. Concise: [Score]/10 +**Assessment:** [Explanation with word count if relevant] + +**Strengths:** +- [What works well] + +**Opportunities:** +- [What could be improved] + +#### 3. Conversational: [Score]/10 +**Assessment:** [Explanation] + +**Strengths:** +- [What works well] + +**Opportunities:** +- [What could be improved] + +#### 4. Clear: [Score]/10 +**Assessment:** [Explanation with reading level if relevant] + +**Strengths:** +- [What works well] + +**Opportunities:** +- [What could be improved] + +--- + +### Overall Score: [Average]/10 + +**Overall Assessment:** [Brief summary of the text quality] + +--- + +### Recommended Improvements + +[If score is below 8/10, provide specific improvement suggestions] + +**Suggested revision:** +[Improved version of the text] + +**Why this is better:** +1. **Purposeful:** [Explanation] +2. **Concise:** [Explanation] +3. **Conversational:** [Explanation] +4. **Clear:** [Explanation] + +**Improved scores:** +- Purposeful: [New score]/10 +- Concise: [New score]/10 +- Conversational: [New score]/10 +- Clear: [New score]/10 +- **Overall: [New average]/10** +``` + +## Additional Checks + +When analyzing, also consider: + +### Accessibility +- Does it work for screen readers? +- Is it paired with visual indicators? +- Is language plain and simple? + +### Pattern Compliance +- Does it follow best practices for this UI element type? +- Buttons: Imperative verb + object? +- Errors: Problem + solution? +- Empty states: Explanation + CTA? + +### Tone Appropriateness +- Does the tone match user emotional state? +- Is it empathetic for error states? +- Is it encouraging for success states? +- Is it serious for high-stakes actions? + +## Tips for Analysis + +1. **Read aloud** - If it sounds awkward, it likely is +2. **Check word count** - Compare against benchmarks +3. **Test comprehension** - Can user understand in 2 seconds? +4. **Consider context** - Same text works differently in different situations +5. **Think accessibility** - How does this work for all users? +6. **Apply patterns** - Does it follow proven UX text patterns? + +## Example Analysis + +**Text:** "An error has occurred while processing your request. Please try again later." + +**Analysis:** +- **Purposeful: 3/10** - Doesn't explain what failed or provide actionable next steps +- **Concise: 5/10** - 12 words, but "an error has occurred" is 4 wasted words +- **Conversational: 3/10** - Robotic system-speak, passive voice +- **Clear: 2/10** - What error? When is "later"? Vague and unhelpful +- **Overall: 3.25/10** + +**Improved:** "We couldn't process your request. Check your connection and try again." +- Purposeful: 8/10, Concise: 9/10, Conversational: 9/10, Clear: 8/10 +- **Overall: 8.5/10** + +## Completion + +After providing the analysis: +1. Ask if user wants to see improved version (if not already provided) +2. Offer to analyze additional text +3. Suggest running full audit if multiple pieces of text need review diff --git a/src/modules/ux-writer/tasks/create-ux-text.md b/src/modules/ux-writer/tasks/create-ux-text.md new file mode 100644 index 00000000..61e7b36f --- /dev/null +++ b/src/modules/ux-writer/tasks/create-ux-text.md @@ -0,0 +1,341 @@ +# Create UX Text Task + +Create new interface copy for specific UI patterns using the Four Quality Standards framework and research-backed best practices. + +## Task Overview + +This task guides you through creating effective interface copy for common UI elements: buttons, error messages, success messages, empty states, notifications, form fields, and onboarding flows. + +## Elicitation Process + +### 1. Identify Pattern Type + +``` +What type of interface copy do you need? + +1. Button or link +2. Error message +3. Success/confirmation message +4. Empty state +5. Notification +6. Form field (label, instruction, placeholder) +7. Onboarding step +8. Other (please describe) + +Please select a number or describe your need. +``` + +### 2. Gather Context + +**For all patterns, ask:** +``` +Help me understand the context: + +1. **User goal:** What is the user trying to accomplish? +2. **User state:** How is the user likely feeling? (confident, frustrated, confused, cautious, excited) +3. **Stakes:** Is this low-stakes (changing theme) or high-stakes (deleting data)? +4. **Constraints:** Any character limits, technical constraints, or requirements? +``` + +### 3. Pattern-Specific Questions + +**For buttons:** +- What action does this button trigger? +- Is this primary, secondary, or destructive action? + +**For error messages:** +- What failed or went wrong? +- Why did it fail (if known)? +- What can the user do to fix it? +- What type: inline validation, system error, or blocking error? + +**For empty states:** +- Why is this empty? (first use, user cleared, no results) +- What action would populate this? + +**For success messages:** +- What action just completed? +- What benefit did the user get? + +**For notifications:** +- What information needs to be communicated? +- Is action required or is this passive information? +- How time-sensitive is this? + +**For form fields:** +- What information are you collecting? +- Why do you need this information? +- Are there specific format requirements? + +## Creation Framework + +Apply the Four Quality Standards: + +### 1. Purposeful +- Identify the primary goal (user + business) +- Anticipate user questions/concerns +- Include value proposition when needed + +### 2. Concise +- Start with conversational version, then trim +- Remove unnecessary words +- Meet pattern-specific benchmarks +- Front-load key information + +### 3. Conversational +- Write how you'd say it +- Use active voice (85% of time) +- Include natural connecting words +- Avoid corporate jargon + +### 4. Clear +- Use specific, accurate verbs +- Target appropriate reading level +- Avoid ambiguity +- Use consistent terminology + +## Pattern-Specific Guidelines + +### Buttons +**Format:** `[Verb] [object]` +**Style:** Active imperative, sentence case +**Length:** 2-4 words ideal, 6 maximum + +**Examples:** +- βœ… "Save changes" +- βœ… "Delete account" +- βœ… "Start free trial" +- ❌ "Submit" +- ❌ "OK" +- ❌ "Click here" + +**Process:** +1. Identify the action +2. Choose specific verb (not generic) +3. Add object for clarity +4. Keep under 6 words + +### Error Messages + +**Format:** `[What failed]. [Why, if known]. [What to do].` + +**Types:** + +**Inline (validation):** Brief guidance +- Pattern: `[Field] [requirement]` +- Example: "Email must include @" +- Length: 3-6 words + +**Detour (recoverable):** Problem + solution +- Example: "Payment failed. Check your card details and try again." +- Length: 10-15 words + +**Blocking (system):** Explanation + timeline + reassurance +- Example: "Service temporarily unavailable. We're updating our systems and will be back in 15 minutes. Your data is safe." +- Length: 15-25 words + +**Key principles:** +- Never blame user +- Be empathetic +- Provide clear recovery path +- Use active voice +- Front-load the problem + +### Success Messages +**Format:** `[Action completed] [result/benefit]` +**Style:** Past tense, specific, encouraging +**Length:** 2-5 words ideal + +**Examples:** +- βœ… "Changes saved" +- βœ… "Email sent" +- βœ… "Profile updated" +- ❌ "Success!" +- ❌ "Operation completed successfully" + +### Empty States +**Format:** Explanation + CTA + +**Structure:** +- **Title:** Why it's empty (3-6 words) +- **Body:** Brief guidance (8-15 words) +- **CTA:** Clear next action (2-4 words) + +**Example:** +``` +No messages yet +Start a conversation to connect with your team. +[Send message] +``` + +**Types:** +- **First use:** Encourage first action +- **User cleared:** Celebrate completion +- **No results:** Suggest alternative + +### Notifications +**Format:** Title + optional body + +**Structure:** +- **Title:** Verb-first, specific (6-12 words) +- **Body:** Context and details (10-20 words) +- **Action:** Clear CTA if needed (2-4 words) + +**Example:** +``` +Your bus is arriving +Route 42 to Downtown arrives in 2 minutes at Bay St. +``` + +### Form Fields +**Elements:** + +**Label:** Noun phrase describing input +- Examples: "Email address", "Phone number", "Date of birth" +- Keep to 2-4 words + +**Instruction (helper text):** Explain why needed +- Example: "We'll send updates to this email" +- Length: 6-12 words + +**Placeholder:** Use sparingly, standard formats only +- Examples: "name@example.com", "(555) 555-5555" + +**Error:** Specific correction guidance +- Example: "Must include @ symbol" + +## Output Format + +Present created copy in this structure: + +```markdown +## Created UX Text + +**Pattern:** [Type of UI element] +**Context:** [User scenario] + +--- + +### Recommended Copy + +[The created text] + +--- + +### Quality Standards Analysis + +**Purposeful (9/10):** +[Explain how this helps user achieve goals] + +**Concise ([score]/10):** +[Word count and length assessment] + +**Conversational ([score]/10):** +[Natural language assessment] + +**Clear ([score]/10):** +[Clarity and comprehension assessment] + +**Overall: [Average]/10** + +--- + +### Rationale + +**Why this works:** +1. [Explanation tied to standards] +2. [Pattern-specific best practice applied] +3. [Accessibility consideration] + +**Alternatives to consider:** + +1. [Variation 1] - [When to use this] +2. [Variation 2] - [When to use this] +3. [Variation 3] - [When to use this] + +[Provide 2-3 alternative versions with different tones or approaches] + +--- + +### Implementation Notes + +**Accessibility:** +- [Screen reader consideration] +- [Cognitive load consideration] + +**Technical:** +- Character count: [X] +- Reading level: [Grade level] +- Meets benchmark: [Yes/No] + +**Tone:** +- [How tone matches user emotional state] +``` + +## Tone Adaptation + +Adjust tone based on user emotional state: + +**Frustrated** (errors, failures) +- Empathetic and solution-focused +- Acknowledge problem without blame +- Clear recovery path + +**Confused** (first use, complex) +- Patient and explanatory +- Break down steps +- Provide context + +**Confident** (routine tasks) +- Efficient and direct +- Minimal explanation +- Quick confirmation + +**Cautious** (high-stakes) +- Serious and transparent +- Clear consequences +- Respectful of decision + +**Successful** (completions) +- Positive and encouraging +- Proportional to achievement +- Brief celebration + +## Accessibility Checklist + +Ensure all created copy: +- [ ] Works for screen readers (descriptive labels) +- [ ] Uses plain language (appropriate reading level) +- [ ] Includes text with visual indicators (not color alone) +- [ ] Keeps critical content to 8-14 words +- [ ] Uses specific, meaningful verbs +- [ ] Provides context at point of action + +## Example Creation + +**User Request:** "I need an error message for when a file upload fails because it's too large." + +**Created Copy:** +``` +"Upload failed. File is too large. Choose a file under 10MB." +``` + +**Analysis:** +- **Purposeful: 9/10** - Clear problem and solution +- **Concise: 10/10** - 11 words, efficient +- **Conversational: 9/10** - Natural, active voice +- **Clear: 9/10** - Specific size limit +- **Overall: 9.25/10** + +**Alternatives:** +1. "File too large. Please upload under 10MB." (More concise, 7 words) +2. "We couldn't upload your file because it's too large. Please choose a file under 10MB." (More empathetic, 16 words) +3. "File exceeds 10MB limit. Choose a smaller file." (Direct, 8 words) + +## Completion + +After creating the copy: +1. Provide the recommended version with scoring +2. Offer 2-3 alternatives with different tones +3. Explain when each variation works best +4. Ask if user wants refinements or additional variations diff --git a/src/modules/ux-writer/tasks/improve-ux-text.md b/src/modules/ux-writer/tasks/improve-ux-text.md new file mode 100644 index 00000000..6bb32de2 --- /dev/null +++ b/src/modules/ux-writer/tasks/improve-ux-text.md @@ -0,0 +1,328 @@ +# Improve UX Text Task + +Transform existing interface copy using the Four Quality Standards framework with before/after comparison and detailed scoring. + +## Task Overview + +This task takes existing UX text and improves it through systematic application of the Four Quality Standards: Purposeful, Concise, Conversational, and Clear. + +## Elicitation Process + +### 1. Get Original Text +``` +Please share the interface text you want to improve. +``` + +### 2. Gather Context +``` +Help me understand: + +1. What type of UI element is this? (button, error, notification, etc.) +2. What is the user trying to do when they see this? +3. Where does this appear in your product? +4. What is the user's likely emotional state? +5. Are there any constraints? (character limits, technical requirements, brand guidelines) +``` + +### 3. Identify Priorities +``` +What's most important to improve? + +1. Make it more helpful/purposeful +2. Make it more concise +3. Make it sound more natural/human +4. Make it clearer/easier to understand +5. All of the above + +(This helps prioritize if there are tradeoffs) +``` + +## Improvement Process + +### Step 1: Analyze Original + +Score the original text against four standards (0-10 each): + +**Purposeful:** +- Does it help user achieve goals? +- Is value clear? +- Are concerns addressed? + +**Concise:** +- Word count vs. benchmarks +- Unnecessary words? +- Front-loaded? + +**Conversational:** +- Natural language? +- Active voice? +- Human tone? + +**Clear:** +- Unambiguous? +- Specific verbs? +- Appropriate reading level? + +### Step 2: Identify Issues + +Common problems to look for: + +**Purposeful issues:** +- Generic/vague purpose +- Doesn't help user progress +- Missing user benefit +- Doesn't address concerns + +**Concise issues:** +- Redundant words ("please note that...") +- Passive constructions ("your request has been received") +- Unnecessary qualifiers ("very", "quite", "really") +- Buried key information + +**Conversational issues:** +- Robotic phrases ("an error has occurred") +- Excessive passive voice +- Corporate jargon +- Missing natural connectors + +**Clear issues:** +- Ambiguous language +- Technical jargon without explanation +- Generic verbs ("handle", "process") +- High reading level +- Inconsistent terminology + +### Step 3: Apply Improvements + +**For Purposeful:** +1. Front-load user benefit +2. Add missing context +3. Anticipate questions +4. Make value explicit + +**For Concise:** +1. Remove qualifier words +2. Combine redundant phrases +3. Use shorter alternative words +4. Eliminate unnecessary preambles + +**For Conversational:** +1. Convert passive to active voice +2. Replace robotic phrases with natural language +3. Write how you'd say it aloud +4. Add contractions where appropriate + +**For Clear:** +1. Replace generic verbs with specific ones +2. Simplify complex words +3. Break long sentences +4. Add concrete details + +### Step 4: Validate Improvements + +Check improved version: +- [ ] Scores higher on all four standards +- [ ] Meets accessibility requirements +- [ ] Follows pattern best practices +- [ ] Respects any constraints +- [ ] Maintains appropriate tone + +## Output Format + +```markdown +## UX Text Improvement + +### Before + +**Original Text:** +[The original text] + +**Context:** [UI element type and scenario] + +**Quality Scoring:** +- Purposeful: [X]/10 +- Concise: [X]/10 +- Conversational: [X]/10 +- Clear: [X]/10 +- **Overall: [X]/10** + +**Issues Identified:** +1. [Specific problem with standard reference] +2. [Specific problem with standard reference] +3. [Specific problem with standard reference] + +--- + +### After + +**Improved Text:** +[The improved text] + +**Quality Scoring:** +- Purposeful: [X]/10 ↑ +[improvement] +- Concise: [X]/10 ↑ +[improvement] +- Conversational: [X]/10 ↑ +[improvement] +- Clear: [X]/10 ↑ +[improvement] +- **Overall: [X]/10** ↑ +[total improvement] + +--- + +### What Changed & Why + +**1. Purposeful Improvements:** +[Specific changes and why they help user/business goals] + +**Example:** +- Removed: [vague phrase] +- Added: [specific user benefit] +- Impact: User now understands [what they gain] + +**2. Concise Improvements:** +[Specific changes and word count reduction] + +**Example:** +- Original word count: [X] words +- Improved word count: [Y] words +- Reduction: [Z] words ([%] shorter) +- Removed: [unnecessary phrases] + +**3. Conversational Improvements:** +[Specific changes and natural language improvements] + +**Example:** +- Changed: [robotic phrase] β†’ [natural phrase] +- Voice: Passive β†’ Active +- Tone: [how it's more natural] + +**4. Clear Improvements:** +[Specific changes and clarity enhancements] + +**Example:** +- Replaced: [generic verb] with [specific verb] +- Simplified: [complex phrase] to [simple phrase] +- Reading level: [old] β†’ [new] grade + +--- + +### Comparison Summary + +| Aspect | Before | After | Improvement | +|--------|--------|-------|-------------| +| Word count | [X] | [Y] | -[Z] words | +| Character count | [X] | [Y] | -[Z] chars | +| Reading level | [X] grade | [Y] grade | Clearer | +| Active voice | No/Partial | Yes | More natural | +| User benefit | Unclear | Clear | More purposeful | + +--- + +### Alternative Variations + +[Provide 2-3 alternative improved versions with different approaches] + +**Variation 1: [Focus]** (e.g., "Ultra-concise") +[Alternative text] +- When to use: [Context where this works better] + +**Variation 2: [Focus]** (e.g., "More empathetic") +[Alternative text] +- When to use: [Context where this works better] + +**Variation 3: [Focus]** (e.g., "More detailed") +[Alternative text] +- When to use: [Context where this works better] +``` + +## Common Improvements by Pattern + +### Button Text +**Before:** "Submit Form" β†’ **After:** "Submit application" +- More specific object +- Maintains active imperative + +**Before:** "Click here to download" β†’ **After:** "Download report" +- Removed "click here" +- Specific about what downloads + +### Error Messages +**Before:** "Error 404: Page not found" β†’ **After:** "We can't find that page. Check the URL or return home." +- Removed error code +- Added recovery action +- More empathetic + +**Before:** "Invalid email address" β†’ **After:** "Email must include @" +- Removed blame word "invalid" +- Specific requirement +- Shorter + +### Empty States +**Before:** "There are no items here." β†’ **After:** "No items yet. Add your first item to get started." +- Added "yet" for encouragement +- Clear call to action +- Future-oriented + +### Success Messages +**Before:** "Your request has been successfully processed." β†’ **After:** "Request processed." +- Removed passive voice +- Removed unnecessary "successfully" +- More concise + +### Form Instructions +**Before:** "Please enter your email address in the field below." β†’ **After:** "We'll send updates to this email." +- Focus on user benefit +- Removed obvious instruction +- More purposeful + +## Accessibility Impact + +When improving, ensure: + +**Screen readers:** +- Improved text works without visual context +- Labels are descriptive +- Links describe destination + +**Cognitive load:** +- Shorter sentences (8-14 words for critical content) +- Simpler vocabulary +- Clearer structure + +**Plain language:** +- Lower reading level +- No jargon +- Common words + +## Example Improvement + +**Original:** +"An error has occurred while processing your payment transaction. Please try again later or contact our customer support team if the problem persists." + +**Analysis:** +- Purposeful: 2/10 (doesn't explain or guide) +- Concise: 3/10 (22 words, very verbose) +- Conversational: 2/10 (robotic, passive) +- Clear: 2/10 (vague timing, unclear problem) +- **Overall: 2.25/10** + +**Improved:** +"We couldn't process your payment. Check your card details and try again." + +**New Analysis:** +- Purposeful: 9/10 (clear problem + solution) +- Concise: 9/10 (11 words, 50% shorter) +- Conversational: 9/10 (active voice, natural) +- Clear: 9/10 (specific action) +- **Overall: 9/10** ↑ +6.75 + +**What Changed:** +1. **Purposeful:** Specified what failed (payment), removed vague "contact support" +2. **Concise:** Removed "an error has occurred", "transaction", "if problem persists" (11 words saved) +3. **Conversational:** Changed passive to active ("we couldn't" vs "has occurred") +4. **Clear:** Specific action (check card) instead of vague (try later) + +## Completion + +After providing improvements: +1. Ask if user wants alternative versions +2. Offer to improve related text for consistency +3. Suggest full audit if multiple pieces need improvement diff --git a/src/modules/ux-writer/templates/empty-state-template.md b/src/modules/ux-writer/templates/empty-state-template.md new file mode 100644 index 00000000..2231a0ef --- /dev/null +++ b/src/modules/ux-writer/templates/empty-state-template.md @@ -0,0 +1,185 @@ +# Empty State Template + +Use this template to guide users when content is absent and help them take action to populate the space. + +## Structure + +``` +[Title explaining the empty state] [Brief explanation or encouragement] [Clear call to action] +``` + +## Template Types + +### First-Use Empty State +**Purpose**: Guide new users to populate content +**Tone**: Inviting, encouraging, clear on benefit + +``` +**Title**: [What's empty] +**Body**: [Brief benefit of adding content] +**Button**: [Specific action to populate] +``` + +**Example:** +``` +**Title**: No projects yet +**Body**: Create your first project to start organizing work. +**Button**: Create project +``` + +--- + +### User-Cleared Empty State +**Purpose**: Confirm completion, positive reinforcement +**Tone**: Positive, celebratory (appropriately) + +``` +**Title**: [Positive completion statement] +**Body**: [Optional: What happens next or when new content appears] +``` + +**Example:** +``` +**Title**: You're all caught up +**Body**: New tasks will appear here when they're assigned to you. +``` + +--- + +### Error/No Results Empty State +**Purpose**: Suggest alternatives when search/filter returns nothing +**Tone**: Helpful, solution-focused + +``` +**Title**: [What wasn't found] +**Body**: [Suggestion to modify or alternative action] +**Button**: [Alternative action] +``` + +**Example:** +``` +**Title**: No results for "vintage cameras" +**Body**: Try different keywords or browse all items. +**Button**: Browse all items +``` + +--- + +## Empty State Checklist + +Before finalizing an empty state, verify: + +- [ ] **Clear context** β€” User knows what's empty and why +- [ ] **Actionable** β€” Provides specific next step +- [ ] **Appropriate tone** β€” Matches emotional context +- [ ] **Value-focused** β€” Shows benefit of taking action +- [ ] **Concise** β€” Brief enough to scan quickly +- [ ] **Avoids negativity** β€” No "nothing here" or "you have no..." + +## Content Patterns by Type + +### First-Use (Onboarding) +**Pattern**: "No [content] yet. [Benefit statement]. [Action]" + +Examples: +- "No contacts yet. Import contacts to start messaging. **Import contacts**" +- "No favorites saved. Save items to find them quickly later. **Browse items**" +- "No team members yet. Invite people to collaborate on projects. **Invite team**" + +### User-Cleared (Completion) +**Pattern**: "All [done/complete/caught up]. [Optional: when more appears]" + +Examples: +- "All tasks complete. New tasks appear when teammates assign them to you." +- "Inbox zero! You've read all your messages." +- "You're all set. Check back tomorrow for new recommendations." + +### No Results (Search/Filter) +**Pattern**: "No [content] match [criteria]. [Suggestion]. [Alternative]" + +Examples: +- "No files match your search. Try different keywords or **view all files**." +- "No events this month. **See upcoming events** or **create an event**." +- "No team members match these filters. **Clear filters** to see all members." + +### Permission/Access Required +**Pattern**: "[Content] isn't available. [Why]. [How to get access]" + +Examples: +- "Reports aren't available yet. Upgrade to Premium to access detailed analytics. **View plans**" +- "This folder is private. Ask the owner to share it with you." +- "Calendar events are hidden. Enable calendar sync in **settings** to see events." + +## Voice Variations + +### Professional/B2B Product +``` +**Title**: No documents uploaded +**Body**: Upload files to share with your team. +**Button**: Upload document +``` + +### Consumer/Friendly Product +``` +**Title**: Nothing here yet! +**Body**: Start adding favorites to build your collection. +**Button**: Find favorites +``` + +### Serious/High-Stakes Product +``` +**Title**: No alerts +**Body**: Your systems are running normally. +``` + +## Illustration Guidance + +When working with designers on empty state illustrations: + +**First-use**: Optimistic, inviting imagery (open boxes, blank canvases, starting points) +**User-cleared**: Positive, completion imagery (checkmarks, clean spaces, celebrations) +**No results**: Neutral, helpful imagery (search icons, magnifying glasses, directional arrows) + +## Common Mistakes to Avoid + +❌ **Negative framing**: "You have no contacts" +βœ… **Neutral/positive**: "No contacts yet" + +❌ **No guidance**: "Empty" +βœ… **Actionable**: "No contacts yet. Import to get started." + +❌ **Multiple CTAs**: Three different buttons competing +βœ… **Single primary CTA**: One clear next action + +❌ **Too much text**: Long paragraph explaining the feature +βœ… **Concise**: One sentence benefit, clear button + +❌ **Technical**: "No records found in database" +βœ… **Human**: "No projects found" + +## Quick Fill Template + +Use this for rapid empty state drafting: + +**Empty state type:** (First-use / User-cleared / No results / Permission) +**What's empty:** +**Why it's empty:** +**What user should do:** +**User benefit:** + +**Draft:** +**Title**: [What's empty] +**Body**: [Benefit of action or what happens next] +**Button**: [Specific action] + +**Example filled:** +- Type: First-use +- What's empty: Saved reports +- Why: New user +- What to do: Create or save a report +- Benefit: Quick access to important data + +Draft: +**Title**: No saved reports yet +**Body**: Save reports to access your most important data quickly. +**Button**: Create report diff --git a/src/modules/ux-writer/templates/error-message-template.md b/src/modules/ux-writer/templates/error-message-template.md new file mode 100644 index 00000000..b09805d1 --- /dev/null +++ b/src/modules/ux-writer/templates/error-message-template.md @@ -0,0 +1,132 @@ +# Error Message Template + +Use this template to write clear, actionable error messages that help users recover. + +## Structure + +``` +[What failed] [Why it might have failed, if known] [What to do next] +``` + +## Template + +### Inline Error (Form Validation) +**Format**: Brief, immediate correction guidance + +``` +[Field requirement or constraint] +``` + +**Examples:** +- Email must include @ +- Password needs 8+ characters +- Card number is incomplete +- Choose a future date + +--- + +### Detour Error (Recoverable Problem) +**Format**: Problem + Solution + +``` +**Title**: [Action that failed] +**Body**: [Brief explanation]. [Recovery instruction]. +**Button**: [Specific recovery action] +``` + +**Example:** +``` +**Title**: Can't save changes +**Body**: Check your internet connection and try again. +**Button**: Retry +``` + +--- + +### Blocking Error (System Issue) +**Format**: Clear explanation + Timeline + Reassurance + +``` +**Title**: [What's unavailable] +**Body**: [Why it's unavailable]. [When it will be available]. [Reassurance about user data]. +**Button**: [Status check or alternative action] +``` + +**Example:** +``` +**Title**: Service temporarily unavailable +**Body**: We're updating our systems and will be back in about 15 minutes. Your data is safe. +**Button**: Check status +``` + +--- + +## Error Message Checklist + +Before finalizing an error message, verify: + +- [ ] **Avoids blame** β€” No "invalid," "illegal," "wrong," "error" +- [ ] **Empathetic tone** β€” Acknowledge user frustration +- [ ] **Specific problem** β€” Not generic "something went wrong" +- [ ] **Clear recovery** β€” Tell user exactly what to do +- [ ] **Front-loaded** β€” Most important info first +- [ ] **Active voice** β€” "We couldn't save" not "changes could not be saved" +- [ ] **Human language** β€” Not system codes or technical jargon + +## Voice Variations by Context + +### High-Stakes Error (Payment, Security, Data Loss) +**Tone**: Serious, clear, reassuring + +``` +We couldn't process your payment. Your card wasn't charged. Check your card details and try again. +``` + +### Low-Stakes Error (Optional Feature, Nice-to-Have) +**Tone**: Light, helpful, not dramatic + +``` +Couldn't load preview. Refresh to try again. +``` + +### First-Time User Error +**Tone**: Educational, patient + +``` +Profile photo must be under 5MB. Try a smaller file or compress your image. +``` + +## Common Mistakes to Avoid + +❌ **Vague**: "An error occurred" +βœ… **Specific**: "We couldn't save your changes" + +❌ **Blaming**: "Invalid email address" +βœ… **Guiding**: "Email must include @" + +❌ **Technical**: "ERR_CONNECTION_TIMEOUT" +βœ… **Human**: "Connection timed out. Check your internet and try again." + +❌ **No solution**: "Upload failed" +βœ… **Actionable**: "Upload failed. Check your file size and try again." + +❌ **Passive**: "Your request could not be processed" +βœ… **Active**: "We couldn't process your request" + +## Quick Fill Template + +Use this for rapid error message drafting: + +**What failed:** +**Why (if known):** +**What user should do:** + +**Draft:** +[What failed]. [Why, if known]. [Next action]. + +**Example filled:** +- What failed: Couldn't send invite +- Why: Email bounced +- What to do: Check spelling + +Draft: "Couldn't send invite. Check the email address and try again." diff --git a/src/modules/ux-writer/templates/onboarding-flow-template.md b/src/modules/ux-writer/templates/onboarding-flow-template.md new file mode 100644 index 00000000..3c5fd541 --- /dev/null +++ b/src/modules/ux-writer/templates/onboarding-flow-template.md @@ -0,0 +1,303 @@ +# Onboarding Flow Template + +Use this template to design clear, encouraging onboarding experiences that help users succeed quickly. + +## Onboarding Principles + +1. **Show value early** β€” Help users succeed in their first session +2. **Progressive disclosure** β€” Don't overwhelm with all features at once +3. **Optional whenever possible** β€” Let users skip and explore +4. **Celebrate small wins** β€” Acknowledge each completed step +5. **Be concise** β€” Users want to start using the product, not read about it + +## Core Flow Structure + +``` +Welcome β†’ Setup β†’ First Success β†’ Next Steps +``` + +Each step should answer: +- **Where am I?** (Progress indicator) +- **What do I do here?** (Clear instruction) +- **Why does this matter?** (Benefit to user) +- **Can I skip this?** (Exit option) + +## Template: Welcome Screen + +**Purpose**: Orient user and set expectations + +``` +**Headline**: [Welcome + value proposition] +**Body**: [2-3 benefits, bulleted] +**Primary CTA**: [Get started action] +**Secondary CTA**: [Sign in, if applicable] +``` + +**Example:** +``` +**Headline**: Welcome to TaskFlow +**Body**: +β€’ Organize projects with your team +β€’ Track progress in real time +β€’ Never miss a deadline + +**Primary CTA**: Create account +**Secondary CTA**: Sign in +``` + +--- + +## Template: Account Setup + +**Purpose**: Collect essential information only + +``` +**Title**: [Action-oriented title] +**Body**: [Why this information is needed] +**Fields**: [Minimum required fields] +**Primary CTA**: [Continue/Next action] +**Secondary CTA**: [Skip, if truly optional] +``` + +**Example:** +``` +**Title**: Tell us about yourself +**Body**: We'll personalize your experience. + +**Fields**: +- Name +- Email +- Password + +**Primary CTA**: Continue +**Secondary CTA**: I'll do this later +``` + +**Best practices:** +- Only ask for what you absolutely need now +- Explain why each field is required +- Use smart defaults when possible +- Allow skipping optional steps + +--- + +## Template: Feature Introduction + +**Purpose**: Teach one feature at a time through action + +``` +**Title**: [Feature name + benefit] +**Body**: [Brief explanation, 1-2 sentences] +**Visual**: [Screenshot or illustration] +**Primary CTA**: [Action to try the feature] +**Secondary CTA**: Skip / Next +**Progress**: [X of Y steps] +``` + +**Example:** +``` +**Title**: Create your first project +**Body**: Projects help you organize related tasks and collaborate with your team. + +[Visual: Screenshot of project view] + +**Primary CTA**: Create project +**Secondary CTA**: Skip for now +**Progress**: Step 2 of 4 +``` + +**Best practices:** +- Show, don't tell (use visuals) +- Let users try immediately +- Keep explanations under 20 words +- Always allow skipping + +--- + +## Template: First Success / Completion + +**Purpose**: Celebrate user's first win, encourage next action + +``` +**Title**: [Celebratory statement] +**Body**: [What they accomplished + what's possible next] +**Primary CTA**: [Next natural action] +**Secondary CTA**: [Alternative or exit to product] +``` + +**Example:** +``` +**Title**: You're all set! +**Body**: You created your first project. Ready to invite your team? + +**Primary CTA**: Invite team members +**Secondary CTA**: Explore on my own +``` + +**Best practices:** +- Use exclamation points sparingly (once per flow max) +- Make the celebration feel earned +- Suggest logical next step +- Provide exit to main product + +--- + +## Onboarding Step Checklist + +For each step in your onboarding flow, verify: + +- [ ] **Single focus** β€” One action or concept per step +- [ ] **Clear value** β€” User knows why this matters +- [ ] **Actionable** β€” User knows exactly what to do +- [ ] **Skipable** β€” Optional steps can be skipped +- [ ] **Progress visible** β€” User knows how many steps remain +- [ ] **Concise** β€” Body text under 30 words +- [ ] **Appropriate tone** β€” Encouraging without being patronizing + +## Content Patterns by Step Type + +### Welcome/Introduction +**Pattern**: "Welcome to [Product]. [Do X to achieve Y]." + +Examples: +- "Welcome to Notion. Create beautiful docs, wikis, and projects." +- "Welcome to Figma. Design, prototype, and collaborate in real time." + +### Permission Request +**Pattern**: "Enable [permission] to [specific benefit]" + +Examples: +- "Enable notifications to stay updated on team activity" +- "Allow camera access to scan documents instantly" + +### Feature Tutorial +**Pattern**: "[Action]. [Brief benefit]." + +Examples: +- "Add your first task. Stay organized and never miss a deadline." +- "Create a workspace. Collaborate with your team in one place." + +### Completion +**Pattern**: "[Celebration]! [What's now possible]. [Optional: Next step]" + +Examples: +- "You're ready to go! Start creating, or invite teammates to collaborate." +- "Setup complete! Your workspace is ready for your team." + +## Tone Variations + +### Professional/B2B +``` +**Title**: Set up your workspace +**Body**: Add team members and create your first project. +**CTA**: Continue setup +``` + +### Consumer/Casual +``` +**Title**: Let's get you started! +**Body**: This will only take a minute. +**CTA**: Let's go +``` + +### Technical/Developer +``` +**Title**: Configure your environment +**Body**: Connect your repository to start deploying. +**CTA**: Connect repo +``` + +## Multi-Screen Flow Example + +### Screen 1: Welcome +``` +**Welcome to WriteRight** + +Write better, faster with AI-powered editing. + +β€’ Fix grammar instantly +β€’ Improve clarity and tone +β€’ Write with confidence + +[Get started] +``` + +### Screen 2: Setup +``` +**What brings you to WriteRight?** (2 of 4) + +Select all that apply: +β–‘ Business writing +β–‘ Creative writing +β–‘ Student papers +β–‘ Personal projects + +[Continue] [Skip] +``` + +### Screen 3: First Action +``` +**Try it out** (3 of 4) + +Paste any text below and watch WriteRight improve it. + +[Text input box] + +[Analyze my writing] [Skip] +``` + +### Screen 4: Success +``` +**Nice work!** + +You improved your first piece of writing. Ready to write your next masterpiece? + +[Start writing] [See tips] +``` + +## Common Mistakes to Avoid + +❌ **Too many steps**: 10+ screens before using the product +βœ… **Focused flow**: 3-5 steps to first value + +❌ **Feature dump**: "Here are 47 things you can do!" +βœ… **Progressive disclosure**: One key feature at a time + +❌ **No skip option**: Forcing users through every screen +βœ… **Respect choice**: Skip available for optional features + +❌ **Passive voice**: "Your account has been created" +βœ… **Active voice**: "You created your account!" + +❌ **Corporate speak**: "Facilitate enhanced productivity" +βœ… **Plain language**: "Get more done" + +## Quick Flow Builder + +Use this to draft a basic onboarding flow: + +**Product name:** +**Core value (one sentence):** +**Key features to introduce (pick 2-3):** +1. +2. +3. + +**First user action that shows value:** +**Celebration/success moment:** + +**Draft flow:** +1. Welcome β†’ [Value prop] +2. Setup β†’ [Essential info only] +3. Feature 1 β†’ [Try it action] +4. Feature 2 β†’ [Try it action] +5. Success β†’ [Celebrate + next step] + +## Testing Your Onboarding + +Questions to answer: +1. Can users complete onboarding in under 2 minutes? +2. Do users achieve something meaningful in their first session? +3. Can users skip optional steps without confusion? +4. Is the tone encouraging without being condescending? +5. Does each screen have a single, clear purpose? diff --git a/src/modules/ux-writer/templates/quality-scorecard.md b/src/modules/ux-writer/templates/quality-scorecard.md new file mode 100644 index 00000000..25295fc6 --- /dev/null +++ b/src/modules/ux-writer/templates/quality-scorecard.md @@ -0,0 +1,287 @@ +# UX Text Quality Scorecard + +Use this scorecard to objectively evaluate interface copy against the Four Quality Standards framework. + +## Text Being Evaluated + +**Text:** _________________________________________ + +**Type:** ☐ Button ☐ Error ☐ Success ☐ Empty State ☐ Notification ☐ Form ☐ Other: _______ + +**Context:** _________________________________________ + +**User scenario:** _________________________________________ + +--- + +## 1. Purposeful (0-10) + +Does this text help users or the business achieve goals? + +### Evaluation Criteria +- [ ] User benefit is clear +- [ ] Helps user accomplish their goal +- [ ] Addresses anticipated user concerns +- [ ] Advances business objectives +- [ ] Value proposition is explicit + +### Scoring + +☐ **9-10 (Excellent)**: Clear user benefit, addresses concerns, advances goals +☐ **7-8 (Good)**: User benefit present, addresses most concerns +☐ **5-6 (Adequate)**: Some user benefit, generic value +☐ **3-4 (Needs Work)**: Unclear purpose, doesn't obviously help user +☐ **1-2 (Poor)**: No discernible benefit, system-focused +☐ **0 (Unacceptable)**: Actively hinders goals + +**Score: _____ / 10** + +**Notes:** +_________________________________________ +_________________________________________ + +--- + +## 2. Concise (0-10) + +Does this use the fewest words possible without losing meaning? + +### Evaluation Criteria +- [ ] No wasted words +- [ ] Meets pattern benchmark +- [ ] Information is front-loaded +- [ ] Every word earns its space +- [ ] No redundant phrases + +### Word Count & Benchmarks + +**Current word count:** _____ words +**Current character count:** _____ characters + +**Benchmarks:** +- Buttons/CTAs: 2-4 words ideal, 6 max +- Error messages: 12-18 words +- Titles: 3-6 words, 40 chars max +- Instructions: 14 words ideal, 20 max +- Notifications: 10-15 words + +**Meets benchmark?** ☐ Yes ☐ No ☐ N/A + +### Scoring + +☐ **9-10 (Excellent)**: No wasted words, meets/beats benchmark +☐ **7-8 (Good)**: Generally concise, close to benchmark +☐ **5-6 (Adequate)**: Some unnecessary words, slightly over +☐ **3-4 (Needs Work)**: Verbose, well over benchmark +☐ **1-2 (Poor)**: Extremely wordy, far exceeds benchmark +☐ **0 (Unacceptable)**: Incomprehensibly verbose + +**Score: _____ / 10** + +**Notes:** +_________________________________________ +_________________________________________ + +--- + +## 3. Conversational (0-10) + +Does this sound natural and human, not robotic? + +### Evaluation Criteria +- [ ] Would say this out loud +- [ ] Uses active voice (target: 85%) +- [ ] Includes natural connecting words +- [ ] Free of corporate jargon +- [ ] Feels human and warm + +### Voice Analysis + +**Active or passive?** ☐ Active ☐ Passive ☐ Mixed + +**Contains jargon/robotic phrases?** ☐ Yes ☐ No + +**Examples of robotic phrases to avoid:** +- "An error has occurred" +- "Your request has been received" +- "Please be advised that" +- "Kindly note that" + +### Scoring + +☐ **9-10 (Excellent)**: Completely natural, would say in person +☐ **7-8 (Good)**: Mostly natural, minor stiffness +☐ **5-6 (Adequate)**: Some natural elements, mix of active/passive +☐ **3-4 (Needs Work)**: Stiff and formal, heavy passive voice +☐ **1-2 (Poor)**: Extremely robotic, all passive voice +☐ **0 (Unacceptable)**: Incomprehensible jargon + +**Score: _____ / 10** + +**Notes:** +_________________________________________ +_________________________________________ + +--- + +## 4. Clear (0-10) + +Is this unambiguous and easy to understand? + +### Evaluation Criteria +- [ ] Unambiguous - only one interpretation +- [ ] Uses specific, meaningful verbs +- [ ] Consistent terminology +- [ ] Meets reading level target +- [ ] Free of technical jargon (unless appropriate) + +### Clarity Analysis + +**Reading level:** _____ grade (Target: 7th-10th for general audience) + +**Uses specific verbs?** ☐ Yes ☐ No +**Examples:** _________________________________________ + +**Any ambiguous phrases?** ☐ Yes ☐ No +**Examples:** _________________________________________ + +**Consistent with product terminology?** ☐ Yes ☐ No + +### Scoring + +☐ **9-10 (Excellent)**: Crystal clear, unambiguous, perfect terminology +☐ **7-8 (Good)**: Generally clear, minor ambiguities +☐ **5-6 (Adequate)**: Understandable, some ambiguity +☐ **3-4 (Needs Work)**: Confusing, significant ambiguity +☐ **1-2 (Poor)**: Very confusing, highly ambiguous +☐ **0 (Unacceptable)**: Incomprehensible + +**Score: _____ / 10** + +**Notes:** +_________________________________________ +_________________________________________ + +--- + +## Overall Assessment + +### Total Score + +**Purposeful:** _____ / 10 +**Concise:** _____ / 10 +**Conversational:** _____ / 10 +**Clear:** _____ / 10 + +**Overall Average:** _____ / 10 + +### Quality Benchmark + +☐ **9-10 (Excellent)**: Ship it - Meets all standards +☐ **8-8.9 (Very Good)**: Minor tweaks only +☐ **7-7.9 (Good)**: Consider improvements +☐ **6-6.9 (Adequate)**: Needs work +☐ **Below 6 (Poor)**: Requires significant revision + +--- + +## Improvement Recommendations + +### Priority Issues (Score < 7) + +**1.** _________________________________________ +**2.** _________________________________________ +**3.** _________________________________________ + +### Suggested Improvements + +**Revised text:** +_________________________________________ +_________________________________________ + +**Expected new scores:** +- Purposeful: _____ / 10 +- Concise: _____ / 10 +- Conversational: _____ / 10 +- Clear: _____ / 10 +- **Overall: _____ / 10** + +--- + +## Accessibility Check + +- [ ] Works for screen readers (descriptive labels) +- [ ] Doesn't rely on color alone +- [ ] Uses plain language (appropriate reading level) +- [ ] Sentence length appropriate (8-14 words for critical content) +- [ ] Provides text alternatives for icons + +**Accessibility concerns:** _________________________________________ + +--- + +## Pattern Compliance + +**Does this follow best practices for its pattern?** + +**Buttons:** +- [ ] Uses imperative verb + object +- [ ] Describes specific action +- [ ] Avoids generic labels (OK, Submit) + +**Errors:** +- [ ] States what failed +- [ ] Explains why (if known) +- [ ] Provides recovery action +- [ ] Doesn't blame user + +**Success:** +- [ ] Past tense +- [ ] Specific action +- [ ] Brief confirmation + +**Empty states:** +- [ ] Explains why empty +- [ ] Provides clear CTA +- [ ] Encouraging tone + +**Forms:** +- [ ] Clear labels +- [ ] Helpful instructions +- [ ] Appropriate placeholder use + +--- + +## Context Appropriateness + +**User emotional state:** ☐ Confident ☐ Frustrated ☐ Confused ☐ Cautious ☐ Successful + +**Tone matches state?** ☐ Yes ☐ No + +**Stakes:** ☐ Low ☐ Medium ☐ High + +**Tone matches stakes?** ☐ Yes ☐ No + +--- + +## Final Recommendation + +☐ **Ship as is** - Scores 9+ overall +☐ **Minor tweaks** - Scores 8-8.9 +☐ **Needs improvement** - Scores 6-7.9 +☐ **Requires revision** - Scores below 6 + +**Priority:** ☐ High ☐ Medium ☐ Low + +**Next steps:** +_________________________________________ +_________________________________________ + +--- + +## Reviewer Information + +**Reviewer:** _________________________________________ +**Date:** _________________________________________ +**Product/Feature:** _________________________________________ +**Review cycle:** ☐ Initial ☐ Revision 1 ☐ Revision 2 ☐ Final diff --git a/src/modules/ux-writer/templates/voice-chart-template.md b/src/modules/ux-writer/templates/voice-chart-template.md new file mode 100644 index 00000000..87f9c03c --- /dev/null +++ b/src/modules/ux-writer/templates/voice-chart-template.md @@ -0,0 +1,132 @@ +# Voice Chart Template + +A voice chart helps establish consistent brand personality across all UX text. Use this template to define your product's voice. + +## Structure + +A voice chart contains three key elements for each brand concept: + +1. **Concept** β€” A core brand principle or value +2. **Voice Characteristics** β€” Adjectives describing how the concept manifests in writing +3. **Examples** β€” Concrete do/don't pairs showing the voice in action + +## Template + +### Concept 1: [Brand Principle] + +**Voice characteristics**: [Adjective 1], [Adjective 2], [Adjective 3] + +**Description**: [1-2 sentences explaining what this means for the writing] + +**Do**: +- Example of text that embodies this concept +- Another example showing this voice + +**Don't**: +- Example of what to avoid +- Counter-example that violates this voice + +--- + +### Concept 2: [Brand Principle] + +**Voice characteristics**: [Adjective 1], [Adjective 2], [Adjective 3] + +**Description**: [1-2 sentences explaining what this means for the writing] + +**Do**: +- Example of text that embodies this concept +- Another example showing this voice + +**Don't**: +- Example of what to avoid +- Counter-example that violates this voice + +--- + +### Concept 3: [Brand Principle] + +**Voice characteristics**: [Adjective 1], [Adjective 2], [Adjective 3] + +**Description**: [1-2 sentences explaining what this means for the writing] + +**Do**: +- Example of text that embodies this concept +- Another example showing this voice + +**Don't**: +- Example of what to avoid +- Counter-example that violates this voice + +--- + +## Example: TAPP Transit System + +### Concept 1: Helpful + +**Voice characteristics**: Friendly, supportive, clear + +**Description**: TAPP is a companion that helps riders navigate the transit system with confidence. We anticipate questions and provide clear guidance. + +**Do**: +- "Your bus arrives in 5 minutes at Bay St." +- "Tap your card when you board and when you exit." + +**Don't**: +- "Arrival: 5 min" +- "Payment required at entry and exit points." + +--- + +### Concept 2: Efficient + +**Voice characteristics**: Concise, direct, scannable + +**Description**: Riders are often in a hurry. We respect their time by being brief and front-loading important information. + +**Do**: +- "Route delayed 10 minutes due to traffic" +- "Transfer at Main St for Line 3" + +**Don't**: +- "Due to unexpected traffic conditions, your route is experiencing delays of approximately 10 minutes" +- "You can transfer to Line 3 if you get off at Main St" + +--- + +### Concept 3: Trustworthy + +**Voice characteristics**: Honest, transparent, reliable + +**Description**: Riders depend on TAPP to get where they need to go. We're upfront about problems and provide accurate information. + +**Do**: +- "This route is currently unavailable. Use Route 42 instead." +- "Your payment didn't go through. Update your card to continue." + +**Don't**: +- "Service interruption on this route." +- "Payment error. Try again." + +--- + +## Tips for Creating Your Voice Chart + +1. **Base it on brand values** β€” Review mission, vision, values, and personality +2. **Use 3-5 concepts** β€” Enough to guide, not so many you can't remember +3. **Be specific with examples** β€” Show actual interface text, not abstract descriptions +4. **Test against real scenarios** β€” Apply to buttons, errors, and notifications +5. **Share with your team** β€” Voice only works if everyone uses it consistently +6. **Update as you learn** β€” Refine based on user research and team feedback + +## Common Voice Characteristics + +**Positive tones**: Friendly, encouraging, optimistic, warm, enthusiastic, cheerful, supportive, welcoming, inspiring + +**Neutral tones**: Professional, straightforward, clear, direct, informative, practical, matter-of-fact, efficient + +**Cautious/Serious tones**: Careful, thoughtful, measured, precise, formal, reserved, respectful + +**Personality traits**: Playful, witty, conversational, casual, technical, sophisticated, humble, confident, empowering + +Choose characteristics that align with your brand and serve your users' needs in context.