ux-writing

by @content-designer in Development

# Install this skill:

npx skills add content-designer/ux-writing-skill

Or install specific skill: npx add-skill https://github.com/content-designer/ux-writing-skill

# Description

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.

# SKILL.md

name: ux-writing
description: 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.

UX Writing

Write clear, concise, user-centered interface copy (UX text/microcopy) for digital products and experiences. This skill provides frameworks, patterns, and best practices for creating text that helps users accomplish their goals.

Compatible with: Claude Desktop, Claude Code, and Codex (CLI and IDE extensions)

Note: This skill works with Codex CLI/IDE, not ChatGPT. ChatGPT cannot install or use skills.

When to Use This Skill

Use this skill when:
- Writing interface copy (buttons, labels, titles, messages, forms)
- Editing existing UX text for clarity and effectiveness
- Creating error messages, notifications, or success messages
- Designing conversational flows or onboarding experiences
- Establishing voice and tone for a product
- Auditing product content for consistency and usability

Core UX Writing Principles

The Four Quality Standards

Every piece of UX text should be:

Purposeful — Helps users or the business achieve goals
Concise — Uses the fewest words possible without losing meaning
Conversational — Sounds natural and human, not robotic
Clear — Unambiguous, accurate, and easy to understand

Key Best Practices

Conciseness
- Use 40-60 characters per line maximum
- Every word must have a job
- Break dense text into scannable chunks
- Front-load important information

Clarity
- Use plain language (7th grade reading level for general, 10th for professional)
- Avoid jargon, idioms, and technical terms
- Use consistent terminology throughout
- Choose meaningful, specific verbs

Conversational Tone
- Write how you speak
- Use active voice 85% of the time
- Include prepositions and articles
- Avoid robotic phrasing

User-Centered
- Focus on user benefits, not features
- Anticipate and answer user questions
- Use second-person ("you") language
- Match user's language and mental models

UX Text Patterns

Apply these common patterns for interface elements.

Titles

Purpose: Orient users to where they are
Format: Noun phrases, sentence case
Types: Brand titles, content titles, category titles, task titles
Examples: "Account settings", "Your library", "Create new post"

Buttons and Links

Purpose: Enable users to take action
Format: Active imperative verbs, sentence case
Pattern: [Verb] [object]
Examples: "Save changes", "Delete account", "View details"
Avoid: Generic labels like "OK", "Submit", "Click here"

Error Messages

Purpose: Explain problem and provide solution
Format: Empathetic, clear, actionable
Pattern: [What failed]. [Why/context]. [What to do].

Error Message Types

Validation Errors (Inline)
- Show as user completes field or on blur
- Brief, specific guidance to correct input
- Pattern: [Field] [specific requirement]
- Examples:
- "Email must include @"
- "Password must be at least 8 characters"
- "Choose a date in the future"
- Timing: Real-time or on field exit
- Location: Below or beside the field

System Errors (Modal/Banner)
- Show when backend operations fail
- Explain what happened and why
- Pattern: [Action failed]. [Likely cause]. [Recovery step].
- Examples:
- "Payment failed. Your card was declined. Try a different payment method."
- "Couldn't save changes. Connection lost. Reconnect and try again."
- "Upload failed. File is too large. Choose a file under 10MB."
- Timing: Immediately after failure
- Location: Modal dialog or prominent banner

Blocking Errors (Full-screen)
- Prevent continued use until resolved
- Clear explanation of blocker and resolution
- Pattern: [What's blocked]. [Why]. [Specific action needed].
- Examples:
- "Update required. This version is no longer supported. Update now to continue."
- "Subscription expired. Your account is paused. Renew subscription to restore access."
- "Verification needed. Confirm your email to access features. Check your inbox."
- Timing: On app launch or feature access
- Location: Full screen or large modal

Permission Errors
- Explain benefit before requesting permission
- Pattern: [User benefit]. [Permission needed].
- Examples:
- "Get notified when orders ship. Enable notifications."
- "Find nearby stores. Allow location access."
- "Back up your photos. Grant storage permission."
- Timing: When feature is first used
- Location: In context of the feature

What to Avoid
- Technical codes without explanation ("Error 403")
- Blame language ("invalid input", "illegal character")
- Robotic tone ("An error has occurred")
- Dead ends (error with no recovery path)
- Vague causes ("Something went wrong")

Success Messages

Purpose: Confirm action completion
Format: Past tense, specific, encouraging
Pattern: [Action] [result/benefit]
Examples: "Changes saved", "Email sent", "Profile updated"

Empty States

Purpose: Guide users when content is absent
Types: First-use, user-cleared, error/no results
Format: Explanation + CTA to populate
Example: "No messages yet. Start a conversation to connect with your team."

Form Fields

Labels: Clear noun phrases describing input ("Email address", "Phone number")
Instructions: Verb-first, explain why information is needed
Placeholder: Use sparingly, only for standard inputs like "[email protected]"
Helper text: Static, on-demand, or automatic based on importance

Notifications

Purpose: Deliver timely, valuable information
Types: Action-required (intrusive), Passive (less intrusive)
Format: Verb-first title + contextual description
Example: "Update required. Install the latest version to continue."

Voice and Tone

Voice (Consistent Brand Personality)

Voice is the consistent personality of the product. Establish voice using:
- Concepts: 3-5 key brand principles/values
- Voice characteristics: Descriptive adjectives for each concept
- Do/Don't examples: Concrete examples showing voice in action

See references/voice-chart-template.md for creating a voice chart.

Tone (Adaptive to Context)

Tone is how voice adapts to specific situations. While voice remains constant, tone shifts based on user context and emotional state.

Tone Variables
- Purpose: Why user is seeing this text (information, action, confirmation)
- Context: What user is trying to do (learning, completing task, recovering from error)
- Emotional state: How user likely feels (frustrated, excited, confused, cautious)
- Stakes: Impact of the action (low: changing theme, high: deleting account)

Tone Adaptation by User Emotional State

Frustrated (errors, failures, blockers)
- Empathetic and solution-focused
- Acknowledge the problem without blame
- Provide clear recovery path
- Example: "Payment failed. Your card was declined. Try a different payment method."

Confused (first use, complex features)
- Patient and explanatory
- Break down steps clearly
- Provide context and guidance
- Example: "Connect your bank to see spending insights. We'll guide you through it."

Confident (routine tasks, return visits)
- Efficient and direct
- Minimal explanation
- Quick confirmation
- Example: "Saved"

Cautious (high-stakes actions, data loss)
- Serious and transparent
- Clear consequences
- Respectful of user's decision
- Example: "Delete account? You'll lose all data and this can't be undone."

Successful (completions, achievements)
- Positive and encouraging
- Proportional to achievement
- Brief celebration
- Example: "Profile updated. Your changes are live."

Tone Adaptation by Content Type

Error messages: Empathetic, reassuring, solution-focused
- Never blame user
- Explain what happened
- Provide clear next step

Success messages: Positive, specific, encouraging
- Confirm what happened
- Proportional to action importance
- Brief and clear

Instructions: Clear, direct, helpful
- Front-load key action
- Explain why when needed
- Use simple steps

Onboarding: Inviting, encouraging, concise
- Welcome without overwhelming
- Focus on value
- Celebrate early wins

Confirmations: Serious, transparent, respectful
- Clear about consequences
- No manipulation
- Easy to back out

Empty states: Hopeful, actionable, guiding
- Explain why it's empty
- Provide clear next action
- Keep encouraging tone

Editing Process

Edit UX text in four phases:

Phase 1: Purposeful

Does text help user achieve their goal?
Does text serve business objectives?
Is value to user clear?
Are concerns anticipated and addressed?

Phase 2: Concise

Remove unnecessary words
Combine redundant information
Ensure every word earns its space
Front-load important concepts

Phase 3: Conversational

Read aloud—would you say this?
Use active voice (unless passive is clearer)
Include natural connecting words
Avoid corporate jargon

Phase 4: Clear

Use specific, accurate verbs
Maintain consistent terminology
Test readability (Hemingway Editor, Flesch-Kincaid)
Ensure unambiguous meaning

Workflow

Understand context
User goals and needs
Business objectives
Technical constraints
Emotional state of user
Draft content
Start with conversation (what would you say?)
Apply appropriate pattern
Consider voice and tone
Front-load important information
Edit iteratively
Phase 1: Purposeful
Phase 2: Concise
Phase 3: Conversational
Phase 4: Clear
Test and measure
Review with team
Test with users when possible
Measure task completion, comprehension
Iterate based on feedback

Accessibility in UX Writing

Writing accessible content ensures all users, including those using assistive technology, can understand and interact with your product.

Core Accessibility Principles

Screen Reader Optimization
- Label all interactive elements explicitly ("Submit form" not just "Submit")
- Write descriptive link text ("Read pricing details" not "Click here")
- Structure error messages to work with screen readers (error + field label read together)
- Use ARIA labels when visual context isn't sufficient

Cognitive Accessibility
- Target 8-14 words per sentence (8 words = 100% comprehension, 14 words = 90%)
- Break complex information into scannable chunks
- Use clear headings and logical hierarchy
- Provide consistent, predictable patterns

Multi-Modal Communication
- Don't rely on color alone to convey meaning
- Pair visual indicators with text ("Error: Email required" with red icon)
- Provide text alternatives for icons and images
- Ensure sufficient color contrast (WCAG AA minimum: 4.5:1)

Plain Language for All
- Target 7th-8th grade reading level for general audience
- Define technical terms when first used
- Avoid idioms, metaphors, and cultural references
- Use common, everyday words

Accessible Pattern Examples

Buttons
- ❌ Poor: "Submit" (context missing for screen readers)
- ✅ Good: "Submit application"

Links
- ❌ Poor: "Click here for more information"
- ✅ Good: "Read our privacy policy"

Error Messages
- ❌ Poor: Red text showing "Invalid"
- ✅ Good: "Error: Email must include @" (with error icon)

Form Labels
- ❌ Poor: Placeholder-only fields
- ✅ Good: Visible label + optional placeholder

UX Text Benchmarks

Use these research-backed metrics to create effective UX text.

Sentence Length Targets

By Content Type
- Buttons/CTAs: 2-4 words ideal, 6 word maximum
- Titles: 3-6 words, 40 characters maximum
- Error messages: 12-18 words (including solution)
- Instructions: 20 words maximum, 14 ideal
- Body copy: 15-20 words per sentence average
- Notifications: 10-15 words for title + body

Comprehension Rates
- 8 words or fewer: 100% user comprehension
- 14 words or fewer: 90% user comprehension
- 25 words: Maximum before significant comprehension drop

Character and Line Length

Optimal Ranges
- Line length: 40-60 characters for maximum readability
- Button labels: 15-25 characters
- Page titles: 30-50 characters
- Notification titles: 35-45 characters

Reading Level Guidelines

By Audience
- General public: 7th-8th grade (Flesch-Kincaid)
- Professional tools: 9th-10th grade
- Technical products: 10th-11th grade
- Specialized fields: 11th-12th grade (only when necessary)

Testing Tools
- Hemingway Editor: Highlights complex sentences
- Readable.com: Provides multiple readability scores
- Microsoft Word: Built-in Flesch-Kincaid scoring

Common Mistakes to Avoid

Using passive voice excessively
Generic button labels ("Submit", "OK")
Blaming users in error messages
Overly clever humor in serious contexts
Inconsistent terminology
Hidden instructions or explanations
System-oriented language vs. user language
Too many words (not concise enough)
Robotic, corporate tone
Relying on color alone for meaning
Writing inaccessible link text ("Click here")

Quick Reference

Sentence case: "Save your changes" (not "Save Your Changes")
Active imperative for buttons: "Delete account" (not "Account deletion")
User-focused: "Save time with shortcuts" (not "We offer shortcuts")
Specific verbs: "Delete" (not "Remove" when permanently deleting)
Front-loaded: "Password must be 8 characters" (not "Must be 8 characters for your password")

Resources

This skill includes:
- references/accessibility-guidelines.md: Comprehensive guide to writing accessible UX text for all users
- references/voice-chart-template.md: Template for creating a product voice chart
- references/content-usability-checklist.md: Comprehensive checklist for evaluating UX text quality
- references/patterns-detailed.md: Extended examples of UX text patterns in different voices
- examples/real-world-improvements.md: Before/after transformations with detailed analysis and scoring
- templates/error-message-template.md: Fillable template for writing effective error messages
- templates/empty-state-template.md: Guide for creating helpful empty states
- templates/onboarding-flow-template.md: Framework for designing clear onboarding experiences
- docs/claude-figma-integration.md: Guide for using this skill with Claude Code and Figma MCP
- docs/codex-figma-integration.md: Guide for using this skill with Codex CLI/IDE and Figma MCP

# README.md

UX Writing Skill for Claude & Codex

Scale content quality through AI-powered design system enforcement

🌐 View Website

An Agent Skill that enables Claude and OpenAI Codex to write and edit user-centered interface copy (UX text/microcopy) for digital products. This skill transforms AI assistants into specialized UX writing tools that apply consistent standards, patterns, and voice across your product.

The Problem

Design systems solve visual consistency, but content quality still depends on individual writers. Every error message, button label, and empty state requires manual review to ensure it's clear, concise, conversational, and purposeful. This doesn't scale.

The Solution

This Agent Skill packages UX writing expertise into a system that Claude can apply automatically. Instead of asking "make this better," you can rely on consistent, evidence-based improvements across your entire product interface.

What Makes This Different

Systems thinking, not style guides: This isn't a list of writing tips. It's a framework for evaluating and improving UX text based on four measurable quality standards.

Progressive disclosure: Reference materials are loaded only when needed, keeping Claude's context efficient while providing deep expertise on demand.

Proven patterns: Built from real-world UX writing best practices, with examples across different product voices and contexts.

Immediately actionable: Every pattern includes concrete before/after examples and scoring against quality standards.

What You Get

Core Framework

Four quality standards: Purposeful, Concise, Conversational, Clear
Common UX patterns: Buttons, errors, empty states, forms, notifications, onboarding
Editing process: Systematic approach to improving any interface text
Voice and tone guidance: Adapt content to brand personality and context
Accessibility guidelines: Write for screen readers, cognitive accessibility, and WCAG compliance
Research-backed benchmarks: Sentence length targets, comprehension rates, reading levels

Reference Materials

Accessibility guidelines: Comprehensive guide for writing inclusive, accessible UX text
Voice chart template: Establish consistent brand personality
Content usability checklist: Evaluate text quality with scoring framework
Detailed pattern examples: See how different voices apply the same patterns

Practical Tools

Real-world improvements: Before/after transformations with analysis
Fillable templates: Error messages, empty states, onboarding flows
Expanded error patterns: Validation, system, blocking, and permission errors with examples
Tone adaptation framework: Map emotional states to appropriate tone
Quick reference: Common patterns and anti-patterns

Use Cases

For content designers: Apply consistent UX writing standards across your product without memorizing every rule.

For product teams: Enable non-writers to create interface copy that follows your design system.

For design system teams: Enforce content guidelines at scale without becoming a bottleneck.

For early-stage products: Build content quality in from the start with proven patterns.

Installation

What You Need

This skill works with Claude Desktop, Claude Code, and Codex (CLI and IDE extensions). Choose the installation method that matches your setup.

Note: This skill works with Codex CLI/IDE, not ChatGPT. ChatGPT cannot install or use skills.

Quick Install (Claude Desktop)

If you're using Claude Desktop, installation is simple:

Download ux-writing-skill.zip — this contains just the skill files and documentation
Open Claude Desktop
Go to Settings → Capabilities → Skills
Click Upload skill and select ux-writing-skill.zip
Upload the ZIP file directly — do not extract it first
Start using the skill immediately!

The ZIP contains only skill-relevant files: SKILL.md plus supporting documentation in docs/, examples/, references/, and templates/.

Manual Install (Claude Code)

If you're using Claude Code, follow these steps:

Step 1: Download the Skill

Download ux-writing-skill.zip
Extract the ZIP file (double-click on Mac, right-click → Extract on Windows)

Step 2: Copy to Skills Folder

Copy the extracted folder to your Claude skills directory:

Mac/Linux: ~/.claude/skills/
Windows: %USERPROFILE%\.claude\skills\

Create the directory if it doesn't exist.

Step 3: Restart Claude Code

Quit and reopen Claude Code to activate the skill.

Verify It's Working

Try asking Claude:

Write an error message for when a payment fails

Claude will apply UX writing best practices and create a clear, empathetic error message.

Install in Codex (CLI/IDE)

If you're using Codex CLI or IDE extensions, installation is straightforward:

Step 1: Download the Skill

Download ux-writing-skill.zip
Extract the ZIP file

Step 2: Copy to Codex Skills Folder

Copy the extracted folder to your Codex skills directory:

Mac/Linux: ~/.codex/skills/
Windows: %USERPROFILE%\.codex\skills\

Create the directory if it doesn't exist.

Step 3: Restart Codex

Quit and reopen Codex (or your IDE with Codex extension) to activate the skill.

Verify It's Working

Try asking in Codex:

Write an error message for when a payment fails

Codex will apply UX writing best practices and create a clear, empathetic error message.

Alternative: Use the Built-in Skill Creator

You can also use Codex's built-in skill creator:
1. In Codex CLI or IDE, type $skill-creator
2. Provide the path to the extracted skill folder
3. Follow the prompts to install

For Teams: Project Installation

Want your whole team to use this skill automatically?

For Claude Code:
1. Copy the ux-writing folder to .claude/skills/ in your project's root directory
2. Commit it to your repository
3. When teammates pull the code, they'll automatically get the skill
4. Note: Project skills only work when Claude Code is opened in that project folder

For Codex:
1. Copy the ux-writing folder to .codex/skills/ in your project's root directory
2. Commit it to your repository
3. When teammates pull the code, they'll automatically get the skill

Figma Integration

Review and improve UX copy directly from your Figma designs!

Connect this skill to Figma through Claude Code or Codex to analyze mockups, audit copy, and suggest improvements based on UX writing best practices. Perfect for:
- Content designers reviewing flows before launch
- Product teams iterating on copy in designs
- Design QA and accessibility audits
- Cross-platform consistency checks

Quick Start with Claude Code

Connect Figma to Claude Code (one-time setup):
bash claude mcp add --transport http figma https://mcp.figma.com/mcp
Restart Claude Code and authenticate with Figma when prompted.
Share a Figma frame link with Claude:
```
Review the UX copy in this login screen:
https://www.figma.com/file/abc123/Design?node-id=123-456

Check for accessibility, clarity, and tone.
```

Get instant feedback with specific improvements based on the four quality standards.

📖 Full Claude Code setup guide: docs/claude-figma-integration.md

Quick Start with Codex

Configure Codex MCP - Add to ~/.codex/config.toml:
```toml
[features]
rmcp_client = true

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
```

Install and authenticate:
bash npm i -g @openai/codex codex mcp login figma
Restart your IDE and test with a Figma Dev Mode link.

📖 Full Codex setup guide: docs/codex-figma-integration.md

Usage Examples

Basic Usage

Write an error message for when a payment fails

Claude applies the skill automatically and generates clear, actionable error messages following best practices.

Editing Existing Copy

Review this button label: "Submit your information for processing"

Claude evaluates against the four quality standards and suggests improvements.

Creating Consistent Patterns

Create empty state copy for a task list, keeping voice consistent with:
- Purposeful, Concise, Conversational, Clear
- Professional but friendly tone

Claude applies the appropriate patterns and maintains voice consistency.

Evaluating Quality

Score this error message:
"An error occurred. Please try again later."

Claude uses the content usability checklist to provide detailed scoring and improvement suggestions.

How It Works

This skill uses model-invoked activation — Claude and Codex automatically decide when to use it based on your request. You don't need to explicitly call the skill; it activates when you:

Write or edit interface copy
Create error messages, notifications, or empty states
Work on button labels, form fields, or instructions
Review product content for consistency
Establish voice and tone guidelines

The AI loads reference materials progressively, using only what's needed for your specific task to maintain efficient context usage.

In Codex CLI/IDE, you can also explicitly invoke the skill using $ux-writing or through the /skills command.

What You'll Learn

Using this skill exposes the systematic thinking behind effective UX writing:

How to evaluate content objectively with scoring frameworks
Why certain patterns work across different product contexts
How voice stays consistent while tone adapts to situations
The difference between writing for clarity vs. writing for personality

For Content Design Teams

This skill can serve as:

Onboarding tool: New team members learn patterns faster
Quality baseline: Consistent standards across all writers
Efficiency multiplier: Generate first drafts that follow guidelines
System documentation: Reference materials that never go stale

Credits

Built by Christopher Greer, Staff Content Designer at Stripe, based on established UX writing principles from:

Content Design by Sarah Richards
Strategic Writing for UX by Torrey Podmajersky
Nicely Said by Kate Kiefer Lee and Nicole Fenton
Google Material Design writing guidelines
Years of practical application building design systems

Contributing

Contributions welcome! If you have:

Additional reference patterns
More real-world examples
Template improvements
Translations to other languages

Please open an issue or submit a pull request.

Building the Skill Package

If you're contributing or want to build the skill ZIP locally:

./build-skill.sh

This creates dist/ux-writing-skill.zip containing only the skill files (SKILL.md, docs/, examples/, references/, templates/).

The build script excludes repository files like README.md, CONTRIBUTING.md, index.html, and the demo video — these live on GitHub but aren't needed in the skill package.

License

MIT License — use this skill freely in your projects and teams.

Looking for more Agent Skills?

For Claude:
- Browse the Claude Code Skills collection
- Learn about Agent Skills architecture
- Read best practices for authoring skills

For Codex (CLI/IDE):
- Explore Codex Skills documentation
- Learn how to create custom skills
- Join the OpenAI Developer Community to discuss skills

Why This Matters

Content is infrastructure. Every button label, error message, and empty state shapes how people understand and use your product. Good UX writing shouldn't depend on having an expert review every string.

This skill makes UX writing excellence systematic, scalable, and consistent — exactly what design systems do for visual design.

Status: Production-ready • Version: 1.5.0 • Last updated: January 2026

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

⚡ Amp 🚀 Antigravity 🤖 Claude Code 🦀 Clawdbot 📝 Codex ▶️ Cursor 🤖 Droid 💎 Gemini CLI 🐙 GitHub Copilot 🪿 Goose 📊 Kilo Code 🔧 Kiro CLI 💻 OpenCode 🦘 Roo Code 🌲 Trae 🏄 Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.