---
name: dcode:improve-copy
description: Improve UI copy using proven frameworks (JTBD, benefit-first, error patterns). Use when a designer wants to improve button text, error messages, empty states, or audit copy in a component. Supports interactive walkthrough mode for reviewing changes one-by-one, or batch mode for quick fixes.
---

# Improve Copy

Improve UI microcopy using proven UX writing frameworks.

**For designers who think:** "This button says 'Submit'... there has to be something better."

## Frameworks Reference

### JTBD (Jobs to Be Done)
Focus on the outcome the user is hiring the product to achieve.
- "Submit" → "Get my results"
- "Sign up" → "Start saving time"
- Formula: What does the user *get*, not what they *do*

### Benefit-First
Lead with value, then the action.
- "Enable notifications" → "Never miss updates — enable notifications"
- "Enter email" → "Get weekly tips — enter your email"
- Formula: "[Benefit] — [action]"

### Action-First
Start with the verb, be direct.
- "User settings page" → "Manage your account"
- "Password reset functionality" → "Reset your password"
- Formula: "[Verb] [object]"

### Error Messages
Structure: [What happened] [Why] [What to do]
- "Error" → "Couldn't save. Connection lost. Try again."
- "Invalid input" → "Email format looks wrong. Try name@example.com"

### Empty States
Structure: "No [items] yet. [Action] to [benefit]."
- "No results" → "No projects yet. Create one to get started."
- Variants: encouraging, minimal, benefit-focused

### Confirmation Dialogs
Structure: "[Consequence]. [Question]?"
- "Are you sure?" → "This will delete all your data. Continue?"
- Be specific about what happens

### Loading States
Tell users what's happening, or build anticipation.
- "Loading..." → "Finding your files..."
- "Please wait" → "Preparing your dashboard..."
- Formula: "[Action in progress]..." or "[Benefit coming]..."

### Voice Dimensions
Calibrate tone on these spectrums:

| Dimension | Range |
|-----------|-------|
| Formal ↔ Casual | "Please submit your request" ↔ "Send it over" |
| Serious ↔ Playful | "Error occurred" ↔ "Oops, something broke" |
| Respectful ↔ Irreverent | "We appreciate your patience" ↔ "Hang tight" |
| Matter-of-fact ↔ Enthusiastic | "File uploaded" ↔ "Your file is ready to go!" |

Match your product's personality. Banking apps stay serious; creative tools can be playful.

### Contextual Tone Shifting
Same voice, different tone based on situation:

| Context | Tone | Example |
|---------|------|---------|
| Onboarding | Warm, encouraging | "Welcome! Let's get you set up." |
| Success | Celebratory but brief | "Done! Your changes are live." |
| Error | Calm, helpful | "Couldn't save. Check your connection." |
| Destructive action | Serious, clear | "This will permanently delete your data." |
| Empty state | Encouraging | "Nothing here yet—let's fix that." |

### The 4 C's
Quality checklist for any copy:

| Principle | Question to ask |
|-----------|-----------------|
| **Clear** | Would a new user understand this? |
| **Concise** | Can I say this in fewer words? |
| **Conversational** | Does this sound like a helpful human? |
| **Consistent** | Am I using the same terms everywhere? |

## Modes

### Single Suggestion Mode
User provides copy, get suggestions:
```
Input: "Submit"
Output: Table of options across frameworks
```

### Audit Mode
Scan a file or current context for copy to improve:
```
/dcode:copy -audit [file]
```

### Interactive Walkthrough
Step through each item with choices. Default for < 10 items.

### Batch Mode
Show all suggestions in a table. Use `--batch` flag or type `a` during walkthrough.

## Instructions

### 1. Determine Mode

Check the input:
- If text in quotes → Single suggestion mode
- If `-audit` flag → Audit mode
- If `-list` → Show frameworks reference
- If no input and context available → Offer to audit current file

### 2. For Single Suggestions

Present improvements across relevant frameworks:

```
"Submit" improvements:

| Framework | Suggestion | Why |
|-----------|------------|-----|
| jtbd | Get my results | Focuses on outcome |
| action-first | Send request | Clear action |
| contextual | Save changes | Matches actual behavior |

Recommendation: [best option based on context]
```

If context is unclear, ask: "What does this button do?"

### 3. For Audit Mode

#### 3a. Context Detection
If no file specified:
- Check if user has been working on a file in this session
- Ask: "I see you're working on [file]. Audit that? (y/n/other)"
- If no context: "What should I audit? (paste path or describe screen)"

#### 3b. Scan for Copy
Find UI copy in the file:
- Button/link text
- Labels and headings
- Error messages
- Empty states
- Placeholder text
- Tooltips
- Confirmation dialogs

Categorize each item by type (button, error, empty, label, etc.)

#### 3c. Choose Walkthrough or Batch
- If ≤ 10 items and no `--batch` flag → Interactive walkthrough
- If > 10 items or `--batch` flag → Batch mode
- User can switch modes anytime

### 4. Interactive Walkthrough

For each copy item:

```
────────────────────────────────────────
[1/4] Line 23: Button
────────────────────────────────────────

Current:  "Submit"
Context:  Form submission button

Suggestions:
  1. "Get started" (jtbd)
  2. "Save changes" (action-first)
  3. "Continue" (minimal)
  4. Keep as-is
  5. Custom...

Choice (1-5, s=skip, a=all, r=apply-to-similar, q=quit):
```

#### Shortcut Keys
| Key | Action |
|-----|--------|
| `1-5` | Pick suggestion |
| `s` | Skip this item |
| `a` | Show all remaining as table (exit walkthrough) |
| `r` | Apply this choice to all remaining items of same type |
| `q` | Quit audit |
| `e` | Enter custom text |
| `?` | Show help |
| `↵` | Accept first suggestion |

#### Apply-to-Similar Pattern
When user picks a suggestion and types `r`:
```
Apply "jtbd" style to all remaining buttons? (y/n)
> y

✓ Applied to 3 buttons:
  - Line 45: "Submit" → "Complete purchase"
  - Line 67: "Send" → "Send message"
  - Line 89: "OK" → "Got it"

Moving to error messages...
```

### 5. Batch Mode

Show all items in a table:

```
Copy audit for CheckoutForm.tsx:

| Line | Type | Current | Suggestion |
|------|------|---------|------------|
| 23 | button | "Submit" | "Complete purchase" |
| 31 | error | "Invalid" | "Card number looks wrong" |
| 45 | empty | "No items" | "Your cart is empty" |
| 52 | button | "Cancel" | Keep as-is |

Apply all? (y/n/review-each)
```

### 6. Summary & Apply

After walkthrough or batch review:

```
────────────────────────────────────────
Audit complete
────────────────────────────────────────

Changes:
  ✓ Line 23: "Submit" → "Complete purchase"
  ✓ Line 31: "Invalid" → "Card number looks wrong"
  · Line 45: skipped
  ✓ Line 52: "Cancel" → kept as-is

Apply to file? (y/n/preview)
```

If `preview`:
- Show diff of changes
- Confirm before applying

If `y`:
- Apply changes to file
- Report success

### 7. Power User Flags

| Flag | Behavior |
|------|----------|
| `--batch` | Skip walkthrough, show table |
| `--dry-run` | Preview only, no prompts to apply |
| `--apply` | Auto-apply first suggestion (use with caution) |
| `--framework X` | Only suggest using framework X |

## Examples

**Improve a single piece of copy:**
```
/dcode:copy "Click here to learn more"
```

**List available frameworks:**
```
/dcode:copy -list
```

**Audit current file interactively:**
```
/dcode:copy -audit
```

**Audit specific file in batch mode:**
```
/dcode:copy -audit src/components/LoginForm.tsx --batch
```

**Get JTBD suggestions only:**
```
/dcode:copy "Submit" --framework jtbd
```