Harness UX Copy

Harness UX Copy

Audit microcopy, error messages, and UI strings for voice/tone consistency, clarity, and actionability. Produces a structured report with specific rewrites and a project voice guide when none exists.

When to Use

• When reviewing a PR that adds or changes user-facing text (labels, error messages, tooltips, onboarding flows)
• When establishing or enforcing a voice/tone guide across a product
• When error messages are vague, blame the user, or lack actionable next steps
• NOT for internationalization string extraction (use harness-i18n)
• NOT for accessibility auditing of non-text elements (use harness-accessibility)
• NOT for marketing copy or landing page content outside the application

Process

Phase 1: DISCOVER -- Locate UI String Sources

1. Resolve project root. Use provided path or cwd.

2. Locate voice/tone guide. Search for VOICE.md, STYLE.md, docs/voice-guide.md, docs/tone.md, or a voice section in harness.config.json. If no guide is found, flag this as a gap and use sensible defaults (clear, concise, respectful, action-oriented).

3. Identify string sources. Scan the project for UI text using multiple strategies:

   • Component files: src/**/components/**/*.{tsx,jsx,vue,svelte} for inline text
   • String constants: src/**/strings*, src/**/messages*, src/**/copy* for centralized copy
   • i18n files: src/**/i18n/**, locales/, translations/ for translation keys
   • Error definitions: files containing throw new Error, toast.error, setError, addNotification
   • Form labels: files containing label=, placeholder=, aria-label=, helperText=

4. Determine audit scope. If --scope is provided, filter to the specified category. If triggered by a PR, scope to changed files only using git diff --name-only.

5. Build string inventory. Extract all user-facing strings with their source location, category (error, label, help, onboarding, confirmation, empty-state), and surrounding context.

6. Report discovery summary. Output the count of strings found by category and source type:

   Discovery: 142 strings found
     Errors: 23 | Labels: 48 | Help text: 31 | Onboarding: 12 | Empty states: 8 | Other: 20
     Sources: 18 components, 3 string files, 2 i18n bundles
   

---

Phase 2: AUDIT -- Evaluate Copy Quality

1. Check error messages against quality rules. Every error message must satisfy:

   • What happened: Describe the problem without technical jargon
   • Why it happened: Provide context when possible (not "An error occurred")
   • What to do next: Include an actionable recovery step
   • No blame language: Avoid "you failed to," "invalid input," "wrong password" -- prefer "we couldn't," "please check," "that password didn't match"

2. Check labels and form text. Evaluate:

   • Clarity: Can the user understand what is expected without additional context?
   • Consistency: Are similar fields labeled the same way across the app? (e.g., "Email" vs "Email address" vs "E-mail")
   • Brevity: Are labels concise without sacrificing clarity?
   • Placeholder misuse: Are placeholders being used as labels? (accessibility anti-pattern)

3. Check voice/tone alignment. Compare strings against the voice guide (or defaults):

   • Formality level: Is the tone consistent? (e.g., mixing "gonna" with "We regret to inform you")
   • Pronoun usage: Is first/second person used consistently? ("your account" vs "the account")
   • Technical jargon: Are technical terms exposed to non-technical users?
   • Emotional tone: Are error states empathetic? Are success states appropriately celebratory?

4. Check empty states and onboarding. Evaluate:

   • Do empty states explain what will appear and how to get started?
   • Do onboarding flows use progressive disclosure?
   • Are CTAs clear and specific? ("Add your first project" vs "Get started")

5. Check confirmation dialogs. Evaluate:

   • Is the consequence of the action clearly stated?
   • Are button labels specific? ("Delete project" vs "OK")
   • Is the destructive action visually distinct?

6. Classify findings by severity:

   • Error: Misleading text, blame language, missing recovery steps, accessibility violations
   • Warning: Inconsistent terminology, vague CTAs, jargon exposure
   • Info: Style preferences, minor tone adjustments, punctuation inconsistencies

---

Phase 3: GUIDE -- Produce Recommendations

1. Generate specific rewrites. For every error and warning finding, provide:

   • The current string (with file location)
   • The recommended rewrite
   • The rule that triggered the finding
   • A brief rationale

2. Produce consistency patches. When terminology is inconsistent (e.g., "Sign in" vs "Log in"), recommend a single canonical term and list all locations that need updating.

3. Generate voice guide draft. If no voice guide was found in Phase 1, produce a draft VOICE.md covering:

   • Brand voice attributes (3-5 adjectives with examples)
   • Tone spectrum (how voice changes by context: error, success, onboarding, help)
   • Word list (preferred terms and terms to avoid)
   • Punctuation and capitalization rules
   • Example patterns for common UI scenarios

4. Produce error message template. Generate a reusable template for error messages:

   [What happened]. [Why / context]. [What to do next].
   Example: "We couldn't save your changes. The file may have been modified by someone else. Try refreshing the page and saving again."
   

5. Prioritize recommendations. Order by impact: error-severity findings first, then warnings grouped by frequency (most repeated patterns first), then informational suggestions.

---

Phase 4: VALIDATE -- Verify Recommendations

1. Check rewrites preserve meaning. Verify each recommended rewrite conveys the same information as the original. Flag any rewrite that changes the semantic meaning.

2. Check i18n compatibility. If the project uses i18n:

   • Verify recommended strings do not break interpolation variables ({count}, {{name}})
   • Verify string key references remain valid
   • Flag any rewrites that would require translator review

3. Check length constraints. Verify rewrites fit within UI constraints:

   • Button labels: typically under 25 characters
   • Toast messages: typically under 100 characters
   • Form labels: typically under 40 characters
   • Flag any rewrite that significantly increases string length

4. Output structured report. Present findings in a format suitable for PR review:

   UX Copy Audit: [PASS/NEEDS_ATTENTION/FAIL]
   Strings audited: N
   Findings: E errors, W warnings, I info
   
   ERRORS:
   [UXC-ERR-001] src/components/LoginForm.tsx:42
     Current: "Invalid credentials"
     Recommended: "That email and password combination didn't match. Please try again or reset your password."
     Rule: error-missing-recovery-step
   
   WARNINGS:
   [UXC-WARN-001] Inconsistent terminology: "Sign in" (4 occurrences) vs "Log in" (2 occurrences)
     Recommendation: Standardize on "Sign in" across all 6 locations.
   

5. Verify voice guide completeness. If a voice guide was generated, confirm it covers all required sections and includes at least 3 examples per section.

---

Harness Integration

• harness skill run harness-ux-copy -- Primary command for running the UX copy audit.
• harness validate -- Run after applying recommended changes to verify project health.
• Glob -- Used to locate string sources, component files, and voice guides.
• Grep -- Used to extract inline strings, error patterns, and label attributes from source files.
• Read -- Used to read voice guides, component files, and string constant files.
• Write -- Used to generate voice guide drafts when none exists.
• emit_interaction -- Used to present findings and request confirmation on bulk terminology changes.

Success Criteria

• All user-facing strings in scope are audited
• Every error message is evaluated for what-happened, why, and what-to-do-next
• Terminology inconsistencies are identified with canonical term recommendations
• Specific rewrites are provided for every error and warning finding
• Rewrites preserve semantic meaning and i18n compatibility
• Voice guide exists (found or generated) with actionable patterns
• Report follows structured format with severity classification

Examples

Example: React Application with Vague Error Messages

Phase 1: DISCOVER
  Scanned: 34 components, 2 string files, 1 i18n bundle
  Found: 89 strings (18 errors, 32 labels, 14 help text, 25 other)
  Voice guide: not found (will generate draft)

Phase 2: AUDIT
  [UXC-ERR-001] src/components/CheckoutForm.tsx:78
    "Payment failed" -- missing context and recovery step
  [UXC-ERR-002] src/components/SignupForm.tsx:33
    "Invalid email" -- blame language, no guidance
  [UXC-WARN-001] Terminology inconsistency:
    "Shopping cart" (3 files) vs "Cart" (5 files) vs "Basket" (1 file)
  [UXC-WARN-002] src/components/EmptyOrders.tsx:12
    "No orders" -- empty state missing guidance on what to do

Phase 3: GUIDE
  Rewrite: "Payment failed" ->
    "Your payment didn't go through. Please check your card details and try again, or use a different payment method."
  Rewrite: "Invalid email" ->
    "Please enter a valid email address, like name@example.com."
  Terminology: Standardize on "Cart" (most frequent, shortest)
  Generated: VOICE.md draft with friendly-professional tone

Phase 4: VALIDATE
  All rewrites preserve original meaning: YES
  i18n interpolation variables intact: YES
  Length constraints met: 1 warning (payment rewrite exceeds toast limit, suggest truncated variant)
  Result: NEEDS_ATTENTION -- 2 errors, 2 warnings

Example: Vue.js SaaS Dashboard with Existing Voice Guide

Phase 1: DISCOVER
  Voice guide found: docs/VOICE.md (professional, empathetic, action-oriented)
  Scanned: 52 components, 4 string files
  Scope: PR diff (8 changed files, 14 new/modified strings)

Phase 2: AUDIT
  [UXC-ERR-001] src/views/Settings.vue:145
    "Error: 403 Forbidden" -- exposes HTTP status, no user context
  [UXC-WARN-001] src/views/Dashboard.vue:67
    "Click here to learn more" -- vague CTA, accessibility concern
  [UXC-INFO-001] src/components/Sidebar.vue:23
    "Organisations" -- British spelling, rest of app uses American English

Phase 3: GUIDE
  Rewrite: "Error: 403 Forbidden" ->
    "You don't have permission to change these settings. Ask your workspace admin to update your role."
  Rewrite: "Click here to learn more" ->
    "Learn how to configure integrations"
  Consistency: Standardize on American English per voice guide

Phase 4: VALIDATE
  All rewrites align with VOICE.md tone: YES
  Result: NEEDS_ATTENTION -- 1 error, 1 warning, 1 info

Example: Next.js E-commerce with i18n (next-intl)

Phase 1: DISCOVER
  i18n framework: next-intl (detected via next.config.js and messages/ directory)
  Locales: en, es, fr, de
  Scanned: messages/en.json (312 keys)
  Scope: --scope errors

Phase 2: AUDIT
  [UXC-ERR-001] messages/en.json -> errors.generic
    "Something went wrong" -- no context, no recovery
  [UXC-ERR-002] messages/en.json -> errors.network
    "Network error" -- technical, no user action
  [UXC-ERR-003] messages/en.json -> checkout.cardDeclined
    "Your card was declined" -- blame language

Phase 3: GUIDE
  Rewrite: errors.generic ->
    "Something unexpected happened on our end. Please try again, or contact support if the problem continues."
  Rewrite: errors.network ->
    "We're having trouble connecting. Please check your internet connection and try again."
  Rewrite: checkout.cardDeclined ->
    "This card couldn't be processed. Please try a different card or contact your bank."
  Note: All rewrites use {variable} interpolation compatible with next-intl

Phase 4: VALIDATE
  Interpolation variables preserved: YES (no variables in affected keys)
  Translator review needed: YES (3 keys modified, flag for es/fr/de update)
  Result: NEEDS_ATTENTION -- 3 errors requiring translator coordination

Rationalizations to Reject

Rationalization	Reality
"There's no voice guide, but the existing strings have a consistent tone — I can infer the voice from them and skip generating VOICE.md."	Inferring voice from existing strings that may themselves have quality problems is circular. The GUIDE phase must produce a VOICE.md draft when none exists. Without a written guide, the audit has no stable reference for subsequent runs.
"This error message says 'Invalid credentials' — the rewrite is obvious, so I'll apply it without waiting for confirmation."	The gates require no semantic changes and no bulk changes without confirmation. Even obvious rewrites must be presented in the structured report format with the UXC-ERR code, current string, recommendation, rule, and rationale — not applied directly.
"The {count} interpolation variable is in the original string — my rewrite restructured the sentence so the variable moved to a different position. That's still compatible."	Rewrites must preserve interpolation variables exactly as they appear. If restructuring a sentence moves a variable to a position where the resulting translation would be grammatically wrong in target locales, the rewrite is invalid. Flag it for translator review instead.
"There are 8 occurrences of 'Sign in' and 3 of 'Log in' — I'll just update all 11 to 'Sign in' since that's clearly the majority term."	Terminology standardization affecting more than 5 files requires presenting the full change list and waiting for human confirmation before recommending. The majority term is a reasonable default recommendation, but the human must approve the batch.
"This empty state just says 'No results' — that's a warning, not an error, so I can deprioritize it and skip the rewrite."	Every warning finding requires a specific rewrite, not just a note that one is needed. The GUIDE phase produces rewrites for all error and warning findings. Skipping the rewrite for any classified finding produces an incomplete report.

Gates

• No rewrite may change semantic meaning. If a recommended rewrite alters what the user understands about the situation or available actions, it is rejected. Rewrites improve clarity and tone, not content.
• No breaking i18n interpolation. Rewrites must preserve all interpolation variables exactly as they appear in the original string. A rewrite that drops {count} or renames {{userName}} is invalid.
• No applying bulk changes without confirmation. When a terminology standardization affects more than 5 files, present the change list and wait for human confirmation before recommending the batch edit.
• No generating a voice guide that contradicts an existing one. If a voice guide exists, recommendations must align with it. If the guide itself has problems, flag them separately rather than overriding.

Escalation

• When the voice guide conflicts with accessibility best practices: Flag the conflict. Accessibility requirements take precedence over voice guide preferences. Example: the guide says "use playful language for errors" but playful error messages can confuse screen reader users. Recommend a voice guide amendment.
• When terminology standardization has brand implications: If the inconsistency involves brand-specific terms (product names, feature names), do not auto-recommend. Present the variants and escalate to the product team: "Found 3 variants of the product tier name. This needs a product decision."
• When rewrites significantly increase string length: If a rewrite exceeds UI constraints and cannot be shortened without losing critical information, flag the constraint: "This error message needs more space than the current toast component allows. Consider using an inline error or expanding the toast max-width."
• When error messages require backend changes: If an error message improvement requires the backend to send more specific error codes or context, document the dependency: "Improving this message requires the API to distinguish between 'card declined' and 'card expired' -- currently both return PAYMENT_FAILED."