cgallic/kai-cmo-harness / harness/skills-v2/ux-writing
ux-writing
VerifiedCreate user-centered, accessible interface copy (microcopy) for digital products including buttons, labels, error messages, notifications, forms, onboarding, empty states, success messages, and help text. Use when writing or editing any text that appears in apps, websites, or software interfaces, designing conversational flows, establishing voice and tone guidelines, auditing product content for consistency and usability, reviewing UI strings, or improving existing interface copy. Applies UX writing best practices based on four quality standards — purposeful, concise, conversational, and clear. Includes accessibility guidelines, research-backed benchmarks (sentence length, comprehension rates, reading levels), expanded error patterns, tone adaptation frameworks, and comprehensive reference materials.
| File | Kind | Size |
|---|---|---|
| LICENSE | other | 1.0 KB |
| SKILL.md | skill md | 3.9 KB |
| UPSTREAM.md | markdown | 1.2 KB |
| docs/figma-integration.md | markdown | 12.6 KB |
| examples/real-world-improvements.md | markdown | 7.3 KB |
| references/accessibility-guidelines.md | markdown | 11.3 KB |
| references/content-usability-checklist.md | markdown | 4.8 KB |
| references/patterns-detailed.md | markdown | 10.0 KB |
| references/ux-writing-rules.md | markdown | 15.0 KB |
| references/voice-chart-template.md | markdown | 3.9 KB |
| templates/empty-state-template.md | markdown | 5.1 KB |
| templates/error-message-template.md | markdown | 3.1 KB |
| templates/onboarding-flow-template.md | markdown | 7.1 KB |
examples/real-world-improvements.md
View on GitHub# Real-World UX Writing Improvements
This document shows actual UX text transformations with scoring against the four quality standards: Purposeful, Concise, Conversational, and Clear.
## E-commerce Checkout Error
### Before
"An error has occurred while processing your payment. Please try again later or contact customer support if the problem persists."
**Analysis:**
- **Purposeful**: 2/10 — Doesn't help user recover or understand next steps
- **Concise**: 4/10 — 18 words, vague timeframe ("later")
- **Conversational**: 4/10 — Robotic system-speak ("an error has occurred")
- **Clear**: 2/10 — What error? When is "later"? Why did it fail?
**Overall**: 3/10 — Poor user experience
### After
"We couldn't process your payment. Check your card details and try again."
**Analysis:**
- **Purposeful**: 9/10 — Provides specific next action
- **Concise**: 9/10 — 11 words, direct instruction
- **Conversational**: 9/10 — Natural language ("we couldn't")
- **Clear**: 9/10 — Specific problem and solution
**Overall**: 9/10 — Excellent
**Why it works**: Users know exactly what failed (payment), likely cause (card details), and what to do (check and retry).
---
## SaaS Dashboard Empty State
### Before
"No data available."
**Analysis:**
- **Purposeful**: 2/10 — Doesn't explain why or guide next steps
- **Concise**: 10/10 — Very brief, but too brief
- **Conversational**: 5/10 — Cold and unhelpful
- **Clear**: 3/10 — Technically accurate but not helpful
**Overall**: 4/10 — Needs significant work
### After
"No data yet. Connect your account to see insights."
**Analysis:**
- **Purposeful**: 9/10 — Explains state and provides clear CTA
- **Concise**: 9/10 — 9 words, includes action
- **Conversational**: 8/10 — Friendly "yet" implies this is temporary
- **Clear**: 9/10 — Tells you exactly what to do
**Overall**: 9/10 — Excellent
**Why it works**: "Yet" creates expectation of future value, CTA is specific and actionable.
---
## Mobile App Permission Request
### Before
"'AppName' Would Like to Access Your Location"
[Allow] [Don't Allow]
**Analysis:**
- **Purposeful**: 4/10 — Doesn't explain benefit to user
- **Concise**: 7/10 — Adequate length but no context
- **Conversational**: 6/10 — Standard iOS pattern, not particularly engaging
- **Clear**: 5/10 — Action is clear but reason isn't
**Overall**: 5/10 — Adequate but could be better
### After
"Enable location to find coffee shops near you"
[Allow] [Not now]
**Analysis:**
- **Purposeful**: 9/10 — Clear user benefit (find shops)
- **Concise**: 8/10 — 7 words with value proposition
- **Conversational**: 9/10 — Direct, benefit-focused
- **Clear**: 9/10 — Exact benefit stated upfront
**Overall**: 9/10 — Excellent
**Why it works**: Leads with user benefit, not system need. "Not now" is less final than "Don't Allow."
---
## Account Deletion Confirmation
### Before
"Are you sure you want to delete your account? This action cannot be undone. All your data will be permanently deleted."
**Analysis:**
- **Purposeful**: 6/10 — Warns of consequences but feels heavy-handed
- **Concise**: 5/10 — 19 words, some redundancy ("permanently deleted")
- **Conversational**: 5/10 — Somewhat robotic multiple sentences
- **Clear**: 7/10 — Consequences are clear
**Overall**: 6/10 — Adequate but could be improved
### After
"Delete your account? You'll lose all your data and this can't be undone."
**Analysis:**
- **Purposeful**: 8/10 — Clear warning without being preachy
- **Concise**: 9/10 — 13 words, no redundancy
- **Conversational**: 9/10 — Natural phrasing, contraction
- **Clear**: 9/10 — Consequences clearly stated
**Overall**: 9/10 — Excellent
**Why it works**: Question format engages user, contractions feel human, consequences clear without repetition.
---
## Password Requirements
### Before
"Password must contain at least 8 characters including uppercase letters, lowercase letters, numbers and special characters."
**Analysis:**
- **Purposeful**: 7/10 — Provides requirements but hard to scan
- **Concise**: 4/10 — 17 words in one dense sentence
- **Conversational**: 5/10 — List reads like technical documentation
- **Clear**: 6/10 — Complete info but overwhelming format
**Overall**: 5/10 — Adequate but not optimal
### After
"Create a strong password (8+ characters)
Use a mix of letters, numbers, and symbols"
**Analysis:**
- **Purposeful**: 8/10 — Explains why (strong) and what
- **Concise**: 9/10 — 14 words, broken into scannable lines
- **Conversational**: 9/10 — "Create" vs "must contain"
- **Clear**: 9/10 — Easy to scan and understand
**Overall**: 9/10 — Excellent
**Why it works**: Two short lines easier to scan, "strong password" explains purpose, active voice.
---
## Newsletter Unsubscribe Confirmation
### Before
"You have been successfully unsubscribed from our mailing list. You will no longer receive emails from us. Thank you for your participation."
**Analysis:**
- **Purposeful**: 4/10 — Overly formal for someone leaving
- **Concise**: 3/10 — 23 words, lots of redundancy
- **Conversational**: 3/10 — Corporate, stiff
- **Clear**: 7/10 — Message is clear but verbose
**Overall**: 4/10 — Needs work
### After
"You're unsubscribed. You can resubscribe anytime in your settings."
**Analysis:**
- **Purposeful**: 9/10 — Confirms action, offers easy reversal
- **Concise**: 10/10 — 9 words, direct
- **Conversational**: 10/10 — Casual, respectful
- **Clear**: 9/10 — Simple and actionable
**Overall**: 9/10 — Excellent
**Why it works**: Respects user's decision, provides exit ramp without guilt, uses contraction.
---
## File Upload Progress
### Before
"File uploading... Please wait."
**Analysis:**
- **Purposeful**: 5/10 — Shows status but no time estimate
- **Concise**: 8/10 — Very brief
- **Conversational**: 5/10 — Somewhat robotic
- **Clear**: 6/10 — Basic info only
**Overall**: 6/10 — Adequate
### After
"Uploading report.pdf... Almost done"
**Analysis:**
- **Purposeful**: 8/10 — Shows filename and reassuring progress
- **Concise**: 8/10 — 4 words plus filename
- **Conversational**: 9/10 — Encouraging "almost done"
- **Clear**: 9/10 — Specific file being uploaded
**Overall**: 8/10 — Good
**Why it works**: Filename confirms right file is uploading, "almost done" reduces anxiety.
---
## Common Patterns Across These Improvements
1. **Lead with specifics, not generics** — "We couldn't process your payment" vs "An error occurred"
2. **Show user benefit before system need** — "Find coffee shops" before "access location"
3. **Use contractions** — "You're" feels human, "You are" feels robotic
4. **Break dense text into scannable chunks** — Two short lines beat one long sentence
5. **Remove redundancy** — "Permanently deleted" → "can't be undone"
6. **Use active voice** — "Create a password" vs "Password must contain"
7. **Provide recovery paths** — Always tell users what to do next
8. **Respect user decisions** — Don't guilt-trip people who opt out
## Quick Self-Audit Questions
Use these to improve any UX text:
1. **Can I remove any words without losing meaning?**
2. **Does this explain what the user needs to know right now?**
3. **Would I actually say this out loud to a friend?**
4. **Is there a specific verb I could use instead of a generic one?**
5. **Am I showing value before asking for something?**
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |