/polish

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