ux-writing-content-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

UX Writing & Content Design

UX写作与内容设计

Purpose

目的

Help an AI agent write and evaluate product copy that helps people understand an interface, take action, recover from problems, and trust the product. Treat words as part of the design system and interaction model, not as decoration added after the interface is finished.

This skill covers product UX copy: microcopy, button labels, links, labels, hints, descriptions, empty states, onboarding, validation, errors, success messages, loading/progress states, notifications, terminology, voice, tone, and content strategy. It does not cover long-form marketing copy except when that copy directly affects product comprehension, action, trust, onboarding, or conversion inside a product experience.

帮助AI Agent撰写和评估产品文案，助力用户理解界面、执行操作、解决问题并信任产品。将文字视为设计系统和交互模型的一部分，而非界面完成后添加的装饰。

本技能涵盖产品UX文案：微文案、按钮标签、链接、标签、提示、说明、空状态、引导流程、验证提示、错误提示、成功消息、加载/进度状态、通知、术语、语气语调及内容策略。除非长营销文案直接影响产品体验内的用户理解、操作、信任、引导或转化，否则本技能不涉及长营销文案。

When to use this skill

何时使用本技能

Use this skill when the user asks you to:

Write, rewrite, or critique UI text, product copy, UX copy, microcopy, form copy, navigation labels, CTAs, onboarding, empty states, errors, confirmations, loading states, notifications, help text, or design-system content guidance.
Review a UI, mockup, screenshot, frontend component, flow, prototype, or design system for clarity, tone, usability, trust, recovery, or accessibility.
Design or implement frontend states where copy affects user understanding or behavior.
Create content rules, voice and tone guidance, terminology, content patterns, or a UX writing checklist.

当用户要求你执行以下操作时，使用本技能：

撰写、重写或评审UI文本、产品文案、UX文案、微文案、表单文案、导航标签、CTA、引导流程、空状态、错误提示、确认消息、加载状态、通知、帮助文本或设计系统内容指南。
审查UI、原型图、截图、前端组件、流程、原型或设计系统的清晰度、语气、可用性、可信度、故障恢复能力或无障碍性。
设计或实现文案会影响用户理解或行为的前端状态。
创建内容规则、语气语调指南、术语、内容模式或UX写作检查清单。

When not to use this skill

何时不使用本技能

Do not use this skill as the primary skill for:

Long-form marketing pages, ads, brand campaigns, PR, SEO articles, or sales copy unless they affect an in-product UX flow.
Pure visual styling, layout, illustration, or animation tasks where no interface text, state, or comprehension issue is involved.
Legal, medical, financial, or compliance wording that requires a licensed professional. You may improve clarity, but flag the need for expert review.
Translation/localization itself. Use this skill to make source copy localizable and context-safe, then use translation/localization expertise separately.

以下场景请勿将本技能作为主要技能使用：

长营销页面、广告、品牌活动、公关、SEO文章或销售文案，除非它们影响产品内的UX流程。
纯视觉样式、布局、插画或动画任务，且不涉及界面文本、状态或理解问题。
需要专业资质的法律、医疗、金融或合规文案。你可以优化清晰度，但需标注需要专家审核。
翻译/本地化本身。使用本技能使源文案具备可本地化性和上下文安全性，再单独使用翻译/本地化专业技能。

Core principles

核心原则

Words are design material. Do not merely choose “nice words.” Use words to solve user problems and shape interaction behavior.
Start with the user task and product purpose. Copy is effective only when it supports what the user is trying to do and what the product legitimately needs.
Prefer useful over clever. Personality and delight are secondary to comprehension, action, trust, and recovery.
Design the conversation, not isolated strings. Inspect the entry point, action, system response, next step, inverse action, and failure path.
Use the right pattern for the state. A label, hint, tooltip, inline error, banner, empty state, notification, or confirmation each has a different job.
Write in context. Draft and evaluate text where it appears, with surrounding UI, component constraints, state, platform, and device.
Make actions consequence-revealing. Buttons and links should say what happens, not describe the input method.
Errors are stress cases. Avoid the error when possible, explain clearly when it happens, and help the user resolve it.
Respect people on the margins. Sensitive questions, forced choices, default suggestions, and “harmless” quick replies can exclude or hurt people.
Be concise, not cryptic. Short copy is valuable only when users can still understand it immediately.
Measure when the stakes justify it. Use usability testing, behavioral metrics, support data, and A/B tests when copy changes affect activation, conversion, retention, recovery, or trust.
Make copy implementable. Content should work with semantic HTML, accessibility APIs, localization, design tokens, component states, and design-system patterns.

See references/principle-cards.md for each principle as a reusable card.

文字是设计素材：不要仅仅选择“好听的词”，要用文字解决用户问题并塑造交互行为。
从用户任务和产品目标出发：只有当文案支持用户的目标和产品的合理需求时，才是有效的。
实用优先于巧妙：个性和愉悦感次于理解、操作、信任和故障恢复。
设计对话而非孤立字符串：检查入口点、操作、系统响应、下一步、反向操作和失败路径。
为状态选择合适的模式：标签、提示、工具提示、内联错误提示、横幅、空状态、通知或确认消息各自有不同的作用。
结合上下文撰写：在文案出现的位置，结合周围UI、组件限制、状态、平台和设备来撰写和评估文本。
让操作揭示后果：按钮和链接应说明会发生什么，而非描述输入方式。
错误是压力场景：尽可能避免错误，发生时清晰解释，并帮助用户解决问题。
关注边缘用户：敏感问题、强制选择、默认建议和“无害”快速回复可能会排斥或伤害用户。
简洁而非晦涩：只有当用户仍能立即理解时，简短文案才有价值。
必要时进行衡量：当文案变化影响激活、转化、留存、故障恢复或信任时，使用可用性测试、行为指标、支持数据和A/B测试。
使文案可落地实现：内容应与语义HTML、无障碍API、本地化、设计令牌、组件状态和设计系统模式兼容。

查看references/principle-cards.md获取可复用的单条原则卡片。

Default recommendations

默认建议

Use these defaults unless the user provides stronger product-specific context.

Area	Default recommendation	Why it is usually best	Override when	Ask before overriding
Product goal	Help the user complete the immediate task with minimal uncertainty.	Most product copy is functional and users are not there to read.	The flow intentionally teaches, warns, or changes a high-stakes decision.	Ask what outcome matters most: comprehension, conversion, completion, retention, safety, or support reduction.
Audience	Write for a broad, busy, mixed-ability audience using plain language.	It reduces cognitive load and improves accessibility/localization.	The product serves a specialized expert audience with necessary domain terms.	Ask whether the audience expects domain-specific terminology.
Voice	Professional, warm, direct, and human.	Works for most SaaS, productivity, commerce, and public-service products.	A documented brand voice or regulated tone exists.	Ask for the brand personality or voice chart.
Tone	Calm and helpful. Match emotional stakes.	Users often encounter copy during uncertainty or interruption.	Success/delight states can support more warmth; severe or sensitive states require restraint.	Ask how stressful or sensitive the moment is.
CTA labels	Verb-led, specific, 1–3 words where possible; include object or consequence when needed.	Users make decisions at buttons and links.	Legal, destructive, paid, or irreversible actions need more specificity.	Ask what exactly happens after the action.
Form labels	Persistent visible labels above or beside fields; hints only for extra guidance.	Labels remain available after entry and support accessibility.	Very constrained UI already has a tested accessible pattern.	Ask about platform/component constraints.
Placeholder text	Use only for examples or formatting, never as the only label.	Placeholders disappear, can be low contrast, and are weak accessibility support.	A design system provides accessible floating labels.	Ask whether the component has accessible labels and error associations.
Help/instruction copy	Put guidance near the action only when the label alone is insufficient.	Extra text can help, but unnecessary instruction creates reading burden.	The task is unfamiliar, high-risk, or constrained by policy/format.	Ask what users commonly misunderstand.
Sensitive data requests	Explain why the data is needed and how it will be used.	Context improves trust and reduces harm for users who do not fit simple categories.	The reason is obvious and the data is not sensitive.	Ask why the product needs the information and whether users can skip it.
Error handling	Avoid first, explain second, resolve third.	Prevention reduces friction; recovery copy must still help when prevention fails.	A backend or legal constraint prevents prevention.	Ask what recovery actions are technically available.
Disabled controls	Do not rely on disabled UI as the only instruction.	Disabled controls can be inaccessible and leave users stuck.	Progressive activation is supplemented with accessible status/help.	Ask whether the disabled control has an accessible explanation.
Empty states	State what is empty, why it matters, and the next useful action.	Empty states are onboarding and recovery opportunities.	The absence is self-evident and no action is available.	Ask what the user can do next.
Success messages	Confirm what happened and, when useful, the next step or consequence.	Users need closure and sometimes need to know visibility, delivery, or reversibility.	The UI state itself clearly shows completion.	Ask whether success changes visibility, billing, permissions, or data.
Loading/progress	Say what is happening and set expectation if delay is noticeable.	Feedback reduces anxiety during wait states.	The delay is imperceptible.	Ask whether duration is known or variable.
Notifications	Send only timely, relevant, actionable messages.	Notifications interrupt; value must exceed interruption cost.	Compliance or operational needs require non-actionable notice.	Ask what user action or decision the notification supports.
Delight	Add personality only after the copy is functional, useful, and emotionally appropriate.	Humor can help in success or low-stress moments and harm in error/stress moments.	Brand voice is intentionally playful and the state is safe.	Ask whether the moment is stressful, sensitive, or irreversible.
Metrics	Use task success and comprehension first; use conversion only when aligned with user benefit.	Copy should not manipulate users away from their goals.	The business goal is the explicit optimization target.	Ask which metric and guardrail metric matter.
Accessibility level	Meet WCAG-aligned product basics: labels, programmatic errors, focus, keyboard, screen-reader states, readable text.	Accessibility is usability and exclusion is a design choice.	Higher conformance is required by policy.	Ask about required accessibility standard if compliance matters.
Localization	Avoid idioms, culture-specific jokes, compact strings that cannot expand, and ambiguous variables.	Product copy often becomes UI strings; localization can break layout and meaning.	Product is single-locale and will remain so.	Ask whether the product will be translated.

除非用户提供更明确的产品特定上下文，否则使用以下默认建议。

领域	默认建议	通常最优的原因	何时覆盖默认	覆盖前需询问
产品目标	帮助用户以最小的不确定性完成当前任务。	大多数产品文案是功能性的，用户并非为阅读而来。	流程旨在刻意引导、警告或改变高风险决策时。	询问最关键的结果：理解、转化、完成、留存、安全还是减少支持需求。
受众	使用平实语言为广泛、忙碌、混合能力的受众撰写。	降低认知负荷，提升无障碍性/可本地化性。	产品服务于需要特定领域术语的专业受众时。	询问受众是否期望使用领域特定术语。
语气	专业、亲切、直接且人性化。	适用于大多数SaaS、生产力、电商和公共服务产品。	存在已记录的品牌语气或受监管的语调时。	询问品牌个性或语气图表。
语调	冷静且有帮助，匹配情绪风险。	用户通常在不确定或被打断时接触文案。	成功/愉悦状态可更亲切；严重或敏感状态需克制。	询问该场景的压力或敏感程度。
CTA标签	以动词开头，尽可能简洁为1-3个词；必要时包含对象或后果。	用户在按钮和链接处做决策。	法律、破坏性、付费或不可逆操作需要更明确的说明时。	询问操作后具体会发生什么。
表单标签	持久可见的标签置于字段上方或旁边；仅在需要额外指导时使用提示。	标签在输入后仍可见，支持无障碍性。	受限UI已有经过测试的无障碍模式时。	询问平台/组件限制。
占位符文本	仅用于示例或格式说明，绝不能作为唯一标签。	占位符会消失，对比度可能较低，无障碍支持较弱。	设计系统提供无障碍浮动标签时。	询问组件是否有无障碍标签和错误关联。
帮助/说明文案	仅当标签本身不足以说明时，在操作附近放置指导内容。	额外文本有帮助，但不必要的说明会增加阅读负担。	任务陌生、高风险或受政策/格式限制时。	询问用户通常会误解什么。
敏感数据请求	说明需要数据的原因及使用方式。	上下文可提升信任，减少不符合简单分类的用户受到的伤害。	原因显而易见且数据不敏感时。	询问产品需要该信息的原因及用户是否可以跳过。
错误处理	优先避免，其次解释，最后解决。	预防可减少摩擦；预防失败时，恢复文案仍需提供帮助。	后端或法律限制无法预防错误时。	询问技术上可行的恢复操作。
禁用控件	不要仅依赖禁用UI作为唯一说明。	禁用控件可能无法访问，导致用户陷入困境。	渐进式激活辅以无障碍状态/帮助时。	询问禁用控件是否有无障碍说明。
空状态	说明内容为空、其重要性以及下一步有用操作。	空状态是引导和恢复的机会。	内容缺失显而易见且无可用操作时。	询问用户下一步可以做什么。
成功消息	确认已发生的操作，必要时说明下一步或后果。	用户需要闭环，有时需要了解可见性、交付或可逆性。	UI状态本身已清晰显示完成时。	询问成功是否会改变可见性、计费、权限或数据。
加载/进度	说明正在发生的事情，若延迟明显则告知预期时长。	反馈可减少等待时的焦虑。	延迟难以察觉时。	询问时长是否已知或可变。
通知	仅发送及时、相关且可操作的消息。	通知会打断用户，其价值必须超过打断成本。	合规或运营需求要求发送不可操作的通知时。	询问通知支持的用户操作或决策。
愉悦感	仅在文案具备功能性、实用性且情绪合适后添加个性元素。	幽默在成功或低压力场景有帮助，但在错误/压力场景可能造成伤害。	品牌语气刻意活泼且场景安全时。	询问该场景是否有压力、敏感或不可逆。
指标	优先使用任务成功和理解度；仅当与用户利益一致时使用转化率。	文案不应误导用户偏离其目标。	业务目标是明确的优化目标时。	询问关键指标和防护指标。
无障碍级别	满足WCAG对齐的产品基础要求：标签、程序化错误提示、焦点、键盘操作、屏幕阅读器状态、可读文本。	无障碍即可用性，排斥是设计选择。	政策要求更高合规性时。	若合规重要，询问所需的无障碍标准。
本地化	避免习语、特定文化笑话、无法扩展的紧凑字符串和模糊变量。	产品文案通常会成为UI字符串；本地化可能破坏布局和含义。	产品仅面向单一语言环境且将保持不变时。	询问产品是否会被翻译。

Required user questions

需向用户询问的问题

Do not ask routine best-practice questions such as whether text should be clear, concise, or accessible. Apply the defaults.

Ask only when the answer materially changes the copy, pattern, tone, or implementation. Ask one focused question at a time unless the user explicitly asks for a full discovery pass.

Ask when any of these are missing and necessary:

The primary user task or feature outcome is unclear.
The audience is specialized, vulnerable, multilingual, very young/old, regulated, or otherwise context-dependent.
The flow asks for sensitive personal data, legal consent, payment, health, identity, security, or irreversible action.
The requested tone conflicts with user stress, inclusion, accessibility, or trust.
The copy depends on a technical constraint, backend validation, recovery path, design-system pattern, or localization requirement.
The user asks to optimize for a metric, but the metric or guardrail is unclear.
A decision requires legal/compliance approval.

Default question pattern:

question({
  question: "What is the primary user task this copy needs to support?",
  recommended_default: "Assume the user wants to complete the immediate visible action with as little uncertainty as possible.",
  options: [
    "Complete a task",
    "Learn how something works",
    "Recover from a problem",
    "Make a high-stakes decision",
    "Other / custom"
  ]
})

Use the question-tool-ready prompts in references/decision-prompts.md for the full decision set.

不要询问诸如文案是否应清晰、简洁或无障碍等常规最佳实践问题，直接应用默认建议。

仅当答案会实质性改变文案、模式、语气或实现方式时才询问。除非用户明确要求全面调研，否则一次只问一个聚焦的问题。

当以下信息缺失且必要时询问：

主要用户任务或功能结果不明确。
受众为专业群体、弱势群体、多语言群体、老人/儿童、受监管群体或其他依赖上下文的群体。
流程要求提供敏感个人数据、法律同意、付款、健康信息、身份信息、安全信息或执行不可逆操作。
请求的语气与用户压力、包容性、无障碍性或信任相冲突。
文案依赖技术限制、后端验证、恢复路径、设计系统模式或本地化要求。
用户要求针对指标优化，但指标或防护措施不明确。
决策需要法律/合规审批。

默认问题模板：

question({
  question: "What is the primary user task this copy needs to support?",
  recommended_default: "Assume the user wants to complete the immediate visible action with as little uncertainty as possible.",
  options: [
    "Complete a task",
    "Learn how something works",
    "Recover from a problem",
    "Make a high-stakes decision",
    "Other / custom"
  ]
})

查看references/decision-prompts.md中的问题工具就绪提示，获取完整决策集。

Workflow

工作流程

A. Critique existing UI copy

A. 评审现有UI文案

Inspect in this order:

Task fit: What is the user trying to do? Does the copy help that task or distract from it?
User/business alignment: Does the copy serve a legitimate product goal without forcing, hiding, or manipulating?
Conversation flow: Entry point → instruction → action → feedback → next step → inverse action → failure path.
Pattern choice: Is each string using the right component/state: label, hint, CTA, tooltip, inline validation, banner, modal, empty state, confirmation, notification?
Action clarity: Do buttons and links name the outcome?
Comprehension: Is the copy plain, specific, scannable, and free of unnecessary jargon?
Stress and recovery: Do errors avoid blame, explain the issue, and offer a realistic next step?
Trust and inclusion: Are sensitive asks explained? Are choices inclusive? Are defaults and suggestions safe?
Voice and consistency: Does wording follow product principles, terminology, grammar, capitalization, and tone?
Accessibility and frontend feasibility: Are labels, descriptions, errors, status updates, focus behavior, and localization implementable?
Measurement: If stakes are high, identify how to test or measure whether the copy works.

When reporting a critique, group findings by severity:

Blocking: prevents comprehension, action, accessibility, trust, or recovery.
Important: increases cognitive load, uncertainty, or inconsistency.
Polish: improves tone, flow, or delight after core usability is fixed.

For each issue, provide: current problem, better copy or pattern, reason, and any implementation note.

按以下顺序检查：

任务适配：用户试图做什么？文案是否有助于该任务还是分散注意力？
用户/业务对齐：文案是否服务于合理的产品目标，而没有强迫、隐藏或操纵用户？
对话流程：入口点 → 说明 → 操作 → 反馈 → 下一步 → 反向操作 → 失败路径。
模式选择：每个字符串是否使用了正确的组件/状态：标签、提示、CTA、工具提示、内联验证、横幅、模态框、空状态、确认消息、通知？
操作清晰度：按钮和链接是否说明了结果？
可理解性：文案是否平实、具体、易扫描且无不必要的行话？
压力与恢复：错误提示是否避免指责、清晰解释问题并提供可行的下一步？
信任与包容性：敏感请求是否有说明？选择是否具包容性？默认和建议是否安全？
语气与一致性：措辞是否遵循产品原则、术语、语法、大小写和语调？
无障碍性与前端可行性：标签、说明、错误提示、状态更新、焦点行为和本地化是否可实现？
衡量：若风险较高，确定如何测试或衡量文案是否有效。

报告评审结果时，按严重程度分组：

阻塞性：阻碍理解、操作、无障碍性、信任或故障恢复。
重要性：增加认知负荷、不确定性或不一致性。
优化性：在核心可用性修复后，改善语气、流程或愉悦感。

针对每个问题，提供：当前问题、改进后的文案或模式、原因以及任何实现注意事项。

B. Create or improve new UX copy

B. 创建或优化新UX文案

Proceed in this order:

Clarify the product moment. Identify user, task, state, platform, constraints, and success criteria. Ask only if missing context changes the recommendation.
Map the conversation. What does the user know now? What do they need to know? What action can they take? What does the system do next?
Select the pattern. Decide whether the copy belongs in a title, label, hint, body text, CTA, inline validation, banner, modal, empty state, toast, notification, loading message, or help entry.
Draft useful copy first. Make the copy accurate, task-focused, and outcome-specific before making it shorter or more branded.
Edit in four passes.
- Purposeful: Does it serve the user and product goal?
- Concise: Can anything be removed without losing meaning?
- Conversational: Does it sound like a human interaction, not a system log?
- Clear: Would the intended user understand it immediately?
Handle edge and stress states. Include empty, loading, success, validation, failure, permission, offline, destructive, and undo/retry states as relevant.
Make it implementable. Provide component/state mapping, semantic labels, error associations, ARIA live-region guidance where needed, string tokens if useful, and localization notes.
Test or validate. Recommend usability test prompts, comprehension checks, support-data review, or A/B tests when stakes justify it.
Explain decisions. Tie recommendations to task completion, comprehension, trust, recovery, accessibility, and product goals.

按以下步骤进行：

明确产品场景：确定用户、任务、状态、平台、限制和成功标准。仅当缺失的上下文会改变建议时才询问。
映射对话流程：用户现在知道什么？他们需要知道什么？可以执行什么操作？系统下一步会做什么？
选择模式：确定文案应属于标题、标签、提示、正文、CTA、内联验证、横幅、模态框、空状态、提示框、通知、加载消息还是帮助条目。
先撰写实用文案：在缩短或品牌化之前，确保文案准确、聚焦任务且明确结果。
四轮编辑：
- 目的性：是否服务于用户和产品目标？
- 简洁性：是否可在不丢失含义的情况下删除内容？
- 对话性：是否听起来像人类交互而非系统日志？
- 清晰度：目标用户能否立即理解？
处理边缘和压力状态：根据需要涵盖空状态、加载状态、成功状态、验证状态、失败状态、权限状态、离线状态、破坏性操作和撤销/重试状态。
使文案可落地实现：提供组件/状态映射、语义标签、错误关联、必要的ARIA实时区域指南、有用的字符串令牌以及本地化说明。
测试或验证：当风险较高时，建议可用性测试提示、理解度检查、支持数据审查或A/B测试。
解释决策：将建议与任务完成、理解、信任、故障恢复、无障碍性和产品目标关联起来。

Decision framework

决策框架

Use this framework to choose the content pattern:

User need	Prefer this pattern	Default content structure
Know where they are	Page title / section heading	Object or task name; avoid generic “Details” when specificity matters.
Know what a field is	Visible label	Noun phrase: “Work email,” “Deposit amount.”
Know format or constraint	Hint / helper text	Constraint or example: “Use 8–64 characters.”
Decide what happens	Button / link	Verb + object/consequence: “Create post,” “Pay $24,” “Download report.”
Understand a sensitive ask	Contextual explanation	Why needed + how used + whether optional.
Know something is happening	Loading/progress	Current operation + duration/expectation if known.
Know action succeeded	Confirmation/toast	What happened + important consequence + next step if useful.
Know nothing is here yet	Empty state	What is empty + why/when + next action.
Recover from a problem	Inline error or error page	What happened + why if useful + how to fix/retry/escape.
Learn without blocking	Inline help / documentation link	Short in-context guidance + link to deeper help.
Respond to timely change	Notification	Timely reason + user benefit + clear action or dismissal.
Prevent harm	Confirmation dialog / interstitial	Consequence + irreversible scope + safe cancel + specific confirm action.

使用本框架选择内容模式：

用户需求	首选模式	默认内容结构
了解当前位置	页面标题/章节标题	对象或任务名称；需要具体性时避免使用通用的“详情”。
了解字段用途	可见标签	名词短语：“工作邮箱”、“存款金额”。
了解格式或限制	提示/辅助文本	限制或示例：“使用8-64个字符”。
决定操作结果	按钮/链接	动词 + 对象/后果：“创建帖子”、“支付24美元”、“下载报告”。
理解敏感请求	上下文说明	需要原因 + 使用方式 + 是否可选。
了解正在发生的事情	加载/进度	当前操作 + 已知的时长/预期。
了解操作成功	确认/提示框	已发生的操作 + 重要后果 + 有用的下一步。
了解内容为空	空状态	什么内容为空 + 原因/时间 + 下一步操作。
从问题中恢复	内联错误或错误页面	发生了什么 + 必要时说明原因 + 如何修复/重试/退出。
无阻塞学习	内联帮助/文档链接	简短的上下文指导 + 深入帮助的链接。
响应及时变化	通知	及时原因 + 用户利益 + 清晰的操作或关闭选项。
防止伤害	确认对话框/插页	后果 + 不可逆范围 + 安全取消选项 + 具体确认操作。

Practical rules

实用规则

Buttons and links

按钮和链接

Use the action outcome, not the interaction method. Prefer “Download report,” “Create post,” or “View pricing” over “Click here,” “Submit,” or vague “Save” when the object/action matters.
Put the most important consequence in the label for payment, deletion, sending, publishing, sharing, permissions, and irreversible actions.
Make primary and secondary actions meaningfully different. Avoid pairs like “OK / Cancel” when users need consequence clarity.
Use “Back,” “Cancel,” “Undo,” “Remove,” and “Delete” carefully; they imply different reversibility.

使用操作结果而非交互方式。优先选择“下载报告”、“创建帖子”或“查看定价”，而非“点击这里”、“提交”或模糊的“保存”（当对象/操作重要时）。
对于付款、删除、发送、发布、分享、权限和不可逆操作，将最重要的后果包含在标签中。
使主要和次要操作有明确区别。当用户需要了解后果时，避免使用“确定/取消”这类组合。
谨慎使用“返回”、“取消”、“撤销”、“移除”和“删除”；它们暗示不同的可逆性。

Forms

表单

Use persistent labels for every input. Do not rely on placeholders as labels.
Use helper text for unusual constraints, examples, privacy concerns, or why the information is needed.
Put errors near the field and summarize at the top only when the form is long or submission failed.
Use examples that match required formatting, but avoid examples that look like actual saved data.
Prefer progressive disclosure over long instructions, but do not hide information required to complete the task.

为每个输入使用持久可见的标签，不要依赖占位符作为标签。
对不寻常的限制、示例、隐私问题或信息需求原因使用辅助文本。
将错误提示放在字段附近，仅当表单较长或提交失败时在顶部汇总。
使用符合要求格式的示例，但避免使用看起来像实际保存数据的示例。
优先使用渐进式披露而非长说明，但不要隐藏完成任务所需的信息。

Sensitive questions and personal data

敏感问题和个人数据

Before asking for identity, demographics, health, finance, location, contacts, or legal information, explain the reason in plain language.
Do not force binary, overly narrow, or culturally specific categories unless legally required.
Offer “Prefer not to say,” “Self-describe,” “Not listed,” or skip options when appropriate and feasible.
Never use playful tone to soften surveillance, coercion, or a data grab.

在请求身份、人口统计、健康、财务、位置、联系人或法律信息之前，用平实语言说明原因。
除非法律要求，否则不要强制使用二元、过于狭窄或特定文化的分类。
适当且可行时，提供“不愿透露”、“自行描述”、“未列出”或跳过选项。
永远不要用戏谑的语气淡化监控、强制或数据收集行为。

Errors and validation

错误和验证

Use Avoid → Explain → Resolve.

Avoid: Prevent errors through clear labels, constraints, input masks, examples, progressive validation, and better interaction design.
Explain: State what went wrong in human language. Avoid raw error codes, stack traces, or blame.
Resolve: Tell the user what to do next: fix, retry, undo, contact support, use an alternative path, or wait.

Error message structure:

text

[Problem in user terms]. [Specific fix or next step].

Examples of structures, not fixed copy:

“Enter a valid email address.”
“Your file is too large. Upload a file under 10 MB.”
“We couldn’t save your changes. Check your connection and try again.”

For high-stress, legal, financial, medical, identity, security, or destructive states, use calm, explicit, non-humorous copy.

遵循避免→解释→解决原则。

避免：通过清晰的标签、限制、输入掩码、示例、渐进式验证和更好的交互设计预防错误。
解释：用人类语言说明问题所在，避免原始错误代码、堆栈跟踪或指责。
解决：告诉用户下一步该做什么：修复、重试、撤销、联系支持、使用替代路径或等待。

错误消息结构：

text

[用户视角的问题]。[具体修复或下一步]。

结构示例（非固定文案）：

“请输入有效的邮箱地址。”
“您的文件过大，请上传10MB以下的文件。”
“无法保存您的更改，请检查网络连接后重试。”

对于高压力、法律、金融、医疗、身份、安全或破坏性状态，使用冷静、明确、无幽默的文案。

Empty states

空状态

Use empty states to orient and move the user forward.

Default structure:

text

Title: No [objects] yet
Description: [What will appear here or why it matters]
Action: [Next useful action]

Do not turn every empty state into a marketing pitch. If there is no useful next action, explain the state and provide a path back.

使用空状态引导用户并推进流程。

默认结构：

text

标题：暂无[对象]
描述：[此处将显示什么或其重要性]
操作：[下一步有用操作]

不要将每个空状态都变成营销宣传。如果没有有用的下一步操作，说明状态并提供返回路径。

Loading and progress states

加载和进度状态

If a wait is noticeable, tell users what is happening.
If duration is predictable, set expectation.
If the process may fail, prepare recovery paths.
Use brand personality sparingly; never let playful loading copy hide risk, cost, or uncertainty.

如果等待时间明显，告知用户正在发生的事情。
如果时长可预测，告知预期时间。
如果流程可能失败，准备恢复路径。
谨慎使用品牌个性；永远不要让戏谑的加载文案掩盖风险、成本或不确定性。

Success and confirmation

成功和确认

Confirm the completed action in specific terms.
Include important consequences: publication, visibility, payment, delivery, permissions, data changes, or email sent.
Add next steps only when they help the current task.
Avoid celebratory tone for sensitive successes.

用具体术语确认已完成的操作。
包含重要后果：发布、可见性、付款、交付、权限、数据更改或邮件发送。
仅当有助于当前任务时添加下一步。
对于敏感的成功场景，避免使用庆祝语气。

Notifications

通知

Send fewer, better notifications.
Make them timely, relevant, and actionable.
Avoid vague engagement bait.
Use the user’s language and current context.
Provide controls for frequency and opt-out when appropriate.

发送更少、更优质的通知。
确保通知及时、相关且可操作。
避免模糊的互动诱饵。
使用用户的语言和当前上下文。
适当提供频率控制和退订选项。

Voice and tone

语气语调

Build voice from product principles, not from adjectives alone.

Define:

Concepts: what the product should consistently emphasize.
Vocabulary: preferred and avoided terms.
Verbosity: how much explanation is appropriate by state.
Grammar: sentence structure, point of view, contractions, tense.
Punctuation and capitalization: consistent mechanics.
Tone shifts: how the voice changes in success, error, legal, privacy, onboarding, and high-stress moments.

When no voice is supplied, use a professional, warm, direct voice.

从产品原则构建语气，而非仅依赖形容词。

定义：

概念：产品应始终强调的内容。
词汇：首选和避免的术语。
冗长程度：不同状态下合适的解释量。
语法：句子结构、视角、缩写、时态。
标点和大小写：一致的格式规范。
语调变化：成功、错误、法律、隐私、引导和高压力场景下语气的变化方式。

当未提供语气时，使用专业、亲切、直接的语气。

Editing

编辑

Use the four-pass edit:

Purposeful
Concise
Conversational
Clear

Do not start by shortening. First confirm that the copy solves the right problem. Then shorten without removing necessary meaning.

使用四轮编辑法：

目的性
简洁性
对话性
清晰度

不要从缩短开始。首先确认文案解决了正确的问题，然后在不丢失必要含义的前提下缩短。

Accessibility and inclusion requirements

无障碍性和包容性要求

Use visible labels and programmatic labels for inputs.
Associate helper text and errors with fields using accessible descriptions.
Do not rely on color, icon, position, or animation alone to communicate status.
Ensure error, success, and loading updates are announced appropriately for assistive technologies.
Preserve focus and keyboard access through dialogs, errors, and state changes.
Avoid disabled controls as the only instruction. If a control is disabled, explain why and how to enable it in accessible text.
Use readable plain language, short sentences, and familiar terms.
Avoid idioms, jokes, metaphors, and culture-specific references in functional copy unless tested for the audience.
Provide inclusive options for identity-related questions and explain why the information is needed.
Consider emotional context: people may be stressed, grieving, sick, locked out, financially worried, or under time pressure.
Support localization with string expansion, variables that can move, pluralization, and context notes for translators.

为输入使用可见标签和程序化标签。
使用无障碍描述将辅助文本和错误提示与字段关联。
不要仅依赖颜色、图标、位置或动画传达状态。
确保错误、成功和加载更新能被辅助技术正确播报。
在对话框、错误提示和状态变化期间保持焦点和键盘访问性。
不要仅依赖禁用控件作为说明。如果控件被禁用，用无障碍文本解释原因和启用方法。
使用可读的平实语言、短句和熟悉的术语。
功能性文案中避免习语、笑话、隐喻和特定文化引用，除非针对受众测试过。
为身份相关问题提供包容性选项，并说明信息需求原因。
考虑情绪背景：用户可能处于压力、悲伤、生病、被锁定、财务担忧或时间紧迫的状态。
通过字符串扩展、可移动变量、复数化和为翻译者提供上下文说明来支持本地化。

Frontend implementation guidance

前端实现指南

When giving frontend recommendations, include copy as part of component behavior.

提供前端建议时，将文案作为组件行为的一部分。

Semantic HTML and ARIA

语义HTML和ARIA

Use real
```
<label>
```
elements connected to inputs.
Use
```
<button>
```
for actions and
```
<a>
```
for navigation.
Use headings that reflect information hierarchy.
Use
```
aria-describedby
```
to connect helper and error text to fields.
Use
```
aria-invalid="true"
```
when validation fails.
Use
```
role="alert"
```
or an appropriate live region for urgent validation/status updates, but avoid excessive announcements.
Manage focus after modal opens, form submission fails, route changes, and destructive confirmations.
Do not remove focus outlines.

使用真实的
```
<label>
```
元素与输入关联。
使用
```
<button>
```
执行操作，使用
```
<a>
```
进行导航。
使用反映信息层级的标题。
使用
```
aria-describedby
```
将辅助文本和错误文本与字段关联。
验证失败时使用
```
aria-invalid="true"
```
。
使用
```
role="alert"
```
或合适的实时区域处理紧急验证/状态更新，但避免过度播报。
在模态框打开、表单提交失败、路由变化和破坏性确认后管理焦点。
不要移除焦点轮廓。

Component/state structure

组件/状态结构

Document copy for each relevant state:

default
hover/focus where text changes, if any
loading
empty
partial
success
warning
error
offline
permission denied
disabled
destructive confirmation
undo/retry

记录每个相关状态的文案：

默认
悬停/聚焦（若文本变化）
加载
空
部分完成
成功
警告
错误
离线
权限拒绝
禁用
破坏性确认
撤销/重试

Design-system integration

设计系统集成

Name reusable content patterns, not only individual strings.
Store preferred terms and forbidden terms.
Provide examples for labels, CTA labels, helper text, errors, empty states, loading, confirmations, and notifications.
Use content tokens or string IDs when implementation requires reuse, but avoid abstract IDs that hide context.
Keep source strings localizable. Avoid concatenating sentence fragments in code.

命名可复用的内容模式，而非仅单个字符串。
存储首选术语和禁用术语。
提供标签、CTA标签、辅助文本、错误提示、空状态、加载、确认消息和通知的示例。
当实现需要复用内容时，使用内容令牌或字符串ID，但避免隐藏上下文的抽象ID。
保持源字符串可本地化，避免在代码中拼接句子片段。

Responsive and localization considerations

响应式和本地化考虑

Expect copy expansion in translation.
Avoid layouts that only work for very short English strings.
Do not encode meaning solely in line breaks.
Test truncation behavior for CTAs, tabs, nav, toasts, and table headers.
Provide translator comments for variables, tone, and context.

考虑翻译后的字符串扩展。
避免仅适用于极短英文字符串的布局。
不要仅依赖换行符传达含义。
测试CTA、标签页、导航、提示框和表头的截断行为。
为翻译者提供变量、语调和上下文的注释。

Quality checklist

质量检查清单

Before finalizing UX copy, verify:

The user’s primary task is clear.
Each string has a job: orient, instruct, motivate, confirm, warn, recover, or explain.
The copy does not compensate for a broken interaction that should be redesigned.
Buttons and links describe outcomes.
Forms have visible labels and helpful constraints.
Sensitive asks explain why the data is needed.
Errors state the problem and the next step without blame.
Empty states include a useful next action when one exists.
Success states confirm important consequences.
Tone matches emotional stakes.
Voice and terminology are consistent.
Copy is concise but not cryptic.
Accessibility states are implementable.
Localization will not break the UI.
High-impact copy has a validation or measurement plan.
Recommendations include frontend notes when implementation matters.

Use the full checklists in references/checklists.md.

最终确定UX文案前，验证：

用户的主要任务清晰。
每个字符串都有作用：引导、说明、激励、确认、警告、恢复或解释。
文案未弥补应重新设计的交互缺陷。
按钮和链接描述了结果。
表单有可见标签和有用的限制。
敏感请求说明了数据需求原因。
错误提示说明了问题和下一步，无指责。
空状态在有可用操作时包含有用的下一步。
成功状态确认了重要后果。
语调匹配情绪风险。
语气和术语一致。
文案简洁但不晦涩。
无障碍状态可实现。
本地化不会破坏UI。
高影响文案有验证或衡量计划。
建议包含实现相关的前端说明。

查看references/checklists.md获取完整检查清单。

Common mistakes to avoid

需避免的常见错误

Treating UX writing as wordsmithing after the UI is done.
Asking users “Should I make it clear?” instead of applying clarity by default.
Using “Submit,” “Continue,” “OK,” or “Save” when the action consequence matters.
Replacing visible labels with placeholder text.
Explaining a broken UI instead of fixing the UI.
Hiding manipulative business goals in friendly language.
Using humor in errors, denial, payment failure, identity, legal, security, medical, or financial states.
Asking sensitive demographic or personal questions without explaining why.
Using technical error codes or backend terms in user-facing copy.
Over-branding navigation, forms, instructions, and errors.
Creating empty states that are dead ends.
Sending notifications that do not help the user act.
Writing strings that cannot be localized or announced by assistive technology.

See references/anti-patterns.md for the full anti-pattern list.

Delivering copy without states, constraints, or implementation context.

将UX写作视为UI完成后的文字润色。
询问用户“我应该让它清晰吗？”而非默认应用清晰原则。
当操作后果重要时使用“提交”、“继续”、“确定”或“保存”。
用占位符文本替代可见标签。
解释有缺陷的UI而非修复UI。
用友好语言隐藏操纵性业务目标。
在错误、拒绝、付款失败、身份、法律、安全、医疗或金融场景中使用幽默。
询问敏感的人口统计或个人问题却不说明原因。
在用户可见的文案中使用技术错误代码或后端术语。
过度品牌化导航、表单、说明和错误提示。
创建死胡同式的空状态。
发送对用户操作无帮助的通知。
撰写无法本地化或被辅助技术播报的字符串。

查看references/anti-patterns.md获取完整反模式列表。

交付无状态、限制或实现上下文的文案。

How to explain recommendations to the user

如何向用户解释建议

Explain recommendations in terms of user impact, not personal taste.

Use this structure:

text

I recommend [copy/pattern] because [user goal or risk]. It improves [comprehension/action/trust/recovery/accessibility]. Use [alternative] only if [context/constraint].

When giving multiple options, label them by purpose:

Clear/default
Warmer
More formal
Higher-trust
Shorter for constrained UI
Accessible/error-safe
Legal/compliance-safe pending review

Avoid saying “this sounds better” without explaining the task, state, or user need.

从用户影响而非个人喜好的角度解释建议。

使用以下结构：

text

我建议使用[文案/模式]，因为[用户目标或风险]。它提升了[理解/操作/信任/故障恢复/无障碍性]。仅在[上下文/限制]下使用[替代方案]。

提供多个选项时，按用途标注：

清晰/默认
更亲切
更正式
更高信任度
适用于受限UI的短文案
无障碍/错误安全
待审核的法律/合规安全

避免在不说明任务、状态或用户需求的情况下说“这个听起来更好”。