From 50141bd9d0b1d099981a16dfb4a979a31f8a1225 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 17:59:46 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 20 + README.md | 3 + agents/accessibility-specialist.md | 39 ++ agents/design-lead.md | 36 ++ agents/ux-researcher.md | 39 ++ agents/ux-writer.md | 38 ++ plugin.lock.json | 73 +++ skills/accessibility/SKILL.md | 134 +++++ skills/brand-strategy/SKILL.md | 153 ++++++ skills/ux-research/SKILL.md | 703 +++++++++++++++++++++++++++ skills/ux-writing/SKILL.md | 756 +++++++++++++++++++++++++++++ 11 files changed, 1994 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 agents/accessibility-specialist.md create mode 100644 agents/design-lead.md create mode 100644 agents/ux-researcher.md create mode 100644 agents/ux-writer.md create mode 100644 plugin.lock.json create mode 100644 skills/accessibility/SKILL.md create mode 100644 skills/brand-strategy/SKILL.md create mode 100644 skills/ux-research/SKILL.md create mode 100644 skills/ux-writing/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..505fcec --- /dev/null +++ b/.claude-plugin/plugin.json @@ -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" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..4000528 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# design + +User-centered design team with 4 specialized roles covering UX research, writing, accessibility, and creative direction diff --git a/agents/accessibility-specialist.md b/agents/accessibility-specialist.md new file mode 100644 index 0000000..ce0b078 --- /dev/null +++ b/agents/accessibility-specialist.md @@ -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" diff --git a/agents/design-lead.md b/agents/design-lead.md new file mode 100644 index 0000000..0c77cb1 --- /dev/null +++ b/agents/design-lead.md @@ -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" diff --git a/agents/ux-researcher.md b/agents/ux-researcher.md new file mode 100644 index 0000000..21fc459 --- /dev/null +++ b/agents/ux-researcher.md @@ -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" diff --git a/agents/ux-writer.md b/agents/ux-writer.md new file mode 100644 index 0000000..3f2ca3f --- /dev/null +++ b/agents/ux-writer.md @@ -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" diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..5703eff --- /dev/null +++ b/plugin.lock.json @@ -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": [] + } +} \ No newline at end of file diff --git a/skills/accessibility/SKILL.md b/skills/accessibility/SKILL.md new file mode 100644 index 0000000..dbe89bf --- /dev/null +++ b/skills/accessibility/SKILL.md @@ -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 + +
Click me
+ + + +``` + +### ARIA Labels +```html + +``` + +### 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 + +{error && ( + + {error} + +)} +``` + +### Accessible Modals +```tsx +
+

Modal Title

+ {/* Trap focus within modal */} + {/* Close on Escape */} +
+``` + +### Accessible Tables +```html + + + + + + + + + + + + + + +
Monthly Sales Data
MonthSales
January0,000
+``` + +## 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 + diff --git a/skills/brand-strategy/SKILL.md b/skills/brand-strategy/SKILL.md new file mode 100644 index 0000000..e58a991 --- /dev/null +++ b/skills/brand-strategy/SKILL.md @@ -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 + diff --git a/skills/ux-research/SKILL.md b/skills/ux-research/SKILL.md new file mode 100644 index 0000000..6c85050 --- /dev/null +++ b/skills/ux-research/SKILL.md @@ -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 diff --git a/skills/ux-writing/SKILL.md b/skills/ux-writing/SKILL.md new file mode 100644 index 0000000..0de80af --- /dev/null +++ b/skills/ux-writing/SKILL.md @@ -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 +``` +2024 sales distribution by region +
+ Chart data + North America: 45%, Europe: 30%, Asia: 20%, Other: 5% +
+``` + +### ARIA Labels + +**Use when visual label is missing or insufficient:** + +```html + + + + + + + +❌ +✅ +``` + +### 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 + + + + + + +At least 8 characters with 1 number + + + + + + Please enter a valid email like name@example.com + +``` + +### 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.