Back to Details

polish

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MANDATORY PREPARATION

必备准备工作

Invoke /impeccable — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding — if no design context exists yet, you MUST run /impeccable teach first. Additionally gather: quality bar (MVP vs flagship).
Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished.
调用 /impeccable 命令——其中包含设计原则、反模式以及上下文收集协议。在开始操作前必须遵循该协议——如果尚无设计上下文，你必须先运行 /impeccable teach。此外还需明确：质量标准（MVP 还是旗舰级）。
执行细致的最终检查，找出所有区分优秀与卓越作品的细微细节，也就是已完成与精雕细琢之间的差距。

Design System Discovery

设计系统调研

Before polishing, understand the system you are polishing toward:
  1. Find the design system: Search for design system documentation, component libraries, style guides, or token definitions. Study the core patterns: color tokens, spacing scale, typography styles, component API.
  2. Note the conventions: How are shared components imported? What spacing scale is used? Which colors come from tokens vs hard-coded values? What motion and interaction patterns are established?
  3. Identify drift: Where does the target feature deviate from the system? Hard-coded values that should be tokens, custom components that duplicate shared ones, spacing that doesn't match the scale.
If a design system exists, polish should align the feature with it. If none exists, polish against the conventions visible in the codebase.
在润色前，先明确你要对齐的目标系统：
  1. 查找设计系统：搜索设计系统文档、组件库、样式指南或令牌定义。研究核心模式：颜色令牌、间距刻度、排版样式、组件API。
  2. 记录约定规范：共享组件如何导入？使用何种间距刻度？哪些颜色来自令牌而非硬编码值？已确立的动效和交互模式是什么？
  3. 识别偏差：目标功能与系统存在哪些偏离？本应使用令牌的硬编码值、重复共享组件的自定义组件、不符合刻度的间距。
如果存在设计系统，润色需使功能与系统对齐；如果没有，则根据代码库中可见的约定进行润色。

Pre-Polish Assessment

润色前评估

Understand the current state and goals:
  1. Review completeness:
    • Is it functionally complete?
    • Are there known issues to preserve (mark with TODOs)?
    • What's the quality bar? (MVP vs flagship feature?)
    • When does it ship? (How much time for polish?)
  2. Identify polish areas:
    • Visual inconsistencies
    • Spacing and alignment issues
    • Interaction state gaps
    • Copy inconsistencies
    • Edge cases and error states
    • Loading and transition smoothness
CRITICAL: Polish is the last step, not the first. Don't polish work that's not functionally complete.
了解当前状态与目标：
  1. 检查完整性：
    • 功能是否完整？
    • 是否有需要保留的已知问题（用TODO标记）？
    • 质量标准是什么？（MVP还是旗舰级功能？）
    • 发布时间？（有多少润色时间？）
  2. 识别润色方向：
    • 视觉不一致问题
    • 间距与对齐问题
    • 交互状态缺失
    • 文案不一致
    • 边缘场景与错误状态
    • 加载与过渡流畅度
关键提示：润色是最后一步，而非第一步。不要对功能未完成的内容进行润色。

Polish Systematically

系统化润色

Work through these dimensions methodically:
按以下维度有序推进：

Visual Alignment & Spacing

视觉对齐与间距

  • Pixel-perfect alignment: Everything lines up to grid
  • Consistent spacing: All gaps use spacing scale (no random 13px gaps)
  • Optical alignment: Adjust for visual weight (icons may need offset for optical centering)
  • Responsive consistency: Spacing and alignment work at all breakpoints
  • Grid adherence: Elements snap to baseline grid
Check:
  • Enable grid overlay and verify alignment
  • Check spacing with browser inspector
  • Test at multiple viewport sizes
  • Look for elements that "feel" off
  • 像素级精准对齐：所有元素对齐网格
  • 间距一致性：所有间隙使用间距刻度（无随机13px间隙）
  • 视觉对齐调整：根据视觉重量调整（图标可能需要偏移以实现视觉居中）
  • 响应式一致性：所有断点下间距与对齐保持一致
  • 网格遵循：元素贴合基线网格
检查项：
  • 启用网格覆盖层并验证对齐
  • 使用浏览器检查工具核查间距
  • 在多个视口尺寸下测试
  • 找出“看起来不对劲”的元素

Typography Refinement

排版优化

  • Hierarchy consistency: Same elements use same sizes/weights throughout
  • Line length: 45-75 characters for body text
  • Line height: Appropriate for font size and context
  • Widows & orphans: No single words on last line
  • Hyphenation: Appropriate for language and column width
  • Kerning: Adjust letter spacing where needed (especially headlines)
  • Font loading: No FOUT/FOIT flashes
  • 层级一致性：相同元素全程使用相同尺寸/字重
  • 行长度：正文文本保持45-75字符
  • 行高：与字体大小和场景匹配
  • 孤行处理：避免最后一行仅单个单词
  • 连字符使用：根据语言和列宽合理使用
  • 字距调整：按需调整字母间距（尤其标题）
  • 字体加载：无FOUT/FOIT闪烁

Color & Contrast

颜色与对比度

  • Contrast ratios: All text meets WCAG standards
  • Consistent token usage: No hard-coded colors, all use design tokens
  • Theme consistency: Works in all theme variants
  • Color meaning: Same colors mean same things throughout
  • Accessible focus: Focus indicators visible with sufficient contrast
  • Tinted neutrals: No pure gray or pure black—add subtle color tint (0.01 chroma)
  • Gray on color: Never put gray text on colored backgrounds—use a shade of that color or transparency
  • 对比度比例：所有文本符合WCAG标准
  • 令牌使用一致性：无硬编码颜色，全部使用设计令牌
  • 主题一致性：在所有主题变体中正常显示
  • 颜色语义一致性：相同颜色在全程表达相同含义
  • 可访问焦点状态：焦点指示器可见且对比度充足
  • 带色调中性色：不使用纯灰或纯黑——添加细微色调（0.01色度）
  • 彩色背景文本规则：切勿在彩色背景上使用灰色文本——使用该颜色的阴影或透明度

Interaction States

交互状态

Every interactive element needs all states:
  • Default: Resting state
  • Hover: Subtle feedback (color, scale, shadow)
  • Focus: Keyboard focus indicator (never remove without replacement)
  • Active: Click/tap feedback
  • Disabled: Clearly non-interactive
  • Loading: Async action feedback
  • Error: Validation or error state
  • Success: Successful completion
Missing states create confusion and broken experiences.
每个交互元素需具备完整状态：
  • 默认状态：静止状态
  • 悬停状态：细微反馈（颜色、缩放、阴影）
  • 焦点状态：键盘焦点指示器（禁止移除而不替换）
  • 激活状态：点击/触摸反馈
  • 禁用状态：明确显示非交互性
  • 加载状态：异步操作反馈
  • 错误状态：验证或错误提示
  • 成功状态：操作完成确认
缺失状态会造成混淆和体验断裂。

Micro-interactions & Transitions

微交互与过渡

  • Smooth transitions: All state changes animated appropriately (150-300ms)
  • Consistent easing: Use ease-out-quart/quint/expo for natural deceleration. Never bounce or elastic—they feel dated.
  • No jank: 60fps animations, only animate transform and opacity
  • Appropriate motion: Motion serves purpose, not decoration
  • Reduced motion: Respects 
    prefers-reduced-motion
  • 平滑过渡：所有状态变化使用合适动画（150-300ms）
  • 缓动一致性：使用ease-out-quart/quint/expo实现自然减速。禁止使用弹跳或弹性效果——这类效果已过时。
  • 无卡顿：动画保持60fps，仅对transform和opacity属性执行动画
  • 动效合理性：动效服务于功能，而非装饰
  • 适配减少动效偏好：遵循
    prefers-reduced-motion
    设置

Content & Copy

内容与文案

  • Consistent terminology: Same things called same names throughout
  • Consistent capitalization: Title Case vs Sentence case applied consistently
  • Grammar & spelling: No typos
  • Appropriate length: Not too wordy, not too terse
  • Punctuation consistency: Periods on sentences, not on labels (unless all labels have them)
  • 术语一致性：相同事物全程使用相同名称
  • 大小写一致性：统一使用标题大小写或句子大小写
  • 语法与拼写：无拼写错误
  • 长度适宜：不过于冗长也不过于简洁
  • 标点一致性：句子使用句号，标签不使用（除非所有标签都使用）

Icons & Images

图标与图片

  • Consistent style: All icons from same family or matching style
  • Appropriate sizing: Icons sized consistently for context
  • Proper alignment: Icons align with adjacent text optically
  • Alt text: All images have descriptive alt text
  • Loading states: Images don't cause layout shift, proper aspect ratios
  • Retina support: 2x assets for high-DPI screens
  • 风格一致性：所有图标来自同一系列或匹配风格
  • 尺寸适配：图标尺寸与场景一致
  • 对齐准确：图标与相邻文本视觉对齐
  • 替代文本：所有图片配有描述性alt文本
  • 加载状态：图片不会导致布局偏移，保持正确宽高比
  • 视网膜屏支持：为高DPI屏幕提供2倍分辨率资源

Forms & Inputs

表单与输入框

  • Label consistency: All inputs properly labeled
  • Required indicators: Clear and consistent
  • Error messages: Helpful and consistent
  • Tab order: Logical keyboard navigation
  • Auto-focus: Appropriate (don't overuse)
  • Validation timing: Consistent (on blur vs on submit)
  • 标签一致性：所有输入框均正确标注
  • 必填项标识：清晰且统一
  • 错误提示：有用且统一
  • Tab键顺序：符合逻辑的键盘导航
  • 自动聚焦：合理使用（勿过度）
  • 验证时机：统一（失焦时验证 vs 提交时验证）

Edge Cases & Error States

边缘场景与错误状态

  • Loading states: All async actions have loading feedback
  • Empty states: Helpful empty states, not just blank space
  • Error states: Clear error messages with recovery paths
  • Success states: Confirmation of successful actions
  • Long content: Handles very long names, descriptions, etc.
  • No content: Handles missing data gracefully
  • Offline: Appropriate offline handling (if applicable)
  • 加载状态：所有异步操作均有加载反馈
  • 空状态：提供有用的空状态提示，而非仅空白区域
  • 错误状态：清晰的错误提示及恢复路径
  • 成功状态：操作成功的确认提示
  • 长内容处理：支持超长名称、描述等内容
  • 无内容处理：优雅处理缺失数据
  • 离线处理：合理的离线适配（如适用）

Responsiveness

响应式适配

  • All breakpoints: Test mobile, tablet, desktop
  • Touch targets: 44x44px minimum on touch devices
  • Readable text: No text smaller than 14px on mobile
  • No horizontal scroll: Content fits viewport
  • Appropriate reflow: Content adapts logically
  • 全断点测试：测试移动端、平板端、桌面端
  • 触控目标尺寸：触控设备上最小44x44px
  • 文本可读性：移动端文本不小于14px
  • 无横向滚动：内容适配视口
  • 合理回流：内容逻辑适配不同尺寸

Performance

性能优化

  • Fast initial load: Optimize critical path
  • No layout shift: Elements don't jump after load (CLS)
  • Smooth interactions: No lag or jank
  • Optimized images: Appropriate formats and sizes
  • Lazy loading: Off-screen content loads lazily
  • 快速初始加载：优化关键路径
  • 无布局偏移：加载后元素不跳转（CLS）
  • 交互流畅：无延迟或卡顿
  • 图片优化：使用合适格式和尺寸
  • 懒加载：屏外内容延迟加载

Code Quality

代码质量

  • Remove console logs: No debug logging in production
  • Remove commented code: Clean up dead code
  • Remove unused imports: Clean up unused dependencies
  • Consistent naming: Variables and functions follow conventions
  • Type safety: No TypeScript 
    any
    or ignored errors
  • Accessibility: Proper ARIA labels and semantic HTML
  • 移除控制台日志：生产环境无调试日志
  • 移除注释代码：清理无用代码
  • 移除未使用导入：清理未使用依赖
  • 命名一致性：变量和函数遵循约定
  • 类型安全：无TypeScript 
    any
    类型或忽略错误
  • 无障碍适配：正确使用ARIA标签和语义化HTML

Polish Checklist

润色检查清单

Go through systematically:
  • Visual alignment perfect at all breakpoints
  • Spacing uses design tokens consistently
  • Typography hierarchy consistent
  • All interactive states implemented
  • All transitions smooth (60fps)
  • Copy is consistent and polished
  • Icons are consistent and properly sized
  • All forms properly labeled and validated
  • Error states are helpful
  • Loading states are clear
  • Empty states are welcoming
  • Touch targets are 44x44px minimum
  • Contrast ratios meet WCAG AA
  • Keyboard navigation works
  • Focus indicators visible
  • No console errors or warnings
  • No layout shift on load
  • Works in all supported browsers
  • Respects reduced motion preference
  • Code is clean (no TODOs, console.logs, commented code)
IMPORTANT: Polish is about details. Zoom in. Squint at it. Use it yourself. The little things add up.
NEVER:
  • Polish before it's functionally complete
  • Spend hours on polish if it ships in 30 minutes (triage)
  • Introduce bugs while polishing (test thoroughly)
  • Ignore systematic issues (if spacing is off everywhere, fix the system)
  • Perfect one thing while leaving others rough (consistent quality level)
  • Create new one-off components when design system equivalents exist
  • Hard-code values that should use design tokens
按顺序逐一检查：
  • 所有断点下视觉对齐完美
  • 间距始终使用设计令牌
  • 排版层级一致
  • 所有交互状态已实现
  • 所有过渡平滑（60fps）
  • 文案一致且打磨到位
  • 图标风格一致且尺寸合适
  • 所有表单均正确标注并验证
  • 错误状态提示有用
  • 加载状态清晰
  • 空状态友好
  • 触控目标最小44x44px
  • 对比度符合WCAG AA标准
  • 键盘导航正常
  • 焦点指示器可见
  • 无控制台错误或警告
  • 加载时无布局偏移
  • 在所有支持的浏览器中正常运行
  • 遵循减少动效偏好设置
  • 代码整洁（无TODO、console.log、注释代码）
重要提示：润色关乎细节。放大查看、眯眼观察、亲自使用。细节积累起来效果显著。
绝对禁止：
  • 在功能未完成前进行润色
  • 如果30分钟后就要发布，却花费数小时进行润色（需优先处理重点）
  • 润色时引入新bug（需全面测试）
  • 忽视系统性问题（如果多处间距不符，应修复整个系统）
  • 只完善某一处而忽略其他部分（保持统一质量水平）
  • 当设计系统已有对应组件时，仍创建新的一次性组件
  • 硬编码本应使用设计令牌的值

Final Verification

最终验证

Before marking as done:
  • Use it yourself: Actually interact with the feature
  • Test on real devices: Not just browser DevTools
  • Ask someone else to review: Fresh eyes catch things
  • Compare to design: Match intended design
  • Check all states: Don't just test happy path
标记完成前需：
  • 亲自使用：实际操作该功能
  • 在真实设备上测试：不局限于浏览器开发者工具
  • 请他人审核：新鲜视角能发现问题
  • 与设计稿对比：匹配预期设计
  • 检查所有状态：勿仅测试正常流程

Clean Up

清理工作

After polishing, ensure code quality:
  • Replace custom implementations: If the design system provides a component you reimplemented, switch to the shared version.
  • Remove orphaned code: Delete unused styles, components, or files made obsolete by polish.
  • Consolidate tokens: If you introduced new values, check whether they should be tokens.
  • Verify DRYness: Look for duplication introduced during polishing and consolidate.
Remember: You have impeccable attention to detail and exquisite taste. Polish until it feels effortless, looks intentional, and works flawlessly. Sweat the details - they matter.
润色完成后，确保代码质量：
  • 替换自定义实现：如果设计系统提供了你重新实现的组件，切换为共享版本。
  • 移除废弃代码：删除因润色而过时的无用样式、组件或文件。
  • 整合令牌：如果引入了新值，检查是否应转为令牌。
  • 验证DRY原则：查找润色过程中引入的重复代码并整合。
记住：你具备极致的细节关注度和出色的审美能力。润色至操作流畅、设计自然、功能完美为止。重视细节——它们至关重要。