# 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.

<!--
Guidance: How to use this template
- Keep the guide short enough that designers and engineers read it.
  Every rule should prevent a mistake you have actually seen.
- Give each rule a Do / Don't pair from your own product.
- Agree the guide with design, engineering and localisation, because
  all three ship interface text.
- Store approved strings in one place (a string file or design token
  library) and link to it.
-->

## Document control

<!-- Guidance: Name the owner and the people who approve changes to rules. -->

| Field | Value |
|---|---|
| Document ID | [DOC-UXW-001] |
| Version | [1.0] |
| Status | [Draft / Approved] |
| Owner | [@content-designer] |
| Approvers/reviewers | [@design-lead], [@localisation-lead], [@accessibility-lead] |
| String source | [Path to string files, for example `messages/en.json`] |
| Spelling variant | [US English / UK English] |
| Last updated | YYYY-MM-DD |

### Revision history

| Version | Date | Author | Change |
|---|---|---|---|
| 1.0 | YYYY-MM-DD | [@name] | First version |

## 1. Voice and tone

<!-- Guidance: The voice is constant; tone adapts to the user's situation. Describe both with examples. -->

Voice: **plain, calm, helpful**. *(Example)*

| Situation | Tone | Do | Don't |
|---|---|---|---|
| First use | Welcoming, brief | "Write your first note" | "Welcome to the revolutionary Tallow Notes experience!" |
| Error | Calm, specific | "We could not save your note. Check your connection and try again." | "Oops! Something went wrong!" |
| Destructive action | Serious, clear | "Delete 3 notes? You cannot undo this." | "Are you sure?" |
| Success | Short, quiet | "Note saved" | "Awesome, you did it!" |

## 2. Buttons and links

<!-- Guidance: A button label should tell users exactly what will happen. -->

- 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

<!-- Guidance: Labels and instructions are required wherever input is requested (WCAG 2.2 SC 3.3.2, Level A). -->

- 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

<!-- Guidance: Errors are where users most need help. Apply the WCAG criteria and the structure below to every message. -->

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

| Success criterion | Level | What it means for text |
|---|---|---|
| 3.3.1 Error Identification | A | When input errors are detected automatically, identify the field and describe the error in text |
| 3.3.3 Error Suggestion | AA | When you know how to fix the error, tell the user, unless that would harm security or purpose |
| 3.3.4 Error Prevention (Legal, Financial, Data) | AA | For commitments and data changes, allow reversal, checking or confirmation before submission |
| 4.1.3 Status Messages | AA | Status messages can be announced by assistive technology without moving focus |

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

| ID | Do | Don't |
|---|---|---|
| ERR-01 *(Example)* | "Enter a date after today." | "Invalid input." |
| ERR-02 *(Example)* | "This file is larger than 25 MB. Choose a smaller file or compress it." | "Upload failed." |
| ERR-03 *(Example)* | "We could not sync. Your notes are saved on this device and will sync when you are back online." | "Network error 0x80070057." |

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

<!-- Guidance: An empty screen is a chance to teach. Say why it is empty and what to do next. -->

| Case | Pattern | Example |
|---|---|---|
| First use | What this is + first action | "No notes yet. Write your first note." *(Example)* |
| No search results | Echo the query + suggestion | "No notes match 'invoce'. Check the spelling or search all folders." *(Example)* |
| Cleared by user | Confirm + way back | "Trash is empty." *(Example)* |

## 6. Confirmations and destructive actions

<!-- Guidance: Ask for confirmation only when the action is hard to undo; otherwise offer Undo. -->

- 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

<!-- Guidance: Decide what deserves interrupting the user. -->

| Type | When | Example |
|---|---|---|
| Inline status | Background result the user may want to know | "Saved" *(Example)* |
| Toast | Result of a user action, with Undo where possible | "Note moved to Trash. Undo" *(Example)* |
| Banner | Ongoing state affecting the whole app | "You are offline. Changes are saved on this device." *(Example)* |

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

## 8. Inclusive language

<!-- Guidance: Write for every user. Review new strings against these rules. -->

- 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

<!-- Guidance: Most translation bugs are created in the source language. These rules let translators do their job. -->

- **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):*

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

## 10. Word list

<!-- Guidance: Record decisions on words that recur in the interface. -->

| Use | Avoid | Note |
|---|---|---|
| sign in | log in, login (as a verb) | *(Example)* Match the identity provider's wording |
| delete | remove | *(Example)* "Remove" only when the item still exists elsewhere |
| note | document, file | *(Example)* Product noun |
| [term] | [term] | [note] |

## 11. Review checklist

<!-- Guidance: Use this before merging any string change. -->

- [ ] 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

<!-- Guidance: List the standards and related guides. -->

- 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.