feat: add UX Writer module - interface copy specialist with Four Quality Standards
Add comprehensive UX Writing module based on https://github.com/content-designer/ux-writing-skill This module provides AI-powered interface copy creation and analysis using the research-backed Four Quality Standards framework (Purposeful, Concise, Conversational, Clear). **Agent:** - UX Writer (Alex) - Expert UX writing specialist - Complete persona with 11 specialized commands - Quality scoring system (0-10 scale per standard) - Pattern-based approach for all UI elements **Core Capabilities:** - Analyze existing text with objective scoring - Create new interface copy for all patterns - Improve existing copy with before/after comparison - Content audits for consistency - Voice chart creation and tone adaptation - Accessibility compliance checking - Research-backed benchmark scoring **UI Patterns Covered:** - Buttons and links - Error messages (inline, detour, blocking) - Success messages - Empty states (first-use, cleared, no-results) - Notifications and alerts - Form fields (labels, instructions, placeholders) - Onboarding flows - Help text and tooltips **Quality Framework:** The Four Quality Standards with objective 0-10 scoring: 1. Purposeful - Helps users/business achieve goals 2. Concise - Fewest words without losing meaning 3. Conversational - Natural and human, not robotic 4. Clear - Unambiguous and easy to understand **Research-Backed Benchmarks:** - Sentence length targets (8-14 words for 90%+ comprehension) - Word count limits by UI element - Reading level guidelines (7th-12th grade) - Character count benchmarks - Active voice target (85%) **Tasks (3):** - analyze-ux-text.md - Score against four standards - create-ux-text.md - Pattern-based creation with elicitation - improve-ux-text.md - Before/after with detailed analysis **Templates (5):** - error-message-template.md - Error message creation guide - empty-state-template.md - Empty state design framework - onboarding-flow-template.md - Onboarding step-by-step - voice-chart-template.md - Voice documentation - quality-scorecard.md - Evaluation scorecard **Data Resources (6):** - four-quality-standards.md - Complete framework (detailed scoring rubrics) - ux-writing-benchmarks.md - Research metrics (comprehension, reading levels) - patterns-detailed.md - Pattern library with examples in 3 voices - accessibility-guidelines.md - WCAG compliance for UX writing - content-usability-checklist.md - Quality evaluation - real-world-improvements.md - Before/after with scoring **Key Features:** - Objective quality scoring (not subjective) - Evidence-based approach (research-backed metrics) - Accessibility-first (WCAG AA compliance) - Tone adaptation (5 emotional states: frustrated, confused, confident, cautious, successful) - Pattern library (proven approaches for all UI elements) - Multiple variations (brainstorm alternatives) - Interactive elicitation (context gathering) **Module Configuration:** - Target audience selection (general, professional, technical, specialized) - Reading level targets (7th-12th grade) - Quality thresholds (7-9/10) - Tone adaptation modes - Accessibility compliance levels - Content type preferences Total files: 17 Source: https://github.com/content-designer/ux-writing-skill (MIT License) Credits: Christopher Greer (Stripe), Sarah Richards, Torrey Podmajersky, Google Material Design
This commit is contained in:
Claude
parent
63bf649b28
commit
9f0664a8c5
|
|
@ -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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<sub>Write interface copy that helps users succeed</sub>
|
||||||
|
</p>
|
||||||
|
|
@ -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"
|
||||||
|
|
@ -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"
|
||||||
|
|
@ -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.
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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.
|
||||||
|
|
@ -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?**
|
||||||
|
|
@ -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)
|
||||||
|
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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."
|
||||||
|
|
@ -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?
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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.
|
||||||
Loading…
Reference in New Issue