cgallic/kai-cmo-harness / harness/skills/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 | 15.0 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/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 |
templates/empty-state-template.md
View on GitHub# Empty State Template
Use this template to guide users when content is absent and help them take action to populate the space.
## Structure
```
[Title explaining the empty state] [Brief explanation or encouragement] [Clear call to action]
```
## Template Types
### First-Use Empty State
**Purpose**: Guide new users to populate content
**Tone**: Inviting, encouraging, clear on benefit
```
**Title**: [What's empty]
**Body**: [Brief benefit of adding content]
**Button**: [Specific action to populate]
```
**Example:**
```
**Title**: No projects yet
**Body**: Create your first project to start organizing work.
**Button**: Create project
```
---
### User-Cleared Empty State
**Purpose**: Confirm completion, positive reinforcement
**Tone**: Positive, celebratory (appropriately)
```
**Title**: [Positive completion statement]
**Body**: [Optional: What happens next or when new content appears]
```
**Example:**
```
**Title**: You're all caught up
**Body**: New tasks will appear here when they're assigned to you.
```
---
### Error/No Results Empty State
**Purpose**: Suggest alternatives when search/filter returns nothing
**Tone**: Helpful, solution-focused
```
**Title**: [What wasn't found]
**Body**: [Suggestion to modify or alternative action]
**Button**: [Alternative action]
```
**Example:**
```
**Title**: No results for "vintage cameras"
**Body**: Try different keywords or browse all items.
**Button**: Browse all items
```
---
## Empty State Checklist
Before finalizing an empty state, verify:
- [ ] **Clear context** — User knows what's empty and why
- [ ] **Actionable** — Provides specific next step
- [ ] **Appropriate tone** — Matches emotional context
- [ ] **Value-focused** — Shows benefit of taking action
- [ ] **Concise** — Brief enough to scan quickly
- [ ] **Avoids negativity** — No "nothing here" or "you have no..."
## Content Patterns by Type
### First-Use (Onboarding)
**Pattern**: "No [content] yet. [Benefit statement]. [Action]"
Examples:
- "No contacts yet. Import contacts to start messaging. **Import contacts**"
- "No favorites saved. Save items to find them quickly later. **Browse items**"
- "No team members yet. Invite people to collaborate on projects. **Invite team**"
### User-Cleared (Completion)
**Pattern**: "All [done/complete/caught up]. [Optional: when more appears]"
Examples:
- "All tasks complete. New tasks appear when teammates assign them to you."
- "Inbox zero! You've read all your messages."
- "You're all set. Check back tomorrow for new recommendations."
### No Results (Search/Filter)
**Pattern**: "No [content] match [criteria]. [Suggestion]. [Alternative]"
Examples:
- "No files match your search. Try different keywords or **view all files**."
- "No events this month. **See upcoming events** or **create an event**."
- "No team members match these filters. **Clear filters** to see all members."
### Permission/Access Required
**Pattern**: "[Content] isn't available. [Why]. [How to get access]"
Examples:
- "Reports aren't available yet. Upgrade to Premium to access detailed analytics. **View plans**"
- "This folder is private. Ask the owner to share it with you."
- "Calendar events are hidden. Enable calendar sync in **settings** to see events."
## Voice Variations
### Professional/B2B Product
```
**Title**: No documents uploaded
**Body**: Upload files to share with your team.
**Button**: Upload document
```
### Consumer/Friendly Product
```
**Title**: Nothing here yet!
**Body**: Start adding favorites to build your collection.
**Button**: Find favorites
```
### Serious/High-Stakes Product
```
**Title**: No alerts
**Body**: Your systems are running normally.
```
## Illustration Guidance
When working with designers on empty state illustrations:
**First-use**: Optimistic, inviting imagery (open boxes, blank canvases, starting points)
**User-cleared**: Positive, completion imagery (checkmarks, clean spaces, celebrations)
**No results**: Neutral, helpful imagery (search icons, magnifying glasses, directional arrows)
## Common Mistakes to Avoid
❌ **Negative framing**: "You have no contacts"
✅ **Neutral/positive**: "No contacts yet"
❌ **No guidance**: "Empty"
✅ **Actionable**: "No contacts yet. Import to get started."
❌ **Multiple CTAs**: Three different buttons competing
✅ **Single primary CTA**: One clear next action
❌ **Too much text**: Long paragraph explaining the feature
✅ **Concise**: One sentence benefit, clear button
❌ **Technical**: "No records found in database"
✅ **Human**: "No projects found"
## Quick Fill Template
Use this for rapid empty state drafting:
**Empty state type:** (First-use / User-cleared / No results / Permission)
**What's empty:**
**Why it's empty:**
**What user should do:**
**User benefit:**
**Draft:**
**Title**: [What's empty]
**Body**: [Benefit of action or what happens next]
**Button**: [Specific action]
**Example filled:**
- Type: First-use
- What's empty: Saved reports
- Why: New user
- What to do: Create or save a report
- Benefit: Quick access to important data
Draft:
**Title**: No saved reports yet
**Body**: Save reports to access your most important data quickly.
**Button**: Create report
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 |