pr

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR

Make the pull request understandable to an engineer who was not in the design conversation.

让未参与设计讨论的工程师也能理解该拉取请求。

Always

始终遵循

Context — inspect what is already known before asking the user to repeat it. Use
```
.ux/INTENT.md
```
when product purpose or outcome can change the answer, and load only the additional project context the task needs.
User — ground the work in the people affected, their goal, task, context, and available evidence. Do not invent user needs, behaviors, or personas.
Evidence — keep known, inferred, assumed, unknown, and conflicted information distinct when the difference matters.
System — prefer established product language, components, patterns, and rules before inventing new ones.
Clear — lead with the useful point, use the minimum structure needed, and remove generic AI filler.
Trust — never invent evidence, requirements, rationale, implementation status, or compliance.
Outcome — for substantial multi-step work, keep intent active, use a small
```
.ux/STATE.md
```
only when continuity needs it, prioritize the highest-impact unresolved gap before polishing, and verify the actual experience against intent before declaring completion.

Do not recite these rules to the user unless one of them materially affects the answer.

Do not introduce research questions, personas, or discovery work when the user and task are already clear or the missing information would not materially change the work.

上下文（Context） — 先查看已知信息，再要求用户重复。当产品目标或结果会影响答案时，使用
```
.ux/INTENT.md
```
，仅加载任务所需的额外项目上下文。
用户（User） — 基于受影响人群、他们的目标、任务、场景和可用证据开展工作。不得编造用户需求、行为或角色。
证据（Evidence） — 当差异很重要时，明确区分已知、推断、假设、未知和有冲突的信息。
系统（System） — 优先使用已确立的产品语言、组件、模式和规则，而非创建新的。
清晰（Clear） — 先给出有用的要点，使用必要的最少结构，删除通用AI填充内容。
可信（Trust） — 不得编造证据、需求、理由、实施状态或合规性信息。
成果（Outcome） — 对于重大的多步骤工作，保持意图明确；仅当需要连续性时使用小型
```
.ux/STATE.md
```
；在优化之前优先处理影响最大的未解决差距；在宣布完成前，验证实际体验是否符合预期。

除非这些规则对答案有实质性影响，否则不要向用户复述这些规则。

当用户和任务已经明确，或缺失的信息不会对工作产生实质性改变时，不要引入研究问题、用户角色或探索性工作。

Inspect before writing

撰写前检查

Read the actual diff or changed files when available, the relevant design/handoff/contract, decision records, the smallest relevant project context, design-system context, and the repository's PR template.

Describe what the code actually changes. Do not copy a design intention into the PR as though it has already been implemented.

在有可用的差异文件或变更文件时，阅读实际的diff或变更文件，相关的设计/交接/契约、决策记录、最小的相关项目上下文、设计系统上下文以及仓库的PR模板。

描述代码实际变更的内容。不要将设计意图复制到PR中，仿佛它已经被实现了。

Write for review

为评审撰写

A useful PR description normally answers:

Why does this change exist?
What user-visible or system behavior changed?
Which existing components or patterns are reused, extended, or added?
Which important states are covered?
What accessibility behavior is relevant?
What was tested or verified?
What remains intentionally out of scope?
What should reviewers pay particular attention to?

Include links to authoritative design, intent, decision, ticket, or contract artifacts when available.

Do not force empty sections into the PR template.

有用的PR描述通常会回答以下问题：

为什么存在此变更？
用户可见的行为或系统行为有哪些变更？
复用、扩展或添加了哪些现有组件或模式？
覆盖了哪些重要状态？
相关的可访问性行为有哪些？
测试或验证了哪些内容？
哪些内容是故意不纳入范围的？
评审人员应特别注意什么？

在有可用的权威设计、意图、决策、工单或契约工件时，包含其链接。

不要在PR模板中强行添加空章节。

Make review easier

简化评审流程

Call out risky transitions, async behavior, new shared patterns, migration impact, unresolved constraints, or places where implementation intentionally differs from the initial design.

Avoid vague descriptions such as "updates UI" or enormous chronological change logs.

突出显示有风险的过渡、异步行为、新的共享模式、迁移影响、未解决的约束，或实现与初始设计有意不同的地方。

避免模糊描述，例如“更新UI”或冗长的按时间顺序的变更日志。

Repository actions

仓库操作

If the user asks to open a PR and tools permit it, inspect the branch/diff and repository state first. Opening, updating, merging, requesting reviewers, or otherwise mutating a PR requires the user's authorization for that action. Never merge merely because the description is complete.

如果用户要求打开PR且工具允许，请先检查分支/差异和仓库状态。打开、更新、合并、请求评审人员或以其他方式修改PR需要用户授权该操作。不要仅仅因为描述完整就合并PR。

Contrast example

对比示例

Bad:

Updates the account recovery UI to match the new designs. Also fixes some accessibility issues and error states.

Good:

Why: Users could become stranded when verification failed during account recovery.

Changed: Failed verification now preserves the entered code, shows the existing Alert error pattern, and moves focus to the error summary. No new design-system components were added.

Review: Please verify the API-error mapping and focus behavior. Expired-code recovery is intentionally out of scope for this PR.

Why: the good description gives engineering the reason, implemented behavior, system impact, review focus, and scope without narrating every file change.

不好的例子：

更新账户恢复UI以匹配新设计。同时修复了一些可访问性问题和错误状态。

好的例子：

原因： 当账户恢复过程中的验证失败时，用户可能会陷入困境。

变更内容： 验证失败时现在会保留输入的验证码，显示现有的Alert错误模式，并将焦点移至错误摘要。未添加新的设计系统组件。

评审要点： 请验证API错误映射和焦点行为。验证码过期的恢复功能被有意排除在本次PR的范围之外。

原因：好的描述为工程师提供了变更理由、已实现的行为、系统影响、评审重点和范围，而无需叙述每个文件的变更。

Examples

示例场景

"Write the PR description for this UX change."
"Create a PR engineers can actually review."
"Explain this design-engineering change in the PR."

“为此次UX变更撰写PR描述。”
“创建一个工程师实际可以评审的PR。”
“在PR中解释此次设计工程变更。”