How to Write Hints and Messages
Hints and messages are where the product talks to the user. There's a fixed formula—no need to reinvent it each time.
What you'll run into
- 错误提示只说「操作失败」，用户不知道接下来该干嘛
- 同一个意思在三个地方三种说法，语气也不统一
- AI 生成的文案全是感叹号，像在冲你喊
The two-part formula
| 别写 | 改成 |
|---|---|
| 操作失败！ | 没能连上服务器，稍后再试一次 |
| 格式不正确 | 手机号是 11 位数字，请检查一下 |
| Error 500 | 服务暂时不可用，几分钟后会自动恢复 |
| 暂无数据 | 还没有订单，下单后可以在这里查看物流 |
| 已删除！ | 文件已删除，可到回收站恢复 |
Four principles
- Correct. No typos, no grammar errors, no ambiguity — state objective facts. This 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 way to recover. A hint that reports a problem without a way out is as good as unwritten.
- Concise. Use the shortest, most direct wording; avoid long sentences and jargon unless you're sure the user understands.
- Consistent. Unify language, word order, punctuation, and icons across the site. The same feature should be called the same thing in hints as in the UI — if the UI says "Archive," the hint shouldn't say "Completed."
Punctuation and icon conventions
| 规范 | 怎么做 |
|---|---|
| 统一中文标点 | 不要中英文标点混用 |
| 避免感叹号 | 它会带来过强的情绪，把一次网络波动渲染成事故 |
| 句尾不加标点 | 除非是疑问句。「文件已删除」后面不用句号 |
| 句中用逗号断句 | 让结构清晰，比一长句好读 |
| 强调对象用双引号 | 「确定删除"项目周报"吗」，避免误解 |
| 等待类用省略号 | 「加载中…」「正在验证…」 |
| 内容超长用省略号截断 | 设计字段时就要考虑极值，超出用「…」代替 |
When choosing a hint form, sort by strength into three tiers: errors that must be fixed immediately use a modal; general info and success notices use a global toast; optional, nice-to-have info uses a bubble. Reaching above your tier costs you user sensitivity to that entire tier.
Note for the AI
This convention is a good fit to distill straight into the project file—after that, all copy is generated against it.
CLAUDE.md · copywriting spec
## 提示语 公式：说明当前状况 + 引导措施。两段都要有。 ✗ 操作失败 ✓ 没能连上服务器，稍后再试一次 原则：正确、有指导性、简洁、全站一致。 功能名称在提示里的叫法必须跟界面上一致。 标点： - 统一中文标点，不要中英混用 - 不使用感叹号 - 句尾除疑问句外不加标点 - 句中用逗号断句 - 需要强调某个对象时用双引号 - 等待类文案以「…」结尾，例如「加载中…」 - 内容超出显示范围时用「…」截断 强度分档（不要越级）： - 弹窗：必须立刻修正的错误 - 全局提示 / 横幅：状态变化、成功提示 - 气泡 / 红点：可看可不看的信息 错误提示不得暴露状态码、堆栈或英文报错原文， 一律转成用户能读懂的话，并给出下一步操作。