reviewer-harness 1.8.0 → 1.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +2 -2
- package/skills/motion-design.md +76 -0
package/package.json
CHANGED
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: motion-design
|
|
3
|
+
description: Animation principles distilled from GSAP (GreenSock) — easing, sequencing, stagger, and performance. Make UI motion feel premium, not flashy. For any task involving CSS/JS animations, transitions, or micro-interactions.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
## Skill: motion-design
|
|
7
|
+
|
|
8
|
+
*Distilled from [GSAP (GreenSock Animation Platform)](https://github.com/greensock/GSAP) — the industry-standard JavaScript animation library (90k+ stars, used on 12M+ sites). Every rule below cites its GSAP source.*
|
|
9
|
+
|
|
10
|
+
When to use: adding animations, transitions, loading states, or micro-interactions to any UI.
|
|
11
|
+
|
|
12
|
+
### 1. Easing is 80% of good animation
|
|
13
|
+
Source: [GSAP Eases docs](https://gsap.com/docs/v3/Eases) — `src/EasePack.js`
|
|
14
|
+
|
|
15
|
+
Linear motion looks robotic. Real objects accelerate and decelerate.
|
|
16
|
+
- **Entrances:** ease-out (`power2.out`, `cubic-bezier(0.22, 1, 0.36, 1)`) — fast start, gentle landing.
|
|
17
|
+
- **Exits:** ease-in (`power2.in`) — gentle start, fast finish.
|
|
18
|
+
- **Never** use linear for UI motion unless it's a continuous loop (spinner, marquee).
|
|
19
|
+
- **Never** use the default `ease` — it's mushy. Pick a deliberate curve.
|
|
20
|
+
|
|
21
|
+
### 2. Sequence with timelines, not delays
|
|
22
|
+
Source: [GSAP Timeline docs](https://gsap.com/docs/v3/GSAP/Timeline) — `src/Timeline.js`
|
|
23
|
+
|
|
24
|
+
Chaining animations with `setTimeout` or CSS `animation-delay` is fragile — one change breaks the chain.
|
|
25
|
+
- Group related animations into a **timeline** (GSAP) or a single orchestrated keyframe sequence (CSS).
|
|
26
|
+
- Each step should start relative to the previous (`"-=0.1"` overlap in GSAP), not at absolute times.
|
|
27
|
+
- If one step is removed, the rest still flow correctly.
|
|
28
|
+
|
|
29
|
+
### 3. Stagger lists — never animate all items at once
|
|
30
|
+
Source: [GSAP Stagger docs](https://gsap.com/docs/v3/Stagger) — core `gsap.to()` stagger feature
|
|
31
|
+
|
|
32
|
+
When multiple items appear (list, cards, menu):
|
|
33
|
+
- Offset each item by 30–80ms (`stagger: 0.05`).
|
|
34
|
+
- Animate from a subtle offset (translateY 8–12px + fade), not from far away.
|
|
35
|
+
- Cap the total stagger time — 10 items × 50ms = 500ms max. Beyond that, batch them.
|
|
36
|
+
|
|
37
|
+
### 4. Animate transform and opacity only
|
|
38
|
+
Source: [GSAP performance docs](https://gsap.com/docs/v3/Plugins/CSSPlugin) — `src/CSSPlugin.js`
|
|
39
|
+
|
|
40
|
+
Animating `width`, `height`, `top`, `left`, or `margin` triggers layout recalculation every frame — janky on low-end devices.
|
|
41
|
+
- **Safe:** `transform` (translate, scale, rotate), `opacity`.
|
|
42
|
+
- **Avoid:** layout properties. If you must animate size, use `transform: scale()` instead.
|
|
43
|
+
- Use `will-change: transform` sparingly — only on elements that animate frequently.
|
|
44
|
+
|
|
45
|
+
### 5. Respect reduced motion
|
|
46
|
+
Source: [gsap.matchMedia() docs](https://gsap.com/docs/v3/GSAP/gsap.matchMedia()) — README highlights accessibility
|
|
47
|
+
|
|
48
|
+
Some users experience motion sickness or vestibular disorders.
|
|
49
|
+
- Wrap all non-essential animation in `@media (prefers-reduced-motion: no-preference)`.
|
|
50
|
+
- Provide a `prefers-reduced-motion: reduce` fallback that disables or minimizes motion.
|
|
51
|
+
- Essential state changes (loading → loaded) must still communicate without animation.
|
|
52
|
+
|
|
53
|
+
### 6. Micro-interactions: fast in, faster out
|
|
54
|
+
Source: general practice (GSAP community conventions)
|
|
55
|
+
|
|
56
|
+
- **Hover:** 150–200ms transition. Feels responsive, not laggy.
|
|
57
|
+
- **Press/active:** 100–150ms + subtle scale (0.97). Confirms the action.
|
|
58
|
+
- **Entrance:** 250–350ms ease-out. Long enough to notice, short enough to not wait.
|
|
59
|
+
- **Exit:** 150–250ms ease-in. Exits should feel snappier than entrances.
|
|
60
|
+
- Anything over 500ms for a UI micro-interaction feels broken.
|
|
61
|
+
|
|
62
|
+
### Quick check before shipping
|
|
63
|
+
- [ ] Easing: deliberate curve, not linear or default `ease`
|
|
64
|
+
- [ ] Lists: staggered, not simultaneous
|
|
65
|
+
- [ ] Properties: transform/opacity only
|
|
66
|
+
- [ ] Durations: hover ≤200ms, entrance ≤350ms, exit ≤250ms
|
|
67
|
+
- [ ] Reduced motion: respected via media query
|
|
68
|
+
- [ ] No layout thrashing (no width/height/top/left animation)
|
|
69
|
+
|
|
70
|
+
### Anti-patterns
|
|
71
|
+
- Linear easing on UI elements (looks robotic).
|
|
72
|
+
- All list items animating simultaneously (visual noise).
|
|
73
|
+
- Animating `width`/`height` (layout thrash).
|
|
74
|
+
- 1-second+ durations on buttons or toggles (feels broken).
|
|
75
|
+
- Ignoring `prefers-reduced-motion` (accessibility failure).
|
|
76
|
+
- Bounce/elastic easings on serious UI (save for playful contexts only).
|