Skip to content

cgallic/kai-cmo-harness / harness/skills-v2/ux-writing

ux-writing

Verified

Create 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.

references/voice-chart-template.md

View on GitHub
# Voice Chart Template

A voice chart helps establish consistent brand personality across all UX text. Use this template to define your product's voice.

## Structure

A voice chart contains three key elements for each brand concept:

1. **Concept** — A core brand principle or value
2. **Voice Characteristics** — Adjectives describing how the concept manifests in writing
3. **Examples** — Concrete do/don't pairs showing the voice in action

## Template

### Concept 1: [Brand Principle]

**Voice characteristics**: [Adjective 1], [Adjective 2], [Adjective 3]

**Description**: [1-2 sentences explaining what this means for the writing]

**Do**:
- Example of text that embodies this concept
- Another example showing this voice

**Don't**:
- Example of what to avoid
- Counter-example that violates this voice

---

### Concept 2: [Brand Principle]

**Voice characteristics**: [Adjective 1], [Adjective 2], [Adjective 3]

**Description**: [1-2 sentences explaining what this means for the writing]

**Do**:
- Example of text that embodies this concept
- Another example showing this voice

**Don't**:
- Example of what to avoid
- Counter-example that violates this voice

---

### Concept 3: [Brand Principle]

**Voice characteristics**: [Adjective 1], [Adjective 2], [Adjective 3]

**Description**: [1-2 sentences explaining what this means for the writing]

**Do**:
- Example of text that embodies this concept
- Another example showing this voice

**Don't**:
- Example of what to avoid
- Counter-example that violates this voice

---

## Example: TAPP Transit System

### Concept 1: Helpful

**Voice characteristics**: Friendly, supportive, clear

**Description**: TAPP is a companion that helps riders navigate the transit system with confidence. We anticipate questions and provide clear guidance.

**Do**:
- "Your bus arrives in 5 minutes at Bay St."
- "Tap your card when you board and when you exit."

**Don't**:
- "Arrival: 5 min"
- "Payment required at entry and exit points."

---

### Concept 2: Efficient

**Voice characteristics**: Concise, direct, scannable

**Description**: Riders are often in a hurry. We respect their time by being brief and front-loading important information.

**Do**:
- "Route delayed 10 minutes due to traffic"
- "Transfer at Main St for Line 3"

**Don't**:
- "Due to unexpected traffic conditions, your route is experiencing delays of approximately 10 minutes"
- "You can transfer to Line 3 if you get off at Main St"

---

### Concept 3: Trustworthy

**Voice characteristics**: Honest, transparent, reliable

**Description**: Riders depend on TAPP to get where they need to go. We're upfront about problems and provide accurate information.

**Do**:
- "This route is currently unavailable. Use Route 42 instead."
- "Your payment didn't go through. Update your card to continue."

**Don't**:
- "Service interruption on this route."
- "Payment error. Try again."

---

## Tips for Creating Your Voice Chart

1. **Base it on brand values** — Review mission, vision, values, and personality
2. **Use 3-5 concepts** — Enough to guide, not so many you can't remember
3. **Be specific with examples** — Show actual interface text, not abstract descriptions
4. **Test against real scenarios** — Apply to buttons, errors, and notifications
5. **Share with your team** — Voice only works if everyone uses it consistently
6. **Update as you learn** — Refine based on user research and team feedback

## Common Voice Characteristics

**Positive tones**: Friendly, encouraging, optimistic, warm, enthusiastic, cheerful, supportive, welcoming, inspiring

**Neutral tones**: Professional, straightforward, clear, direct, informative, practical, matter-of-fact, efficient

**Cautious/Serious tones**: Careful, thoughtful, measured, precise, formal, reserved, respectful

**Personality traits**: Playful, witty, conversational, casual, technical, sophisticated, humble, confident, empowering

Choose characteristics that align with your brand and serve your users' needs in context.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall