zhongwei/gh-bandofai-puerto-plugins-design
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 17:59:46 +08:00
commit 50141bd9d0
11 changed files with 1994 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
skills/accessibility/SKILL.md Normal file
View 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
View 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
View 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
View 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.