---

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:

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

Contextual Tone Shifting

Same voice, different tone based on situation:

The 4 C's

Quality checklist for any copy:

Modes

Single Suggestion Mode

User provides copy, get suggestions:

CopyInput: "Submit"
Output: Table of options across frameworks

Audit Mode

Scan a file or current context for copy to improve:

Copy/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:

Copy"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:

Copy────────────────────────────────────────
[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

Apply-to-Similar Pattern

When user picks a suggestion and types r:

CopyApply "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:

CopyCopy 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:

Copy────────────────────────────────────────
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

Examples

Improve a single piece of copy:

Copy/dcode:copy "Click here to learn more"

List available frameworks:

Copy/dcode:copy -list

Audit current file interactively:

Copy/dcode:copy -audit

Audit specific file in batch mode:

Copy/dcode:copy -audit src/components/LoginForm.tsx --batch

Get JTBD suggestions only:

Copy/dcode:copy "Submit" --framework jtbd