How to Write Hints and Messages

State the current situation plus the next action. No exclamation marks, no trailing punctuation.

Hints and messages are where the product talks to the user. There's a fixed formula, and you shouldn't have to reinvent it each time. error-guidelines

What you'll run into:

• An error says "operation failed" and the user has no idea what to do next
• The same meaning appears three different ways in three places, with inconsistent tone
• AI-generated copy is all exclamation marks, like it's yelling at you

The two-part formula

A message has two parts: state the current situation, then give the next action. Both are required.

The left column all shares one flaw: it says only half—the situation, with no way out. The user still doesn't know what to do. And "operation failed" doesn't even state the situation clearly: what failed, why, and what to do next are all missing.

Four principles

• Correct. No typos, no grammar errors, no ambiguity—state objective facts. It sounds obvious, but typos in hint copy show up surprisingly often.
• Actionable. When the user makes a mistake, tell them how to fix it; when something goes wrong, give a path to recover. A message that only reports the problem is as good as unwritten.
• Concise. Use the shortest, most direct wording. Avoid long sentences and technical jargon unless you're sure the user understands.
• Consistent. Unify language, word order, punctuation, and icons across the whole site. A feature should be called the same thing in messages as in the UI—if the UI says "Archive," the message shouldn't say "Completed," or users will think it's a different thing.

Punctuation and icon conventions

• Use one punctuation style. Don't mix Chinese and English punctuation.
• Avoid exclamation marks. They inject emotion and turn a network blip into a catastrophe.
• No trailing punctuation. Except for questions. "File deleted" doesn't need a period.
• Use commas to break up long sentences. Easier to read than one long run-on.
• Quote the object you're emphasizing. Like "Delete 'Project Weekly'?"—it prevents misunderstanding.
• Use an ellipsis for waiting states. "Loading…" "Verifying…".
• Truncate overflowing text with an ellipsis. Design for the extreme case; anything beyond shows "…".

Icons follow industry convention: an exclamation for warnings, a question mark for help, red for errors, yellow for warnings, green for success. This layer doesn't need innovation. When choosing the form, sort by severity into three tiers: errors that must be fixed immediately use a modal; status changes and success use a global toast; optional information uses a bubble. Jumping a tier costs you the user's attention for that entire tier—if everything is a modal, no modal gets read.

Note for the AI

This convention belongs in your project file, so all future copy is generated against it.

CLAUDE.md · copywriting spec:

## Messages

Formula: state the current situation + give the next action. Both parts required.
  ✗ Operation failed
  ✓ Couldn't reach the server, try again in a moment

Principles: correct, actionable, concise, consistent across the site.
Feature names in messages must match the UI.

Punctuation:
- Use one punctuation style, no mixing
- No exclamation marks
- No trailing punctuation except for questions
- Use commas to break up long sentences
- Quote emphasized objects with double quotes
- Waiting states end with an ellipsis, e.g. "Loading…"
- Truncate overflowing text with an ellipsis

Severity tiers (never jump a tier):
- Modal: errors that must be fixed immediately
- Global toast / banner: status changes, success
- Bubble / badge: optional information

Error messages must not expose status codes, stack traces,
or raw English error text—translate everything into words
the user understands, and give the next step.