---
name: ui-microcopy-conventions
source: https://app.decimal.ai/s/ui-microcopy-conventions@1/SKILL.md
source_sha256: b848bfacf25a
---

# UI Microcopy Conventions

The handful of words that sit inside a product interface — on a button, in a failure
message, on a blank screen, in a setup step. Base models write these on autopilot and reach
for three defaults that all read as generic and leave the user stuck:

- Labels in **Title Case** (`Save Changes`, `Create New Project`).
- Failures that **open with a bare apology and no fix** (`Oops! Something went wrong.`).
- Blank screens that **just report emptiness** (`No projects yet.`) with nowhere to go.

The convention below replaces each default. One idea unifies all four surfaces: **no dead
ends** — every piece of interface copy points the user at what to do next.

## When to Activate

Activate when the user asks for the words that live inside a running interface:

- The text for this button / label / menu item / toggle.
- What the screen should say when this action fails or errors out.
- The copy for this blank / empty / no-data screen or list.
- The wording for this onboarding / welcome / first-run / setup step.
- "Fix the microcopy on this screen" / "the wording here feels off".

Not for marketing headlines or body paragraphs, email subject lines, choosing the outcome
verb and length of a marketing CTA (that is **cta-microcopy**), or turning a raw exception
or stack trace into a developer-facing message across audiences (that is
**error-message-rewriter**).

## The Conventions

Four surfaces, four rules. Apply the matching rule; when unsure which surface, apply the
one unifying rule — never leave the user with nothing to do next.

### 1. Buttons and labels — verb-first, sentence case

Start with the verb that names the action, and capitalize the label like a sentence:
only the first word (and any proper noun) takes a capital.

- `Save changes` — not `Save Changes`, not `Changes`.
- `Create project` — not `Create New Project`, not `New`, not `OK` for a create action.
- `Delete account` — not `Delete Account`, not `Yes` on a destructive confirm button.

In a confirm dialog, the primary button restates the verb (`Delete account`) rather than a
bare `Yes` / `OK`, so the button is readable on its own.

### 2. Error and failure messages — name the fix, not the apology

A failure message earns its space by telling the user what to do about it. State, in plain
words, what happened and the one concrete next step. Do not open with `Oops`, and do not
ship a message whose entire content is a generic apology like `Something went wrong`.

- Wrong password → say the password was incorrect and offer to reset it, not `Login failed`.
- File too large → give the actual limit and what to do (`Choose a file under 10 MB`), not
  `Upload error`.
- Card declined → say the card was declined and to try another, not `Payment failed`.

Be specific and non-blaming: point at the fix, not at the user.

### 3. Empty states — always offer the first action

When a screen has no data yet, do two things: say in one line what will appear here, then
give the user the action that fills it. An empty screen is never a dead end — it is the
best place to prompt the very next step.

- No projects → one line of context plus a `Create project` action, not just `No projects`.
- No search results → say nothing matched and offer a way forward (clear filters, broaden
  the search), not a bare `No results`.
- Empty inbox → a calm one-liner, not an error and not a blank void.

### 4. Onboarding and first-run — a way forward and a way out

Every setup step gives the user one clear action to continue, and a way to skip or dismiss
so they are never trapped. One decision per step; never a screen the user cannot leave.

- A permission prompt states the benefit and offers both `Turn on notifications` and a
  `Not now`.
- A welcome step has a single forward action, not three competing buttons.

## Quick Check

Before returning any interface copy, confirm:

- Labels: first word is the action verb, sentence case (only the first word capitalized).
- Errors: a concrete next step is present; no bare `Oops` / `Something went wrong` alone.
- Empty screens: an action to fill the screen is present — no dead end.
- Onboarding: a way forward AND a way to skip; one action per step.

## Per-surface pattern catalog

For a wider bank of before→after rewrites on each surface, see the catalog under
`references/` (buttons, errors, empty-states, onboarding). The rules above are complete on
their own; the catalog is lookup depth for edge cases, not new conventions.