# Complete UX Microcopy Package

**PRODUCT:**
Clarity Analytics - AI-powered analytics dashboard for e-commerce

**BRAND VOICE:**
Professional but friendly, helpful, clear, confident without being arrogant

**TARGET USERS:**
Marketing managers at e-commerce brands, moderate technical skill

---

## UNDERSTANDING UX MICROCOPY

### Why Microcopy Matters:

```
Microcopy is the UI text users interact with:
- Buttons and CTAs
- Error messages
- Empty states
- Tooltips and hints
- Form labels and placeholders
- Confirmation messages
- Onboarding text
- Loading states
- Success messages
- Navigation labels
```

### The Microcopy Principles:

```
1. CLEAR — Users understand immediately
2. CONCISE — Every word earns its place
3. HELPFUL — Guides users to success
4. HUMAN — Sounds like a person, not a robot
5. CONSISTENT — Same patterns throughout
```

### Voice and Tone Matrix:

| Situation | Tone | Example |
|-----------|------|--------|
| Success | Celebratory, warm | "You are all set!" |
| Error | Calm, helpful | "That did not work. Try..." |
| Empty state | Encouraging, guiding | "Nothing here yet. Create your first..." |
| Onboarding | Welcoming, clear | "Let us get you started" |
| Warning | Direct, serious | "This cannot be undone" |
| Loading | Patient, light | "Crunching the numbers..." |

---

## SECTION 1: BUTTON AND CTA COPY

### Primary Action Buttons:

```
Generic (Avoid)     →    Specific (Better)
─────────────────────────────────────────
Submit              →    Save Changes
Click Here          →    View Report
OK                  →    Got It
Yes                 →    Delete Account
Next                →    Continue to Payment
Send                →    Send Message
```

### Button Copy Formulas:

```
Verb + Object:
- "Create Dashboard"
- "Export Report"
- "Add Data Source"
- "Invite Team Member"

Verb + Benefit:
- "Start Free Trial"
- "Get My Insights"
- "Unlock Full Access"

First Person (increases conversion):
- "Start My Free Trial"
- "Create My Account"
- "Get My Report"
```

### Button Examples by Context:

```
**Sign Up Flow:**
- "Create Free Account"
- "Get Started Free"
- "Start My Trial"

**Upgrade/Purchase:**
- "Upgrade to Pro"
- "Start Pro Trial"
- "Unlock All Features"

**Forms:**
- "Save Changes"
- "Update Profile"
- "Submit Request"

**Destructive Actions:**
- "Delete Dashboard"
- "Remove Connection"
- "Cancel Subscription"

**Secondary Actions:**
- "Learn More"
- "See Examples"
- "Skip for Now"
- "Maybe Later"
```

---

## SECTION 2: ERROR MESSAGES

### Error Message Formula:

```
[WHAT HAPPENED] + [WHY] + [HOW TO FIX]
```

### Error Message Examples:

```
**Form Validation:**

Bad: "Invalid email"
Good: "Please enter a valid email address (example: you@company.com)"

Bad: "Password error"
Good: "Password must be at least 8 characters with one number"

Bad: "Invalid input"
Good: "Please enter a number between 1 and 100"

**Connection Errors:**

Bad: "Error 500"
Good: "Something went wrong on our end. Please try again in a few minutes."

Bad: "Connection failed"
Good: "Could not connect to your data source. Check your credentials and try again."

Bad: "Timeout"
Good: "This is taking longer than expected. Refresh to try again."

**Permission Errors:**

Bad: "Access denied"
Good: "You do not have permission to view this. Contact your admin for access."

Bad: "Unauthorized"
Good: "Your session expired. Please sign in again."

**Data Errors:**

Bad: "No data"
Good: "No data found for this date range. Try selecting different dates."

Bad: "File error"
Good: "This file type is not supported. Please upload a CSV or Excel file."
```

### Error Message Tone:

```
DO:
- Be specific about what went wrong
- Offer a clear path to fix it
- Take responsibility (our end, not yours)
- Use plain language

DO NOT:
- Blame the user
- Use technical jargon (Error 403, null reference)
- Be vague (Something went wrong)
- Use ALL CAPS or exclamation marks
- Apologize excessively
```

---

## SECTION 3: EMPTY STATES

### Empty State Formula:

```
[ACKNOWLEDGE] + [VALUE HINT] + [CLEAR CTA]
```

### Empty State Examples:

```
**No Dashboards Yet:**

Headline: "No dashboards yet"
Body: "Create your first dashboard to start seeing your data come to life."
CTA: "Create Dashboard"

**No Search Results:**

Headline: "No results for [search term]"
Body: "Try different keywords or check your filters."
CTA: "Clear Filters"

**No Data Connected:**

Headline: "Connect your first data source"
Body: "Link your Shopify, Google Analytics, or other platforms to start getting insights."
CTA: "Add Data Source"

**No Team Members:**

Headline: "You are the only one here"
Body: "Invite your team to collaborate on dashboards and share insights."
CTA: "Invite Team"

**No Notifications:**

Headline: "All caught up"
Body: "You have no new notifications. We will let you know when something needs your attention."

**No Activity:**

Headline: "No activity yet"
Body: "When your team makes changes, you will see them here."
```

### Empty State Guidelines:

```
- Always provide a next action
- Explain the value of what goes here
- Keep it encouraging, not sad
- Use illustrations sparingly
- Make the CTA specific, not "Get Started"
```

---

## SECTION 4: TOOLTIPS AND HINTS

### Tooltip Formula:

```
[WHAT IT IS/DOES] + [WHY IT MATTERS] (optional)
```

### Tooltip Examples:

```
**Feature Explanations:**

"AI Insights: Automatically surfaces patterns and anomalies in your data."

"Conversion Rate: Percentage of visitors who completed a purchase."

"LTV (Lifetime Value): Predicted total revenue from a single customer."

**Settings Explanations:**

"When enabled, you will receive daily email summaries of your key metrics."

"This controls who can view this dashboard. Admins can always access everything."

"Time zone affects how dates appear in your reports."

**Input Hints:**

"Enter the URL where your tracking pixel is installed."

"Use tags to organize dashboards. Separate multiple tags with commas."

"Optional. We will use your company name if left blank."
```

### Tooltip Guidelines:

```
- Keep under 150 characters when possible
- Do not repeat what is already obvious
- Use tooltips to educate, not to hide essential info
- Be specific, not vague
- Avoid jargon without explanation
```

---

## SECTION 5: ONBOARDING COPY

### Welcome Messages:

```
**First Login:**

"Welcome to Clarity! Let us get your first dashboard set up."

"Hey [Name], ready to see what your data can tell you?"

"You are in. Let us connect your data and start exploring."

**Progress Steps:**

Step 1: "First, connect your data source"
Step 2: "Great! Now let us create your first dashboard"
Step 3: "Almost there! Invite your team to collaborate"
Step 4: "You are all set! Explore your insights"

**Completion:**

"Nice work! Your dashboard is ready."

"All done. Your data is now flowing."

"Setup complete! Here is what you can do next..."
```

### Onboarding Tips:

```
**Feature Callouts:**

"Pro tip: Click any metric to see the breakdown by channel."

"New: AI now flags unusual changes automatically."

"Did you know? You can export any chart as an image."

**Guidance:**

"Start here: Connect your Shopify store to see sales data."

"Recommended: Set up daily email reports to stay on top of changes."
```

---

## SECTION 6: CONFIRMATION AND SUCCESS MESSAGES

### Success Messages:

```
"Dashboard saved"
"Changes saved successfully"
"Invitation sent to [email]"
"Data source connected"
"Export complete. Check your downloads."
"Report scheduled. You will receive it every Monday."
```

### Confirmation Dialogs:

```
**Delete Confirmation:**

Title: "Delete this dashboard?"
Body: "This cannot be undone. All charts and settings will be permanently removed."
Buttons: "Cancel" | "Delete Dashboard"

**Unsaved Changes:**

Title: "You have unsaved changes"
Body: "Do you want to save before leaving?"
Buttons: "Discard" | "Save Changes"

**Subscription Cancel:**

Title: "Cancel your subscription?"
Body: "You will lose access to Pro features at the end of your billing period."
Buttons: "Keep Subscription" | "Cancel Anyway"
```

### Confirmation Guidelines:

```
- Be clear about consequences
- Make the safe action obvious
- Use specific button labels (not just Yes/No)
- For destructive actions, require extra confirmation
```

---

## SECTION 7: LOADING AND WAITING STATES

### Loading Messages:

```
**Standard:**
"Loading..."
"Loading your dashboard..."

**With Progress:**
"Loading your data (50%)..."
"Almost there..."

**Branded/Playful (if fits your voice):**
"Crunching the numbers..."
"Gathering your insights..."
"Connecting the dots..."
"Teaching AI your data patterns..."

**Long Operations:**
"This might take a minute. Feel free to grab a coffee."
"Processing large dataset. We will email you when ready."
```

---

## SECTION 8: FORM LABELS AND PLACEHOLDERS

### Label Best Practices:

```
**Clear Labels:**
Label: "Work Email"
Placeholder: "you@company.com"

Label: "Password"
Placeholder: (leave empty for passwords)
Hint: "At least 8 characters"

Label: "Company Name"
Placeholder: "Acme Inc."

**Optional Fields:**
Label: "Phone Number (optional)"
or
Label: "Phone Number"
Hint: "Optional"
```

### Placeholder Guidelines:

```
DO:
- Use realistic examples
- Show format when relevant (xxx-xxx-xxxx)
- Keep it short

DO NOT:
- Use placeholder as label
- Use "Enter your..." (redundant)
- Use placeholder for critical instructions
```

---

## MICROCOPY FORMULAS

### Formula 1: Action + Object

```
"Create Dashboard"
"Export Report"
"Add Connection"
```

### Formula 2: What + Why

```
"Connect Shopify to see your sales data"
"Invite team to collaborate on dashboards"
```

### Formula 3: Situation + Solution

```
"No data yet. Connect a source to get started."
"Session expired. Sign in to continue."
```

---

## COMMON MICROCOPY MISTAKES

| Mistake | Example | Fix |
|---------|---------|-----|
| Too vague | "Error" | "Email already in use" |
| Too technical | "Error 403" | "You need permission to view this" |
| Too long | 3 sentences for a tooltip | Keep under 150 characters |
| Blaming user | "You entered wrong password" | "Password does not match" |
| Generic buttons | "OK" / "Submit" | "Save Changes" / "Send Invite" |
| Missing guidance | "No results" | "No results. Try different keywords" |

---

## UX MICROCOPY CHECKLIST

### Content:
- [ ] Clear and understandable
- [ ] Concise (every word earns its place)
- [ ] Helpful (guides user to success)
- [ ] Consistent (same patterns throughout)
- [ ] Actionable (tells user what to do)

### Tone:
- [ ] Matches brand voice
- [ ] Appropriate for situation
- [ ] Human, not robotic
- [ ] Not blaming or condescending

### Accessibility:
- [ ] Does not rely on color alone
- [ ] Makes sense without visuals
- [ ] Screen reader friendly
- [ ] Clear for non-native speakers