ux-writing-and-microcopy

name	ux-writing-and-microcopy
description	Use when writing or reviewing buttons, field labels, hints, tooltips, menus, toggles, placeholders, tabs, navigation labels, or other routine interface microcopy. Use error-empty-and-system-messaging for system states and voice-tone-and-content-style-guide for voice governance.
metadata	{"portable":true,"category":"10-content-design-and-ux-writing","compatible_with":["claude-code","codex"]}

UX Writing & Microcopy (Clarity-First Interface Copy)

Microcopy is the small, functional text the user reads at the moment of action — the verb on a button, the label above a field, the one line in a confirmation dialog. It is where most of an interface's words live and where most of its friction hides. This skill makes that copy clear first, on-brand second, and never decorative — and ties every string back to the product's voice rather than letting each screen drift.

Microcopy is also a doctrine concern, not just a writing concern. Generic, hedged interface copy ("Submit", "Are you sure?", "Oops! Something went wrong") is the verbal form of AI slop: the convergent, unconsidered default. Per doctrine/design-doctrine.md §0–2, the moat is output that looks authored — and that includes the words. State the voice, then write copy a templating tool would never have produced.

Use When

• Deciding what a button or CTA should say (primary action, secondary, cancel, destructive).
• Writing form labels, hints, placeholders, helper text, and inline-success strings.
• Writing tooltips and short helper text for ambiguous icons or controls.
• Writing confirmation / destructive-action dialogs (delete, discard, overwrite, sign out).
• Writing toggle, checkbox, radio, and menu-item labels so state and consequence are clear.
• Auditing existing UI copy that is vague, jargon-heavy, inconsistent, or off-voice.
• Establishing a terminology glossary so one concept has exactly one word across the product.

Do Not Use When

• The copy is an error message, empty state, or system status (offline, loading, 404, permission-denied) → use 10-content-design-and-ux-writing/error-empty-and-system-messaging (it owns the error formula and the empty-state library; this skill owns the interactive copy — buttons, labels, tooltips, confirmations).
• You are defining the brand voice / tone-of-voice spectrum itself (the adjectives, the do/don't voice chart) → that lives in 02-color-brand-and-visual-identity/brand-style-guide. This skill consumes that voice and applies it to microcopy.
• You are designing the visual empty/error/loading states (layout, illustration, hierarchy) → 14-conversion-and-web-page-patterns/empty-error-and-loading-states. This skill writes the words that go in them.
• You are writing long-form marketing or documentation prose, not in-interface strings.
• You need to detect generic, machine-written prose (the em-dash tell, "delve"-class diction, hedged transitions, list-of-three padding) → that textual AI-slop detection lives in the digital-research engine's writing-slop skills, not here. This skill decides what the words should be and whether they are on-voice; it does not judge whether a passage reads as AI-generated. Cross-reference; never duplicate.
• Voice/tone routing: once voice-tone-and-content-style-guide ships in group 10, route the voice/tone definition there (the operational content voice/tone system). Until then, the voice source is 02-color-brand-and-visual-identity/brand-style-guide; this skill consumes it.

Required Inputs

Input	Source	Required?	Evidence
User goal, screen, and complete flow	Product design and research	yes	Before/action/after context
Voice and terminology rules	voice-tone-and-content-style-guide	yes	Approved voice statement and glossary
Action consequence, reversibility, and constraints	Product and engineering owners	yes	Behaviour and validation contract

• The screen/flow and the moment: what the user is trying to do, what they just did, what happens next when they act. Microcopy without context becomes generic.
• The brand voice — the tone adjectives and do/don't from brand-style-guide. If none exists, state a provisional voice in one line before writing (per doctrine §2 non-negotiable 1).
• The consequence and reversibility of each action (especially for buttons/confirmations: is it destructive? irreversible? does it cost money or notify someone?).
• The locale / reading level and any string-length constraint (button width, mobile).

Workflow

1. State the voice before writing a word (doctrine §2, non-negotiable 1). One line: the tone adjectives and the register (e.g. "plain, warm, confident — never cute, never corporate"). Pull it from brand-style-guide; if absent, declare a provisional voice. Clarity outranks voice when they conflict — voice is how you are clear, never an excuse to be cute.
2. Name the user's goal and the moment. Write the copy from the user's intent, not the system's. "Save changes" (their goal) beats "Submit form" (the system's plumbing).
3. Buttons & CTAs — lead with a specific verb that names the outcome. Use references/button-and-cta-copy.md: action verb + object where space allows ("Create project", "Send invite", "Delete 3 files"), not "OK" / "Submit" / "Yes". The button text should complete the sentence "I want to ___". Make destructive verbs explicit ("Delete", "Discard", "Remove") — never soften them to "OK". One primary action per view. When a label is a reusable pattern (not a one-off string), state it in the {} / [] notation — {curly} = runtime variable, [square] = optional, plain text = literal, e.g. {verb} [{object}] → Create project / Save. See references/text-patterns-and-editing-curve.md §1. Keep title ↔ CTA continuity: the view's action title and its primary button name the same action, each making sense read alone ("Invite a teammate" → "Send invite", never "Submit").
4. Labels & fields — name the data in the user's language. Label = noun phrase the user recognises ("Work email", not "Email address 2"). Helper text states format or why you ask, not the obvious. Never use placeholder text as the label (it vanishes on input and fails contrast — see doctrine/references/wcag-2.2-criteria.md §perennial 4.1.2 / 1.4.3). See references/microcopy-patterns.md.
5. Tooltips & helper text — only for genuine ambiguity, and keep them short. A tooltip is a patch for an unclear control; first try to make the control self-evident. When a tooltip is warranted, one phrase, no period needed, no restating the label. Tooltips must be keyboard- and screen-reader-reachable (WCAG 1.4.13 / 4.1.2) — they are not a place to hide essential info. See references/microcopy-patterns.md §tooltips.
6. Confirmations & destructive dialogs — title states the consequence, buttons name the choices. Title = the specific outcome as a question or statement ("Delete this invoice?"), body = what is lost and whether it is reversible, buttons = the two ("Delete" / "Keep"), never "Yes / No" or "OK / Cancel". The destructive button is labelled with its real verb and visually de-emphasised or guarded. Don't pop a confirmation for trivial, reversible actions — reserve the interrupt for the costly and irreversible. See §confirmations.

Decision Rules

Condition	Copy choice	Wrong-choice failure
Action has a clear outcome	Use a specific verb plus object	Generic “Submit” hides the consequence
Space is constrained but meaning is critical	Preserve meaning; shorten surrounding text	Truncating the label creates ambiguity
Destructive action is reversible	State the outcome and recovery path	Alarmist confirmation adds friction without safety
Term conflicts with the glossary	Use the governed term or escalate an exception	Synonyms fragment the product mental model

Capability Contract

Read and search are required across flows, behaviour, terminology, and research. Editing is allowed only when content implementation is requested. Rendering and accessibility inspection are required to claim fit, truncation, accessible-name, and localisation success; publication requires separate authority.

Degraded Mode

If required evidence or tooling is unavailable, use the scoped fallback below and mark the result unverified. Without full flow context, return candidate strings with explicit assumptions rather than final copy. Without renders or localisation evidence, mark fit and translation expansion unverified, provide length-safe alternatives, and stop before release of layout-critical strings.

Anti-Patterns

• "Submit" / "OK" / "Yes-No" buttons — they name the mechanism, not the outcome. Use the verb.
• "Are you sure?" with Yes/No — the user can't tell which button does what without re-reading.
• Cute over clear — "Oopsie!", "Let's gooo!", forced jokes that delay comprehension. Voice serves clarity; it never replaces it.
• Placeholder-as-label — disappears on focus, fails contrast, breaks screen readers (4.1.2).
• Mystery-meat tooltips — essential info hidden in hover-only text unreachable by keyboard.
• Terminology drift — "project" on one screen, "workspace" on the next, for the same thing.
• Filler words — "Please simply click the button below to get started now." Cut to the verb.
• Title Case Everything / ALL CAPS — harder to read, reads as shouting or generic-template.
• Softened destructive actions — "OK" on a delete dialog hides the consequence. Say "Delete".
• Confirmation fatigue — interrupting reversible, trivial actions trains users to click past.
• Untranslatable idioms / word-order tricks — break the moment the product ships a locale.
• Copy written from the system's view — "Form submitted successfully" vs "Invite sent".

Outputs

Artefact	Consumer	Evidence and acceptance condition
Ready-to-ship interface strings	Design and engineering	Each string maps to a named state, action, and outcome
Terminology and rationale record	Content governance	Governed terms and approved exceptions are traceable
Contextual review evidence	QA and localisation	Renders, accessible names, and expansion checks pass or are marked unverified

• Final interface strings for the screen/flow: button & CTA labels, field labels + helper text, tooltips, toggle/menu labels, confirmation dialog title/body/buttons, inline success strings.
• A short terminology glossary (one word per concept) for consistency across the product.
• A one-line voice statement the copy was written against (for handoff and review).

Examples

• examples/before-after-microcopy.md — real slop-tier interface copy rewritten to clear, on-voice strings, with the reasoning for each change (buttons, labels, tooltips, a destructive confirmation), so the why transfers, not just the wording.

References

• doctrine/design-doctrine.md — §0–2: copy is part of the "looks authored" moat; state the voice before producing; no convergent default strings.
• doctrine/references/wcag-2.2-criteria.md — accessible names (4.1.2), contrast for labels/placeholders (1.4.3), focus appearance for tooltips (1.4.13). Microcopy must satisfy the AA floor.
• references/microcopy-patterns.md — patterns + good/bad for labels, tooltips, confirmations, toggles/menus, success strings, and the terminology-glossary discipline.
• references/button-and-cta-copy.md — the button/CTA copy system: verb+object formula, the primary/secondary/cancel/destructive hierarchy, and a good/bad catalogue by action type.
• references/text-patterns-and-editing-curve.md — the {} / [] pattern notation (variable vs optional vs literal), the four-phase editing curve (Purposeful → Concise → Conversational → Clear), "concise ≠ short / cutting words ≠ removing messaging", title ↔ CTA continuity, and the boundary note (AI-slop detection → research engine; voice/tone → the new group-10 skill).
• Pairs with 10-content-design-and-ux-writing/error-empty-and-system-messaging (error/empty/ system copy), 02-color-brand-and-visual-identity/brand-style-guide (the voice this consumes), and 14-conversion-and-web-page-patterns/empty-error-and-loading-states (the visual states copy fills).