/sota-ux-writing

name: sota-ux-writing
description: >-
  State-of-the-art UX writing and product-copy guidance (2026) covering voice
  and tone systems, plain language (ISO 24495-1), microcopy (buttons, labels,
  empty states, onboarding, notifications), error and feedback message craft,
  and the accessibility and localization of interface language (WCAG 2.2
  language criteria, alt text, ICU pluralization, i18n-safe strings). Use when
  writing or reviewing ANY user-facing interface text — web, mobile, desktop,
  or CLI products — AND when auditing existing product copy for clarity,
  consistency, tone, accessibility, and localization readiness. Trigger
  keywords: UX writing, microcopy, product copy, content design, error message,
  empty state, button label, tooltip, onboarding copy, form label, placeholder,
  notification, toast, confirmation dialog, tone of voice, terminology, plain
  language, readability, alt text, i18n strings, localization, translation.

SOTA UX Writing & Product Copy

Purpose

Expert-level rules for the *words inside the product*: labels, buttons, errors, empty states, onboarding, notifications, and every other string a user reads while trying to get something done. The core thesis: **interface text is functional infrastructure, not decoration — a user reads it under task pressure, often in a second language, often through a screen reader, and every word either moves them forward or costs them a support ticket.**

Boundaries: this skill owns the *language*. The UX *patterns* the language lives in (when to show an empty state, validation timing, dialog escalation) are `sota-frontend-design` rules/04; technical documentation is `sota-docs-workflow`; outward-facing marketing content is `sota-copywriting`; CLI-specific output contracts are `sota-cli-ux`.

BUILD mode

When writing or changing interface text:

1. **Write the unhappy paths first** — errors, empty states, and confirmations carry more consequence than the happy path (`rules/03`). 2. **Apply the plain-language spine** to every string: relevant, findable, understandable, actionable (ISO 24495-1) — front-load the point, one idea per sentence, common words (`rules/01`). 3. **Name things once.** Check the product glossary before introducing a term; never let the UI, docs, and API call the same concept different names (`rules/01` §4). 4. **Buttons are verbs with objects** ("Delete project", never "OK"/"Yes"), and every dialog states the specific consequence (`rules/02`). 5. **Write for the translator and the screen reader as you go**: externalized strings, ICU plurals, named placeholders, descriptive link text, accessible names matching visible labels (`rules/04`). 6. Before finishing, run each loaded rules file's **Audit checklist** against the diff — including the greps for banned strings.

AUDIT mode

When reviewing existing product copy:

1. Inventory the string surface: localization files (`*.json`, `*.po`, `*.strings`, `*.xlf`), hardcoded literals in components, error-message constants, email/notification templates. 2. Run the banned-pattern greps from each rules file's audit checklist (e.g. `"click here"`, `"an error occurred"`, `"invalid input"`, concatenated plurals). 3. Walk the critical flows as a user: signup, first-run empty state, a failed payment/submit, a destructive action. Judge every string against `rules/01`–`03`. 4. Check localization readiness (`rules/04`) even for single-language products — retrofitting string externalization is expensive.

Severity conventions

• **Critical** — copy that causes data loss or deception: destructive-action

dialog whose buttons don't name the action; error message leaking secrets, internals, or account existence; consent text that misrepresents what happens; dark-pattern confirmshaming.

• **High** — copy that blocks task completion or excludes users: error with no

next step; placeholder used as the only label; icon-only control with no accessible name; untranslatable concatenated strings; link text meaningless out of context ("click here").

• **Medium** — friction and inconsistency: same concept under two names;

jargon or internal codenames in UI; blame-framed errors; toasts carrying the only path to an action; missing empty-state guidance.

• **Low** — polish: tone drift, capitalization inconsistency, "please"

inflation, exclamation marks, filler words ("simply", "just").

Finding format

`file:line | rule violated | severity | effort | fix` — quote the current string and propose the exact replacement string; copy findings without a proposed rewrite are half-findings.

Rules index

| File | Read this when... | |---|---| | `rules/01-voice-tone-plain-language.md` | Establishing or auditing the overall language system: voice vs tone, stress-aware tone shifts, plain-language rules (ISO 24495-1), readability, terminology/glossary discipline, capitalization and punctuation conventions. | | `rules/02-microcopy-components.md` | Writing the words in components: buttons/CTAs, labels vs placeholders vs hints, empty states, onboarding and tooltips, confirmation dialogs, notifications/toasts/badges, counts and plurals, relative time, link text, loading/progress text. | | `rules/03-errors-feedback.md` | Anything that reports a problem or outcome: error-message anatomy, no-blame framing, validation wording, security-sensitive errors, warnings vs errors, success confirmations, permission prompts, and dark-pattern-free upsell moments. | | `rules/04-accessibility-localization.md` | Making the language reach everyone: WCAG 2.2 language criteria, alt text craft, accessible names, screen-reader-facing strings, string externalization, ICU plurals, translator context, text expansion, RTL, inclusive language. |

Top-10 non-negotiables

1. **Every error says what happened and what to do next** — a dead-end error is a support ticket with extra steps. (rules/03 §1) 2. **Buttons and dialog actions a