Back to Details

polish

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

MANDATORY PREPARATION

强制准备

Users start this workflow with 
/polish
. Once this skill is active, load $frontend-design — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow that protocol before proceeding — if no design context exists yet, you MUST load $setup 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.
Polish should make existing hierarchy and systems more precise. It should not be used to decorate a weak foundation.
Consult the 
empty-state
skill when zero-data surfaces themselves need design work. Use 
onboard
when the broader activation flow, aha moment, or first-run strategy is the real issue.
用户通过 
/polish
启动此工作流。此 skill 激活后，加载 $frontend-design——其中包含设计原则、反模式及 上下文收集协议（Context Gathering Protocol）。继续之前必须遵循该协议；如果尚无设计上下文，则必须先加载 $setup。此外还需确认：质量标准（MVP 还是旗舰级）。
执行一次细致入微的最终检查，找出所有让优秀作品与卓越作品拉开差距的细节。发布完成与精心打磨之间的区别，正来自这些细节。
打磨应当让既有的信息层级与设计系统更加精准，而不是用来装饰薄弱的基础。
当零数据界面本身需要专门设计时，请查阅 
empty-state
skill。当更广泛的激活流程、顿悟时刻（aha moment）或首次使用策略才是真正的问题时，请使用 
onboard
。

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:
Consult the hierarchy checklist for grayscale tests, action hierarchy, and label/value treatment. Consult the text hierarchy and readability for line length, line-height, alignment, baseline, and title restraint. Consult the action hierarchy when checking whether actions lead or recede correctly. Consult the semantic color when checking alerts, status, and tinted semantic surfaces. Consult the design-system alignment when deciding whether a polish issue is really local detail or system drift. Consult the surface separation when borders, cards, shadows, overlap, or background shifts feel noisy or inconsistent. Consult the image treatment when screenshots, icons, or media feel awkward, unreadable, or poorly contained. Consult the finishing touches when default UI elements, accents, or decorative backgrounds need more intentional refinement.
按以下维度逐一推进：
查阅层级检查清单，了解灰度测试、操作层级以及标签/值处理方式。 查阅文本层级与可读性，了解行宽、行高、对齐方式、基线以及标题的克制使用。 查阅操作层级，检查操作是否正确地引导或弱化用户注意力。 查阅语义化颜色，检查提醒、状态及带色调的语义化界面。 查阅设计系统一致性，判断某个打磨问题究竟是局部细节，还是系统发生了偏移。 查阅界面分隔，检查边框、卡片、阴影、重叠或背景变化是否显得杂乱或不一致。 查阅图像处理，检查截图、图标或媒体素材是否显得突兀、难以辨认或未被妥善容纳。 查阅收尾细节，在默认 UI 元素、强调色或装饰性背景需要更有意图地精修时参考。

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
  • Group clarity: There is more space around groups than within them
  • Surface separation: Borders, shadows, cards, and background shifts are used deliberately instead of all at once
Check:
  • Enable grid overlay and verify alignment
  • Check spacing with browser inspector
  • Test at multiple viewport sizes
  • Look for elements that "feel" off
  • 像素级对齐：所有元素与网格准确对齐
  • 间距一致：所有间隙都使用间距刻度（不能出现随意的 13px 间隙）
  • 视觉对齐：根据视觉重量进行调整（图标可能需要偏移才能实现视觉居中）
  • 响应式一致性：间距和对齐在所有 breakpoints 下均正常
  • 遵循网格：元素与基线网格对齐
  • 分组清晰：组与组之间的空间应大于组内元素之间的空间
  • 界面分隔：有意识地使用边框、阴影、卡片和背景变化，而不是同时堆叠所有手段
检查：
  • 启用 grid overlay 并验证对齐
  • 使用 browser inspector 检查间距
  • 在多个 viewport 尺寸下测试
  • 找出那些感觉“不对劲”的元素

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
  • Baseline alignment: Mixed-size text aligns cleanly when sharing a row
  • Link restraint: Secondary links are not colored so loudly that they compete with the main path
  • Number alignment: Numeric columns are right-aligned when comparison matters
  • Title restraint: Section headings support the content instead of overpowering it
  • 层级一致：相同元素在各处使用相同的字号/字重
  • 行宽：正文保持 45-75 个字符
  • 行高：与字号和使用场景相匹配
  • 避免孤行与孤字：末行不要只留下一个词
  • 断词处理：根据语言和栏宽采用合适的断词方式
  • 字距调整：在需要时调整 letter spacing（尤其是标题）
  • 字体加载：不出现 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
  • Palette discipline: Surfaces and accents use defined ramps, not improvised one-off shades
  • 对比度：所有文本均符合 WCAG 标准
  • Token 使用一致：不硬编码颜色，全部使用 design tokens
  • 主题一致：适用于所有主题变体
  • 颜色含义一致：相同颜色在各处表达相同含义
  • 无障碍焦点：焦点指示器清晰可见，并具有足够的对比度
  • 带色调的中性色：不使用纯灰或纯黑，加入微妙的色彩倾向（0.01 chroma）
  • 彩色背景上的文字：不要在彩色背景上使用灰色文字，应使用该背景色的深浅变体或透明色
  • 色板纪律：界面表面和强调色使用已定义的色阶，而不是临时创造零散色值

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 / press feedback
  • Disabled: Clearly non-interactive
  • Loading: Async action feedback
  • Error: Validation or error state
  • Success: Successful completion
Missing states create confusion and broken experiences.
Make sure action hierarchy remains intact across states: the primary action should still read as primary on hover, focus, active, loading, and disabled.
每个交互元素都需要具备全部状态：
  • 默认（Default）：静止状态
  • 悬停（Hover）：提供细微反馈（颜色、缩放、阴影）
  • 焦点（Focus）：提供键盘焦点指示器（移除后必须提供替代方案）
  • 激活（Active）：提供点击/按压反馈
  • 禁用（Disabled）：明确表现为不可交互
  • 加载（Loading）：提供异步操作反馈
  • 错误（Error）：提供验证或错误状态
  • 成功（Success）：确认操作已成功完成
缺失状态会造成困惑和体验损坏。
确保操作层级在各状态下依然完整：主要操作在 hover、focus、active、loading 和 disabled 状态下都应仍然清晰呈现为主要操作。

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)
  • 术语一致：相同事物在各处使用相同名称
  • 大小写一致：标题式大小写（Title Case）与句式大小写（Sentence case）应始终保持一致
  • 语法与拼写：没有拼写错误
  • 长度适当：既不过于冗长，也不过于简短
  • 标点一致：句子使用句号，标签不使用句号（除非所有标签都使用句号）

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
  • Screenshot legibility: Screenshots are not scaled so small that their structure becomes useless
  • Icon sizing discipline: Tiny icons are not enlarged into chunky blobs, and detailed icons are not reduced to mush
  • 风格一致：所有图标来自同一图标家族或采用匹配风格
  • 尺寸适当：图标尺寸与使用场景保持一致
  • 对齐正确：图标与相邻文本实现视觉对齐
  • 替代文本：所有图像都有描述性的 alt text
  • 加载状态：图像不会导致布局偏移，并保持正确的宽高比
  • Retina 支持：为高 DPI 屏幕提供 2x 素材
  • 截图可读性：截图不会被缩得过小，以至于其结构失去可读性
  • 图标尺寸克制：小图标不会被放大成笨重的色块，细节丰富的图标也不会被缩小得模糊不清

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 顺序：键盘导航顺序符合逻辑
  • 自动聚焦：使用恰当（不要过度使用）
  • 验证时机：保持一致（blur 时还是 submit 时）

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)
  • Empty-state hierarchy: Empty states have a clear next action and don't leave dead controls hanging around needlessly
  • 加载状态：所有异步操作都有加载反馈
  • 空状态：提供有帮助的空状态，而不是留下一片空白
  • 错误状态：错误消息清晰，并提供恢复路径
  • 成功状态：确认操作已成功完成
  • 长内容：正确处理非常长的名称、描述等内容
  • 无内容：优雅处理数据缺失
  • 离线：在适用的情况下提供恰当的离线处理
  • 空状态层级：空状态应提供清晰的下一步操作，不要无意义地留下失效控件

Responsiveness

响应式

  • All breakpoints: Test narrow, medium, and wide layouts
  • Touch targets: 44x44px minimum on touch devices
  • Readable text: No text smaller than 14px in compact layouts
  • No horizontal scroll: Content fits viewport
  • Appropriate reflow: Content adapts logically
  • 所有 breakpoints：测试窄、中、宽三种布局
  • 触控目标：触控设备上至少为 44x44px
  • 文本可读：紧凑布局中不使用小于 14px 的文字
  • 无水平滚动：内容适配 viewport
  • 合理重排：内容以符合逻辑的方式自适应

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
  • 移除 console logs：生产环境中不保留调试日志
  • 移除注释掉的代码：清理无效代码
  • 移除未使用的 imports：清理未使用的 dependencies
  • 命名一致：变量和函数遵循既定规范
  • 类型安全：不使用 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)
  • Use borders, shadows, or color flourishes to hide unresolved hierarchy problems
  • Use bright link color, border clutter, or decorative overlap where quieter separation would work better
逐项系统检查：
  • 所有 breakpoints 下的视觉对齐均完美
  • 间距始终一致地使用 design tokens
  • 排版层级一致
  • 所有交互状态均已实现
  • 所有过渡均流畅（60fps）
  • 文案一致且经过打磨
  • 图标风格统一且尺寸适当
  • 所有表单均有恰当标签和验证
  • 错误状态具有指导意义
  • 加载状态清晰明确
  • 空状态友好且具有引导性
  • 触控目标至少为 44x44px
  • 对比度符合 WCAG AA
  • 键盘导航正常工作
  • 焦点指示器清晰可见
  • 没有 console 错误或警告
  • 加载时没有布局偏移
  • 在所有受支持的浏览器中正常工作
  • 遵循减少动态效果偏好
  • 代码整洁（无 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
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.
在标记为完成之前：
  • 亲自使用：实际与该功能进行交互
  • 在真实设备上测试：不要只依赖 browser DevTools
  • 请其他人审查：全新的视角能发现遗漏
  • 与设计稿对比：与预期设计保持一致
  • 检查所有状态：不要只测试 happy path
记住：你拥有对细节无可挑剔的关注和精致入微的审美。持续打磨，直到它感觉自然、视觉表达有意图且运行无瑕。死磕细节——它们很重要。