1---
  2name: polish
  3description: "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."
  4argument-hint: "[target]"
  5user-invocable: true
  6---
  7
  8## MANDATORY PREPARATION
  9
 10Invoke {{command_prefix}}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 {{command_prefix}}impeccable teach first. Additionally gather: quality bar (MVP vs flagship).
 11
 12---
 13
 14Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished.
 15
 16## Design System Discovery
 17
 18Before polishing, understand the system you are polishing toward:
 19
 201. **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.
 212. **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?
 223. **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.
 23
 24If a design system exists, polish should align the feature with it. If none exists, polish against the conventions visible in the codebase.
 25
 26## Pre-Polish Assessment
 27
 28Understand the current state and goals:
 29
 301. **Review completeness**:
 31   - Is it functionally complete?
 32   - Are there known issues to preserve (mark with TODOs)?
 33   - What's the quality bar? (MVP vs flagship feature?)
 34   - When does it ship? (How much time for polish?)
 35
 362. **Identify polish areas**:
 37   - Visual inconsistencies
 38   - Spacing and alignment issues
 39   - Interaction state gaps
 40   - Copy inconsistencies
 41   - Edge cases and error states
 42   - Loading and transition smoothness
 43
 44**CRITICAL**: Polish is the last step, not the first. Don't polish work that's not functionally complete.
 45
 46## Polish Systematically
 47
 48Work through these dimensions methodically:
 49
 50### Visual Alignment & Spacing
 51
 52- **Pixel-perfect alignment**: Everything lines up to grid
 53- **Consistent spacing**: All gaps use spacing scale (no random 13px gaps)
 54- **Optical alignment**: Adjust for visual weight (icons may need offset for optical centering)
 55- **Responsive consistency**: Spacing and alignment work at all breakpoints
 56- **Grid adherence**: Elements snap to baseline grid
 57
 58**Check**:
 59- Enable grid overlay and verify alignment
 60- Check spacing with browser inspector
 61- Test at multiple viewport sizes
 62- Look for elements that "feel" off
 63
 64### Typography Refinement
 65
 66- **Hierarchy consistency**: Same elements use same sizes/weights throughout
 67- **Line length**: 45-75 characters for body text
 68- **Line height**: Appropriate for font size and context
 69- **Widows & orphans**: No single words on last line
 70- **Hyphenation**: Appropriate for language and column width
 71- **Kerning**: Adjust letter spacing where needed (especially headlines)
 72- **Font loading**: No FOUT/FOIT flashes
 73
 74### Color & Contrast
 75
 76- **Contrast ratios**: All text meets WCAG standards
 77- **Consistent token usage**: No hard-coded colors, all use design tokens
 78- **Theme consistency**: Works in all theme variants
 79- **Color meaning**: Same colors mean same things throughout
 80- **Accessible focus**: Focus indicators visible with sufficient contrast
 81- **Tinted neutrals**: No pure gray or pure black—add subtle color tint (0.01 chroma)
 82- **Gray on color**: Never put gray text on colored backgrounds—use a shade of that color or transparency
 83
 84### Interaction States
 85
 86Every interactive element needs all states:
 87
 88- **Default**: Resting state
 89- **Hover**: Subtle feedback (color, scale, shadow)
 90- **Focus**: Keyboard focus indicator (never remove without replacement)
 91- **Active**: Click/tap feedback
 92- **Disabled**: Clearly non-interactive
 93- **Loading**: Async action feedback
 94- **Error**: Validation or error state
 95- **Success**: Successful completion
 96
 97**Missing states create confusion and broken experiences**.
 98
 99### Micro-interactions & Transitions
100
101- **Smooth transitions**: All state changes animated appropriately (150-300ms)
102- **Consistent easing**: Use ease-out-quart/quint/expo for natural deceleration. Never bounce or elastic—they feel dated.
103- **No jank**: 60fps animations, only animate transform and opacity
104- **Appropriate motion**: Motion serves purpose, not decoration
105- **Reduced motion**: Respects `prefers-reduced-motion`
106
107### Content & Copy
108
109- **Consistent terminology**: Same things called same names throughout
110- **Consistent capitalization**: Title Case vs Sentence case applied consistently
111- **Grammar & spelling**: No typos
112- **Appropriate length**: Not too wordy, not too terse
113- **Punctuation consistency**: Periods on sentences, not on labels (unless all labels have them)
114
115### Icons & Images
116
117- **Consistent style**: All icons from same family or matching style
118- **Appropriate sizing**: Icons sized consistently for context
119- **Proper alignment**: Icons align with adjacent text optically
120- **Alt text**: All images have descriptive alt text
121- **Loading states**: Images don't cause layout shift, proper aspect ratios
122- **Retina support**: 2x assets for high-DPI screens
123
124### Forms & Inputs
125
126- **Label consistency**: All inputs properly labeled
127- **Required indicators**: Clear and consistent
128- **Error messages**: Helpful and consistent
129- **Tab order**: Logical keyboard navigation
130- **Auto-focus**: Appropriate (don't overuse)
131- **Validation timing**: Consistent (on blur vs on submit)
132
133### Edge Cases & Error States
134
135- **Loading states**: All async actions have loading feedback
136- **Empty states**: Helpful empty states, not just blank space
137- **Error states**: Clear error messages with recovery paths
138- **Success states**: Confirmation of successful actions
139- **Long content**: Handles very long names, descriptions, etc.
140- **No content**: Handles missing data gracefully
141- **Offline**: Appropriate offline handling (if applicable)
142
143### Responsiveness
144
145- **All breakpoints**: Test mobile, tablet, desktop
146- **Touch targets**: 44x44px minimum on touch devices
147- **Readable text**: No text smaller than 14px on mobile
148- **No horizontal scroll**: Content fits viewport
149- **Appropriate reflow**: Content adapts logically
150
151### Performance
152
153- **Fast initial load**: Optimize critical path
154- **No layout shift**: Elements don't jump after load (CLS)
155- **Smooth interactions**: No lag or jank
156- **Optimized images**: Appropriate formats and sizes
157- **Lazy loading**: Off-screen content loads lazily
158
159### Code Quality
160
161- **Remove console logs**: No debug logging in production
162- **Remove commented code**: Clean up dead code
163- **Remove unused imports**: Clean up unused dependencies
164- **Consistent naming**: Variables and functions follow conventions
165- **Type safety**: No TypeScript `any` or ignored errors
166- **Accessibility**: Proper ARIA labels and semantic HTML
167
168## Polish Checklist
169
170Go through systematically:
171
172- [ ] Visual alignment perfect at all breakpoints
173- [ ] Spacing uses design tokens consistently
174- [ ] Typography hierarchy consistent
175- [ ] All interactive states implemented
176- [ ] All transitions smooth (60fps)
177- [ ] Copy is consistent and polished
178- [ ] Icons are consistent and properly sized
179- [ ] All forms properly labeled and validated
180- [ ] Error states are helpful
181- [ ] Loading states are clear
182- [ ] Empty states are welcoming
183- [ ] Touch targets are 44x44px minimum
184- [ ] Contrast ratios meet WCAG AA
185- [ ] Keyboard navigation works
186- [ ] Focus indicators visible
187- [ ] No console errors or warnings
188- [ ] No layout shift on load
189- [ ] Works in all supported browsers
190- [ ] Respects reduced motion preference
191- [ ] Code is clean (no TODOs, console.logs, commented code)
192
193**IMPORTANT**: Polish is about details. Zoom in. Squint at it. Use it yourself. The little things add up.
194
195**NEVER**:
196- Polish before it's functionally complete
197- Spend hours on polish if it ships in 30 minutes (triage)
198- Introduce bugs while polishing (test thoroughly)
199- Ignore systematic issues (if spacing is off everywhere, fix the system)
200- Perfect one thing while leaving others rough (consistent quality level)
201- Create new one-off components when design system equivalents exist
202- Hard-code values that should use design tokens
203
204## Final Verification
205
206Before marking as done:
207
208- **Use it yourself**: Actually interact with the feature
209- **Test on real devices**: Not just browser DevTools
210- **Ask someone else to review**: Fresh eyes catch things
211- **Compare to design**: Match intended design
212- **Check all states**: Don't just test happy path
213
214## Clean Up
215
216After polishing, ensure code quality:
217
218- **Replace custom implementations**: If the design system provides a component you reimplemented, switch to the shared version.
219- **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish.
220- **Consolidate tokens**: If you introduced new values, check whether they should be tokens.
221- **Verify DRYness**: Look for duplication introduced during polishing and consolidate.
222
223Remember: You have impeccable attention to detail and exquisite taste. Polish until it feels effortless, looks intentional, and works flawlessly. Sweat the details - they matter.
224