polish

强制准备

调用 /impeccable — 其中包含设计原则、反模式和 Context Gathering Protocol。继续之前，务必遵循该协议 — 如果还没有设计上下文，必须先运行 /impeccable teach。此外还要了解质量标准（MVP 还是旗舰级）。

---

进行细致的最终检查，找出区分优秀作品与卓越作品的所有细节。这就是已交付与精心打磨之间的差别。

设计系统调研

开始打磨前，先了解要对齐的设计系统：

1. 查找设计系统：搜索设计系统文档、组件库、样式指南或令牌定义。了解核心模式：颜色令牌、间距比例、排版样式、组件 API。
2. 记录约定：共享组件如何导入？使用哪种间距比例？哪些颜色来自令牌，哪些是硬编码值？已确立了哪些动效和交互模式？
3. 识别偏差：目标功能有哪些地方偏离了系统？是否有本应使用令牌的硬编码值、重复实现共享组件的自定义组件，或不符合比例的间距？

如果存在设计系统，打磨时应与之保持一致。如果没有，则依据代码库中可见的约定进行打磨。

打磨前评估

了解当前状态和目标：

1. 检查完成度：

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

2. 识别需要打磨的方面：

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

重要：打磨是最后一步，不是第一步。功能尚未完成时，不要进行打磨。

系统化打磨

有条理地逐项检查以下方面：

视觉对齐与间距

• 像素级对齐：所有内容都与网格对齐
• 间距一致：所有间隔都使用间距比例（不要出现随意的 13px 间距）
• 视觉对齐：根据视觉权重进行调整（图标可能需要偏移，才能在视觉上居中）
• 响应式一致性：所有断点下的间距和对齐都正常
• 遵循网格：元素与基线网格对齐

检查：

• 启用网格叠加层并验证对齐情况
• 使用浏览器检查器检查间距
• 在多种视口尺寸下测试
• 留意视觉上“感觉”不对的元素

排版优化

• 层级一致性：相同元素在各处使用相同字号和字重
• 行长：正文每行 45-75 个字符
• 行高：适合字号和上下文
• 孤行与寡行：避免最后一行只剩一个词
• 断词：适合语言和列宽
• 字距调整：在需要时调整字间距（尤其是标题）
• 字体加载：避免出现 FOUT/FOIT 闪烁

颜色与对比度

• 对比度：所有文本均符合 WCAG 标准
• 令牌使用一致：不使用硬编码颜色，全部使用设计令牌
• 主题一致性：适用于所有主题变体
• 颜色含义：同一种颜色在各处表达相同含义
• 无障碍焦点：焦点指示器清晰可见且对比度充足
• 带色调的中性色：不要使用纯灰色或纯黑色，应添加微妙的颜色色调（0.01 色度）
• 彩色背景上的灰色：彩色背景上绝不使用灰色文本，应使用该颜色的某种色调或透明度

交互状态

每个交互元素都需要具备以下状态：

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

缺少状态会造成困惑，破坏使用体验。

微交互与过渡效果

• 平滑过渡：所有状态变化都应有恰当的动画（150-300ms）
• 缓动一致：使用 ease-out-quart/quint/expo 实现自然减速。不要使用弹跳或弹性效果，这些效果显得过时。
• 避免卡顿：动画保持 60fps，只对 transform 和 opacity 进行动画处理
• 动效恰当：动效应服务于功能，而非装饰
• 减少动态效果：遵循 prefers-reduced-motion

内容与文案

• 术语一致：同一事物在全文中使用相同名称
• 大小写一致：统一使用 Title Case 或 Sentence case
• 语法与拼写：没有拼写错误
• 长度恰当：不冗长，也不过于简短
• 标点一致：句子使用句号，标签不使用句号（除非所有标签都使用句号）

图标与图片

• 风格一致：所有图标来自同一套图标库，或风格相匹配
• 尺寸恰当：根据使用场景统一图标尺寸
• 对齐准确：图标与相邻文本在视觉上对齐
• 替代文本：所有图片都有描述性替代文本
• 加载状态：图片不会导致布局偏移，并采用恰当的宽高比
• Retina 支持：为高 DPI 屏幕提供 2x 资源

表单与输入

• 标签一致：所有输入项都有恰当的标签
• 必填标记：清晰且一致
• 错误消息：实用且一致
• Tab 顺序：键盘导航顺序合理
• 自动聚焦：使用恰当（不要过度使用）
• 验证时机：保持一致（失焦时或提交时）

边缘情况与错误状态

• 加载状态：所有异步操作都有加载反馈
• 空状态：提供有帮助的空状态，而非一片空白
• 错误状态：提供清晰的错误消息和恢复途径
• 成功状态：确认操作成功
• 长内容：妥善处理很长的名称、描述等
• 无内容：缺少数据时也能妥善处理
• 离线状态：妥善处理离线情况（如适用）

响应式设计

• 所有断点：测试手机、平板和桌面设备
• 触控目标：触控设备上的最小尺寸为 44x44px
• 文本可读性：手机上的文本不小于 14px
• 无水平滚动：内容适配视口
• 恰当重排：内容布局调整合理

性能

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

代码质量

• 移除控制台日志：生产环境中不保留调试日志
• 移除注释代码：清理无用代码
• 移除未使用的导入：清理未使用的依赖
• 命名一致：变量和函数遵循命名规范
• 类型安全：不使用 TypeScript any，也不忽略错误
• 无障碍性：使用恰当的 ARIA 标签和语义化 HTML

润色清单

按顺序逐项检查：

• 在所有断点下，视觉对齐都完美无误
• 间距始终一致地使用设计令牌
• 排版层级保持一致
• 已实现所有交互状态
• 所有过渡都流畅（60fps）
• 文案一致且精炼
• 图标风格一致且尺寸合适
• 所有表单都已正确标注并完成验证
• 错误状态能提供帮助
• 加载状态清晰明了
• 空状态令人感到友好
• 触控目标至少为 44x44px
• 对比度符合 WCAG AA 标准
• 键盘导航正常
• 焦点指示器清晰可见
• 控制台中没有错误或警告
• 加载时没有布局偏移
• 在所有受支持的浏览器中都能正常运行
• 尊重减少动态效果的偏好设置
• 代码整洁（没有 TODO、console.logs 或注释掉的代码）

重要提示：润色重在细节。放大查看，眯起眼睛仔细观察，亲自使用。点滴细节累积起来，效果显著。

切勿：

• 在功能尚未完成前就开始润色
• 如果 30 分钟后就要发布，却花数小时润色（要分清轻重缓急）
• 在润色时引入错误（要彻底测试）
• 忽视系统性问题（如果到处的间距都有问题，就修复整个系统）
• 只把一处做到完美，却让其他地方显得粗糙（保持一致的质量水准）
• 在设计系统已有对应组件时，另建一次性组件
• 对本应使用设计令牌的值进行硬编码

最终验证

标记为完成前：

• 亲自使用：实际与此功能交互
• 在真实设备上测试：不能只用浏览器 DevTools
• 请他人评审：换个视角能发现问题
• 与设计稿对比：确保符合预期设计
• 检查所有状态：不要只测试顺利流程

清理

润色后，确保代码质量：

• 替换自定义实现：如果设计系统提供了你重新实现的组件，请改用共享版本。
• 移除孤立代码：删除因润色而过时的未使用样式、组件或文件。
• 整合令牌：如果引入了新值，请检查它们是否应该成为令牌。
• 检查是否遵循 DRY 原则：查找润色过程中引入的重复内容并加以整合。

请记住：你对细节有着无可挑剔的关注，品味也十分出众。持续润色，直到一切显得毫不费力、设计意图清晰、运行完美。关注细节——它们很重要。