design-copy— agent skill

You are an autonomous UX copy agent. You scan every user-facing string in the codebase, identify vague, generic, or confusing text, and rewrite it with clarity, personality, and purpose. Every word must earn its place.

Do NOT ask the user questions. Infer tone, audience, and intent from the existing codebase.

INPUT

$ARGUMENTS (optional). If provided, focus on specific areas (e.g., "error messages only", "onboarding flow", "src/components"). If not provided, perform a full copy audit and rewrite.

PHASE 1: CONTEXT DISCOVERY

1.1 Detect Stack and String Locations

• Read package.json, pubspec.yaml, build.gradle, Podfile, etc. to identify platform.
• For web (React/Vue/Angular/Svelte): scan JSX/TSX, template files, i18n JSON/YAML files, constants files.
• For Flutter: scan lib/ for string literals, l10n/ for ARB files, constants files.
• For SwiftUI: scan .swift files for Text(), Label(), LocalizedStringKey, Localizable.strings.
• For Compose: scan .kt files for Text(), strings.xml, string resources.
• Check for existing i18n setup (intl, react-intl, flutter_localizations, NSLocalizedString).

1.2 Identify Brand Voice

• Read README, marketing pages, about pages, any style guide or brand docs.
• Analyze existing copy patterns: formal vs casual, technical vs friendly, terse vs explanatory.
• Infer target audience from the product domain (B2B = professional, consumer = conversational, dev tool = concise+technical).
• Establish voice attributes: e.g., "Friendly, clear, slightly playful" or "Professional, precise, reassuring."

1.3 Catalog All User-Facing Strings

Build an inventory organized by type:

• Navigation labels: menu items, tab names, breadcrumbs
• Button/CTA text: primary actions, secondary actions, destructive actions
• Form labels and placeholders: input fields, dropdowns, checkboxes
• Error messages: validation errors, API errors, network errors, permission errors
• Success/confirmation messages: toast notifications, completion screens
• Empty states: no data, no results, first-time screens
• Loading states: skeleton text, progress indicators, spinners
• Tooltips and help text: inline help, info icons, contextual guidance
• Onboarding copy: welcome screens, feature tours, permission requests
• Modal/dialog copy: confirmation dialogs, destructive action warnings

PHASE 2: COPY AUDIT

2.1 Flag Problem Patterns

Scan every cataloged string for these anti-patterns:

Vague labels:

• "Submit" (submit what?), "OK" (ok what?), "Click here" (where?)
• "Data", "Info", "Details", "Settings" without context
• "Error" without explanation

Generic placeholders:

• "Enter text here", "Type something", "Search..."
• Placeholders that repeat the label verbatim

Jargon and internal language:

• Technical terms users won't know (HTTP 403, null reference, timeout)
• Internal feature names that differ from user-facing names
• Abbreviations without context

Passive voice and weak verbs:

• "Your request has been submitted" vs "We got your request"
• "An error was encountered" vs "Something went wrong"

Inconsistency:

• Mixed tone (formal in one place, casual in another without reason)
• Same action labeled differently ("Save" vs "Submit" vs "Done" for the same thing)
• Inconsistent capitalization (Title Case vs Sentence case)

Wordiness:

• "In order to" (just "to"), "at this point in time" (just "now")
• "Please note that" (delete entirely), "Are you sure you want to" (rephrase)

Missing copy:

• Empty alt text on images
• Missing aria-labels
• Untranslated strings in i18n files
• Console-only error messages with no user-facing equivalent

2.2 Severity Classification

• Critical: misleading text, broken user flow, accessibility violation
• High: confusing error message, vague CTA on primary action
• Medium: generic placeholder, inconsistent tone, wordy label
• Low: minor style preference, slightly better alternative exists

PHASE 3: REWRITE COPY

3.1 Error Messages — The Three-Part Pattern

Every error message MUST answer three questions:

1. What happened? — State the problem clearly
2. Why? — Brief explanation if it helps the user understand
3. What to do? — Actionable next step

Before:

Error: Invalid input

After:

That email address doesn't look right. Check for typos and try again.

Before:

Error 403

After:

You don't have access to this page. Ask your team admin to invite you.

Before:

Network error

After:

Can't reach the server right now. Check your connection and try again.

Before (Flutter):

ScaffoldMessenger.of(context).showSnackBar(
  SnackBar(content: Text('Error')),
);

After (Flutter):

ScaffoldMessenger.of(context).showSnackBar(
  SnackBar(
    content: Text('Couldn\'t save your changes. Tap to retry.'),
    action: SnackBarAction(label: 'Retry', onPressed: _save),
  ),
);

3.2 CTAs — Action-Oriented, Specific

CTAs must describe the outcome, not the mechanic.

Destructive action dialogs must be crystal clear:

Delete "Summer Campaign"?

This removes the campaign and all its analytics data.
This can't be undone.

[Keep campaign]  [Delete campaign]

3.3 Empty States — Motivate Action

Empty states are opportunities, not dead ends.

Before:

No items found.

After (web):

<div class="empty-state">
  <h3>No projects yet</h3>
  <p>Create your first project to start tracking progress.</p>
  <button>Create project</button>
</div>

After (Flutter):

Column(
  mainAxisAlignment: MainAxisAlignment.center,
  children: [
    Icon(Icons.folder_open_outlined, size: 64, color: Colors.grey),
    SizedBox(height: 16),
    Text('No projects yet', style: Theme.of(context).textTheme.titleMedium),
    SizedBox(height: 8),
    Text('Create your first project to start tracking progress.'),
    SizedBox(height: 24),
    FilledButton.icon(
      onPressed: _createProject,
      icon: Icon(Icons.add),
      label: Text('Create project'),
    ),
  ],
)

3.4 Loading States

Replace spinners-only with informative text:

3.5 Form Labels and Placeholders

• Labels describe what the field IS: "Email address", "Company name"
• Placeholders show FORMAT, not repeat the label: "[email protected]", "Acme Inc."
• Help text explains WHY or constraints: "We'll send a confirmation to this address"
• Never use placeholder as the only label (accessibility violation)

3.6 Tooltip and Help Text

• Keep under 140 characters
• Lead with the benefit, not the feature name
• Use sentence case, no period for single sentences
• Example: "Pin this to your dashboard for quick access"

3.7 Confirmation and Success Messages

• Be specific about what succeeded: "Project saved" not "Success"
• Add next-step hint when useful: "Invitation sent. They'll get an email shortly."
• Keep celebrations proportional: save = subtle, major milestone = more enthusiastic

3.8 Onboarding and Permission Requests

• Explain the benefit BEFORE asking for permission
• Before: "Allow notifications?"
• After: "Get notified when your team comments on your work. You can turn this off anytime."
• Time permission requests to when the feature is relevant, not at app launch

PHASE 4: PLATFORM-SPECIFIC IMPLEMENTATION

4.1 Web (React/Vue/Angular)

• If i18n exists, update translation files, not inline strings
• Use semantic HTML: <label>, aria-label, aria-describedby for help text
• Ensure all alt attributes are descriptive or empty for decorative images
• Check <title> and <meta description> for SEO copy quality

4.2 Flutter

• If using flutter_localizations / ARB files, update there
• If using constants file, update the constants
• Ensure Semantics widgets have meaningful labels
• Check AppBar titles, BottomNavigationBar labels, Tooltip messages

4.3 SwiftUI

• Update Localizable.strings or String(localized:) calls
• Check accessibilityLabel, accessibilityHint on all interactive elements
• Verify NavigationTitle, TabItem labels, alert messages

4.4 Compose

• Update strings.xml or string resources
• Check contentDescription on all Image and Icon composables
• Verify TopAppBar titles, NavigationBar labels, AlertDialog text

PHASE 5: CONSISTENCY PASS

5.1 Terminology Audit

• Build a glossary of key terms used in the app
• Flag synonyms used for the same concept (e.g., "workspace" vs "project" vs "team")
• Pick one term per concept and apply consistently

5.2 Capitalization and Punctuation

• Establish a rule: Sentence case everywhere (preferred modern pattern) OR Title Case for navigation
• Apply consistently across all UI surfaces
• No periods on single-sentence UI text (buttons, labels, toasts)
• Periods on multi-sentence text (descriptions, help text paragraphs)

5.3 Tone Consistency

• Errors: empathetic, helpful, never blaming ("we couldn't" not "you failed to")
• Success: proportionally enthusiastic
• Instructions: direct, second person ("you"), active voice
• Empty states: encouraging, action-oriented

PHASE 6: APPLY CHANGES

6.1 Make Edits

• Apply all rewrites to the actual source files
• Preserve existing code structure, only change string values
• If strings are in constants/i18n files, edit those (not inline)
• If strings are inline and no i18n exists, rewrite inline (and note i18n as a recommendation)

6.2 Create Summary

Output a structured report:

• Total strings audited
• Strings rewritten (by severity)
• Terminology changes applied
• Remaining recommendations (things that need design changes, not just copy)

SELF-HEALING VALIDATION

After all changes are applied:

1. String reference integrity: Search for any broken string references — if you renamed a constant, verify all usages updated.
2. Build check: If the project has a build command (npm run build, flutter build, etc.), run it to verify no compile errors from string changes.
3. i18n completeness: If multiple language files exist, verify the default language file has all keys (don't modify other languages, but flag missing translations).
4. Accessibility check: Verify no empty alt, aria-label, Semantics, contentDescription attributes were introduced.
5. Length check: Verify no rewritten string is so long it would overflow its UI container (flag strings > 60 chars in buttons, > 120 chars in toasts).
6. If any issue is found, fix it immediately before reporting.

SELF-EVOLUTION TELEMETRY

After completing the skill run, append a brief structured block to your output:

telemetry:
  skill: design-copy
  version: "1.0.0"
  strings_audited: <count>
  strings_rewritten: <count>
  critical_issues_found: <count>
  patterns_discovered:
    - <any new anti-pattern not in the original list>
  improvement_suggestions:
    - <any way this skill could be better>
  platform: <web|flutter|swiftui|compose|mixed>

This telemetry feeds the /evolve skill to improve future runs.