better-writing

融入介面、自然隐形的文案

清晰精炼胜过花梢巧妙，一致连贯胜过变化多端；而最完美的错误讯息，就是重新设计互动流程，让错误根本不会发生。撰写或审查任何面向使用者的文字时，请落实这些原则。

文案呈现细节（通过 text-transform 呈现的大小写、截断、智慧标点符号）由 better-typography skill 涵盖；错误标记与辅助宣告（aria-invalid、动态区域 live regions）由 better-accessibility skill 涵盖；预留翻译字串的空间则由 better-layout skill 涵盖。

核心原则

1. 勘查现有的品牌语气 (Voice)

在撰写或审查之前，先检视附近的介面文案、产品的术语习惯、在地化规范，以及任何品牌语气或内容风格指南。当原有的品牌特色清晰且符合情境轻重时，请予以保留。只有在偏离通用平实语言会导致前后不一、产生歧义、增加翻译风险或语调不当时，才将其列为需要修正的问题。

2. 统一品牌语气，弹性调整腔调 (Tone)

产品拥有单一的品牌语气，这是由现有的系统建立的，而不是在局部修改时随手捏造的。请保持术语一致：如果选单中叫做“封存”，就不要在 Toast 提示讯息中变成“搬到储存空间”。腔调则应随情境轻重调整：

情境	腔调
操作成功、新手引导、空状态	温暖亲切，可适度轻松
例行操作、设定	中立客观，精简扼要
错误、破坏性确认操作	沉着平实，绝不嬉闹
资料遗失、安全性风险	严肃谨慎，明确直白

3. 直接称呼读者

在指引性质的介面文案中，请使用“你/您”直接称呼读者，而非“使用者”。避免在错误讯息中使用“我们”，以免造成权责模糊或有推卸责任之感：例如优先使用“无法载入内容”，而非“我们在载入内容时遇到了麻烦”。若在低风险情境中已有建立好的第一人称品牌语气，且表达依然清晰，则可保留。谨慎使用所有格（例如用“最爱”代替“你的最爱”），且切勿无意间切换视角。

4. 用字平实易懂，摒弃花梢字眼

选择容易理解的字词，删除所有不必要的冗词赘字。不要使用无法直译的成语、俗语或幽默。省略不必要的性别代名词：“订户可以发布食谱”，而非“每位订户可以发布他或她的食谱”。配合输入设备：触控装置用“轻点 (tap)”，指标装置用“点击 (click)”，两者皆可时用“选择 (select)”。切勿通过拼接变数两侧的字串碎片来构成句子（如 "你有 " + n + " 则新讯息"）；不同语言的字序各异，因此请使用完整的模版字串（templated strings）并搭配适当的单复数处理。

5. 按钮动词优先

按钮标签必须以描述具体动作的动词开头：“发送”、“储存草稿”、“删除专案”。涉及重大后果的操作切勿使用“OK!”、“出发吧！”或单纯的“是/否”。确认按钮应重复提及操作后果，让使用者无需阅读正文就能做出判断：“确定删除此专案？”应提供 删除专案 与 取消，而非 是 与 否。

6. 统一流程词汇

多步骤流程必须使用统一的词汇组：“开始”用于进入，“继续”或“下一步”（二选一）用于推进，“完成”用于结束。在不同步骤间交替使用同义词，会让使用者怀疑这些按钮是否代表不同功能。

7. 连结应明确描述目的地

连结文字即使脱离上下文也能独立理解；萤幕阅读器使用者常通过页面的连结清册进行导航。例如使用“阅读帐务文档”，绝不要用“点击这里”（这也违反了触控装置的动词规则），当同一页出现多个连结时，更不要使用孤立的“了解更多”。请为每个连结加上后缀：“了解更多关于导出的资讯”。

8. 统一大小写规范

针对不同的元素类型（所有按钮、所有标题）选定标题大小写（Title Case）或句首大写（Sentence Case）规范，并严谨贯彻；句首大写是更安全的预设选择：感觉更沉稳、没有逐字大小写的繁琐规则，且更容易在地化。“储存变更”旁边出现“舍弃变更”会让介面显得粗糙割裂。

9. 设定开关应描述“开启”状态

切换开关的标签应描述其“开启”时会发生什么：“传送已读回执”，使用者自然能推断出关闭时的状态。切勿使用否定句作为标签（例如“不要传送已读回执”），这会让开关变成双重否定。请直接连结至引用的设定项，而非描述查找路径：提供“通知设定”连结，而不是“请前往 设定 > 通知 > 电子邮件”。

10. 错误讯息应在出错位置旁说明如何修复

错误讯息是一条指引，应紧邻发生故障的栏位：

错误示范	良好示范
密码太短	请输入至少 8 个字元的密码
姓名无效	姓名请仅使用字母
哎呀！出错了。	无法储存。请检查你的连线后再试一次。

不归咎使用者，不使用“哎呀！”，不用感叹号。提示语请采用正面表述（“请仅使用字母”，而非“请勿使用数字或符号”），并在使用者犯错前展示，而不是事后才出。如果大量使用者持续遇到相同的错误，请重新设计互动流程，而不是修改文案措辞。

11. 空状态应指引前行方向

空状态应说明此处的功能以及如何填满它，并提供一个明确的下一步动作：

<!-- 错误示范：耸耸肩敷衍 -->
<p>没有结果。</p>

<!-- 良好示范：说明定位并指引下一步 -->
<p class="font-medium">尚无专案</p>
<p class="text-sm text-zinc-500">专案能将你的任务与档案集中管理。</p>
<button class="mt-4">建立专案</button>

搜寻与筛选的空状态应标示出查询字词并提供退出选项：“没有关于 'quarterly' 的结果。清除筛选”。切勿将关键的持久性资讯放在空状态中；因为一旦内容产生，空状态就会立刻消失。

12. 占位文字是示例，不是栏位标签

占位文字（Placeholder）展示的是预期格式（如 name@example.com、YYYY/MM/DD）。占位文字绝不能作为栏位的唯一标签：因为输入时它就会消失，每个栏位都必须保持显示可见的标签。

常见错误

常见错误	修正方案
局部重写忽略了产品既有的术语或语气	提出修改提案前，先检视附近的文案与风格指南
在指引性介面文案中使用“使用者”	直接以“你/您”称呼读者
“我们遇到了麻烦…”模糊了责任或恢复路径	使用直白的现状与下一步指引：“无法载入内容”
在破坏性确认对话盒中使用 OK / 是	重复操作后果：“删除专案”
步骤 2 用“继续”，步骤 3 用“下一步”	全程统一使用一组流程词汇
“点击这里”或孤立的“了解更多”连结	描述目的地：“阅读帐务文档”
“储存变更”与“舍弃变更”混用不同大小写规范	每种元素类型统一采用一种大小写规范
切换开关命名为“不要传送已读回执”	命名开启状态：“传送已读回执”
“哎呀！出错了。”	在出错栏位旁说明具体的解决步骤
将“没有结果。”作为整个空状态	说明定位并以下一步动作指引前行
用占位文字替代栏位标签	保持可见的标签；占位文字仅展示格式示例
"你有 " + n + " 则讯息"	使用完整的模版字串并搭配复数处理

审查输出格式

仅当使用者要求进行单项文案审查时使用此格式。当由 better-interface 统筹审查时，请将领域证据与发现提供给该 skill，并以其输出格式、严重度层级、整合规则、上限和最终结论为准。

单项审查报告分为两个部分呈现。

发现事项 (Findings)

按原则归类所有已确认的发现事项。使用包含 严重度 (Severity)、位置 (Location)、修改前 (Before)、修改后 (After) 与 原因 (Why) 栏位的 Markdown 表格。切勿使用单独的 "Before:" / "After:" 行。

• 严重度 (Severity)：HIGH 会误导使用者、隐瞒后果或阻碍恢复；MEDIUM 会降低任务的可理解度；LOW 属于单点的语气或一致性润饰。
• 位置 (Location)：引用 path/to/file:line。若产物没有源代码档案，则改为引用确切的画面与元件。
• 修改前 / 修改后 (Before / After)：引用当前的文案及其完整的替换内容。
• 原因 (Why)：指明违反的原则，并解释对理解力或信任度造成的损害。

将重复发生的系统性问题合并为一行，并列出所有受影响的位置。无发现事项的原则请直接省略。

范例

错误讯息应说明如何修复

严重度	位置	修改前	修改后	原因
MEDIUM	src/PasswordField.tsx:36	"Invalid password"	"Choose a password with at least 8 characters"	错误讯息必须说明如何解决问题
HIGH	src/Editor.tsx:81	"We couldn't process your request" Toast 提示	行内“无法储存。请检查你的连线后再试一次。”	当前的讯息既没有定位故障位置，也没有提供恢复指引

按钮动词优先

严重度	位置	修改前	修改后	原因
HIGH	src/DeleteDialog.tsx:29	删除确认对话盒中的 "OK"	"Delete project"	具有重大后果的操作必须重复说明后果
MEDIUM	src/Signup.tsx:54	"Let's go!"	"Create account"	标签必须明确命名具体的动作

验证与结论 (Verification and Verdict)

在发现事项之后：

1. 验证 (Verification)：列出执行的具体检查项与观察到的结果，适用的情况下包含完整流程、变数插值、单复数处理以及窄萤幕换行。若未执行某项检查，请说明仍需验证的事项。
2. 结论 (Verdict)：若仍存在任何 HIGH 发现事项则判为 Block；若仅存在 MEDIUM 或 LOW 发现事项则判为 Needs changes；仅在无任何需处理的发现事项时判为 Approve。

当没有任何发现事项时，省略表格，注明“无需处理的文案发现事项”，汇报验证情况，并以 Approve 结束。