| 1 | > **Additional context needed**: quality bar (MVP vs flagship). |
| 2 | |
| 3 | Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished. |
| 4 | |
| 5 | Detector and automated QA output are defect evidence only. A clean script result is never proof that the design is strong; gather browser evidence and inspect the real interaction path. |
| 6 | |
| 7 | ## Design System Discovery |
| 8 | |
| 9 | Aligning the feature to the design system is **not optional**. Polish without alignment is decoration on top of drift, and it makes the next person's job harder. Discovery comes before any other polish work. |
| 10 | |
| 11 | 1. **Find the design system**: Search for design system documentation, component libraries, style guides, or token definitions. Study the core patterns: design principles, target audience, color tokens, spacing scale, typography styles, component API, motion conventions. |
| 12 | 2. **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? What flow shapes are used for comparable actions (modal vs full-page, inline vs route, save-on-blur vs explicit submit)? |
| 13 | 3. **Identify drift, then name the root cause**: For every deviation, classify it as a **missing token** (the value should exist in the system but doesn't), a **one-off implementation** (a shared component already exists but wasn't used), or a **conceptual misalignment** (the feature's flow, IA, or hierarchy doesn't match neighboring features). The fix differs by category: patch the value, swap to the shared component, or rework the flow. Fixing the symptom without naming the cause is how drift compounds. |
| 14 | |
| 15 | If a design system exists, polish **must** align the feature with it. If none exists, polish against the conventions visible in the codebase. **If anything about the system is ambiguous, ask. Never guess at design system principles.** |
| 16 | |
| 17 | ## Pre-Polish Assessment |
| 18 | |
| 19 | Understand the current state and goals before touching anything: |
| 20 | |
| 21 | 1. **Review completeness**: |
| 22 | - Is it functionally complete? |
| 23 | - Are there known issues to preserve (mark with TODOs)? |
| 24 | - What's the quality bar? (MVP vs flagship feature?) |
| 25 | - When does it ship? (How much time for polish?) |
| 26 | |
| 27 | 2. **Think experience-first**: Who actually uses this, and what's the best possible experience for them? Effective design beats decorative polish; a feature that looks beautiful but fights the user's flow is not polished. Walk the path from their perspective before opening DevTools. |
| 28 | |
| 29 | 3. **Identify polish areas**: |
| 30 | - Visual inconsistencies |
| 31 | - Spacing and alignment issues |
| 32 | - Interaction state gaps |
| 33 | - Copy inconsistencies |
| 34 | - Edge cases and error states |
| 35 | - Loading and transition smoothness |
| 36 | - Information architecture and flow drift (does this feature reveal complexity the way neighboring features do?) |
| 37 | |
| 38 | 4. **Pull in any prior critique** (optional signal): If `$impeccable critique` has been run on the same target, its priority issues are a useful prior for what to address first. Resolve the target to a file path or URL, then: |
| 39 | ```bash |
| 40 | slug=$(node .agents/skills/impeccable/scripts/critique-storage.mjs slug "<resolved>") |
| 41 | node .agents/skills/impeccable/scripts/critique-storage.mjs latest "$slug" |
| 42 | ``` |
| 43 | Exit 0 with body = found; fold the P0/P1 items into your polish list and mention the snapshot path so the user sees what you read. Exit 2 = no snapshot, continue without it. The critique is one input among many. Do your own pass either way. |
| 44 | |
| 45 | 5. **Triage cosmetic vs functional**: Classify each issue as **cosmetic** (looks off, doesn't impede the user) or **functional** (breaks, blocks, or confuses the experience). When polish time is tight, functional issues ship first; cosmetic ones can land in a follow-up. Quality should be consistent; never perfect one corner while leaving another rough. |
| 46 | |
| 47 | **CRITICAL**: Polish is the last step, not the first. Don't polish work that's not functionally complete. |
| 48 | |
| 49 | ## Polish Systematically |
| 50 | |
| 51 | Work through these dimensions methodically: |
| 52 | |
| 53 | ### Visual Alignment & Spacing |
| 54 | |
| 55 | - **Pixel-perfect alignment**: Everything lines up to grid |
| 56 | - **Consistent spacing**: All gaps use spacing scale (no random 13px gaps) |
| 57 | - **Optical alignment**: Adjust for visual weight (icons may need offset for optical centering) |
| 58 | - **Responsive consistency**: Spacing and alignment work at all breakpoints |
| 59 | - **Grid adherence**: Elements snap to baseline grid |
| 60 | |
| 61 | **Check**: |
| 62 | - Enable grid overlay and verify alignment |
| 63 | - Check spacing with browser inspector |
| 64 | - Test at multiple viewport sizes |
| 65 | - Look for elements that "feel" off |
| 66 | |
| 67 | ### Information Architecture & Flow |
| 68 | |
| 69 | Visual polish on a misshapen flow is wasted work. Match the *shape* of the experience to the system, not just the surface. |
| 70 | |
| 71 | - **Progressive disclosure**: Match how much is revealed when, compared to neighboring features. A settings page exposing 40 fields when the rest of the app reveals 5 at a time is drift, even if every field is perfectly styled. |
| 72 | - **Established user flows**: Multi-step actions follow the same shape as comparable flows elsewhere: modal vs full-page, inline edit vs separate route, save-on-blur vs explicit submit, optimistic vs pessimistic updates. |
| 73 | - **Hierarchy & complexity**: The same conceptual weight gets the same visual weight throughout. Primary actions don't become tertiary in one corner of the product, and tertiary actions don't shout. |
| 74 | - **Empty, loading, and arrival transitions**: How content arrives, updates, and leaves matches how it does in adjacent features. |
| 75 | - **Naming and mental model**: The feature uses the same nouns and verbs as the rest of the system. A "Workspace" here shouldn't be a "Project" three screens away. |
| 76 | |
| 77 | ### Typography Refinement |
| 78 | |
| 79 | - **Hierarchy consistency**: Same elements use same sizes/weights throughout |
| 80 | - **Line length**: 45-75 characters for body text |
| 81 | - **Line height**: Appropriate for font size and context |
| 82 | - **Widows & orphans**: No single words on last line |
| 83 | - **Hyphenation**: Appropriate for language and column width |
| 84 | - **Kerning**: Adjust letter spacing where needed (especially headlines) |
| 85 | - **Font loading**: No FOUT/FOIT flashes |
| 86 | |
| 87 | ### Color & Contrast |
| 88 | |
| 89 | - **Contrast ratios**: All text meets WCAG standards |
| 90 | - **Consistent token usage**: No hard-coded colors, all use design tokens |
| 91 | - **Theme consistency**: Works in all theme variants |
| 92 | - **Color meaning**: Same colors mean same things throughout |
| 93 | - **Accessible focus**: Focus indicators visible with sufficient contrast |
| 94 | - **Gray on color**: Never put gray text on colored backgrounds; use a shade of that color or transparency |
| 95 | |
| 96 | ### Interaction States |
| 97 | |
| 98 | Every interactive element needs all states: |
| 99 | |
| 100 | - **Default**: Resting state |
| 101 | - **Hover**: Subtle feedback (color, scale, shadow) |
| 102 | - **Focus**: Keyboard focus indicator (never remove without replacement) |
| 103 | - **Active**: Click/tap feedback |
| 104 | - **Disabled**: Clearly non-interactive |
| 105 | - **Loading**: Async action feedback |
| 106 | - **Error**: Validation or error state |
| 107 | - **Success**: Successful completion |
| 108 | |
| 109 | **Missing states create confusion and broken experiences**. |
| 110 | |
| 111 | ### Micro-interactions & Transitions |
| 112 | |
| 113 | - **Smooth transitions**: All state changes animated appropriately (150-300ms) |
| 114 | - **Consistent easing**: Use ease-out-quart/quint/expo for natural deceleration. Never bounce or elastic; they feel dated. |
| 115 | - **No jank**: Smooth animations; use atmospheric blur/filter/mask/shadow effects when they add polish, but bound expensive paint areas and avoid casual layout-property animation |
| 116 | - **Appropriate motion**: Motion serves purpose, not decoration |
| 117 | - **Reduced motion**: Respects `prefers-reduced-motion` |
| 118 | |
| 119 | ### Content & Copy |
| 120 | |
| 121 | - **Consistent terminology**: Same things called same names throughout |
| 122 | - **Consistent capitalization**: Title Case vs Sentence case applied consistently |
| 123 | - **Grammar & spelling**: No typos |
| 124 | - **Appropriate length**: Not too wordy, not too terse |
| 125 | - **Punctuation consistency**: Periods on sentences, not on labels (unless all labels have them) |
| 126 | |
| 127 | ### Icons & Images |
| 128 | |
| 129 | - **Consistent style**: All icons from same family or matching style |
| 130 | - **Appropriate sizing**: Icons sized consistently for context |
| 131 | - **Proper alignment**: Icons align with adjacent text optically |
| 132 | - **Alt text**: All images have descriptive alt text |
| 133 | - **Loading states**: Images don't cause layout shift, proper aspect ratios |
| 134 | - **Retina support**: 2x assets for high-DPI screens |
| 135 | |
| 136 | ### Forms & Inputs |
| 137 | |
| 138 | - **Label consistency**: All inputs properly labeled |
| 139 | - **Required indicators**: Clear and consistent |
| 140 | - **Error messages**: Helpful and consistent |
| 141 | - **Tab order**: Logical keyboard navigation |
| 142 | - **Auto-focus**: Appropriate (don't overuse) |
| 143 | - **Validation timing**: Consistent (on blur vs on submit) |
| 144 | |
| 145 | ### Edge Cases & Error States |
| 146 | |
| 147 | - **Loading states**: All async actions have loading feedback |
| 148 | - **Empty states**: Helpful empty states, not just blank space |
| 149 | - **Error states**: Clear error messages with recovery paths |
| 150 | - **Success states**: Confirmation of successful actions |
| 151 | - **Long content**: Handles very long names, descriptions, etc. |
| 152 | - **No content**: Handles missing data gracefully |
| 153 | - **Offline**: Appropriate offline handling (if applicable) |
| 154 | |
| 155 | ### Responsiveness |
| 156 | |
| 157 | - **All breakpoints**: Test mobile, tablet, desktop |
| 158 | - **Touch targets**: 44x44px minimum on touch devices |
| 159 | - **Readable text**: No text smaller than 14px on mobile |
| 160 | - **No horizontal scroll**: Content fits viewport |
| 161 | - **Appropriate reflow**: Content adapts logically |
| 162 | |
| 163 | ### Performance |
| 164 | |
| 165 | - **Fast initial load**: Optimize critical path |
| 166 | - **No layout shift**: Elements don't jump after load (CLS) |
| 167 | - **Smooth interactions**: No lag or jank |
| 168 | - **Optimized images**: Appropriate formats and sizes |
| 169 | - **Lazy loading**: Off-screen content loads lazily |
| 170 | |
| 171 | ### Code Quality |
| 172 | |
| 173 | - **Remove console logs**: No debug logging in production |
| 174 | - **Remove commented code**: Clean up dead code |
| 175 | - **Remove unused imports**: Clean up unused dependencies |
| 176 | - **Consistent naming**: Variables and functions follow conventions |
| 177 | - **Type safety**: No TypeScript `any` or ignored errors |
| 178 | - **Accessibility**: Proper ARIA labels and semantic HTML |
| 179 | |
| 180 | ## Polish Checklist |
| 181 | |
| 182 | Go through systematically: |
| 183 | |
| 184 | - [ ] Aligned to the design system (drift named and resolved by root cause) |
| 185 | - [ ] Information architecture and flow shape match neighboring features |
| 186 | - [ ] Visual alignment perfect at all breakpoints |
| 187 | - [ ] Spacing uses design tokens consistently |
| 188 | - [ ] Typography hierarchy consistent |
| 189 | - [ ] All interactive states implemented |
| 190 | - [ ] All transitions smooth (60fps) |
| 191 | - [ ] Copy is consistent and polished |
| 192 | - [ ] Icons are consistent and properly sized |
| 193 | - [ ] All forms properly labeled and validated |
| 194 | - [ ] Error states are helpful |
| 195 | - [ ] Loading states are clear |
| 196 | - [ ] Empty states are welcoming |
| 197 | - [ ] Touch targets are 44x44px minimum |
| 198 | - [ ] Contrast ratios meet WCAG AA |
| 199 | - [ ] Keyboard navigation works |
| 200 | - [ ] Focus indicators visible |
| 201 | - [ ] No console errors or warnings |
| 202 | - [ ] No layout shift on load |
| 203 | - [ ] Works in all supported browsers |
| 204 | - [ ] Respects reduced motion preference |
| 205 | - [ ] Code is clean (no TODOs, console.logs, commented code) |
| 206 | |
| 207 | **IMPORTANT**: Polish is about details. Zoom in. Squint at it. Use it yourself. The little things add up. |
| 208 | |
| 209 | Sweat the details. Zoom in until the alignment is right and the spacing reads as deliberate. Then ship. |
| 210 | |
| 211 | **NEVER**: |
| 212 | - Polish before it's functionally complete |
| 213 | - Polish without aligning to the design system; that's decoration on drift |
| 214 | - Guess at design system principles instead of asking when something is ambiguous |
| 215 | - Spend hours on polish if it ships in 30 minutes (triage) |
| 216 | - Introduce bugs while polishing (test thoroughly) |
| 217 | - Ignore systematic issues (if spacing is off everywhere, fix the system, not just one screen) |
| 218 | - Perfect one thing while leaving others rough (consistent quality level) |
| 219 | - Create new one-off components when design system equivalents exist |
| 220 | - Hard-code values that should use design tokens |
| 221 | - Introduce new patterns or flows that diverge from established ones |
| 222 | |
| 223 | ## Final Verification |
| 224 | |
| 225 | Before marking as done: |
| 226 | |
| 227 | - **Use it yourself**: Actually interact with the feature. |
| 228 | - **Test on real devices**: Not just browser DevTools. |
| 229 | - **Ask someone else to review**: Fresh eyes catch things. |
| 230 | - **Compare to design**: Match intended design. |
| 231 | - **Check all states**: Don't just test happy path. |
| 232 | - **Treat automation carefully**: Run detector or QA commands when they are available and relevant, fix their defects, but never cite a clean result as proof that the work is polished. |
| 233 | |
| 234 | ## Clean Up |
| 235 | |
| 236 | After polishing, ensure code quality: |
| 237 | |
| 238 | - **Replace custom implementations**: If the design system provides a component you reimplemented, switch to the shared version. |
| 239 | - **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish. |
| 240 | - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. |
| 241 | - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. |
| 242 |