Skip to content

ericrisco/rsc-harness / skills/ux

Use when an app or SaaS must be easy to use: designing complete user flows, screens and every state, navigation, forms, onboarding, tables, dashboards, search or AI features, or auditing usability and accessibility. Anyone finishes the job without a manual; experts go fast. NOT the visual direction (design), NOT the words (landing-copy).

FileKindSize
SKILL.mdskill md9.3 KB
THIRD_PARTY.mdmarkdown1.6 KB
evals/cases.yamlconfig2.5 KB
references/flows.mdmarkdown7.3 KB
upstream/UPSTREAM.jsonconfig4.7 KB
upstream/ux-designer/GUIDE.mdmarkdown15.2 KB
upstream/ux-designer/LICENSEother1.0 KB
upstream/ux-designer/references/01-core-principles.mdmarkdown7.9 KB
upstream/ux-designer/references/02-laws-of-ux.mdmarkdown8.3 KB
upstream/ux-designer/references/03-accessibility.mdmarkdown10.7 KB
upstream/ux-designer/references/04-visual-design.mdmarkdown8.9 KB
upstream/ux-designer/references/05-information-architecture.mdmarkdown9.1 KB
upstream/ux-designer/references/06-interaction-design.mdmarkdown11.2 KB
upstream/ux-designer/references/07-forms-and-inputs.mdmarkdown11.4 KB
upstream/ux-designer/references/08-mobile-ux.mdmarkdown10.9 KB
upstream/ux-designer/references/09-ux-writing.mdmarkdown9.0 KB
upstream/ux-designer/references/10-user-research.mdmarkdown10.6 KB
upstream/ux-designer/references/11-design-systems.mdmarkdown13.2 KB
upstream/ux-designer/references/12a-presence-awareness.mdmarkdown10.2 KB
upstream/ux-designer/references/12b-conflict-resolution-sync.mdmarkdown15.8 KB
upstream/ux-designer/references/13a-canvas-navigation.mdmarkdown9.5 KB
upstream/ux-designer/references/13b-canvas-objects-performance.mdmarkdown14.2 KB
upstream/ux-designer/references/14-ai-ux-patterns.mdmarkdown20.9 KB
upstream/ux-designer/references/15-ethical-design.mdmarkdown13.9 KB
upstream/ux-designer/references/16-onboarding.mdmarkdown16.5 KB
upstream/ux-designer/references/17-notifications.mdmarkdown17.7 KB
upstream/ux-designer/references/18-data-visualization.mdmarkdown18.8 KB
upstream/ux-designer/references/19-search-ux.mdmarkdown19.0 KB
upstream/ux-designer/references/20-emotional-design.mdmarkdown14.5 KB
upstream/ux-designer/references/21-data-tables.mdmarkdown20.5 KB
upstream/ux-designer/references/22-performance-ux.mdmarkdown17.5 KB
upstream/ux-designer/references/23-internationalization.mdmarkdown15.4 KB
upstream/ux-designer/references/24-voice-and-multimodal.mdmarkdown15.9 KB
upstream/ux-designer/references/25a-barcode-camera-scanning.mdmarkdown21.3 KB
upstream/ux-designer/references/25b-barcode-scanner-workflows.mdmarkdown25.3 KB
upstream/ux-designer/references/25c-barcode-display.mdmarkdown17.3 KB
upstream/ux-usability-foundations/GUIDE.mdmarkdown16.0 KB
upstream/ux-usability-foundations/LICENSEother1.0 KB
upstream/ux-usability-foundations/references/anti-patterns.mdmarkdown8.3 KB
upstream/ux-usability-foundations/references/checklists.mdmarkdown6.2 KB
upstream/ux-usability-foundations/references/decision-prompts.mdmarkdown10.0 KB
upstream/ux-usability-foundations/references/principle-cards.mdmarkdown15.4 KB

upstream/ux-designer/references/09-ux-writing.md

View on GitHub
# UX Writing & Microcopy

UX writing is the practice of crafting user-facing text that helps people use digital products. Every word in an interface is designed to enhance the user experience.

---

## Contents

- What is Microcopy?
- Core Principles
- Voice and Tone
- Writing for Common UI Elements
- Form Copy
- Accessibility in Writing
- Localization Considerations
- AI Tools for UX Writing
- Testing Microcopy
- Content Design Process
- Resources
- Sources

---

## What is Microcopy?

Microcopy refers to the small bits of text throughout an interface:
- Button labels
- Error messages
- Form labels and hints
- Tooltips
- Empty states
- Confirmation messages
- Loading text
- Navigation labels
- Onboarding text

### The Impact of Microcopy

Good microcopy:
- Reduces user errors
- Increases conversion rates
- Builds trust and brand personality
- Decreases support requests
- Guides users through complex tasks

---

## Core Principles

### Clarity

Users should instantly understand what they're reading.

```
Good: "Delete this file?"
Bad: "Are you sure you wish to proceed with the deletion of the selected item?"

Good: "Sign up"
Bad: "Get started on your journey"

Good: "Saved"
Bad: "Your changes have been successfully persisted to the database"
```

### Conciseness

Use the fewest words needed to communicate clearly.

```
Good: "Password must be 8+ characters"
Bad: "Please ensure that your password contains a minimum of eight characters"

Good: "Email sent"
Bad: "Your email has been sent successfully"
```

### Usefulness

Every word should help the user accomplish their goal.

```
Good: "Enter the 6-digit code from your authenticator app"
Bad: "Enter code"

Good: "We'll email you a receipt"
Bad: "Transaction complete"
```

### Conversational (But Professional)

Write like you speak, while maintaining appropriateness.

```
Good: "Looks like that email doesn't exist. Want to create an account?"
Bad: "Error 404: User not found in database"

Good: "We couldn't find any results for 'xyz'"
Bad: "Your search query returned zero results"
```

---

## Voice and Tone

### Voice vs. Tone

**Voice** = Your brand's personality (consistent)
**Tone** = How you adapt to context (varies)

```
Voice: Friendly, helpful, professional
Tone varies:
- Onboarding: Welcoming, encouraging
- Errors: Empathetic, solution-focused
- Success: Celebratory (subtly)
- Security: Serious, trustworthy
```

### Developing Brand Voice

Document your voice characteristics:

| Attribute | We are... | We are NOT... |
|-----------|-----------|---------------|
| Friendly | Warm, approachable | Overly casual, unprofessional |
| Helpful | Clear, guiding | Condescending, verbose |
| Confident | Assured, direct | Arrogant, pushy |
| Human | Conversational, real | Robotic, corporate |

### Adapting Tone

```
Context: Error Message
Voice: Helpful
Tone: Empathetic + Solution-focused

"Something went wrong on our end. We're looking into it.
Your work has been saved—you won't lose anything."
```

---

## Writing for Common UI Elements

### Buttons

```
Good Button Labels:
- "Sign up" / "Log in" (standard actions)
- "Add to cart" / "Buy now" (specific actions)
- "Save changes" / "Save" (what happens)
- "Send message" (what it does)
- "Try free for 14 days" (value proposition)

Avoid:
- "Submit" (too generic)
- "Click here" (not descriptive, accessibility issue)
- "Yes" / "No" (require context)
- "OK" (too generic for important actions)
```

### Error Messages

```
Structure: What happened + How to fix it

Good:
"We couldn't log you in. Check your email and password and try again."

"That email is already registered. Log in or reset your password."

"Your card was declined. Try a different payment method."

Avoid:
"Error"
"Invalid credentials"
"Error 422: Unprocessable entity"
```

### Empty States

```
Components:
1. What this area is for
2. Why it's empty
3. How to fill it

Example:
"No projects yet

Projects help you organize your work. Create your first project
to get started.

[Create project]"
```

### Success Messages

```
Good:
"Password updated" ✓
"Order placed! We'll email you when it ships."
"Welcome aboard! Let's set up your workspace."

Keep it brief—user wants to move on.
Provide next steps when helpful.
```

### Loading States

```
Generic:
"Loading..."

Contextual (better):
"Finding nearby restaurants..."
"Saving your changes..."
"Connecting to server..."

Humorous (use carefully):
"Reticulating splines..."
"Convincing pixels to behave..."
```

### Confirmation Dialogs

```
Structure:
- Clear headline stating action
- Brief explanation of consequences
- Actionable button labels

Example:
"Delete this project?

This will permanently delete 'Marketing Q4' and all its files.
This can't be undone.

[Cancel] [Delete project]"

Not:
"Are you sure?"
[Yes] [No]
```

---

## Form Copy

### Labels

```
Good:
"Email address"
"Password"
"First name"

Avoid:
"Your email address"
"Enter your password"
"Please provide first name"
```

### Placeholder Text

```
Use for examples, not labels:
"you@example.com"
"555-123-4567"
"Search products..."

Don't use as the only label (disappears on focus)
```

### Help Text

```
Place below input or as tooltip:
"Password must be at least 8 characters"
"We'll only contact you about your order"
"Optional—for faster shipping estimates"
```

### Validation Messages

```
Specific and helpful:
"Enter a valid email (e.g., name@company.com)"
"Phone number must be 10 digits"
"Passwords don't match"

Not:
"Invalid input"
"Please check this field"
"Error in form"
```

---

## Accessibility in Writing

### Link Text

```
Good:
"Read our privacy policy"
"Download the report (PDF, 2.3 MB)"
"Learn more about pricing"

Avoid:
"Click here"
"Read more"
"Here" (as standalone link)
```

### Alt Text

```
Informative images:
"Bar chart showing 40% increase in sales from Q3 to Q4 2024"

Decorative images:
alt="" (empty)

Functional images (buttons/links):
"Search" (not "magnifying glass icon")
```

### Headings

```
Use logical hierarchy for screen readers:
<h1>Account Settings</h1>
  <h2>Profile</h2>
  <h2>Security</h2>
    <h3>Password</h3>
    <h3>Two-factor authentication</h3>
```

---

## Localization Considerations

### Writing for Translation

```
Avoid idioms:
"Piece of cake" → "Easy"
"Kill two birds" → "Accomplish both"
"Ball is in your court" → "Your turn to decide"

Keep text expandable (30-40% expansion typical):
English: "Settings"
German: "Einstellungen"

Avoid text in images (can't be translated)

Don't embed variables mid-sentence:
"You have 5 messages" (number placement varies by language)
→ "Messages: 5"
```

### Cultural Sensitivity

- Date formats vary (MM/DD/YYYY vs. DD/MM/YYYY)
- Color meanings differ across cultures
- Gestures and icons may have different connotations
- Humor often doesn't translate

---

## AI Tools for UX Writing

### Content Generation

**ChatGPT / Claude:**
- Brainstorm alternative phrasings
- Generate variation options
- Check tone consistency

**Writer / Jasper:**
- Brand voice enforcement
- Style guide compliance
- Terminology consistency

### Quality Checking

**Grammarly:**
- Grammar and spelling
- Clarity suggestions
- Tone detection

**Hemingway Editor:**
- Readability score
- Sentence complexity
- Passive voice detection

### Important Note

AI is a co-pilot, not a replacement. Always:
- Review and edit AI suggestions
- Ensure brand voice consistency
- Test with real users
- Consider context AI might miss

---

## Testing Microcopy

### A/B Testing

Test button text:
```
A: "Sign up free"
B: "Get started"
C: "Create account"
```

Measure: Click-through rate, completion rate

### Usability Testing

- Can users complete the task?
- Do they understand what's happening?
- Any confusion or hesitation?
- What do they expect to happen next?

### Preference Testing

"Which of these messages is clearer?"
"Which feels more appropriate for this situation?"

---

## Content Design Process

### 1. Research
- Understand user needs and language
- Analyze existing content
- Review support tickets and FAQs
- Conduct user interviews

### 2. Strategy
- Define voice and tone
- Create content guidelines
- Map user journeys
- Identify content touchpoints

### 3. Write
- Draft multiple options
- Collaborate with design
- Iterate with feedback
- Consider edge cases

### 4. Validate
- Usability testing
- A/B testing
- Accessibility review
- Stakeholder review

### 5. Maintain
- Update as product evolves
- Track metrics
- Gather ongoing feedback
- Keep guidelines current

---

## Resources

### Books
- "Microcopy: The Complete Guide" - Kinneret Yifrah
- "Strategic Writing for UX" - Torrey Podmajersky
- "Conversational Design" - Erika Hall

### Courses
- UX Content Collective - UX Writing Fundamentals
- UX Writing Hub - UX Writing Academy
- Coursera - Microcopy & UX Writing

### Communities
- UX Writing Hub (Slack)
- Content Design (Slack)
- r/UXWriting (Reddit)

---

## Sources

- [UX Writing Hub](https://uxwritinghub.com/)
- [Nielsen Norman Group - Writing for the Web](https://www.nngroup.com/topic/writing-web/)
- [Google Design - Writing](https://design.google/library/ux-writing)
- [Shopify Polaris - Voice and Tone](https://polaris.shopify.com/foundations/voice-and-tone)
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