PaperclipOrg
Claude Agent Skill · by Pbakaus

Polish

This is the final quality pass you run before shipping anything user-facing. It systematically checks visual alignment, spacing consistency, interaction states,

Install
Terminal · npx
$npx skills add https://github.com/pbakaus/impeccable --skill polish
Works with Paperclip

How Polish fits into a Paperclip company.

Polish drops into any Paperclip agent that handles this kind of work. Assign it to a specialist inside a pre-configured PaperclipOrg company and the skill becomes available on every heartbeat — no prompt engineering, no tool wiring.

S
SaaS FactoryPaired

Pre-configured AI company — 18 agents, 18 skills, one-time purchase.

$27$59
Explore pack
Source file
SKILL.md224 lines
Expand
---name: polishdescription: Performs a final quality pass fixing alignment, spacing, consistency, and micro-detail issues before shipping. Use when the user mentions polish, finishing touches, pre-launch review, something looks off, or wants to go from good to great.version: 2.1.1user-invocable: trueargument-hint: "[target]"--- ## MANDATORY PREPARATION Invoke /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 /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: 1. **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.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?3. **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: 1. **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?) 2. **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 ### 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 & 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: - [ ] 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) **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.