Spaces:
Running
Running
| name: polish | |
| description: 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. | |
| user-invocable: true | |
| argument-hint: "[target]" | |
| ## MANDATORY PREPARATION | |
| Invoke /frontend-design — 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 /teach-impeccable 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. | |
| ## 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. | |
| ## 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: | |
| - [ ] 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) | |
| ## 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. |