Design Polish

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