Merge pull request #4 from jamon8888/claude/bmad-career-coach-setup-017hT71W8pGVVCuMtEB9F1hF
feat: add UX Writer module - interface copy specialist with Four Qual…
This commit is contained in:
Jamin
GitHub
commit
8ffd951012
|
|
@ -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 '..', no leading/trailing dot, and only letters, numbers, dashes, underscores, slashes, and dots)."
|
||||
|
||||
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