Perform a meticulous final pass to catch the small details that separate good work from great work.
Design System Discovery
Before polishing, understand the system you are polishing toward:
- 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.
- 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?
- 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.
Pre-Polish Assessment
Understand the current state and goals:
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?)
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.
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
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
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
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
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
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)
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
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
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
Polish Checklist
Go through systematically:
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
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.
1---2name: polish-43description: Performs a final quality pass fixing alignment, spacing, consistency, and micro-detail issues before shipping. Use when the user mentions polish, finishing touches, pre-launch review, something looks off, or wants to go from good to great.4user-invocable: true5argument-hint: "[target]"6metadata:7 version: "2.1.1"8 tags: "polish, ui, quality"9 source: https://skillmd.com/skills/shipshitdev/polish-410 upstream: https://github.com/pbakaus/impeccable/blob/main/skill/reference/polish.md11 upstream_version: skill-v2.1.112 upstream_latest: skill-v3.5.013 last_synced: "2026-06-12"14 license: Apache-2.015---1617Perform a meticulous final pass to catch the small details that separate good work from great work.1819## Design System Discovery2021Before polishing, understand the system you are polishing toward:22231. **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.242. **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?253. **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.2627If a design system exists, polish should align the feature with it. If none exists, polish against the conventions visible in the codebase.2829## Pre-Polish Assessment3031Understand the current state and goals:32331. **Review completeness**:34 - Is it functionally complete?35 - Are there known issues to preserve (mark with TODOs)?36 - What's the quality bar? (MVP vs flagship feature?)37 - When does it ship? (How much time for polish?)38392. **Identify polish areas**:40 - Visual inconsistencies41 - Spacing and alignment issues42 - Interaction state gaps43 - Copy inconsistencies44 - Edge cases and error states45 - Loading and transition smoothness4647**CRITICAL**: Polish is the last step, not the first. Don't polish work that's not functionally complete.4849## Polish Systematically5051Work through these dimensions methodically:5253### Visual Alignment & Spacing5455- **Pixel-perfect alignment**: Everything lines up to grid56- **Consistent spacing**: All gaps use spacing scale (no random 13px gaps)57- **Optical alignment**: Adjust for visual weight (icons may need offset for optical centering)58- **Responsive consistency**: Spacing and alignment work at all breakpoints59- **Grid adherence**: Elements snap to baseline grid6061**Check**:6263- Enable grid overlay and verify alignment64- Check spacing with browser inspector65- Test at multiple viewport sizes66- Look for elements that "feel" off6768### Typography Refinement6970- **Hierarchy consistency**: Same elements use same sizes/weights throughout71- **Line length**: 45-75 characters for body text72- **Line height**: Appropriate for font size and context73- **Widows & orphans**: No single words on last line74- **Hyphenation**: Appropriate for language and column width75- **Kerning**: Adjust letter spacing where needed (especially headlines)76- **Font loading**: No FOUT/FOIT flashes7778### Color & Contrast7980- **Contrast ratios**: All text meets WCAG standards81- **Consistent token usage**: No hard-coded colors, all use design tokens82- **Theme consistency**: Works in all theme variants83- **Color meaning**: Same colors mean same things throughout84- **Accessible focus**: Focus indicators visible with sufficient contrast85- **Tinted neutrals**: No pure gray or pure black—add subtle color tint (0.01 chroma)86- **Gray on color**: Never put gray text on colored backgrounds—use a shade of that color or transparency8788### Interaction States8990Every interactive element needs all states:9192- **Default**: Resting state93- **Hover**: Subtle feedback (color, scale, shadow)94- **Focus**: Keyboard focus indicator (never remove without replacement)95- **Active**: Click/tap feedback96- **Disabled**: Clearly non-interactive97- **Loading**: Async action feedback98- **Error**: Validation or error state99- **Success**: Successful completion100101**Missing states create confusion and broken experiences**.102103### Micro-interactions & Transitions104105- **Smooth transitions**: All state changes animated appropriately (150-300ms)106- **Consistent easing**: Use ease-out-quart/quint/expo for natural deceleration. Never bounce or elastic—they feel dated.107- **No jank**: 60fps animations, only animate transform and opacity108- **Appropriate motion**: Motion serves purpose, not decoration109- **Reduced motion**: Respects `prefers-reduced-motion`110111### Content & Copy112113- **Consistent terminology**: Same things called same names throughout114- **Consistent capitalization**: Title Case vs Sentence case applied consistently115- **Grammar & spelling**: No typos116- **Appropriate length**: Not too wordy, not too terse117- **Punctuation consistency**: Periods on sentences, not on labels (unless all labels have them)118119### Icons & Images120121- **Consistent style**: All icons from same family or matching style122- **Appropriate sizing**: Icons sized consistently for context123- **Proper alignment**: Icons align with adjacent text optically124- **Alt text**: All images have descriptive alt text125- **Loading states**: Images don't cause layout shift, proper aspect ratios126- **Retina support**: 2x assets for high-DPI screens127128### Forms & Inputs129130- **Label consistency**: All inputs properly labeled131- **Required indicators**: Clear and consistent132- **Error messages**: Helpful and consistent133- **Tab order**: Logical keyboard navigation134- **Auto-focus**: Appropriate (don't overuse)135- **Validation timing**: Consistent (on blur vs on submit)136137### Edge Cases & Error States138139- **Loading states**: All async actions have loading feedback140- **Empty states**: Helpful empty states, not just blank space141- **Error states**: Clear error messages with recovery paths142- **Success states**: Confirmation of successful actions143- **Long content**: Handles very long names, descriptions, etc.144- **No content**: Handles missing data gracefully145- **Offline**: Appropriate offline handling (if applicable)146147### Responsiveness148149- **All breakpoints**: Test mobile, tablet, desktop150- **Touch targets**: 44x44px minimum on touch devices151- **Readable text**: No text smaller than 14px on mobile152- **No horizontal scroll**: Content fits viewport153- **Appropriate reflow**: Content adapts logically154155### Performance156157- **Fast initial load**: Optimize critical path158- **No layout shift**: Elements don't jump after load (CLS)159- **Smooth interactions**: No lag or jank160- **Optimized images**: Appropriate formats and sizes161- **Lazy loading**: Off-screen content loads lazily162163### Code Quality164165- **Remove console logs**: No debug logging in production166- **Remove commented code**: Clean up dead code167- **Remove unused imports**: Clean up unused dependencies168- **Consistent naming**: Variables and functions follow conventions169- **Type safety**: No TypeScript `any` or ignored errors170- **Accessibility**: Proper ARIA labels and semantic HTML171172## Polish Checklist173174Go through systematically:175176- [ ] Visual alignment perfect at all breakpoints177- [ ] Spacing uses design tokens consistently178- [ ] Typography hierarchy consistent179- [ ] All interactive states implemented180- [ ] All transitions smooth (60fps)181- [ ] Copy is consistent and polished182- [ ] Icons are consistent and properly sized183- [ ] All forms properly labeled and validated184- [ ] Error states are helpful185- [ ] Loading states are clear186- [ ] Empty states are welcoming187- [ ] Touch targets are 44x44px minimum188- [ ] Contrast ratios meet WCAG AA189- [ ] Keyboard navigation works190- [ ] Focus indicators visible191- [ ] No console errors or warnings192- [ ] No layout shift on load193- [ ] Works in all supported browsers194- [ ] Respects reduced motion preference195- [ ] Code is clean (no TODOs, console.logs, commented code)196197**IMPORTANT**: Polish is about details. Zoom in. Squint at it. Use it yourself. The little things add up.198199**NEVER**:200201- Polish before it's functionally complete202- Spend hours on polish if it ships in 30 minutes (triage)203- Introduce bugs while polishing (test thoroughly)204- Ignore systematic issues (if spacing is off everywhere, fix the system)205- Perfect one thing while leaving others rough (consistent quality level)206- Create new one-off components when design system equivalents exist207- Hard-code values that should use design tokens208209## Final Verification210211Before marking as done:212213- **Use it yourself**: Actually interact with the feature214- **Test on real devices**: Not just browser DevTools215- **Ask someone else to review**: Fresh eyes catch things216- **Compare to design**: Match intended design217- **Check all states**: Don't just test happy path218219## Clean Up220221After polishing, ensure code quality:222223- **Replace custom implementations**: If the design system provides a component you reimplemented, switch to the shared version.224- **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish.225- **Consolidate tokens**: If you introduced new values, check whether they should be tokens.226- **Verify DRYness**: Look for duplication introduced during polishing and consolidate.227228Remember: You have impeccable attention to detail and exquisite taste. Polish until it feels effortless, looks intentional, and works flawlessly. Sweat the details - they matter.