ui-polish-pass

UI 润色

角色与范围

ADS 工艺负责人。作为同一轮构建／评审的一部分，在任务匹配度和信息结构都合理后，针对变更涉及的界面应用相关机制。微小改动只需进行简单检查。不要重新设计已选定的方向，不要把原型打磨成可用于生产的成品，也不要让实用型工作免于基本易用性检查。只有存在真实且尚未解决的决策时，才需要探索新方向，而不是为了润色而例行其事。

核心视角

• 先提炼，再装饰。
• 将界面精简到必要结构，再只添加真正有价值的内容。
• 如果润色需要增加更多颜色、卡片和界面装饰，那可能就不是润色。
• 将 /bolder 和 /quieter 作为方向性调整：
  • /bolder = 提高对比度、层级感或确定性，但不增加杂乱
  • /quieter = 去除噪声、降低强调，让重点内容引领界面

视觉基础检查

优先使用产品现有的设计令牌。如果没有统一的视觉基础，请先定义一组最精简且实用的令牌，再进行润色：

• 字体角色、字号比例、行高和易读的行长
• 间距步进和分组节奏
• 表面、边框、文本、操作和语义颜色
• 圆角和层级规则
• 图标系列和尺寸规则

已有适用令牌时，不要另造新令牌。如果重复出现的元素彼此冲突，应在授权范围内先修复其所属的基础组件，再处理细节；对于范围更广的系统性工作，应予以报告，不要默默扩大改动范围。

机械规范默认值

这些规范用于统一界面机制，而非产品特性。如果项目已有更严格的规范，应保持与其一致。

控件几何尺寸

如果没有控件尺寸规范，请使用以下三个命名高度：

• compact: 32px，用于高密度、仅限桌面端的工具
• default: 40px，用于常规桌面端控件
• touch: 48px，用于触控优先和主要移动端控件

同一行中的控件应具有相同高度。触控目标至少为 48 乘 48px，且相邻目标之间至少间隔 8px，即使可见图形更小也应如此。常规控件应使用所选图标系列预期的光学尺寸；独立展示或编辑性场景则使用更大的尺寸。应在控件基础组件中集中定义图标与标签的间距、水平内边距、圆角和焦点样式。

下拉菜单箭头与边缘至少保持 16px 间距，并为文本留出至少 44px 的空间。 应将这两个值设置在共享的选择器／菜单触发器基础组件中，而不是针对每个实例重复打补丁。 在目标桌面端和移动端／WebKit 界面中验证长标签、焦点以及打开／关闭行为。

文本适配

• 默认允许内容换行。只有产品规范明确要求单行时才截断。
• 截断后的值必须能通过无障碍工具提示、展开披露或详情视图等可靠方式查看完整内容。
• 必要时为 Flex 和 Grid 中的文本子元素设置 min-width: 0，让长内容能够换行或截断，避免页面溢出。
• 不要将有意义的文本放入固定高度容器。
• 验证长名称、本地化后的文本扩展、浏览器缩放以及 200% 文本缩放。
• 行内元数据挤占主要文本空间时，应先改为堆叠或重新排布，而不是缩小字号。
• 文本尺寸或视口宽度变化时，应保持信息层级一致。

数据语法

• 文本列左对齐，数值列右对齐。
• 对变化的数字、比较值、价格、百分比、计数和时间戳使用等宽数字。
• 每种数据类型采用一种符合区域设置的格式。小数精度、单位、正负号、日期样式和时区应明确且保持一致。
• 将缺失、零、不适用和加载表示为不同状态。使用有意义的标签，而不是含义模糊的破折号。
• 表头和表格正文的行密度应协调一致。除非有语义上的需要，否则不要在同一张表中混用不同的行高。
• 为内容密集的表格留出所需的页面宽度。不要将其塞进模态框、嵌套卡片或狭窄的侧面板。
• 在窄屏上，选择明确的表格呈现策略，例如优先列、行详情、卡片或带有可见提示的水平滚动。绝不要将桌面端的列挤在一起，导致文字难以阅读。

交互状态系统

每种交互组件都基于同一套令牌配方定义启用、悬停、可见焦点、按下、选中（适用时）、禁用和忙碌状态。

• 使用清晰可见的焦点指示器，其周边等效区域至少为 2px，且对比度变化达到 3:1。背景表面不一时，优先使用双色焦点环。
• 悬停状态不能用于展示唯一可用的操作或说明。
• 按下和忙碌状态应立即响应输入，且不移动周围布局。
• 选中状态、状态信息和验证结果不能仅依赖颜色传达。
• 如果禁用控件的原因很重要，应在附近通过持续显示的文案说明。不要依赖必须先聚焦禁用控件才能触发的工具提示。
• 各种状态组合必须保持清晰易读，包括选中加悬停、选中加焦点，以及忙碌加禁用。

表面层级

除非产品确实需要更多层级，否则最多使用三个语义表面层级：

• base 用于页面画布
• raised 用于常驻面板和分组工作区域
• overlay 用于菜单、弹出层、对话框和临时图层

每个层级都定义自己的背景、边框、圆角和层级效果配方。边框用于传达分组或状态；阴影用于传达实际的层级关系。不要仅为增加内边距而添加卡片。除非嵌套表面具有不同的交互或状态作用，否则应避免卡片中嵌套卡片的布局。

表单结构

• 使用可见标签。占位符文本用于示例或提示，不能作为唯一标签。
• 将标签、控件、辅助文本、验证信息和状态信息置于一致且可预测的组件结构中。
• 尽可能复用辅助文本位置显示验证信息，避免错误导致布局大幅跳动。
• 使用正确的输入类型、输入模式、自动填充令牌和原生语义。
• 根据预期答案设置字段尺寸。短答案不应默认占满整页宽度。
• 在字段附近显示验证信息，在触发操作附近显示操作反馈。Toast 是辅助确认方式，不能作为唯一的错误或成功反馈渠道。

异步稳定性与恢复

• 骨架屏和加载占位符应尽可能贴合最终内容的几何尺寸，以避免布局偏移。
• 操作等待期间，保持触发操作的控件可见。禁用该控件或更改其标签，并在操作发生处显示进度。
• 某个请求失败时，仍保留可用的部分数据。
• 乐观更新需要有回滚路径。对于可撤销的破坏性操作，优先提供撤销；对于确实不可逆的操作，则应要求确认。
• 空状态和错误状态应保留页面的视觉主轴，并包含下一步有用的操作。

响应式布局与层级

• 每个复杂组件都应声明其小屏幕适配策略：重排、调整顺序、展开内容、替换或有意允许滚动。
• 当任务发生变化时，移动端应采用不同的布局，而不是将桌面端整体等比例缩小。
• 粘性页眉、底部操作、对话框和聚焦控件应避开安全区域，且不得遮挡内容或键盘焦点。
• 为基础内容、粘性元素、弹出层、对话框和通知使用命名层级令牌。不要随意累加 z-index 值。
• 在用户有合理预期会返回时，跨导航保留滚动位置、选中项、筛选条件和任务上下文。

不要将这些机械化的默认项用于决定通用字体、配色、密度风格或品牌表达。这些仍由项目自行决定。

图标默认规范

优先保留项目现有且统一的图标系列。否则，在许可证允许的前提下，遵循明确的项目或用户偏好；如果没有偏好，则选择一个合适的开源系列。ADS 不要求使用特定图标供应商。

• 使用一致的字重／描边，并采用所选系列预期的光学尺寸。
• 在项目明确批准迁移之前，保留现有且统一的图标系列。
• 对原生平台规范、品牌系统、游戏及其他特定领域的视觉语言，可有意采用例外。
• 除非有明确的设计理由，否则不要在同一界面中混用不同的图标系列或描边体系。

使用共享的 Icon 或 InlineIcon 基元，集中管理系列、尺寸、描边、颜色、对齐、无障碍支持和光学修正。

• 与文本并列的图标应与文本首行基线对齐。在弹性布局中，先采用基线对齐，并在共享基元中应用系列级光学偏移；切勿针对单个图标单独微调。
• 方形按钮、工具栏、头像或其他固定图标容器中的独立图标应保持几何居中。
• 装饰性图标应对辅助技术隐藏。仅含图标的控件必须具有无障碍名称。
• 如果图标含义并非普遍明确，应为其配上可见标签。

图标库有各自的许可证。未经再分发许可，不要提交付费图标库或许可证密钥。保留必要声明，使用授权的包访问方式，并在发布前确认项目特定的共享和模板条款。如果所选系列未获准用于预期用途，请选择已获批准的替代方案。

工艺审查

综合检查相关维度，而不是强制分成七轮：

• 间距与构图： 将相关内容分组，使用既定比例，保留产品的信息密度，并突出一个清晰的主要焦点。移除多余的界面装饰会有所帮助，但不能因此删除必要信息。
• 排版： 采用统一的文字层级和易读的行宽。保留常规的功能性字体、自然的大小写形式和既定的排版节奏。额外的颜色或更小的文字无法弥补信息架构不清的问题。
• 对齐： 保持内边距一致、图标在视觉上对齐、控件行稳定，并合理控制内容宽度。使用共享的基础组件进行同类组件的视觉校正。
• 颜色与对比度： 使用项目的语义化令牌，并测试最终合成后的颜色。随意设置不透明度百分比并不能保证次要文字清晰可读。检查受支持的主题。
• 交互手感： 保留可见的焦点状态和即时的输入反馈。只有在确有帮助时才使用有目的且可中断的动画；高频控件可能无需动画。实现时遵循现有的动画令牌和 ../web-animation-design/SKILL.md。克制的缓动适用于功能性工作；手势弹簧或富有表现力的动画则需要结合情境给出理由。尊重减少动态效果的设置；弹跳和按压时缩放都不适用于所有情况。
• 完成度： 对变化的数字使用等宽数字，确保文本换行稳健、图标协调；适用时使用同心的嵌套圆角，并有意识地为特定属性添加过渡。不要使用 transition: all。不要强行为所有界面添加抗锯齿、图像描边、图标切换动画或按压缩放。

基础规范仍由 ADS/design-review 负责：不使用视觉状态点或装饰性圆点、强制大写、单边圆角边框或仿造阴影。保持字面数据不变。不要仅为营造层级而添加分隔线或卡片。

验证与停止

在最终尺寸和目标视口下检查渲染结果，并与选定的基准及相关参考进行比较。测试受影响控件的行为、长内容和响应式变化。以实际任务的清晰度和对参考的还原度为标准，而不是看某个时髦产品是否会采用这种设计。截图无法证明交互效果或审美是否获得认可。

润色到满足所请求产物的需要即可。临时实验可以保持粗糙；有用的内部工具仍须清晰易读且控件可正常使用。如果工艺审查发现结构性缺陷，应在现有预算内将问题交回 ADS 判断阶段，而不是开启新一轮重新设计。