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 |
references/content-usability-checklist.md
View on GitHub# Content Usability Checklist
Use this checklist to evaluate UX text quality. Rate each criterion 0-10.
## Concise
**Every word has a distinct job**
- No filler words like "basically", "actually", "just"
- Each word adds meaning or clarity
- Can't remove words without losing meaning
**High information density in minimal words**
- Maximum meaning per word
- Efficient phrasing
- No redundancy
**40-60 characters per line**
- Optimal line length for readability
- Breaks appropriately for scanning
- Not too long (causes focus loss) or too short (causes back-and-forth eye movement)
**Short sentences and paragraphs**
- Less than 3-4 lines per paragraph
- Sentences vary in length but average ~15-20 words
- Broken into scannable chunks
**Front-loaded with signal words**
- Most important words come first
- Action words at start of sentences
- Users see key information immediately
**Ideas ordered by priority**
- Most critical information first
- Secondary details follow
- Nice-to-know information last
## Purposeful
**User goals are clear and supported**
- Text helps users complete their task
- Addresses user's "why am I here?" question
- Removes barriers to action
**Business goals are met**
- Supports conversion, engagement, or retention
- Aligns with product objectives
- Advances organizational goals
**Brand voice is reflected**
- Consistent with brand personality
- Recognizable as coming from this product
- Uses appropriate tone for context
**Value proposition is evident**
- User benefit is clear
- Explains "what's in it for me?"
- Shows value before asking for action
**Subject matter focuses on user benefit**
- Written in second person ("you")
- Emphasizes outcomes, not features
- User-centered, not company-centered
**Active, inviting framing**
- Motivates action without being pushy
- Matches user's intention and journey stage
- Appropriate level of urgency
## Conversational
**Natural, spoken language**
- Sounds like something you'd say aloud
- Flows naturally when read
- Not stiff or overly formal
**Active voice predominates**
- Subject performs the action
- Direct and energetic
- Use passive only when it's clearer (rare cases)
**Connecting words included**
- Prepositions present ("to", "from", "with")
- Articles included ("a", "an", "the")
- Not telegraphic or robotic
**Familiar words and phrases**
- Uses language your users use
- Based on user research and testing
- No unnecessary technical jargon
**Personality in appropriate moments**
- Voice shines through when context allows
- Not overly serious in light contexts
- Not playful in serious moments
## Clear
**Accurate action words**
- Specific verbs that describe the action
- "Delete" not "Remove" for permanent deletion
- "Save" not "OK" for saving changes
**Command forms used appropriately**
- Active imperative for buttons
- Clear, direct instructions
- Action-oriented language
**Plain language**
- 7th grade reading level for general audience
- 10th grade for professional contexts
- Avoids complex vocabulary and sentence structures
**Meaningful, descriptive titles**
- Titles tell you where you are
- Not generic or vague
- Provide context and orientation
**Consistent patterns and terminology**
- Same word means same thing throughout
- UI patterns applied consistently
- Terminology documented in style guide
## Scoring Guide
**9-10**: Excellent — Best practice example
**7-8**: Good — Minor improvements possible
**5-6**: Adequate — Notable issues to address
**3-4**: Needs work — Significant problems
**0-2**: Poor — Major revision required
## How to Use This Checklist
1. **Review individual pieces** — Evaluate specific UI strings, messages, or flows
2. **Audit entire experiences** — Score major screens or user journeys
3. **Compare options** — Rate different versions to choose the best
4. **Track improvements** — Measure before and after edits
5. **Build rationale** — Use scores to explain writing decisions
6. **Focus efforts** — Identify lowest-scoring areas to improve first
## Example Evaluation
**Text**: "An error occurred while processing your request. Please try again."
**Concise**: 6/10 — Wordy, could be "We couldn't process your request. Try again."
**Purposeful**: 4/10 — Doesn't help user fix the problem or explain what happened
**Conversational**: 5/10 — Somewhat robotic, "an error occurred" is system-speak
**Clear**: 5/10 — Vague, doesn't specify what error or why
**Overall**: 5/10 — Adequate but needs significant improvement
**Improved**: "We couldn't save your changes. Check your connection and try again."
**Concise**: 9/10 — Brief, direct, no wasted words
**Purposeful**: 8/10 — Suggests likely cause (connection) and next step
**Conversational**: 9/10 — Natural, human phrasing
**Clear**: 9/10 — Specific about what failed and what to do
**Overall**: 9/10 — Excellent
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 |