dcodeimprove-copy

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 [e-mail]"

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