+16 -1

.agents/skills/adapt/SKILL.md

reviewed

··· 45 45 ### Mobile Adaptation (Desktop → Mobile) 46 46 47 47 **Layout Strategy**: 48 48 + 48 49 - Single column instead of multi-column 49 50 - Vertical stacking instead of side-by-side 50 51 - Full-width components instead of fixed widths 51 52 - Bottom navigation instead of top/side navigation 52 53 53 54 **Interaction Strategy**: 55 55 + 54 56 - Touch targets 44x44px minimum (not hover-dependent) 55 57 - Swipe gestures where appropriate (lists, carousels) 56 58 - Bottom sheets instead of dropdowns ··· 58 60 - Larger tap areas with more spacing 59 61 60 62 **Content Strategy**: 63 63 + 61 64 - Progressive disclosure (don't show everything at once) 62 65 - Prioritize primary content (secondary content in tabs/accordions) 63 66 - Shorter text (more concise) 64 67 - Larger text (16px minimum) 65 68 66 69 **Navigation Strategy**: 70 70 + 67 71 - Hamburger menu or bottom navigation 68 72 - Reduce navigation complexity 69 73 - Sticky headers for context ··· 72 76 ### Tablet Adaptation (Hybrid Approach) 73 77 74 78 **Layout Strategy**: 79 79 + 75 80 - Two-column layouts (not single or three-column) 76 81 - Side panels for secondary content 77 82 - Master-detail views (list + detail) 78 83 - Adaptive based on orientation (portrait vs landscape) 79 84 80 85 **Interaction Strategy**: 86 86 + 81 87 - Support both touch and pointer 82 88 - Touch targets 44x44px but allow denser layouts than phone 83 89 - Side navigation drawers ··· 86 92 ### Desktop Adaptation (Mobile → Desktop) 87 93 88 94 **Layout Strategy**: 95 95 + 89 96 - Multi-column layouts (use horizontal space) 90 97 - Side navigation always visible 91 98 - Multiple information panels simultaneously 92 99 - Fixed widths with max-width constraints (don't stretch to 4K) 93 100 94 101 **Interaction Strategy**: 102 102 + 95 103 - Hover states for additional information 96 104 - Keyboard shortcuts 97 105 - Right-click context menus ··· 99 107 - Multi-select with Shift/Cmd 100 108 101 109 **Content Strategy**: 110 110 + 102 111 - Show more information upfront (less progressive disclosure) 103 112 - Data tables with many columns 104 113 - Richer visualizations ··· 107 116 ### Print Adaptation (Screen → Print) 108 117 109 118 **Layout Strategy**: 119 119 + 110 120 - Page breaks at logical points 111 121 - Remove navigation, footer, interactive elements 112 122 - Black and white (or limited color) 113 123 - Proper margins for binding 114 124 115 125 **Content Strategy**: 126 126 + 116 127 - Expand shortened content (show full URLs, hidden sections) 117 128 - Add page numbers, headers, footers 118 129 - Include metadata (print date, page title) ··· 121 132 ### Email Adaptation (Web → Email) 122 133 123 134 **Layout Strategy**: 135 135 + 124 136 - Narrow width (600px max) 125 137 - Single column only 126 138 - Inline CSS (no external stylesheets) 127 139 - Table-based layouts (for email client compatibility) 128 140 129 141 **Interaction Strategy**: 142 142 + 130 143 - Large, obvious CTAs (buttons not text links) 131 144 - No hover states (not reliable) 132 145 - Deep links to web app for complex interactions ··· 138 151 ### Responsive Breakpoints 139 152 140 153 Choose appropriate breakpoints: 154 154 + 141 155 - Mobile: 320px-767px 142 156 - Tablet: 768px-1023px 143 157 - Desktop: 1024px+ ··· 176 190 **IMPORTANT**: Test on real devices, not just browser DevTools. Device emulation is helpful but not perfect. 177 191 178 192 **NEVER**: 193 193 + 179 194 - Hide core functionality on mobile (if it matters, make it work) 180 195 - Assume desktop = powerful device (consider accessibility, older machines) 181 196 - Use different information architecture across contexts (confusing) ··· 196 211 - **Edge cases**: Very small screens (320px), very large screens (4K) 197 212 - **Slow connections**: Test on throttled network 198 213 199 199 - Remember: You're a cross-platform design expert. Make experiences that feel native to each context while maintaining brand and functionality consistency. Adapt intentionally, test thoroughly. 214 214 + Remember: You're a cross-platform design expert. Make experiences that feel native to each context while maintaining brand and functionality consistency. Adapt intentionally, test thoroughly.

+17 -4

.agents/skills/animate/SKILL.md

reviewed

··· 51 51 Add motion systematically across these categories: 52 52 53 53 ### Entrance Animations 54 54 + 54 55 - **Page load choreography**: Stagger element reveals (100-150ms delays), fade + slide combinations 55 56 - **Hero section**: Dramatic entrance for primary content (scale, parallax, or creative effects) 56 57 - **Content reveals**: Scroll-triggered animations using intersection observer 57 58 - **Modal/drawer entry**: Smooth slide + fade, backdrop fade, focus management 58 59 59 60 ### Micro-interactions 61 61 + 60 62 - **Button feedback**: 61 63 - Hover: Subtle scale (1.02-1.05), color shift, shadow increase 62 64 - Click: Quick scale down then up (0.95 → 1), ripple effect ··· 69 71 - **Like/favorite**: Scale + rotation, particle effects, color transition 70 72 71 73 ### State Transitions 74 74 + 72 75 - **Show/hide**: Fade + slide (not instant), appropriate timing (200-300ms) 73 76 - **Expand/collapse**: Height transition with overflow handling, icon rotation 74 77 - **Loading states**: Skeleton screen fades, spinner animations, progress bars ··· 76 79 - **Enable/disable**: Opacity transitions, cursor changes 77 80 78 81 ### Navigation & Flow 82 82 + 79 83 - **Page transitions**: Crossfade between routes, shared element transitions 80 84 - **Tab switching**: Slide indicator, content fade/slide 81 85 - **Carousel/slider**: Smooth transforms, snap points, momentum 82 86 - **Scroll effects**: Parallax layers, sticky headers with state changes, scroll progress indicators 83 87 84 88 ### Feedback & Guidance 89 89 + 85 90 - **Hover hints**: Tooltip fade-ins, cursor changes, element highlights 86 91 - **Drag & drop**: Lift effect (shadow + scale), drop zone highlights, smooth repositioning 87 92 - **Copy/paste**: Brief highlight flash on paste, "copied" confirmation 88 93 - **Focus flow**: Highlight path through form or workflow 89 94 90 95 ### Delight Moments 96 96 + 91 97 - **Empty states**: Subtle floating animations on illustrations 92 98 - **Completed actions**: Confetti, check mark flourish, success celebrations 93 99 - **Easter eggs**: Hidden interactions for discovery ··· 100 106 ### Timing & Easing 101 107 102 108 **Durations by purpose:** 109 109 + 103 110 - **100-150ms**: Instant feedback (button press, toggle) 104 111 - **200-300ms**: State changes (hover, menu open) 105 112 - **300-500ms**: Layout changes (accordion, modal) 106 113 - **500-800ms**: Entrance animations (page load) 107 114 108 115 **Easing curves (use these, not CSS defaults):** 116 116 + 109 117 ```css 110 118 /* Recommended - natural deceleration */ 111 111 - --ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1); /* Smooth, refined */ 112 112 - --ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1); /* Slightly snappier */ 113 113 - --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1); /* Confident, decisive */ 119 119 + --ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1); /* Smooth, refined */ 120 120 + --ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1); /* Slightly snappier */ 121 121 + --ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1); /* Confident, decisive */ 114 122 115 123 /* AVOID - feel dated and tacky */ 116 124 /* bounce: cubic-bezier(0.34, 1.56, 0.64, 1); */ ··· 120 128 **Exit animations are faster than entrances.** Use ~75% of enter duration. 121 129 122 130 ### CSS Animations 131 131 + 123 132 ```css 124 133 /* Prefer for simple, declarative animations */ 125 134 - transitions for state changes ··· 128 137 ``` 129 138 130 139 ### JavaScript Animation 140 140 + 131 141 ```javascript 132 142 /* Use for complex, interactive animations */ 133 143 - Web Animations API for programmatic control ··· 136 146 ``` 137 147 138 148 ### Performance 149 149 + 139 150 - **GPU acceleration**: Use `transform` and `opacity`, avoid layout properties 140 151 - **will-change**: Add sparingly for known expensive animations 141 152 - **Reduce paint**: Minimize repaints, use `contain` where appropriate 142 153 - **Monitor FPS**: Ensure 60fps on target devices 143 154 144 155 ### Accessibility 156 156 + 145 157 ```css 146 158 @media (prefers-reduced-motion: reduce) { 147 159 * { ··· 153 165 ``` 154 166 155 167 **NEVER**: 168 168 + 156 169 - Use bounce or elastic easing curves—they feel dated and draw attention to the animation itself 157 170 - Animate layout properties (width, height, top, left)—use transform instead 158 171 - Use durations over 500ms for feedback—it feels laggy ··· 172 185 - **Doesn't block**: Users can interact during/after animations 173 186 - **Adds value**: Makes interface clearer or more delightful 174 187 175 175 - Remember: Motion should enhance understanding and provide feedback, not just add decoration. Animate with purpose, respect performance constraints, and always consider accessibility. Great animation is invisible - it just makes everything feel right. 188 188 + Remember: Motion should enhance understanding and provide feedback, not just add decoration. Animate with purpose, respect performance constraints, and always consider accessibility. Great animation is invisible - it just makes everything feel right.

+19 -9

.agents/skills/audit/SKILL.md

reviewed

··· 23 23 ### 1. Accessibility (A11y) 24 24 25 25 **Check for**: 26 26 + 26 27 - **Contrast issues**: Text contrast ratios < 4.5:1 (or 7:1 for AAA) 27 28 - **Missing ARIA**: Interactive elements without proper roles, labels, or states 28 29 - **Keyboard navigation**: Missing focus indicators, illogical tab order, keyboard traps ··· 35 36 ### 2. Performance 36 37 37 38 **Check for**: 39 39 + 38 40 - **Layout thrashing**: Reading/writing layout properties in loops 39 41 - **Expensive animations**: Animating layout properties (width, height, top, left) instead of transform/opacity 40 42 - **Missing optimization**: Images without lazy loading, unoptimized assets, missing will-change ··· 46 48 ### 3. Theming 47 49 48 50 **Check for**: 51 51 + 49 52 - **Hard-coded colors**: Colors not using design tokens 50 53 - **Broken dark mode**: Missing dark mode variants, poor contrast in dark theme 51 54 - **Inconsistent tokens**: Using wrong tokens, mixing token types ··· 56 59 ### 4. Responsive Design 57 60 58 61 **Check for**: 62 62 + 59 63 - **Fixed widths**: Hard-coded widths that break on mobile 60 64 - **Touch targets**: Interactive elements < 44x44px 61 65 - **Horizontal scroll**: Content overflow on narrow viewports ··· 74 78 75 79 ### Audit Health Score 76 80 77 77 - | # | Dimension | Score | Key Finding | 78 78 - |---|-----------|-------|-------------| 79 79 - | 1 | Accessibility | ? | [most critical a11y issue or "--"] | 80 80 - | 2 | Performance | ? | | 81 81 - | 3 | Responsive Design | ? | | 82 82 - | 4 | Theming | ? | | 83 83 - | 5 | Anti-Patterns | ? | | 84 84 - | **Total** | | **??/20** | **[Rating band]** | 81 81 + | # | Dimension | Score | Key Finding | 82 82 + | --------- | ----------------- | --------- | ---------------------------------- | 83 83 + | 1 | Accessibility | ? | [most critical a11y issue or "--"] | 84 84 + | 2 | Performance | ? | | 85 85 + | 3 | Responsive Design | ? | | 86 86 + | 4 | Theming | ? | | 87 87 + | 5 | Anti-Patterns | ? | | 88 88 + | **Total** | | **??/20** | **[Rating band]** | 85 89 86 90 **Rating bands**: 18-20 Excellent (minor polish), 14-17 Good (address weak dimensions), 10-13 Acceptable (significant work needed), 6-9 Poor (major overhaul), 0-5 Critical (fundamental issues) 87 91 88 92 ### Anti-Patterns Verdict 93 93 + 89 94 **Start here.** Pass/fail: Does this look AI-generated? List specific tells. Be brutally honest. 90 95 91 96 ### Executive Summary 97 97 + 92 98 - Audit Health Score: **??/20** ([rating band]) 93 99 - Total issues found (count by severity: P0/P1/P2/P3) 94 100 - Top 3-5 critical issues ··· 97 103 ### Detailed Findings by Severity 98 104 99 105 Tag every issue with **P0-P3 severity**: 106 106 + 100 107 - **P0 Blocking**: Prevents task completion — fix immediately 101 108 - **P1 Major**: Significant difficulty or WCAG AA violation — fix before release 102 109 - **P2 Minor**: Annoyance, workaround exists — fix in next pass 103 110 - **P3 Polish**: Nice-to-fix, no real user impact — fix if time permits 104 111 105 112 For each issue, document: 113 113 + 106 114 - **[P?] Issue name** 107 115 - **Location**: Component, file, line 108 116 - **Category**: Accessibility / Performance / Theming / Responsive / Anti-Pattern ··· 114 122 ### Patterns & Systemic Issues 115 123 116 124 Identify recurring problems that indicate systemic gaps rather than one-off mistakes: 125 125 + 117 126 - "Hard-coded colors appear in 15+ components, should use design tokens" 118 127 - "Touch targets consistently too small (<44px) throughout mobile experience" 119 128 ··· 139 148 **IMPORTANT**: Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters. 140 149 141 150 **NEVER**: 151 151 + 142 152 - Report issues without explaining impact (why does this matter?) 143 153 - Provide generic recommendations (be specific and actionable) 144 154 - Skip positive findings (celebrate what works) 145 155 - Forget to prioritize (everything can't be P0) 146 156 - Report false positives without verification 147 157 148 148 - Remember: You're a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement. 158 158 + Remember: You're a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement.

+8 -1

.agents/skills/bolder/SKILL.md

reviewed

··· 54 54 Systematically increase impact across these dimensions: 55 55 56 56 ### Typography Amplification 57 57 + 57 58 - **Replace generic fonts**: Swap system fonts for distinctive choices (see impeccable skill for inspiration) 58 59 - **Extreme scale**: Create dramatic size jumps (3x-5x differences, not 1.5x) 59 60 - **Weight contrast**: Pair 900 weights with 200 weights, not 600 with 400 60 61 - **Unexpected choices**: Variable fonts, display fonts for headlines, condensed/extended widths, monospace as intentional accent (not as lazy "dev tool" default) 61 62 62 63 ### Color Intensification 64 64 + 63 65 - **Increase saturation**: Shift to more vibrant, energetic colors (but not neon) 64 66 - **Bold palette**: Introduce unexpected color combinations—avoid the purple-blue gradient AI slop 65 67 - **Dominant color strategy**: Let one bold color own 60% of the design ··· 68 70 - **Rich gradients**: Intentional multi-stop gradients (not generic purple-to-blue) 69 71 70 72 ### Spatial Drama 73 73 + 71 74 - **Extreme scale jumps**: Make important elements 3-5x larger than surroundings 72 75 - **Break the grid**: Let hero elements escape containers and cross boundaries 73 76 - **Asymmetric layouts**: Replace centered, balanced layouts with tension-filled asymmetry ··· 75 78 - **Overlap**: Layer elements intentionally for depth 76 79 77 80 ### Visual Effects 81 81 + 78 82 - **Dramatic shadows**: Large, soft shadows for elevation (but not generic drop shadows on rounded rectangles) 79 83 - **Background treatments**: Mesh patterns, noise textures, geometric patterns, intentional gradients (not purple-to-blue) 80 84 - **Texture & depth**: Grain, halftone, duotone, layered elements—NOT glassmorphism (it's overused AI slop) ··· 82 86 - **Custom elements**: Illustrative elements, custom icons, decorative details that reinforce brand 83 87 84 88 ### Motion & Animation 89 89 + 85 90 - **Entrance choreography**: Staggered, dramatic page load animations with 50-100ms delays 86 91 - **Scroll effects**: Parallax, reveal animations, scroll-triggered sequences 87 92 - **Micro-interactions**: Satisfying hover effects, click feedback, state changes 88 93 - **Transitions**: Smooth, noticeable transitions using ease-out-quart/quint/expo (not bounce or elastic—they cheapen the effect) 89 94 90 95 ### Composition Boldness 96 96 + 91 97 - **Hero moments**: Create clear focal points with dramatic treatment 92 98 - **Diagonal flows**: Escape horizontal/vertical rigidity with diagonal arrangements 93 99 - **Full-bleed elements**: Use full viewport width/height for impact 94 100 - **Unexpected proportions**: Golden ratio? Throw it out. Try 70/30, 80/20 splits 95 101 96 102 **NEVER**: 103 103 + 97 104 - Add effects randomly without purpose (chaos ≠ bold) 98 105 - Sacrifice readability for aesthetics (body text must be readable) 99 106 - Make everything bold (then nothing is bold - need contrast) ··· 114 121 115 122 **The test**: If you showed this to someone and said "AI made this bolder," would they believe you immediately? If yes, you've failed. Bold means distinctive, not "more AI effects." 116 123 117 117 - Remember: Bold design is confident design. It takes risks, makes statements, and creates memorable experiences. But bold without strategy is just loud. Be intentional, be dramatic, be unforgettable. 124 124 + Remember: Bold design is confident design. It takes risks, makes statements, and creates memorable experiences. But bold without strategy is just loud. Be intentional, be dramatic, be unforgettable.

+20 -1

.agents/skills/clarify/SKILL.md

reviewed

··· 51 51 Refine text across these common areas: 52 52 53 53 ### Error Messages 54 54 + 54 55 **Bad**: "Error 403: Forbidden" 55 56 **Good**: "You don't have permission to view this page. Contact your admin for access." 56 57 ··· 58 59 **Good**: "Email addresses need an @ symbol. Try: name@example.com" 59 60 60 61 **Principles**: 62 62 + 61 63 - Explain what went wrong in plain language 62 64 - Suggest how to fix it 63 65 - Don't blame the user ··· 65 67 - Link to help/support if applicable 66 68 67 69 ### Form Labels & Instructions 70 70 + 68 71 **Bad**: "DOB (MM/DD/YYYY)" 69 72 **Good**: "Date of birth" (with placeholder showing format) 70 73 ··· 72 75 **Good**: "Your email address" or "Company name" 73 76 74 77 **Principles**: 78 78 + 75 79 - Use clear, specific labels (not generic placeholders) 76 80 - Show format expectations with examples 77 81 - Explain why you're asking (when not obvious) ··· 79 83 - Keep required field indicators clear 80 84 81 85 ### Button & CTA Text 86 86 + 82 87 **Bad**: "Click here" | "Submit" | "OK" 83 88 **Good**: "Create account" | "Save changes" | "Got it, thanks" 84 89 85 90 **Principles**: 91 91 + 86 92 - Describe the action specifically 87 93 - Use active voice (verb + noun) 88 94 - Match user's mental model 89 95 - Be specific ("Save" is better than "OK") 90 96 91 97 ### Help Text & Tooltips 98 98 + 92 99 **Bad**: "This is the username field" 93 100 **Good**: "Choose a username. You can change this later in Settings." 94 101 95 102 **Principles**: 103 103 + 96 104 - Add value (don't just repeat the label) 97 105 - Answer the implicit question ("What is this?" or "Why do you need this?") 98 106 - Keep it brief but complete 99 107 - Link to detailed docs if needed 100 108 101 109 ### Empty States 110 110 + 102 111 **Bad**: "No items" 103 112 **Good**: "No projects yet. Create your first project to get started." 104 113 105 114 **Principles**: 115 115 + 106 116 - Explain why it's empty (if not obvious) 107 117 - Show next action clearly 108 118 - Make it welcoming, not dead-end 109 119 110 120 ### Success Messages 121 121 + 111 122 **Bad**: "Success" 112 123 **Good**: "Settings saved! Your changes will take effect immediately." 113 124 114 125 **Principles**: 126 126 + 115 127 - Confirm what happened 116 128 - Explain what happens next (if relevant) 117 129 - Be brief but complete 118 130 - Match the user's emotional moment (celebrate big wins) 119 131 120 132 ### Loading States 133 133 + 121 134 **Bad**: "Loading..." (for 30+ seconds) 122 135 **Good**: "Analyzing your data... this usually takes 30-60 seconds" 123 136 124 137 **Principles**: 138 138 + 125 139 - Set expectations (how long?) 126 140 - Explain what's happening (when it's not obvious) 127 141 - Show progress when possible 128 142 - Offer escape hatch if appropriate ("Cancel") 129 143 130 144 ### Confirmation Dialogs 145 145 + 131 146 **Bad**: "Are you sure?" 132 147 **Good**: "Delete 'Project Alpha'? This can't be undone." 133 148 134 149 **Principles**: 150 150 + 135 151 - State the specific action 136 152 - Explain consequences (especially for destructive actions) 137 153 - Use clear button labels ("Delete project" not "Yes") 138 154 - Don't overuse confirmations (only for risky actions) 139 155 140 156 ### Navigation & Wayfinding 157 157 + 141 158 **Bad**: Generic labels like "Items" | "Things" | "Stuff" 142 159 **Good**: Specific labels like "Your projects" | "Team members" | "Settings" 143 160 144 161 **Principles**: 162 162 + 145 163 - Be specific and descriptive 146 164 - Use language users understand (not internal jargon) 147 165 - Make hierarchy clear ··· 159 177 6. **Be consistent**: Use same terms throughout (don't vary for variety) 160 178 161 179 **NEVER**: 180 180 + 162 181 - Use jargon without explanation 163 182 - Blame users ("You made an error" → "This field is required") 164 183 - Be vague ("Something went wrong" without explanation) ··· 180 199 - **Consistency**: Does it match terminology elsewhere? 181 200 - **Tone**: Is it appropriate for the situation? 182 201 183 183 - Remember: You're a clarity expert with excellent communication skills. Write like you're explaining to a smart friend who's unfamiliar with the product. Be clear, be helpful, be human. 202 202 + Remember: You're a clarity expert with excellent communication skills. Write like you're explaining to a smart friend who's unfamiliar with the product. Be clear, be helpful, be human.

+13 -2

.agents/skills/colorize/SKILL.md

reviewed

··· 52 52 Add color systematically across these dimensions: 53 53 54 54 ### Semantic Color 55 55 + 55 56 - **State indicators**: 56 57 - Success: Green tones (emerald, forest, mint) 57 58 - Error: Red/pink tones (rose, crimson, coral) ··· 63 64 - **Progress indicators**: Colored bars, rings, or charts showing completion or health 64 65 65 66 ### Accent Color Application 67 67 + 66 68 - **Primary actions**: Color the most important buttons/CTAs 67 69 - **Links**: Add color to clickable text (maintain accessibility) 68 70 - **Icons**: Colorize key icons for recognition and personality ··· 70 72 - **Hover states**: Introduce color on interaction 71 73 72 74 ### Background & Surfaces 75 75 + 73 76 - **Tinted backgrounds**: Replace pure gray (`#f5f5f5`) with warm neutrals (`oklch(97% 0.01 60)`) or cool tints (`oklch(97% 0.01 250)`) 74 77 - **Colored sections**: Use subtle background colors to separate areas 75 78 - **Gradient backgrounds**: Add depth with subtle, intentional gradients (not generic purple-blue) 76 79 - **Cards & surfaces**: Tint cards or surfaces slightly for warmth 77 80 78 78 - **Use OKLCH for color**: It's perceptually uniform, meaning equal steps in lightness *look* equal. Great for generating harmonious scales. 81 81 + **Use OKLCH for color**: It's perceptually uniform, meaning equal steps in lightness _look_ equal. Great for generating harmonious scales. 79 82 80 83 ### Data Visualization 84 84 + 81 85 - **Charts & graphs**: Use color to encode categories or values 82 86 - **Heatmaps**: Color intensity shows density or importance 83 87 - **Comparison**: Color coding for different datasets or timeframes 84 88 85 89 ### Borders & Accents 90 90 + 86 91 - **Accent borders**: Add colored left/top borders to cards or sections 87 92 - **Underlines**: Color underlines for emphasis or active states 88 93 - **Dividers**: Subtle colored dividers instead of gray lines 89 94 - **Focus rings**: Colored focus indicators matching brand 90 95 91 96 ### Typography Color 97 97 + 92 98 - **Colored headings**: Use brand colors for section headings (maintain contrast) 93 99 - **Highlight text**: Color for emphasis or categories 94 100 - **Labels & tags**: Small colored labels for metadata or categories 95 101 96 102 ### Decorative Elements 103 103 + 97 104 - **Illustrations**: Add colored illustrations or icons 98 105 - **Shapes**: Geometric shapes in brand colors as background elements 99 106 - **Gradients**: Colorful gradient overlays or mesh backgrounds ··· 104 111 Ensure color addition improves rather than overwhelms: 105 112 106 113 ### Maintain Hierarchy 114 114 + 107 115 - **Dominant color** (60%): Primary brand color or most used accent 108 116 - **Secondary color** (30%): Supporting color for variety 109 117 - **Accent color** (10%): High contrast for key moments 110 118 - **Neutrals** (remaining): Gray/black/white for structure 111 119 112 120 ### Accessibility 121 121 + 113 122 - **Contrast ratios**: Ensure WCAG compliance (4.5:1 for text, 3:1 for UI components) 114 123 - **Don't rely on color alone**: Use icons, labels, or patterns alongside color 115 124 - **Test for color blindness**: Verify red/green combinations work for all users 116 125 117 126 ### Cohesion 127 127 + 118 128 - **Consistent palette**: Use colors from defined palette, not arbitrary choices 119 129 - **Systematic application**: Same color meanings throughout (green always = success) 120 130 - **Temperature consistency**: Warm palette stays warm, cool stays cool 121 131 122 132 **NEVER**: 133 133 + 123 134 - Use every color in the rainbow (choose 2-4 colors beyond neutrals) 124 135 - Apply color randomly without semantic meaning 125 136 - Put gray text on colored backgrounds—it looks washed out; use a darker shade of the background color or transparency instead ··· 140 151 - **Still accessible**: Do all color combinations meet WCAG standards? 141 152 - **Not overwhelming**: Is color balanced and purposeful? 142 153 143 143 - Remember: Color is emotional and powerful. Use it to create warmth, guide attention, communicate meaning, and express personality. But restraint and strategy matter more than saturation and variety. Be colorful, but be intentional. 154 154 + Remember: Color is emotional and powerful. Use it to create warmth, guide attention, communicate meaning, and express personality. But restraint and strategy matter more than saturation and variety. Be colorful, but be intentional.

+39 -20

.agents/skills/critique/SKILL.md

reviewed

··· 25 25 #### Assessment A: LLM Design Review 26 26 27 27 Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this; do not reuse existing tabs. After navigation, label the tab by setting the document title: 28 28 + 28 29 ```javascript 29 29 - document.title = '[LLM] ' + document.title; 30 30 + document.title = "[LLM] " + document.title; 30 31 ``` 32 32 + 31 33 Think like a design director. Evaluate: 32 34 33 35 **AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines in the impeccable skill. Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately? ··· 35 37 **Holistic Design Review**: visual hierarchy (eye flow, primary action clarity), information architecture (structure, grouping, cognitive load), emotional resonance (does it match brand and audience?), discoverability (are interactive elements obvious?), composition (balance, whitespace, rhythm), typography (hierarchy, readability, font choices), color (purposeful use, cohesion, accessibility), states & edge cases (empty, loading, error, success), microcopy (clarity, tone, helpfulness). 36 38 37 39 **Cognitive Load** (consult [cognitive-load](reference/cognitive-load.md)): 40 40 + 38 41 - Run the 8-item cognitive load checklist. Report failure count: 0-1 = low (good), 2-3 = moderate, 4+ = critical. 39 42 - Count visible options at each decision point. If >4, flag it. 40 43 - Check for progressive disclosure: is complexity revealed only when needed? 41 44 42 45 **Emotional Journey**: 46 46 + 43 47 - What emotion does this interface evoke? Is that intentional? 44 48 - **Peak-end rule**: Is the most intense moment positive? Does the experience end well? 45 49 - **Emotional valleys**: Check for anxiety spikes at high-stakes moments (payment, delete, commit). Are there design interventions (progress indicators, reassurance copy, undo options)? ··· 54 58 Run the bundled deterministic detector, which flags 25 specific patterns (AI slop tells + general design quality). 55 59 56 60 **CLI scan**: 61 61 + 57 62 ```bash 58 63 npx impeccable --json [--fast] [target] 59 64 ``` ··· 76 81 2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL). Do not reuse existing tabs. 77 82 3. **Label the tab** via `javascript_tool` so the user can distinguish it: 78 83 ```javascript 79 79 - document.title = '[Human] ' + document.title; 84 84 + document.title = "[Human] " + document.title; 80 85 ``` 81 86 4. **Scroll to top** to ensure the page is scrolled to the very top before injection 82 87 5. **Inject** via `javascript_tool` (replace PORT with the port from step 1): 83 88 ```javascript 84 84 - const s = document.createElement('script'); s.src = 'http://localhost:PORT/detect.js'; document.head.appendChild(s); 89 89 + const s = document.createElement("script"); 90 90 + s.src = "http://localhost:PORT/detect.js"; 91 91 + document.head.appendChild(s); 85 92 ``` 86 93 6. Wait 2-3 seconds for the detector to render overlays 87 94 7. **Read results from console** using `read_console_messages` with pattern `impeccable`. The detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays. ··· 101 108 Structure your feedback as a design director would: 102 109 103 110 #### Design Health Score 104 104 - > *Consult [heuristics-scoring](reference/heuristics-scoring.md)* 111 111 + 112 112 + > _Consult [heuristics-scoring](reference/heuristics-scoring.md)_ 105 113 106 114 Present the Nielsen's 10 heuristics scores as a table: 107 115 108 108 - | # | Heuristic | Score | Key Issue | 109 109 - |---|-----------|-------|-----------| 110 110 - | 1 | Visibility of System Status | ? | [specific finding or "n/a" if solid] | 111 111 - | 2 | Match System / Real World | ? | | 112 112 - | 3 | User Control and Freedom | ? | | 113 113 - | 4 | Consistency and Standards | ? | | 114 114 - | 5 | Error Prevention | ? | | 115 115 - | 6 | Recognition Rather Than Recall | ? | | 116 116 - | 7 | Flexibility and Efficiency | ? | | 117 117 - | 8 | Aesthetic and Minimalist Design | ? | | 118 118 - | 9 | Error Recovery | ? | | 119 119 - | 10 | Help and Documentation | ? | | 120 120 - | **Total** | | **??/40** | **[Rating band]** | 116 116 + | # | Heuristic | Score | Key Issue | 117 117 + | --------- | ------------------------------- | --------- | ------------------------------------ | 118 118 + | 1 | Visibility of System Status | ? | [specific finding or "n/a" if solid] | 119 119 + | 2 | Match System / Real World | ? | | 120 120 + | 3 | User Control and Freedom | ? | | 121 121 + | 4 | Consistency and Standards | ? | | 122 122 + | 5 | Error Prevention | ? | | 123 123 + | 6 | Recognition Rather Than Recall | ? | | 124 124 + | 7 | Flexibility and Efficiency | ? | | 125 125 + | 8 | Aesthetic and Minimalist Design | ? | | 126 126 + | 9 | Error Recovery | ? | | 127 127 + | 10 | Help and Documentation | ? | | 128 128 + | **Total** | | **??/40** | **[Rating band]** | 121 129 122 130 Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32. 123 131 ··· 132 140 **Visual overlays** (if browser was used): Tell the user that overlays are now visible in the **[Human]** tab in their browser, highlighting the detected issues. Summarize what the console output reported. 133 141 134 142 #### Overall Impression 143 143 + 135 144 A brief gut reaction: what works, what doesn't, and the single biggest opportunity. 136 145 137 146 #### What's Working 147 147 + 138 148 Highlight 2-3 things done well. Be specific about why they work. 139 149 140 150 #### Priority Issues 151 151 + 141 152 The 3-5 most impactful design problems, ordered by importance. 142 153 143 154 For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](reference/heuristics-scoring.md) for severity definitions): 155 155 + 144 156 - **[P?] What**: Name the problem clearly 145 157 - **Why it matters**: How this hurts users or undermines goals 146 158 - **Fix**: What to do about it (be concrete) 147 159 - **Suggested command**: Which command could address this (from: /polish, /typeset, /colorize, /quieter, /critique, /overdrive, /clarify, /bolder, /audit, /distill, /harden, /layout, /shape, /animate, /optimize, /adapt, /delight) 148 160 149 161 #### Persona Red Flags 150 150 - > *Consult [personas](reference/personas.md)* 162 162 + 163 163 + > _Consult [personas](reference/personas.md)_ 151 164 152 165 Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If `.github/copilot-instructions.md` contains a `## Design Context` section from `impeccable teach`, also generate 1-2 project-specific personas from the audience/brand info. 153 166 ··· 160 173 Be specific. Name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them. 161 174 162 175 #### Minor Observations 176 176 + 163 177 Quick notes on smaller issues worth addressing. 164 178 165 179 #### Questions to Consider 180 180 + 166 181 Provocative questions that might unlock better solutions: 182 182 + 167 183 - "What if the primary action were more prominent?" 168 184 - "Does this need to feel this complex?" 169 185 - "What would a confident version of this look like?" 170 186 171 187 **Remember**: 188 188 + 172 189 - Be direct. Vague feedback wastes everyone's time. 173 190 - Be specific. "The submit button," not "some elements." 174 191 - Say what's wrong AND why it matters to users. ··· 191 208 4. **Constraints** (optional; only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done. 192 209 193 210 **Rules for questions**: 211 211 + 194 212 - Every question must reference specific findings from the report. Never ask generic "who is your audience?" questions. 195 213 - Keep it to 2-4 questions maximum. Respect the user's time. 196 214 - Offer concrete options, not open-ended prompts. ··· 206 224 207 225 1. **`/command-name`**: Brief description of what to fix (specific context from critique findings) 208 226 2. **`/command-name`**: Brief description (specific context) 209 209 - ... 227 227 + ... 210 228 211 229 **Rules for recommendations**: 230 230 + 212 231 - Only recommend commands from: /polish, /typeset, /colorize, /quieter, /critique, /overdrive, /clarify, /bolder, /audit, /distill, /harden, /layout, /shape, /animate, /optimize, /adapt, /delight 213 232 - Order by the user's stated priorities first, then by impact 214 233 - Each item's description should carry enough context that the command knows what to focus on ··· 222 241 223 242 > You can ask me to run these one at a time, all at once, or in any order you prefer. 224 243 > 225 225 - > Re-run `/critique` after fixes to see your score improve. 244 244 + > Re-run `/critique` after fixes to see your score improve.

+17 -1

.agents/skills/critique/reference/cognitive-load.md

reviewed

··· 7 7 ## Three Types of Cognitive Load 8 8 9 9 ### Intrinsic Load — The Task Itself 10 10 + 10 11 Complexity inherent to what the user is trying to do. You can't eliminate this, but you can structure it. 11 12 12 13 **Manage it by**: 14 14 + 13 15 - Breaking complex tasks into discrete steps 14 16 - Providing scaffolding (templates, defaults, examples) 15 17 - Progressive disclosure — show what's needed now, hide the rest 16 18 - Grouping related decisions together 17 19 18 20 ### Extraneous Load — Bad Design 21 21 + 19 22 Mental effort caused by poor design choices. **Eliminate this ruthlessly** — it's pure waste. 20 23 21 24 **Common sources**: 25 25 + 22 26 - Confusing navigation that requires mental mapping 23 27 - Unclear labels that force users to guess meaning 24 28 - Visual clutter competing for attention ··· 26 30 - Unnecessary steps between user intent and result 27 31 28 32 ### Germane Load — Learning Effort 29 29 - Mental effort spent building understanding. This is *good* cognitive load — it leads to mastery. 33 33 + 34 34 + Mental effort spent building understanding. This is _good_ cognitive load — it leads to mastery. 30 35 31 36 **Support it by**: 37 37 + 32 38 - Progressive disclosure that reveals complexity gradually 33 39 - Consistent patterns that reward learning 34 40 - Feedback that confirms correct understanding ··· 58 64 **Humans can hold ≤4 items in working memory at once** (Miller's Law revised by Cowan, 2001). 59 65 60 66 At any decision point, count the number of distinct options, actions, or pieces of information a user must simultaneously consider: 67 67 + 61 68 - **≤4 items**: Within working memory limits — manageable 62 69 - **5–7 items**: Pushing the boundary — consider grouping or progressive disclosure 63 70 - **8+ items**: Overloaded — users will skip, misclick, or abandon 64 71 65 72 **Practical applications**: 73 73 + 66 74 - Navigation menus: ≤5 top-level items (group the rest under clear categories) 67 75 - Form sections: ≤4 fields visible per group before a visual break 68 76 - Action buttons: 1 primary, 1–2 secondary, group the rest in a menu ··· 74 82 ## Common Cognitive Load Violations 75 83 76 84 ### 1. The Wall of Options 85 85 + 77 86 **Problem**: Presenting 10+ choices at once with no hierarchy. 78 87 **Fix**: Group into categories, highlight recommended, use progressive disclosure. 79 88 80 89 ### 2. The Memory Bridge 90 90 + 81 91 **Problem**: User must remember info from step 1 to complete step 3. 82 92 **Fix**: Keep relevant context visible, or repeat it where it's needed. 83 93 84 94 ### 3. The Hidden Navigation 95 95 + 85 96 **Problem**: User must build a mental map of where things are. 86 97 **Fix**: Always show current location (breadcrumbs, active states, progress indicators). 87 98 88 99 ### 4. The Jargon Barrier 100 100 + 89 101 **Problem**: Technical or domain language forces translation effort. 90 102 **Fix**: Use plain language. If domain terms are unavoidable, define them inline. 91 103 92 104 ### 5. The Visual Noise Floor 105 105 + 93 106 **Problem**: Every element has the same visual weight — nothing stands out. 94 107 **Fix**: Establish clear hierarchy: one primary element, 2–3 secondary, everything else muted. 95 108 96 109 ### 6. The Inconsistent Pattern 110 110 + 97 111 **Problem**: Similar actions work differently in different places. 98 112 **Fix**: Standardize interaction patterns. Same type of action = same type of UI. 99 113 100 114 ### 7. The Multi-Task Demand 115 115 + 101 116 **Problem**: Interface requires processing multiple simultaneous inputs (reading + deciding + navigating). 102 117 **Fix**: Sequence the steps. Let the user do one thing at a time. 103 118 104 119 ### 8. The Context Switch 120 120 + 105 121 **Problem**: User must jump between screens/tabs/modals to gather info for a single decision. 106 122 **Fix**: Co-locate the information needed for each decision. Reduce back-and-forth.

+23 -13

.agents/skills/critique/reference/heuristics-scoring.md

reviewed

··· 9 9 Keep users informed about what's happening through timely, appropriate feedback. 10 10 11 11 **Check for**: 12 12 + 12 13 - Loading indicators during async operations 13 14 - Confirmation of user actions (save, submit, delete) 14 15 - Progress indicators for multi-step processes ··· 29 30 Speak the user's language. Follow real-world conventions. Information appears in natural, logical order. 30 31 31 32 **Check for**: 33 33 + 32 34 - Familiar terminology (no unexplained jargon) 33 35 - Logical information order matching user expectations 34 36 - Recognizable icons and metaphors ··· 49 51 Users need a clear "emergency exit" from unwanted states without extended dialogue. 50 52 51 53 **Check for**: 54 54 + 52 55 - Undo/redo functionality 53 56 - Cancel buttons on forms and modals 54 57 - Clear navigation back to safety (home, previous) ··· 69 72 Users shouldn't wonder whether different words, situations, or actions mean the same thing. 70 73 71 74 **Check for**: 75 75 + 72 76 - Consistent terminology throughout the interface 73 77 - Same actions produce same results everywhere 74 78 - Platform conventions followed (standard UI patterns) ··· 89 93 Better than good error messages is a design that prevents problems in the first place. 90 94 91 95 **Check for**: 96 96 + 92 97 - Confirmation before destructive actions (delete, overwrite) 93 98 - Constraints preventing invalid input (date pickers, dropdowns) 94 99 - Smart defaults that reduce errors ··· 109 114 Minimize memory load. Make objects, actions, and options visible or easily retrievable. 110 115 111 116 **Check for**: 117 117 + 112 118 - Visible options (not buried in hidden menus) 113 119 - Contextual help when needed (tooltips, inline hints) 114 120 - Recent items and history ··· 129 135 Accelerators — invisible to novices — speed up expert interaction. 130 136 131 137 **Check for**: 138 138 + 132 139 - Keyboard shortcuts for common actions 133 140 - Customizable interface elements 134 141 - Recent items and favorites ··· 149 156 Interfaces should not contain irrelevant or rarely needed information. Every element should serve a purpose. 150 157 151 158 **Check for**: 159 159 + 152 160 - Only necessary information visible at each step 153 161 - Clear visual hierarchy directing attention 154 162 - Purposeful use of color and emphasis ··· 169 177 Error messages should use plain language, precisely indicate the problem, and constructively suggest a solution. 170 178 171 179 **Check for**: 180 180 + 172 181 - Plain language error messages (no error codes for users) 173 182 - Specific problem identification ("Email is missing @" not "Invalid input") 174 183 - Actionable recovery suggestions ··· 189 198 Even if the system is usable without docs, help should be easy to find, task-focused, and concise. 190 199 191 200 **Check for**: 201 201 + 192 202 - Searchable help or documentation 193 203 - Contextual help (tooltips, inline hints, guided tours) 194 204 - Task-focused organization (not feature-organized) ··· 210 220 211 221 **Total possible**: 40 points (10 heuristics × 4 max) 212 222 213 213 - | Score Range | Rating | What It Means | 214 214 - |-------------|--------|---------------| 215 215 - | 36–40 | Excellent | Minor polish only — ship it | 216 216 - | 28–35 | Good | Address weak areas, solid foundation | 217 217 - | 20–27 | Acceptable | Significant improvements needed before users are happy | 218 218 - | 12–19 | Poor | Major UX overhaul required — core experience broken | 219 219 - | 0–11 | Critical | Redesign needed — unusable in current state | 223 223 + | Score Range | Rating | What It Means | 224 224 + | ----------- | ---------- | ------------------------------------------------------ | 225 225 + | 36–40 | Excellent | Minor polish only — ship it | 226 226 + | 28–35 | Good | Address weak areas, solid foundation | 227 227 + | 20–27 | Acceptable | Significant improvements needed before users are happy | 228 228 + | 12–19 | Poor | Major UX overhaul required — core experience broken | 229 229 + | 0–11 | Critical | Redesign needed — unusable in current state | 220 230 221 231 --- 222 232 ··· 224 234 225 235 Tag each individual issue found during scoring with a priority level: 226 236 227 227 - | Priority | Name | Description | Action | 228 228 - |----------|------|-------------|--------| 229 229 - | **P0** | Blocking | Prevents task completion entirely | Fix immediately — this is a showstopper | 230 230 - | **P1** | Major | Causes significant difficulty or confusion | Fix before release | 231 231 - | **P2** | Minor | Annoyance, but workaround exists | Fix in next pass | 232 232 - | **P3** | Polish | Nice-to-fix, no real user impact | Fix if time permits | 237 237 + | Priority | Name | Description | Action | 238 238 + | -------- | -------- | ------------------------------------------ | --------------------------------------- | 239 239 + | **P0** | Blocking | Prevents task completion entirely | Fix immediately — this is a showstopper | 240 240 + | **P1** | Major | Causes significant difficulty or confusion | Fix before release | 241 241 + | **P2** | Minor | Annoyance, but workaround exists | Fix in next pass | 242 242 + | **P3** | Polish | Nice-to-fix, no real user impact | Fix if time permits | 233 243 234 244 **Tip**: If you're unsure between two levels, ask: "Would a user contact support about this?" If yes, it's at least P1.

+22 -7

.agents/skills/critique/reference/personas.md

reviewed

··· 11 11 **Profile**: Expert with similar products. Expects efficiency, hates hand-holding. Will find shortcuts or leave. 12 12 13 13 **Behaviors**: 14 14 + 14 15 - Skips all onboarding and instructions 15 16 - Looks for keyboard shortcuts immediately 16 17 - Tries to bulk-select, batch-edit, and automate ··· 18 19 - Abandons if anything feels slow or patronizing 19 20 20 21 **Test Questions**: 22 22 + 21 23 - Can Alex complete the core task in under 60 seconds? 22 24 - Are there keyboard shortcuts for common actions? 23 25 - Can onboarding be skipped entirely? ··· 25 27 - Is there a "power user" path (shortcuts, bulk actions)? 26 28 27 29 **Red Flags** (report these specifically): 30 30 + 28 31 - Forced tutorials or unskippable onboarding 29 32 - No keyboard navigation for primary actions 30 33 - Slow animations that can't be skipped ··· 38 41 **Profile**: Never used this type of product. Needs guidance at every step. Will abandon rather than figure it out. 39 42 40 43 **Behaviors**: 44 44 + 41 45 - Reads all instructions carefully 42 46 - Hesitates before clicking anything unfamiliar 43 47 - Looks for help or support constantly ··· 45 49 - Takes the most literal interpretation of any label 46 50 47 51 **Test Questions**: 52 52 + 48 53 - Is the first action obviously clear within 5 seconds? 49 54 - Are all icons labeled with text? 50 55 - Is there contextual help at decision points? ··· 52 57 - Is there a clear "back" or "undo" at every step? 53 58 54 59 **Red Flags** (report these specifically): 60 60 + 55 61 - Icon-only navigation with no labels 56 62 - Technical jargon without explanation 57 63 - No visible help option or guidance ··· 65 71 **Profile**: Uses screen reader (VoiceOver/NVDA), keyboard-only navigation. May have low vision, motor impairment, or cognitive differences. 66 72 67 73 **Behaviors**: 74 74 + 68 75 - Tabs through the interface linearly 69 76 - Relies on ARIA labels and heading structure 70 77 - Cannot see hover states or visual-only indicators ··· 72 79 - May use browser zoom up to 200% 73 80 74 81 **Test Questions**: 82 82 + 75 83 - Can the entire primary flow be completed keyboard-only? 76 84 - Are all interactive elements focusable with visible focus indicators? 77 85 - Do images have meaningful alt text? ··· 79 87 - Does the screen reader announce state changes (loading, success, errors)? 80 88 81 89 **Red Flags** (report these specifically): 90 90 + 82 91 - Click-only interactions with no keyboard alternative 83 92 - Missing or invisible focus indicators 84 93 - Meaning conveyed by color alone (red = error, green = success) ··· 93 102 **Profile**: Methodical user who pushes interfaces beyond the happy path. Tests edge cases, tries unexpected inputs, and probes for gaps in the experience. 94 103 95 104 **Behaviors**: 105 105 + 96 106 - Tests edge cases intentionally (empty states, long strings, special characters) 97 107 - Submits forms with unexpected data (emoji, RTL text, very long values) 98 108 - Tries to break workflows by navigating backwards, refreshing mid-flow, or opening in multiple tabs ··· 100 110 - Documents problems methodically 101 111 102 112 **Test Questions**: 113 113 + 103 114 - What happens at the edges (0 items, 1000 items, very long text)? 104 115 - Do error states recover gracefully or leave the UI in a broken state? 105 116 - What happens on refresh mid-workflow? Is state preserved? ··· 107 118 - How does the UI handle unexpected input (emoji, special chars, paste from Excel)? 108 119 109 120 **Red Flags** (report these specifically): 121 121 + 110 122 - Features that appear to work but silently fail or produce wrong results 111 123 - Error handling that exposes technical details or leaves UI in a broken state 112 124 - Empty states that show nothing useful ("No results" with no guidance) ··· 120 132 **Profile**: Using phone one-handed on the go. Frequently interrupted. Possibly on a slow connection. 121 133 122 134 **Behaviors**: 135 135 + 123 136 - Uses thumb only — prefers bottom-of-screen actions 124 137 - Gets interrupted mid-flow and returns later 125 138 - Switches between apps frequently ··· 127 140 - Types as little as possible, prefers taps and selections 128 141 129 142 **Test Questions**: 143 143 + 130 144 - Are primary actions in the thumb zone (bottom half of screen)? 131 145 - Is state preserved if the user leaves and returns? 132 146 - Does it work on slow connections (3G)? ··· 134 148 - Are touch targets at least 44×44pt? 135 149 136 150 **Red Flags** (report these specifically): 151 151 + 137 152 - Important actions positioned at the top of the screen (unreachable by thumb) 138 153 - No state persistence — progress lost on tab switch or interruption 139 154 - Large text inputs required where selection would work ··· 146 161 147 162 Choose personas based on the interface type: 148 163 149 149 - | Interface Type | Primary Personas | Why | 150 150 - |---------------|-----------------|-----| 164 164 + | Interface Type | Primary Personas | Why | 165 165 + | ------------------------ | -------------------- | -------------------------------- | 151 166 | Landing page / marketing | Jordan, Riley, Casey | First impressions, trust, mobile | 152 152 - | Dashboard / admin | Alex, Sam | Power users, accessibility | 153 153 - | E-commerce / checkout | Casey, Riley, Jordan | Mobile, edge cases, clarity | 154 154 - | Onboarding flow | Jordan, Casey | Confusion, interruption | 155 155 - | Data-heavy / analytics | Alex, Sam | Efficiency, keyboard nav | 156 156 - | Form-heavy / wizard | Jordan, Sam, Casey | Clarity, accessibility, mobile | 167 167 + | Dashboard / admin | Alex, Sam | Power users, accessibility | 168 168 + | E-commerce / checkout | Casey, Riley, Jordan | Mobile, edge cases, clarity | 169 169 + | Onboarding flow | Jordan, Casey | Confusion, interruption | 170 170 + | Data-heavy / analytics | Alex, Sam | Efficiency, keyboard nav | 171 171 + | Form-heavy / wizard | Jordan, Sam, Casey | Clarity, accessibility, mobile | 157 172 158 173 --- 159 174

+35 -3

.agents/skills/delight/SKILL.md

reviewed

··· 48 48 Follow these guidelines: 49 49 50 50 ### Delight Amplifies, Never Blocks 51 51 + 51 52 - Delight moments should be quick (< 1 second) 52 53 - Never delay core functionality for delight 53 54 - Make delight skippable or subtle 54 55 - Respect user's time and task focus 55 56 56 57 ### Surprise and Discovery 58 58 + 57 59 - Hide delightful details for users to discover 58 60 - Reward exploration and curiosity 59 61 - Don't announce every delight moment 60 62 - Let users share discoveries with others 61 63 62 64 ### Appropriate to Context 65 65 + 63 66 - Match delight to emotional moment (celebrate success, empathize with errors) 64 67 - Respect the user's state (don't be playful during critical errors) 65 68 - Match brand personality and audience expectations 66 69 - Cultural sensitivity (what's delightful varies by culture) 67 70 68 71 ### Compound Over Time 72 72 + 69 73 - Delight should remain fresh with repeated use 70 74 - Vary responses (not same animation every time) 71 75 - Reveal deeper layers with continued use ··· 78 82 ### Micro-interactions & Animation 79 83 80 84 **Button delight**: 85 85 + 81 86 ```css 82 87 /* Satisfying button press */ 83 88 .button { 84 84 - transition: transform 0.1s, box-shadow 0.1s; 89 89 + transition: 90 90 + transform 0.1s, 91 91 + box-shadow 0.1s; 85 92 } 86 93 .button:active { 87 94 transform: translateY(2px); 88 88 - box-shadow: 0 2px 4px rgba(0,0,0,0.2); 95 95 + box-shadow: 0 2px 4px rgba(0, 0, 0, 0.2); 89 96 } 90 97 91 98 /* Ripple effect on click */ ··· 97 104 ``` 98 105 99 106 **Loading delight**: 107 107 + 100 108 - Playful loading animations (not just spinners) 101 109 - Personality in loading messages (write product-specific ones, not generic AI filler) 102 110 - Progress indication with encouraging messages 103 111 - Skeleton screens with subtle animations 104 112 105 113 **Success animations**: 114 114 + 106 115 - Checkmark draw animation 107 116 - Confetti burst for major achievements 108 117 - Gentle scale + fade for confirmation 109 118 - Satisfying sound effects (subtle) 110 119 111 120 **Hover surprises**: 121 121 + 112 122 - Icons that animate on hover 113 123 - Color shifts or glow effects 114 124 - Tooltip reveals with personality ··· 117 127 ### Personality in Copy 118 128 119 129 **Playful error messages**: 130 130 + 120 131 ``` 121 132 "Error 404" 122 133 "This page is playing hide and seek. (And winning)" ··· 126 137 ``` 127 138 128 139 **Encouraging empty states**: 140 140 + 129 141 ``` 130 142 "No projects" 131 143 "Your canvas awaits. Create something amazing." ··· 135 147 ``` 136 148 137 149 **Playful labels & tooltips**: 150 150 + 138 151 ``` 139 152 "Delete" 140 153 "Send to void" (for playful brand) ··· 148 161 ### Illustrations & Visual Personality 149 162 150 163 **Custom illustrations**: 164 164 + 151 165 - Empty state illustrations (not stock icons) 152 166 - Error state illustrations (friendly monsters, quirky characters) 153 167 - Loading state illustrations (animated characters) 154 168 - Success state illustrations (celebrations) 155 169 156 170 **Icon personality**: 171 171 + 157 172 - Custom icon set matching brand personality 158 173 - Animated icons (subtle motion on hover/click) 159 174 - Illustrative icons (more detailed than generic) 160 175 - Consistent style across all icons 161 176 162 177 **Background effects**: 178 178 + 163 179 - Subtle particle effects 164 180 - Gradient mesh backgrounds 165 181 - Geometric patterns ··· 169 185 ### Satisfying Interactions 170 186 171 187 **Drag and drop delight**: 188 188 + 172 189 - Lift effect on drag (shadow, scale) 173 190 - Snap animation when dropped 174 191 - Satisfying placement sound 175 192 - Undo toast ("Dropped in wrong place? [Undo]") 176 193 177 194 **Toggle switches**: 195 195 + 178 196 - Smooth slide with spring physics 179 197 - Color transition 180 198 - Haptic feedback on mobile 181 199 - Optional sound effect 182 200 183 201 **Progress & achievements**: 202 202 + 184 203 - Streak counters with celebratory milestones 185 204 - Progress bars that "celebrate" at 100% 186 205 - Badge unlocks with animation 187 206 - Playful stats ("You're on fire! 5 days in a row") 188 207 189 208 **Form interactions**: 209 209 + 190 210 - Input fields that animate on focus 191 211 - Checkboxes with a satisfying scale pulse when checked 192 212 - Success state that celebrates valid input ··· 195 215 ### Sound Design 196 216 197 217 **Subtle audio cues** (when appropriate): 218 218 + 198 219 - Notification sounds (distinctive but not annoying) 199 220 - Success sounds (satisfying "ding") 200 221 - Error sounds (empathetic, not harsh) ··· 202 223 - Ambient background audio (very subtle) 203 224 204 225 **IMPORTANT**: 226 226 + 205 227 - Respect system sound settings 206 228 - Provide mute option 207 229 - Keep volumes quiet (subtle cues, not alarms) ··· 210 232 ### Easter Eggs & Hidden Delights 211 233 212 234 **Discovery rewards**: 235 235 + 213 236 - Konami code unlocks special theme 214 237 - Hidden keyboard shortcuts (Cmd+K for special features) 215 238 - Hover reveals on logos or illustrations ··· 217 240 - Console messages for developers ("Like what you see? We're hiring!") 218 241 219 242 **Seasonal touches**: 243 243 + 220 244 - Holiday themes (subtle, tasteful) 221 245 - Seasonal color shifts 222 246 - Weather-based variations 223 247 - Time-based changes (dark at night, light during day) 224 248 225 249 **Contextual personality**: 250 250 + 226 251 - Different messages based on time of day 227 252 - Responses to specific user actions 228 253 - Randomized variations (not same every time) ··· 231 256 ### Loading & Waiting States 232 257 233 258 **Make waiting engaging**: 259 259 + 234 260 - Interesting loading messages that rotate 235 261 - Progress bars with personality 236 262 - Mini-games during long loads ··· 250 276 ### Celebration Moments 251 277 252 278 **Success celebrations**: 279 279 + 253 280 - Confetti for major milestones 254 281 - Animated checkmarks for completions 255 282 - Progress bar celebrations at 100% ··· 257 284 - Personalized messages ("You published your 10th article!") 258 285 259 286 **Milestone recognition**: 287 287 + 260 288 - First-time actions get special treatment 261 289 - Streak tracking and celebration 262 290 - Progress toward goals ··· 265 293 ## Implementation Patterns 266 294 267 295 **Animation libraries**: 296 296 + 268 297 - Framer Motion (React) 269 298 - GSAP (universal) 270 299 - Lottie (After Effects animations) 271 300 - Canvas confetti (party effects) 272 301 273 302 **Sound libraries**: 303 303 + 274 304 - Howler.js (audio management) 275 305 - Use-sound (React hook) 276 306 277 307 **Physics libraries**: 308 308 + 278 309 - React Spring (spring physics) 279 310 - Popmotion (animation primitives) 280 311 281 312 **IMPORTANT**: File size matters. Compress images, optimize animations, lazy load delight features. 282 313 283 314 **NEVER**: 315 315 + 284 316 - Delay core functionality for delight 285 317 - Force users through delightful moments (make skippable) 286 318 - Use delight to hide poor UX ··· 301 333 - **Appropriate**: Matches brand and context 302 334 - **Accessible**: Works with reduced motion, screen readers 303 335 304 304 - Remember: Delight is the difference between a tool and an experience. Add personality, surprise users positively, and create moments worth sharing. But always respect usability - delight should enhance, never obstruct. 336 336 + Remember: Delight is the difference between a tool and an experience. Add personality, surprise users positively, and create moments worth sharing. But always respect usability - delight should enhance, never obstruct.

+9 -1

.agents/skills/distill/SKILL.md

reviewed

··· 52 52 Systematically remove complexity across these dimensions: 53 53 54 54 ### Information Architecture 55 55 + 55 56 - **Reduce scope**: Remove secondary actions, optional features, redundant information 56 57 - **Progressive disclosure**: Hide complexity behind clear entry points (accordions, modals, step-through flows) 57 58 - **Combine related actions**: Merge similar buttons, consolidate forms, group related content ··· 59 60 - **Remove redundancy**: If it's said elsewhere, don't repeat it here 60 61 61 62 ### Visual Simplification 63 63 + 62 64 - **Reduce color palette**: Use 1-2 colors plus neutrals, not 5-7 colors 63 65 - **Limit typography**: One font family, 3-4 sizes maximum, 2-3 weights 64 66 - **Remove decorations**: Eliminate borders, shadows, backgrounds that don't serve hierarchy or function ··· 67 69 - **Consistent spacing**: Use one spacing scale, remove arbitrary gaps 68 70 69 71 ### Layout Simplification 72 72 + 70 73 - **Linear flow**: Replace complex grids with simple vertical flow where possible 71 74 - **Remove sidebars**: Move secondary content inline or hide it 72 75 - **Full-width**: Use available space generously instead of complex multi-column layouts ··· 74 77 - **Generous white space**: Let content breathe, don't pack everything tight 75 78 76 79 ### Interaction Simplification 80 80 + 77 81 - **Reduce choices**: Fewer buttons, fewer options, clearer path forward (paradox of choice is real) 78 82 - **Smart defaults**: Make common choices automatic, only ask when necessary 79 83 - **Inline actions**: Replace modal flows with inline editing where possible ··· 81 85 - **Clear CTAs**: ONE obvious next step, not five competing actions 82 86 83 87 ### Content Simplification 88 88 + 84 89 - **Shorter copy**: Cut every sentence in half, then do it again 85 90 - **Active voice**: "Save changes" not "Changes will be saved" 86 91 - **Remove jargon**: Plain language always wins ··· 89 94 - **Remove redundant copy**: No headers restating intros, no repeated explanations, say it once 90 95 91 96 ### Code Simplification 97 97 + 92 98 - **Remove unused code**: Dead CSS, unused components, orphaned files 93 99 - **Flatten component trees**: Reduce nesting depth 94 100 - **Consolidate styles**: Merge similar styles, use utilities consistently 95 101 - **Reduce variants**: Does that component need 12 variations, or can 3 cover 90% of cases? 96 102 97 103 **NEVER**: 104 104 + 98 105 - Remove necessary functionality (simplicity ≠ feature-less) 99 106 - Sacrifice accessibility for simplicity (clear labels and ARIA still required) 100 107 - Make things so simple they're unclear (mystery ≠ minimalism) ··· 115 122 ## Document Removed Complexity 116 123 117 124 If you removed features or options: 125 125 + 118 126 - Document why they were removed 119 127 - Consider if they need alternative access points 120 128 - Note any user feedback to monitor 121 129 122 122 - Remember: You have great taste and judgment. Simplification is an act of confidence - knowing what to keep and courage to remove the rest. As Antoine de Saint-Exupéry said: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away." 130 130 + Remember: You have great taste and judgment. Simplification is an act of confidence - knowing what to keep and courage to remove the rest. As Antoine de Saint-Exupéry said: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away."

+57 -19

.agents/skills/harden/SKILL.md

reviewed

··· 45 45 ### Text Overflow & Wrapping 46 46 47 47 **Long text handling**: 48 48 + 48 49 ```css 49 50 /* Single line with ellipsis */ 50 51 .truncate { ··· 70 71 ``` 71 72 72 73 **Flex/Grid overflow**: 74 74 + 73 75 ```css 74 76 /* Prevent flex items from overflowing */ 75 77 .flex-item { ··· 85 87 ``` 86 88 87 89 **Responsive text sizing**: 90 90 + 88 91 - Use `clamp()` for fluid typography 89 92 - Set minimum readable sizes (14px on mobile) 90 93 - Test text scaling (zoom to 200%) ··· 93 96 ### Internationalization (i18n) 94 97 95 98 **Text expansion**: 99 99 + 96 100 - Add 30-40% space budget for translations 97 101 - Use flexbox/grid that adapts to content 98 102 - Test with longest language (usually German) ··· 107 111 ``` 108 112 109 113 **RTL (Right-to-Left) support**: 114 114 + 110 115 ```css 111 116 /* Use logical properties */ 112 117 margin-inline-start: 1rem; /* Not margin-left */ ··· 114 119 border-inline-end: 1px solid; /* Not border-right */ 115 120 116 121 /* Or use dir attribute */ 117 117 - [dir="rtl"] .arrow { transform: scaleX(-1); } 122 122 + [dir="rtl"] .arrow { 123 123 + transform: scaleX(-1); 124 124 + } 118 125 ``` 119 126 120 127 **Character set support**: 128 128 + 121 129 - Use UTF-8 encoding everywhere 122 130 - Test with Chinese/Japanese/Korean (CJK) characters 123 131 - Test with emoji (they can be 2-4 bytes) 124 132 - Handle different scripts (Latin, Cyrillic, Arabic, etc.) 125 133 126 134 **Date/Time formatting**: 135 135 + 127 136 ```javascript 128 137 // ✅ Use Intl API for proper formatting 129 129 - new Intl.DateTimeFormat('en-US').format(date); // 1/15/2024 130 130 - new Intl.DateTimeFormat('de-DE').format(date); // 15.1.2024 138 138 + new Intl.DateTimeFormat("en-US").format(date); // 1/15/2024 139 139 + new Intl.DateTimeFormat("de-DE").format(date); // 15.1.2024 131 140 132 132 - new Intl.NumberFormat('en-US', { 133 133 - style: 'currency', 134 134 - currency: 'USD' 141 141 + new Intl.NumberFormat("en-US", { 142 142 + style: "currency", 143 143 + currency: "USD", 135 144 }).format(1234.56); // $1,234.56 136 145 ``` 137 146 138 147 **Pluralization**: 148 148 + 139 149 ```javascript 140 150 // ❌ Bad: Assumes English pluralization 141 141 - `${count} item${count !== 1 ? 's' : ''}` 151 151 + `${count} item${count !== 1 ? "s" : ""}`; 142 152 143 153 // ✅ Good: Use proper i18n library 144 144 - t('items', { count }) // Handles complex plural rules 154 154 + t("items", { count }); // Handles complex plural rules 145 155 ``` 146 156 147 157 ### Error Handling 148 158 149 159 **Network errors**: 160 160 + 150 161 - Show clear error messages 151 162 - Provide retry button 152 163 - Explain what happened ··· 155 166 156 167 ```jsx 157 168 // Error states with recovery 158 158 - {error && ( 159 159 - <ErrorMessage> 160 160 - <p>Failed to load data. {error.message}</p> 161 161 - <button onClick={retry}>Try again</button> 162 162 - </ErrorMessage> 163 163 - )} 169 169 + { 170 170 + error && ( 171 171 + <ErrorMessage> 172 172 + <p>Failed to load data. {error.message}</p> 173 173 + <button onClick={retry}>Try again</button> 174 174 + </ErrorMessage> 175 175 + ); 176 176 + } 164 177 ``` 165 178 166 179 **Form validation errors**: 180 180 + 167 181 - Inline errors near fields 168 182 - Clear, specific messages 169 183 - Suggest corrections ··· 171 185 - Preserve user input on error 172 186 173 187 **API errors**: 188 188 + 174 189 - Handle each status code appropriately 175 190 - 400: Show validation errors 176 191 - 401: Redirect to login ··· 180 195 - 500: Show generic error, offer support 181 196 182 197 **Graceful degradation**: 198 198 + 183 199 - Core functionality works without JavaScript 184 200 - Images have alt text 185 201 - Progressive enhancement ··· 188 204 ### Edge Cases & Boundary Conditions 189 205 190 206 **Empty states**: 207 207 + 191 208 - No items in list 192 209 - No search results 193 210 - No notifications ··· 195 212 - Provide clear next action 196 213 197 214 **Loading states**: 215 215 + 198 216 - Initial load 199 217 - Pagination load 200 218 - Refresh ··· 202 220 - Time estimates for long operations 203 221 204 222 **Large datasets**: 223 223 + 205 224 - Pagination or virtual scrolling 206 225 - Search/filter capabilities 207 226 - Performance optimization 208 227 - Don't load all 10,000 items at once 209 228 210 229 **Concurrent operations**: 230 230 + 211 231 - Prevent double-submission (disable button while loading) 212 232 - Handle race conditions 213 233 - Optimistic updates with rollback 214 234 - Conflict resolution 215 235 216 236 **Permission states**: 237 237 + 217 238 - No permission to view 218 239 - No permission to edit 219 240 - Read-only mode 220 241 - Clear explanation of why 221 242 222 243 **Browser compatibility**: 244 244 + 223 245 - Polyfills for modern features 224 246 - Fallbacks for unsupported CSS 225 247 - Feature detection (not browser detection) ··· 230 252 Production-ready features work for first-time users, not just power users. Design the paths that get new users to value: 231 253 232 254 **Empty states**: Every zero-data screen needs: 255 255 + 233 256 - What will appear here (description or illustration) 234 257 - Why it matters to the user 235 258 - Clear CTA to create the first item or start from a template 236 259 - Visual interest (not just blank space with "No items yet") 237 260 238 261 Empty state types to handle: 262 262 + 239 263 - **First use**: emphasize value, provide templates 240 264 - **User cleared**: light touch, easy to recreate 241 265 - **No results**: suggest a different query, offer to clear filters 242 266 - **No permissions**: explain why, how to get access 243 267 244 268 **First-run experience**: Get users to their "aha moment" as quickly as possible. 269 269 + 245 270 - Show, don't tell -- working examples over descriptions 246 271 - Progressive disclosure -- teach one thing at a time, not everything upfront 247 272 - Make onboarding optional -- let experienced users skip 248 273 - Provide smart defaults so required setup is minimal 249 274 250 275 **Feature discovery**: Teach features when users need them, not upfront. 276 276 + 251 277 - Contextual tooltips at point of use (brief, dismissable, one-time) 252 278 - Badges or indicators on new or unused features 253 279 - Celebrate activation events quietly (a toast, not a modal) 254 280 255 281 **NEVER**: 282 282 + 256 283 - Force long onboarding before users can touch the product 257 284 - Show the same tooltip repeatedly (track and respect dismissals) 258 285 - Block the entire UI during a guided tour ··· 262 289 ### Input Validation & Sanitization 263 290 264 291 **Client-side validation**: 292 292 + 265 293 - Required fields 266 294 - Format validation (email, phone, URL) 267 295 - Length limits ··· 269 297 - Custom validation rules 270 298 271 299 **Server-side validation** (always): 300 300 + 272 301 - Never trust client-side only 273 302 - Validate and sanitize all inputs 274 303 - Protect against injection attacks 275 304 - Rate limiting 276 305 277 306 **Constraint handling**: 307 307 + 278 308 ```html 279 309 <!-- Set clear constraints --> 280 280 - <input 310 310 + <input 281 311 type="text" 282 312 maxlength="100" 283 313 pattern="[A-Za-z0-9]+" 284 314 required 285 315 aria-describedby="username-hint" 286 316 /> 287 287 - <small id="username-hint"> 288 288 - Letters and numbers only, up to 100 characters 289 289 - </small> 317 317 + <small id="username-hint"> Letters and numbers only, up to 100 characters </small> 290 318 ``` 291 319 292 320 ### Accessibility Resilience 293 321 294 322 **Keyboard navigation**: 323 323 + 295 324 - All functionality accessible via keyboard 296 325 - Logical tab order 297 326 - Focus management in modals 298 327 - Skip links for long content 299 328 300 329 **Screen reader support**: 330 330 + 301 331 - Proper ARIA labels 302 332 - Announce dynamic changes (live regions) 303 333 - Descriptive alt text 304 334 - Semantic HTML 305 335 306 336 **Motion sensitivity**: 337 337 + 307 338 ```css 308 339 @media (prefers-reduced-motion: reduce) { 309 340 * { ··· 315 346 ``` 316 347 317 348 **High contrast mode**: 349 349 + 318 350 - Test in Windows high contrast mode 319 351 - Don't rely only on color 320 352 - Provide alternative visual cues ··· 322 354 ### Performance Resilience 323 355 324 356 **Slow connections**: 357 357 + 325 358 - Progressive image loading 326 359 - Skeleton screens 327 360 - Optimistic UI updates 328 361 - Offline support (service workers) 329 362 330 363 **Memory leaks**: 364 364 + 331 365 - Clean up event listeners 332 366 - Cancel subscriptions 333 367 - Clear timers/intervals 334 368 - Abort pending requests on unmount 335 369 336 370 **Throttling & Debouncing**: 371 371 + 337 372 ```javascript 338 373 // Debounce search input 339 374 const debouncedSearch = debounce(handleSearch, 300); ··· 345 380 ## Testing Strategies 346 381 347 382 **Manual testing**: 383 383 + 348 384 - Test with extreme data (very long, very short, empty) 349 385 - Test in different languages 350 386 - Test offline ··· 354 390 - Test on old browsers 355 391 356 392 **Automated testing**: 393 393 + 357 394 - Unit tests for edge cases 358 395 - Integration tests for error scenarios 359 396 - E2E tests for critical paths ··· 363 400 **IMPORTANT**: Hardening is about expecting the unexpected. Real users will do things you never imagined. 364 401 365 402 **NEVER**: 403 403 + 366 404 - Assume perfect input (validate everything) 367 405 - Ignore internationalization (design for global) 368 406 - Leave error messages generic ("Error occurred") ··· 386 424 - **Errors**: Force API errors, test all error states 387 425 - **Empty**: Remove all data, test empty states 388 426 389 389 - Remember: You're hardening for production reality, not demo perfection. Expect users to input weird data, lose connection mid-flow, and use your product in unexpected ways. Build resilience into every component. 427 427 + Remember: You're hardening for production reality, not demo perfection. Expect users to input weird data, lose connection mid-flow, and use your product in unexpected ways. Build resilience into every component.

+45 -24

.agents/skills/impeccable/SKILL.md

reviewed

··· 30 30 Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work. 31 31 32 32 **Required context** (every design skill needs at minimum): 33 33 + 33 34 - **Target audience**: Who uses this product and in what context? 34 35 - **Use cases**: What jobs are they trying to get done? 35 36 - **Brand personality/tone**: How should the interface feel? ··· 39 40 **CRITICAL**: You cannot infer this context by reading the codebase. Code tells you what was built, not who it's for or what it should feel like. Only the creator can provide this context. 40 41 41 42 **Gathering order:** 43 43 + 42 44 1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately. 43 45 2. **Check .impeccable.md (fast)**: If not in instructions, read `.impeccable.md` from the project root. If it exists and contains the required context, proceed. 44 46 3. **Run impeccable teach (REQUIRED)**: If neither source has context, you MUST run /impeccable teach NOW before doing anything else. Do NOT skip this step. Do NOT attempt to infer context from the codebase instead. ··· 48 50 ## Design Direction 49 51 50 52 Commit to a BOLD aesthetic direction: 53 53 + 51 54 - **Purpose**: What problem does this interface solve? Who uses it? 52 55 - **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction. 53 56 - **Constraints**: Technical requirements (framework, performance, accessibility). ··· 56 59 **CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work. The key is intentionality, not intensity. 57 60 58 61 Then implement working code that is: 62 62 + 59 63 - Production-grade and functional 60 64 - Visually striking and memorable 61 65 - Cohesive with a clear aesthetic point-of-view ··· 64 68 ## Frontend Aesthetics Guidelines 65 69 66 70 ### Typography 67 67 - → *Consult [typography reference](reference/typography.md) for OpenType features, web font loading, and the deeper material on scales.* 71 71 + 72 72 + → _Consult [typography reference](reference/typography.md) for OpenType features, web font loading, and the deeper material on scales._ 68 73 69 74 Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font. 70 75 ··· 75 80 - Use fewer sizes with more contrast. A 5-step scale with at least a 1.25 ratio between steps creates clearer hierarchy than 8 sizes that are 1.1× apart. 76 81 - Line-height scales inversely with line length. Narrow columns want tighter leading, wide columns want more. For light text on dark backgrounds, ADD 0.05-0.1 to your normal line-height — light type reads as lighter weight and needs more breathing room. 77 82 - Cap line length at ~65-75ch. Body text wider than that is fatiguing. 78 78 - </typography_principles> 83 83 + </typography_principles> 79 84 80 85 <font_selection_procedure> 81 86 DO THIS BEFORE TYPING ANY FONT NAME. ··· 114 119 115 120 Reject every font that appears in the reflex_fonts_to_reject list. They are your training-data defaults and they create monoculture across projects. 116 121 117 117 - Step 3. Browse a font catalog with the 3 brand words in mind. Sources: Google Fonts, Pangram Pangram, Future Fonts, Adobe Fonts, ABC Dinamo, Klim Type Foundry, Velvetyne. Look for something that fits the brand as a *physical object* — a museum exhibit caption, a hand-painted shop sign, a 1970s mainframe terminal manual, a fabric label on the inside of a coat, a children's book printed on cheap newsprint. Reject the first thing that "looks designy" — that's the trained reflex too. Keep looking. 122 122 + Step 3. Browse a font catalog with the 3 brand words in mind. Sources: Google Fonts, Pangram Pangram, Future Fonts, Adobe Fonts, ABC Dinamo, Klim Type Foundry, Velvetyne. Look for something that fits the brand as a _physical object_ — a museum exhibit caption, a hand-painted shop sign, a 1970s mainframe terminal manual, a fabric label on the inside of a coat, a children's book printed on cheap newsprint. Reject the first thing that "looks designy" — that's the trained reflex too. Keep looking. 118 123 119 124 Step 4. Cross-check the result. The right font for an "elegant" brief is NOT necessarily a serif. The right font for a "technical" brief is NOT necessarily a sans-serif. The right font for a "warm" brief is NOT Fraunces. If your final pick lines up with your reflex pattern, go back to Step 3. 120 125 </font_selection_procedure> ··· 133 138 </typography_rules> 134 139 135 140 ### Color & Theme 136 136 - → *Consult [color reference](reference/color-and-contrast.md) for the deeper material on contrast, accessibility, and palette construction.* 141 141 + 142 142 + → _Consult [color reference](reference/color-and-contrast.md) for the deeper material on contrast, accessibility, and palette construction._ 137 143 138 144 Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. 139 145 140 146 <color_principles> 141 147 Always apply these — do not consult a reference, just do them: 142 148 143 143 - - Use OKLCH, not HSL. OKLCH is perceptually uniform: equal steps in lightness *look* equal, which HSL does not deliver. As you move toward white or black, REDUCE chroma — high chroma at extreme lightness looks garish. A light blue at 85% lightness wants ~0.08 chroma, not the 0.15 of your base color. 149 149 + - Use OKLCH, not HSL. OKLCH is perceptually uniform: equal steps in lightness _look_ equal, which HSL does not deliver. As you move toward white or black, REDUCE chroma — high chroma at extreme lightness looks garish. A light blue at 85% lightness wants ~0.08 chroma, not the 0.15 of your base color. 144 150 - Tint your neutrals toward your brand hue. Even a chroma of 0.005-0.01 is perceptible and creates subconscious cohesion between brand color and UI surfaces. The hue you tint toward should come from THIS brand, not from a "warm = friendly" or "cool = tech" formula. Pick the brand's actual hue first, then tint everything toward it. 145 145 - - The 60-30-10 rule is about visual *weight*, not pixel count. 60% neutral / surface, 30% secondary text and borders, 10% accent. Accents work BECAUSE they're rare. Overuse kills their power. 146 146 - </color_principles> 151 151 + - The 60-30-10 rule is about visual _weight_, not pixel count. 60% neutral / surface, 30% secondary text and borders, 10% accent. Accents work BECAUSE they're rare. Overuse kills their power. 152 152 + </color_principles> 147 153 148 154 <theme_selection> 149 155 Theme (light vs dark) should be DERIVED from audience and viewing context, not picked from a default. Read the brief and ask: when is this product used, by whom, in what physical setting? ··· 173 179 </color_rules> 174 180 175 181 ### Layout & Space 176 176 - → *Consult [spatial reference](reference/spatial-design.md) for the deeper material on grids, container queries, and optical adjustments.* 182 182 + 183 183 + → _Consult [spatial reference](reference/spatial-design.md) for the deeper material on grids, container queries, and optical adjustments._ 177 184 178 185 Create visual rhythm through varied spacing, not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis. 179 186 ··· 185 192 - Vary spacing for hierarchy. A heading with extra space above it reads as more important — make use of that. Don't apply the same padding everywhere. 186 193 - Self-adjusting grid pattern: `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` is the breakpoint-free responsive grid for card-style content. 187 194 - Container queries are for components, viewport queries are for page layout. A card in a sidebar should adapt to the sidebar's width, not the viewport's. 188 188 - </spatial_principles> 195 195 + </spatial_principles> 189 196 190 197 <spatial_rules> 191 198 DO create visual rhythm through varied spacing: tight groupings, generous separations. ··· 207 214 These CSS patterns are NEVER acceptable. They are the most recognizable AI design tells. Match-and-refuse: if you find yourself about to write any of these, stop and rewrite the element with a different structure entirely. 208 215 209 216 BAN 1: Side-stripe borders on cards/list items/callouts/alerts 210 210 - - PATTERN: `border-left:` or `border-right:` with width greater than 1px 211 211 - - INCLUDES: hard-coded colors AND CSS variables 212 212 - - FORBIDDEN: `border-left: 3px solid red`, `border-left: 4px solid #ff0000`, `border-left: 4px solid var(--color-warning)`, `border-left: 5px solid oklch(...)`, etc. 213 213 - - WHY: this is the single most overused "design touch" in admin, dashboard, and medical UIs. It never looks intentional regardless of color, radius, opacity, or whether the variable name is "primary" or "warning" or "accent." 214 214 - - REWRITE: use a different element structure entirely. Do not just swap to box-shadow inset. Reach for full borders, background tints, leading numbers/icons, or no visual indicator at all. 217 217 + 218 218 + - PATTERN: `border-left:` or `border-right:` with width greater than 1px 219 219 + - INCLUDES: hard-coded colors AND CSS variables 220 220 + - FORBIDDEN: `border-left: 3px solid red`, `border-left: 4px solid #ff0000`, `border-left: 4px solid var(--color-warning)`, `border-left: 5px solid oklch(...)`, etc. 221 221 + - WHY: this is the single most overused "design touch" in admin, dashboard, and medical UIs. It never looks intentional regardless of color, radius, opacity, or whether the variable name is "primary" or "warning" or "accent." 222 222 + - REWRITE: use a different element structure entirely. Do not just swap to box-shadow inset. Reach for full borders, background tints, leading numbers/icons, or no visual indicator at all. 215 223 216 224 BAN 2: Gradient text 217 217 - - PATTERN: `background-clip: text` (or `-webkit-background-clip: text`) combined with a gradient background 218 218 - - FORBIDDEN: any combination that makes text fill come from a `linear-gradient`, `radial-gradient`, or `conic-gradient` 219 219 - - WHY: gradient text is decorative rather than meaningful and is one of the top three AI design tells 220 220 - - REWRITE: use a single solid color for text. If you want emphasis, use weight or size, not gradient fill. 221 221 - </absolute_bans> 225 225 + 226 226 + - PATTERN: `background-clip: text` (or `-webkit-background-clip: text`) combined with a gradient background 227 227 + - FORBIDDEN: any combination that makes text fill come from a `linear-gradient`, `radial-gradient`, or `conic-gradient` 228 228 + - WHY: gradient text is decorative rather than meaningful and is one of the top three AI design tells 229 229 + - REWRITE: use a single solid color for text. If you want emphasis, use weight or size, not gradient fill. 230 230 + </absolute_bans> 222 231 223 232 DO: Use intentional, purposeful decorative elements that reinforce brand. 224 233 DO NOT: Use border-left or border-right greater than 1px as a colored accent stripe on cards, list items, callouts, or alerts. See <absolute_bans> above for the strict CSS pattern. ··· 228 237 DO NOT: Use modals unless there's truly no better alternative. Modals are lazy. 229 238 230 239 ### Motion 231 231 - → *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.* 240 240 + 241 241 + → _Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion._ 232 242 233 243 Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. 234 244 ··· 239 249 **DON'T**: Use bounce or elastic easing. They feel dated and tacky; real objects decelerate smoothly 240 250 241 251 ### Interaction 242 242 - → *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.* 252 252 + 253 253 + → _Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns._ 243 254 244 255 Make interactions feel fast. Use optimistic UI: update immediately, sync later. 245 256 ··· 250 261 **DON'T**: Make every button primary. Use ghost buttons, text links, secondary styles; hierarchy matters 251 262 252 263 ### Responsive 253 253 - → *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.* 264 264 + 265 265 + → _Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries._ 254 266 255 267 **DO**: Use container queries (@container) for component-level responsiveness 256 268 **DO**: Adapt the interface for different contexts, not just shrink it 257 269 **DON'T**: Hide critical functionality on mobile. Adapt the interface, don't amputate it 258 270 259 271 ### UX Writing 260 260 - → *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.* 272 272 + 273 273 + → _Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states._ 261 274 262 275 **DO**: Make every word earn its place 263 276 **DON'T**: Repeat information users can already see ··· 312 325 ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase: 313 326 314 327 #### Users & Purpose 328 328 + 315 329 - Who uses this? What's their context when using it? 316 330 - What job are they trying to get done? 317 331 - What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.) 318 332 319 333 #### Brand & Personality 334 334 + 320 335 - How would you describe the brand personality in 3 words? 321 336 - Any reference sites or apps that capture the right feel? What specifically about them? 322 337 - What should this explicitly NOT look like? Any anti-references? 323 338 324 339 #### Aesthetic Preferences 340 340 + 325 341 - Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.) 326 342 - Light mode, dark mode, or both? 327 343 - Any colors that must be used or avoided? 328 344 329 345 #### Accessibility & Inclusion 346 346 + 330 347 - Specific accessibility requirements? (WCAG level, known user needs) 331 348 - Considerations for reduced motion, color blindness, or other accommodations? 332 349 ··· 340 357 ## Design Context 341 358 342 359 ### Users 360 360 + 343 361 [Who they are, their context, the job to be done] 344 362 345 363 ### Brand Personality 364 364 + 346 365 [Voice, tone, 3-word personality, emotional goals] 347 366 348 367 ### Aesthetic Direction 368 368 + 349 369 [Visual tone, references, anti-references, theme] 350 370 351 371 ### Design Principles 372 372 + 352 373 [3-5 principles derived from the conversation that should guide all design decisions] 353 374 ``` 354 375 ··· 362 383 363 384 ## Extract Mode 364 385 365 365 - If this skill is invoked with the argument "extract" (e.g., `/impeccable extract [target]`), follow the [extract flow](reference/extract.md). Pass any additional arguments as the extraction target. 386 386 + If this skill is invoked with the argument "extract" (e.g., `/impeccable extract [target]`), follow the [extract flow](reference/extract.md). Pass any additional arguments as the extraction target.

+19 -19

.agents/skills/impeccable/reference/color-and-contrast.md

reviewed

··· 2 2 3 3 ## Color Spaces: Use OKLCH 4 4 5 5 - **Stop using HSL.** Use OKLCH (or LCH) instead. It's perceptually uniform, meaning equal steps in lightness *look* equal—unlike HSL where 50% lightness in yellow looks bright while 50% in blue looks dark. 5 5 + **Stop using HSL.** Use OKLCH (or LCH) instead. It's perceptually uniform, meaning equal steps in lightness _look_ equal—unlike HSL where 50% lightness in yellow looks bright while 50% in blue looks dark. 6 6 7 7 The OKLCH function takes three components: `oklch(lightness chroma hue)` where lightness is 0-100%, chroma is roughly 0-0.4, and hue is 0-360. To build a primary color and its lighter / darker variants, hold the chroma+hue roughly constant and vary the lightness — but **reduce chroma as you approach white or black**, because high chroma at extreme lightness looks garish. 8 8 ··· 22 22 23 23 A complete system needs: 24 24 25 25 - | Role | Purpose | Example | 26 26 - |------|---------|---------| 27 27 - | **Primary** | Brand, CTAs, key actions | 1 color, 3-5 shades | 28 28 - | **Neutral** | Text, backgrounds, borders | 9-11 shade scale | 25 25 + | Role | Purpose | Example | 26 26 + | ------------ | ----------------------------- | ------------------------- | 27 27 + | **Primary** | Brand, CTAs, key actions | 1 color, 3-5 shades | 28 28 + | **Neutral** | Text, backgrounds, borders | 9-11 shade scale | 29 29 | **Semantic** | Success, error, warning, info | 4 colors, 2-3 shades each | 30 30 - | **Surface** | Cards, modals, overlays | 2-3 elevation levels | 30 30 + | **Surface** | Cards, modals, overlays | 2-3 elevation levels | 31 31 32 32 **Skip secondary/tertiary unless you need them.** Most apps work fine with one accent color. Adding more creates decision fatigue and visual noise. 33 33 ··· 39 39 - **30%**: Secondary colors—text, borders, inactive states 40 40 - **10%**: Accent—CTAs, highlights, focus states 41 41 42 42 - The common mistake: using the accent color everywhere because it's "the brand color." Accent colors work *because* they're rare. Overuse kills their power. 42 42 + The common mistake: using the accent color everywhere because it's "the brand color." Accent colors work _because_ they're rare. Overuse kills their power. 43 43 44 44 ## Contrast & Accessibility 45 45 46 46 ### WCAG Requirements 47 47 48 48 - | Content Type | AA Minimum | AAA Target | 49 49 - |--------------|------------|------------| 50 50 - | Body text | 4.5:1 | 7:1 | 51 51 - | Large text (18px+ or 14px bold) | 3:1 | 4.5:1 | 52 52 - | UI components, icons | 3:1 | 4.5:1 | 53 53 - | Non-essential decorations | None | None | 48 48 + | Content Type | AA Minimum | AAA Target | 49 49 + | ------------------------------- | ---------- | ---------- | 50 50 + | Body text | 4.5:1 | 7:1 | 51 51 + | Large text (18px+ or 14px bold) | 3:1 | 4.5:1 | 52 52 + | UI components, icons | 3:1 | 4.5:1 | 53 53 + | Non-essential decorations | None | None | 54 54 55 55 **The gotcha**: Placeholder text still needs 4.5:1. That light gray placeholder you see everywhere? Usually fails WCAG. 56 56 ··· 83 83 84 84 You can't just swap colors. Dark mode requires different design decisions: 85 85 86 86 - | Light Mode | Dark Mode | 87 87 - |------------|-----------| 88 88 - | Shadows for depth | Lighter surfaces for depth (no shadows) | 89 89 - | Dark text on light | Light text on dark (reduce font weight) | 90 90 - | Vibrant accents | Desaturate accents slightly | 91 91 - | White backgrounds | Never pure black—use dark gray (oklch 12-18%) | 86 86 + | Light Mode | Dark Mode | 87 87 + | ------------------ | --------------------------------------------- | 88 88 + | Shadows for depth | Lighter surfaces for depth (no shadows) | 89 89 + | Dark text on light | Light text on dark (reduce font weight) | 90 90 + | Vibrant accents | Desaturate accents slightly | 91 91 + | White backgrounds | Never pure black—use dark gray (oklch 12-18%) | 92 92 93 93 In dark mode, depth comes from surface lightness, not shadow. Build a 3-step surface scale where higher elevations are lighter (e.g. 15% / 20% / 25% lightness). Use the SAME hue and chroma as your brand color (whatever it is for THIS project — do not reach for blue) and only vary the lightness. Reduce body text weight slightly (e.g. 350 instead of 400) because light text on dark reads as heavier than dark text on light. 94 94

+3

.agents/skills/impeccable/reference/craft.md

reviewed

··· 18 18 - [typography.md](typography.md) for type hierarchy 19 19 20 20 Then add references based on the brief's needs: 21 21 + 21 22 - Complex interactions or forms? Consult [interaction-design.md](interaction-design.md) 22 23 - Animation or transitions? Consult [motion-design.md](motion-design.md) 23 24 - Color-heavy or themed? Consult [color-and-contrast.md](color-and-contrast.md) ··· 37 38 7. **Responsive**: Adapt for different viewports. Don't just shrink; redesign for the context. 38 39 39 40 ### During Build 41 41 + 40 42 - Test with real (or realistic) data at every step, not placeholder text 41 43 - Check each state as you build it, not all at the end 42 44 - If you discover a design question, stop and ask rather than guessing ··· 62 64 ## Step 5: Present 63 65 64 66 Present the result to the user: 67 67 + 65 68 - Show the feature in its primary state 66 69 - Walk through the key states (empty, error, responsive) 67 70 - Explain design decisions that connect back to the design brief

+1

.agents/skills/impeccable/reference/extract.md

reviewed

··· 60 60 - Update any Storybook or component catalog 61 61 62 62 **NEVER**: 63 63 + 63 64 - Extract one-off, context-specific implementations without generalization 64 65 - Create components so generic they are useless 65 66 - Extract without considering existing design system conventions

+13 -12

.agents/skills/impeccable/reference/interaction-design.md

reviewed

··· 4 4 5 5 Every interactive element needs these states designed: 6 6 7 7 - | State | When | Visual Treatment | 8 8 - |-------|------|------------------| 9 9 - | **Default** | At rest | Base styling | 10 10 - | **Hover** | Pointer over (not touch) | Subtle lift, color shift | 11 11 - | **Focus** | Keyboard/programmatic focus | Visible ring (see below) | 12 12 - | **Active** | Being pressed | Pressed in, darker | 13 13 - | **Disabled** | Not interactive | Reduced opacity, no pointer | 14 14 - | **Loading** | Processing | Spinner, skeleton | 15 15 - | **Error** | Invalid state | Red border, icon, message | 16 16 - | **Success** | Completed | Green check, confirmation | 7 7 + | State | When | Visual Treatment | 8 8 + | ------------ | --------------------------- | --------------------------- | 9 9 + | **Default** | At rest | Base styling | 10 10 + | **Hover** | Pointer over (not touch) | Subtle lift, color shift | 11 11 + | **Focus** | Keyboard/programmatic focus | Visible ring (see below) | 12 12 + | **Active** | Being pressed | Pressed in, darker | 13 13 + | **Disabled** | Not interactive | Reduced opacity, no pointer | 14 14 + | **Loading** | Processing | Spinner, skeleton | 15 15 + | **Error** | Invalid state | Red border, icon, message | 16 16 + | **Success** | Completed | Green check, confirmation | 17 17 18 18 **The common miss**: Designing hover without focus, or vice versa. They're different. Keyboard users never see hover states. 19 19 ··· 35 35 ``` 36 36 37 37 **Focus ring design**: 38 38 + 38 39 - High contrast (3:1 minimum against adjacent colors) 39 40 - 2-3px thick 40 41 - Offset from element (not inside it) ··· 66 67 Or use the native `<dialog>` element: 67 68 68 69 ```javascript 69 69 - const dialog = document.querySelector('dialog'); 70 70 - dialog.showModal(); // Opens with focus trap, closes on Escape 70 70 + const dialog = document.querySelector("dialog"); 71 71 + dialog.showModal(); // Opens with focus trap, closes on Escape 71 72 ``` 72 73 73 74 ## The Popover API

+14 -12

.agents/skills/impeccable/reference/motion-design.md

reviewed

··· 4 4 5 5 Timing matters more than easing. These durations feel right for most UI: 6 6 7 7 - | Duration | Use Case | Examples | 8 8 - |----------|----------|----------| 9 9 - | **100-150ms** | Instant feedback | Button press, toggle, color change | 10 10 - | **200-300ms** | State changes | Menu open, tooltip, hover states | 11 11 - | **300-500ms** | Layout changes | Accordion, modal, drawer | 12 12 - | **500-800ms** | Entrance animations | Page load, hero reveals | 7 7 + | Duration | Use Case | Examples | 8 8 + | ------------- | ------------------- | ---------------------------------- | 9 9 + | **100-150ms** | Instant feedback | Button press, toggle, color change | 10 10 + | **200-300ms** | State changes | Menu open, tooltip, hover states | 11 11 + | **300-500ms** | Layout changes | Accordion, modal, drawer | 12 12 + | **500-800ms** | Entrance animations | Page load, hero reveals | 13 13 14 14 **Exit animations are faster than entrances**—use ~75% of enter duration. 15 15 ··· 17 17 18 18 **Don't use `ease`.** It's a compromise that's rarely optimal. Instead: 19 19 20 20 - | Curve | Use For | CSS | 21 21 - |-------|---------|-----| 22 22 - | **ease-out** | Elements entering | `cubic-bezier(0.16, 1, 0.3, 1)` | 23 23 - | **ease-in** | Elements leaving | `cubic-bezier(0.7, 0, 0.84, 0)` | 20 20 + | Curve | Use For | CSS | 21 21 + | --------------- | ---------------------------- | -------------------------------- | 22 22 + | **ease-out** | Elements entering | `cubic-bezier(0.16, 1, 0.3, 1)` | 23 23 + | **ease-in** | Elements leaving | `cubic-bezier(0.7, 0, 0.84, 0)` | 24 24 | **ease-in-out** | State toggles (there → back) | `cubic-bezier(0.65, 0, 0.35, 1)` | 25 25 26 26 **For micro-interactions, use exponential curves**—they feel natural because they mimic real physics (friction, deceleration): ··· 59 59 /* Provide alternative for reduced motion */ 60 60 @media (prefers-reduced-motion: reduce) { 61 61 .card { 62 62 - animation: fade-in 200ms ease-out; /* Crossfade instead of motion */ 62 62 + animation: fade-in 200ms ease-out; /* Crossfade instead of motion */ 63 63 } 64 64 } 65 65 66 66 /* Or disable entirely */ 67 67 @media (prefers-reduced-motion: reduce) { 68 68 - *, *::before, *::after { 68 68 + *, 69 69 + *::before, 70 70 + *::after { 69 71 animation-duration: 0.01ms !important; 70 72 transition-duration: 0.01ms !important; 71 73 }

+20 -14

.agents/skills/impeccable/reference/responsive-design.md

reviewed

··· 15 15 ```css 16 16 /* Fine pointer (mouse, trackpad) */ 17 17 @media (pointer: fine) { 18 18 - .button { padding: 8px 16px; } 18 18 + .button { 19 19 + padding: 8px 16px; 20 20 + } 19 21 } 20 22 21 23 /* Coarse pointer (touch, stylus) */ 22 24 @media (pointer: coarse) { 23 23 - .button { padding: 12px 20px; } /* Larger touch target */ 25 25 + .button { 26 26 + padding: 12px 20px; 27 27 + } /* Larger touch target */ 24 28 } 25 29 26 30 /* Device supports hover */ 27 31 @media (hover: hover) { 28 28 - .card:hover { transform: translateY(-2px); } 32 32 + .card:hover { 33 33 + transform: translateY(-2px); 34 34 + } 29 35 } 30 36 31 37 /* Device doesn't support hover (touch) */ 32 38 @media (hover: none) { 33 33 - .card { /* No hover state - use active instead */ } 39 39 + .card { 40 40 + /* No hover state - use active instead */ 41 41 + } 34 42 } 35 43 ``` 36 44 ··· 55 63 ``` 56 64 57 65 **Enable viewport-fit** in your meta tag: 66 66 + 58 67 ```html 59 59 - <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover"> 68 68 + <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" /> 60 69 ``` 61 70 62 71 ## Responsive Images: Get It Right ··· 66 75 ```html 67 76 <img 68 77 src="hero-800.jpg" 69 69 - srcset=" 70 70 - hero-400.jpg 400w, 71 71 - hero-800.jpg 800w, 72 72 - hero-1200.jpg 1200w 73 73 - " 78 78 + srcset="hero-400.jpg 400w, hero-800.jpg 800w, hero-1200.jpg 1200w" 74 79 sizes="(max-width: 768px) 100vw, 50vw" 75 80 alt="Hero image" 76 76 - > 81 81 + /> 77 82 ``` 78 83 79 84 **How it works**: 85 85 + 80 86 - `srcset` lists available images with their actual widths (`w` descriptors) 81 87 - `sizes` tells the browser how wide the image will display 82 88 - Browser picks the best file based on viewport width AND device pixel ratio ··· 87 93 88 94 ```html 89 95 <picture> 90 90 - <source media="(min-width: 768px)" srcset="wide.jpg"> 91 91 - <source media="(max-width: 767px)" srcset="tall.jpg"> 92 92 - <img src="fallback.jpg" alt="..."> 96 96 + <source media="(min-width: 768px)" srcset="wide.jpg" /> 97 97 + <source media="(max-width: 767px)" srcset="tall.jpg" /> 98 98 + <img src="fallback.jpg" alt="..." /> 93 99 </picture> 94 100 ``` 95 101

+11 -10

.agents/skills/impeccable/reference/spatial-design.md

reviewed

··· 21 21 ### The Squint Test 22 22 23 23 Blur your eyes (or screenshot and blur). Can you still identify: 24 24 + 24 25 - The most important element? 25 26 - The second most important? 26 27 - Clear groupings? ··· 31 32 32 33 Don't rely on size alone. Combine: 33 34 34 34 - | Tool | Strong Hierarchy | Weak Hierarchy | 35 35 - |------|------------------|----------------| 36 36 - | **Size** | 3:1 ratio or more | <2:1 ratio | 37 37 - | **Weight** | Bold vs Regular | Medium vs Regular | 38 38 - | **Color** | High contrast | Similar tones | 39 39 - | **Position** | Top/left (primary) | Bottom/right | 40 40 - | **Space** | Surrounded by white space | Crowded | 35 35 + | Tool | Strong Hierarchy | Weak Hierarchy | 36 36 + | ------------ | ------------------------- | ----------------- | 37 37 + | **Size** | 3:1 ratio or more | <2:1 ratio | 38 38 + | **Weight** | Bold vs Regular | Medium vs Regular | 39 39 + | **Color** | High contrast | Similar tones | 40 40 + | **Position** | Top/left (primary) | Bottom/right | 41 41 + | **Space** | Surrounded by white space | Crowded | 41 42 42 43 **The best hierarchy uses 2-3 dimensions at once**: A heading that's larger, bolder, AND has more space above it. 43 44 ··· 79 80 80 81 ```css 81 82 .icon-button { 82 82 - width: 24px; /* Visual size */ 83 83 + width: 24px; /* Visual size */ 83 84 height: 24px; 84 85 position: relative; 85 86 } 86 87 87 88 .icon-button::before { 88 88 - content: ''; 89 89 + content: ""; 89 90 position: absolute; 90 90 - inset: -10px; /* Expand tap target to 44px */ 91 91 + inset: -10px; /* Expand tap target to 44px */ 91 92 } 92 93 ``` 93 94

+35 -23

.agents/skills/impeccable/reference/typography.md

reviewed

··· 12 12 13 13 **Use fewer sizes with more contrast.** A 5-size system covers most needs: 14 14 15 15 - | Role | Typical Ratio | Use Case | 16 16 - |------|---------------|----------| 17 17 - | xs | 0.75rem | Captions, legal | 18 18 - | sm | 0.875rem | Secondary UI, metadata | 19 19 - | base | 1rem | Body text | 20 20 - | lg | 1.25-1.5rem | Subheadings, lead text | 21 21 - | xl+ | 2-4rem | Headlines, hero text | 15 15 + | Role | Typical Ratio | Use Case | 16 16 + | ---- | ------------- | ---------------------- | 17 17 + | xs | 0.75rem | Captions, legal | 18 18 + | sm | 0.875rem | Secondary UI, metadata | 19 19 + | base | 1rem | Body text | 20 20 + | lg | 1.25-1.5rem | Subheadings, lead text | 21 21 + | xl+ | 2-4rem | Headlines, hero text | 22 22 23 23 Popular ratios: 1.25 (major third), 1.333 (perfect fourth), 1.5 (perfect fifth). Pick one and commit. 24 24 ··· 34 34 35 35 **Avoid the invisible defaults**: Inter, Roboto, Open Sans, Lato, Montserrat. These are everywhere, making your design feel generic. They're fine for documentation or tools where personality isn't the goal—but if you want distinctive design, look elsewhere. 36 36 37 37 - **Pick the font from the brief, not from a category preset.** The most common AI typography failure is reaching for the same "tasteful" font for every editorial brief, the same "modern" font for every tech brief, the same "elegant serif" for every premium brief. Those reflexes produce monoculture across projects. The right font is one whose physical character matches *this specific* brand, audience, and moment. 37 37 + **Pick the font from the brief, not from a category preset.** The most common AI typography failure is reaching for the same "tasteful" font for every editorial brief, the same "modern" font for every tech brief, the same "elegant serif" for every premium brief. Those reflexes produce monoculture across projects. The right font is one whose physical character matches _this specific_ brand, audience, and moment. 38 38 39 39 A working selection process: 40 40 41 41 1. Read the brief once. Write down three concrete words for the brand voice. Not "modern" or "elegant" — those are dead categories. Try "warm and mechanical and opinionated" or "calm and clinical and careful" or "fast and dense and unimpressed" or "handmade and a little weird." 42 42 - 2. Now imagine the font as a physical object the brand could ship: a typewriter ribbon, a hand-lettered shop sign, a 1970s mainframe terminal manual, a fabric label on the inside of a coat, a museum exhibit caption, a tax form, a children's book printed on cheap newsprint. Whichever physical object fits the three words is pointing at the right *kind* of typeface. 42 42 + 2. Now imagine the font as a physical object the brand could ship: a typewriter ribbon, a hand-lettered shop sign, a 1970s mainframe terminal manual, a fabric label on the inside of a coat, a museum exhibit caption, a tax form, a children's book printed on cheap newsprint. Whichever physical object fits the three words is pointing at the right _kind_ of typeface. 43 43 3. Browse a font catalog (Google Fonts, Pangram Pangram, Adobe Fonts, Future Fonts, ABC Dinamo) with that physical object in mind. **Reject the first thing that "looks designy."** That's your trained-everywhere reflex. Keep looking. 44 44 4. Avoid your defaults from previous projects. If you find yourself reaching for the same display font you used last time, make yourself pick something else. 45 45 46 46 **Anti-reflexes worth defending against**: 47 47 + 47 48 - A technical/utilitarian brief does NOT need a serif "for warmth." Most tech tools should look like tech tools. 48 49 - An editorial/premium brief does NOT need the same expressive serif everyone is using right now. Premium can be Swiss-modern, can be neo-grotesque, can be a literal monospace, can be a quiet humanist sans. 49 50 - A children's product does NOT need a rounded display font. Kids' books use real type. ··· 56 57 **The non-obvious truth**: You often don't need a second font. One well-chosen font family in multiple weights creates cleaner hierarchy than two competing typefaces. Only add a second font when you need genuine contrast (e.g., display headlines + body serif). 57 58 58 59 When pairing, contrast on multiple axes: 60 60 + 59 61 - Serif + Sans (structure contrast) 60 62 - Geometric + Humanist (personality contrast) 61 63 - Condensed display + Wide body (proportion contrast) ··· 69 71 ```css 70 72 /* 1. Use font-display: swap for visibility */ 71 73 @font-face { 72 72 - font-family: 'CustomFont'; 73 73 - src: url('font.woff2') format('woff2'); 74 74 + font-family: "CustomFont"; 75 75 + src: url("font.woff2") format("woff2"); 74 76 font-display: swap; 75 77 } 76 78 77 79 /* 2. Match fallback metrics to minimize shift */ 78 80 @font-face { 79 79 - font-family: 'CustomFont-Fallback'; 80 80 - src: local('Arial'); 81 81 - size-adjust: 105%; /* Scale to match x-height */ 82 82 - ascent-override: 90%; /* Match ascender height */ 83 83 - descent-override: 20%; /* Match descender depth */ 84 84 - line-gap-override: 10%; /* Match line spacing */ 81 81 + font-family: "CustomFont-Fallback"; 82 82 + src: local("Arial"); 83 83 + size-adjust: 105%; /* Scale to match x-height */ 84 84 + ascent-override: 90%; /* Match ascender height */ 85 85 + descent-override: 20%; /* Match descender depth */ 86 86 + line-gap-override: 10%; /* Match line spacing */ 85 87 } 86 88 87 89 body { 88 88 - font-family: 'CustomFont', 'CustomFont-Fallback', sans-serif; 90 90 + font-family: "CustomFont", "CustomFont-Fallback", sans-serif; 89 91 } 90 92 ``` 91 93 ··· 107 109 108 110 ```css 109 111 /* Tabular numbers for data alignment */ 110 110 - .data-table { font-variant-numeric: tabular-nums; } 112 112 + .data-table { 113 113 + font-variant-numeric: tabular-nums; 114 114 + } 111 115 112 116 /* Proper fractions */ 113 113 - .recipe-amount { font-variant-numeric: diagonal-fractions; } 117 117 + .recipe-amount { 118 118 + font-variant-numeric: diagonal-fractions; 119 119 + } 114 120 115 121 /* Small caps for abbreviations */ 116 116 - abbr { font-variant-caps: all-small-caps; } 122 122 + abbr { 123 123 + font-variant-caps: all-small-caps; 124 124 + } 117 125 118 126 /* Disable ligatures in code */ 119 119 - code { font-variant-ligatures: none; } 127 127 + code { 128 128 + font-variant-ligatures: none; 129 129 + } 120 130 121 131 /* Enable kerning (usually on by default, but be explicit) */ 122 122 - body { font-kerning: normal; } 132 132 + body { 133 133 + font-kerning: normal; 134 134 + } 123 135 ``` 124 136 125 137 Check what features your font supports at [Wakamai Fondue](https://wakamaifondue.com/).

+33 -32

.agents/skills/impeccable/reference/ux-writing.md

reviewed

··· 4 4 5 5 **Never use "OK", "Submit", or "Yes/No".** These are lazy and ambiguous. Use specific verb + object patterns: 6 6 7 7 - | Bad | Good | Why | 8 8 - |-----|------|-----| 9 9 - | OK | Save changes | Says what will happen | 10 10 - | Submit | Create account | Outcome-focused | 11 11 - | Yes | Delete message | Confirms the action | 12 12 - | Cancel | Keep editing | Clarifies what "cancel" means | 13 13 - | Click here | Download PDF | Describes the destination | 7 7 + | Bad | Good | Why | 8 8 + | ---------- | -------------- | ----------------------------- | 9 9 + | OK | Save changes | Says what will happen | 10 10 + | Submit | Create account | Outcome-focused | 11 11 + | Yes | Delete message | Confirms the action | 12 12 + | Cancel | Keep editing | Clarifies what "cancel" means | 13 13 + | Click here | Download PDF | Describes the destination | 14 14 15 15 **For destructive actions**, name the destruction: 16 16 + 16 17 - "Delete" not "Remove" (delete is permanent, remove implies recoverable) 17 18 - "Delete 5 items" not "Delete selected" (show the count) 18 19 ··· 22 23 23 24 ### Error Message Templates 24 25 25 25 - | Situation | Template | 26 26 - |-----------|----------| 27 27 - | **Format error** | "[Field] needs to be [format]. Example: [example]" | 28 28 - | **Missing required** | "Please enter [what's missing]" | 29 29 - | **Permission denied** | "You don't have access to [thing]. [What to do instead]" | 30 30 - | **Network error** | "We couldn't reach [thing]. Check your connection and [action]." | 31 31 - | **Server error** | "Something went wrong on our end. We're looking into it. [Alternative action]" | 26 26 + | Situation | Template | 27 27 + | --------------------- | ------------------------------------------------------------------------------ | 28 28 + | **Format error** | "[Field] needs to be [format]. Example: [example]" | 29 29 + | **Missing required** | "Please enter [what's missing]" | 30 30 + | **Permission denied** | "You don't have access to [thing]. [What to do instead]" | 31 31 + | **Network error** | "We couldn't reach [thing]. Check your connection and [action]." | 32 32 + | **Server error** | "Something went wrong on our end. We're looking into it. [Alternative action]" | 32 33 33 34 ### Don't Blame the User 34 35 ··· 43 44 **Voice** is your brand's personality—consistent everywhere. 44 45 **Tone** adapts to the moment. 45 46 46 46 - | Moment | Tone Shift | 47 47 - |--------|------------| 48 48 - | Success | Celebratory, brief: "Done! Your changes are live." | 49 49 - | Error | Empathetic, helpful: "That didn't work. Here's what to try..." | 50 50 - | Loading | Reassuring: "Saving your work..." | 51 51 - | Destructive confirm | Serious, clear: "Delete this project? This can't be undone." | 47 47 + | Moment | Tone Shift | 48 48 + | ------------------- | -------------------------------------------------------------- | 49 49 + | Success | Celebratory, brief: "Done! Your changes are live." | 50 50 + | Error | Empathetic, helpful: "That didn't work. Here's what to try..." | 51 51 + | Loading | Reassuring: "Saving your work..." | 52 52 + | Destructive confirm | Serious, clear: "Delete this project? This can't be undone." | 52 53 53 54 **Never use humor for errors.** Users are already frustrated. Be helpful, not cute. 54 55 ··· 62 63 63 64 German text is ~30% longer than English. Allocate space: 64 65 65 65 - | Language | Expansion | 66 66 - |----------|-----------| 67 67 - | German | +30% | 68 68 - | French | +20% | 69 69 - | Finnish | +30-40% | 70 70 - | Chinese | -30% (fewer chars, but same width) | 66 66 + | Language | Expansion | 67 67 + | -------- | ---------------------------------- | 68 68 + | German | +30% | 69 69 + | French | +20% | 70 70 + | Finnish | +30-40% | 71 71 + | Chinese | -30% (fewer chars, but same width) | 71 72 72 73 ### Translation-Friendly Patterns 73 74 ··· 77 78 78 79 Pick one term and stick with it: 79 80 80 80 - | Inconsistent | Consistent | 81 81 - |--------------|------------| 82 82 - | Delete / Remove / Trash | Delete | 83 83 - | Settings / Preferences / Options | Settings | 84 84 - | Sign in / Log in / Enter | Sign in | 85 85 - | Create / Add / New | Create | 81 81 + | Inconsistent | Consistent | 82 82 + | -------------------------------- | ---------- | 83 83 + | Delete / Remove / Trash | Delete | 84 84 + | Settings / Preferences / Options | Settings | 85 85 + | Sign in / Log in / Enter | Sign in | 86 86 + | Create / Add / New | Create | 86 87 87 88 Build a terminology glossary and enforce it. Variety creates confusion. 88 89

+36 -25

.agents/skills/impeccable/scripts/cleanup-deprecated.mjs

reviewed

··· 18 18 * 4. Removes the corresponding entries from skills-lock.json. 19 19 */ 20 20 21 21 - import { existsSync, readFileSync, writeFileSync, rmSync, readdirSync, statSync, lstatSync, unlinkSync } from 'node:fs'; 22 22 - import { join, resolve } from 'node:path'; 21 21 + import { existsSync, readFileSync, writeFileSync, rmSync, lstatSync, unlinkSync } from "node:fs"; 22 22 + import { join, resolve } from "node:path"; 23 23 24 24 // Skills that were renamed, merged, or folded in v2.0 and v2.1. 25 25 const DEPRECATED_NAMES = [ 26 26 - 'frontend-design', // renamed to impeccable (v2.0) 27 27 - 'teach-impeccable', // folded into /impeccable teach (v2.0) 28 28 - 'arrange', // renamed to layout (v2.1) 29 29 - 'normalize', // merged into polish (v2.1) 30 30 - 'onboard', // merged into harden (v2.1) 31 31 - 'extract', // merged into /impeccable extract (v2.1) 26 26 + "frontend-design", // renamed to impeccable (v2.0) 27 27 + "teach-impeccable", // folded into /impeccable teach (v2.0) 28 28 + "arrange", // renamed to layout (v2.1) 29 29 + "normalize", // merged into polish (v2.1) 30 30 + "onboard", // merged into harden (v2.1) 31 31 + "extract", // merged into /impeccable extract (v2.1) 32 32 ]; 33 33 34 34 // All known harness directories that may contain a skills/ subfolder. 35 35 const HARNESS_DIRS = [ 36 36 - '.claude', '.cursor', '.gemini', '.codex', '.agents', 37 37 - '.trae', '.trae-cn', '.pi', '.opencode', '.kiro', '.rovodev', 36 36 + ".claude", 37 37 + ".cursor", 38 38 + ".gemini", 39 39 + ".codex", 40 40 + ".agents", 41 41 + ".trae", 42 42 + ".trae-cn", 43 43 + ".pi", 44 44 + ".opencode", 45 45 + ".kiro", 46 46 + ".rovodev", 38 47 ]; 39 48 40 49 /** ··· 43 52 */ 44 53 export function findProjectRoot(startDir = process.cwd()) { 45 54 let dir = resolve(startDir); 46 46 - const { root } = { root: '/' }; 55 55 + const { root } = { root: "/" }; 47 56 while (dir !== root) { 48 57 if ( 49 49 - existsSync(join(dir, 'package.json')) || 50 50 - existsSync(join(dir, '.git')) || 51 51 - existsSync(join(dir, 'skills-lock.json')) 58 58 + existsSync(join(dir, "package.json")) || 59 59 + existsSync(join(dir, ".git")) || 60 60 + existsSync(join(dir, "skills-lock.json")) 52 61 ) { 53 62 return dir; 54 63 } 55 55 - const parent = resolve(dir, '..'); 64 64 + const parent = resolve(dir, ".."); 56 65 if (parent === dir) break; 57 66 dir = parent; 58 67 } ··· 65 74 * Returns false for non-existent paths or skills that don't match. 66 75 */ 67 76 export function isImpeccableSkill(skillDir) { 68 68 - const skillMd = join(skillDir, 'SKILL.md'); 77 77 + const skillMd = join(skillDir, "SKILL.md"); 69 78 if (!existsSync(skillMd)) return false; 70 79 try { 71 71 - const content = readFileSync(skillMd, 'utf-8'); 80 80 + const content = readFileSync(skillMd, "utf-8"); 72 81 return /impeccable/i.test(content); 73 82 } catch { 74 83 return false; ··· 95 104 export function findSkillsDirs(projectRoot) { 96 105 const dirs = []; 97 106 for (const harness of HARNESS_DIRS) { 98 98 - const candidate = join(projectRoot, harness, 'skills'); 107 107 + const candidate = join(projectRoot, harness, "skills"); 99 108 if (existsSync(candidate)) { 100 109 dirs.push(candidate); 101 110 } ··· 154 163 * Returns the list of removed skill names. 155 164 */ 156 165 export function cleanSkillsLock(projectRoot) { 157 157 - const lockPath = join(projectRoot, 'skills-lock.json'); 166 166 + const lockPath = join(projectRoot, "skills-lock.json"); 158 167 if (!existsSync(lockPath)) return []; 159 168 160 169 let lock; 161 170 try { 162 162 - lock = JSON.parse(readFileSync(lockPath, 'utf-8')); 171 171 + lock = JSON.parse(readFileSync(lockPath, "utf-8")); 163 172 } catch { 164 173 return []; 165 174 } 166 175 167 167 - if (!lock.skills || typeof lock.skills !== 'object') return []; 176 176 + if (!lock.skills || typeof lock.skills !== "object") return []; 168 177 169 178 const targets = buildTargetNames(); 170 179 const removed = []; ··· 173 182 const entry = lock.skills[name]; 174 183 if (!entry) continue; 175 184 // Only remove if it belongs to impeccable 176 176 - if (entry.source === 'pbakaus/impeccable') { 185 185 + if (entry.source === "pbakaus/impeccable") { 177 186 delete lock.skills[name]; 178 187 removed.push(name); 179 188 } 180 189 } 181 190 182 191 if (removed.length > 0) { 183 183 - writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n', 'utf-8'); 192 192 + writeFileSync(lockPath, JSON.stringify(lock, null, 2) + "\n", "utf-8"); 184 193 } 185 194 186 195 return removed; ··· 200 209 if (process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname)) { 201 210 const result = cleanup(); 202 211 if (result.deletedPaths.length === 0 && result.removedLockEntries.length === 0) { 203 203 - console.log('No deprecated Impeccable skills found. Nothing to clean up.'); 212 212 + console.log("No deprecated Impeccable skills found. Nothing to clean up."); 204 213 } else { 205 214 if (result.deletedPaths.length > 0) { 206 215 console.log(`Removed ${result.deletedPaths.length} deprecated skill(s):`); 207 216 for (const p of result.deletedPaths) console.log(` - ${p}`); 208 217 } 209 218 if (result.removedLockEntries.length > 0) { 210 210 - console.log(`Cleaned ${result.removedLockEntries.length} entry/entries from skills-lock.json:`); 219 219 + console.log( 220 220 + `Cleaned ${result.removedLockEntries.length} entry/entries from skills-lock.json:`, 221 221 + ); 211 222 for (const name of result.removedLockEntries) console.log(` - ${name}`); 212 223 } 213 224 }

+2 -1

.agents/skills/layout/SKILL.md

reviewed

··· 103 103 - If an icon looks visually off-center despite being geometrically centered, nudge it — but only if you're confident it actually looks wrong. Don't adjust speculatively. 104 104 105 105 **NEVER**: 106 106 + 106 107 - Use arbitrary spacing values outside your scale 107 108 - Make all spacing equal — variety creates hierarchy 108 109 - Wrap everything in cards — not everything needs a container ··· 122 123 - **Consistency**: Is the spacing system applied uniformly? 123 124 - **Responsiveness**: Does the layout adapt gracefully across screen sizes? 124 125 125 125 - Remember: Space is the most underused design tool. A layout with the right rhythm and hierarchy can make even simple content feel polished and intentional. 126 126 + Remember: Space is the most underused design tool. A layout with the right rhythm and hierarchy can make even simple content feel polished and intentional.

+31 -9

.agents/skills/optimize/SKILL.md

reviewed

··· 34 34 ### Loading Performance 35 35 36 36 **Optimize Images**: 37 37 + 37 38 - Use modern formats (WebP, AVIF) 38 39 - Proper sizing (don't load 3000px image for 300px display) 39 40 - Lazy loading for below-fold images ··· 42 43 - Use CDN for faster delivery 43 44 44 45 ```html 45 45 - <img 46 46 + <img 46 47 src="hero.webp" 47 48 srcset="hero-400.webp 400w, hero-800.webp 800w, hero-1200.webp 1200w" 48 49 sizes="(max-width: 400px) 400px, (max-width: 800px) 800px, 1200px" ··· 52 53 ``` 53 54 54 55 **Reduce JavaScript Bundle**: 56 56 + 55 57 - Code splitting (route-based, component-based) 56 58 - Tree shaking (remove unused code) 57 59 - Remove unused dependencies ··· 60 62 61 63 ```javascript 62 64 // Lazy load heavy component 63 63 - const HeavyChart = lazy(() => import('./HeavyChart')); 65 65 + const HeavyChart = lazy(() => import("./HeavyChart")); 64 66 ``` 65 67 66 68 **Optimize CSS**: 69 69 + 67 70 - Remove unused CSS 68 71 - Critical CSS inline, rest async 69 72 - Minimize CSS files 70 73 - Use CSS containment for independent regions 71 74 72 75 **Optimize Fonts**: 76 76 + 73 77 - Use `font-display: swap` or `optional` 74 78 - Subset fonts (only characters you need) 75 79 - Preload critical fonts ··· 78 82 79 83 ```css 80 84 @font-face { 81 81 - font-family: 'CustomFont'; 82 82 - src: url('/fonts/custom.woff2') format('woff2'); 85 85 + font-family: "CustomFont"; 86 86 + src: url("/fonts/custom.woff2") format("woff2"); 83 87 font-display: swap; /* Show fallback immediately */ 84 88 unicode-range: U+0020-007F; /* Basic Latin only */ 85 89 } 86 90 ``` 87 91 88 92 **Optimize Loading Strategy**: 93 93 + 89 94 - Critical resources first (async/defer non-critical) 90 95 - Preload critical assets 91 96 - Prefetch likely next pages ··· 95 100 ### Rendering Performance 96 101 97 102 **Avoid Layout Thrashing**: 103 103 + 98 104 ```javascript 99 105 // ❌ Bad: Alternating reads and writes (causes reflows) 100 100 - elements.forEach(el => { 106 106 + elements.forEach((el) => { 101 107 const height = el.offsetHeight; // Read (forces layout) 102 108 el.style.height = height * 2; // Write 103 109 }); 104 110 105 111 // ✅ Good: Batch reads, then batch writes 106 106 - const heights = elements.map(el => el.offsetHeight); // All reads 112 112 + const heights = elements.map((el) => el.offsetHeight); // All reads 107 113 elements.forEach((el, i) => { 108 114 el.style.height = heights[i] * 2; // All writes 109 115 }); 110 116 ``` 111 117 112 118 **Optimize Rendering**: 119 119 + 113 120 - Use CSS `contain` property for independent regions 114 121 - Minimize DOM depth (flatter is faster) 115 122 - Reduce DOM size (fewer elements) ··· 117 124 - Virtual scrolling for very long lists (react-window, react-virtualized) 118 125 119 126 **Reduce Paint & Composite**: 127 127 + 120 128 - Use `transform` and `opacity` for animations (GPU-accelerated) 121 129 - Avoid animating layout properties (width, height, top, left) 122 130 - Use `will-change` sparingly for known expensive operations ··· 125 133 ### Animation Performance 126 134 127 135 **GPU Acceleration**: 136 136 + 128 137 ```css 129 138 /* ✅ GPU-accelerated (fast) */ 130 139 .animated { ··· 140 149 ``` 141 150 142 151 **Smooth 60fps**: 152 152 + 143 153 - Target 16ms per frame (60fps) 144 154 - Use `requestAnimationFrame` for JS animations 145 155 - Debounce/throttle scroll handlers ··· 147 157 - Avoid long-running JavaScript during animations 148 158 149 159 **Intersection Observer**: 160 160 + 150 161 ```javascript 151 162 // Efficiently detect when elements enter viewport 152 163 const observer = new IntersectionObserver((entries) => { 153 153 - entries.forEach(entry => { 164 164 + entries.forEach((entry) => { 154 165 if (entry.isIntersecting) { 155 166 // Element is visible, lazy load or animate 156 167 } ··· 161 172 ### React/Framework Optimization 162 173 163 174 **React-specific**: 175 175 + 164 176 - Use `memo()` for expensive components 165 177 - `useMemo()` and `useCallback()` for expensive computations 166 178 - Virtualize long lists ··· 169 181 - Use React DevTools Profiler 170 182 171 183 **Framework-agnostic**: 184 184 + 172 185 - Minimize re-renders 173 186 - Debounce expensive operations 174 187 - Memoize computed values ··· 177 190 ### Network Optimization 178 191 179 192 **Reduce Requests**: 193 193 + 180 194 - Combine small files 181 195 - Use SVG sprites for icons 182 196 - Inline small critical assets 183 197 - Remove unused third-party scripts 184 198 185 199 **Optimize APIs**: 200 200 + 186 201 - Use pagination (don't load everything) 187 202 - GraphQL to request only needed fields 188 203 - Response compression (gzip, brotli) ··· 190 205 - CDN for static assets 191 206 192 207 **Optimize for Slow Connections**: 208 208 + 193 209 - Adaptive loading based on connection (navigator.connection) 194 210 - Optimistic UI updates 195 211 - Request prioritization ··· 198 214 ## Core Web Vitals Optimization 199 215 200 216 ### Largest Contentful Paint (LCP < 2.5s) 217 217 + 201 218 - Optimize hero images 202 219 - Inline critical CSS 203 220 - Preload key resources ··· 205 222 - Server-side rendering 206 223 207 224 ### First Input Delay (FID < 100ms) / INP (< 200ms) 225 225 + 208 226 - Break up long tasks 209 227 - Defer non-critical JavaScript 210 228 - Use web workers for heavy computation 211 229 - Reduce JavaScript execution time 212 230 213 231 ### Cumulative Layout Shift (CLS < 0.1) 232 232 + 214 233 - Set dimensions on images and videos 215 234 - Don't inject content above existing content 216 235 - Use `aspect-ratio` CSS property ··· 227 246 ## Performance Monitoring 228 247 229 248 **Tools to use**: 249 249 + 230 250 - Chrome DevTools (Lighthouse, Performance panel) 231 251 - WebPageTest 232 252 - Core Web Vitals (Chrome UX Report) ··· 234 254 - Performance monitoring (Sentry, DataDog, New Relic) 235 255 236 256 **Key metrics**: 257 257 + 237 258 - LCP, FID/INP, CLS (Core Web Vitals) 238 259 - Time to Interactive (TTI) 239 260 - First Contentful Paint (FCP) ··· 244 265 **IMPORTANT**: Measure on real devices with real network conditions. Desktop Chrome with fast connection isn't representative. 245 266 246 267 **NEVER**: 268 268 + 247 269 - Optimize without measuring (premature optimization) 248 270 - Sacrifice accessibility for performance 249 271 - Break functionality while optimizing ··· 261 283 - **Different devices**: Test on low-end Android, not just flagship iPhone 262 284 - **Slow connections**: Throttle to 3G, test experience 263 285 - **No regressions**: Ensure functionality still works 264 264 - - **User perception**: Does it *feel* faster? 286 286 + - **User perception**: Does it _feel_ faster? 265 287 266 266 - Remember: Performance is a feature. Fast experiences feel more responsive, more polished, more professional. Optimize systematically, measure ruthlessly, and prioritize user-perceived performance. 288 288 + Remember: Performance is a feature. Fast experiences feel more responsive, more polished, more professional. Optimize systematically, measure ruthlessly, and prioritize user-perceived performance.

+21 -4

.agents/skills/overdrive/SKILL.md

reviewed

··· 42 42 The right kind of technical ambition depends entirely on what you're working with. Before choosing a technique, ask: **what would make a user of THIS specific interface say "wow, that's nice"?** 43 43 44 44 ### For visual/marketing surfaces 45 45 + 45 46 Pages, hero sections, landing pages, portfolios — the "wow" is often sensory: a scroll-driven reveal, a shader background, a cinematic page transition, generative art that responds to the cursor. 46 47 47 48 ### For functional UI 49 49 + 48 50 Tables, forms, dialogs, navigation — the "wow" is in how it FEELS: a dialog that morphs from the button that triggered it via View Transitions, a data table that renders 100k rows at 60fps via virtual scrolling, a form with streaming validation that feels instant, drag-and-drop with spring physics. 49 51 50 52 ### For performance-critical UI 53 53 + 51 54 The "wow" is invisible but felt: a search that filters 50k items without a flicker, a complex form that never blocks the main thread, an image editor that processes in near-real-time. The interface just never hesitates. 52 55 53 56 ### For data-heavy interfaces 57 57 + 54 58 Charts and dashboards — the "wow" is in fluidity: GPU-accelerated rendering via Canvas/WebGL for massive datasets, animated transitions between data states, force-directed graph layouts that settle naturally. 55 59 56 60 **The common thread**: something about the implementation goes beyond what users expect from a web interface. The technique serves the experience, not the other way around. ··· 60 64 Organized by what you're trying to achieve, not by technology name. 61 65 62 66 ### Make transitions feel cinematic 67 67 + 63 68 - **View Transitions API** (same-document: all browsers; cross-document: no Firefox) — shared element morphing between states. A list item expanding into a detail page. A button morphing into a dialog. This is the closest thing to native FLIP animations. 64 69 - **`@starting-style`** (all browsers) — animate elements from `display: none` to visible with CSS only, including entry keyframes 65 70 - **Spring physics** — natural motion with mass, tension, and damping instead of cubic-bezier. Libraries: motion (formerly Framer Motion), GSAP, or roll your own spring solver. 66 71 67 72 ### Tie animation to scroll position 73 73 + 68 74 - **Scroll-driven animations** (`animation-timeline: scroll()`) — CSS-only, no JS. Parallax, progress bars, reveal sequences all driven by scroll position. (Chrome/Edge/Safari; Firefox: flag only — always provide a static fallback) 69 75 70 76 ### Render beyond CSS 77 77 + 71 78 - **WebGL** (all browsers) — shader effects, post-processing, particle systems. Libraries: Three.js, OGL (lightweight), regl. Use for effects CSS can't express. 72 79 - **WebGPU** (Chrome/Edge; Safari partial; Firefox: flag only) — next-gen GPU compute. More powerful than WebGL but limited browser support. Always fall back to WebGL2. 73 80 - **Canvas 2D / OffscreenCanvas** — custom rendering, pixel manipulation, or moving heavy rendering off the main thread entirely via Web Workers + OffscreenCanvas. 74 81 - **SVG filter chains** — displacement maps, turbulence, morphology for organic distortion effects. CSS-animatable. 75 82 76 83 ### Make data feel alive 84 84 + 77 85 - **Virtual scrolling** — render only visible rows for tables/lists with tens of thousands of items. No library required for simple cases; TanStack Virtual for complex ones. 78 86 - **GPU-accelerated charts** — Canvas or WebGL-rendered data visualization for datasets too large for SVG/DOM. Libraries: deck.gl, regl-based custom renderers. 79 87 - **Animated data transitions** — morph between chart states rather than replacing. D3's `transition()` or View Transitions for DOM-based charts. 80 88 81 89 ### Animate complex properties 90 90 + 82 91 - **`@property`** (all browsers) — register custom CSS properties with types, enabling animation of gradients, colors, and complex values that CSS can't normally interpolate. 83 92 - **Web Animations API** (all browsers) — JavaScript-driven animations with the performance of CSS. Composable, cancellable, reversible. The foundation for complex choreography. 84 93 85 94 ### Push performance boundaries 95 95 + 86 96 - **Web Workers** — move computation off the main thread. Heavy data processing, image manipulation, search indexing — anything that would cause jank. 87 97 - **OffscreenCanvas** — render in a Worker thread. The main thread stays free while complex visuals render in the background. 88 98 - **WASM** — near-native performance for computation-heavy features. Image processing, physics simulations, codecs. 89 99 90 100 ### Interact with the device 101 101 + 91 102 - **Web Audio API** — spatial audio, audio-reactive visualizations, sonic feedback. Requires user gesture to start. 92 103 - **Device APIs** — orientation, ambient light, geolocation. Use sparingly and always with user permission. 93 104 ··· 101 112 102 113 ```css 103 114 @supports (animation-timeline: scroll()) { 104 104 - .hero { animation-timeline: scroll(); } 115 115 + .hero { 116 116 + animation-timeline: scroll(); 117 117 + } 105 118 } 106 119 ``` 107 120 108 121 ```javascript 109 109 - if ('gpu' in navigator) { /* WebGPU */ } 110 110 - else if (canvas.getContext('webgl2')) { /* WebGL2 fallback */ } 122 122 + if ("gpu" in navigator) { 123 123 + /* WebGPU */ 124 124 + } else if (canvas.getContext("webgl2")) { 125 125 + /* WebGL2 fallback */ 126 126 + } 111 127 /* CSS-only fallback must still look good */ 112 128 ``` 113 129 ··· 124 140 The gap between "cool" and "extraordinary" is in the last 20% of refinement: the easing curve on a spring animation, the timing offset in a staggered reveal, the subtle secondary motion that makes a transition feel physical. Don't ship the first version that works — ship the version that feels inevitable. 125 141 126 142 **NEVER**: 143 143 + 127 144 - Ignore `prefers-reduced-motion` — this is an accessibility requirement, not a suggestion 128 145 - Ship effects that cause jank on mid-range devices 129 146 - Use bleeding-edge APIs without a functional fallback ··· 139 156 - **The accessibility test**: Enable reduced motion. Still beautiful? 140 157 - **The context test**: Does this make sense for THIS brand and audience? 141 158 142 142 - Remember: "Technically extraordinary" isn't about using the newest API. It's about making an interface do something users didn't think a website could do. 159 159 + Remember: "Technically extraordinary" isn't about using the newest API. It's about making an interface do something users didn't think a website could do.

+3 -1

.agents/skills/polish/SKILL.md

reviewed

··· 57 57 - **Grid adherence**: Elements snap to baseline grid 58 58 59 59 **Check**: 60 60 + 60 61 - Enable grid overlay and verify alignment 61 62 - Check spacing with browser inspector 62 63 - Test at multiple viewport sizes ··· 194 195 **IMPORTANT**: Polish is about details. Zoom in. Squint at it. Use it yourself. The little things add up. 195 196 196 197 **NEVER**: 198 198 + 197 199 - Polish before it's functionally complete 198 200 - Spend hours on polish if it ships in 30 minutes (triage) 199 201 - Introduce bugs while polishing (test thoroughly) ··· 221 223 - **Consolidate tokens**: If you introduced new values, check whether they should be tokens. 222 224 - **Verify DRYness**: Look for duplication introduced during polishing and consolidate. 223 225 224 224 - 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. 226 226 + 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.

+7 -1

.agents/skills/quieter/SKILL.md

reviewed

··· 52 52 Systematically reduce intensity across these dimensions: 53 53 54 54 ### Color Refinement 55 55 + 55 56 - **Reduce saturation**: Shift from fully saturated to 70-85% saturation 56 57 - **Soften palette**: Replace bright colors with muted, sophisticated tones 57 58 - **Reduce color variety**: Use fewer colors more thoughtfully ··· 61 62 - **Never gray on color**: If you have gray text on a colored background, use a darker shade of that color or transparency instead 62 63 63 64 ### Visual Weight Reduction 65 65 + 64 66 - **Typography**: Reduce font weights (900 → 600, 700 → 500), decrease sizes where appropriate 65 67 - **Hierarchy through subtlety**: Use weight, size, and space instead of color and boldness 66 68 - **White space**: Increase breathing room, reduce density 67 69 - **Borders & lines**: Reduce thickness, decrease opacity, or remove entirely 68 70 69 71 ### Simplification 72 72 + 70 73 - **Remove decorative elements**: Gradients, shadows, patterns, textures that don't serve purpose 71 74 - **Simplify shapes**: Reduce border radius extremes, simplify custom shapes 72 75 - **Reduce layering**: Flatten visual hierarchy where possible 73 76 - **Clean up effects**: Reduce or remove blur effects, glows, multiple shadows 74 77 75 78 ### Motion Reduction 79 79 + 76 80 - **Reduce animation intensity**: Shorter distances (10-20px instead of 40px), gentler easing 77 81 - **Remove decorative animations**: Keep functional motion, remove flourishes 78 82 - **Subtle micro-interactions**: Replace dramatic effects with gentle feedback ··· 80 84 - **Remove animations entirely** if they're not serving a clear purpose 81 85 82 86 ### Composition Refinement 87 87 + 83 88 - **Reduce scale jumps**: Smaller contrast between sizes creates calmer feeling 84 89 - **Align to grid**: Bring rogue elements back into systematic alignment 85 90 - **Even out spacing**: Replace extreme spacing variations with consistent rhythm 86 91 87 92 **NEVER**: 93 93 + 88 94 - Make everything the same size/weight (hierarchy still matters) 89 95 - Remove all color (quiet ≠ grayscale) 90 96 - Eliminate all personality (maintain character through refinement) ··· 100 106 - **Better reading**: Is text easier to read for extended periods? 101 107 - **Sophistication**: Does it feel more refined and premium? 102 108 103 103 - Remember: Quiet design is confident design. It doesn't need to shout. Less is more, but less is also harder. Refine with precision and maintain intentionality. 109 109 + Remember: Quiet design is confident design. It doesn't need to shout. Less is more, but less is also harder. Refine with precision and maintain intentionality.

+6 -1

.agents/skills/shape/SKILL.md

reviewed

··· 29 29 Ask these questions in conversation, adapting based on answers. Don't dump them all at once; have a natural dialogue. ask the user directly to clarify what you cannot infer. 30 30 31 31 ### Purpose & Context 32 32 + 32 33 - What is this feature for? What problem does it solve? 33 34 - Who specifically will use it? (Not "users"; be specific: role, context, frequency) 34 35 - What does success look like? How will you know this feature is working? 35 36 - What's the user's state of mind when they reach this feature? (Rushed? Exploring? Anxious? Focused?) 36 37 37 38 ### Content & Data 39 39 + 38 40 - What content or data does this feature display or collect? 39 41 - What are the realistic ranges? (Minimum, typical, maximum, e.g., 0 items, 5 items, 500 items) 40 42 - What are the edge cases? (Empty state, error state, first-time use, power user) 41 43 - Is any content dynamic? What changes and how often? 42 44 43 45 ### Design Goals 46 46 + 44 47 - What's the single most important thing a user should do or understand here? 45 48 - What should this feel like? (Fast/efficient? Calm/trustworthy? Fun/playful? Premium/refined?) 46 49 - Are there existing patterns in the product this should be consistent with? 47 50 - Are there specific examples (inside or outside the product) that capture what you're going for? 48 51 49 52 ### Constraints 53 53 + 50 54 - Are there technical constraints? (Framework, performance budget, browser support) 51 55 - Are there content constraints? (Localization, dynamic text length, user-generated content) 52 56 - Mobile/responsive requirements? 53 57 - Accessibility requirements beyond WCAG AA? 54 58 55 59 ### Anti-Goals 60 60 + 56 61 - What should this NOT be? What would be a wrong direction? 57 62 - What's the biggest risk of getting this wrong? 58 63 ··· 93 98 94 99 ask the user directly to clarify what you cannot infer. Get explicit confirmation of the brief before finishing. If the user disagrees with any part, revisit the relevant discovery questions. 95 100 96 96 - Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this skill internally.) 101 101 + Once confirmed, the brief is complete. The user can now hand it to /impeccable, or use it to guide any other implementation approach. (If the user wants the full discovery-then-build flow in one step, they should use /impeccable craft instead, which runs this skill internally.)

+4 -1

.agents/skills/typeset/SKILL.md

reviewed

··· 61 61 ### Font Selection 62 62 63 63 If fonts need replacing: 64 64 + 64 65 - Choose fonts that reflect the brand personality 65 66 - Pair with genuine contrast (serif + sans, geometric + humanist) — or use a single family in multiple weights 66 67 - Ensure web font loading doesn't cause layout shift (`font-display: swap`, metric-matched fallbacks) ··· 68 69 ### Establish Hierarchy 69 70 70 71 Build a clear type scale: 72 72 + 71 73 - **5 sizes cover most needs**: caption, secondary, body, subheading, heading 72 74 - **Use a consistent ratio** between levels (1.25, 1.333, or 1.5) 73 75 - **Combine dimensions**: Size + weight + color + space for strong hierarchy — don't rely on size alone ··· 95 97 - Load only the weights you actually use (each weight adds to page load) 96 98 97 99 **NEVER**: 100 100 + 98 101 - Use more than 2-3 font families 99 102 - Pick sizes arbitrarily — commit to a scale 100 103 - Set body text below 16px ··· 113 116 - **Performance**: Are web fonts loading efficiently without layout shift? 114 117 - **Accessibility**: Does text meet WCAG contrast ratios? Is it zoomable to 200%? 115 118 116 116 - Remember: Typography is the foundation of interface design — it carries the majority of information. Getting it right is the highest-leverage improvement you can make. 119 119 + Remember: Typography is the foundation of interface design — it carries the majority of information. Getting it right is the highest-leverage improvement you can make.