this repo has no description
formats
+450
-211
+16
-1
.agents/skills/adapt/SKILL.md
+16
-1
.agents/skills/adapt/SKILL.md
···
45
45
### Mobile Adaptation (Desktop → Mobile)
46
46
47
47
**Layout Strategy**:
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
-
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
+
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
+17
-4
.agents/skills/animate/SKILL.md
···
51
51
Add motion systematically across these categories:
52
52
53
53
### Entrance Animations
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
+
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
+
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
+
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
+
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
+
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
+
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
+
109
117
```css
110
118
/* Recommended - natural deceleration */
111
-
--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1); /* Smooth, refined */
112
-
--ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1); /* Slightly snappier */
113
-
--ease-out-expo: cubic-bezier(0.16, 1, 0.3, 1); /* Confident, decisive */
119
+
--ease-out-quart: cubic-bezier(0.25, 1, 0.5, 1); /* Smooth, refined */
120
+
--ease-out-quint: cubic-bezier(0.22, 1, 0.36, 1); /* Slightly snappier */
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
+
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
+
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
+
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
+
145
157
```css
146
158
@media (prefers-reduced-motion: reduce) {
147
159
* {
···
153
165
```
154
166
155
167
**NEVER**:
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
-
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
+
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
+19
-9
.agents/skills/audit/SKILL.md
···
23
23
### 1. Accessibility (A11y)
24
24
25
25
**Check for**:
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
+
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
+
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
+
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
-
| # | Dimension | Score | Key Finding |
78
-
|---|-----------|-------|-------------|
79
-
| 1 | Accessibility | ? | [most critical a11y issue or "--"] |
80
-
| 2 | Performance | ? | |
81
-
| 3 | Responsive Design | ? | |
82
-
| 4 | Theming | ? | |
83
-
| 5 | Anti-Patterns | ? | |
84
-
| **Total** | | **??/20** | **[Rating band]** |
81
+
| # | Dimension | Score | Key Finding |
82
+
| --------- | ----------------- | --------- | ---------------------------------- |
83
+
| 1 | Accessibility | ? | [most critical a11y issue or "--"] |
84
+
| 2 | Performance | ? | |
85
+
| 3 | Responsive Design | ? | |
86
+
| 4 | Theming | ? | |
87
+
| 5 | Anti-Patterns | ? | |
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
+
89
94
**Start here.** Pass/fail: Does this look AI-generated? List specific tells. Be brutally honest.
90
95
91
96
### Executive Summary
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
+
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
+
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
+
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
+
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
-
Remember: You're a technical quality auditor. Document systematically, prioritize ruthlessly, cite specific code locations, and provide clear paths to improvement.
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
+8
-1
.agents/skills/bolder/SKILL.md
···
54
54
Systematically increase impact across these dimensions:
55
55
56
56
### Typography Amplification
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
+
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
+
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
+
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
+
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
+
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
+
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
-
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
+
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
+20
-1
.agents/skills/clarify/SKILL.md
···
51
51
Refine text across these common areas:
52
52
53
53
### Error Messages
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
+
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
+
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
+
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
+
82
87
**Bad**: "Click here" | "Submit" | "OK"
83
88
**Good**: "Create account" | "Save changes" | "Got it, thanks"
84
89
85
90
**Principles**:
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
+
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
+
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
+
102
111
**Bad**: "No items"
103
112
**Good**: "No projects yet. Create your first project to get started."
104
113
105
114
**Principles**:
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
+
111
122
**Bad**: "Success"
112
123
**Good**: "Settings saved! Your changes will take effect immediately."
113
124
114
125
**Principles**:
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
+
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
+
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
+
131
146
**Bad**: "Are you sure?"
132
147
**Good**: "Delete 'Project Alpha'? This can't be undone."
133
148
134
149
**Principles**:
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
+
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
+
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
+
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
-
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
+
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
+13
-2
.agents/skills/colorize/SKILL.md
···
52
52
Add color systematically across these dimensions:
53
53
54
54
### Semantic Color
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
+
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
+
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
-
**Use OKLCH for color**: It's perceptually uniform, meaning equal steps in lightness *look* equal. Great for generating harmonious scales.
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
-
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
+
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.
+35
-3
.agents/skills/delight/SKILL.md
+35
-3
.agents/skills/delight/SKILL.md
···
48
48
Follow these guidelines:
49
49
50
50
### Delight Amplifies, Never Blocks
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
+
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
+
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
+
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
+
81
86
```css
82
87
/* Satisfying button press */
83
88
.button {
84
-
transition: transform 0.1s, box-shadow 0.1s;
89
+
transition:
90
+
transform 0.1s,
91
+
box-shadow 0.1s;
85
92
}
86
93
.button:active {
87
94
transform: translateY(2px);
88
-
box-shadow: 0 2px 4px rgba(0,0,0,0.2);
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
+
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
+
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
+
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
+
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
+
129
141
```
130
142
"No projects"
131
143
"Your canvas awaits. Create something amazing."
···
135
147
```
136
148
137
149
**Playful labels & tooltips**:
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
274
304
- Howler.js (audio management)
275
305
- Use-sound (React hook)
276
306
277
307
**Physics libraries**:
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
+
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
-
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
+
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
+9
-1
.agents/skills/distill/SKILL.md
···
52
52
Systematically remove complexity across these dimensions:
53
53
54
54
### Information Architecture
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
-
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
+
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."
+45
-24
.agents/skills/impeccable/SKILL.md
+45
-24
.agents/skills/impeccable/SKILL.md
···
14
14
Design skills produce generic output without project context. You MUST have confirmed design context before doing any design work.
15
15
16
16
**Required context** (every design skill needs at minimum):
17
+
17
18
- **Target audience**: Who uses this product and in what context?
18
19
- **Use cases**: What jobs are they trying to get done?
19
20
- **Brand personality/tone**: How should the interface feel?
···
23
24
**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.
24
25
25
26
**Gathering order:**
27
+
26
28
1. **Check current instructions (instant)**: If your loaded instructions already contain a **Design Context** section, proceed immediately.
27
29
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.
28
30
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.
···
32
34
## Design Direction
33
35
34
36
Commit to a BOLD aesthetic direction:
37
+
35
38
- **Purpose**: What problem does this interface solve? Who uses it?
36
39
- **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.
37
40
- **Constraints**: Technical requirements (framework, performance, accessibility).
···
40
43
**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work. The key is intentionality, not intensity.
41
44
42
45
Then implement working code that is:
46
+
43
47
- Production-grade and functional
44
48
- Visually striking and memorable
45
49
- Cohesive with a clear aesthetic point-of-view
···
48
52
## Frontend Aesthetics Guidelines
49
53
50
54
### Typography
51
-
→ *Consult [typography reference](reference/typography.md) for OpenType features, web font loading, and the deeper material on scales.*
55
+
56
+
→ _Consult [typography reference](reference/typography.md) for OpenType features, web font loading, and the deeper material on scales._
52
57
53
58
Choose fonts that are beautiful, unique, and interesting. Pair a distinctive display font with a refined body font.
54
59
···
59
64
- 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.
60
65
- 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.
61
66
- Cap line length at ~65-75ch. Body text wider than that is fatiguing.
62
-
</typography_principles>
67
+
</typography_principles>
63
68
64
69
<font_selection_procedure>
65
70
DO THIS BEFORE TYPING ANY FONT NAME.
···
98
103
99
104
Reject every font that appears in the reflex_fonts_to_reject list. They are your training-data defaults and they create monoculture across projects.
100
105
101
-
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.
106
+
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.
102
107
103
108
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.
104
109
</font_selection_procedure>
···
117
122
</typography_rules>
118
123
119
124
### Color & Theme
120
-
→ *Consult [color reference](reference/color-and-contrast.md) for the deeper material on contrast, accessibility, and palette construction.*
125
+
126
+
→ _Consult [color reference](reference/color-and-contrast.md) for the deeper material on contrast, accessibility, and palette construction._
121
127
122
128
Commit to a cohesive palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
123
129
124
130
<color_principles>
125
131
Always apply these — do not consult a reference, just do them:
126
132
127
-
- 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.
133
+
- 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.
128
134
- 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.
129
-
- 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.
130
-
</color_principles>
135
+
- 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.
136
+
</color_principles>
131
137
132
138
<theme_selection>
133
139
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?
···
157
163
</color_rules>
158
164
159
165
### Layout & Space
160
-
→ *Consult [spatial reference](reference/spatial-design.md) for the deeper material on grids, container queries, and optical adjustments.*
166
+
167
+
→ _Consult [spatial reference](reference/spatial-design.md) for the deeper material on grids, container queries, and optical adjustments._
161
168
162
169
Create visual rhythm through varied spacing, not the same padding everywhere. Embrace asymmetry and unexpected compositions. Break the grid intentionally for emphasis.
163
170
···
169
176
- 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.
170
177
- Self-adjusting grid pattern: `grid-template-columns: repeat(auto-fit, minmax(280px, 1fr))` is the breakpoint-free responsive grid for card-style content.
171
178
- 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.
172
-
</spatial_principles>
179
+
</spatial_principles>
173
180
174
181
<spatial_rules>
175
182
DO create visual rhythm through varied spacing: tight groupings, generous separations.
···
191
198
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.
192
199
193
200
BAN 1: Side-stripe borders on cards/list items/callouts/alerts
194
-
- PATTERN: `border-left:` or `border-right:` with width greater than 1px
195
-
- INCLUDES: hard-coded colors AND CSS variables
196
-
- FORBIDDEN: `border-left: 3px solid red`, `border-left: 4px solid #ff0000`, `border-left: 4px solid var(--color-warning)`, `border-left: 5px solid oklch(...)`, etc.
197
-
- 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."
198
-
- 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.
201
+
202
+
- PATTERN: `border-left:` or `border-right:` with width greater than 1px
203
+
- INCLUDES: hard-coded colors AND CSS variables
204
+
- FORBIDDEN: `border-left: 3px solid red`, `border-left: 4px solid #ff0000`, `border-left: 4px solid var(--color-warning)`, `border-left: 5px solid oklch(...)`, etc.
205
+
- 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."
206
+
- 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.
199
207
200
208
BAN 2: Gradient text
201
-
- PATTERN: `background-clip: text` (or `-webkit-background-clip: text`) combined with a gradient background
202
-
- FORBIDDEN: any combination that makes text fill come from a `linear-gradient`, `radial-gradient`, or `conic-gradient`
203
-
- WHY: gradient text is decorative rather than meaningful and is one of the top three AI design tells
204
-
- REWRITE: use a single solid color for text. If you want emphasis, use weight or size, not gradient fill.
205
-
</absolute_bans>
209
+
210
+
- PATTERN: `background-clip: text` (or `-webkit-background-clip: text`) combined with a gradient background
211
+
- FORBIDDEN: any combination that makes text fill come from a `linear-gradient`, `radial-gradient`, or `conic-gradient`
212
+
- WHY: gradient text is decorative rather than meaningful and is one of the top three AI design tells
213
+
- REWRITE: use a single solid color for text. If you want emphasis, use weight or size, not gradient fill.
214
+
</absolute_bans>
206
215
207
216
DO: Use intentional, purposeful decorative elements that reinforce brand.
208
217
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.
···
212
221
DO NOT: Use modals unless there's truly no better alternative. Modals are lazy.
213
222
214
223
### Motion
215
-
→ *Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion.*
224
+
225
+
→ _Consult [motion reference](reference/motion-design.md) for timing, easing, and reduced motion._
216
226
217
227
Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions.
218
228
···
223
233
**DON'T**: Use bounce or elastic easing. They feel dated and tacky; real objects decelerate smoothly
224
234
225
235
### Interaction
226
-
→ *Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns.*
236
+
237
+
→ _Consult [interaction reference](reference/interaction-design.md) for forms, focus, and loading patterns._
227
238
228
239
Make interactions feel fast. Use optimistic UI: update immediately, sync later.
229
240
···
234
245
**DON'T**: Make every button primary. Use ghost buttons, text links, secondary styles; hierarchy matters
235
246
236
247
### Responsive
237
-
→ *Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries.*
248
+
249
+
→ _Consult [responsive reference](reference/responsive-design.md) for mobile-first, fluid design, and container queries._
238
250
239
251
**DO**: Use container queries (@container) for component-level responsiveness
240
252
**DO**: Adapt the interface for different contexts, not just shrink it
241
253
**DON'T**: Hide critical functionality on mobile. Adapt the interface, don't amputate it
242
254
243
255
### UX Writing
244
-
→ *Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states.*
256
+
257
+
→ _Consult [ux-writing reference](reference/ux-writing.md) for labels, errors, and empty states._
245
258
246
259
**DO**: Make every word earn its place
247
260
**DON'T**: Repeat information users can already see
···
296
309
ask the user directly to clarify what you cannot infer. Focus only on what you couldn't infer from the codebase:
297
310
298
311
#### Users & Purpose
312
+
299
313
- Who uses this? What's their context when using it?
300
314
- What job are they trying to get done?
301
315
- What emotions should the interface evoke? (confidence, delight, calm, urgency, etc.)
302
316
303
317
#### Brand & Personality
318
+
304
319
- How would you describe the brand personality in 3 words?
305
320
- Any reference sites or apps that capture the right feel? What specifically about them?
306
321
- What should this explicitly NOT look like? Any anti-references?
307
322
308
323
#### Aesthetic Preferences
324
+
309
325
- Any strong preferences for visual direction? (minimal, bold, elegant, playful, technical, organic, etc.)
310
326
- Light mode, dark mode, or both?
311
327
- Any colors that must be used or avoided?
312
328
313
329
#### Accessibility & Inclusion
330
+
314
331
- Specific accessibility requirements? (WCAG level, known user needs)
315
332
- Considerations for reduced motion, color blindness, or other accommodations?
316
333
···
324
341
## Design Context
325
342
326
343
### Users
344
+
327
345
[Who they are, their context, the job to be done]
328
346
329
347
### Brand Personality
348
+
330
349
[Voice, tone, 3-word personality, emotional goals]
331
350
332
351
### Aesthetic Direction
352
+
333
353
[Visual tone, references, anti-references, theme]
334
354
335
355
### Design Principles
356
+
336
357
[3-5 principles derived from the conversation that should guide all design decisions]
337
358
```
338
359
···
346
367
347
368
## Extract Mode
348
369
349
-
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.
370
+
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
+19
-19
.agents/skills/impeccable/reference/color-and-contrast.md
···
2
2
3
3
## Color Spaces: Use OKLCH
4
4
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
+
**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
-
| Role | Purpose | Example |
26
-
|------|---------|---------|
27
-
| **Primary** | Brand, CTAs, key actions | 1 color, 3-5 shades |
28
-
| **Neutral** | Text, backgrounds, borders | 9-11 shade scale |
25
+
| Role | Purpose | Example |
26
+
| ------------ | ----------------------------- | ------------------------- |
27
+
| **Primary** | Brand, CTAs, key actions | 1 color, 3-5 shades |
28
+
| **Neutral** | Text, backgrounds, borders | 9-11 shade scale |
29
29
| **Semantic** | Success, error, warning, info | 4 colors, 2-3 shades each |
30
-
| **Surface** | Cards, modals, overlays | 2-3 elevation levels |
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
-
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
+
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
-
| Content Type | AA Minimum | AAA Target |
49
-
|--------------|------------|------------|
50
-
| Body text | 4.5:1 | 7:1 |
51
-
| Large text (18px+ or 14px bold) | 3:1 | 4.5:1 |
52
-
| UI components, icons | 3:1 | 4.5:1 |
53
-
| Non-essential decorations | None | None |
48
+
| Content Type | AA Minimum | AAA Target |
49
+
| ------------------------------- | ---------- | ---------- |
50
+
| Body text | 4.5:1 | 7:1 |
51
+
| Large text (18px+ or 14px bold) | 3:1 | 4.5:1 |
52
+
| UI components, icons | 3:1 | 4.5:1 |
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
-
| Light Mode | Dark Mode |
87
-
|------------|-----------|
88
-
| Shadows for depth | Lighter surfaces for depth (no shadows) |
89
-
| Dark text on light | Light text on dark (reduce font weight) |
90
-
| Vibrant accents | Desaturate accents slightly |
91
-
| White backgrounds | Never pure black—use dark gray (oklch 12-18%) |
86
+
| Light Mode | Dark Mode |
87
+
| ------------------ | --------------------------------------------- |
88
+
| Shadows for depth | Lighter surfaces for depth (no shadows) |
89
+
| Dark text on light | Light text on dark (reduce font weight) |
90
+
| Vibrant accents | Desaturate accents slightly |
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
+3
.agents/skills/impeccable/reference/craft.md
···
18
18
- [typography.md](typography.md) for type hierarchy
19
19
20
20
Then add references based on the brief's needs:
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
+
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
+
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
+1
.agents/skills/impeccable/reference/extract.md
+13
-12
.agents/skills/impeccable/reference/interaction-design.md
+13
-12
.agents/skills/impeccable/reference/interaction-design.md
···
4
4
5
5
Every interactive element needs these states designed:
6
6
7
-
| State | When | Visual Treatment |
8
-
|-------|------|------------------|
9
-
| **Default** | At rest | Base styling |
10
-
| **Hover** | Pointer over (not touch) | Subtle lift, color shift |
11
-
| **Focus** | Keyboard/programmatic focus | Visible ring (see below) |
12
-
| **Active** | Being pressed | Pressed in, darker |
13
-
| **Disabled** | Not interactive | Reduced opacity, no pointer |
14
-
| **Loading** | Processing | Spinner, skeleton |
15
-
| **Error** | Invalid state | Red border, icon, message |
16
-
| **Success** | Completed | Green check, confirmation |
7
+
| State | When | Visual Treatment |
8
+
| ------------ | --------------------------- | --------------------------- |
9
+
| **Default** | At rest | Base styling |
10
+
| **Hover** | Pointer over (not touch) | Subtle lift, color shift |
11
+
| **Focus** | Keyboard/programmatic focus | Visible ring (see below) |
12
+
| **Active** | Being pressed | Pressed in, darker |
13
+
| **Disabled** | Not interactive | Reduced opacity, no pointer |
14
+
| **Loading** | Processing | Spinner, skeleton |
15
+
| **Error** | Invalid state | Red border, icon, message |
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
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
-
const dialog = document.querySelector('dialog');
70
-
dialog.showModal(); // Opens with focus trap, closes on Escape
70
+
const dialog = document.querySelector("dialog");
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
+14
-12
.agents/skills/impeccable/reference/motion-design.md
···
4
4
5
5
Timing matters more than easing. These durations feel right for most UI:
6
6
7
-
| Duration | Use Case | Examples |
8
-
|----------|----------|----------|
9
-
| **100-150ms** | Instant feedback | Button press, toggle, color change |
10
-
| **200-300ms** | State changes | Menu open, tooltip, hover states |
11
-
| **300-500ms** | Layout changes | Accordion, modal, drawer |
12
-
| **500-800ms** | Entrance animations | Page load, hero reveals |
7
+
| Duration | Use Case | Examples |
8
+
| ------------- | ------------------- | ---------------------------------- |
9
+
| **100-150ms** | Instant feedback | Button press, toggle, color change |
10
+
| **200-300ms** | State changes | Menu open, tooltip, hover states |
11
+
| **300-500ms** | Layout changes | Accordion, modal, drawer |
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
-
| Curve | Use For | CSS |
21
-
|-------|---------|-----|
22
-
| **ease-out** | Elements entering | `cubic-bezier(0.16, 1, 0.3, 1)` |
23
-
| **ease-in** | Elements leaving | `cubic-bezier(0.7, 0, 0.84, 0)` |
20
+
| Curve | Use For | CSS |
21
+
| --------------- | ---------------------------- | -------------------------------- |
22
+
| **ease-out** | Elements entering | `cubic-bezier(0.16, 1, 0.3, 1)` |
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
-
animation: fade-in 200ms ease-out; /* Crossfade instead of motion */
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
-
*, *::before, *::after {
68
+
*,
69
+
*::before,
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
+20
-14
.agents/skills/impeccable/reference/responsive-design.md
···
15
15
```css
16
16
/* Fine pointer (mouse, trackpad) */
17
17
@media (pointer: fine) {
18
-
.button { padding: 8px 16px; }
18
+
.button {
19
+
padding: 8px 16px;
20
+
}
19
21
}
20
22
21
23
/* Coarse pointer (touch, stylus) */
22
24
@media (pointer: coarse) {
23
-
.button { padding: 12px 20px; } /* Larger touch target */
25
+
.button {
26
+
padding: 12px 20px;
27
+
} /* Larger touch target */
24
28
}
25
29
26
30
/* Device supports hover */
27
31
@media (hover: hover) {
28
-
.card:hover { transform: translateY(-2px); }
32
+
.card:hover {
33
+
transform: translateY(-2px);
34
+
}
29
35
}
30
36
31
37
/* Device doesn't support hover (touch) */
32
38
@media (hover: none) {
33
-
.card { /* No hover state - use active instead */ }
39
+
.card {
40
+
/* No hover state - use active instead */
41
+
}
34
42
}
35
43
```
36
44
···
55
63
```
56
64
57
65
**Enable viewport-fit** in your meta tag:
66
+
58
67
```html
59
-
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
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
-
srcset="
70
-
hero-400.jpg 400w,
71
-
hero-800.jpg 800w,
72
-
hero-1200.jpg 1200w
73
-
"
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
-
>
81
+
/>
77
82
```
78
83
79
84
**How it works**:
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
-
<source media="(min-width: 768px)" srcset="wide.jpg">
91
-
<source media="(max-width: 767px)" srcset="tall.jpg">
92
-
<img src="fallback.jpg" alt="...">
96
+
<source media="(min-width: 768px)" srcset="wide.jpg" />
97
+
<source media="(max-width: 767px)" srcset="tall.jpg" />
98
+
<img src="fallback.jpg" alt="..." />
93
99
</picture>
94
100
```
95
101
+11
-10
.agents/skills/impeccable/reference/spatial-design.md
+11
-10
.agents/skills/impeccable/reference/spatial-design.md
···
21
21
### The Squint Test
22
22
23
23
Blur your eyes (or screenshot and blur). Can you still identify:
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
-
| Tool | Strong Hierarchy | Weak Hierarchy |
35
-
|------|------------------|----------------|
36
-
| **Size** | 3:1 ratio or more | <2:1 ratio |
37
-
| **Weight** | Bold vs Regular | Medium vs Regular |
38
-
| **Color** | High contrast | Similar tones |
39
-
| **Position** | Top/left (primary) | Bottom/right |
40
-
| **Space** | Surrounded by white space | Crowded |
35
+
| Tool | Strong Hierarchy | Weak Hierarchy |
36
+
| ------------ | ------------------------- | ----------------- |
37
+
| **Size** | 3:1 ratio or more | <2:1 ratio |
38
+
| **Weight** | Bold vs Regular | Medium vs Regular |
39
+
| **Color** | High contrast | Similar tones |
40
+
| **Position** | Top/left (primary) | Bottom/right |
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
-
width: 24px; /* Visual size */
83
+
width: 24px; /* Visual size */
83
84
height: 24px;
84
85
position: relative;
85
86
}
86
87
87
88
.icon-button::before {
88
-
content: '';
89
+
content: "";
89
90
position: absolute;
90
-
inset: -10px; /* Expand tap target to 44px */
91
+
inset: -10px; /* Expand tap target to 44px */
91
92
}
92
93
```
93
94
+35
-23
.agents/skills/impeccable/reference/typography.md
+35
-23
.agents/skills/impeccable/reference/typography.md
···
12
12
13
13
**Use fewer sizes with more contrast.** A 5-size system covers most needs:
14
14
15
-
| Role | Typical Ratio | Use Case |
16
-
|------|---------------|----------|
17
-
| xs | 0.75rem | Captions, legal |
18
-
| sm | 0.875rem | Secondary UI, metadata |
19
-
| base | 1rem | Body text |
20
-
| lg | 1.25-1.5rem | Subheadings, lead text |
21
-
| xl+ | 2-4rem | Headlines, hero text |
15
+
| Role | Typical Ratio | Use Case |
16
+
| ---- | ------------- | ---------------------- |
17
+
| xs | 0.75rem | Captions, legal |
18
+
| sm | 0.875rem | Secondary UI, metadata |
19
+
| base | 1rem | Body text |
20
+
| lg | 1.25-1.5rem | Subheadings, lead text |
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
-
**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
+
**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
-
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
+
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
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
+
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
-
font-family: 'CustomFont';
73
-
src: url('font.woff2') format('woff2');
74
+
font-family: "CustomFont";
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
-
font-family: 'CustomFont-Fallback';
80
-
src: local('Arial');
81
-
size-adjust: 105%; /* Scale to match x-height */
82
-
ascent-override: 90%; /* Match ascender height */
83
-
descent-override: 20%; /* Match descender depth */
84
-
line-gap-override: 10%; /* Match line spacing */
81
+
font-family: "CustomFont-Fallback";
82
+
src: local("Arial");
83
+
size-adjust: 105%; /* Scale to match x-height */
84
+
ascent-override: 90%; /* Match ascender height */
85
+
descent-override: 20%; /* Match descender depth */
86
+
line-gap-override: 10%; /* Match line spacing */
85
87
}
86
88
87
89
body {
88
-
font-family: 'CustomFont', 'CustomFont-Fallback', sans-serif;
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
-
.data-table { font-variant-numeric: tabular-nums; }
112
+
.data-table {
113
+
font-variant-numeric: tabular-nums;
114
+
}
111
115
112
116
/* Proper fractions */
113
-
.recipe-amount { font-variant-numeric: diagonal-fractions; }
117
+
.recipe-amount {
118
+
font-variant-numeric: diagonal-fractions;
119
+
}
114
120
115
121
/* Small caps for abbreviations */
116
-
abbr { font-variant-caps: all-small-caps; }
122
+
abbr {
123
+
font-variant-caps: all-small-caps;
124
+
}
117
125
118
126
/* Disable ligatures in code */
119
-
code { font-variant-ligatures: none; }
127
+
code {
128
+
font-variant-ligatures: none;
129
+
}
120
130
121
131
/* Enable kerning (usually on by default, but be explicit) */
122
-
body { font-kerning: normal; }
132
+
body {
133
+
font-kerning: normal;
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
+33
-32
.agents/skills/impeccable/reference/ux-writing.md
···
4
4
5
5
**Never use "OK", "Submit", or "Yes/No".** These are lazy and ambiguous. Use specific verb + object patterns:
6
6
7
-
| Bad | Good | Why |
8
-
|-----|------|-----|
9
-
| OK | Save changes | Says what will happen |
10
-
| Submit | Create account | Outcome-focused |
11
-
| Yes | Delete message | Confirms the action |
12
-
| Cancel | Keep editing | Clarifies what "cancel" means |
13
-
| Click here | Download PDF | Describes the destination |
7
+
| Bad | Good | Why |
8
+
| ---------- | -------------- | ----------------------------- |
9
+
| OK | Save changes | Says what will happen |
10
+
| Submit | Create account | Outcome-focused |
11
+
| Yes | Delete message | Confirms the action |
12
+
| Cancel | Keep editing | Clarifies what "cancel" means |
13
+
| Click here | Download PDF | Describes the destination |
14
14
15
15
**For destructive actions**, name the destruction:
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
-
| Situation | Template |
26
-
|-----------|----------|
27
-
| **Format error** | "[Field] needs to be [format]. Example: [example]" |
28
-
| **Missing required** | "Please enter [what's missing]" |
29
-
| **Permission denied** | "You don't have access to [thing]. [What to do instead]" |
30
-
| **Network error** | "We couldn't reach [thing]. Check your connection and [action]." |
31
-
| **Server error** | "Something went wrong on our end. We're looking into it. [Alternative action]" |
26
+
| Situation | Template |
27
+
| --------------------- | ------------------------------------------------------------------------------ |
28
+
| **Format error** | "[Field] needs to be [format]. Example: [example]" |
29
+
| **Missing required** | "Please enter [what's missing]" |
30
+
| **Permission denied** | "You don't have access to [thing]. [What to do instead]" |
31
+
| **Network error** | "We couldn't reach [thing]. Check your connection and [action]." |
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
-
| Moment | Tone Shift |
47
-
|--------|------------|
48
-
| Success | Celebratory, brief: "Done! Your changes are live." |
49
-
| Error | Empathetic, helpful: "That didn't work. Here's what to try..." |
50
-
| Loading | Reassuring: "Saving your work..." |
51
-
| Destructive confirm | Serious, clear: "Delete this project? This can't be undone." |
47
+
| Moment | Tone Shift |
48
+
| ------------------- | -------------------------------------------------------------- |
49
+
| Success | Celebratory, brief: "Done! Your changes are live." |
50
+
| Error | Empathetic, helpful: "That didn't work. Here's what to try..." |
51
+
| Loading | Reassuring: "Saving your work..." |
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
-
| Language | Expansion |
66
-
|----------|-----------|
67
-
| German | +30% |
68
-
| French | +20% |
69
-
| Finnish | +30-40% |
70
-
| Chinese | -30% (fewer chars, but same width) |
66
+
| Language | Expansion |
67
+
| -------- | ---------------------------------- |
68
+
| German | +30% |
69
+
| French | +20% |
70
+
| Finnish | +30-40% |
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
-
| Inconsistent | Consistent |
81
-
|--------------|------------|
82
-
| Delete / Remove / Trash | Delete |
83
-
| Settings / Preferences / Options | Settings |
84
-
| Sign in / Log in / Enter | Sign in |
85
-
| Create / Add / New | Create |
81
+
| Inconsistent | Consistent |
82
+
| -------------------------------- | ---------- |
83
+
| Delete / Remove / Trash | Delete |
84
+
| Settings / Preferences / Options | Settings |
85
+
| Sign in / Log in / Enter | Sign in |
86
+
| Create / Add / New | Create |
86
87
87
88
Build a terminology glossary and enforce it. Variety creates confusion.
88
89
+45
-25
.agents/skills/impeccable/scripts/cleanup-deprecated.mjs
+45
-25
.agents/skills/impeccable/scripts/cleanup-deprecated.mjs
···
18
18
* 4. Removes the corresponding entries from skills-lock.json.
19
19
*/
20
20
21
-
import { existsSync, readFileSync, writeFileSync, rmSync, readdirSync, statSync, lstatSync, unlinkSync } from 'node:fs';
22
-
import { join, resolve } from 'node:path';
21
+
import {
22
+
existsSync,
23
+
readFileSync,
24
+
writeFileSync,
25
+
rmSync,
26
+
readdirSync,
27
+
statSync,
28
+
lstatSync,
29
+
unlinkSync,
30
+
} from "node:fs";
31
+
import { join, resolve } from "node:path";
23
32
24
33
// Skills that were renamed, merged, or folded in v2.0 and v2.1.
25
34
const DEPRECATED_NAMES = [
26
-
'frontend-design', // renamed to impeccable (v2.0)
27
-
'teach-impeccable', // folded into /impeccable teach (v2.0)
28
-
'arrange', // renamed to layout (v2.1)
29
-
'normalize', // merged into polish (v2.1)
30
-
'onboard', // merged into harden (v2.1)
31
-
'extract', // merged into /impeccable extract (v2.1)
35
+
"frontend-design", // renamed to impeccable (v2.0)
36
+
"teach-impeccable", // folded into /impeccable teach (v2.0)
37
+
"arrange", // renamed to layout (v2.1)
38
+
"normalize", // merged into polish (v2.1)
39
+
"onboard", // merged into harden (v2.1)
40
+
"extract", // merged into /impeccable extract (v2.1)
32
41
];
33
42
34
43
// All known harness directories that may contain a skills/ subfolder.
35
44
const HARNESS_DIRS = [
36
-
'.claude', '.cursor', '.gemini', '.codex', '.agents',
37
-
'.trae', '.trae-cn', '.pi', '.opencode', '.kiro', '.rovodev',
45
+
".claude",
46
+
".cursor",
47
+
".gemini",
48
+
".codex",
49
+
".agents",
50
+
".trae",
51
+
".trae-cn",
52
+
".pi",
53
+
".opencode",
54
+
".kiro",
55
+
".rovodev",
38
56
];
39
57
40
58
/**
···
43
61
*/
44
62
export function findProjectRoot(startDir = process.cwd()) {
45
63
let dir = resolve(startDir);
46
-
const { root } = { root: '/' };
64
+
const { root } = { root: "/" };
47
65
while (dir !== root) {
48
66
if (
49
-
existsSync(join(dir, 'package.json')) ||
50
-
existsSync(join(dir, '.git')) ||
51
-
existsSync(join(dir, 'skills-lock.json'))
67
+
existsSync(join(dir, "package.json")) ||
68
+
existsSync(join(dir, ".git")) ||
69
+
existsSync(join(dir, "skills-lock.json"))
52
70
) {
53
71
return dir;
54
72
}
55
-
const parent = resolve(dir, '..');
73
+
const parent = resolve(dir, "..");
56
74
if (parent === dir) break;
57
75
dir = parent;
58
76
}
···
65
83
* Returns false for non-existent paths or skills that don't match.
66
84
*/
67
85
export function isImpeccableSkill(skillDir) {
68
-
const skillMd = join(skillDir, 'SKILL.md');
86
+
const skillMd = join(skillDir, "SKILL.md");
69
87
if (!existsSync(skillMd)) return false;
70
88
try {
71
-
const content = readFileSync(skillMd, 'utf-8');
89
+
const content = readFileSync(skillMd, "utf-8");
72
90
return /impeccable/i.test(content);
73
91
} catch {
74
92
return false;
···
95
113
export function findSkillsDirs(projectRoot) {
96
114
const dirs = [];
97
115
for (const harness of HARNESS_DIRS) {
98
-
const candidate = join(projectRoot, harness, 'skills');
116
+
const candidate = join(projectRoot, harness, "skills");
99
117
if (existsSync(candidate)) {
100
118
dirs.push(candidate);
101
119
}
···
154
172
* Returns the list of removed skill names.
155
173
*/
156
174
export function cleanSkillsLock(projectRoot) {
157
-
const lockPath = join(projectRoot, 'skills-lock.json');
175
+
const lockPath = join(projectRoot, "skills-lock.json");
158
176
if (!existsSync(lockPath)) return [];
159
177
160
178
let lock;
161
179
try {
162
-
lock = JSON.parse(readFileSync(lockPath, 'utf-8'));
180
+
lock = JSON.parse(readFileSync(lockPath, "utf-8"));
163
181
} catch {
164
182
return [];
165
183
}
166
184
167
-
if (!lock.skills || typeof lock.skills !== 'object') return [];
185
+
if (!lock.skills || typeof lock.skills !== "object") return [];
168
186
169
187
const targets = buildTargetNames();
170
188
const removed = [];
···
173
191
const entry = lock.skills[name];
174
192
if (!entry) continue;
175
193
// Only remove if it belongs to impeccable
176
-
if (entry.source === 'pbakaus/impeccable') {
194
+
if (entry.source === "pbakaus/impeccable") {
177
195
delete lock.skills[name];
178
196
removed.push(name);
179
197
}
180
198
}
181
199
182
200
if (removed.length > 0) {
183
-
writeFileSync(lockPath, JSON.stringify(lock, null, 2) + '\n', 'utf-8');
201
+
writeFileSync(lockPath, JSON.stringify(lock, null, 2) + "\n", "utf-8");
184
202
}
185
203
186
204
return removed;
···
200
218
if (process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname)) {
201
219
const result = cleanup();
202
220
if (result.deletedPaths.length === 0 && result.removedLockEntries.length === 0) {
203
-
console.log('No deprecated Impeccable skills found. Nothing to clean up.');
221
+
console.log("No deprecated Impeccable skills found. Nothing to clean up.");
204
222
} else {
205
223
if (result.deletedPaths.length > 0) {
206
224
console.log(`Removed ${result.deletedPaths.length} deprecated skill(s):`);
207
225
for (const p of result.deletedPaths) console.log(` - ${p}`);
208
226
}
209
227
if (result.removedLockEntries.length > 0) {
210
-
console.log(`Cleaned ${result.removedLockEntries.length} entry/entries from skills-lock.json:`);
228
+
console.log(
229
+
`Cleaned ${result.removedLockEntries.length} entry/entries from skills-lock.json:`,
230
+
);
211
231
for (const name of result.removedLockEntries) console.log(` - ${name}`);
212
232
}
213
233
}
+2
-1
.agents/skills/layout/SKILL.md
+2
-1
.agents/skills/layout/SKILL.md
···
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
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
-
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
+
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
+31
-9
.agents/skills/optimize/SKILL.md
···
34
34
### Loading Performance
35
35
36
36
**Optimize Images**:
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
-
<img
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
+
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
-
const HeavyChart = lazy(() => import('./HeavyChart'));
65
+
const HeavyChart = lazy(() => import("./HeavyChart"));
64
66
```
65
67
66
68
**Optimize CSS**:
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
+
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
-
font-family: 'CustomFont';
82
-
src: url('/fonts/custom.woff2') format('woff2');
85
+
font-family: "CustomFont";
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
+
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
+
98
104
```javascript
99
105
// ❌ Bad: Alternating reads and writes (causes reflows)
100
-
elements.forEach(el => {
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
-
const heights = elements.map(el => el.offsetHeight); // All reads
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
+
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
+
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
+
128
137
```css
129
138
/* ✅ GPU-accelerated (fast) */
130
139
.animated {
···
140
149
```
141
150
142
151
**Smooth 60fps**:
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
+
150
161
```javascript
151
162
// Efficiently detect when elements enter viewport
152
163
const observer = new IntersectionObserver((entries) => {
153
-
entries.forEach(entry => {
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
-
- **User perception**: Does it *feel* faster?
286
+
- **User perception**: Does it _feel_ faster?
265
287
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
+
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
+21
-4
.agents/skills/overdrive/SKILL.md
···
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
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
+
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
-
.hero { animation-timeline: scroll(); }
115
+
.hero {
116
+
animation-timeline: scroll();
117
+
}
105
118
}
106
119
```
107
120
108
121
```javascript
109
-
if ('gpu' in navigator) { /* WebGPU */ }
110
-
else if (canvas.getContext('webgl2')) { /* WebGL2 fallback */ }
122
+
if ("gpu" in navigator) {
123
+
/* WebGPU */
124
+
} else if (canvas.getContext("webgl2")) {
125
+
/* WebGL2 fallback */
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
+
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
-
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
+
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
+3
-1
.agents/skills/polish/SKILL.md
···
57
57
- **Grid adherence**: Elements snap to baseline grid
58
58
59
59
**Check**:
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
+
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
-
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
+
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
+7
-1
.agents/skills/quieter/SKILL.md
···
52
52
Systematically reduce intensity across these dimensions:
53
53
54
54
### Color Refinement
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
+
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
+
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
+
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
+
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
+
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
-
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
+
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
+6
-1
.agents/skills/shape/SKILL.md
···
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
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
+
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
+
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
+
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
+
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
-
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
+
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
+4
-1
.agents/skills/typeset/SKILL.md
···
61
61
### Font Selection
62
62
63
63
If fonts need replacing:
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
+
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
+
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
-
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
+
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.