Errors
Name what failed and how to fix it, next to the field. Never blame the reader.
Prevent the error first
The best error message is the one nobody needs. Before you write one, check whether the interface can stop the mistake: validate as the person types, offer a picker instead of a free text field, or make an invalid value impossible to enter.
Write the message
- Name the failure: "Payment failed", not "Something went wrong".
- Give a concrete recovery step: "Enter a valid email address", not "Invalid entry".
- Use plain language, not system language: "Select the start date", not "Invalid temporal parameter".
- Use the real number, date or limit: "Use 64 characters or fewer".
- Put an error code last, and only when the reader can act on it.
- Don't blame and don't apologize, unless the system caused real loss.
<tk-field label="Email" error="Enter a valid email address"> <tk-input type="email" value="ada@example"></tk-input> </tk-field>
Place it next to the field
- Show the message as visible text next to the field it is about, not in a tooltip.
- Keep what the reader typed, so they fix it instead of starting over.
- If the first fix might not work, offer a second path.
Error or warning
- An error means something is broken and needs action before the reader can go on.
- A warning means the reader can continue, but should know the consequence.
Don't style one as the other.
Keep strings generic
Specific behavior, generic language. Don't build real names or file names into the string; it breaks translation. Put user-provided content in quotes instead: "Delete 'cat shirt'?".
Fail in layers
A broken widget shows its own empty state while the rest of the page keeps working. Save full-page errors for the cases that need them: page not found, access denied, a server error, a bad request.
Do and don't
| ✅ Do | ❌ Don't |
|---|---|
| "Enter a valid email address" | "Invalid entry" |
| "Payment failed. Your card was declined. Try another card." | "Something went wrong" |
| "Select the start date" | "Invalid temporal parameter" |
| "Use 64 characters or fewer" | "Too long" |