用 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.mdTrae 中文目录镜像与 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 polishskill/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 labelsplaceholder 只是示例不能替代标签——一旦用户开始输入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 文本要传达图片承载的信息纯装饰性图片用空 altalt避免读屏用户被噪声打断。无障碍与信息呈现的三条红线读屏名称与可见标签、结果保持一致——用户听到的控件名必须和看到的按钮字一模一样不能一个是“删除项目”一个是“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” 的检查项。两个命令各司其职、有明确的交接点而不是在同一个文件上无限叠加编辑轮次。九、一页纸速查把 clarify 方法论固化成清单是否已明确受众知识与情绪状态高风险/高压力场景删除、支付、隐私优先于常规场景处理。是否读了完整交互路径而非单个字符串标题、按钮、toast、空态、后续页是否语义连续每个状态是否回答四问现在的事实 → 可用动作 → 会改变决策的上下文 → 恰当语气破坏性动作是否点名对象与后果可恢复的用 Undo确认框与按钮是否使用同一动作动词而非Yes/OK表单是否有常驻标签要求是否在提交前给出校验是否指出问题与改法、且不指责用户错误是否回答“什么失败/为什么/如何恢复”内部错误码是否没有充当主消息加载是否写真实操作、不虚构进度空状态是否区分首次/无结果/筛选/权限/失败成功是否简短是否写成可翻译的完整消息、结构化变量、允许长度扩展是否在同一概念上保持统一术语读屏名称是否与可见标签一致是否不只依赖颜色/图标/标点表意是否在目标宽度、200% 缩放下验证换行与可扫读语气是否匹配后果是否符合“不能再短而不丢失意义与恢复路径”的收敛判据文案干净后是否已交接给/impeccable polish做最终质量收口把这套清单交给 Agent 作为clarify的执行模板它就拥有了从“改字”升级为“系统化澄清界面语义”的完整决策框架——这正是这份参考文档真正的价值所在它训练的是一种先判断信息优先级、再按功能与情绪选择写法、最后在上下文中验证的文案工程能力。【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考