← Catalog

design-polish

Perform a final quality pass fixing alignment, spacing, consistency, and micro-detail issues before shipping. Use when asked to polish, add finishing touches, do a pre-launch review, fix something that looks off, or go from good to great.

Source

Mandatory Preparation

Invoke /design-frontend — it contains design principles, anti-patterns, and the Context Gathering Protocol. Follow the protocol before proceeding. If no design context exists yet, run /design-context 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.

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 is 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

Polish is the last step, not the first. Do not polish work that is not functionally complete.

Polish Systematically

Work through these dimensions methodically:

Visual Alignment and 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, 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 and 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 and 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 and 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.
  • No jank: 60fps animations, only animate transform and opacity
  • Appropriate motion: Motion serves purpose, not decoration
  • Reduced motion: Respects prefers-reduced-motion

Content and Copy

  • Consistent terminology: Same things called same names throughout
  • Consistent capitalization: Title Case vs Sentence case applied consistently
  • Grammar and spelling: No typos
  • Appropriate length: Not too wordy, not too terse
  • Punctuation consistency: Periods on sentences, not on labels

Icons and 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 do not cause layout shift, proper aspect ratios
  • Retina support: 2x assets for high-DPI screens

Forms and 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 (do not overuse)
  • Validation timing: Consistent (on blur vs on submit)

Edge Cases and 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

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 do not 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)

NEVER:

  • Polish before it is 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

  • 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: Do not just test happy path