better-writing

融入界面的文案

清晰简短胜过巧妙，保持一致胜过追求多样，而最好的错误消息，是重新设计交互，让错误无从发生。编写或审阅任何面向用户的文本时，都应遵循这些原则。

文案的呈现方式（通过 text-transform 控制大小写、截断、智能标点）由 better-typography 技能介绍；错误标记和播报（aria-invalid、实时区域）由 better-accessibility 技能介绍；为翻译后的字符串预留空间则由 better-layout 技能介绍。

快速参考

类别	使用时机
审阅输出格式	严重程度分级、问题表格、验证、结论

核心原则

1. 了解现有语气

编写或审阅之前，先检查界面中相近的文案、产品术语、本地化规范，以及任何语气或内容风格指南。如果品牌特色是有意为之，且表达清晰、符合场景的重要程度，就应予以保留。只有当偏离通用浅白语言的做法造成不一致、歧义、翻译风险或不恰当的语气时，才将其视为问题。

2. 语气统一，灵活调整

产品应有一种统一的语气，由现有体系确立，而不是在局部修改时凭空创造。术语要保持一致：如果菜单中用的是“归档”，提示消息中就不应变成“移至存储”。语气则应随场景的重要程度调整：

场景	语气
成功、引导流程、空状态	亲切，可以轻松一些
常规操作、设置	中性、简洁
错误、危险操作确认	冷静、直白，不带玩笑意味
数据丢失、安全	严肃、明确

3. 直接面向读者

在说明性界面文案中，直接称呼读者为“你”，而不是“用户”。如果错误消息中的“我们”会造成歧义或显得推卸责任，就应避免使用：优先采用“无法加载内容”，而不是“我们无法加载此内容”。在风险较低的场景中，如果既有的第一人称品牌语气依然清晰，就应予以保留。少用所有格（用“收藏夹”而不是“你的收藏夹”），且绝不要无意中切换叙述视角。

4. 用浅白词语，避免卖弄

选择容易理解的词语，删去所有不必要的字词。不要使用无法翻译的习语、口语表达或幽默。避免不必要的性别区分：写“订阅者可以发布食谱”，而不是“每位订阅者都可以发布他或她的食谱”。用词应与输入设备相符：触屏用“轻触”，指针设备用“点击”，两种设备都适用时用“选择”。绝不要通过在变量两侧拼接片段来构造句子（"You have " + n + " new messages"）；语序会因语言而异，因此应使用完整的模板字符串，并正确处理复数形式。

5. 按钮文案以动词开头

按钮标签应以动词开头，明确说明具体操作：“发送”“保存草稿”“删除项目”。绝不要使用“好的！”“出发吧！”或在重要操作中只写“是”或“否”。确认按钮应重复说明后果，让用户不读正文也能作答：确认对话框询问“删除此项目？”，按钮应为 删除项目 和 取消，而不是“是”和“否”。

6. 流程用语保持一致

多步骤流程应使用统一的词汇：“开始”用于进入，“继续”或“下一步”（二选一）用于推进，“完成”用于结束。跨步骤交替使用同义词，会让用户怀疑按钮是否有不同作用。

7. 链接要说明目标

脱离上下文时，链接文本也应有意义；屏幕阅读器用户会通过页面链接列表进行导航。使用“阅读账单文档”，不要使用“点击此处”（这也违反了触屏设备上的动词规则），页面上出现多个链接时，也不要只写“了解更多”。应在每个链接后说明主题：“了解有关导出的更多信息”。

8. 统一大小写规则

按元素类型选择标题式大小写或句首字母大写（例如所有按钮、所有标题），并始终保持一致；句首字母大写通常更稳妥：语气更平和，无需为每个单词制定大小写规则，也更便于本地化。“保存更改”旁边写着“舍弃更改”，会显得不够用心。

9. 设置项描述开启状态

切换开关的标签应描述开启后的效果，例如“发送已读回执”，用户自然会推断关闭时的状态。切勿用否定形式命名（“不发送已读回执”），否则会让开关变成双重否定。直接链接到提及的设置，而不是描述前往该设置的路径：使用“通知设置”链接，而非“前往设置 > 通知 > 邮件”。

10. 错误提示应说明如何修复，并紧邻出错位置

错误提示是一条操作指引，应放在出错字段旁边：

不佳	更好
密码太短	请选择至少包含 8 个字符的密码
名称无效	名称只能使用字母
哎呀！出了点问题。	无法保存。请检查连接，然后重试。

不要责怪用户，不要写“哎呀”，也不要使用感叹号。提示应采用肯定的表达方式（“只能使用字母”，而非“不要使用数字或符号”），并在用户出错之前显示，而不是之后。如果同一错误反复影响许多用户，应重新设计交互，而不是改写提示文案。

11. 空状态应指引用户继续操作

空状态应说明此处是什么，以及如何填充内容，并提供一个明确的下一步操作：

<p>No results.</p>


<p class="font-medium">No projects yet</p>
<p class="text-sm text-zinc-500">Projects keep your tasks and files together.</p>
<button class="mt-4">Create a project</button>

搜索和筛选的空状态应指出查询内容，并提供退出方式：“没有‘季度’的结果。清除筛选条件”。切勿将重要的持久信息放在空状态中；一旦有了内容，这些信息就会消失。

12. 占位符是示例，不是标签

占位符展示预期格式（[email protected]、DD/MM/YYYY）。占位符绝不能是字段唯一的标签：输入内容后，占位符会消失，因此每个字段都应保留可见标签。

常见错误

错误	修正方法
局部改写忽略了产品既定术语或语气	提出修改前，先检查附近的文案和风格指南
指引性界面文案中使用“用户”	直接以“你”称呼读者
“我们遇到了一些问题……”掩盖责任归属或恢复方法	使用明确的状态和下一步操作：“无法加载内容”
在具有破坏性的确认对话框中使用 OK / 是	重复说明后果：“删除项目”
第 2 步用“继续”，第 3 步用“下一步”	整个流程使用统一的术语
“点击此处”或单独使用“了解详情”作为链接文字	描述链接目标：“阅读账单文档”
“保存更改”与“放弃更改”并列	每种元素类型采用统一的大小写规则
“不发送已读回执”开关	标注开启状态：“发送已读回执”
“哎呀！出了点问题。”	在出错字段旁说明应采取的操作
将“没有结果。”作为完整的空状态	提供说明和下一步操作
用占位符代替标签	保留可见标签；用占位符展示格式
"You have " + n + " messages"	使用完整的模板字符串，并处理复数形式

报告

只有当所有已确认的问题都按照 review-output.md 中的格式报告，并附有验证结果和判定结论时，独立的文案审查才算完成。在 better-interface 下则以其格式为准。