Skip to content
GitHub
Sections

Reference · UI writing

Error messages that report without helping

Forbidden
"Oops, something went wrong! Your payment wasn't successful as an error occurred" → OK
Instead
"Payment failed. Update your payment details and try again" → Update payment details

What this rule looks like

Forbidden
Instead

Why this rule

An error message has three jobs: say what happened, say why where it helps, and give the way forward. Then:

  • Never blame the user. Not "you entered an invalid card number" but "that card number doesn't look right".
  • Cut the apology. "Please", "sorry", "oops", "unfortunately" add length and delay the useful part. A cheerful "Oops!" above a failed payment is worse than nothing.
  • No system voice. No codes, stack traces or internal terminology in front of a user.
  • Make the heading and the button descriptive enough to work alone. Someone who reads only "Payment failed" and the button label can recover without the paragraph.

See P-01 for *where* the message goes and F-37 for field-level validation text.

Kind
Rule
Section
UI writing
Group
Errors
Bucket
judgment
Severity
note
Since
v0.1.0

Read as plain text