---
title: Words and Labels
slug: words-and-labels
kind: grammar
summary: The text is the interface. A button named after its outcome, a label in the customer's vocabulary and an error that says what to do next do more than any amount of layout.
problem: >-
  Labels get written from the developer's side of the screen — Submit, New,
  Invalid input, Entity — so the person has to translate every one of them into
  what it means for them, and sometimes translates wrongly.
family: [orient, act]
principles: [orientation, friction, consistency]
status: stable
visibility: public
related:
  - title: Orientation
    url: /patterns/orientation
    summary: Self-explaining labels are half of what makes a screen orienting.
  - title: Validation Errors
    url: /patterns/validation-errors
    summary: The place where words matter most, and are written worst.
---

## Buttons are named after outcomes

**"Save Invoice" beats "Submit". "Add Customer" beats "New".** The button is
where people learn what will happen, and a verb with no object makes them guess.

The test: read the button alone, with the rest of the screen covered. If you
cannot tell what will exist afterwards, it is under-named.

This applies hardest to the last button in a flow. "Finish" tells you the wizard
is over; "Create the account" tells you what you just did.

## Use the customer's vocabulary, not the schema's

If the business says *job*, the interface says job — even when the table is
`work_orders`. If they say *matter*, or *load*, or *case*, use that.

Vocabulary that has to be translated is vocabulary people get wrong, and the
cost lands in training, in support, and in the quiet errors where someone picked
the wrong thing because two words sounded similar.

Capture the real words during discovery. They are the cheapest source of quality
in the whole build, and they are free at the start and expensive later.

## Labels stay visible

A placeholder is not a label. It disappears exactly when someone is typing —
the moment they most need to check what the field was for — and it fails for
anyone returning to a half-filled form.

Put the label above the field, keep it there, and use the placeholder for an
**example of the format** if it earns its place: `PO-2291`, not "Enter
reference".

## Errors say what to do next

Three parts, in order: what happened, why, and what to do.

- ❌ "Invalid input."
- ❌ "Error: constraint violation."
- ✅ "That reference is already used by INV-1039. Use a different one, or open
  INV-1039."

The second half of a good error is a **path**, not an apology. And an error
should never blame the person for a rule they could not have known.

## Empty states and confirmations are copy problems

An [empty state](/patterns/empty-state) is almost entirely words: which of the
four kinds of empty this is, and what to do about it. A confirmation is words
too — "Delete 43 invoices? This cannot be undone" is a completely different
dialog from "Are you sure?", and the only difference is the writing.

## The rules worth enforcing

- One term per concept, everywhere. Never *client* on one screen and *customer*
  on the next.
- Sentence case for labels and buttons. Title Case reads as a heading and slows
  scanning.
- No jargon the customer does not already use — including yours.
- Numbers in copy, not vagueness: "43 invoices", not "several items".
- Never blame the reader: "That file is too large (12 MB, limit 8 MB)", not "You
  uploaded an invalid file".
- Write the error for the person who will hit it at 5pm on a Friday.

## The test

Cover every icon, colour and box on the screen and read only the text. If the
screen still makes sense — what it is, what is wrong, what to do — the words are
doing their job. Most screens fail this, and it is almost always the cheapest
thing to fix.