用 impeccable clarify 打磨界面文案：从“用户看不懂”到“发生了什么、为什么、下一步做什么”-开发者社区

用 impeccable clarify 打磨界面文案：从“用户看不懂”到“发生了什么、为什么、下一步做什么”

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable

本文是一份面向 AI Agent 与前端开发者的 UX 文案（microcopy / interface copy）实操指南，讲解 Impeccable 设计技能中clarify命令（Fix/修复类目）的方法论与执行规范。它回答的是界面中一个高频真实问题：当错误信息、表单校验、空状态、按钮标签让用户产生困惑、焦虑或误操作时，如何在不改变产品事实与品牌语气的约束下，把文案改写成“用户能立刻理解发生了什么、什么重要、下一步该做什么”的清晰语言。读完本文，你将掌握一条可复用的四步文案手术流程——全路径语言审计、信息层级决策、按功能分类重写、系统化验证——并了解它如何在 Impeccable 命令体系中与audit、polish、onboard、harden等命令衔接协作。

一、clarify 是什么：它在 Impeccable 技能体系中的位置

Impeccable 是一个面向前端界面设计工作的 Agent 技能包（仓库根目录的 skill/SKILL.src.md 是其主入口）。它把复杂的设计工作组织成一组以斜杠命令触发的子命令，按类目划分为 Build（构建）、Evaluate（评估）、Refine（精修）、Enhance（增强）、Fix（修复）、Iterate（迭代）等。其中clarify属于Fix 类目，官方描述为：

clarify [target]— Fix — Improve UX copy, labels, and error messages（改进 UX 文案、标签和错误信息）

在 skill/scripts/command-metadata.json 的命令元数据里，它的触发场景被扩展得更完整：

"Improve unclear UX copy, error messages, microcopy, labels, and instructions to make interfaces easier to understand. Use when the user mentions confusing text, unclear labels, bad error messages, hard-to-follow instructions, or wanting better UX writing."

也就是说，当用户提到“这段文案很绕”“这个报错看不懂”“标签不清不楚”“说明很难照做”或明确要求“更好的 UX 写作”时，Agent 就应当路由到clarify。而在 scripts/lib/skill-categories.js 的分类实现里，clarify与distill同属 "SIMPLIFY - reduce and clarify"（简化——删减与澄清）语义簇，说明它的本质目标不是“写得更花哨”，而是通过删减歧义与冗余，让界面信息变简单、可理解。

clarify的参考文档在仓库中有多处镜像副本——因为 Impeccable 会把同一套参考文档同步到各 AI 工具各自的技能目录（详见 scripts/build.js 中的同步逻辑与 deprecated skill 清理表），例如 skill/reference/clarify.md（本体）、.trae-cn/skills/impeccable/reference/clarify.md（Trae 中文目录镜像）与 plugin/skills/impeccable/reference/clarify.md（共享插件子树）。它们内容一致，本文即基于这份参考文档展开。

触发与调用方式

根据 skill/SKILL.src.md 的路由规则，clarify是带[target]参数的子命令，可用npx impeccable clarify [target]、/impeccable clarify [target]或对应工具前缀（如{{command_prefix}}impeccable clarify）触发。参考文档开头的元信息（> **Additional context needed**: audience knowledge and emotional state.）点明了执行此命令前的两个必补上下文：

受众知识（audience knowledge）：这条界面文案写给谁？目标用户对产品领域、术语、技术背景有多少既有认知？
情绪状态（emotional state）：用户此刻处于什么情境？是首次试用、提交失败、即将执行不可逆删除，还是刚完成一次成功操作？

缺少这两项输入，任何“改写”都是盲改——因为同一条文案在不同受众与情绪下的最优写法可能截然相反。

一条清晰的工作流

把clarify.md与相邻参考文档对照，可以看到它的执行边界与上下游衔接：

上游（发现）：audit（技术质量检查，见 skill/reference/audit.md）负责从无障碍、性能、响应式等维度扫出“文案是否可达”；而clarify接手的是“文案是否可懂、可行动”这一语义层。
执行主体：clarify只在文案语义层作业，不负责把按钮做更大或重排布局（那是layout/adapt的事）。
下游（收尾）：参考文档最后一句明确要求——当文案读起来已经干净清晰后，交给/impeccable polish（skill/reference/polish.md）做最终的质量把关（alignment、spacing、一致性等视觉与微细节层面）。

二、核心前提：先读懂用户，再动笔改文案

参考文档给出的总纲值得逐字拆解：

Rewrite unclear interface text so users understand what happened, what matters, and what to do next. Preserve factual meaning, product terminology, and brand voice.

（重写不清晰的界面文本，让用户理解：发生了什么、什么重要、接下来做什么。保留事实含义、产品术语与品牌语气。）

这一定义设置了三条不可逾越的改写红线，也是 Agent 判断“该不该动这句话”的边界：

红线	含义	违反后果示例
Preserve factual meaning	事实性含义必须保留，不得增删或歪曲	把“每 24 小时同步一次”写成“实时同步”
Preserve product terminology	产品术语要保持原样，不能为通俗而牺牲准确	把用户已学会的“工作区（Workspace）”换成“文件夹”
Preserve brand voice	品牌语气要延续，不能因追求“友好”而风格跳变	严肃的财务工具突然出现网络流行语

参考文档同时给了兜底条款：“Infer audience and task from product context and surrounding UI.Ask before changing factual claims, legal meaning, or a term that may be domain-specific.”（从产品上下文与周边界面推断受众与任务；在改动事实性陈述、法律含义或可能属于领域专有的术语之前，必须先询问用户。）这与 skill/reference/polish.md 中“Ask before changing claims”（改动任何声明前先询问）的口径完全一致——澄清的任务是让表达变清楚，不是替产品团队做事实决策。

三、第一步：审计语言——读全路径，而非孤立字符串

参考文档的核心方法论第一条是：Read the entire interaction path, not isolated strings.（阅读完整交互路径，而不是孤立的字符串。）UI 文案的歧义往往不在单句内部，而在句子与句子、状态与状态之间。一个“删除成功”的 toast 本身没问题，但如果它前面是“确认删除这个项目？”的确认框、按钮叫“确定”，整条路径的语义就是脱节的。

执行审计时，需逐项排查以下语言病灶（即“要找出什么”）：

模糊的名词、动词与动作：如“项目”“处理”“更新”这类在不同上下文里指代不同的词；
内部黑话与隐含知识：代码层术语直接裸露到界面（如把 API 状态码“401”“配额超限”当主消息展示），或默认用户了解产品内部机制；
含糊的标签、结果与系统状态：看不出“这个开关控制什么”“现在系统处于什么阶段”；
缺失的后果、恢复路径或时间信息：报错只说“失败”，不说是否已回滚、数据是否安全、何时能重试；
术语与大小写不一致：同一概念在导航、标题、按钮、正文里叫法不一（如 “Login / Sign in / 登录”混用）；
冗余的标题、引言、帮助文本与确认：标题已经把状态说清楚了，正文又来复述一遍；确认框已经写清动作，按钮却只写“是”；
在真实宽度或翻译环境下会断裂的文本：未考虑按钮宽度放不下、德语/俄语等语言的超长词导致布局破裂；
忽视压力、风险、成功或紧迫性的语气：删除账户与点赞成功用同一语气，就是语气失当。

判断“模糊”的依据不是文案作者的主观喜好，而是周围 UI 与产品上下文共同揭示的受众与任务——这也再次呼应了开头“需要受众知识与情绪状态”两个输入项。

四、第二步：建立信息层级——每个状态只回答四个问题

在动笔改写之前，clarify要求先为每一个界面状态做一次信息优先级决策。参考文档给出四层金字塔：

用户此刻需要知道的唯一事实（The one fact the user needs now）——最高优先级；
下一步可用的动作（The action available next）；
会改变决策的支撑性上下文（Supporting context that changes the decision）——只有真正影响判断的细节才该出现；
适合此刻的语气（The appropriate tone for this moment）。

配套的写作纪律是：Say each idea once.（每个想法只说一遍。）若标题已经说明了状态（如“无法连接到服务器”），那么引言要么补充新信息（如“我们会在 30 秒后自动重试”），要么干脆消失。这正是信息层级思维与“堆文案”的分水岭：层叠冗余的说明不产生信息量，只增加认知负担。

这一点同样体现在 Impeccable 相邻命令的理念里——skill/reference/distill.md 的精简准则同样强调 “No headers restating intros, no repeated explanations, say it once”；clarify在做语义澄清，distill在做整体删减，二者共享“一次只表达一遍”的核心纪律。

五、第三步：按功能分类重写——五类界面文案的手术规范

参考文档把界面文案按功能角色拆成五类，每一类都有独立的改写规范。这是整份文档里实操密度最高的部分。

5.1 动作与导航（Actions and navigation）

当结果并非不言自明时，使用具体的“动词 + 宾语”。标签要描述“点击后会发生什么”，而不是描述触发它的手势或隐喻。例如 “下一步”不如“保存并继续”，“点击这里”应改为对动作本身的描述。
同一概念在产品内保持同一组名词与动词——这是术语一致性的最小单位。
破坏性动作必须点名对象与后果：明确写出被删的对象和不可逆的代价（如“删除 23 个未同步的草稿记录”而非“删除”）。
安全前提下优先用 Undo 而非二次确认：可恢复的操作，提供“撤销”按钮的价值高于让用户再点一次弹窗。
确有必要确认时，消息和按钮上都要写清动作名称，而不是用通用的Yes/No/OK/Submit。按钮文字应与确认内容一致（消息说“删除项目？”按钮就应是“删除项目”，而不是“确定”），从而形成语义闭环。

5.2 表单（Forms）

使用常驻标签（persistent labels）；placeholder 只是示例，不能替代标签——一旦用户开始输入，placeholder 就消失了，若它还承载字段说明，等于让用户失忆。
格式与资格要求要在提交之前给出（如密码位数、文件类型、命名规则），而不是等用户填错提交后再用校验报错告知。
仅在信息用途不明显时才解释“为什么收集它”（如询问手机号时说明“用于接收验证码”）。
必填与选填的处理必须一致：同一种视觉约定全站统一，不要让用户在一处习惯、在另一处迷惑。
校验信息的写法：指出需要关注什么 + 如何修正，且不指责用户（不说“你填错了”，而说“密码至少需要 8 位，当前为 5 位”）。
相关指导文本放在字段附近；错误要以无障碍可宣告的方式被读屏软件获知（详见第七节）。

5.3 错误与权限（Errors and permissions）

一条“可行动的错误消息”必须回答三个问题（这也是 Agent 重写报错时的固定检查项）：

什么失败了（what failed）；
为什么——当原因已知且有用时（why, when known and useful）；
如何恢复，或还有什么替代方案（how to recover or what alternative remains）。

配套的硬性纪律包括：

不要把内部错误码当作主消息暴露给用户（“Error 0x80070057”不能是正文，最多作为技术附注）；
不要承诺系统其实无法知晓的原因或解决方案——比如不确定时不要写“您的网络有问题”，写“无法连接到服务器，请稍后重试”即可；
对待隐私、支付、删除、访问权丢失与被阻塞的工作，要严肃：语气可以温暖，但不能开玩笑。这类场景用户处于高压力情绪，任何俏皮话都会被误读为轻慢。

5.4 加载、空状态与成功状态（Loading, empty, and success states）

加载文案要说出真实操作名（“正在上传第 2 份文件”而非“请稍候”），并在等待确有意义时设定诚实预期。有确定进度就展示进度条；绝不虚构进度（比如系统实际无法估算时，不要伪造“还剩 10 秒”）。

空状态要先分辨它是哪种“空”：首次使用（first use）、无搜索结果（no results）、被筛选清空（filters）、无权限（permissions）还是出错（failure）。不同原因要给出不同解释与下一步动作——例如“暂无搜索结果”应跟“换个关键词试试”或“清除筛选条件”，而“首次使用”应引导去创建第一个对象。这与 skill/reference/onboard.md 对 first-run / empty-state 的设计指导相互印证：clarity 负责把“现在是什么状态、接下来能做什么”写清楚，onboard 负责把整个首次体验流程设计对。

成功状态要确认已完成的结果；只有当“下一个后果会改变用户该做什么”时才提及它（例如“已保存。您的更改将在 2 小时内对所有访问者生效。”）。日常性的成功应保持简短——把每个操作都庆祝一遍，会稀释真正重要时刻的信号。

5.5 帮助与说明性文本（Help and instructional text）

帮助文本应回答一个隐含的问题，而不是复述控件本身（输入框旁写“用于登录邮箱”而非“邮箱”）。
不常见或很深的细节用**渐进披露（progressive disclosure）**承载——默认折叠成“了解更多”，需要时再展开，避免常态界面信息过载。
链接文本离开上下文也要能独立成义（“了解定价方案”好于“点此/了解更多”这种悬空链接）。
纯图标控件需要无障碍可访问名称（accessible name），不能只有视觉图形。

六、Voice、无障碍与本地化：把文案写成可翻译、可朗读、可缩放的语言

这一节把界面的语气（voice）、无障碍（accessibility）与国际化（localization）拧成一套可执行规则。

Voice 与语气分层：Voice（品牌一贯的声音）保持稳定，Tone（面对当下情境的语气）随之调整——这是回扣“情绪状态”输入项的关键。始终使用平实语言，但不要为了“通俗”而抹平用户真正掌握的领域术语——术语是被信任的专业性，不是敌人。

面向翻译（i18n）与无障碍的四条硬性写法：

写完整、可翻译的整句消息，而不是拼接的碎片。"Hello, " + name + ", you have " + count + " messages"在英语里勉强能读，但在词序不同的语言里根本无法翻译；应写成带占位符的完整模板，如"You have {count} new messages."。
把变量与数字结构化成翻译者可以重排的形式（结构化占位符而非硬拼接），让译者按目标语言的自然语序自由摆放。
允许文本扩展，不要过早缩写。界面文案要为本地化后的长度增长预留空间（德语、俄语、芬兰语通常比英语长 30% 以上），并在第七节验证里在 200% 缩放下实测。
alt 文本要传达图片承载的信息；纯装饰性图片用空 alt（alt=""），避免读屏用户被噪声打断。

无障碍与信息呈现的三条红线：

读屏名称与可见标签、结果保持一致——用户听到的控件名必须和看到的按钮字一模一样，不能一个是“删除项目”一个是“OK”；
不要依赖标点、颜色或图标单独承载信息——色弱用户看不出“红色=错误”，只靠 ❗ 也无法表意，必须搭配文字；
成功/错误等状态变化要能被无障碍地宣告（如通过 aria-live 区域让读屏实时播报），不能只在视觉上悄悄变化。

最后，当术语不一致已经蔓延到整个产品时，维护一份简短的术语表（terminology glossary）；界面不是文学创作，不要为了“文学效果”在同一概念上变换用词——变化制造不确定。

七、第四步：验证——在上下文里重读，而不是逐行重读

改完不等于改对。参考文档要求在流程上下文中（in context）重读文案，并对下列维度逐项测试：

无需隐藏产品知识即可理解（comprehension without hidden product knowledge）——把文案拿给“不知情读者”视角检查，能否看懂？
错误态、空态与决策点的可行动性（actionability）——用户在每个停顿点是否知道下一步点哪里？
事实准确与术语一致（factual accuracy and consistent terminology）——没有在重写中偷换事实？
目标宽度与 200% 缩放下的可扫读性（scanability at target widths and 200% zoom）——放大两倍后是否换行破碎、信息是否仍能一眼扫到重点；
长名称、本地化扩展、复数形式与动态值——1 filesvs1 file、多语言数字格式、超长用户名截断等边界；
可访问名称与状态变化宣告；
与后果和情绪情境相匹配的语气。

验证的收敛判据是一句可执行的标尺：

The final copy is as short as it can be without removing meaning or recovery.

（最终文案应短到——在不删除意义或恢复路径的前提下——不能再短。）

这条判据说明clarify的产出不是“最短”而是“恰好短”：删到仍能传达意义、仍能给出恢复办法为止。写完后再回头读一遍交互路径，确认每个状态仍然四问齐全（事实 → 动作 → 支撑上下文 → 语气）。

八、收尾：何时结束 clarify，何时交给 polish

参考文档的最终工作流指令非常明确：当文案读起来已经顺畅清晰（the language reads cleanly）时，交给/impeccable polish做最后一道检查。

这条交接边界与 Impeccable 的整体哲学一致——在 skill/SKILL.src.md 的开篇原则里写着 “Verify in bounded passes, not a loop”：构建完整、批量检查一次、修复、最多再确认一轮，然后停止打磨。clarify只处理文案语义层，polish则在其后把界面在视觉、对齐、间距、术语大小写与最终一致性上收口（参考 skill/reference/polish.md 中 “Keep terminology, capitalization, punctuation, and factual copy consistent” 的检查项）。两个命令各司其职、有明确的交接点，而不是在同一个文件上无限叠加编辑轮次。