# Tone of Voice Guide

**Consistent communication personality for UI microcopy and system messages**

---

## What is Tone of Voice?

**Tone of Voice (ToV)** defines your product's communication personality—how your brand "speaks" to users through all UI microcopy and system messages.

It's the consistent voice users hear in:
- Form labels and placeholders
- Button text
- Error and success messages
- Empty states
- Loading states
- Tooltips and instructions
- System notifications

---

## Why Tone of Voice Matters

### Creates Consistency
- All UI microcopy feels like it comes from the same "person"
- Users develop a relationship with your brand voice
- Professional, cohesive experience

### Builds Brand Personality
- Differentiates you from competitors
- Reinforces brand values and positioning
- Creates emotional connection

### Guides Decisions
- Designers/developers know how to write microcopy
- No need to debate every button label
- Faster, more consistent implementation

---

## Tone of Voice vs Strategic Content

### Tone of Voice (Product-Wide Consistency)

**Applies to UI Microcopy:**
- ✅ Form field labels
- ✅ Button text (standard actions)
- ✅ Error messages
- ✅ Success/confirmation messages
- ✅ Empty states
- ✅ Loading states
- ✅ Tooltips
- ✅ System notifications
- ✅ Navigation labels

**Characteristics:**
- Consistent across entire product
- Defined once in Product Brief
- Applied systematically
- Based on brand personality and target users

---

### Strategic Content (Context-Specific Purpose)

**Applies to Marketing/Feature Content:**
- ❌ Headlines and hero sections
- ❌ Feature descriptions
- ❌ Value propositions
- ❌ Testimonials and case studies
- ❌ Landing page content
- ❌ Onboarding narratives

**Characteristics:**
- Varies by page/context
- Created using Content Creation Workshop
- Purpose-driven (each piece has a job)
- Uses strategic models (CAC, Golden Circle, Badass Users, etc.)

---

## Defining Your Tone of Voice

### Step 1: Choose 3-5 Tone Attributes

**Common attributes:**
- Friendly vs Professional
- Casual vs Formal
- Playful vs Serious
- Warm vs Cool
- Technical vs Accessible
- Empathetic vs Straightforward
- Quirky vs Traditional
- Authoritative vs Humble

**Example combinations:**

**Consumer Social App:**
- Friendly
- Casual
- Playful
- Warm

**Enterprise B2B SaaS:**
- Professional
- Clear
- Supportive
- Authoritative

**Healthcare App:**
- Empathetic
- Warm
- Professional
- Reassuring

**Developer Tool:**
- Technical
- Precise
- Straightforward
- Respectful

### Step 2: Write Examples

Show don't tell. For each tone attribute, provide examples:

**Format:**
```
[Tone Attribute]: [Brief description]

Examples:
❌ Generic: [Standard industry phrasing]
✅ Our Tone: [Rewritten in your voice]
```

### Step 3: Create Guidelines

**Do's and Don'ts:**

Clear rules for what fits your tone and what doesn't:
- Do use contractions / Don't be overly formal
- Do acknowledge user feelings / Don't be robotic
- Do keep it concise / Don't over-explain

---

## Tone of Voice by Context

### Error Messages

**Generic (no tone):**
- "Error: Invalid input"
- "404 Not Found"
- "Authentication failed"

**Friendly & Empathetic:**
- "Hmm, that doesn't look quite right. Mind double-checking?"
- "We couldn't find that page. Let's get you back on track."
- "We couldn't log you in. Check your email and password?"

**Professional & Clear:**
- "Please enter a valid email address"
- "This page doesn't exist. Return to dashboard?"
- "Login failed. Verify your credentials and try again"

**Technical & Precise:**
- "Invalid email format. Expected: `name@domain.com`"
- "Resource not found. Check URL and retry"
- "Authentication error: Invalid credentials provided"

---

### Success Messages

**Generic (no tone):**
- "Success"
- "Operation completed"
- "Saved"

**Friendly & Empathetic:**
- "You're all set! 🎉"
- "Perfect! Your changes are saved."
- "Nice work! Everything's updated."

**Professional & Clear:**
- "Changes saved successfully"
- "Your profile has been updated"
- "Settings applied"

**Technical & Precise:**
- "Operation completed: Profile updated"
- "Save successful. Last modified: [timestamp]"
- "Configuration saved to database"

---

### Button Text

**Generic (no tone):**
- Submit
- Continue
- Cancel
- Delete

**Friendly & Empathetic:**
- Let's go!
- Next step
- Never mind
- Remove this

**Professional & Clear:**
- Confirm
- Proceed
- Go back
- Delete item

**Technical & Precise:**
- Execute
- Advance
- Abort
- Remove record

---

### Empty States

**Generic (no tone):**
- "No results"
- "Empty"
- "Nothing found"

**Friendly & Empathetic:**
- "Nothing here yet. Ready to add your first item?"
- "Your inbox is empty—enjoy the peace!"
- "No matches found. Try a different search?"

**Professional & Clear:**
- "No items to display. Add your first item to get started."
- "Your inbox is empty."
- "No results match your search criteria."

**Technical & Precise:**
- "Query returned 0 results"
- "No records in database"
- "Search yielded no matches for specified criteria"

---

## How to Apply Tone of Voice

### During Product Brief (Phase 1)

1. Agent analyzes product, users, positioning
2. Agent suggests appropriate tone attributes
3. Agent provides examples of tone in action
4. User confirms/refines
5. Tone of Voice documented in Product Brief

### During UI Design (Phase 4)

1. Designer creates UI elements
2. For standard microcopy (labels, buttons, errors), apply ToV
3. For strategic content (headlines, features), use Content Creation Workshop
4. ToV ensures all microcopy feels consistent

### During Development

1. Developers reference ToV guidelines
2. Write new microcopy following established tone
3. No need to ask designer for every button label
4. Consistency maintained automatically

---

## Examples by Product Type

### Consumer Social App: FriendCircle

**Tone Attributes:** Friendly, Casual, Playful, Warm

**Error Messages:**
- ✅ "Oops! We couldn't upload that photo. Try again?"
- ✅ "Hmm, we're having trouble connecting. Check your wifi?"

**Button Text:**
- ✅ "Share with friends"
- ✅ "Love it!"
- ✅ "Maybe later"

**Empty States:**
- ✅ "No posts yet. Be the first to share!"
- ✅ "Your feed is empty. Follow some friends to get started!"

---

### Enterprise SaaS: TaskFlow

**Tone Attributes:** Professional, Clear, Supportive, Efficient

**Error Messages:**
- ✅ "Please enter a valid project name"
- ✅ "We couldn't save your changes. Check your connection and try again"

**Button Text:**
- ✅ "Create project"
- ✅ "Save changes"
- ✅ "Cancel"

**Empty States:**
- ✅ "No projects yet. Create your first project to get started."
- ✅ "All tasks complete. Well done!"

---

### Healthcare App: WellPath

**Tone Attributes:** Empathetic, Warm, Professional, Reassuring

**Error Messages:**
- ✅ "We couldn't record your reading. Please try again, or contact support if this continues"
- ✅ "That date doesn't look quite right. Check and try again?"

**Button Text:**
- ✅ "Log today's reading"
- ✅ "I'm done"
- ✅ "Skip for now"

**Empty States:**
- ✅ "No readings yet. Let's record your first one."
- ✅ "You're all caught up. Great work staying on track!"

---

### Developer Tool: CodeStream

**Tone Attributes:** Technical, Precise, Straightforward, Respectful

**Error Messages:**
- ✅ "Build failed: Syntax error on line 47"
- ✅ "API request failed: Invalid authentication token"

**Button Text:**
- ✅ "Run build"
- ✅ "Deploy"
- ✅ "Abort"

**Empty States:**
- ✅ "No builds configured. Add your first build pipeline."
- ✅ "Query returned 0 results"

---

## Common Mistakes

### ❌ Inconsistent Tone

**Problem:** Mixing tones within the same product

**Example:**
- Error: "Oops! Something went wrong 😅" (playful)
- Success: "Operation completed successfully" (formal)

**Fix:** Choose one tone and apply it consistently

---

### ❌ Over-Personification

**Problem:** Treating software like a person with feelings

**Example:**
- "I'm sorry, I couldn't do that" (who is "I"?)
- "I'm confused by your input"

**Fix:** Keep focus on user and their action
- "We couldn't complete that action"
- "Please check your input and try again"

---

### ❌ Forced Personality

**Problem:** Trying too hard to be clever/funny

**Example:**
- "Whoopsie-daisy! Our hamsters fell off their wheels!"
- "Houston, we have a problem..."

**Fix:** Be helpful first, personality second
- "We're experiencing technical difficulties. Please try again"

---

### ❌ Tone-Deaf to Context

**Problem:** Same tone regardless of severity

**Example:**
- Critical error: "Uh oh, looks like we lost your data! 🙈"
- (Playful tone inappropriate for serious situation)

**Fix:** Adjust tone for serious/critical situations
- "We encountered an error saving your data. Please contact support immediately"

---

## Testing Your Tone of Voice

### Consistency Check

Write 10 different UI messages (errors, success, buttons, empty states). Do they all sound like they're from the same "person"?

### User Testing

Show microcopy examples to target users. Ask:
- "How does this make you feel?"
- "Does this match how you'd expect [brand] to communicate?"
- "Is this helpful/clear/respectful?"

### Edge Cases

Test tone in difficult situations:
- Critical errors
- Data loss
- Payment failures
- Account suspensions

Does your tone still work, or does it feel inappropriate?

---

## Integration with WDS

### Phase 1: Product Brief
- **Step 10.5:** Define Tone of Voice
- Agent suggests tone based on product context
- User confirms/refines
- ToV documented in brief

### Phase 4: UX Design
- **UI Microcopy:** Apply ToV guidelines
- **Strategic Content:** Use Content Creation Workshop
- Clear distinction prevents confusion

### Development
- Reference ToV guidelines from Product Brief
- Apply consistently to all microcopy
- No need for case-by-case decisions

---

## Resources

**Related WDS Guides:**
- [Content Purpose Guide](content-purpose-guide.md) - For strategic content
- [Content Creation Workshop](../src/workflows/shared/content-creation-workshop/content-creation-workshop-guide.md) - For headlines/features
- [Product Brief Workflow](../src/workflows/1-project-brief/) - Where ToV is defined

**External Resources:**
- Mailchimp's Voice & Tone Guide
- GOV.UK Content Design Principles
- Nielsen Norman Group: Tone of Voice articles

---

**Make every microcopy decision easier. Define your tone once, apply it everywhere.** 🎯

