Ux Writing

UX Writing

Write clear, concise, user-centered interface copy (UX text/microcopy) for digital products and experiences. This skill provides frameworks, patterns, and best practices for creating text that helps users accomplish their goals.

When to Use This Skill

Use this skill when:

• Writing interface copy (buttons, labels, titles, messages, forms)
• Editing existing UX text for clarity and effectiveness
• Creating error messages, notifications, or success messages
• Designing conversational flows or onboarding experiences
• Establishing voice and tone for a product
• Auditing product content for consistency and usability

Core UX Writing Principles

The Four Quality Standards

Every piece of UX text should be:

1. Purposeful — Helps users or the business achieve goals 2. Concise — Uses the fewest words possible without losing meaning 3. Conversational — Sounds natural and human, not robotic 4. Clear — Unambiguous, accurate, and easy to understand

Key Best Practices

Conciseness

• Use 40-60 characters per line maximum
• Every word must have a job
• Break dense text into scannable chunks
• Front-load important information
• Eliminate deadwood phrases ("in order to" → "to", "due to the fact that" → "because", "at this point in time" → "now")
• Replace phrasal verbs with direct verbs ("find out" → "discover", "set up" → "configure", "carry out" → "perform")
• Avoid stacking modifiers — one adjective is usually enough

Clarity

• Use plain language (7th grade reading level for general, 10th for professional)
• Avoid jargon, idioms, and technical terms
• Use consistent terminology throughout
• Choose meaningful, specific verbs
• Avoid discriminatory or exclusionary language (gendered defaults, ableist idioms, culturally specific metaphors)

Conversational Tone

• Write how you speak
• Use active voice 85% of the time
• Include prepositions and articles
• Avoid robotic phrasing

User-Centered

• Focus on user benefits, not features
• Anticipate and answer user questions
• Use second-person ("you") language
• Match user's language and mental models

UX Text Patterns

Apply these common patterns for interface elements.

Titles

• Purpose: Orient users to where they are
• Format: Noun phrases. Page titles, modal/dialog titles, and menu/navigation items use title case (see Capitalization below for title-case mechanics). Lower-level headings (H3+), figure captions, callouts, and table titles use sentence case.
• Types: Brand titles, content titles, category titles, task titles
• Examples:
• Page title (title case): "Account Settings", "Your Library", "Run Payroll"
• Lower-level heading (sentence case): "Recent activity", "Bank account details", "Tax withholdings"

Buttons and Links

• Purpose: Enable users to take action
• Format: Active imperative verbs, sentence case
• Pattern: [Verb] [object]
• Examples: "Save changes", "Delete account", "View details"
• Avoid: Generic labels like "OK", "Submit", "Click here"

Error Messages

• Purpose: Explain problem and provide solution
• Format: Empathetic, clear, actionable
• Pattern: [What failed]. [Why/context]. [What to do].

Error Message Types

Validation Errors (Inline)

• Show as user completes field or on blur
• Brief, specific guidance to correct input
• Pattern: [Field] [specific requirement]
• Examples:
• "Email must include @"
• "Password must be at least 8 characters"
• "Choose a date in the future"
• Timing: Real-time or on field exit
• Location: Below or beside the field

System Errors (Modal/Banner)

• Show when backend operations fail
• Explain what happened and why
• Pattern: [Action failed]. [Likely cause]. [Recovery step].
• Examples:
• "Payment failed. Your card was declined. Try a different payment method."
• "Couldn't save changes. Connection lost. Reconnect and try again."
• "Upload failed. File is too large. Choose a file under 10MB."
• Timing: Immediately after failure
• Location: Modal dialog or prominent banner

Blocking Errors (Full-screen)

• Prevent continued use until resolved
• Clear explanation of blocker and resolution
• Pattern: [What's blocked]. [Why]. [Specific action needed].
• Examples:
• "Update required. This version is no longer supported. Update now to continue."
• "Subscription expired. Your account is paused. Renew subscription to restore access."
• "Verification needed. Confirm your email to access features. Check your inbox."
• Timing: On app launch or feature access
• Location: Full screen or large modal

Permission Errors

• Explain benefit before requesting permission
• Pattern: [User benefit]. [Permission needed].
• Examples:
• "Get notified when orders ship. Enable notifications."
• "Find nearby stores. Allow location access."
• "Back up your photos. Grant storage permission."
• Timing: When feature is first used
• Location: In context of the feature

What to Avoid

• Technical codes without explanation ("Error 403")
• Blame language ("invalid input", "illegal character")
• Robotic tone ("An error has occurred")
• Dead ends (error with no recovery path)
• Vague causes ("Something went wrong")

Success Messages

• Purpose: Confirm action completion
• Format: Past tense, specific, encouraging
• Pattern: [Action] [result/benefit]
• Examples: "Changes saved", "Email sent", "Profile updated"

Empty States

• Purpose: Guide users when content is absent
• Types: First-use, user-cleared, error/no results
• Format: Explanation + CTA to populate
• Example: "No messages yet. Start a conversation to connect with your team."

Form Fields

• Labels: Clear noun phrases describing input ("Email address", "Phone number")
• Instructions: Verb-first, explain why information is needed
• Placeholder: Use sparingly, only for standard inputs like "name@example.com"
• Helper text: Static, on-demand, or automatic based on importance

Notifications

• Purpose: Deliver timely, valuable information
• Types: Action-required (intrusive), Passive (less intrusive)
• Format: Verb-first title + contextual description
• Example: "Update required. Install the latest version to continue."

Formatting & Style Conventions

Capitalization

• Sentence case (default): Body text, descriptions, helper text, error messages, success messages, tooltips, placeholder text, button labels, lower-level (H3+) headings, figure captions, callouts, table titles
• Title case: Page titles, modal/dialog titles, menu and navigation items, form field labels
• All-caps: Reserved for short overline / eyebrow labels (≤3 words) that sit above a heading or metric — e.g., stat-card section headers like EMPLOYEES, TOTAL PAY, LAST UPDATED, category tags over KPI values — and for acronyms (PDF, URL, API, EIN, SSN). Trimble's own product surfaces use this treatment for short category overlines; it's an intentional typographic signal, not shouting. Do not use all-caps for prose, button labels, error messages, page titles, tabs/menu labels, or any string longer than ~3 words — beyond that length readability drops sharply and it reads as shouting.

Title case mechanics (applies wherever title case is used):

• Capitalize the first and last word of the title regardless of part of speech.
• Capitalize all adjectives, adverbs, and nouns.
• Capitalize all pronouns (including "it").
• Capitalize all verbs, including the verb "to be" in all forms (is, are, was, has been, etc.).
• Capitalize "no", "not", and the interjection "O".
• Do not capitalize articles ("a", "an", "the") unless first or last in the title.
• Do not capitalize coordinating conjunctions ("and", "or", "nor", "but", "for", "yet", "so") unless first or last in the title.
• Do not capitalize "to" (with or without an infinitive) unless first or last in the title.
• Do not capitalize prepositions (e.g., "in", "on", "at", "by", "of", "with") unless first or last in the title.

Examples:

• "Run Payroll for the Pay Period"
• "Add a New Employee"
• "How to File Quarterly Taxes"

Lista interpretations of edge cases:

• "Coming soon" is the canonical future-feature label everywhere it appears (badges, callouts, copy). Even when used in a title-cased context, write it sentence case per the lista-ui-conventions rule. Do not expose milestone granularity ("Coming at Beta", "Coming at GA") in user-facing strings.
• Dropdown action items (imperative-verb items inside a button-triggered menu, e.g. "Add employee", "See payroll runs", "Export report") are treated as buttons → sentence case, not as static navigation menu items. Prism's "menu items use title case" rule applies to navigational menus (side nav, breadcrumbs, top-level nav links pointing to pages), not action menus.
• Buttons that reference a named page (e.g. "Go to Setup Wizard", "Back to Payroll Hub", "Open Time Review") preserve the page name's title case while the surrounding button copy stays sentence case. The page name is a proper noun in this context.

Numbers and Dates

• Use numerals, not words ("12" not "twelve") — saves space and scans faster.
• Spell out the month in dates: "August 5, 2025" or "5 August 2025" — never "8/5/2025" or "8.5.2025" (ambiguous across locales).
• Spell out day of the week and month; abbreviate only when space is constrained (e.g., tables, mobile): "Sat., Jan. 24".
• Avoid ordinal suffixes in dates: write "August 5", not "August 5th"; write "May 1", not "May 1st".
• Year ranges use a hyphen with the full year on both sides: "2015-2016", not "2015-16" and not "2015 to 2016".

Tense

• Prefer past tense over present perfect for status messages: "File uploaded" not "File has been uploaded"
• Present perfect adds words without adding meaning in most UI contexts

Abbreviations

• Only use abbreviations your users will immediately understand (common: PDF, URL, ID)
• Spell out on first use if there's any doubt, then abbreviate after: "application programming interface (API)"
• Latin abbreviations (e.g., i.e., etc.) — use proper punctuation: period after each letter, comma before and after in a sentence
• When in doubt, spell it out

Voice and Tone

Voice (Consistent Brand Personality)

Voice is the consistent personality of the product. Establish voice using:

• Concepts: 3-5 key brand principles/values
• Voice characteristics: Descriptive adjectives for each concept
• Do/Don't examples: Concrete examples showing voice in action

See references/voice-chart-template.md for creating a voice chart.

Tone (Adaptive to Context)

Tone is how voice adapts to specific situations. While voice remains constant, tone shifts based on user context and emotional state.

Tone Variables

• Purpose: Why user is seeing this text (information, action, confirmation)
• Context: What user is trying to do (learning, completing task, recovering from error)
• Emotional state: How user likely feels (frustrated, excited, confused, cautious)
• Stakes: Impact of the action (low: changing theme, high: deleting account)

Tone Adaptation by User Emotional State

Frustrated (errors, failures, blockers)

• Empathetic and solution-focused
• Acknowledge the problem without blame
• Provide clear recovery path
• Example: "Payment failed. Your card was declined. Try a different payment method."

Confused (first use, complex features)

• Patient and explanatory
• Break down steps clearly
• Provide context and guidance
• Example: "Connect your bank to see spending insights. We'll guide you through it."

Confident (routine tasks, return visits)

• Efficient and direct
• Minimal explanation
• Quick confirmation
• Example: "Saved"

Cautious (high-stakes actions, data loss)

• Serious and transparent
• Clear consequences
• Respectful of user's decision
• Example: "Delete account? You'll lose all data and this can't be undone."

Successful (completions, achievements)

• Positive and encouraging
• Proportional to achievement
• Brief celebration
• Example: "Profile updated. Your changes are live."

Tone Adaptation by Content Type

Error messages: Empathetic, reassuring, solution-focused

• Never blame user
• Explain what happened
• Provide clear next step

Success messages: Positive, specific, encouraging

• Confirm what happened
• Proportional to action importance
• Brief and clear

Instructions: Clear, direct, helpful

• Front-load key action
• Explain why when needed
• Use simple steps

Onboarding: Inviting, encouraging, concise

• Welcome without overwhelming
• Focus on value
• Celebrate early wins

Confirmations: Serious, transparent, respectful

• Clear about consequences
• No manipulation
• Easy to back out

Empty states: Hopeful, actionable, guiding

• Explain why it's empty
• Provide clear next action
• Keep encouraging tone

Editing Process

Edit UX text in four phases:

Phase 1: Purposeful

• Does text help user achieve their goal?
• Does text serve business objectives?
• Is value to user clear?
• Are concerns anticipated and addressed?

Phase 2: Concise

• Remove unnecessary words
• Combine redundant information
• Ensure every word earns its space
• Front-load important concepts

Phase 3: Conversational

• Read aloud—would you say this?
• Use active voice (unless passive is clearer)
• Include natural connecting words
• Avoid corporate jargon

Phase 4: Clear

• Use specific, accurate verbs
• Maintain consistent terminology
• Test readability (Hemingway Editor, Flesch-Kincaid)
• Ensure unambiguous meaning

Workflow

1. Understand context

• User goals and needs
• Business objectives
• Technical constraints
• Emotional state of user

2. Draft content

• Start with conversation (what would you say?)
• Apply appropriate pattern
• Consider voice and tone
• Front-load important information

3. Edit iteratively

• Phase 1: Purposeful
• Phase 2: Concise
• Phase 3: Conversational
• Phase 4: Clear

4. Test and measure

• Review with team
• Test with users when possible
• Measure task completion, comprehension
• Iterate based on feedback

Accessibility in UX Writing

Writing accessible content ensures all users, including those using assistive technology, can understand and interact with your product.

Core Accessibility Principles

Screen Reader Optimization

• Label all interactive elements explicitly ("Submit form" not just "Submit")
• Write descriptive link text ("Read pricing details" not "Click here")
• Structure error messages to work with screen readers (error + field label read together)
• Use ARIA labels when visual context isn't sufficient

Cognitive Accessibility

• Target 8-14 words per sentence (8 words = 100% comprehension, 14 words = 90%)
• Break complex information into scannable chunks
• Use clear headings and logical hierarchy
• Provide consistent, predictable patterns

Multi-Modal Communication

• Don't rely on color alone to convey meaning
• Pair visual indicators with text ("Error: Email required" with red icon)
• Provide text alternatives for icons and images
• Ensure sufficient color contrast (WCAG AA minimum: 4.5:1)

Plain Language for All

• Target 7th-8th grade reading level for general audience
• Define technical terms when first used
• Avoid idioms, metaphors, and cultural references
• Use common, everyday words

Accessible Pattern Examples

Buttons

• ❌ Poor: "Submit" (context missing for screen readers)
• ✅ Good: "Submit application"

Links

• ❌ Poor: "Click here for more information"
• ✅ Good: "Read our privacy policy"

Error Messages

• ❌ Poor: Red text showing "Invalid"
• ✅ Good: "Error: Email must include @" (with error icon)

Form Labels

• ❌ Poor: Placeholder-only fields
• ✅ Good: Visible label + optional placeholder

UX Text Benchmarks

Use these research-backed metrics to create effective UX text.

Sentence Length Targets

By Content Type

• Buttons/CTAs: 2-4 words ideal, 6 word maximum
• Titles: 3-6 words, 40 characters maximum
• Error messages: 12-18 words (including solution)
• Instructions: 20 words maximum, 14 ideal
• Body copy: 15-20 words per sentence average
• Notifications: 10-15 words for title + body

Comprehension Rates

• 8 words or fewer: 100% user comprehension
• 14 words or fewer: 90% user comprehension
• 25 words: Maximum before significant comprehension drop

Character and Line Length

Optimal Ranges

• Line length: 40-60 characters for maximum readability
• Button labels: 15-25 characters
• Page titles: 30-50 characters
• Notification titles: 35-45 characters

Reading Level Guidelines

By Audience

• General public: 7th-8th grade (Flesch-Kincaid)
• Professional tools: 9th-10th grade
• Technical products: 10th-11th grade
• Specialized fields: 11th-12th grade (only when necessary)

Testing Tools

• Hemingway Editor: Highlights complex sentences
• Readable.com: Provides multiple readability scores
• Microsoft Word: Built-in Flesch-Kincaid scoring

Common Mistakes to Avoid

• Using passive voice excessively
• Generic button labels ("Submit", "OK")
• Blaming users in error messages
• Overly clever humor in serious contexts
• Inconsistent terminology
• Hidden instructions or explanations
• System-oriented language vs. user language
• Too many words (not concise enough)
• Robotic, corporate tone
• Relying on color alone for meaning
• Writing inaccessible link text ("Click here")

Quick Reference

Sentence case: "Save your changes" (not "Save Your Changes") Active imperative for buttons: "Delete account" (not "Account deletion") User-focused: "Save time with shortcuts" (not "We offer shortcuts") Specific verbs: "Delete" (not "Remove" when permanently deleting) Front-loaded: "Password must be 8 characters" (not "Must be 8 characters for your password")

Style references

External references this skill is grounded in (consult these for any case the skill doesn't cover):

• Modus Style Guide — Trimble's design-system writing rules (the canonical source for Modus-branded products).
• The Chicago Manual of Style — fallback for grammar, punctuation, and citation questions.
• The Merriam-Webster Dictionary — fallback for spelling and word choice.

Lista Payroll inherits Prism's writing conventions, which are themselves aligned with Modus. When this skill conflicts with lista-ui-conventions (e.g. "Coming soon" copy), the Lista rule wins.

Resources

This skill includes:

• references/accessibility-guidelines.md: Comprehensive guide to writing accessible UX text for all users
• references/voice-chart-template.md: Template for creating a product voice chart
• references/content-usability-checklist.md: Comprehensive checklist for evaluating UX text quality
• references/patterns-detailed.md: Extended examples of UX text patterns in different voices
• examples/real-world-improvements.md: Before/after transformations with detailed analysis and scoring
• templates/error-message-template.md: Fillable template for writing effective error messages
• templates/empty-state-template.md: Guide for creating helpful empty states
• templates/onboarding-flow-template.md: Framework for designing clear onboarding experiences

Using UX Writing Skill with Figma

Connect this skill to Figma so Claude can review and improve copy directly from your designs. Perfect for content designers, product designers, and anyone who needs to audit or enhance UX text in Figma mockups.

What You Can Do

Once connected, you can:

• Share Figma frame links with Claude and get instant UX writing feedback
• Audit existing designs for accessibility, clarity, and tone
• Generate improved copy that follows best practices
• Review entire flows for consistency and voice
• Get specific suggestions based on the four quality standards

Quick Example

Here's my login screen: [Figma link]

Review all the UX copy using the UX Writing Skill. Check for:
- Accessibility (screen reader compatibility, plain language)
- Error message clarity
- Button labels
- Tone consistency

Claude will analyze the design, identify all text elements, and provide detailed feedback with specific improvements.

---

Setup: Connect Figma to Claude Code

There are two ways to connect Figma to Claude Code. Choose the Remote Server option unless you have specific requirements for the Desktop Server.

Option 1: Remote Server (Recommended)

Best for: Quick setup, working from anywhere, no Figma desktop app needed

Requirements:

• Claude Code installed
• Figma account (Starter, Professional, Organization, or Enterprise plan)
• Internet connection

Setup Steps:

Step 1: Install Figma MCP

1. Open your terminal (Terminal on Mac, Command Prompt or PowerShell on Windows) 2. Copy and paste this command:

   claude mcp add --transport http figma https://mcp.figma.com/mcp

3. Press Enter and wait for it to complete

Step 2: Restart Claude Code

1. Completely quit Claude Code (don't just close the window) 2. Reopen Claude Code

Step 3: Authenticate with Figma

1. In Claude Code, type: /mcp 2. Press Enter to see your MCP servers 3. Find the "figma-remote-mcp" server 4. If it shows "disconnected", press Enter on that line 5. A browser window will open asking you to allow access 6. Click "Allow access" to connect Claude Code to your Figma account

Step 4: Verify It's Working

Type in Claude Code:

Do you have access to Figma?

Claude should confirm it can access Figma and explain what it can do.

---

Option 2: Desktop Server

Best for: Working locally, no internet dependency once set up

Requirements:

• Figma desktop app (latest version)
• Claude Code installed
• Dev Mode access in Figma

Setup Steps:

Step 1: Enable MCP in Figma Desktop

1. Open the Figma desktop app 2. Open any design file 3. Press Shift + D to switch to Dev Mode 4. In the right panel (Inspect panel), scroll to the MCP server section 5. Click "Enable desktop MCP server" 6. You'll see a confirmation message at the bottom

Step 2: Connect Claude Code

1. Open your terminal 2. Copy and paste this command:

   claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp

3. Press Enter

Step 3: Restart Claude Code

1. Completely quit Claude Code 2. Reopen Claude Code

Step 4: Verify It's Working

Type in Claude Code:

Do you have access to Figma?

Claude should confirm the connection.

Note: The Figma desktop app must be running with Dev Mode enabled for this to work.

---

How to Use with UX Writing Skill

Method 1: Share Figma Links

Step 1: Get the Figma Link

1. Open your design in Figma (web or desktop app) 2. Select the frame you want to review 3. Right-click and select "Copy link"

• Or use the share button in the top right
• Or just copy the URL from your browser

Step 2: Share with Claude

Paste the link in Claude Code along with your request:

Review the UX copy in this login screen:
https://www.figma.com/file/abc123/Design?node-id=123-456

Focus on:
- Button labels
- Error messages
- Form field labels

Step 3: Get Feedback

Claude will: 1. Access the Figma frame 2. Extract all text elements 3. Apply the UX Writing Skill automatically 4. Provide specific, actionable feedback

---

Method 2: Ask for Multi-Frame Analysis

Review entire user flows:

Review all UX copy in this onboarding flow:
https://www.figma.com/file/abc123/Onboarding-Flow

Check for:
- Tone consistency across all screens
- Reading level (target 7th-8th grade)
- Accessibility (screen reader compatibility)
- Button label clarity

---

Method 3: Get Rewritten Copy

Ask Claude to generate improved versions:

Here's my error state: [Figma link]

Rewrite all the copy following UX writing best practices:
- Make it more concise
- Add specific recovery steps
- Ensure screen reader accessibility
- Use empathetic tone

---

Example Workflows for Content Designers

1. Design Review (Quick Audit)

I need to review copy in this checkout flow before launch:
[Figma link to checkout screens]

Using the UX Writing Skill, audit for:
- Accessibility issues
- Sentence length (should be under 20 words)
- Button labels (should be specific, not generic)
- Error message clarity
- Consistency across screens

Provide a prioritized list of issues.

2. Voice and Tone Check

Review the tone in these empty states:
[Figma link]

Our voice is: helpful, friendly, professional
Check if the copy matches this voice and suggest improvements.

3. Accessibility Audit

Audit this form for accessibility:
[Figma link to form]

Check:
- Screen reader compatibility
- Form labels (visible, not just placeholders)
- Error messages (descriptive, actionable)
- Color contrast for text
- Plain language (7th-8th grade level)

4. Before/After Improvements

Here's my current error screen: [Figma link]

Show me:
1. What's wrong with the current copy (score it against the 4 quality standards)
2. Rewritten version with improvements
3. Explanation of what changed and why

5. Cross-Platform Consistency

Compare copy across these three platforms:
- Web: [Figma link 1]
- iOS: [Figma link 2]
- Android: [Figma link 3]

Check for:
- Terminology consistency
- Similar tone
- Character limits respected
- Platform-specific conventions followed

---

Tips for Best Results

Be Specific About What You Want

❌ Too vague:

"Review this design: [link]"

✅ Better:

"Review the error messages in this form: [link]. Check for accessibility, clarity, and actionable guidance."

Reference Multiple Frames for Context

When reviewing a flow, share links to all relevant screens:

Review this 3-step onboarding flow:
1. Welcome screen: [link]
2. Account setup: [link]
3. Preferences: [link]

Check for consistent voice and progressive disclosure of information.

Ask for Specific Frameworks

The UX Writing Skill includes several frameworks you can reference:

Use the tone adaptation framework to suggest appropriate tone for this error state: [link]

Score this against the content usability checklist: [link]

Combine with Other Requests

Review copy in this dashboard: [link]

Then create a voice chart based on the existing copy to document our current voice for the team.

---

Troubleshooting

"I don't have access to that Figma file"

Solutions: 1. Make sure the file is set to "Anyone with the link can view" 2. Check that you're signed into the same Figma account you authenticated with 3. Try copying the link again (might have been truncated)

"The MCP server is disconnected"

For Remote Server: 1. Type /mcp in Claude Code 2. Find the figma server and press Enter to reconnect 3. Re-authenticate if prompted

For Desktop Server: 1. Make sure Figma desktop app is running 2. Switch to Dev Mode (Shift + D) 3. Check that MCP server is enabled in the Inspect panel

"I can't see the MCP server section in Figma"

Solutions: 1. Update to the latest Figma desktop app version 2. Make sure you're in Dev Mode (Shift + D) 3. Check that your Figma plan includes Dev Mode access

Claude doesn't seem to use the UX Writing Skill

Solution: Explicitly mention it in your prompt:

Using the UX Writing Skill, review this design: [link]

Or ask Claude to apply specific frameworks:

Apply the four quality standards (purposeful, concise, conversational, clear) to this copy: [link]

---

Rate Limits

Be aware of Figma MCP rate limits:

Starter Plan or View/Collab seats:

• Up to 6 tool calls per month

Dev or Full seat on Professional/Organization/Enterprise:

• Per-minute rate limits (more generous)

If you hit rate limits, wait a few minutes before making additional requests.

---

Advanced Usage

Create Documentation from Designs

Review all copy in this feature: [link]

Create a content patterns document showing:
- Common patterns we use (buttons, errors, empty states)
- Voice characteristics
- Terminology conventions
- Do/don't examples

Format it as a content style guide section.

Generate Test Copy

I need placeholder copy for this wireframe: [link]

Generate realistic UX copy for all text elements following our voice:
- Helpful, professional, encouraging
- Target reading level: 8th grade
- Keep button labels under 25 characters

Localization Prep

Review this design for translation readiness: [link]

Check:
- Text expansion space (German expands 30-40%)
- Idioms or cultural references to avoid
- Hard-coded text in buttons that should be dynamic
- Character limits that might break in other languages

---

Resources

• Figma MCP Documentation: developers.figma.com/docs/figma-mcp-server
• Claude Code MCP Guide: Type /help mcp in Claude Code
• UX Writing Skill Documentation: See the main README.md

---

Feedback

Have ideas for improving this integration? Open an issue or contribute to the repository. We'd especially love to hear:

• Real-world workflows that work well
• Examples of great UX writing improvements from Figma designs
• Tips for content design teams using this integration

---

Happy designing and writing! 🎨✍️

Real-World UX Writing Improvements

This document shows actual UX text transformations with scoring against the four quality standards: Purposeful, Concise, Conversational, and Clear.

E-commerce Checkout Error

Before

"An error has occurred while processing your payment. Please try again later or contact customer support if the problem persists."

Analysis:

• Purposeful: 2/10 — Doesn't help user recover or understand next steps
• Concise: 4/10 — 18 words, vague timeframe ("later")
• Conversational: 4/10 — Robotic system-speak ("an error has occurred")
• Clear: 2/10 — What error? When is "later"? Why did it fail?

Overall: 3/10 — Poor user experience

After

"We couldn't process your payment. Check your card details and try again."

Analysis:

• Purposeful: 9/10 — Provides specific next action
• Concise: 9/10 — 11 words, direct instruction
• Conversational: 9/10 — Natural language ("we couldn't")
• Clear: 9/10 — Specific problem and solution

Overall: 9/10 — Excellent

Why it works: Users know exactly what failed (payment), likely cause (card details), and what to do (check and retry).

---

SaaS Dashboard Empty State

Before

"No data available."

Analysis:

• Purposeful: 2/10 — Doesn't explain why or guide next steps
• Concise: 10/10 — Very brief, but too brief
• Conversational: 5/10 — Cold and unhelpful
• Clear: 3/10 — Technically accurate but not helpful

Overall: 4/10 — Needs significant work

After

"No data yet. Connect your account to see insights."

Analysis:

• Purposeful: 9/10 — Explains state and provides clear CTA
• Concise: 9/10 — 9 words, includes action
• Conversational: 8/10 — Friendly "yet" implies this is temporary
• Clear: 9/10 — Tells you exactly what to do

Overall: 9/10 — Excellent

Why it works: "Yet" creates expectation of future value, CTA is specific and actionable.

---

Mobile App Permission Request

Before

"'AppName' Would Like to Access Your Location" [Allow] [Don't Allow]

Analysis:

• Purposeful: 4/10 — Doesn't explain benefit to user
• Concise: 7/10 — Adequate length but no context
• Conversational: 6/10 — Standard iOS pattern, not particularly engaging
• Clear: 5/10 — Action is clear but reason isn't

Overall: 5/10 — Adequate but could be better

After

"Enable location to find coffee shops near you" [Allow] [Not now]

Analysis:

• Purposeful: 9/10 — Clear user benefit (find shops)
• Concise: 8/10 — 7 words with value proposition
• Conversational: 9/10 — Direct, benefit-focused
• Clear: 9/10 — Exact benefit stated upfront

Overall: 9/10 — Excellent

Why it works: Leads with user benefit, not system need. "Not now" is less final than "Don't Allow."

---

Account Deletion Confirmation

Before

"Are you sure you want to delete your account? This action cannot be undone. All your data will be permanently deleted."

Analysis:

• Purposeful: 6/10 — Warns of consequences but feels heavy-handed
• Concise: 5/10 — 19 words, some redundancy ("permanently deleted")
• Conversational: 5/10 — Somewhat robotic multiple sentences
• Clear: 7/10 — Consequences are clear

Overall: 6/10 — Adequate but could be improved

After

"Delete your account? You'll lose all your data and this can't be undone."

Analysis:

• Purposeful: 8/10 — Clear warning without being preachy
• Concise: 9/10 — 13 words, no redundancy
• Conversational: 9/10 — Natural phrasing, contraction
• Clear: 9/10 — Consequences clearly stated

Overall: 9/10 — Excellent

Why it works: Question format engages user, contractions feel human, consequences clear without repetition.

---

Password Requirements

Before

"Password must contain at least 8 characters including uppercase letters, lowercase letters, numbers and special characters."

Analysis:

• Purposeful: 7/10 — Provides requirements but hard to scan
• Concise: 4/10 — 17 words in one dense sentence
• Conversational: 5/10 — List reads like technical documentation
• Clear: 6/10 — Complete info but overwhelming format

Overall: 5/10 — Adequate but not optimal

After

"Create a strong password (8+ characters) Use a mix of letters, numbers, and symbols"

Analysis:

• Purposeful: 8/10 — Explains why (strong) and what
• Concise: 9/10 — 14 words, broken into scannable lines
• Conversational: 9/10 — "Create" vs "must contain"
• Clear: 9/10 — Easy to scan and understand

Overall: 9/10 — Excellent

Why it works: Two short lines easier to scan, "strong password" explains purpose, active voice.

---

Newsletter Unsubscribe Confirmation

Before

"You have been successfully unsubscribed from our mailing list. You will no longer receive emails from us. Thank you for your participation."

Analysis:

• Purposeful: 4/10 — Overly formal for someone leaving
• Concise: 3/10 — 23 words, lots of redundancy
• Conversational: 3/10 — Corporate, stiff
• Clear: 7/10 — Message is clear but verbose

Overall: 4/10 — Needs work

After

"You're unsubscribed. You can resubscribe anytime in your settings."

Analysis:

• Purposeful: 9/10 — Confirms action, offers easy reversal
• Concise: 10/10 — 9 words, direct
• Conversational: 10/10 — Casual, respectful
• Clear: 9/10 — Simple and actionable

Overall: 9/10 — Excellent

Why it works: Respects user's decision, provides exit ramp without guilt, uses contraction.

---

File Upload Progress

Before

"File uploading... Please wait."

Analysis:

• Purposeful: 5/10 — Shows status but no time estimate
• Concise: 8/10 — Very brief
• Conversational: 5/10 — Somewhat robotic
• Clear: 6/10 — Basic info only

Overall: 6/10 — Adequate

After

"Uploading report.pdf... Almost done"

Analysis:

• Purposeful: 8/10 — Shows filename and reassuring progress
• Concise: 8/10 — 4 words plus filename
• Conversational: 9/10 — Encouraging "almost done"
• Clear: 9/10 — Specific file being uploaded

Overall: 8/10 — Good

Why it works: Filename confirms right file is uploading, "almost done" reduces anxiety.

---

Common Patterns Across These Improvements

1. Lead with specifics, not generics — "We couldn't process your payment" vs "An error occurred" 2. Show user benefit before system need — "Find coffee shops" before "access location" 3. Use contractions — "You're" feels human, "You are" feels robotic 4. Break dense text into scannable chunks — Two short lines beat one long sentence 5. Remove redundancy — "Permanently deleted" → "can't be undone" 6. Use active voice — "Create a password" vs "Password must contain" 7. Provide recovery paths — Always tell users what to do next 8. Respect user decisions — Don't guilt-trip people who opt out

Quick Self-Audit Questions

Use these to improve any UX text:

1. Can I remove any words without losing meaning? 2. Does this explain what the user needs to know right now? 3. Would I actually say this out loud to a friend? 4. Is there a specific verb I could use instead of a generic one? 5. Am I showing value before asking for something?

Accessibility Guidelines for UX Writing

Writing accessible content ensures all users—including those using assistive technology, experiencing cognitive differences, or facing situational limitations—can understand and interact with your product.

Core Principles

1. Perceivable

Users must be able to perceive the information being presented.

For UX Writers:

• Provide text alternatives for non-text content
• Don't rely on color alone to convey meaning
• Ensure sufficient color contrast (WCAG AA: 4.5:1 for body text, 3:1 for large text)
• Write clear, descriptive labels for all interactive elements

2. Operable

Users must be able to operate the interface.

For UX Writers:

• Write clear button labels that describe the action
• Provide skip links for navigation ("Skip to main content")
• Write descriptive link text (not "click here")
• Use consistent terminology for navigation

3. Understandable

Users must be able to understand the information and interface.

For UX Writers:

• Use plain language (7th-8th grade reading level)
• Keep sentences short (8-14 words for critical content)
• Define technical terms on first use
• Provide clear instructions and error messages

4. Robust

Content must work with current and future assistive technologies.

For UX Writers:

• Write proper labels for form fields
• Structure content with clear headings
• Use semantic HTML-friendly language
• Ensure error messages are programmatically associated with fields

---

Screen Reader Optimization

How Screen Readers Work

Screen readers announce content linearly, reading: 1. Element type (button, link, heading, form field) 2. Label or text content 3. State (expanded, collapsed, selected, required)

Writing for Screen Readers

Buttons

• ❌ Poor: "Submit" (context missing)
• ✅ Good: "Submit application"
• ✅ Better: "Submit job application"

Links

• ❌ Poor: "Click here to learn more"
• ❌ Poor: "Read more" (about what?)
• ✅ Good: "Learn about our privacy policy"
• ✅ Good: "View pricing details"

Form Fields

• ❌ Poor: Placeholder text as only label
• ✅ Good: Visible label + optional placeholder
• ✅ Example: Label: "Email address", Placeholder: "name@example.com"

Error Messages Screen readers read the field label + error message together, so write errors that make sense in that context.

• ❌ Poor: "Invalid" (announced as "Email address, invalid")
• ✅ Good: "Must include @" (announced as "Email address, must include @")
• ✅ Better: "Email must include @" (complete sentence)

Images and Icons

• Write meaningful alt text that conveys purpose
• ❌ Poor: "image.png"
• ❌ Poor: "icon"
• ✅ Good: "Success" (for checkmark icon)
• ✅ Good: "Error: Payment failed" (for error icon)

ARIA Labels Use ARIA labels when visual context isn't available to screen readers:

• Search button with only magnifying glass icon: aria-label="Search"
• Close button with only X icon: aria-label="Close dialog"
• Social media links with only icons: aria-label="Visit us on Twitter"

---

Cognitive Accessibility

Comprehension Research

• 8 words or fewer: 100% comprehension
• 14 words or fewer: 90% comprehension
• 25+ words: Comprehension drops significantly

Best Practices

Keep Sentences Short

• Critical instructions: 8-14 words maximum
• Error messages: 12-18 words (including solution)
• General content: 15-20 words average
• Complex explanations: Break into multiple short sentences

Use Simple Language

• Choose common words over complex ones
• ❌ "Utilize" → ✅ "Use"
• ❌ "Purchase" → ✅ "Buy"
• ❌ "Terminate" → ✅ "End"
• Avoid jargon unless your audience expects it
• Define technical terms on first use

Create Scannable Content

• Use clear headings (H1, H2, H3 hierarchy)
• Break content into short paragraphs (3-4 lines max)
• Use bulleted lists for related items
• Front-load important information

Provide Consistent Patterns

• Use the same words for the same actions
• Place elements in predictable locations
• Follow established UI patterns
• Reduce cognitive load in high-stress moments (errors, confirmations)

Reduce Memory Load

• Don't make users remember information from previous screens
• Repeat critical information when needed
• Provide context at the point of action
• Use progressive disclosure for complex flows

---

Plain Language Guidelines

Reading Level Targets

General Public

• Target: 7th-8th grade (Flesch-Kincaid)
• Sentence length: 15-20 words average
• Word choice: Common, everyday words

Professional Tools

• Target: 9th-10th grade
• Sentence length: 20-25 words maximum
• Word choice: Industry terms okay if audience expects them

Technical Products

• Target: 10th-11th grade
• Sentence length: 25 words maximum
• Word choice: Technical terms with clear definitions

Plain Language Techniques

Active Voice (85% of the time)

• ❌ Passive: "Your account was created"
• ✅ Active: "We created your account"
• ❌ Passive: "Payment will be processed"
• ✅ Active: "We'll process your payment"

Concrete Verbs

• ❌ Weak: "Make a selection"
• ✅ Strong: "Choose"
• ❌ Weak: "Provide notification"
• ✅ Strong: "Notify"

Positive Framing

• ❌ Negative: "Don't forget to save"
• ✅ Positive: "Remember to save"
• ❌ Negative: "You can't proceed without..."
• ✅ Positive: "To proceed, please..."

Avoid Idioms and Metaphors These don't translate well and confuse non-native speakers:

• ❌ "Get the ball rolling"
• ❌ "Think outside the box"
• ❌ "Hit the ground running"
• ✅ Use literal language instead

---

Multi-Modal Communication

Don't Rely on Color Alone

Bad Example:

• Red text: "Email"
• (Users with color blindness can't distinguish the error)

Good Example:

• "Error: Email must include @" + red icon
• (Text provides meaning independent of color)

Redundant Cues

Provide multiple ways to perceive important information:

Status Messages

• Color + icon + text
• Example: Green checkmark + "Success: Changes saved"

Required Fields

• Asterisk + "required" label + error on submission
• Example: "Email address " with note " Required field"

Error States

• Color + icon + error message + border
• Example: Red border + error icon + "Email must include @"

Links vs Plain Text

• Color + underline (or other visual distinction)
• Ensure 3:1 contrast ratio between link and body text

---

Forms and Input Accessibility

Labels

Always Visible

• Don't hide labels on focus
• Don't use placeholder as only label
• Keep labels adjacent to fields

Clear and Descriptive

• ❌ Poor: "Name"
• ✅ Good: "Full name"
• ✅ Better: "Full name (as it appears on your ID)"

Instructions

Provide Before Input

• Explain requirements before user types
• Keep instructions visible as user completes field

Be Specific

• ❌ Vague: "Enter valid email"
• ✅ Specific: "Email must include @"
• ✅ Example: "Email (you@example.com)"

Error Messages

Pattern: [What's wrong]. [How to fix].

• ❌ "Invalid"
• ❌ "Error"
• ✅ "Email must include @"
• ✅ "Password must be at least 8 characters"

Timing

• Inline validation: Show after user completes field
• Form-level: Show on submit, with focus moved to first error
• Real-time: Only for format requirements (password strength)

Location

• Place error message near the field (above or below)
• Ensure screen readers announce error with field label
• Maintain error message while user corrects input

---

Writing for Translation

Keep It Simple

• Short sentences translate more accurately
• Simple grammar reduces translation errors
• Common words have clearer equivalents

Avoid Culturally-Specific References

• ❌ "Home run" (baseball reference)
• ❌ "The ball is in your court" (idiom)
• ❌ "During the holidays" (varies by culture)
• ✅ Use universal concepts

Plan for Text Expansion

Text expands in translation:

• German: +30-40%
• French/Spanish: +15-20%
• Italian/Portuguese: +20-25%

Design Implications:

• Buttons: Allow for 150-200% text expansion
• Titles: Plan for 130-150% expansion
• Character limits: Test with longest likely translation

Gender-Neutral Language

• Use "they/them" for unknown subjects
• Avoid gendered job titles
• ❌ "Policeman" → ✅ "Police officer"
• ❌ "Stewardess" → ✅ "Flight attendant"
• Structure sentences to avoid gender assumptions

---

High-Stress Context Accessibility

Users experiencing stress, frustration, or urgency have reduced cognitive capacity.

Error Messages

• Be immediately clear: State the problem upfront
• Provide quick recovery: One-step solution when possible
• Avoid blame: Never use judgmental language
• Stay calm: Reassuring tone without being condescending

Time-Sensitive Actions

• Clear deadlines: Specific times, not "soon"
• Visible countdown: "5 minutes remaining"
• Obvious actions: Bold, clear CTAs

High-Stakes Decisions

• Transparent consequences: "You'll lose all data"
• Reversibility: State if action can be undone
• Easy exit: Clear "Cancel" or "Go back" options

---

Testing for Accessibility

Automated Tools

• WAVE: Web accessibility evaluation tool
• axe DevTools: Browser extension for accessibility testing
• Lighthouse: Built into Chrome DevTools

Manual Testing

Screen Reader Test

• Turn on VoiceOver (Mac) or NVDA (Windows)
• Navigate using keyboard only
• Verify all content is announced meaningfully
• Check that error messages are clear when announced

Readability Test

• Hemingway Editor: Highlights complex sentences
• Readable.com: Multiple readability scores
• Microsoft Word: Flesch-Kincaid scoring

Color Contrast Test

• WebAIM Contrast Checker
• Verify 4.5:1 for body text
• Verify 3:1 for large text and UI elements

Keyboard Navigation Test

• Unplug your mouse
• Complete all tasks using only keyboard
• Verify all interactive elements are reachable
• Check that focus order is logical

---

Quick Reference Checklist

Before Publishing Any UX Text

• [ ] All interactive elements have clear, descriptive labels
• [ ] Links describe destination ("View pricing" not "Click here")
• [ ] Error messages are specific and actionable
• [ ] Color is not the only indicator of meaning
• [ ] Text has sufficient contrast (4.5:1 minimum)
• [ ] Sentences average 15-20 words or fewer
• [ ] Reading level is appropriate for audience
• [ ] No idioms, metaphors, or cultural references
• [ ] Required fields are marked with more than just color
• [ ] Form instructions appear before input fields
• [ ] Success and error states include text, not just icons

---

Resources

WCAG Guidelines

• WCAG 2.1 Quick Reference
• Understanding WCAG Success Criteria

Testing Tools

• WAVE Web Accessibility Evaluation Tool
• Hemingway Editor
• WebAIM Contrast Checker

Plain Language

• PlainLanguage.gov
• Readable.com

Screen Readers

• VoiceOver (Mac/iOS): Built-in
• NVDA (Windows): Free download
• JAWS (Windows): Commercial

---

Remember: Accessibility isn't a feature—it's a baseline requirement. Writing accessibly makes your product better for everyone, not just users with disabilities.

Content Usability Checklist

Use this checklist to evaluate UX text quality. Rate each criterion 0-10.

Concise

Every word has a distinct job

• No filler words like "basically", "actually", "just"
• Each word adds meaning or clarity
• Can't remove words without losing meaning

High information density in minimal words

• Maximum meaning per word
• Efficient phrasing
• No redundancy

40-60 characters per line

• Optimal line length for readability
• Breaks appropriately for scanning
• Not too long (causes focus loss) or too short (causes back-and-forth eye movement)

Short sentences and paragraphs

• Less than 3-4 lines per paragraph
• Sentences vary in length but average ~15-20 words
• Broken into scannable chunks

Front-loaded with signal words

• Most important words come first
• Action words at start of sentences
• Users see key information immediately

Ideas ordered by priority

• Most critical information first
• Secondary details follow
• Nice-to-know information last

Purposeful

User goals are clear and supported

• Text helps users complete their task
• Addresses user's "why am I here?" question
• Removes barriers to action

Business goals are met

• Supports conversion, engagement, or retention
• Aligns with product objectives
• Advances organizational goals

Brand voice is reflected

• Consistent with brand personality
• Recognizable as coming from this product
• Uses appropriate tone for context

Value proposition is evident

• User benefit is clear
• Explains "what's in it for me?"
• Shows value before asking for action

Subject matter focuses on user benefit

• Written in second person ("you")
• Emphasizes outcomes, not features
• User-centered, not company-centered

Active, inviting framing

• Motivates action without being pushy
• Matches user's intention and journey stage
• Appropriate level of urgency

Conversational

Natural, spoken language

• Sounds like something you'd say aloud
• Flows naturally when read
• Not stiff or overly formal

Active voice predominates

• Subject performs the action
• Direct and energetic
• Use passive only when it's clearer (rare cases)

Connecting words included

• Prepositions present ("to", "from", "with")
• Articles included ("a", "an", "the")
• Not telegraphic or robotic

Familiar words and phrases

• Uses language your users use
• Based on user research and testing
• No unnecessary technical jargon

Personality in appropriate moments

• Voice shines through when context allows
• Not overly serious in light contexts
• Not playful in serious moments

Clear

Accurate action words

• Specific verbs that describe the action
• "Delete" not "Remove" for permanent deletion
• "Save" not "OK" for saving changes

Command forms used appropriately

• Active imperative for buttons
• Clear, direct instructions
• Action-oriented language

Plain language

• 7th grade reading level for general audience
• 10th grade for professional contexts
• Avoids complex vocabulary and sentence structures

Meaningful, descriptive titles

• Titles tell you where you are
• Not generic or vague
• Provide context and orientation

Consistent patterns and terminology

• Same word means same thing throughout
• UI patterns applied consistently
• Terminology documented in style guide

Scoring Guide

9-10: Excellent — Best practice example 7-8: Good — Minor improvements possible 5-6: Adequate — Notable issues to address 3-4: Needs work — Significant problems 0-2: Poor — Major revision required

How to Use This Checklist

1. Review individual pieces — Evaluate specific UI strings, messages, or flows 2. Audit entire experiences — Score major screens or user journeys 3. Compare options — Rate different versions to choose the best 4. Track improvements — Measure before and after edits 5. Build rationale — Use scores to explain writing decisions 6. Focus efforts — Identify lowest-scoring areas to improve first

Example Evaluation

Text: "An error occurred while processing your request. Please try again."

Concise: 6/10 — Wordy, could be "We couldn't process your request. Try again." Purposeful: 4/10 — Doesn't help user fix the problem or explain what happened Conversational: 5/10 — Somewhat robotic, "an error occurred" is system-speak Clear: 5/10 — Vague, doesn't specify what error or why

Overall: 5/10 — Adequate but needs significant improvement

Improved: "We couldn't save your changes. Check your connection and try again."

Concise: 9/10 — Brief, direct, no wasted words Purposeful: 8/10 — Suggests likely cause (connection) and next step Conversational: 9/10 — Natural, human phrasing Clear: 9/10 — Specific about what failed and what to do

Overall: 9/10 — Excellent

UX Text Patterns — Detailed Examples

This document provides extended examples of common UX text patterns applied across three different product voices: TAPP Transit (helpful, efficient, trustworthy), 'appee Social Game (playful, competitive, rewarding), and Sturgeon Club (sophisticated, exclusive, elegant).

Titles

Brand Title

Identifies the product/organization

TAPP Transit: "TAPP" 'appee: "'appee" Sturgeon Club: "The Sturgeon Club"

Content Title

Reflects what's on the screen

TAPP Transit: "Your routes", "Bus schedule", "Payment methods" 'appee: "Your photos", "Leaderboard", "Daily challenge" Sturgeon Club: "Your reservations", "Member directory", "Event calendar"

Category Title (Ambiguous Task)

Covers multiple related actions

TAPP Transit: "Trip planning", "Account settings", "Help and support" 'appee: "Profile settings", "Game stats", "Photo gallery" Sturgeon Club: "Membership benefits", "Venue access", "Concierge services"

Task Title (Single Action)

Acts as instruction for one task

TAPP Transit: "Buy a day pass", "Report a problem", "Change your email" 'appee: "Upload a photo", "Vote on photos", "Invite a friend" Sturgeon Club: "Reserve a table", "Update your preferences", "Download your invoice"

---

Buttons

Primary Actions

TAPP Transit:

• "Buy pass"
• "Track bus"
• "Plan trip"
• "Report issue"

'appee:

• "Upload photo"
• "Vote now"
• "Challenge friend"
• "Claim reward"

Sturgeon Club:

• "Reserve table"
• "View details"
• "Confirm attendance"
• "Request service"

Secondary Actions

TAPP Transit:

• "View schedule"
• "Cancel"
• "Go back"
• "Skip"

'appee:

• "See rules"
• "Maybe later"
• "Pass"
• "View profile"

Sturgeon Club:

• "Learn more"
• "Decline"
• "Return"
• "Not now"

Destructive Actions

TAPP Transit:

• "Delete payment method"
• "Cancel trip"
• "Remove favorite"

'appee:

• "Delete photo"
• "Leave game"
• "Remove friend"

Sturgeon Club:

• "Cancel reservation"
• "Remove guest"
• "Close account"

---

Links

Navigational Links

TAPP Transit:

• "See all routes"
• "View trip history"
• "Check real-time updates"

'appee:

• "Browse all challenges"
• "See your stats"
• "View friend activity"

Sturgeon Club:

• "Explore member benefits"
• "View upcoming events"
• "Access your membership card"

Contextual Links

TAPP Transit:

• "Learn about fare options"
• "Get help with passes"
• "Contact support"

'appee:

• "How scoring works"
• "Tips for better photos"
• "Report a problem"

Sturgeon Club:

• "Terms of membership"
• "Dress code requirements"
• "Concierge contacts"

---

Error Messages

Inline Errors

TAPP Transit:

• "Email must include @"
• "Card number is incomplete"
• "Pick a future date"

'appee:

• "Username already taken"
• "Photo must be under 10MB"
• "Needs at least 3 characters"

Sturgeon Club:

• "Email address required"
• "Valid phone number required"
• "Select a date"

Detour Errors

TAPP Transit: Title: "Can't buy pass" Body: "Your payment didn't go through. Check your card details and try again." Action: "Update card"

'appee: Title: "Upload failed" Body: "Your photo couldn't be uploaded. Check your connection and try again." Action: "Retry upload"

Sturgeon Club: Title: "Reservation unavailable" Body: "This time slot is no longer available. Please select another time." Action: "Choose different time"

Blocking Errors

TAPP Transit: Title: "Service temporarily unavailable" Body: "We're updating our systems and will be back online in about 15 minutes. Your saved trips and passes are safe." Action: "Check status"

'appee: Title: "Update required" Body: "You need the latest version of 'appee to continue playing. Update now to access new challenges and features." Action: "Update app"

Sturgeon Club: Title: "Membership renewal required" Body: "Your membership expired on March 15. Renew your membership to continue accessing club services." Action: "Renew membership"

---

Success Messages

Simple Confirmation

TAPP Transit:

• "Pass purchased"
• "Favorite added"
• "Route saved"
• "Email updated"

'appee:

• "Photo uploaded"
• "Vote recorded"
• "Friend added"
• "Profile saved"

Sturgeon Club:

• "Reservation confirmed"
• "Preferences updated"
• "Guest added"
• "Payment processed"

Detailed Success

TAPP Transit: Title: "Trip saved" Body: "You'll get a reminder 30 minutes before your bus arrives."

'appee: Title: "Challenge complete!" Body: "You earned 50 points. Check the leaderboard to see your ranking."

Sturgeon Club: Title: "Reservation confirmed" Body: "Table for 4 on Saturday, May 20 at 7:30 PM. You'll receive a reminder the day before."

---

Empty States

First-Use Empty State

TAPP Transit: Title: "No saved routes yet" Body: "Save your frequent trips for quick access." Action: "Plan a trip"

'appee: Title: "No photos yet" Body: "Upload your first photo to start earning points." Action: "Upload photo"

Sturgeon Club: Title: "No upcoming reservations" Body: "Reserve a table at any of our exclusive venues." Action: "Make reservation"

User-Cleared Empty State

TAPP Transit: Title: "All caught up" Body: "You've completed all your trips for today."

'appee: Title: "You're all done!" Body: "You've voted on all today's photos. New challenges arrive tomorrow."

Sturgeon Club: Title: "No pending requests" Body: "You're all set. We'll notify you when we process your reservation."

Error Empty State

TAPP Transit: Title: "No results found" Body: "Try a different search or browse all routes." Action: "See all routes"

'appee: Title: "No photos match your search" Body: "Try different keywords or browse all photos." Action: "Browse photos"

Sturgeon Club: Title: "No events match your criteria" Body: "Adjust your filters or view all upcoming events." Action: "View all events"

---

Notifications

Action-Required

TAPP Transit: Title: "Your bus is arriving" Body: "Route 42 to Downtown arrives in 2 minutes at Bay St."

'appee: Title: "New challenge available" Body: "Today's theme: Sunset. Upload by midnight to compete."

Sturgeon Club: Title: "Reservation reminder" Body: "Your reservation is tonight at 7:30 PM. Confirm or modify by 5 PM." Actions: "Confirm" | "Modify"

Passive

TAPP Transit: Title: "Service update" Body: "Route 15 is running 5 minutes late due to traffic."

'appee: Title: "You earned a badge" Body: "Weekly Warrior: Uploaded photos 7 days in a row."

Sturgeon Club: Title: "New event announced" Body: "Wine tasting on June 15. Reserve your spot before it fills."

---

Form Fields

Labels

TAPP Transit: "Email address", "Card number", "Expiration date", "Security code" 'appee: "Username", "Display name", "Bio", "Profile photo" Sturgeon Club: "Member name", "Phone number", "Dietary preferences", "Guest names"

Instructions (Helper Text)

TAPP Transit:

• "We'll send trip updates to this email"
• "This card will be saved securely for future purchases"
• "Shown on your receipts and account"

'appee:

• "Choose a unique name others will see"
• "Tell other players about yourself"
• "Upload a photo that represents you"

Sturgeon Club:

• "Required for reservation confirmations"
• "We'll contact you about events and updates"
• "Help us prepare the perfect dining experience"

Placeholder Text

TAPP Transit: "name@example.com", "4111 1111 1111 1111", "MM/YY" 'appee: "PhotoPro2024", "About me...", "Add caption" Sturgeon Club: "John Smith", "(555) 555-5555", "Guest name"

---

Controls

Toggle Switches

TAPP Transit:

• Name: "Real-time updates"
• Description: "Get notifications when your bus is arriving"

'appee:

• Name: "Push notifications"
• Description: "Get notified about new challenges and friend activity"

Sturgeon Club:

• Name: "Event reminders"
• Description: "Receive notifications about upcoming reservations and events"

Checkboxes

TAPP Transit:

• "Remember this payment method"
• "Include accessibility information"
• "Show express routes only"

'appee:

• "Make profile public"
• "Allow friend requests"
• "Share scores on leaderboard"

Sturgeon Club:

• "Send event invitations"
• "Include guests in communications"
• "Opt in to exclusive offers"

---

Instructions

Static Instructions

TAPP Transit: "Tap your card when you board and when you exit." 'appee: "Upload one photo per day to earn points." Sturgeon Club: "Present your membership card upon arrival."

On-Demand Instructions

TAPP Transit: Trigger: Help icon next to "Transfer" Content: "Switch to another bus or train at connecting stops. Your pass covers transfers within 2 hours."

'appee: Trigger: Question mark next to "Challenge rules" Content: "Upload a photo matching today's theme by midnight. Other players vote on entries. Top 10 photos earn bonus points."

Sturgeon Club: Trigger: Info icon next to "Guest policy" Content: "Members may bring up to 3 guests per visit. Guest names must be provided 24 hours in advance for evening reservations."

---

Key Differences by Voice

TAPP Transit (Helpful, Efficient, Trustworthy):

• Direct, clear, informative
• Focuses on practical information
• Anticipates user needs
• Transparent about problems

'appee (Playful, Competitive, Rewarding):

• Energetic, encouraging language
• Emphasizes achievement and competition
• Celebrates user actions
• Uses exclamation points appropriately

Sturgeon Club (Sophisticated, Exclusive, Elegant):

• Polished, refined tone
• Emphasizes service and quality
• More formal phrasing
• Sophisticated word choices

All three maintain the core UX principles: purposeful, concise, conversational (within voice), and clear.

Voice Chart Template

A voice chart helps establish consistent brand personality across all UX text. Use this template to define your product's voice.

Structure

A voice chart contains three key elements for each brand concept:

1. Concept — A core brand principle or value 2. Voice Characteristics — Adjectives describing how the concept manifests in writing 3. Examples — Concrete do/don't pairs showing the voice in action

Template

Concept 1: [Brand Principle]

Voice characteristics: [Adjective 1], [Adjective 2], [Adjective 3]

Description: [1-2 sentences explaining what this means for the writing]

Do:

• Example of text that embodies this concept
• Another example showing this voice

Don't:

• Example of what to avoid
• Counter-example that violates this voice

---

Concept 2: [Brand Principle]

Voice characteristics: [Adjective 1], [Adjective 2], [Adjective 3]

Description: [1-2 sentences explaining what this means for the writing]

Do:

• Example of text that embodies this concept
• Another example showing this voice

Don't:

• Example of what to avoid
• Counter-example that violates this voice

---

Concept 3: [Brand Principle]

Voice characteristics: [Adjective 1], [Adjective 2], [Adjective 3]

Description: [1-2 sentences explaining what this means for the writing]

Do:

• Example of text that embodies this concept
• Another example showing this voice

Don't:

• Example of what to avoid
• Counter-example that violates this voice

---

Example: TAPP Transit System

Concept 1: Helpful

Voice characteristics: Friendly, supportive, clear

Description: TAPP is a companion that helps riders navigate the transit system with confidence. We anticipate questions and provide clear guidance.

Do:

• "Your bus arrives in 5 minutes at Bay St."
• "Tap your card when you board and when you exit."

Don't:

• "Arrival: 5 min"
• "Payment required at entry and exit points."

---

Concept 2: Efficient

Voice characteristics: Concise, direct, scannable

Description: Riders are often in a hurry. We respect their time by being brief and front-loading important information.

Do:

• "Route delayed 10 minutes due to traffic"
• "Transfer at Main St for Line 3"

Don't:

• "Due to unexpected traffic conditions, your route is experiencing delays of approximately 10 minutes"
• "You can transfer to Line 3 if you get off at Main St"

---

Concept 3: Trustworthy

Voice characteristics: Honest, transparent, reliable

Description: Riders depend on TAPP to get where they need to go. We're upfront about problems and provide accurate information.

Do:

• "This route is currently unavailable. Use Route 42 instead."
• "Your payment didn't go through. Update your card to continue."

Don't:

• "Service interruption on this route."
• "Payment error. Try again."

---

Tips for Creating Your Voice Chart

1. Base it on brand values — Review mission, vision, values, and personality 2. Use 3-5 concepts — Enough to guide, not so many you can't remember 3. Be specific with examples — Show actual interface text, not abstract descriptions 4. Test against real scenarios — Apply to buttons, errors, and notifications 5. Share with your team — Voice only works if everyone uses it consistently 6. Update as you learn — Refine based on user research and team feedback

Common Voice Characteristics

Positive tones: Friendly, encouraging, optimistic, warm, enthusiastic, cheerful, supportive, welcoming, inspiring

Neutral tones: Professional, straightforward, clear, direct, informative, practical, matter-of-fact, efficient

Cautious/Serious tones: Careful, thoughtful, measured, precise, formal, reserved, respectful

Personality traits: Playful, witty, conversational, casual, technical, sophisticated, humble, confident, empowering

Choose characteristics that align with your brand and serve your users' needs in context.

Empty State Template

Use this template to guide users when content is absent and help them take action to populate the space.

Structure

[Title explaining the empty state] [Brief explanation or encouragement] [Clear call to action]

Template Types

First-Use Empty State

Purpose: Guide new users to populate content Tone: Inviting, encouraging, clear on benefit

**Title**: [What's empty]
**Body**: [Brief benefit of adding content]
**Button**: [Specific action to populate]

Example:

**Title**: No projects yet
**Body**: Create your first project to start organizing work.
**Button**: Create project

---

User-Cleared Empty State

Purpose: Confirm completion, positive reinforcement Tone: Positive, celebratory (appropriately)

**Title**: [Positive completion statement]
**Body**: [Optional: What happens next or when new content appears]

Example:

**Title**: You're all caught up
**Body**: New tasks will appear here when they're assigned to you.

---

Error/No Results Empty State

Purpose: Suggest alternatives when search/filter returns nothing Tone: Helpful, solution-focused

**Title**: [What wasn't found]
**Body**: [Suggestion to modify or alternative action]
**Button**: [Alternative action]

Example:

**Title**: No results for "vintage cameras"
**Body**: Try different keywords or browse all items.
**Button**: Browse all items

---

Empty State Checklist

Before finalizing an empty state, verify:

• [ ] Clear context — User knows what's empty and why
• [ ] Actionable — Provides specific next step
• [ ] Appropriate tone — Matches emotional context
• [ ] Value-focused — Shows benefit of taking action
• [ ] Concise — Brief enough to scan quickly
• [ ] Avoids negativity — No "nothing here" or "you have no..."

Content Patterns by Type

First-Use (Onboarding)

Pattern: "No [content] yet. [Benefit statement]. [Action]"

Examples:

• "No contacts yet. Import contacts to start messaging. Import contacts"
• "No favorites saved. Save items to find them quickly later. Browse items"
• "No team members yet. Invite people to collaborate on projects. Invite team"

User-Cleared (Completion)

Pattern: "All [done/complete/caught up]. [Optional: when more appears]"

Examples:

• "All tasks complete. New tasks appear when teammates assign them to you."
• "Inbox zero! You've read all your messages."
• "You're all set. Check back tomorrow for new recommendations."

No Results (Search/Filter)

Pattern: "No [content] match [criteria]. [Suggestion]. [Alternative]"

Examples:

• "No files match your search. Try different keywords or view all files."
• "No events this month. See upcoming events or create an event."
• "No team members match these filters. Clear filters to see all members."

Permission/Access Required

Pattern: "[Content] isn't available. [Why]. [How to get access]"

Examples:

• "Reports aren't available yet. Upgrade to Premium to access detailed analytics. View plans"
• "This folder is private. Ask the owner to share it with you."
• "Calendar events are hidden. Enable calendar sync in settings to see events."

Voice Variations

Professional/B2B Product

**Title**: No documents uploaded
**Body**: Upload files to share with your team.
**Button**: Upload document

Consumer/Friendly Product

**Title**: Nothing here yet!
**Body**: Start adding favorites to build your collection.
**Button**: Find favorites

Serious/High-Stakes Product

**Title**: No alerts
**Body**: Your systems are running normally.

Illustration Guidance

When working with designers on empty state illustrations:

First-use: Optimistic, inviting imagery (open boxes, blank canvases, starting points) User-cleared: Positive, completion imagery (checkmarks, clean spaces, celebrations) No results: Neutral, helpful imagery (search icons, magnifying glasses, directional arrows)

Common Mistakes to Avoid

❌ Negative framing: "You have no contacts" ✅ Neutral/positive: "No contacts yet"

❌ No guidance: "Empty" ✅ Actionable: "No contacts yet. Import to get started."

❌ Multiple CTAs: Three different buttons competing ✅ Single primary CTA: One clear next action

❌ Too much text: Long paragraph explaining the feature ✅ Concise: One sentence benefit, clear button

❌ Technical: "No records found in database" ✅ Human: "No projects found"

Quick Fill Template

Use this for rapid empty state drafting:

Empty state type: (First-use / User-cleared / No results / Permission) What's empty: Why it's empty: What user should do: User benefit:

Draft: Title: [What's empty] Body: [Benefit of action or what happens next] Button: [Specific action]

Example filled:

• Type: First-use
• What's empty: Saved reports
• Why: New user
• What to do: Create or save a report
• Benefit: Quick access to important data

Draft: Title: No saved reports yet Body: Save reports to access your most important data quickly. Button: Create report

Error Message Template

Use this template to write clear, actionable error messages that help users recover.

Structure

[What failed] [Why it might have failed, if known] [What to do next]

Template

Inline Error (Form Validation)

Format: Brief, immediate correction guidance

[Field requirement or constraint]

Examples:

• Email must include @
• Password needs 8+ characters
• Card number is incomplete
• Choose a future date

---

Detour Error (Recoverable Problem)

Format: Problem + Solution

**Title**: [Action that failed]
**Body**: [Brief explanation]. [Recovery instruction].
**Button**: [Specific recovery action]

Example:

**Title**: Can't save changes
**Body**: Check your internet connection and try again.
**Button**: Retry

---

Blocking Error (System Issue)

Format: Clear explanation + Timeline + Reassurance

**Title**: [What's unavailable]
**Body**: [Why it's unavailable]. [When it will be available]. [Reassurance about user data].
**Button**: [Status check or alternative action]

Example:

**Title**: Service temporarily unavailable  
**Body**: We're updating our systems and will be back in about 15 minutes. Your data is safe.
**Button**: Check status

---

Error Message Checklist

Before finalizing an error message, verify:

• [ ] Avoids blame — No "invalid," "illegal," "wrong," "error"
• [ ] Empathetic tone — Acknowledge user frustration
• [ ] Specific problem — Not generic "something went wrong"
• [ ] Clear recovery — Tell user exactly what to do
• [ ] Front-loaded — Most important info first
• [ ] Active voice — "We couldn't save" not "changes could not be saved"
• [ ] Human language — Not system codes or technical jargon

Voice Variations by Context

High-Stakes Error (Payment, Security, Data Loss)

Tone: Serious, clear, reassuring

We couldn't process your payment. Your card wasn't charged. Check your card details and try again.

Low-Stakes Error (Optional Feature, Nice-to-Have)

Tone: Light, helpful, not dramatic

Couldn't load preview. Refresh to try again.

First-Time User Error

Tone: Educational, patient

Profile photo must be under 5MB. Try a smaller file or compress your image.

Common Mistakes to Avoid

❌ Vague: "An error occurred" ✅ Specific: "We couldn't save your changes"

❌ Blaming: "Invalid email address" ✅ Guiding: "Email must include @"

❌ Technical: "ERR_CONNECTION_TIMEOUT" ✅ Human: "Connection timed out. Check your internet and try again."

❌ No solution: "Upload failed" ✅ Actionable: "Upload failed. Check your file size and try again."

❌ Passive: "Your request could not be processed" ✅ Active: "We couldn't process your request"

Quick Fill Template

Use this for rapid error message drafting:

What failed: Why (if known): What user should do:

Draft: [What failed]. [Why, if known]. [Next action].

Example filled:

• What failed: Couldn't send invite
• Why: Email bounced
• What to do: Check spelling

Draft: "Couldn't send invite. Check the email address and try again."

Onboarding Flow Template

Use this template to design clear, encouraging onboarding experiences that help users succeed quickly.

Onboarding Principles

1. Show value early — Help users succeed in their first session 2. Progressive disclosure — Don't overwhelm with all features at once 3. Optional whenever possible — Let users skip and explore 4. Celebrate small wins — Acknowledge each completed step 5. Be concise — Users want to start using the product, not read about it

Core Flow Structure

Welcome → Setup → First Success → Next Steps

Each step should answer:

• Where am I? (Progress indicator)
• What do I do here? (Clear instruction)
• Why does this matter? (Benefit to user)
• Can I skip this? (Exit option)

Template: Welcome Screen

Purpose: Orient user and set expectations

**Headline**: [Welcome + value proposition]
**Body**: [2-3 benefits, bulleted]
**Primary CTA**: [Get started action]
**Secondary CTA**: [Sign in, if applicable]

Example:

**Headline**: Welcome to TaskFlow
**Body**: 
• Organize projects with your team
• Track progress in real time  
• Never miss a deadline

**Primary CTA**: Create account
**Secondary CTA**: Sign in

---

Template: Account Setup

Purpose: Collect essential information only

**Title**: [Action-oriented title]
**Body**: [Why this information is needed]
**Fields**: [Minimum required fields]
**Primary CTA**: [Continue/Next action]
**Secondary CTA**: [Skip, if truly optional]

Example:

**Title**: Tell us about yourself
**Body**: We'll personalize your experience.

**Fields**:
- Name
- Email  
- Password

**Primary CTA**: Continue
**Secondary CTA**: I'll do this later

Best practices:

• Only ask for what you absolutely need now
• Explain why each field is required
• Use smart defaults when possible
• Allow skipping optional steps

---

Template: Feature Introduction

Purpose: Teach one feature at a time through action

**Title**: [Feature name + benefit]
**Body**: [Brief explanation, 1-2 sentences]
**Visual**: [Screenshot or illustration]
**Primary CTA**: [Action to try the feature]
**Secondary CTA**: Skip / Next
**Progress**: [X of Y steps]

Example:

**Title**: Create your first project
**Body**: Projects help you organize related tasks and collaborate with your team.

[Visual: Screenshot of project view]

**Primary CTA**: Create project
**Secondary CTA**: Skip for now
**Progress**: Step 2 of 4

Best practices:

• Show, don't tell (use visuals)
• Let users try immediately
• Keep explanations under 20 words
• Always allow skipping

---

Template: First Success / Completion

Purpose: Celebrate user's first win, encourage next action

**Title**: [Celebratory statement]
**Body**: [What they accomplished + what's possible next]
**Primary CTA**: [Next natural action]
**Secondary CTA**: [Alternative or exit to product]

Example:

**Title**: You're all set!
**Body**: You created your first project. Ready to invite your team?

**Primary CTA**: Invite team members
**Secondary CTA**: Explore on my own

Best practices:

• Use exclamation points sparingly (once per flow max)
• Make the celebration feel earned
• Suggest logical next step
• Provide exit to main product

---

Onboarding Step Checklist

For each step in your onboarding flow, verify:

• [ ] Single focus — One action or concept per step
• [ ] Clear value — User knows why this matters
• [ ] Actionable — User knows exactly what to do
• [ ] Skipable — Optional steps can be skipped
• [ ] Progress visible — User knows how many steps remain
• [ ] Concise — Body text under 30 words
• [ ] Appropriate tone — Encouraging without being patronizing

Content Patterns by Step Type

Welcome/Introduction

Pattern: "Welcome to [Product]. [Do X to achieve Y]."

Examples:

• "Welcome to Notion. Create beautiful docs, wikis, and projects."
• "Welcome to Figma. Design, prototype, and collaborate in real time."

Permission Request

Pattern: "Enable [permission] to [specific benefit]"

Examples:

• "Enable notifications to stay updated on team activity"
• "Allow camera access to scan documents instantly"

Feature Tutorial

Pattern: "[Action]. [Brief benefit]."

Examples:

• "Add your first task. Stay organized and never miss a deadline."
• "Create a workspace. Collaborate with your team in one place."

Completion

Pattern: "[Celebration]! [What's now possible]. [Optional: Next step]"

Examples:

• "You're ready to go! Start creating, or invite teammates to collaborate."
• "Setup complete! Your workspace is ready for your team."

Tone Variations

Professional/B2B

**Title**: Set up your workspace
**Body**: Add team members and create your first project.
**CTA**: Continue setup

Consumer/Casual

**Title**: Let's get you started!
**Body**: This will only take a minute.
**CTA**: Let's go

Technical/Developer

**Title**: Configure your environment
**Body**: Connect your repository to start deploying.
**CTA**: Connect repo

Multi-Screen Flow Example

Screen 1: Welcome

**Welcome to WriteRight**

Write better, faster with AI-powered editing.

• Fix grammar instantly
• Improve clarity and tone
• Write with confidence

[Get started]

Screen 2: Setup

**What brings you to WriteRight?** (2 of 4)

Select all that apply:
□ Business writing
□ Creative writing  
□ Student papers
□ Personal projects

[Continue] [Skip]

Screen 3: First Action

**Try it out** (3 of 4)

Paste any text below and watch WriteRight improve it.

[Text input box]

[Analyze my writing] [Skip]

Screen 4: Success

**Nice work!**

You improved your first piece of writing. Ready to write your next masterpiece?

[Start writing] [See tips]

Common Mistakes to Avoid

❌ Too many steps: 10+ screens before using the product ✅ Focused flow: 3-5 steps to first value

❌ Feature dump: "Here are 47 things you can do!" ✅ Progressive disclosure: One key feature at a time

❌ No skip option: Forcing users through every screen ✅ Respect choice: Skip available for optional features

❌ Passive voice: "Your account has been created" ✅ Active voice: "You created your account!"

❌ Corporate speak: "Facilitate enhanced productivity" ✅ Plain language: "Get more done"

Quick Flow Builder

Use this to draft a basic onboarding flow:

Product name: Core value (one sentence): Key features to introduce (pick 2-3): 1. 2. 3.

First user action that shows value: Celebration/success moment:

Draft flow: 1. Welcome → [Value prop] 2. Setup → [Essential info only] 3. Feature 1 → [Try it action] 4. Feature 2 → [Try it action] 5. Success → [Celebrate + next step]

Testing Your Onboarding

Questions to answer: 1. Can users complete onboarding in under 2 minutes? 2. Do users achieve something meaningful in their first session? 3. Can users skip optional steps without confusion? 4. Is the tone encouraging without being condescending? 5. Does each screen have a single, clear purpose?