UX Writing Guide Template

UX Writing Guide: [Product name]

House standard for interface text (microcopy): voice and tone, buttons and links, form labels, error messages, empty states, confirmations, notifications, inclusive language and the hooks that make text translatable. Error rules follow WCAG 2.2 (W3C Recommendation, first published 5 October 2023, current version 12 December 2024) success criteria for input errors and status messages. Replace every [bracketed] value and every row marked Example. The examples use a fictional app, Tallow Notes.

Document control

Revision history

1. Voice and tone

Voice: plain, calm, helpful. (Example)

2. Buttons and links

• Start with a verb and name the object: "Save note", "Export PDF".
• Match the label to the result in the dialog title: a dialog called "Delete note?" has a button "Delete", not "OK".
• Use sentence case.
• Link text describes the destination: "Read the export guide", never "click here".
• Keep the visible label inside the accessible name of a control, so speech-input users can say what they see (WCAG 2.2 SC 2.5.3 Label in Name, Level A).

3. Forms and labels

• Every field has a visible label; placeholders are hints, not labels.
• State format rules before the user types: "Date (YYYY-MM-DD)".
• Mark optional fields rather than required ones when most are required.
• Do not ask again for information already given in the same process (WCAG 2.2 SC 3.3.7 Redundant Entry, Level A).

4. Error messages

WCAG 2.2 requirements that apply to errors (own summaries; check the official text):

Structure: what happened + why (if known) + what to do.

Rules:

• Never rely on colour alone; add text and an icon.
• Put the message next to the field and move focus to the first error on submit.
• Do not blame the user, and do not use humour in errors.
• Show a code from the error reference (docs/error-message-reference) in small print when support may need it.

5. Empty states

6. Confirmations and destructive actions

• Prefer Undo over confirmation dialogs for reversible actions.
• Dialog title asks the question with the object and count: "Delete 3 notes?"
• Body states the consequence: "They will be removed from all your devices."
• Buttons: the action verb ("Delete") and "Cancel".

7. Notifications and status messages

Expose each status message to assistive technology (for example with a live region) so it is announced without taking focus.

8. Inclusive language

• Use "they" when gender is unknown; avoid gendered defaults.
• Describe the action, not the device or sense used: "Select" or "Choose", not "Click" or "See", when the input method is unknown.
• Avoid idioms, sarcasm and culture-specific references; they translate badly and exclude readers.
• Prefer neutral technical terms: "allowlist" and "blocklist", "primary" and "replica".
• Do not use ableist metaphors such as "crippled" or "blind spot".

9. Localisation hooks

• Never concatenate strings. Use one message with placeholders: "{count} notes moved to {folder}", not count + " notes moved to " + folder.
• Plurals by category. Use a message format that supports CLDR plural categories (zero, one, two, few, many, other). English needs only one and other; other languages need more, and other is always required.
• Allow growth. Leave space for text that can be [30 to 40]% longer after translation; do not fix button widths.
• Context for translators. Add a description to every string: where it appears, what each placeholder holds, the character limit.
• Dates, numbers and currency come from locale formatting, never from hand-built strings.
• Input methods. Do not trigger actions on Enter while text composition is in progress (for example, Japanese, Chinese or Korean input methods).
• Mark the language of passages in another language so screen readers switch pronunciation (WCAG 2.2 SC 3.1.2 Language of Parts, Level AA).

Example message with plural categories (ICU MessageFormat style):

{count, plural,
  one {# note moved to {folder}}
  other {# notes moved to {folder}}
}

10. Word list

11. Review checklist

• The text says what happens, in the user's words.
• Buttons start with a verb and match the dialog title.
• Errors say what happened and how to fix it, next to the field.
• No string is built by concatenation; plurals use categories.
• Each new string has a translator description.
• The string is stored in the string source, not hard-coded.

12. References

• Web Content Accessibility Guidelines (WCAG) 2.2, W3C Recommendation, 12 December 2024: https://www.w3.org/TR/WCAG22/.
• Unicode CLDR, Plural Rules: https://cldr.unicode.org/index/cldr-spec/plural-rules.
• Related templates: docs/style-guide-technical, docs/error-message-reference, docs/localization-brief, docs/termbase, design/design-system, design/accessibility-checklist.

Standard and licence note

Based on WCAG 2.2 (W3C Recommendation, 12 December 2024) for error identification, error suggestion, labels and status messages, and on the Unicode CLDR plural categories; success criteria are cited by number and summarised in original wording. The rest of this guide is original text written for this collection. Check the current W3C version, including errata, before relying on it. Template licence: MIT.