polish

必须完成的准备工作

阅读 frontend-design，并遵循其中的上下文收集流程。复用现有上下文，只针对会产生重大影响的信息缺口提问。此外还要了解质量标准（MVP 还是旗舰级）。

---

进行细致的最终检查，找出所有能让优秀作品更上一层楼的小细节。这就是交付与精致之间的差别。

润色应让现有层级和系统更加精确，而不应被用来装点薄弱的基础。

如果零数据界面本身需要设计工作，请参考 empty-state 技能。如果真正的问题在于更广泛的激活流程、灵光一现的时刻或首次运行策略，请使用 onboard。

使用 视觉验证 记录证据、可复用发现和最终状态。复用对话中匹配的评审意见或经授权保存的报告。行动前先核实其目标和基线；不要盲目套用过时的发现，也不要照搬其他路由的例外情况。

润色前评估

了解当前状态和目标：

1. 检查完整性：

   • 功能是否完整？
   • 是否有需要保留的已知问题（用 TODO 标记）？
   • 质量标准是什么？（MVP 还是旗舰级功能？）
   • 何时发布？（有多少时间用于润色？）

2. 确定润色重点：

   • 视觉不一致
   • 间距和对齐问题
   • 交互状态缺失
   • 文案不一致
   • 边界情况和错误状态
   • 加载和过渡是否流畅

重要：润色是最后一步，而不是第一步。功能尚未完整时，不要进行润色。

系统地进行润色

按以下维度逐一检查：

有关灰度测试、操作层级以及标签和值的处理，请参考层级检查清单。 有关行长、行高、对齐、基线和标题克制，请参考文本层级与可读性。 检查操作是否正确地突出或弱化时，请参考操作层级。 检查警报、状态和着色语义界面时，请参考语义色彩。 判断润色问题究竟是局部细节还是系统偏移时，请参考设计系统对齐。 边框、卡片、阴影、重叠或背景变化显得杂乱或不一致时，请参考界面层次分离。 截图、图标或媒体显得别扭、难以辨认或缺少恰当容器时，请参考图像处理。 默认 UI 元素、强调元素或装饰性背景需要更用心地打磨时，请参考收尾细节。

视觉对齐与间距

• 像素级对齐：所有元素都与网格对齐
• 间距一致：所有间距都使用间距比例（不要出现随意的 13px 间距）
• 视觉对齐：根据视觉重量进行调整（图标可能需要偏移，以实现视觉居中）
• 响应式一致性：所有断点下的间距和对齐都保持一致
• 遵循网格：元素与基线网格对齐
• 组群清晰：组与组之间的间距大于组内元素之间的间距
• 界面层次分离：有意识地使用边框、阴影、卡片和背景变化，而不是同时堆叠所有效果

检查：

• 启用网格叠加层并核实对齐
• 使用浏览器检查器检查间距
• 在多种视口尺寸下测试
• 留意那些看起来“不对劲”的元素

字体排印优化

• 层级一致性：相同元素在各处使用相同的字号和字重
• 行长：正文每行 45-75 个字符
• 行高：根据字号和上下文设置合适的行高
• 孤行与寡行：末行不应只有一个词
• 断字：根据语言和栏宽合理断字
• 字距调整：根据需要调整字母间距（尤其是标题）
• 字体加载：不出现 FOUT/FOIT 闪烁
• 基线对齐：同一行中不同字号的文本应整齐对齐
• 克制使用链接：次要链接的颜色不要过于醒目，以免抢占主要路径的注意力
• 数字对齐：需要比较时，数字列应右对齐
• 标题克制：分节标题应服务于内容，而非喧宾夺主

颜色与对比度

• 对比度：所有文本均符合 WCAG 标准
• 令牌使用一致：不使用硬编码颜色，所有颜色都使用设计令牌
• 主题一致性：适用于所有主题变体
• 颜色含义：相同颜色在各处表示相同含义
• 焦点状态易于识别：焦点指示器清晰可见，且对比度充足
• 品牌中性色：保留已批准的灰色、黑色和白色令牌。仅当调色板允许时才考虑添加色调。
• 彩色背景上的文本：检查文本在实际背景上的渲染对比度和强调效果。
• 调色板规范：表面和强调色使用已定义的色阶，不临时创造一次性颜色

交互状态

检查每个控件适用的状态。不要为简单的导航链接添加未使用的加载、错误或成功行为：

• 默认：静止状态
• 悬停：细微反馈（颜色、缩放、阴影）
• 焦点：键盘焦点指示器（切勿在不提供替代方案的情况下移除）
• 激活：点击／按下反馈
• 禁用：明确表示不可交互
• 加载中：异步操作反馈
• 错误：验证或错误状态
• 成功：成功完成

缺少状态会造成困惑，并导致体验不佳。

确保操作层级在所有状态下都保持不变：主要操作在悬停、焦点、激活、加载中和禁用状态下仍应明显是主要操作。

微交互与过渡效果

• 过渡效果：仅在动画能让反馈更清晰时才为状态变化添加动画。与现有动效系统保持一致。
• 缓动一致性：保留项目中有明确用途的动效；当过度回弹妨碍任务时，应将其移除。
• 避免卡顿：优化前先测量有问题的动效。在适用时优先使用 transform 和 opacity。
• 动效恰当：动效应服务于目的，而非装饰
• 减少动态效果：遵循 prefers-reduced-motion

内容与文案

• 术语一致：相同事物在各处使用相同名称
• 大小写一致：一致采用标题式大小写或句子式大小写
• 语法与拼写：没有错别字
• 长度合适：既不过于冗长，也不过于简短
• 标点一致：句子使用句号，标签不加句号（除非所有标签都加句号）

图标与图片

• 风格一致：所有图标来自同一套图标库或风格相符
• 尺寸合适：图标尺寸应符合上下文，并保持一致
• 对齐得当：从视觉上看，图标应与相邻文本对齐
• 替代文本：信息性图片应提供有用的文本替代内容。装饰性图片使用空替代文本。
• 加载状态：图片不应导致布局偏移，并应设置正确的宽高比
• 视网膜屏支持：为高 DPI 屏幕提供 2x 资源
• 截图清晰易读：截图不应缩得过小，以致其结构难以辨认
• 图标尺寸规范：不要把微小图标放大成笨重的色块，也不要把细节丰富的图标缩小到难以辨认

表单与输入

• 标签一致性：所有输入项都已正确标注
• 必填项指示：清晰且一致
• 错误消息：实用且一致
• Tab 顺序：键盘导航符合逻辑
• 自动聚焦：使用恰当（不要过度使用）
• 验证时机：保持一致（失焦时验证还是提交时验证）

边缘情况与错误状态

• 加载状态：所有异步操作都有加载反馈
• 空状态：提供实用的空状态，而非只留下一片空白
• 错误状态：错误消息清晰，并提供恢复途径
• 成功状态：确认操作已成功
• 长内容：妥善处理很长的名称、描述等
• 无内容：优雅地处理缺失数据
• 离线：妥善处理离线情况（如适用）
• 空状态层级：空状态应有明确的下一步操作，不要让无用的控件悬在那里

响应式布局

• 所有断点：测试窄、中、宽屏布局
• 指针目标：在粗指针场景下，最小尺寸为 44x44px
• 文本可读性：紧凑布局中的文本不得小于 14px
• 溢出：避免页面意外溢出。确保有意设置的表格或图库可滚动且易于使用。
• 合理重排：内容能以合乎逻辑的方式自适应

性能

• 快速初次加载：优化关键路径
• 无布局偏移：加载后元素不会跳动（CLS）
• 交互流畅：无延迟或卡顿
• 优化图片：格式和尺寸恰当
• 延迟加载：屏幕外内容延迟加载

代码质量

• 修复此次更改引入的错误，并运行项目中相关的现有检查。
• 移除此次工作中未使用的导入和临时调试内容。保留有意保留的日志和有用的 TODO。
• 当不安全的类型处理影响更改后的行为时，应予以处理。不要为了满足一刀切的禁令而改写无关类型或依赖项。
• 保留语义化 HTML、可访问名称和错误处理。

润色检查清单

按步骤系统检查：

• 检查相关视口尺寸下的对齐情况
• 一致地使用间距设计令牌
• 排版层级保持一致
• 实现并检查相关交互状态
• 检查相关过渡效果；性能声明应有测量结果支持
• 文案保持一致且精炼
• 图标保持一致且尺寸恰当
• 所有表单均已正确标注并完成验证
• 错误状态实用
• 加载状态清晰
• 空状态友好
• 粗指针目标的最小尺寸为 44x44px
• 对比度符合 WCAG AA
• 键盘导航正常
• 焦点指示器清晰可见
• 没有控制台错误或警告
• 加载时没有布局偏移
• 标明已测试的浏览器；报告尚未覆盖的浏览器
• 遵循减少动态效果偏好
• 不做无关清理；保留有意保留的 TODO 和日志

重要：润色关乎细节。放大仔细看。眯起眼睛观察。亲自使用。细微之处累积起来影响很大。

切勿：

• 在功能尚未完成前进行润色
• 如果 30 分钟后就要发布，还花数小时润色（应先分清轻重缓急）
• 润色时引入错误（务必充分测试）
• 忽略系统性问题（如果到处的间距都有问题，就修复整个系统）
• 只完善一处，却让其他部分粗糙不堪（保持整体质量一致）
• 用边框、阴影或色彩修饰来掩盖尚未解决的层级问题
• 在更克制的分隔方式效果更好时，仍使用鲜艳的链接颜色、杂乱的边框或装饰性重叠

最终验证

按照 视觉验证 进行验证。重新检查已更改的交互，并重新捕获相关视觉状态。对于每项延续的问题，根据当前证据报告其状态：已解决、部分解决、未解决或未验证。

在可用且适合当前任务时，使用真实设备或请另一位审核者参与。否则说明验证的局限性。不要要求他人或子 Agent 完成已授权的工作。

报告已实现的更改、已执行的检查以及仍存在的重要问题。不要声称通过一次聚焦的润色工作完成了整个应用程序的验证。