whiteport-design-studio 0.1.0

package/docs/method/tone-of-voice-guide.md

@@ -0,0 +1,466 @@
+# 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.** 🎯
+