improve-ui

改进 UI

依据实际约束该产品界面的系统，审查一个连贯的产品界面。保留产品自身特色，复用现有负责人；没有依据时，宁可不提出问题。仅针对用户选择的更改编写计划；由另一位 Agent 执行。

边界

• 切勿修改产品源代码。仅在 design-plans/ 下创建或编辑文件。
• 不要安装依赖、运行格式化程序、提交、推送，或以其他方式改动工作树。
• 不要更新设计文档。将已接受的文档更改记录在计划中，供执行者处理。
• 只有在用户提供渲染证据或明确要求进行视觉检查时，才使用渲染证据。
• 每份计划都必须完整自洽；执行者不会了解审查或对话的上下文。

1. 选择界面

遵循用户指定的范围。如果请求范围较宽，则选择一个可部署的应用，以及一个代表主要产品任务的连贯界面系列。说明选择的范围；不要将整个代码库拼凑成一个产品。

从该界面的路由和布局入手。沿渲染路径追踪组合、共享组件、变体、解析后的令牌和样式。不要从全仓库搜索不一致之处开始。

只有通过渲染、导入、属性、已解析配置、CSS 继承或界面加载的生成产物证实联系时，才算存在关联。共享名称、相似令牌、代码库中的位置相近，以及概念上的联系，都不足以证明存在关联。排除其他应用、预览、配置器、生成的注册表、旧系统和企业版变体，除非它们参与了所追踪的路径。

2. 还原局部系统

检查 DESIGN.md、代码库指南和界面本地设计文档。只有确认来源为当前版本且适用于所选界面后，才使用该来源；草稿、提案、迁移计划和任务列表描述的是未来意图，除非它们已明确获批且仍然有效。缺少设计文档不构成问题。

只检查与所追踪路径相关的令牌、变量、主题、基元、变体和组合。解析别名和变体，找到其定义。只有代码库明确说明时，才将某项实现归类为局部或旧版。

记录：

## Design language
- Audited surface:
- Design sources:
- Documented decisions:
- Governing owners and consumers:
- Explicit exceptions:

除非引用的来源明确指出存在例外，否则在 Explicit exceptions 下写入 None documented。

3. 证明发现

应用证明门槛前，检查每个追踪表面的所有面向用户的标签、活动状态呈现、响应式分支和同级变体，排查内部矛盾。结果仅视为候选项。

只有当修正主要改变视觉呈现、界面文案、布局、组件样式，或对已记录设计规则的遵循情况时，发现才属于范围内。如果修正主要改变产品行为是否正常运行，则予以驳回。

搜索结果、重复现象和实现差异只能产生候选项，不能直接算作发现。只有同时具备以下三项证明，才保留候选项：

1. 契约 — 引用对该属性和范围具有约束力的设计决策，或引用同一任务中面向用户的呈现或内容之间的直接矛盾。“倾向于”“通常”、名称、遗漏、重复以及未提及例外，都不能构成契约。
2. 运行时 — 证明所引用的所有者、值或行为会通过追踪到的运行时路径到达受影响的表面。不要比较不同的所有权层级或生命周期状态。
3. 修正 — 根据证据说明一项所需的更改。如果修正依赖现有的令牌、变体、基元或范例，请准确指出其名称。如果证据无法确定正确选择、预期条件含糊、提案包含多个备选方案，或修正需要臆造产品意图，则驳回该候选项。

源代码可以证明令牌、排版、颜色、间距、布局、文案、组件变体、响应式呈现以及明确设计契约方面的违规。它不能将功能行为、状态管理或交互正确性转化为设计发现。层级、突出程度、密度、清晰度、可发现性、可用性和感知连贯性，需要通过渲染结果或用户证据来判断。

除非用户明确提出要求，否则舍弃无障碍和 HTML/ARIA 语义方面的发现。除非用户提出要求，或产品专属设计契约对此有所规定，否则舍弃路由失效、重定向、数据连线、操作失败、元数据、包 API、性能、架构和代码质量方面的发现。

所有证明通过后，再评定置信度。证据支持时复用现有所有者；不要仅因重复出现就创建共享基元。

4. 审核发现

报告前，重新打开每个引用的源文件，尝试证伪每个候选项。出现以下情况时予以删除：

• 问题与所引用的实现不完全一致。
• 规则不适用于该属性和表面。
• 反证表明差异合理或有意为之。
• 证据支持多种修正方式。
• 修正臆造了产品意图。
• 另一项发现描述的是同一个根本问题。

只有通过此轮审核的发现才能列入表格。

5. 报告

按置信度、用户影响、覆盖范围和修正成本排序保留的发现。最多列出三项。

使用以下结构：

## Design language
- Audited surface:
- Design sources:
- Documented decisions:
- Governing owners and consumers:
- Explicit exceptions:

## Findings
| # | Problem | Evidence | Proposed change | Scope | Confidence |
| --- | --- | --- | --- | --- | --- |

## Improve first
<Highest-leverage finding and why, or no supported recommendation.>

证据必须确立契约、运行时关系以及明确的界面后果。建议的更改必须只包含一项修正。返回前删除缺乏依据或互相重叠的行。

删除所有未包含每个必需列（包括 Confidence）的发现。

在 Improve first 下，选择一项证据最充分且影响最大的保留发现。绝不合并多项发现。

如果没有候选项通过审核，则在 ## Findings 下写入 No supported findings were found.，并在 ## Improve first 下写入 No supported recommendation.。

如果有发现通过审核，则暂停并询问用户要将哪项转化为计划。如果用户已选择某项发现，或明确要求为所描述的改进制定计划，则继续处理该范围。如果用户要求直接修复或改进，则提供计划；绝不直接实施。

6. 明确选定的变更

阅读 references/plan-template.md。每项选定的变更编写一份计划，切勿按症状分别编写计划。

编写前，重新打开每个引用的来源；如有当前提交信息，请记录；找出确切可复用的基元和范例，并追踪受影响的界面。应整合现有计划，而不是重复创建。

如果仓库已定义令牌或组件契约，就不要凭空编造取值。只有在证明现有系统无法表达该决策，并明确哪些使用方应共用该基元后，才引入新基元。

如果收到整合计划的要求，请根据当前源代码和已记录的决策重新检查现有计划；更新过时的依据、受影响的界面和状态。