Initial commit
This commit is contained in:
Zhongwei Li
20
.claude-plugin/plugin.json
Normal file
20
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,20 @@
|
|||||||
|
{
|
||||||
|
"name": "design",
|
||||||
|
"description": "User-centered design team with 4 specialized roles covering UX research, writing, accessibility, and creative direction",
|
||||||
|
"version": "1.0.0",
|
||||||
|
"author": {
|
||||||
|
"name": "Puerto"
|
||||||
|
},
|
||||||
|
"skills": [
|
||||||
|
"./skills/ux-research",
|
||||||
|
"./skills/ux-writing",
|
||||||
|
"./skills/accessibility",
|
||||||
|
"./skills/brand-strategy"
|
||||||
|
],
|
||||||
|
"agents": [
|
||||||
|
"./agents/design-lead.md",
|
||||||
|
"./agents/ux-researcher.md",
|
||||||
|
"./agents/ux-writer.md",
|
||||||
|
"./agents/accessibility-specialist.md"
|
||||||
|
]
|
||||||
|
}
|
||||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
|||||||
|
# design
|
||||||
|
|
||||||
|
User-centered design team with 4 specialized roles covering UX research, writing, accessibility, and creative direction
|
||||||
39
agents/accessibility-specialist.md
Normal file
39
agents/accessibility-specialist.md
Normal file
@@ -0,0 +1,39 @@
|
|||||||
|
# Accessibility Specialist
|
||||||
|
|
||||||
|
PROACTIVELY use for WCAG compliance, accessibility audits, inclusive design, and accessibility implementation. Ensures products are usable by everyone, including people with disabilities.
|
||||||
|
|
||||||
|
**Core Capabilities:**
|
||||||
|
- WCAG 2.1 Level AA compliance
|
||||||
|
- Accessibility audits and testing
|
||||||
|
- Screen reader compatibility
|
||||||
|
- Keyboard navigation design
|
||||||
|
- Color contrast analysis
|
||||||
|
- ARIA implementation guidance
|
||||||
|
- Accessible component patterns
|
||||||
|
- Assistive technology testing
|
||||||
|
- Accessibility documentation
|
||||||
|
- Inclusive design principles
|
||||||
|
- Accessibility remediation
|
||||||
|
- Compliance reporting (VPAT/ACR)
|
||||||
|
|
||||||
|
**When to Use:**
|
||||||
|
- Accessibility audits and compliance checks
|
||||||
|
- WCAG compliance validation
|
||||||
|
- Accessible component design
|
||||||
|
- Screen reader optimization
|
||||||
|
- Keyboard navigation implementation
|
||||||
|
- Color contrast fixes
|
||||||
|
- Accessibility documentation
|
||||||
|
- Inclusive design consulting
|
||||||
|
|
||||||
|
**Tools Available:** Read, Write, Edit, Bash, Grep, Glob
|
||||||
|
|
||||||
|
**Skills:** accessibility, ux-research, ux-writing
|
||||||
|
|
||||||
|
**Examples:**
|
||||||
|
- "Conduct WCAG 2.1 Level AA compliance audit"
|
||||||
|
- "Fix accessibility issues in navigation component"
|
||||||
|
- "Create accessible data table with ARIA"
|
||||||
|
- "Improve keyboard navigation for modal dialogs"
|
||||||
|
- "Write accessibility documentation for design system"
|
||||||
|
- "Test product with screen readers and provide fixes"
|
||||||
36
agents/design-lead.md
Normal file
36
agents/design-lead.md
Normal file
@@ -0,0 +1,36 @@
|
|||||||
|
# Design Lead
|
||||||
|
|
||||||
|
PROACTIVELY use for creative direction, brand consistency, design systems, and design team leadership. Provides strategic design guidance and ensures cohesive visual identity.
|
||||||
|
|
||||||
|
**Core Capabilities:**
|
||||||
|
- Creative direction and vision
|
||||||
|
- Brand strategy and positioning
|
||||||
|
- Design system architecture
|
||||||
|
- Visual identity development
|
||||||
|
- Design team coordination
|
||||||
|
- Stakeholder communication
|
||||||
|
- Design critique and feedback
|
||||||
|
- Cross-functional collaboration
|
||||||
|
- Design standards and guidelines
|
||||||
|
- User experience strategy
|
||||||
|
|
||||||
|
**When to Use:**
|
||||||
|
- Setting creative direction
|
||||||
|
- Brand strategy development
|
||||||
|
- Design system planning
|
||||||
|
- High-level design decisions
|
||||||
|
- Design review and critique
|
||||||
|
- Cross-team design coordination
|
||||||
|
- Visual identity guidelines
|
||||||
|
|
||||||
|
**Tools Available:** Read, Write, Edit, Bash, Grep, Glob
|
||||||
|
|
||||||
|
**Skills:** brand-strategy, ux-research, accessibility
|
||||||
|
|
||||||
|
**Examples:**
|
||||||
|
- "Define visual identity and brand guidelines for new product"
|
||||||
|
- "Create design system architecture with component hierarchy"
|
||||||
|
- "Provide creative direction for marketing campaign"
|
||||||
|
- "Review designs for brand consistency"
|
||||||
|
- "Plan design sprint for feature discovery"
|
||||||
|
- "Establish design quality standards and processes"
|
||||||
39
agents/ux-researcher.md
Normal file
39
agents/ux-researcher.md
Normal file
@@ -0,0 +1,39 @@
|
|||||||
|
# UX Researcher
|
||||||
|
|
||||||
|
PROACTIVELY use for user research, usability testing, user insights, and data-driven design decisions. Conducts research to understand user needs, behaviors, and pain points.
|
||||||
|
|
||||||
|
**Core Capabilities:**
|
||||||
|
- User research planning and execution
|
||||||
|
- Usability testing (moderated and unmoderated)
|
||||||
|
- User interviews and contextual inquiry
|
||||||
|
- Surveys and questionnaires
|
||||||
|
- Card sorting and tree testing
|
||||||
|
- Analytics analysis and insights
|
||||||
|
- Persona development
|
||||||
|
- Journey mapping
|
||||||
|
- Research synthesis and reporting
|
||||||
|
- A/B test design and analysis
|
||||||
|
- Heuristic evaluation
|
||||||
|
- Accessibility auditing
|
||||||
|
|
||||||
|
**When to Use:**
|
||||||
|
- Planning user research studies
|
||||||
|
- Conducting usability tests
|
||||||
|
- User interview facilitation
|
||||||
|
- Creating personas and journey maps
|
||||||
|
- Analyzing user behavior data
|
||||||
|
- Validating design decisions
|
||||||
|
- Identifying user pain points
|
||||||
|
- Research synthesis and insights
|
||||||
|
|
||||||
|
**Tools Available:** Read, Write, Edit, Bash, Grep, Glob
|
||||||
|
|
||||||
|
**Skills:** ux-research, accessibility
|
||||||
|
|
||||||
|
**Examples:**
|
||||||
|
- "Design and conduct usability testing for checkout flow"
|
||||||
|
- "Create user personas based on research data"
|
||||||
|
- "Plan user interview guide for feature discovery"
|
||||||
|
- "Analyze analytics data to identify usability issues"
|
||||||
|
- "Conduct heuristic evaluation of existing interface"
|
||||||
|
- "Synthesize research findings into actionable insights"
|
||||||
38
agents/ux-writer.md
Normal file
38
agents/ux-writer.md
Normal file
@@ -0,0 +1,38 @@
|
|||||||
|
# UX Writer
|
||||||
|
|
||||||
|
PROACTIVELY use for content strategy, microcopy, voice and tone, and user-facing text. Crafts clear, consistent, and user-friendly copy across all touchpoints.
|
||||||
|
|
||||||
|
**Core Capabilities:**
|
||||||
|
- UX writing and microcopy
|
||||||
|
- Content strategy and planning
|
||||||
|
- Voice and tone guidelines
|
||||||
|
- Information architecture
|
||||||
|
- Error messages and notifications
|
||||||
|
- Onboarding copy
|
||||||
|
- In-product education
|
||||||
|
- Accessibility-focused writing
|
||||||
|
- Localization support
|
||||||
|
- Content design systems
|
||||||
|
- Call-to-action optimization
|
||||||
|
|
||||||
|
**When to Use:**
|
||||||
|
- Writing user-facing copy
|
||||||
|
- Creating content strategy
|
||||||
|
- Developing voice and tone guidelines
|
||||||
|
- Error message optimization
|
||||||
|
- Onboarding flow copy
|
||||||
|
- Button and CTA text
|
||||||
|
- Help documentation
|
||||||
|
- Accessibility improvements in copy
|
||||||
|
|
||||||
|
**Tools Available:** Read, Write, Edit, Bash, Grep, Glob
|
||||||
|
|
||||||
|
**Skills:** ux-writing, accessibility
|
||||||
|
|
||||||
|
**Examples:**
|
||||||
|
- "Write onboarding flow copy for new users"
|
||||||
|
- "Create voice and tone guidelines for product"
|
||||||
|
- "Optimize error messages for clarity and helpfulness"
|
||||||
|
- "Write accessible button labels and alt text"
|
||||||
|
- "Develop content strategy for feature launch"
|
||||||
|
- "Create microcopy for complex form interactions"
|
||||||
73
plugin.lock.json
Normal file
73
plugin.lock.json
Normal file
@@ -0,0 +1,73 @@
|
|||||||
|
{
|
||||||
|
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||||
|
"pluginId": "gh:bandofai/puerto:plugins/design",
|
||||||
|
"normalized": {
|
||||||
|
"repo": null,
|
||||||
|
"ref": "refs/tags/v20251128.0",
|
||||||
|
"commit": "2d0bd4eee8d4f63b8436ef46b1a7c8e4d31c15c2",
|
||||||
|
"treeHash": "af6e7cf43e4cc1fbfb4d86caf98d6102d7cc6e809afc00ae2a13c14ebac417af",
|
||||||
|
"generatedAt": "2025-11-28T10:14:08.778593Z",
|
||||||
|
"toolVersion": "publish_plugins.py@0.2.0"
|
||||||
|
},
|
||||||
|
"origin": {
|
||||||
|
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||||
|
"branch": "master",
|
||||||
|
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||||
|
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||||
|
},
|
||||||
|
"manifest": {
|
||||||
|
"name": "design",
|
||||||
|
"description": "User-centered design team with 4 specialized roles covering UX research, writing, accessibility, and creative direction",
|
||||||
|
"version": "1.0.0"
|
||||||
|
},
|
||||||
|
"content": {
|
||||||
|
"files": [
|
||||||
|
{
|
||||||
|
"path": "README.md",
|
||||||
|
"sha256": "ca4031b384682405be47c3aebc471939178a1428f4134b8067a836c51ee75972"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "agents/design-lead.md",
|
||||||
|
"sha256": "05974f3eceafb7d8250324d7df7ef9b162b6f441c318064894163bf950a9b120"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "agents/ux-writer.md",
|
||||||
|
"sha256": "331ac614dcfc34ba624807f276246f961bcdbb7cd5b215d4244cf673f767a5ee"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "agents/ux-researcher.md",
|
||||||
|
"sha256": "868af6b8804d11fee5dde04983a6ea71661fbb8fd99fbcdd58ce385efb2bd1cc"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "agents/accessibility-specialist.md",
|
||||||
|
"sha256": "7751c2b249829843bbebfd56a72d420ae29b311a7a0e86ba9e8e9cf44a7dbdb0"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": ".claude-plugin/plugin.json",
|
||||||
|
"sha256": "592a165d1b512956f3a02e69fff8d9936695745a15099d631667aced5b89b242"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/brand-strategy/SKILL.md",
|
||||||
|
"sha256": "c697f67c2a95165ed55d7e3e959fa9d666b5a9d12011265d1752e183a3e31ca9"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/ux-research/SKILL.md",
|
||||||
|
"sha256": "8206fd12afabbf5127f08753608a086fd8652459dbd046207dd08b9911ddd4a0"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/ux-writing/SKILL.md",
|
||||||
|
"sha256": "d0af7408053d0e189ddef2cc980f6d59ddd4852bc570b6212e9e2aaf4b5b4c7a"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"path": "skills/accessibility/SKILL.md",
|
||||||
|
"sha256": "232a9ebe601b8b07ad9e5139512be33aefb438cbeb37723603287227dc563747"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"dirSha256": "af6e7cf43e4cc1fbfb4d86caf98d6102d7cc6e809afc00ae2a13c14ebac417af"
|
||||||
|
},
|
||||||
|
"security": {
|
||||||
|
"scannedAt": null,
|
||||||
|
"scannerVersion": null,
|
||||||
|
"flags": []
|
||||||
|
}
|
||||||
|
}
|
||||||
134
skills/accessibility/SKILL.md
Normal file
134
skills/accessibility/SKILL.md
Normal file
@@ -0,0 +1,134 @@
|
|||||||
|
# Accessibility Standards
|
||||||
|
|
||||||
|
**WCAG 2.1 Level AA compliance patterns and best practices**
|
||||||
|
|
||||||
|
## Core Principles
|
||||||
|
|
||||||
|
### 1. Perceivable
|
||||||
|
- Provide text alternatives for non-text content
|
||||||
|
- Provide captions and transcripts for multimedia
|
||||||
|
- Create content that can be presented in different ways
|
||||||
|
- Make it easier for users to see and hear content
|
||||||
|
|
||||||
|
### 2. Operable
|
||||||
|
- Make all functionality available from keyboard
|
||||||
|
- Give users enough time to read and use content
|
||||||
|
- Do not design content that causes seizures
|
||||||
|
- Help users navigate and find content
|
||||||
|
|
||||||
|
### 3. Understandable
|
||||||
|
- Make text readable and understandable
|
||||||
|
- Make content appear and operate in predictable ways
|
||||||
|
- Help users avoid and correct mistakes
|
||||||
|
|
||||||
|
### 4. Robust
|
||||||
|
- Maximize compatibility with current and future tools
|
||||||
|
|
||||||
|
## Implementation Patterns
|
||||||
|
|
||||||
|
### Semantic HTML
|
||||||
|
```html
|
||||||
|
<!-- ❌ BAD -->
|
||||||
|
<div onClick=handleClick>Click me</div>
|
||||||
|
|
||||||
|
<!-- ✅ GOOD -->
|
||||||
|
<button onClick={handleClick}>Click me</button>
|
||||||
|
```
|
||||||
|
|
||||||
|
### ARIA Labels
|
||||||
|
```html
|
||||||
|
<button aria-label="Close modal" onClick={onClose}>
|
||||||
|
<XIcon />
|
||||||
|
</button>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Keyboard Navigation
|
||||||
|
- Tab order should be logical
|
||||||
|
- Focus indicators must be visible
|
||||||
|
- All interactive elements accessible via keyboard
|
||||||
|
- Escape key closes modals/menus
|
||||||
|
|
||||||
|
### Color Contrast
|
||||||
|
- Normal text: 4.5:1 minimum
|
||||||
|
- Large text (18pt+): 3:1 minimum
|
||||||
|
- Interactive elements: 3:1 minimum
|
||||||
|
|
||||||
|
### Screen Reader Support
|
||||||
|
- Use proper heading hierarchy (h1-h6)
|
||||||
|
- Provide skip links
|
||||||
|
- Label form inputs properly
|
||||||
|
- Use live regions for dynamic content
|
||||||
|
|
||||||
|
## Testing Tools
|
||||||
|
|
||||||
|
- axe DevTools
|
||||||
|
- Pa11y
|
||||||
|
- Lighthouse
|
||||||
|
- NVDA/JAWS screen readers
|
||||||
|
- Keyboard-only navigation testing
|
||||||
|
|
||||||
|
## Common Patterns
|
||||||
|
|
||||||
|
### Accessible Forms
|
||||||
|
```tsx
|
||||||
|
<label htmlFor="email">
|
||||||
|
Email Address
|
||||||
|
<input
|
||||||
|
id="email"
|
||||||
|
type="email"
|
||||||
|
aria-required="true"
|
||||||
|
aria-describedby="email-error"
|
||||||
|
/>
|
||||||
|
</label>
|
||||||
|
{error && (
|
||||||
|
<span id="email-error" role="alert">
|
||||||
|
{error}
|
||||||
|
</span>
|
||||||
|
)}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Accessible Modals
|
||||||
|
```tsx
|
||||||
|
<div
|
||||||
|
role="dialog"
|
||||||
|
aria-modal="true"
|
||||||
|
aria-labelledby="dialog-title"
|
||||||
|
>
|
||||||
|
<h2 id="dialog-title">Modal Title</h2>
|
||||||
|
{/* Trap focus within modal */}
|
||||||
|
{/* Close on Escape */}
|
||||||
|
</div>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Accessible Tables
|
||||||
|
```html
|
||||||
|
<table>
|
||||||
|
<caption>Monthly Sales Data</caption>
|
||||||
|
<thead>
|
||||||
|
<tr>
|
||||||
|
<th scope="col">Month</th>
|
||||||
|
<th scope="col">Sales</th>
|
||||||
|
</tr>
|
||||||
|
</thead>
|
||||||
|
<tbody>
|
||||||
|
<tr>
|
||||||
|
<th scope="row">January</th>
|
||||||
|
<td>0,000</td>
|
||||||
|
</tr>
|
||||||
|
</tbody>
|
||||||
|
</table>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Checklist
|
||||||
|
|
||||||
|
- [ ] Keyboard navigation works
|
||||||
|
- [ ] Screen reader announces content properly
|
||||||
|
- [ ] Color contrast meets requirements
|
||||||
|
- [ ] Focus indicators visible
|
||||||
|
- [ ] Form labels present and associated
|
||||||
|
- [ ] Headings in logical order
|
||||||
|
- [ ] Alternative text for images
|
||||||
|
- [ ] ARIA used correctly (not overused)
|
||||||
|
- [ ] Error messages clear and accessible
|
||||||
|
- [ ] No keyboard traps
|
||||||
|
|
||||||
153
skills/brand-strategy/SKILL.md
Normal file
153
skills/brand-strategy/SKILL.md
Normal file
@@ -0,0 +1,153 @@
|
|||||||
|
# Brand Strategy
|
||||||
|
|
||||||
|
**Brand positioning, visual identity, and design system architecture**
|
||||||
|
|
||||||
|
## Brand Positioning Framework
|
||||||
|
|
||||||
|
### 1. Brand Foundation
|
||||||
|
- Mission: Why you exist
|
||||||
|
- Vision: Where you're going
|
||||||
|
- Values: What you believe
|
||||||
|
- Purpose: Your impact
|
||||||
|
|
||||||
|
### 2. Target Audience
|
||||||
|
- Demographics
|
||||||
|
- Psychographics
|
||||||
|
- Pain points
|
||||||
|
- Aspirations
|
||||||
|
|
||||||
|
### 3. Competitive Analysis
|
||||||
|
- Direct competitors
|
||||||
|
- Indirect competitors
|
||||||
|
- Market gaps
|
||||||
|
- Differentiation opportunities
|
||||||
|
|
||||||
|
### 4. Brand Positioning Statement
|
||||||
|
"For [target audience] who [need/want], [brand] is a [category] that [unique benefit] because [reason to believe]."
|
||||||
|
|
||||||
|
### 5. Brand Personality
|
||||||
|
- Voice and tone
|
||||||
|
- Character traits
|
||||||
|
- Communication style
|
||||||
|
- Visual aesthetic
|
||||||
|
|
||||||
|
## Visual Identity System
|
||||||
|
|
||||||
|
### Logo Design
|
||||||
|
- Primary logo
|
||||||
|
- Logo variations (horizontal, stacked, icon)
|
||||||
|
- Clear space requirements
|
||||||
|
- Minimum size specifications
|
||||||
|
- Incorrect usage examples
|
||||||
|
|
||||||
|
### Color Palette
|
||||||
|
- Primary colors (2-3)
|
||||||
|
- Secondary colors (3-5)
|
||||||
|
- Neutral colors
|
||||||
|
- Color meanings and usage
|
||||||
|
- Accessibility considerations
|
||||||
|
|
||||||
|
### Typography
|
||||||
|
- Primary typeface (headings)
|
||||||
|
- Secondary typeface (body)
|
||||||
|
- Type scale
|
||||||
|
- Font weights and styles
|
||||||
|
- Web fonts and fallbacks
|
||||||
|
|
||||||
|
### Imagery Style
|
||||||
|
- Photography guidelines
|
||||||
|
- Illustration style
|
||||||
|
- Iconography
|
||||||
|
- Graphic elements
|
||||||
|
- Image treatments
|
||||||
|
|
||||||
|
## Design System Architecture
|
||||||
|
|
||||||
|
### Component Hierarchy
|
||||||
|
1. Foundations (colors, typography, spacing)
|
||||||
|
2. Atoms (buttons, inputs, icons)
|
||||||
|
3. Molecules (form fields, cards)
|
||||||
|
4. Organisms (headers, footers, forms)
|
||||||
|
5. Templates (page layouts)
|
||||||
|
6. Pages (actual implementations)
|
||||||
|
|
||||||
|
### Design Tokens
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"color": {
|
||||||
|
"primary": "#0066CC",
|
||||||
|
"secondary": "#FF6B35"
|
||||||
|
},
|
||||||
|
"spacing": {
|
||||||
|
"xs": "4px",
|
||||||
|
"sm": "8px",
|
||||||
|
"md": "16px",
|
||||||
|
"lg": "24px",
|
||||||
|
"xl": "32px"
|
||||||
|
},
|
||||||
|
"typography": {
|
||||||
|
"fontFamily": {
|
||||||
|
"heading": "Inter",
|
||||||
|
"body": "Inter"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Component Library Structure
|
||||||
|
- Component documentation
|
||||||
|
- Usage guidelines
|
||||||
|
- Code examples
|
||||||
|
- Accessibility notes
|
||||||
|
- Design specs (Figma/Sketch)
|
||||||
|
|
||||||
|
## Brand Guidelines
|
||||||
|
|
||||||
|
### Voice and Tone
|
||||||
|
- Professional but approachable
|
||||||
|
- Clear and concise
|
||||||
|
- Empathetic and supportive
|
||||||
|
- Confident but humble
|
||||||
|
|
||||||
|
### Writing Style
|
||||||
|
- Active voice preferred
|
||||||
|
- Second person ("you")
|
||||||
|
- Contractions acceptable
|
||||||
|
- Industry jargon avoided
|
||||||
|
|
||||||
|
### Photography Guidelines
|
||||||
|
- Authentic, not stock-looking
|
||||||
|
- Diverse representation
|
||||||
|
- Natural lighting preferred
|
||||||
|
- Consistent editing style
|
||||||
|
|
||||||
|
### Social Media Guidelines
|
||||||
|
- Platform-specific adaptations
|
||||||
|
- Hashtag usage
|
||||||
|
- Emoji usage
|
||||||
|
- Response templates
|
||||||
|
|
||||||
|
## Implementation
|
||||||
|
|
||||||
|
### Brand Rollout
|
||||||
|
1. Internal launch (team training)
|
||||||
|
2. Digital assets (website, social)
|
||||||
|
3. Physical materials (business cards, signage)
|
||||||
|
4. Marketing campaigns
|
||||||
|
5. Brand monitoring and evolution
|
||||||
|
|
||||||
|
### Brand Governance
|
||||||
|
- Brand steward role
|
||||||
|
- Approval processes
|
||||||
|
- Usage audits
|
||||||
|
- Brand evolution strategy
|
||||||
|
- Trademark protection
|
||||||
|
|
||||||
|
## Measurement
|
||||||
|
|
||||||
|
- Brand awareness metrics
|
||||||
|
- Brand perception surveys
|
||||||
|
- Competitive positioning tracking
|
||||||
|
- Visual identity consistency scores
|
||||||
|
- Brand equity valuation
|
||||||
|
|
||||||
703
skills/ux-research/SKILL.md
Normal file
703
skills/ux-research/SKILL.md
Normal file
@@ -0,0 +1,703 @@
|
|||||||
|
# UX Research
|
||||||
|
|
||||||
|
**User research methodologies and insights synthesis**
|
||||||
|
|
||||||
|
# Research Methods Skill
|
||||||
|
|
||||||
|
**Comprehensive guide to UX research methodologies and when to use each method**
|
||||||
|
|
||||||
|
This skill codifies best practices from hundreds of successful UX research projects across discovery, validation, and optimization phases.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Core Principles
|
||||||
|
|
||||||
|
1. **Match Method to Question**: Choose research methods based on what you need to learn, not what's trendy
|
||||||
|
2. **Triangulate**: Use multiple methods to validate findings and reduce bias
|
||||||
|
3. **Include Users Early and Often**: Research throughout the product lifecycle, not just at the beginning
|
||||||
|
4. **Balance Qual and Quant**: Qualitative explores "why," quantitative measures "how much"
|
||||||
|
5. **Ethical Research Always**: Respect participant time, privacy, and dignity
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Research Method Selection Framework
|
||||||
|
|
||||||
|
### The 2x2 Framework: Attitudinal vs. Behavioral, Qualitative vs. Quantitative
|
||||||
|
|
||||||
|
```
|
||||||
|
QUALITATIVE QUANTITATIVE
|
||||||
|
(Why/How) (How many/much)
|
||||||
|
┌─────────────────────┬──────────────────────────┐
|
||||||
|
│ │ │
|
||||||
|
ATTITUDINAL │ • Interviews │ • Surveys │
|
||||||
|
(What people │ • Focus Groups │ • Card Sorting (quant) │
|
||||||
|
say) │ • Diary Studies │ • A/B Tests (attitudes) │
|
||||||
|
│ │ • Analytics (stated) │
|
||||||
|
├─────────────────────┼──────────────────────────┤
|
||||||
|
│ │ │
|
||||||
|
BEHAVIORAL │ • Usability Tests │ • Analytics │
|
||||||
|
(What people │ • Field Studies │ • A/B Tests │
|
||||||
|
do) │ • Contextual Inq. │ • Heatmaps/Click tracks │
|
||||||
|
│ • Task Analysis │ • Performance Metrics │
|
||||||
|
│ │ │
|
||||||
|
└─────────────────────┴──────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### When to Use Each Quadrant
|
||||||
|
|
||||||
|
**Attitudinal + Qualitative**: Understanding motivations, perceptions, mental models
|
||||||
|
- "Why do users prefer X over Y?"
|
||||||
|
- "What do users think about this concept?"
|
||||||
|
|
||||||
|
**Attitudinal + Quantitative**: Measuring opinions at scale
|
||||||
|
- "How satisfied are users with feature X?"
|
||||||
|
- "How many users would pay for premium tier?"
|
||||||
|
|
||||||
|
**Behavioral + Qualitative**: Understanding how users interact and why
|
||||||
|
- "How do users currently accomplish task X?"
|
||||||
|
- "What workarounds do users create?"
|
||||||
|
|
||||||
|
**Behavioral + Quantitative**: Measuring what users do at scale
|
||||||
|
- "What percentage of users complete onboarding?"
|
||||||
|
- "Which features are used most frequently?"
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Research Methods by Purpose
|
||||||
|
|
||||||
|
### 1. GENERATIVE RESEARCH (Discovery & Exploration)
|
||||||
|
|
||||||
|
**Goal**: Understand user needs, contexts, and problems before defining solutions
|
||||||
|
|
||||||
|
#### User Interviews
|
||||||
|
**Best for**: Deep understanding of motivations, attitudes, experiences
|
||||||
|
|
||||||
|
**When to use**:
|
||||||
|
- Beginning of project to understand problem space
|
||||||
|
- Exploring new market or user segment
|
||||||
|
- Understanding "why" behind behaviors
|
||||||
|
|
||||||
|
**Pros**:
|
||||||
|
- Rich, deep insights
|
||||||
|
- Flexibility to explore unexpected topics
|
||||||
|
- Can uncover unarticulated needs
|
||||||
|
|
||||||
|
**Cons**:
|
||||||
|
- Time-consuming (typically 45-90 min per interview)
|
||||||
|
- Small sample size (5-12 participants)
|
||||||
|
- Susceptible to social desirability bias
|
||||||
|
|
||||||
|
**Sample size**: 5-12 participants per user segment
|
||||||
|
|
||||||
|
**Typical questions**:
|
||||||
|
- "Tell me about the last time you..."
|
||||||
|
- "Walk me through how you..."
|
||||||
|
- "What's most important to you when..."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Contextual Inquiry / Field Studies
|
||||||
|
**Best for**: Observing users in their natural environment
|
||||||
|
|
||||||
|
**When to use**:
|
||||||
|
- Understanding workflow in complex environments
|
||||||
|
- Observing actual behavior (not self-reported)
|
||||||
|
- Discovering workarounds and adaptations
|
||||||
|
|
||||||
|
**Pros**:
|
||||||
|
- Observe real behavior in context
|
||||||
|
- See environmental factors affecting use
|
||||||
|
- Discover unarticulated needs
|
||||||
|
|
||||||
|
**Cons**:
|
||||||
|
- Very time-intensive
|
||||||
|
- Logistically complex (travel, access)
|
||||||
|
- Can be intrusive to participants
|
||||||
|
|
||||||
|
**Sample size**: 4-8 site visits
|
||||||
|
|
||||||
|
**Process**:
|
||||||
|
1. Shadow user in their environment
|
||||||
|
2. Observe tasks and workflows
|
||||||
|
3. Ask questions about what you observe
|
||||||
|
4. Document context (photos, notes)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Diary Studies
|
||||||
|
**Best for**: Understanding behaviors and experiences over time
|
||||||
|
|
||||||
|
**When to use**:
|
||||||
|
- Behaviors that occur sporadically
|
||||||
|
- Understanding context of use over time
|
||||||
|
- Capturing in-the-moment experiences
|
||||||
|
|
||||||
|
**Pros**:
|
||||||
|
- Captures real-time experiences (less recall bias)
|
||||||
|
- Shows patterns over time
|
||||||
|
- Less researcher time than shadowing
|
||||||
|
|
||||||
|
**Cons**:
|
||||||
|
- Participant burden (compliance issues)
|
||||||
|
- Self-reported data
|
||||||
|
- Can take weeks to complete
|
||||||
|
|
||||||
|
**Sample size**: 10-20 participants over 1-4 weeks
|
||||||
|
|
||||||
|
**Tools**: Mobile apps (dscout, Indeemo), photo journals, SMS surveys
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Surveys (Exploratory)
|
||||||
|
**Best for**: Identifying patterns and priorities across large populations
|
||||||
|
|
||||||
|
**When to use**:
|
||||||
|
- Need to understand frequency of behaviors
|
||||||
|
- Want to segment users
|
||||||
|
- Validate interview findings at scale
|
||||||
|
|
||||||
|
**Pros**:
|
||||||
|
- Large sample sizes
|
||||||
|
- Statistically significant results
|
||||||
|
- Cost-effective per response
|
||||||
|
|
||||||
|
**Cons**:
|
||||||
|
- Can't explore "why" deeply
|
||||||
|
- Response bias
|
||||||
|
- No opportunity to clarify answers
|
||||||
|
|
||||||
|
**Sample size**: Minimum 100 for basic analysis, 300+ for segmentation
|
||||||
|
|
||||||
|
**Question types**:
|
||||||
|
- Multiple choice for quantification
|
||||||
|
- Likert scales for attitudes
|
||||||
|
- Open-ended for unexpected insights (limited)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2. EVALUATIVE RESEARCH (Testing & Validation)
|
||||||
|
|
||||||
|
**Goal**: Test designs, concepts, or products to identify issues and validate solutions
|
||||||
|
|
||||||
|
#### Usability Testing (Moderated)
|
||||||
|
**Best for**: Identifying usability issues and understanding user behavior with product
|
||||||
|
|
||||||
|
**When to use**:
|
||||||
|
- Testing prototypes or live products
|
||||||
|
- Evaluating specific flows or features
|
||||||
|
- Before major product launches
|
||||||
|
|
||||||
|
**Pros**:
|
||||||
|
- Identifies specific usability issues
|
||||||
|
- Can probe to understand "why"
|
||||||
|
- Flexible to explore unexpected findings
|
||||||
|
|
||||||
|
**Cons**:
|
||||||
|
- Artificial environment (not real context)
|
||||||
|
- Moderator bias possible
|
||||||
|
- Time-consuming
|
||||||
|
|
||||||
|
**Sample size**: 5 users per user segment (finds ~85% of issues per Nielsen)
|
||||||
|
|
||||||
|
**Process**:
|
||||||
|
1. Give user realistic task scenarios
|
||||||
|
2. Ask them to think aloud
|
||||||
|
3. Observe struggles and successes
|
||||||
|
4. Measure time, errors, completion
|
||||||
|
|
||||||
|
**Metrics**:
|
||||||
|
- Task completion rate
|
||||||
|
- Time on task
|
||||||
|
- Error rate
|
||||||
|
- Satisfaction ratings (post-task)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Usability Testing (Unmoderated Remote)
|
||||||
|
**Best for**: Quick feedback on specific tasks at scale
|
||||||
|
|
||||||
|
**When to use**:
|
||||||
|
- Need results quickly
|
||||||
|
- Testing simple, linear flows
|
||||||
|
- Want larger sample size
|
||||||
|
|
||||||
|
**Pros**:
|
||||||
|
- Fast turnaround (hours, not weeks)
|
||||||
|
- Larger sample sizes
|
||||||
|
- Lower cost per participant
|
||||||
|
|
||||||
|
**Cons**:
|
||||||
|
- Can't ask follow-up questions
|
||||||
|
- Limited to simple tasks
|
||||||
|
- No way to clarify misunderstandings
|
||||||
|
|
||||||
|
**Sample size**: 15-30 participants
|
||||||
|
|
||||||
|
**Tools**: UserTesting, Maze, UserZoom
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### A/B Testing
|
||||||
|
**Best for**: Comparing two design alternatives with real users
|
||||||
|
|
||||||
|
**When to use**:
|
||||||
|
- Have two viable design options
|
||||||
|
- Need to measure impact on key metrics
|
||||||
|
- Have sufficient traffic for significance
|
||||||
|
|
||||||
|
**Pros**:
|
||||||
|
- Measures real behavior (not stated preferences)
|
||||||
|
- Statistically significant results
|
||||||
|
- Removes opinion-based decisions
|
||||||
|
|
||||||
|
**Cons**:
|
||||||
|
- Requires traffic volume
|
||||||
|
- Can only test one variable at a time
|
||||||
|
- Doesn't explain "why" variant won
|
||||||
|
|
||||||
|
**Sample size**: Depends on baseline conversion and desired lift (use calculator)
|
||||||
|
|
||||||
|
**Metrics**: Conversion rate, click-through rate, time on page, revenue
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Concept Testing
|
||||||
|
**Best for**: Validating ideas before building them
|
||||||
|
|
||||||
|
**When to use**:
|
||||||
|
- Early stage, before detailed design
|
||||||
|
- Choosing between multiple concepts
|
||||||
|
- Validating value proposition
|
||||||
|
|
||||||
|
**Pros**:
|
||||||
|
- Fail fast and cheap
|
||||||
|
- Can test multiple concepts
|
||||||
|
- Provides direction for design
|
||||||
|
|
||||||
|
**Cons**:
|
||||||
|
- Reactions to concept ≠ actual usage
|
||||||
|
- Risk of overvaluing stated intent
|
||||||
|
- Hard to imagine new paradigms
|
||||||
|
|
||||||
|
**Sample size**: 8-15 for qualitative, 100+ for quantitative
|
||||||
|
|
||||||
|
**Methods**: Show concept (sketches, storyboards, mockups), gather reactions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Card Sorting
|
||||||
|
**Best for**: Testing or creating information architecture
|
||||||
|
|
||||||
|
**When to use**:
|
||||||
|
- Designing navigation structure
|
||||||
|
- Organizing content or features
|
||||||
|
- Understanding mental models of categorization
|
||||||
|
|
||||||
|
**Types**:
|
||||||
|
- **Open**: Users create and name categories
|
||||||
|
- **Closed**: Users sort into predefined categories
|
||||||
|
- **Hybrid**: Mix of both
|
||||||
|
|
||||||
|
**Pros**:
|
||||||
|
- User-centered IA
|
||||||
|
- Quantifiable results
|
||||||
|
- Easy to conduct remotely
|
||||||
|
|
||||||
|
**Cons**:
|
||||||
|
- Decontextualized from real use
|
||||||
|
- Only tests grouping, not findability
|
||||||
|
- Assumes users know all items
|
||||||
|
|
||||||
|
**Sample size**: 15-30 for open, 30+ for closed
|
||||||
|
|
||||||
|
**Tools**: Optimal Workshop, Maze, UserZoom
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Tree Testing
|
||||||
|
**Best for**: Validating navigation structure
|
||||||
|
|
||||||
|
**When to use**:
|
||||||
|
- After creating IA (validates card sorting)
|
||||||
|
- Testing if users can find content
|
||||||
|
- Before visual design
|
||||||
|
|
||||||
|
**Pros**:
|
||||||
|
- Tests findability directly
|
||||||
|
- Quantifiable results
|
||||||
|
- Fast and cost-effective
|
||||||
|
|
||||||
|
**Cons**:
|
||||||
|
- No visual design context
|
||||||
|
- Text-only (misses visual cues)
|
||||||
|
- Limited to tree structures
|
||||||
|
|
||||||
|
**Sample size**: 50-100 participants
|
||||||
|
|
||||||
|
**Metrics**: Success rate, directness, time
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3. ANALYTICS & BEHAVIORAL DATA
|
||||||
|
|
||||||
|
#### Web/Product Analytics
|
||||||
|
**Best for**: Understanding actual user behavior at scale
|
||||||
|
|
||||||
|
**When to use**:
|
||||||
|
- Identifying where users drop off
|
||||||
|
- Measuring feature adoption
|
||||||
|
- Tracking key metrics over time
|
||||||
|
- Generating hypotheses for research
|
||||||
|
|
||||||
|
**Pros**:
|
||||||
|
- Real behavior, not self-reported
|
||||||
|
- Large sample sizes
|
||||||
|
- Continuous monitoring
|
||||||
|
|
||||||
|
**Cons**:
|
||||||
|
- Doesn't explain "why"
|
||||||
|
- Privacy concerns
|
||||||
|
- Can be misinterpreted without context
|
||||||
|
|
||||||
|
**Key Metrics**:
|
||||||
|
- Acquisition: Where users come from
|
||||||
|
- Activation: Do they complete onboarding?
|
||||||
|
- Engagement: How often do they return?
|
||||||
|
- Retention: Do they stick around?
|
||||||
|
- Revenue: Do they pay?
|
||||||
|
|
||||||
|
**Tools**: Google Analytics, Mixpanel, Amplitude, Heap
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Heatmaps & Session Recordings
|
||||||
|
**Best for**: Visualizing where users click, scroll, and focus attention
|
||||||
|
|
||||||
|
**When to use**:
|
||||||
|
- Optimizing page layouts
|
||||||
|
- Understanding confusion points
|
||||||
|
- Identifying ignored content
|
||||||
|
|
||||||
|
**Pros**:
|
||||||
|
- Visual and intuitive
|
||||||
|
- Shows aggregate patterns
|
||||||
|
- Can identify rage clicks (frustration)
|
||||||
|
|
||||||
|
**Cons**:
|
||||||
|
- Descriptive, not explanatory
|
||||||
|
- Can be over-interpreted
|
||||||
|
- Privacy concerns
|
||||||
|
|
||||||
|
**Tools**: Hotjar, Crazy Egg, FullStory
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 4. SPECIALIZED METHODS
|
||||||
|
|
||||||
|
#### Accessibility Testing
|
||||||
|
**Best for**: Ensuring product works for users with disabilities
|
||||||
|
|
||||||
|
**When to use**:
|
||||||
|
- Required for compliance (WCAG, ADA)
|
||||||
|
- Serving diverse user base
|
||||||
|
- Ethical product development
|
||||||
|
|
||||||
|
**Methods**:
|
||||||
|
- Automated testing (axe, WAVE, Lighthouse)
|
||||||
|
- Manual testing with assistive tech
|
||||||
|
- User testing with people with disabilities
|
||||||
|
|
||||||
|
**Sample size**: 3-5 users per disability type
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Competitive Analysis
|
||||||
|
**Best for**: Understanding market landscape and best practices
|
||||||
|
|
||||||
|
**When to use**:
|
||||||
|
- Entering new market
|
||||||
|
- Benchmarking against competitors
|
||||||
|
- Identifying feature gaps
|
||||||
|
|
||||||
|
**Process**:
|
||||||
|
1. Identify competitors
|
||||||
|
2. Analyze key features, flows, pricing
|
||||||
|
3. Conduct comparative usability testing
|
||||||
|
4. Document strengths and weaknesses
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
#### Heuristic Evaluation
|
||||||
|
**Best for**: Expert review against usability principles
|
||||||
|
|
||||||
|
**When to use**:
|
||||||
|
- Quick assessment without users
|
||||||
|
- Budget/time constraints
|
||||||
|
- Before user testing to fix obvious issues
|
||||||
|
|
||||||
|
**Heuristics** (Nielsen's 10):
|
||||||
|
1. Visibility of system status
|
||||||
|
2. Match between system and real world
|
||||||
|
3. User control and freedom
|
||||||
|
4. Consistency and standards
|
||||||
|
5. Error prevention
|
||||||
|
6. Recognition rather than recall
|
||||||
|
7. Flexibility and efficiency of use
|
||||||
|
8. Aesthetic and minimalist design
|
||||||
|
9. Help users recognize, diagnose, and recover from errors
|
||||||
|
10. Help and documentation
|
||||||
|
|
||||||
|
**Evaluators**: 3-5 UX experts
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Research Method Selection Guide
|
||||||
|
|
||||||
|
### By Project Stage
|
||||||
|
|
||||||
|
**Discovery / Problem Definition**:
|
||||||
|
- User interviews
|
||||||
|
- Field studies / Contextual inquiry
|
||||||
|
- Diary studies
|
||||||
|
- Surveys (exploratory)
|
||||||
|
- Competitive analysis
|
||||||
|
|
||||||
|
**Ideation / Concept Validation**:
|
||||||
|
- Concept testing
|
||||||
|
- Participatory design workshops
|
||||||
|
- Card sorting (for IA)
|
||||||
|
- Surveys (concept preference)
|
||||||
|
|
||||||
|
**Design / Prototype Testing**:
|
||||||
|
- Usability testing (moderated)
|
||||||
|
- Tree testing
|
||||||
|
- First-click testing
|
||||||
|
- Heuristic evaluation
|
||||||
|
|
||||||
|
**Pre-Launch Validation**:
|
||||||
|
- Usability testing (unmoderated)
|
||||||
|
- Accessibility testing
|
||||||
|
- Beta testing
|
||||||
|
- A/B testing (if redesign)
|
||||||
|
|
||||||
|
**Post-Launch Optimization**:
|
||||||
|
- Analytics
|
||||||
|
- A/B testing
|
||||||
|
- Surveys (satisfaction)
|
||||||
|
- Session recordings
|
||||||
|
- Ongoing usability testing
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### By Research Question Type
|
||||||
|
|
||||||
|
**"What do users need?"**
|
||||||
|
→ Interviews, field studies, diary studies
|
||||||
|
|
||||||
|
**"Will users understand this concept?"**
|
||||||
|
→ Concept testing, first-click tests
|
||||||
|
|
||||||
|
**"Can users complete this task?"**
|
||||||
|
→ Usability testing, task analysis
|
||||||
|
|
||||||
|
**"How many users experience this?"**
|
||||||
|
→ Surveys, analytics
|
||||||
|
|
||||||
|
**"Which design performs better?"**
|
||||||
|
→ A/B testing, preference testing
|
||||||
|
|
||||||
|
**"How satisfied are users?"**
|
||||||
|
→ Surveys (NPS, CSAT, SUS), interviews
|
||||||
|
|
||||||
|
**"How do we organize content?"**
|
||||||
|
→ Card sorting, tree testing
|
||||||
|
|
||||||
|
**"Is this accessible?"**
|
||||||
|
→ Accessibility testing, assistive tech testing
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Sample Size Guidelines
|
||||||
|
|
||||||
|
### Qualitative Research
|
||||||
|
|
||||||
|
**Interviews / Usability Tests**: 5-8 per user segment
|
||||||
|
- Diminishing returns after 5 (per Nielsen)
|
||||||
|
- If multiple distinct segments, 5 per segment
|
||||||
|
- For very simple products: 3-5 total
|
||||||
|
- For complex products: 8-12 total
|
||||||
|
|
||||||
|
**Field Studies**: 4-8 site visits
|
||||||
|
- Very time-intensive
|
||||||
|
- Smaller sample acceptable
|
||||||
|
|
||||||
|
**Diary Studies**: 10-20 participants
|
||||||
|
- Higher dropout rate
|
||||||
|
- Need larger initial sample
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Quantitative Research
|
||||||
|
|
||||||
|
**Surveys**:
|
||||||
|
- Exploratory: 100+ for basic insights
|
||||||
|
- Segmentation analysis: 300+
|
||||||
|
- Statistical modeling: 1000+
|
||||||
|
|
||||||
|
**A/B Tests**:
|
||||||
|
- Depends on baseline conversion rate and desired lift
|
||||||
|
- Typically need thousands of users per variant
|
||||||
|
- Use online calculator for specific estimates
|
||||||
|
|
||||||
|
**Card Sorting**:
|
||||||
|
- Open: 15-30
|
||||||
|
- Closed: 30-50
|
||||||
|
|
||||||
|
**Tree Testing**: 50-100
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Mixed Methods Approach
|
||||||
|
|
||||||
|
**Best practice**: Combine qualitative and quantitative for robust insights
|
||||||
|
|
||||||
|
### Example: Redesigning Checkout Flow
|
||||||
|
|
||||||
|
1. **Discover** (Qual): Interview 8 users about current checkout experience
|
||||||
|
- Identify pain points and needs
|
||||||
|
|
||||||
|
2. **Validate** (Quant): Survey 300 users on identified pain points
|
||||||
|
- Quantify how many experience each issue
|
||||||
|
|
||||||
|
3. **Test** (Qual): Usability test new design with 6 users
|
||||||
|
- Identify usability issues
|
||||||
|
|
||||||
|
4. **Measure** (Quant): A/B test new design with live traffic
|
||||||
|
- Measure impact on conversion
|
||||||
|
|
||||||
|
5. **Understand** (Qual): Interview users who abandoned new checkout
|
||||||
|
- Understand why some still fail
|
||||||
|
|
||||||
|
This creates a complete picture: qualitative explains, quantitative measures.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Common Research Mistakes to Avoid
|
||||||
|
|
||||||
|
### 1. Confirmation Bias
|
||||||
|
❌ **Mistake**: Only asking questions that support your hypothesis
|
||||||
|
✅ **Fix**: Include questions that could disprove your assumptions
|
||||||
|
|
||||||
|
### 2. Leading Questions
|
||||||
|
❌ **Mistake**: "Don't you think this design is confusing?"
|
||||||
|
✅ **Fix**: "What are your thoughts on this design?"
|
||||||
|
|
||||||
|
### 3. Hypothetical Questions
|
||||||
|
❌ **Mistake**: "Would you use this feature?"
|
||||||
|
✅ **Fix**: "Tell me about the last time you needed to [accomplish task]"
|
||||||
|
|
||||||
|
### 4. Treating Insights as Data
|
||||||
|
❌ **Mistake**: "5 users said X, so everyone must think X"
|
||||||
|
✅ **Fix**: "5/5 users experienced X (small sample, directional insight)"
|
||||||
|
|
||||||
|
### 5. Testing Too Late
|
||||||
|
❌ **Mistake**: Only testing after full build
|
||||||
|
✅ **Fix**: Test early with low-fidelity prototypes
|
||||||
|
|
||||||
|
### 6. Ignoring Negative Findings
|
||||||
|
❌ **Mistake**: Cherry-picking data that supports your design
|
||||||
|
✅ **Fix**: Report all findings, especially contradictory ones
|
||||||
|
|
||||||
|
### 7. Over-Researching
|
||||||
|
❌ **Mistake**: Endless research without action
|
||||||
|
✅ **Fix**: Define decision criteria upfront, research only to inform decision
|
||||||
|
|
||||||
|
### 8. Research Without Clear Objectives
|
||||||
|
❌ **Mistake**: "Let's do some user interviews and see what we find"
|
||||||
|
✅ **Fix**: "We need to understand [specific question] to decide [specific decision]"
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Ethical Research Guidelines
|
||||||
|
|
||||||
|
### Informed Consent
|
||||||
|
- [ ] Explain purpose of research clearly
|
||||||
|
- [ ] Explain how data will be used
|
||||||
|
- [ ] Explain recording and privacy practices
|
||||||
|
- [ ] Allow participant to opt out at any time
|
||||||
|
- [ ] Obtain explicit consent before proceeding
|
||||||
|
|
||||||
|
### Privacy and Confidentiality
|
||||||
|
- [ ] Anonymize participant data
|
||||||
|
- [ ] Secure storage of recordings and notes
|
||||||
|
- [ ] Delete personal information after analysis
|
||||||
|
- [ ] Don't share recordings outside research team
|
||||||
|
- [ ] Follow GDPR/privacy regulations
|
||||||
|
|
||||||
|
### Respectful Treatment
|
||||||
|
- [ ] Compensate participants fairly for time
|
||||||
|
- [ ] Don't make participants feel judged
|
||||||
|
- [ ] Accommodate accessibility needs
|
||||||
|
- [ ] Allow breaks and adjust pace
|
||||||
|
- [ ] Thank participants sincerely
|
||||||
|
|
||||||
|
### Vulnerable Populations
|
||||||
|
- [ ] Extra care with children, elderly, disabled
|
||||||
|
- [ ] May require guardian consent
|
||||||
|
- [ ] Trauma-informed approach for sensitive topics
|
||||||
|
- [ ] Have resources ready if distress occurs
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Research Planning Checklist
|
||||||
|
|
||||||
|
**Before Research**:
|
||||||
|
- [ ] Clear research questions defined
|
||||||
|
- [ ] Method(s) selected and justified
|
||||||
|
- [ ] Participant criteria specified
|
||||||
|
- [ ] Recruitment plan in place
|
||||||
|
- [ ] Materials prepared (guides, prototypes)
|
||||||
|
- [ ] Consent forms ready
|
||||||
|
- [ ] Recording setup tested
|
||||||
|
- [ ] Pilot test conducted
|
||||||
|
|
||||||
|
**During Research**:
|
||||||
|
- [ ] Follow protocol consistently
|
||||||
|
- [ ] Take detailed notes
|
||||||
|
- [ ] Record sessions (with consent)
|
||||||
|
- [ ] Note unexpected findings
|
||||||
|
- [ ] Debrief after each session
|
||||||
|
- [ ] Adjust if critical issues found
|
||||||
|
|
||||||
|
**After Research**:
|
||||||
|
- [ ] Analyze data systematically
|
||||||
|
- [ ] Identify patterns and themes
|
||||||
|
- [ ] Create actionable insights
|
||||||
|
- [ ] Prioritize recommendations
|
||||||
|
- [ ] Share findings with stakeholders
|
||||||
|
- [ ] Track implementation of recommendations
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Quick Reference: Method Selection Matrix
|
||||||
|
|
||||||
|
| If you need to... | Use this method |
|
||||||
|
|-------------------|----------------|
|
||||||
|
| Understand user needs before designing | Interviews, Field Studies |
|
||||||
|
| Test if users can complete a task | Usability Testing |
|
||||||
|
| Choose between two designs | A/B Testing, Preference Testing |
|
||||||
|
| Organize content/features | Card Sorting |
|
||||||
|
| Validate navigation structure | Tree Testing |
|
||||||
|
| Measure satisfaction | Surveys (SUS, NPS, CSAT) |
|
||||||
|
| Understand "why" behind analytics | Interviews, Session Recordings |
|
||||||
|
| Validate a new concept | Concept Testing |
|
||||||
|
| Track behavior over time | Diary Studies, Analytics |
|
||||||
|
| Quick feedback on prototype | Unmoderated Usability Testing |
|
||||||
|
| Understand expert perspective | Heuristic Evaluation |
|
||||||
|
| Ensure accessibility | Accessibility Testing |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Version**: 1.0
|
||||||
|
**Last Updated**: January 2025
|
||||||
|
**Success Rate**: Based on industry best practices and research literature
|
||||||
756
skills/ux-writing/SKILL.md
Normal file
756
skills/ux-writing/SKILL.md
Normal file
@@ -0,0 +1,756 @@
|
|||||||
|
# UX Writing Skill
|
||||||
|
|
||||||
|
Expert patterns and best practices for creating effective interface copy, error messages, onboarding flows, and accessible content.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
1. [Core Principles](#core-principles)
|
||||||
|
2. [Microcopy Patterns](#microcopy-patterns)
|
||||||
|
3. [Error Messages](#error-messages)
|
||||||
|
4. [Onboarding](#onboarding)
|
||||||
|
5. [Accessibility](#accessibility)
|
||||||
|
6. [Voice & Tone](#voice--tone)
|
||||||
|
7. [Content Patterns](#content-patterns)
|
||||||
|
|
||||||
|
## Core Principles
|
||||||
|
|
||||||
|
### Clarity Over Cleverness
|
||||||
|
**Priority**: Users must understand immediately, without thinking.
|
||||||
|
|
||||||
|
```
|
||||||
|
❌ "Oopsie daisy! Something went sideways."
|
||||||
|
✅ "We couldn't save your changes. Check your connection and try again."
|
||||||
|
```
|
||||||
|
|
||||||
|
**Rules**:
|
||||||
|
- Use simple, common words (8th-grade reading level)
|
||||||
|
- One idea per sentence
|
||||||
|
- Active voice over passive
|
||||||
|
- Specific over vague
|
||||||
|
- Front-load important information
|
||||||
|
|
||||||
|
### Brevity Without Loss
|
||||||
|
**Every word must earn its place.**
|
||||||
|
|
||||||
|
```
|
||||||
|
❌ "In order to proceed with the creation of your account, you'll need to provide us with your email address."
|
||||||
|
✅ "Enter your email to create your account."
|
||||||
|
```
|
||||||
|
|
||||||
|
**Techniques**:
|
||||||
|
- Remove filler words: "in order to" → "to", "utilize" → "use"
|
||||||
|
- Delete redundancy: "advance planning" → "planning"
|
||||||
|
- Use contractions when friendly: "You'll" not "You will"
|
||||||
|
- Cut adverbs: "very important" → "critical"
|
||||||
|
|
||||||
|
### User-Centered Language
|
||||||
|
**Write from the user's perspective, not the system's.**
|
||||||
|
|
||||||
|
```
|
||||||
|
System perspective (❌): "The system requires authentication"
|
||||||
|
User perspective (✅): "Sign in to continue"
|
||||||
|
|
||||||
|
System perspective (❌): "Invalid credentials provided"
|
||||||
|
User perspective (✅): "We don't recognize that email and password combination"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Patterns**:
|
||||||
|
- Use "you/your" (not "the user")
|
||||||
|
- Focus on user goals, not system processes
|
||||||
|
- Explain benefits, not features
|
||||||
|
- Match user's mental model and vocabulary
|
||||||
|
|
||||||
|
### Consistency
|
||||||
|
**Same action = same label everywhere**
|
||||||
|
|
||||||
|
If you call it "Delete" in one place, don't call it "Remove" elsewhere (unless they're different actions).
|
||||||
|
|
||||||
|
**Consistency applies to**:
|
||||||
|
- Terminology (pick one word per concept)
|
||||||
|
- Capitalization (title case vs sentence case)
|
||||||
|
- Punctuation (periods in tooltips?)
|
||||||
|
- Tone (formal vs casual)
|
||||||
|
- Button patterns (verb-first)
|
||||||
|
|
||||||
|
## Microcopy Patterns
|
||||||
|
|
||||||
|
### Button Labels
|
||||||
|
|
||||||
|
**Rules**:
|
||||||
|
1. Start with verb (action word)
|
||||||
|
2. Be specific (what will happen)
|
||||||
|
3. Avoid generic labels when possible
|
||||||
|
4. Match button style to action
|
||||||
|
|
||||||
|
```
|
||||||
|
Primary buttons (main action):
|
||||||
|
✅ "Create account"
|
||||||
|
✅ "Save changes"
|
||||||
|
✅ "Continue to payment"
|
||||||
|
❌ "Submit"
|
||||||
|
❌ "OK"
|
||||||
|
|
||||||
|
Secondary buttons (alternate path):
|
||||||
|
✅ "Cancel"
|
||||||
|
✅ "Go back"
|
||||||
|
✅ "Skip for now"
|
||||||
|
|
||||||
|
Destructive buttons (dangerous):
|
||||||
|
✅ "Delete project"
|
||||||
|
✅ "Remove card"
|
||||||
|
✅ "Permanently delete"
|
||||||
|
❌ "Delete" (not specific enough)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Loading states**:
|
||||||
|
```
|
||||||
|
❌ "Loading..."
|
||||||
|
✅ "Saving..." / "Creating account..." / "Processing payment..."
|
||||||
|
```
|
||||||
|
|
||||||
|
### Form Labels
|
||||||
|
|
||||||
|
**Best practices**:
|
||||||
|
- Use nouns or questions
|
||||||
|
- Place above field (not beside)
|
||||||
|
- Mark required/optional clearly
|
||||||
|
- Include helpful context
|
||||||
|
|
||||||
|
```
|
||||||
|
❌ "Name:" (colon unnecessary)
|
||||||
|
✅ "Full name"
|
||||||
|
|
||||||
|
❌ "Email *" (asterisk meaning unclear)
|
||||||
|
✅ "Email address (required)"
|
||||||
|
✅ "Phone number (optional)"
|
||||||
|
|
||||||
|
Question format (more conversational):
|
||||||
|
✅ "What's your email address?"
|
||||||
|
✅ "How should we contact you?"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Placeholders
|
||||||
|
|
||||||
|
**Use for examples, not instructions**
|
||||||
|
|
||||||
|
```
|
||||||
|
❌ "Enter your email address" (That's what the label is for)
|
||||||
|
✅ "name@company.com"
|
||||||
|
|
||||||
|
❌ "YYYY-MM-DD" (too cryptic)
|
||||||
|
✅ "2024-01-15"
|
||||||
|
|
||||||
|
Good placeholders:
|
||||||
|
- Phone: "(555) 123-4567"
|
||||||
|
- URL: "https://example.com"
|
||||||
|
- Search: "Search products, orders, or customers"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Warning**: Don't rely on placeholders alone—they disappear on input and fail accessibility.
|
||||||
|
|
||||||
|
### Tooltips
|
||||||
|
|
||||||
|
**When to use**:
|
||||||
|
- Add context (not repeat visible label)
|
||||||
|
- Explain consequences
|
||||||
|
- Show keyboard shortcuts
|
||||||
|
- Clarify unfamiliar terms
|
||||||
|
|
||||||
|
```
|
||||||
|
Visible label: "Auto-save"
|
||||||
|
Tooltip: "Changes save automatically every 30 seconds"
|
||||||
|
|
||||||
|
Visible label: "Private"
|
||||||
|
Tooltip: "Only you and people you invite can see this"
|
||||||
|
|
||||||
|
Icon button: [Heart icon]
|
||||||
|
Tooltip: "Add to favorites (⌘D)"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Rules**:
|
||||||
|
- 1-2 sentences maximum
|
||||||
|
- Don't repeat the visible label
|
||||||
|
- Include keyboard shortcut if applicable
|
||||||
|
- Make dismissible/hoverable
|
||||||
|
- Don't put critical info in tooltips (many users won't see them)
|
||||||
|
|
||||||
|
### Empty States
|
||||||
|
|
||||||
|
**Framework**: Explain + Encourage + Action
|
||||||
|
|
||||||
|
```
|
||||||
|
Structure:
|
||||||
|
1. Headline: What's missing (positive frame)
|
||||||
|
2. Explanation: Why it matters / what goes here
|
||||||
|
3. Primary action: Fill this state
|
||||||
|
4. Secondary: Alternative or help
|
||||||
|
|
||||||
|
Example:
|
||||||
|
[Illustration]
|
||||||
|
"No projects yet"
|
||||||
|
"Projects help you organize tasks and collaborate with your team."
|
||||||
|
[Create your first project]
|
||||||
|
[Learn about projects]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Tone**: Encouraging, never condescending
|
||||||
|
```
|
||||||
|
❌ "Nothing to see here"
|
||||||
|
❌ "This page is empty"
|
||||||
|
✅ "You haven't saved any items yet"
|
||||||
|
✅ "Your notifications will appear here"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Notifications & Toasts
|
||||||
|
|
||||||
|
**Types**:
|
||||||
|
1. **Success**: Confirm action completed
|
||||||
|
2. **Info**: Helpful information
|
||||||
|
3. **Warning**: Something needs attention
|
||||||
|
4. **Error**: Action failed
|
||||||
|
|
||||||
|
```
|
||||||
|
Success (brief confirmation):
|
||||||
|
✅ "Project created"
|
||||||
|
✅ "Changes saved"
|
||||||
|
✅ "File uploaded"
|
||||||
|
|
||||||
|
Info (useful context):
|
||||||
|
✅ "New features are available. Refresh to see them."
|
||||||
|
✅ "You have 3 unsaved drafts"
|
||||||
|
|
||||||
|
Warning (needs action soon):
|
||||||
|
✅ "Your trial ends in 3 days. Upgrade to keep access."
|
||||||
|
✅ "You're viewing an old version of this file"
|
||||||
|
|
||||||
|
Error (action failed):
|
||||||
|
✅ "Couldn't upload file. Check your connection and try again."
|
||||||
|
```
|
||||||
|
|
||||||
|
**Rules**:
|
||||||
|
- Be concise (read in 2-3 seconds)
|
||||||
|
- Include an action when possible
|
||||||
|
- Use appropriate icon/color
|
||||||
|
- Don't auto-dismiss errors
|
||||||
|
- Limit frequency (max 1-2 toasts at once)
|
||||||
|
|
||||||
|
## Error Messages
|
||||||
|
|
||||||
|
### The 3-Part Formula
|
||||||
|
Every error message answers:
|
||||||
|
1. **What happened?** (The problem)
|
||||||
|
2. **Why?** (Reason - when helpful)
|
||||||
|
3. **How to fix?** (Solution)
|
||||||
|
|
||||||
|
```
|
||||||
|
Example:
|
||||||
|
"We couldn't save your document [what]. You're offline [why]. Your work is saved locally—reconnect to sync [how to fix]."
|
||||||
|
```
|
||||||
|
|
||||||
|
### Error Types
|
||||||
|
|
||||||
|
#### Validation Errors (User input issues)
|
||||||
|
```
|
||||||
|
❌ "Invalid email"
|
||||||
|
✅ "Please enter a valid email address (e.g., name@company.com)"
|
||||||
|
|
||||||
|
❌ "Password requirements not met"
|
||||||
|
✅ "Your password must be at least 8 characters with 1 number and 1 special character"
|
||||||
|
|
||||||
|
❌ "Field cannot be empty"
|
||||||
|
✅ "We need your phone number to send order updates"
|
||||||
|
```
|
||||||
|
|
||||||
|
#### System Errors (Technical failures)
|
||||||
|
```
|
||||||
|
❌ "Error 500: Internal server error"
|
||||||
|
✅ "Something went wrong on our end. We've been notified and are fixing it. Please try again in a few minutes."
|
||||||
|
|
||||||
|
❌ "Request timed out"
|
||||||
|
✅ "This is taking longer than expected. Your work is saved—try refreshing the page or come back in a few minutes."
|
||||||
|
|
||||||
|
❌ "Database connection failed"
|
||||||
|
✅ "We're having trouble connecting to our servers. Your data is safe. Please try again in a moment."
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Permission Errors (Access issues)
|
||||||
|
```
|
||||||
|
❌ "403 Forbidden"
|
||||||
|
✅ "You don't have permission to edit this project. Contact the project owner to request access."
|
||||||
|
|
||||||
|
❌ "Unauthorized"
|
||||||
|
✅ "Your session has expired. Please sign in again to continue."
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Not Found Errors
|
||||||
|
```
|
||||||
|
❌ "404 Not Found"
|
||||||
|
✅ "We can't find that page. It may have been moved or deleted. [Return to dashboard] or [Search for what you need]"
|
||||||
|
|
||||||
|
❌ "No results"
|
||||||
|
✅ "No results for 'project alpha'. Try a different search term or create a new project."
|
||||||
|
```
|
||||||
|
|
||||||
|
### Tone by Severity
|
||||||
|
|
||||||
|
**Minor errors** (user mistakes, validation):
|
||||||
|
- Friendly and helpful
|
||||||
|
- Light tone acceptable
|
||||||
|
- Focus on easy fix
|
||||||
|
|
||||||
|
```
|
||||||
|
"Oops! Your password needs at least one number. Almost there!"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Moderate errors** (not found, permissions):
|
||||||
|
- Professional and clear
|
||||||
|
- Respectful tone
|
||||||
|
- Provide alternatives
|
||||||
|
|
||||||
|
```
|
||||||
|
"This file isn't available. It may have been deleted. Check your recent files or search for it."
|
||||||
|
```
|
||||||
|
|
||||||
|
**Critical errors** (system failures, data at risk):
|
||||||
|
- Calm and reassuring
|
||||||
|
- Transparent but not technical
|
||||||
|
- Emphasize safety
|
||||||
|
|
||||||
|
```
|
||||||
|
"We encountered a technical issue and couldn't process your payment. Your card has not been charged. We've been notified and are working on a fix. Please try again in 30 minutes or contact support if urgent."
|
||||||
|
```
|
||||||
|
|
||||||
|
### Error Prevention
|
||||||
|
|
||||||
|
**Better than good error messages is preventing errors:**
|
||||||
|
|
||||||
|
1. **Inline validation**: Show errors as users type (with debounce)
|
||||||
|
2. **Format hints**: "MM/DD/YYYY" next to date field
|
||||||
|
3. **Autocomplete**: Suggest valid values
|
||||||
|
4. **Disable invalid actions**: Gray out "Submit" until form valid
|
||||||
|
5. **Confirmation dialogs**: For destructive actions
|
||||||
|
6. **Smart defaults**: Pre-fill when possible
|
||||||
|
|
||||||
|
## Onboarding
|
||||||
|
|
||||||
|
### Onboarding Goals
|
||||||
|
|
||||||
|
1. **Time to value**: First meaningful action in < 2 min
|
||||||
|
2. **Time to success**: First win in < 5 min
|
||||||
|
3. **Time to competency**: Core workflow in < 10 min
|
||||||
|
|
||||||
|
### Progressive Disclosure
|
||||||
|
|
||||||
|
**Don't show everything at once.** Introduce features when needed.
|
||||||
|
|
||||||
|
```
|
||||||
|
❌ Bad: 20-step tutorial on first load
|
||||||
|
✅ Good: 3-step essential setup → Learn by doing → Contextual tips
|
||||||
|
|
||||||
|
❌ Bad: "Here are all 50 features!"
|
||||||
|
✅ Good: "Let's create your first project" → Reveal features in context
|
||||||
|
```
|
||||||
|
|
||||||
|
### Onboarding Patterns
|
||||||
|
|
||||||
|
#### Welcome Screen
|
||||||
|
```
|
||||||
|
Headline: Clear value proposition
|
||||||
|
"Welcome to [Product]! Let's get your workspace set up."
|
||||||
|
|
||||||
|
Subheadline: Process overview
|
||||||
|
"We'll help you connect your data, invite your team, and create your first report."
|
||||||
|
|
||||||
|
CTA: Start journey
|
||||||
|
[Get started]
|
||||||
|
|
||||||
|
Skip: Respectful exit
|
||||||
|
[Skip setup - I'll explore on my own]
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Step Indicators
|
||||||
|
```
|
||||||
|
Show progress clearly:
|
||||||
|
- "Step 2 of 4" (numeric)
|
||||||
|
- [█████░░░] (visual bar)
|
||||||
|
- "Import data" → "Invite team" → "Create report" (named steps)
|
||||||
|
|
||||||
|
Each step:
|
||||||
|
- Headline: What we're doing
|
||||||
|
- Context: Why it matters (1 sentence)
|
||||||
|
- Estimate: "About 30 seconds"
|
||||||
|
- Action: Clear next step
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Empty States (First Use)
|
||||||
|
```
|
||||||
|
[Friendly illustration]
|
||||||
|
"Your dashboard awaits"
|
||||||
|
"Dashboards help you track metrics at a glance. Create your first one to get started."
|
||||||
|
[Create dashboard] [See example]
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Feature Tooltips (Coachmarks)
|
||||||
|
```
|
||||||
|
Guidelines:
|
||||||
|
- Trigger on first encounter (not on page load)
|
||||||
|
- Limit to 3-5 per session
|
||||||
|
- Always dismissible
|
||||||
|
- Point to specific element
|
||||||
|
- 1-2 sentences max
|
||||||
|
|
||||||
|
Example:
|
||||||
|
"Use Quick Add (⌘K) to create tasks from anywhere"
|
||||||
|
[Got it]
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Success Moments
|
||||||
|
```
|
||||||
|
Celebrate completion:
|
||||||
|
"Excellent! Your workspace is ready. Here's what you can do now:"
|
||||||
|
✓ Create and assign tasks
|
||||||
|
✓ Track progress with dashboards
|
||||||
|
✓ Collaborate with your team
|
||||||
|
[Start working]
|
||||||
|
|
||||||
|
Micro-celebrations throughout:
|
||||||
|
✓ "Account connected"
|
||||||
|
✓ "Team invited"
|
||||||
|
✓ "First project created"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Onboarding Copy Guidelines
|
||||||
|
|
||||||
|
**Headlines**:
|
||||||
|
- Action-oriented: "Let's connect your calendar"
|
||||||
|
- Benefit-focused: "Track your time automatically"
|
||||||
|
- User-centric: "You're almost ready to start"
|
||||||
|
|
||||||
|
**CTAs**:
|
||||||
|
- Specific: "Import contacts" not "Next"
|
||||||
|
- Show progress: "Continue (3 of 5)"
|
||||||
|
- Positive: "Continue" not "Don't skip"
|
||||||
|
|
||||||
|
**Skip options**:
|
||||||
|
- Respectful: "I'll do this later"
|
||||||
|
- Honest: "Skip (you can always invite later)"
|
||||||
|
- Easy return: "Remind me tomorrow"
|
||||||
|
|
||||||
|
## Accessibility
|
||||||
|
|
||||||
|
### Alt Text
|
||||||
|
|
||||||
|
**Decorative images**: `alt=""`
|
||||||
|
**Functional images**: Describe action, not appearance
|
||||||
|
**Informative images**: Describe content/data
|
||||||
|
|
||||||
|
```
|
||||||
|
Decorative:
|
||||||
|
alt="" (tells screen readers to skip)
|
||||||
|
|
||||||
|
Functional (button/link):
|
||||||
|
❌ alt="Blue arrow icon"
|
||||||
|
✅ alt="Next page"
|
||||||
|
|
||||||
|
Informative (chart):
|
||||||
|
❌ alt="Chart"
|
||||||
|
✅ alt="Line chart showing 40% revenue growth from Q1 to Q4 2024"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Complex images**: Short alt + long description
|
||||||
|
```
|
||||||
|
<img alt="2024 sales distribution by region" src="chart.png">
|
||||||
|
<details>
|
||||||
|
<summary>Chart data</summary>
|
||||||
|
North America: 45%, Europe: 30%, Asia: 20%, Other: 5%
|
||||||
|
</details>
|
||||||
|
```
|
||||||
|
|
||||||
|
### ARIA Labels
|
||||||
|
|
||||||
|
**Use when visual label is missing or insufficient:**
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- Icon-only button -->
|
||||||
|
<button aria-label="Close dialog">×</button>
|
||||||
|
|
||||||
|
<!-- Add context -->
|
||||||
|
<button aria-label="Search products">🔍</button>
|
||||||
|
|
||||||
|
<!-- Don't use if text is visible -->
|
||||||
|
❌ <button aria-label="Save">Save</button>
|
||||||
|
✅ <button>Save</button>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Link Text
|
||||||
|
|
||||||
|
**Links should make sense out of context:**
|
||||||
|
|
||||||
|
```
|
||||||
|
❌ "Click here to download"
|
||||||
|
❌ "Read more"
|
||||||
|
❌ "Learn more about our privacy policy here"
|
||||||
|
|
||||||
|
✅ "Download 2024 annual report (PDF, 2.3 MB)"
|
||||||
|
✅ "Read our complete privacy policy"
|
||||||
|
✅ "Learn how we protect your data"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Form Accessibility
|
||||||
|
|
||||||
|
```html
|
||||||
|
<!-- Always use <label> -->
|
||||||
|
<label for="email">Email address</label>
|
||||||
|
<input type="email" id="email" />
|
||||||
|
|
||||||
|
<!-- Add helpful instructions -->
|
||||||
|
<label for="password">Password</label>
|
||||||
|
<span id="pwd-hint">At least 8 characters with 1 number</span>
|
||||||
|
<input
|
||||||
|
type="password"
|
||||||
|
id="password"
|
||||||
|
aria-describedby="pwd-hint"
|
||||||
|
/>
|
||||||
|
|
||||||
|
<!-- Associate errors -->
|
||||||
|
<input
|
||||||
|
type="email"
|
||||||
|
id="email"
|
||||||
|
aria-invalid="true"
|
||||||
|
aria-describedby="email-error"
|
||||||
|
/>
|
||||||
|
<span id="email-error" role="alert">
|
||||||
|
Please enter a valid email like name@example.com
|
||||||
|
</span>
|
||||||
|
```
|
||||||
|
|
||||||
|
### Inclusive Language
|
||||||
|
|
||||||
|
**Avoid ableist terms:**
|
||||||
|
```
|
||||||
|
❌ "See the new features"
|
||||||
|
✅ "Check out the new features"
|
||||||
|
|
||||||
|
❌ "Blind spot"
|
||||||
|
✅ "Gap" or "Missing area"
|
||||||
|
|
||||||
|
❌ "Crazy fast" / "Insane performance"
|
||||||
|
✅ "Incredibly fast" / "Exceptional performance"
|
||||||
|
|
||||||
|
❌ "Dummy text" / "Sanity check"
|
||||||
|
✅ "Sample text" / "Verification" or "Test"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Avoid directional language:**
|
||||||
|
```
|
||||||
|
❌ "Click the button on the right"
|
||||||
|
✅ "Click the Save button"
|
||||||
|
|
||||||
|
❌ "See the chart below"
|
||||||
|
✅ "The following chart shows..."
|
||||||
|
```
|
||||||
|
|
||||||
|
**Avoid color-only instructions:**
|
||||||
|
```
|
||||||
|
❌ "Click the green button"
|
||||||
|
✅ "Click the Confirm button"
|
||||||
|
|
||||||
|
❌ "Required fields are in red"
|
||||||
|
✅ "Required fields are marked with an asterisk (*)"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Voice & Tone
|
||||||
|
|
||||||
|
### Voice (Consistent Personality)
|
||||||
|
Your product's voice is its personality—stays consistent across all copy.
|
||||||
|
|
||||||
|
Common voice attributes:
|
||||||
|
- **Professional**: Clear, respectful, competent
|
||||||
|
- **Friendly**: Warm, approachable, conversational
|
||||||
|
- **Helpful**: Supportive, instructive, empowering
|
||||||
|
- **Confident**: Assured, capable, trustworthy
|
||||||
|
|
||||||
|
### Tone (Emotional Context)
|
||||||
|
Tone changes based on the situation.
|
||||||
|
|
||||||
|
**Positive moments** (success, celebration):
|
||||||
|
- Enthusiastic and congratulatory
|
||||||
|
- "Excellent! Your account is all set up and ready to go."
|
||||||
|
|
||||||
|
**Neutral moments** (forms, settings):
|
||||||
|
- Clear and straightforward
|
||||||
|
- "Enter your billing information to complete your purchase."
|
||||||
|
|
||||||
|
**Negative moments** (errors, warnings):
|
||||||
|
- Calm and helpful (never blame user)
|
||||||
|
- "We couldn't process your payment. Please check your card details and try again."
|
||||||
|
|
||||||
|
**Urgent moments** (critical errors, deadlines):
|
||||||
|
- Direct and clear (no fluff)
|
||||||
|
- "Your session expires in 2 minutes. Save your work now."
|
||||||
|
|
||||||
|
### Tone Examples by Context
|
||||||
|
|
||||||
|
```
|
||||||
|
Welcome (enthusiastic):
|
||||||
|
"Welcome to TaskFlow! We're excited to help you get organized."
|
||||||
|
|
||||||
|
Form (neutral):
|
||||||
|
"Enter your company information"
|
||||||
|
|
||||||
|
Success (celebratory):
|
||||||
|
"You did it! Your team has been invited."
|
||||||
|
|
||||||
|
Error (calm and helpful):
|
||||||
|
"We couldn't save your changes. Check your connection and try again."
|
||||||
|
|
||||||
|
Warning (direct):
|
||||||
|
"This action cannot be undone. Delete 3 files?"
|
||||||
|
|
||||||
|
Help (supportive):
|
||||||
|
"Not sure where to start? We'll guide you through setting up your first project."
|
||||||
|
```
|
||||||
|
|
||||||
|
## Content Patterns
|
||||||
|
|
||||||
|
### Character Limits
|
||||||
|
|
||||||
|
**Know your constraints:**
|
||||||
|
|
||||||
|
- **Button**: 15-20 characters ideal, 30 max
|
||||||
|
- **Tooltip**: 60-80 characters (2 lines)
|
||||||
|
- **Notification**: 90-120 characters
|
||||||
|
- **Error message**: 120-150 characters
|
||||||
|
- **Alt text**: 125-150 characters
|
||||||
|
- **Meta description**: 150-160 characters
|
||||||
|
- **Tweet**: 280 characters
|
||||||
|
|
||||||
|
### Numbers and Dates
|
||||||
|
|
||||||
|
**Be specific and use user's format:**
|
||||||
|
|
||||||
|
```
|
||||||
|
❌ "about 2 weeks ago"
|
||||||
|
✅ "January 15, 2024" or "2 weeks ago (Jan 15)"
|
||||||
|
|
||||||
|
❌ "1234567 bytes"
|
||||||
|
✅ "1.2 MB"
|
||||||
|
|
||||||
|
❌ "97.3%"
|
||||||
|
✅ "97% uptime" or "Almost always online"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Localization considerations:**
|
||||||
|
- Dates: US (01/15/2024) vs EU (15/01/2024)
|
||||||
|
- Use ISO 8601 for clarity: 2024-01-15
|
||||||
|
- Or spell out: January 15, 2024
|
||||||
|
- Times: 12-hour (3:00 PM) vs 24-hour (15:00)
|
||||||
|
|
||||||
|
### Capitalization
|
||||||
|
|
||||||
|
**Choose one and be consistent:**
|
||||||
|
|
||||||
|
**Title Case** (Each Major Word Capitalized):
|
||||||
|
- Headlines and page titles
|
||||||
|
- Navigation menu items
|
||||||
|
- Dialog titles
|
||||||
|
|
||||||
|
**Sentence case** (Only first word capitalized):
|
||||||
|
- Body text
|
||||||
|
- Form labels
|
||||||
|
- Button text (recommended)
|
||||||
|
- Error messages
|
||||||
|
- Tooltips
|
||||||
|
|
||||||
|
```
|
||||||
|
Title Case:
|
||||||
|
"Create New Project"
|
||||||
|
"Account Settings"
|
||||||
|
|
||||||
|
Sentence case:
|
||||||
|
"Create new project"
|
||||||
|
"Account settings"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Recommendation**: Sentence case is more readable, scannable, and friendly. Use for most UI copy.
|
||||||
|
|
||||||
|
### Punctuation
|
||||||
|
|
||||||
|
**General rules:**
|
||||||
|
|
||||||
|
- **Periods**: Use in body text and multi-sentence messages. Skip in single-sentence tooltips, labels, and buttons.
|
||||||
|
- **Exclamation points**: Use sparingly for celebration. Max 1 per screen.
|
||||||
|
- **Question marks**: Use in questions (obviously). Don't use in buttons ("Delete?" → "Delete item")
|
||||||
|
- **Colons**: Usually unnecessary in form labels. "Email:" → "Email address"
|
||||||
|
- **Ellipsis (...)**: Use for loading states. "Saving..." → shows ongoing action
|
||||||
|
|
||||||
|
```
|
||||||
|
✅ Button: "Save changes" (no period)
|
||||||
|
✅ Tooltip: "This saves your work automatically" (no period if 1 sentence)
|
||||||
|
✅ Error: "We couldn't save your changes. Check your connection and try again." (periods in multi-sentence)
|
||||||
|
✅ Success: "Project created!" (exclamation for celebration)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Contraction Use
|
||||||
|
|
||||||
|
**When to use contractions:**
|
||||||
|
- Friendly, conversational tone
|
||||||
|
- Onboarding and help text
|
||||||
|
- Success messages
|
||||||
|
- Chatbots and conversational UI
|
||||||
|
|
||||||
|
**When to avoid:**
|
||||||
|
- Formal business settings
|
||||||
|
- Legal or compliance text
|
||||||
|
- Serious errors or warnings
|
||||||
|
- When emphasizing words ("You will be charged")
|
||||||
|
|
||||||
|
```
|
||||||
|
Conversational:
|
||||||
|
"You're all set! We'll send a confirmation email."
|
||||||
|
|
||||||
|
Formal:
|
||||||
|
"You will be charged on the 1st of each month."
|
||||||
|
```
|
||||||
|
|
||||||
|
## UX Writing Checklist
|
||||||
|
|
||||||
|
Before publishing any copy, verify:
|
||||||
|
|
||||||
|
**Clarity**:
|
||||||
|
- [ ] Can a new user understand this immediately?
|
||||||
|
- [ ] Is it written in plain language (8th-grade level)?
|
||||||
|
- [ ] Are there any jargon or technical terms that need explanation?
|
||||||
|
|
||||||
|
**Brevity**:
|
||||||
|
- [ ] Is every word necessary?
|
||||||
|
- [ ] Can this be shorter without losing meaning?
|
||||||
|
- [ ] Have I removed filler words?
|
||||||
|
|
||||||
|
**User-centered**:
|
||||||
|
- [ ] Is it written from the user's perspective (not the system's)?
|
||||||
|
- [ ] Does it use "you/your" language?
|
||||||
|
- [ ] Does it focus on user benefits, not features?
|
||||||
|
|
||||||
|
**Consistency**:
|
||||||
|
- [ ] Does this match our existing terminology?
|
||||||
|
- [ ] Is capitalization consistent with our style?
|
||||||
|
- [ ] Does the tone match the context?
|
||||||
|
|
||||||
|
**Accessibility**:
|
||||||
|
- [ ] Do all images have appropriate alt text?
|
||||||
|
- [ ] Are links descriptive out of context?
|
||||||
|
- [ ] Is this understandable by screen readers?
|
||||||
|
- [ ] Have I avoided ableist language?
|
||||||
|
- [ ] Have I avoided color-only or direction-only instructions?
|
||||||
|
|
||||||
|
**Actionability**:
|
||||||
|
- [ ] Is the next step clear?
|
||||||
|
- [ ] Are CTAs specific and action-oriented?
|
||||||
|
- [ ] Have I provided a solution (for errors)?
|
||||||
|
|
||||||
|
**Scannability**:
|
||||||
|
- [ ] Can users skim and understand key points?
|
||||||
|
- [ ] Have I front-loaded important information?
|
||||||
|
- [ ] Is the structure clear (headlines, bullets)?
|
||||||
|
|
||||||
|
This skill provides the foundation for all UX writing decisions. Apply these patterns consistently to create interfaces that are clear, helpful, and accessible to all users.
|
||||||
Reference in New Issue
Block a user