1> **Additional context needed**: quality bar (MVP vs flagship).
  2
  3Perform a meticulous final pass to catch all the small details that separate good work from great work. The difference between shipped and polished.
  4
  5Detector 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
  9Aligning 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
 111. **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.
 122. **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)?
 133. **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
 15If 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
 19Understand the current state and goals before touching anything:
 20
 211. **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
 272. **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
 293. **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
 384. **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 .pi/skills/impeccable/scripts/critique-storage.mjs slug "<resolved>")
 41   node .pi/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
 455. **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
 51Work 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
 69Visual 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- **Tinted neutrals**: No pure gray or pure black; add subtle color tint (0.01 chroma)
 95- **Gray on color**: Never put gray text on colored backgrounds; use a shade of that color or transparency
 96
 97### Interaction States
 98
 99Every interactive element needs all states:
100
101- **Default**: Resting state
102- **Hover**: Subtle feedback (color, scale, shadow)
103- **Focus**: Keyboard focus indicator (never remove without replacement)
104- **Active**: Click/tap feedback
105- **Disabled**: Clearly non-interactive
106- **Loading**: Async action feedback
107- **Error**: Validation or error state
108- **Success**: Successful completion
109
110**Missing states create confusion and broken experiences**.
111
112### Micro-interactions & Transitions
113
114- **Smooth transitions**: All state changes animated appropriately (150-300ms)
115- **Consistent easing**: Use ease-out-quart/quint/expo for natural deceleration. Never bounce or elastic; they feel dated.
116- **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
117- **Appropriate motion**: Motion serves purpose, not decoration
118- **Reduced motion**: Respects `prefers-reduced-motion`
119
120### Content & Copy
121
122- **Consistent terminology**: Same things called same names throughout
123- **Consistent capitalization**: Title Case vs Sentence case applied consistently
124- **Grammar & spelling**: No typos
125- **Appropriate length**: Not too wordy, not too terse
126- **Punctuation consistency**: Periods on sentences, not on labels (unless all labels have them)
127
128### Icons & Images
129
130- **Consistent style**: All icons from same family or matching style
131- **Appropriate sizing**: Icons sized consistently for context
132- **Proper alignment**: Icons align with adjacent text optically
133- **Alt text**: All images have descriptive alt text
134- **Loading states**: Images don't cause layout shift, proper aspect ratios
135- **Retina support**: 2x assets for high-DPI screens
136
137### Forms & Inputs
138
139- **Label consistency**: All inputs properly labeled
140- **Required indicators**: Clear and consistent
141- **Error messages**: Helpful and consistent
142- **Tab order**: Logical keyboard navigation
143- **Auto-focus**: Appropriate (don't overuse)
144- **Validation timing**: Consistent (on blur vs on submit)
145
146### Edge Cases & Error States
147
148- **Loading states**: All async actions have loading feedback
149- **Empty states**: Helpful empty states, not just blank space
150- **Error states**: Clear error messages with recovery paths
151- **Success states**: Confirmation of successful actions
152- **Long content**: Handles very long names, descriptions, etc.
153- **No content**: Handles missing data gracefully
154- **Offline**: Appropriate offline handling (if applicable)
155
156### Responsiveness
157
158- **All breakpoints**: Test mobile, tablet, desktop
159- **Touch targets**: 44x44px minimum on touch devices
160- **Readable text**: No text smaller than 14px on mobile
161- **No horizontal scroll**: Content fits viewport
162- **Appropriate reflow**: Content adapts logically
163
164### Performance
165
166- **Fast initial load**: Optimize critical path
167- **No layout shift**: Elements don't jump after load (CLS)
168- **Smooth interactions**: No lag or jank
169- **Optimized images**: Appropriate formats and sizes
170- **Lazy loading**: Off-screen content loads lazily
171
172### Code Quality
173
174- **Remove console logs**: No debug logging in production
175- **Remove commented code**: Clean up dead code
176- **Remove unused imports**: Clean up unused dependencies
177- **Consistent naming**: Variables and functions follow conventions
178- **Type safety**: No TypeScript `any` or ignored errors
179- **Accessibility**: Proper ARIA labels and semantic HTML
180
181## Polish Checklist
182
183Go through systematically:
184
185- [ ] Aligned to the design system (drift named and resolved by root cause)
186- [ ] Information architecture and flow shape match neighboring features
187- [ ] Visual alignment perfect at all breakpoints
188- [ ] Spacing uses design tokens consistently
189- [ ] Typography hierarchy consistent
190- [ ] All interactive states implemented
191- [ ] All transitions smooth (60fps)
192- [ ] Copy is consistent and polished
193- [ ] Icons are consistent and properly sized
194- [ ] All forms properly labeled and validated
195- [ ] Error states are helpful
196- [ ] Loading states are clear
197- [ ] Empty states are welcoming
198- [ ] Touch targets are 44x44px minimum
199- [ ] Contrast ratios meet WCAG AA
200- [ ] Keyboard navigation works
201- [ ] Focus indicators visible
202- [ ] No console errors or warnings
203- [ ] No layout shift on load
204- [ ] Works in all supported browsers
205- [ ] Respects reduced motion preference
206- [ ] Code is clean (no TODOs, console.logs, commented code)
207
208**IMPORTANT**: Polish is about details. Zoom in. Squint at it. Use it yourself. The little things add up.
209
210Sweat the details. Zoom in until the alignment is right and the spacing reads as deliberate. Then ship.
211
212**NEVER**:
213- Polish before it's functionally complete
214- Polish without aligning to the design system; that's decoration on drift
215- Guess at design system principles instead of asking when something is ambiguous
216- Spend hours on polish if it ships in 30 minutes (triage)
217- Introduce bugs while polishing (test thoroughly)
218- Ignore systematic issues (if spacing is off everywhere, fix the system, not just one screen)
219- Perfect one thing while leaving others rough (consistent quality level)
220- Create new one-off components when design system equivalents exist
221- Hard-code values that should use design tokens
222- Introduce new patterns or flows that diverge from established ones
223
224## Final Verification
225
226Before marking as done:
227
228- **Use it yourself**: Actually interact with the feature.
229- **Test on real devices**: Not just browser DevTools.
230- **Ask someone else to review**: Fresh eyes catch things.
231- **Compare to design**: Match intended design.
232- **Check all states**: Don't just test happy path.
233- **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.
234
235## Clean Up
236
237After polishing, ensure code quality:
238
239- **Replace custom implementations**: If the design system provides a component you reimplemented, switch to the shared version.
240- **Remove orphaned code**: Delete unused styles, components, or files made obsolete by polish.
241- **Consolidate tokens**: If you introduced new values, check whether they should be tokens.
242- **Verify DRYness**: Look for duplication introduced during polishing and consolidate.