Polish

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pbakaus/impeccable/llms.txt

Use this file to discover all available pages before exploring further.

​

When to Use

• Perform a final quality pass before shipping
• Fix subtle alignment and spacing issues
• Ensure all interaction states are implemented
• Catch typography, color, and consistency issues
• Add missing micro-interactions and transitions
• Perfect edge cases and error states
• Bring work from “good enough” to “exceptional”

​

Parameters

​

Important Prerequisites

​

Workflow

​

Polish Dimensions

​

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

​

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

• 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

​

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

/* Good: Natural deceleration */
.button {
  transition: all 200ms cubic-bezier(0.165, 0.84, 0.44, 1); /* ease-out-quart */
}

/* Bad: Dated and distracting */
.button {
  transition: all 500ms cubic-bezier(0.68, -0.55, 0.265, 1.55); /* bounce */
}

​

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)

​

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)

​

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

• 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)

​

Usage Example

# Polish entire interface
/polish

# Polish specific feature
/polish target="checkout flow"

​

Best Practices

• Zoom in and scrutinize details
• Use the feature yourself
• Test on real devices
• Get fresh eyes to review
• Maintain consistent quality level throughout

• 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)

​

Important Notes