Polish

MANDATORY PREPARATION

Invoke {{command_prefix}}impeccable — 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 {{command_prefix}}impeccable teach 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.

Design System Discovery

Before polishing, understand the system you are polishing toward:

Find the design system: Search for design system documentation, component libraries, style guides, or token definitions. Study the core patterns: color tokens, spacing scale, typography styles, component API.
Note the conventions: How are shared components imported? What spacing scale is used? Which colors come from tokens vs hard-coded values? What motion and interaction patterns are established?
Identify drift: Where does the target feature deviate from the system? Hard-coded values that should be tokens, custom components that duplicate shared ones, spacing that doesn't match the scale.

If a design system exists, polish should align the feature with it. If none exists, polish against the conventions visible in the codebase.

Pre-Polish Assessment

Understand the current state and goals:

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

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:

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)
Create new one-off components when design system equivalents exist
Hard-code values that should use design tokens

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

Clean Up

After polishing, ensure code quality:

Replace custom implementations: If the design system provides a component you reimplemented, switch to the shared version.
Remove orphaned code: Delete unused styles, components, or files made obsolete by polish.
Consolidate tokens: If you introduced new values, check whether they should be tokens.
Verify DRYness: Look for duplication introduced during polishing and consolidate.

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.

Mirrored from https://github.com/pbakaus/impeccable — original author: pbakaus, license: Apache-2.0. This is an unclaimed mirror. Content and ownership transfer to the author when they claim this account.