uw-ssec

ux-writing

Writes, reviews, and refines UI microcopy for digital products including button labels, error messages, empty states, and voice and tone documentation. Use when writing or auditing UI copy — button labels, error messages, empty states, onboarding flows, confirmation dialogs, tooltips, success toasts — or when establishing voice and tone documentation for a product.

uw-ssec 32 14 Updated 20h ago

Resources

1
GitHub

Install

npx skillscat add uw-ssec/savvy/ux-writing

Install via the SkillsCat registry.

SKILL.md

UX Writing

End-to-End Workflow

For every piece of UI copy, run these five steps in order.

1. Identify UI context. Which pattern? (button, error, empty state, onboarding, success toast, confirmation, tooltip, placeholder) Match to a template in Microcopy Guide or Error Message Patterns.

2. Determine user emotional state. Curious, frustrated, anxious, accomplished, lost? Look up the row in the Tone Across Contexts table in Voice & Tone Guide.

3. Apply voice + tone. Voice is constant (the product's personality). Tone shifts by context. Pick the tone row that matches step 2.

4. Write the copy using a pattern below.

5. Validate against the checklist at the bottom. If any item fails, revise.

Pattern: Error Message (formula)

What happened + Why (optional) + How to fix it

Before After
Error: Invalid input That email address doesn't look right. Check that it includes an "@" and a domain like name@example.com.
Error 403: Forbidden You don't have permission to view this page. Ask the project owner to share access with you.
Upload failed That file is too large. Max upload is 10 MB. Try compressing the image or choosing a smaller file.
Password too short Use at least 8 characters for your password.
Request timeout That took too long. Check your connection and try again.
Too many requests You've hit the request limit. Wait a minute and try again.
Required Add a project name to continue
Invalid file type Upload a PNG, JPG, or GIF. PDFs aren't supported here.

Rules:

  1. Plain language, not error codes.
  2. Don't blame the user ("That file is too large" not "You uploaded a file that's too large").
  3. Always give a next step.
  4. Brief, but never at the cost of clarity.

Pattern: Severity → Presentation

Severity Presentation Use when
Inline validation Red text below field One field invalid
Field-level error Highlighted field + message Submission with errors
Toast/snackbar Temporary overlay Non-blocking (network retry)
Banner Persistent banner System-wide (maintenance)
Full page Dedicated error page Fatal (404, 500, offline)

Pattern: Button / CTA

  • Use specific verbs: "Save draft", "Publish post", "Send invitation" — not "Submit".
  • Front-load the action: "Delete account" not "Permanently remove your account from the system".
  • Match context: sign-up form → "Create account", not "Submit".

Full table: Microcopy Guide → Button & CTA Patterns.

Pattern: Empty State

Three types — first-use, user-cleared, error. Full templates in Microcopy Guide → Empty State Type Templates.

Voice vs. Tone (quick definitions)

  • Voice = the product's consistent personality (does not change).
  • Tone = how voice expresses in this specific context (changes with user emotional state).

Full voice attribute table and tone-by-context table: Voice & Tone Guide.

Core Microcopy Principles

  • Clear over clever — "Got it" beats "Roger that, Captain!"
  • Brief over verbose — cut every word that doesn't add meaning.
  • Specific over vague — "Save to drafts" beats "Save".
  • Active voice — "We saved your changes" not "Your changes have been saved".

Validation Checklist

For every piece of copy, confirm:

  • Reads aloud naturally in under 3 seconds.
  • No error codes, jargon, or internal system terms.
  • User knows what to do next (action verb or clear path).
  • No blame language ("you uploaded a bad file" → "that file isn't supported").
  • Button label names the outcome, not "Submit"/"OK".
  • Tone matches user emotional state (see Tone table).
  • Localizable: no idioms, contractions handled, no concatenated strings.
  • Plural and zero states both written ("0 results", "1 result", "5 results").
  • Under context-appropriate length: button ≤ 3 words, toast ≤ 60 chars, error summary ≤ 12 words.

If any item fails → revise and re-validate.

Deep Dive References

  • Microcopy Guide — Buttons, forms, tooltips, navigation, dialogs, status messages, empty states
  • Error Message Patterns — Anatomy, types, tone calibration, localization, prevention, audit checklist
  • Voice & Tone Guide — Voice attribute table, tone-by-context table, style guide essentials, inclusive language, audit process

Next Steps

  • Accessibility Audit (the accessibility-audit skill): Verify copy works with screen readers
  • User Research (the user-research skill): Test copy effectiveness with users
  • Information Architecture (the information-architecture skill): Align copy with navigation labels
  • Design System Creation (the design-system-creation skill): Document voice and tone in the system