ux-writing

UX 写作

为数字产品和体验撰写清晰、简洁、以用户为中心的界面文案（UX 文本／微文案）。此技能提供框架、模式和最佳实践，帮助创作能助力用户实现目标的文本。

兼容： Claude、Codex、Cursor 以及其他支持 Agent skills 规范的 Agent。

注意： 此技能适用于 Codex CLI/IDE，不适用于 ChatGPT。ChatGPT 无法安装或使用技能。

何时使用此技能

在以下情况使用此技能：

• 撰写界面文案（按钮、标签、标题、消息、表单）
• 编辑现有 UX 文本，使其更清晰、更有效
• 创建错误消息、通知或成功消息
• 设计对话流程或新手引导体验
• 为产品确立语气和风格
• 审查产品内容的一致性和易用性

UX 写作核心原则

四项质量标准

每段 UX 文本都应做到：

1. 有目的 — 帮助用户或业务实现目标
2. 简洁 — 在不损失含义的前提下尽可能精简
3. 对话化 — 听起来自然、亲切，而非机械
4. 清晰 — 含义明确、准确且易于理解

关键最佳实践

简洁

• 每行最多使用 40-60 个字符
• 每个词都要发挥作用
• 将密集文本拆分为便于浏览的小段
• 优先呈现重要信息

清晰

• 使用通俗易懂的语言（一般读者控制在 7 年级阅读水平，专业读者控制在 10 年级）
• 避免行话、习语和技术术语
• 全文使用一致的术语
• 选择有意义且具体的动词

对话式语气

• 按照日常说话的方式写
• 85% 的时间使用主动语态
• 加入介词和冠词
• 避免机械的措辞

以用户为中心

• 关注用户收益，而非功能
• 预判并回答用户的问题
• 使用第二人称（“你”）表达
• 符合用户的语言习惯和思维模式

UX 文本模式

将以下常见模式用于界面元素。

标题

• 目的：让用户了解自己所在的位置
• 格式：名词短语，句式大小写
• 类型：品牌标题、内容标题、类别标题、任务标题
• 示例：“账户设置”、“你的资料库”、“创建新帖子”

按钮和链接

• 目的：帮助用户执行操作
• 格式：主动祈使动词，句式大小写
• 模式：[动词] [对象]
• 示例：“保存更改”、“删除账户”、“查看详情”
• 避免：使用“确定”“提交”“点击此处”等泛化标签

错误消息

• 目的：说明问题并提供解决方案
• 格式：体贴、清晰、可执行
• 模式：[出了什么问题]。[原因/背景]。[该怎么做]。

错误消息类型

验证错误（行内）

• 用户填写字段时或离开字段时显示
• 提供简短、具体的输入修正指引
• 模式：[字段] [具体要求]
• 示例：
  • "Email must include @"（电子邮件地址必须包含 @）
  • "Password must be at least 8 characters"（密码至少需要 8 个字符）
  • "Choose a date in the future"（请选择一个未来的日期）
• 时机：实时显示或用户离开字段时
• 位置：字段下方或旁边

系统错误（模态框/横幅）

• 后端操作失败时显示
• 说明发生了什么以及原因
• 模式：[操作失败]。[可能原因]。[恢复步骤]。
• 示例：
  • "Payment failed. Your card was declined. Try a different payment method."（付款失败。您的银行卡被拒绝。请尝试其他付款方式。）
  • "Couldn't save changes. Connection lost. Reconnect and try again."（无法保存更改。连接已断开。请重新连接后重试。）
  • "Upload failed. File is too large. Choose a file under 10MB."（上传失败。文件太大。请选择小于 10MB 的文件。）
• 时机：失败后立即显示
• 位置：模态对话框或醒目的横幅

阻断错误（全屏）

• 问题解决前无法继续使用
• 清楚说明阻断原因和解决方法
• 模式：[受阻事项]。[原因]。[所需的具体操作]。
• 示例：
  • "Update required. This version is no longer supported. Update now to continue."（需要更新。此版本已不再受支持。请立即更新以继续使用。）
  • "Subscription expired. Your account is paused. Renew subscription to restore access."（订阅已过期。您的账户已暂停。请续订以恢复访问权限。）
  • "Verification needed. Confirm your email to access features. Check your inbox."（需要验证。请确认电子邮件地址以使用功能。请查看收件箱。）
• 时机：应用启动或访问功能时
• 位置：全屏或大型模态框

权限错误

• 请求权限前说明其好处
• 模式：[用户可获得的好处]。[所需权限]。
• 示例：
  • "Get notified when orders ship. Enable notifications."（订单发货时获取通知。请启用通知。）
  • "Find nearby stores. Allow location access."（查找附近的门店。请允许访问位置信息。）
  • "Back up your photos. Grant storage permission."（备份照片。请授予存储权限。）
• 时机：首次使用功能时
• 位置：功能相关的界面中

应避免的内容

• 没有解释的技术代码（“错误 403”）
• 责备用户的措辞（“输入无效”“非法字符”）
• 机械的语气（“发生了错误”）
• 没有后续处理方式的错误提示
• 模糊的原因（“出了点问题”）

成功消息

• 目的：确认操作已完成
• 格式：过去时态、具体、鼓励性
• 模式：[操作] [结果/好处]
• 示例：“更改已保存”“电子邮件已发送”“个人资料已更新”

空状态

• 目的：在内容为空时引导用户
• 类型：首次使用、用户清空、错误/无结果
• 格式：说明 + 引导用户添加内容的 CTA
• 示例：“暂无消息。开始对话，与团队建立联系。”

表单字段

• 标签：使用清晰的名词短语描述输入内容（“电子邮件地址”“电话号码”）
• 说明：以动词开头，解释为何需要这些信息
• 占位符：谨慎使用，仅用于“[email protected]”这类标准输入
• 辅助文本：根据重要程度，静态显示、按需显示或自动显示

通知

• 目的：及时传达有价值的信息
• 类型：需要采取行动（干扰性较强）、被动通知（干扰性较弱）
• 格式：以动词开头的标题 + 上下文说明
• 示例：“需要更新。请安装最新版本以继续使用。”

语气与风格

风格（统一的品牌个性）

风格是产品一贯的个性。可通过以下内容确立风格：

• 理念：3-5 个品牌核心原则/价值观
• 风格特点：描述每个理念的形容词
• 应做/不应做示例：展示风格如何具体体现的示例

创建风格图表时，请参阅 references/voice-chart-template.md。

语气（根据情境调整）

语气是指表达方式如何适应特定情境。虽然整体风格保持一致，但语气会根据用户情境和情绪状态进行调整。

语气变量

• 目的：用户为什么会看到这段文本（获取信息、执行操作、确认信息）
• 情境：用户正在尝试做什么（学习、完成任务、从错误中恢复）
• 情绪状态：用户可能的感受（沮丧、兴奋、困惑、谨慎）
• 风险：操作的影响（低：更改主题；高：删除账户）

根据用户情绪状态调整语气

沮丧（错误、失败、受阻）

• 富有同理心，并专注于解决问题
• 承认问题，不归咎于用户
• 提供明确的恢复途径
• 示例："付款失败。您的银行卡被拒绝。请尝试其他付款方式。"

困惑（初次使用、复杂功能）

• 耐心解释
• 清晰拆解步骤
• 提供背景信息和指导
• 示例："连接您的银行账户，即可查看消费洞察。我们会引导您完成操作。"

自信（日常任务、再次访问）

• 高效直接
• 尽量少做解释
• 快速确认
• 示例："已保存"

谨慎（高风险操作、数据丢失）

• 严肃、透明
• 清楚说明后果
• 尊重用户的决定
• 示例："删除账户？您将丢失所有数据，且此操作无法撤销。"

成功（完成任务、取得成就）

• 积极鼓励
• 语气与成就相称
• 简短庆祝
• 示例："个人资料已更新。您的更改已生效。"

根据内容类型调整语气

错误消息：富有同理心、令人安心、专注于解决问题

• 绝不归咎于用户
• 解释发生了什么
• 提供明确的下一步

成功消息：积极、具体、鼓励

• 确认发生了什么
• 语气与操作的重要性相称
• 简短清晰

说明：清晰、直接、实用

• 优先说明关键操作
• 必要时解释原因
• 使用简单的步骤

引导流程：友好、鼓励、简洁

• 欢迎用户，但不要让他们应接不暇
• 聚焦于价值
• 庆祝早期成果

确认信息：严肃、透明、尊重用户

• 清楚说明后果
• 不操纵用户
• 方便用户取消操作

空状态：积极、可操作、具有引导性

• 解释内容为空的原因
• 提供明确的下一步
• 保持鼓励的语气

编辑流程

分四个阶段编辑 UX 文本：

阶段 1：明确目的

• 文本是否帮助用户实现目标？
• 文本是否服务于业务目标？
• 用户能否清楚了解其价值？
• 是否预见并回应了用户的顾虑？

阶段 2：简洁

• 删除不必要的词语
• 合并重复信息
• 确保每个词都有存在的价值
• 将重要概念放在前面

阶段 3：对话化

• 朗读出来——你会这样说吗？
• 使用主动语态（除非被动语态更清晰）
• 加入自然的衔接词
• 避免企业套话

阶段 4：清晰

• 使用具体、准确的动词
• 保持术语一致
• 测试可读性（Hemingway Editor、Flesch-Kincaid）
• 确保含义明确

工作流

1. 了解情境

   • 用户目标和需求
   • 业务目标
   • 技术限制
   • 用户的情绪状态

2. 起草内容

   • 从对话开始（你会怎么说？）
   • 采用合适的模式
   • 考虑整体风格和语气
   • 将重要信息放在前面

3. 反复编辑

   • 阶段 1：明确目的
   • 阶段 2：简洁
   • 阶段 3：对话化
   • 阶段 4：清晰

4. 测试和衡量

   • 与团队一起审阅
   • 尽可能让用户参与测试
   • 衡量任务完成情况和理解程度
   • 根据反馈反复迭代

UX 写作中的无障碍设计

撰写无障碍内容，确保所有用户（包括使用辅助技术的用户）都能理解并使用您的产品。

无障碍核心原则

屏幕阅读器优化

• 明确标注所有交互元素（“提交表单”，而不只是“提交”）
• 使用描述性链接文本（“阅读定价详情”，而不是“点击此处”）
• 设计错误消息时，确保屏幕阅读器能正确朗读（同时读出错误和字段标签）
• 仅当视觉上下文不足时才使用 ARIA 标签

认知无障碍

• 每句以 8–14 个词为目标（8 个词 = 100% 理解率，14 个词 = 90%）
• 将复杂信息拆分为便于浏览的小块
• 使用清晰的标题和合理的层级
• 提供一致、可预测的模式

多模态沟通

• 不要只依靠颜色传达含义
• 将视觉提示与文本搭配使用（例如，红色图标配“错误：必须填写电子邮件”）
• 为图标和图片提供文本替代内容
• 确保颜色对比度足够（WCAG AA 最低标准：4.5:1）

人人易懂的语言

• 面向大众时，以 7–8 年级阅读水平为目标
• 首次使用技术术语时，先作出定义
• 避免使用习语、隐喻和文化典故
• 使用常见的日常用词

无障碍模式示例

按钮

• ❌ 不佳：“提交”（屏幕阅读器缺少上下文）
• ✅ 良好：“提交申请”

链接

• ❌ 不佳：“点击此处了解更多信息”
• ✅ 良好：“阅读我们的隐私政策”

错误消息

• ❌ 不佳：红色文本显示“无效”
• ✅ 良好：“错误：电子邮件必须包含 @”（配有错误图标）

表单标签

• ❌ 不佳：只有占位符的字段
• ✅ 良好：可见标签 + 可选占位符

UX 文本基准

使用这些基于研究的指标，编写有效的 UX 文本。

句子长度目标

按内容类型划分

• 按钮/CTA：理想长度为 2–4 个词，最多 6 个词
• 标题：3–6 个词，最多 40 个字符
• 错误消息：12–18 个词（包括解决方案）
• 说明：最多 20 个词，理想长度为 14 个词
• 正文：平均每句 15–20 个词
• 通知：标题和正文合计 10–15 个词

理解率

• 不超过 8 个词：用户理解率为 100%
• 不超过 14 个词：用户理解率为 90%
• 25 个词：理解率大幅下降前的上限

字符和行长

最佳范围

• 行长：40–60 个字符，最易阅读
• 按钮标签：15–25 个字符
• 页面标题：30–50 个字符
• 通知标题：35–45 个字符

阅读水平指南

按受众划分

• 大众：7–8 年级（Flesch-Kincaid）
• 专业工具：9–10 年级
• 技术产品：10–11 年级
• 专业领域：11–12 年级（仅在必要时）

测试工具

• Hemingway Editor：突出显示复杂句子
• Readable.com：提供多种易读性评分
• Microsoft Word：内置 Flesch-Kincaid 评分

应避免的常见错误

• 过度使用被动语态
• 使用泛泛的按钮标签（“提交”“确定”）
• 在错误消息中责怪用户
• 在严肃场合使用过于俏皮的幽默
• 术语使用不一致
• 隐藏说明或解释
• 使用面向系统而非面向用户的语言
• 用词过多（不够简洁）
• 语气生硬、官腔十足
• 只依靠颜色表达含义
• 编写不易理解的链接文本（“点击此处”）

快速参考

句首字母大写：“Save your changes”（而不是“Save Your Changes”）
按钮使用主动祈使句：“Delete account”（而不是“Account deletion”）
以用户为中心：“Save time with shortcuts”（而不是“We offer shortcuts”）
使用具体动词：永久删除时用“Delete”（而不是“Remove”）
关键信息前置：“Password must be 8 characters”（而不是“Must be 8 characters for your password”）

资源

此技能包含：

• references/accessibility-guidelines.md：为所有用户编写无障碍 UX 文案的综合指南
• references/voice-chart-template.md：创建产品语调图表的模板
• references/content-usability-checklist.md：评估 UX 文案质量的综合检查清单
• references/patterns-detailed.md：不同语调的 UX 文案模式扩展示例
• examples/real-world-improvements.md：包含详细分析和评分的改进前后对比
• templates/error-message-template.md：编写有效错误消息的可填写模板
• templates/empty-state-template.md：创建实用空状态的指南
• templates/onboarding-flow-template.md：设计清晰引导体验的框架
• docs/figma-integration.md：将此技能与 Figma MCP（Claude Code、Codex 和 Cursor）配合使用的指南