Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions plugins/design-skills/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,16 @@ Third-party design skills, copied here so they install with the rest of lippstac

| Skill | Source | What it does |
| :- | :- | :- |
| `apple-design` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/apple-design) @ `5206a95` | Apple's approach to interface design and physical motion, for the web: springs, gestures, sheets, materials, type. |
| `review-animations` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/review-animations) @ `5206a95` | Reviews motion code against a high bar. Flags by default; approval is earned. |
| `break-ui` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/break-ui) @ `5206a95` | Feeds a component worst-case data (long names, empty lists, huge numbers, emoji) behind a toggle and reports what broke, with fixes. |
| `prototype` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/prototype) @ `5206a95` | Builds several genuinely different versions of a UI piece behind a live picker so you choose one. Only runs when called by name. |
| `animation-performance` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/animation-performance) @ `5206a95` | Finds why an animation drops frames and fixes it: composite-only properties, CSS vs WAAPI vs rAF, Framer Motion's accelerated path, React re-renders per frame, `will-change`. |
| `animate` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/animate) @ `5206a95` | Builds one animation in the order that decides whether it feels right: should it move at all, purpose, easing, duration, origin. The other motion skills hand easing and timing to it. |
| `choreograph` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/choreograph) @ `5206a95` | Coordinates several elements moving together: order, overlap, stagger and what stays still, so a group reads as one motion. |
| `gestures` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/gestures) @ `5206a95` | Drag, swipe and sheet interactions that follow the finger 1:1 and can be caught mid-animation. Points to Vaul for drawers. |
| `remove-animations` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/remove-animations) @ `5206a95` | Finds motion the interface doesn't need (keyboard actions, high-frequency surfaces, decoration) and deletes it. Only subtracts. |
| `hallmark` | [nutlope/hallmark](https://github.com/nutlope/hallmark) @ `407fa68` (2.0.0) | Pushes generated pages away from the generic AI look: a fixed floor of rules, a dealt theme, and a lint script (`sloplint`, needs Node) that must pass before it hands back. Builds from the real product when it can capture it. Verbs `audit` and `redesign`. |
| `apple-design` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/apple-design) @ `64eb3de` | Apple's approach to interface design and physical motion, for the web: springs, gestures, sheets, materials, type. |
| `review-animations` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/review-animations) @ `64eb3de` | Reviews motion code against a high bar. Flags by default; approval is earned. |
| `break-ui` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/break-ui) @ `64eb3de` | Feeds a component worst-case data (long names, empty lists, huge numbers, emoji) behind a toggle and reports what broke, with fixes. |
| `prototype` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/prototype) @ `64eb3de` | Builds several genuinely different versions of a UI piece behind a live picker so you choose one. Only runs when called by name. |
| `animation-performance` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/animation-performance) @ `64eb3de` | Finds why an animation drops frames and fixes it: composite-only properties, CSS vs WAAPI vs rAF, Framer Motion's accelerated path, React re-renders per frame, `will-change`. |
| `animate` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/animate) @ `64eb3de` | Builds one animation in the order that decides whether it feels right: should it move at all, purpose, easing, duration, origin. The other motion skills hand easing and timing to it. |
| `choreograph` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/choreograph) @ `64eb3de` | Coordinates several elements moving together: order, overlap, stagger and what stays still, so a group reads as one motion. |
| `gestures` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/gestures) @ `64eb3de` | Drag, swipe and sheet interactions that follow the finger 1:1 and can be caught mid-animation. Points to Vaul for drawers. |
| `remove-animations` | [emilkowalski/skills](https://github.com/emilkowalski/skills/tree/main/skills/remove-animations) @ `64eb3de` | Finds motion the interface doesn't need (keyboard actions, high-frequency surfaces, decoration) and deletes it. Only subtracts. |
| `hallmark` | [nutlope/hallmark](https://github.com/nutlope/hallmark) @ `04977e1` (2.0.0) | Pushes generated pages away from the generic AI look: a fixed floor of rules, a dealt theme, and a lint script (`sloplint`, needs Node) that must pass before it hands back. Builds from the real product when it can capture it. Verbs `audit` and `redesign`. |

## Install

Expand Down
6 changes: 3 additions & 3 deletions plugins/design-skills/skills/animate/RECIPES.md
Original file line number Diff line number Diff line change
Expand Up @@ -169,7 +169,7 @@ Keep it short — this is one of the few animations that costs layout on every f

## Stagger a group entrance

For a list or grid the user sees occasionally — not for a list they scroll past all day.
For a list or grid the user sees occasionally — not for a list they scroll past all day. For group entrances, follow `../choreograph/SKILL.md` (one entrance per container, non-uniform delays).

```css
.item {
Expand All @@ -179,8 +179,8 @@ For a list or grid the user sees occasionally — not for a list they scroll pas
}

.item:nth-child(2) { animation-delay: 50ms; }
.item:nth-child(3) { animation-delay: 100ms; }
.item:nth-child(4) { animation-delay: 150ms; }
.item:nth-child(3) { animation-delay: 90ms; }
.item:nth-child(4) { animation-delay: 120ms; }

@keyframes fadeIn {
to {
Expand Down
14 changes: 8 additions & 6 deletions plugins/design-skills/skills/animate/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Never present motion options as a menu. Make the call, state the reasoning in on
## Hard Rules

1. **Run the sequence in order.** Steps 1 and 2 gate everything. Don't reach for a curve before you know whether it animates at all.
2. **No approximated values.** Every curve, duration, and spring config comes from the tables below. Never invent `cubic-bezier(0.4, 0, 0.2, 1)` because it looks familiar.
2. **No approximated values.** Every curve, duration, and spring config comes from the codebase's existing tokens or the tables below. Never invent `cubic-bezier(0.4, 0, 0.2, 1)` because it looks familiar.
3. **Extend the codebase's tokens, don't fork them.** If `--ease-out` or a duration scale already exists, use it. Adding a parallel system is a defect.
4. **Reduced motion and hover gating ship with the animation**, not as a follow-up.
5. **Cheapest tool that works.** Don't install a motion library for a fade.
Expand Down Expand Up @@ -72,13 +72,13 @@ Walk down; stop at the first that fits.
| --- | --- |
| Hover, press, color, a state toggle you control with a class or attribute | **CSS transition** |
| Entry animation on mount, no JS state | **CSS `@starting-style`** |
| Predetermined motion that must stay smooth while the page is busy loading | **CSS animation** (runs off the main thread) |
| Predetermined motion that must stay smooth while the page is busy loading | **CSS animation** (`transform`/`opacity` run on the compositor) |
| Programmatic control with CSS performance, no library | **WAAPI** (`element.animate()`) |
| Springs, layout animations, exit animations, gesture-driven values | **Motion** (`motion.dev`) |

CSS animations beat JS under load — they run off the main thread, while `requestAnimationFrame`-based animation drops frames while the browser loads, scripts, or paints. Use CSS for predetermined motion, JS for dynamic and interruptible motion.
CSS animations beat JS under load — on `transform`/`opacity` they run on the compositor, while `requestAnimationFrame`-based animation drops frames while the browser loads, scripts, or paints. Use CSS for predetermined motion, JS for dynamic and interruptible motion.

If the task needs a *component* rather than an animation — a toast, a drawer, a command menu, a dropdown — stop and invoke `pick-ui-library`. Hand-rolling those is how you end up with a `<div>` dropdown and no focus management.
If the task needs a *component* rather than an animation — a toast, a drawer, a command menu, a dropdown — stop and read `../pick-ui-library/SKILL.md` to pick one. Hand-rolling those is how you end up with a `<div>` dropdown and no focus management.

### 4. Pick the properties

Expand Down Expand Up @@ -129,7 +129,7 @@ Need a curve that isn't here? Take it from [easing.dev](https://easing.dev/) or
| Modals, drawers | 200–500ms |
| Marketing / explanatory | Can be longer |

**UI animations stay under 300ms.** A 180ms dropdown feels more responsive than a 400ms one.
**UI animations stay under 300ms. Modals, drawers, sheets, and toasts are the documented exceptions.** A 180ms dropdown feels more responsive than a 400ms one.

**Reach for a spring instead** when the motion is drag with momentum, an element that should feel alive, a gesture the user can interrupt or reverse, or decorative mouse-tracking:

Expand All @@ -153,9 +153,11 @@ Ships with the animation, every time.

```css
@media (prefers-reduced-motion: reduce) {
.element { animation: fade 0.2s ease; } /* keep opacity/color, drop transform-based motion */
.element { animation-name: fade; } /* same timing, opacity only — drop transform-based motion */
}

@keyframes fade { from { opacity: 0; } }

@media (hover: hover) and (pointer: fine) {
.element:hover { transform: scale(1.05); } /* touch fires false hovers on tap */
}
Expand Down
14 changes: 7 additions & 7 deletions plugins/design-skills/skills/animation-performance/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: animation-performance
description: Keep web animations inside the frame budget — animate composite-only properties, keep motion off the main thread when the page is busy, and find the cause when an animation drops frames. Covers the layout/paint/composite pipeline, cheaper property swaps, CSS vs WAAPI vs requestAnimationFrame, Motion's hardware-accelerated path, React re-rendering per frame, inherited CSS variable recalculation, blur cost, and when `will-change` actually helps. Use when an animation is janky, choppy, stutters, or drops frames; when choosing which property to animate; when deciding between CSS and JS animation on performance grounds; or when reaching for `will-change` or GPU layers. For choosing easing, duration, or whether to animate at all use animate; for reviewing motion as a whole use review-animations.
description: Keep web animations inside the frame budget — animate composite-only properties, keep motion off the main thread when the page is busy, and find the cause when an animation drops frames. Use when an animation is janky, choppy, stutters, or drops frames; when choosing which property to animate; when deciding between CSS and JS animation on performance grounds; or when reaching for `will-change` or GPU layers. For choosing easing, duration, or whether to animate at all use animate; for reviewing motion as a whole use review-animations.
---

# Animation Performance
Expand Down Expand Up @@ -43,7 +43,7 @@ Start here. Match what the user is seeing, then read the matching section.
| Problem | Solution |
| --- | --- |
| Animation stutters | Animate `transform`/`opacity`, not `width`/`height`/`top`/`margin` |
| Shadow animation is choppy | `filter: drop-shadow()` |
| Shadow animation is choppy | `filter: drop-shadow()` (composited in Chrome; measure elsewhere) |
| Jank only during navigation or loading | Move the animation to CSS or WAAPI so it runs off the main thread |
| Motion `x`/`y` drops frames | Upgrade to `motion` 14.2+, or animate the full `transform` string |
| Hand-rolled animation drops frames in React | Write to `ref.current.style`, not state |
Expand Down Expand Up @@ -75,26 +75,26 @@ Every property enters this pipeline at one of three points, and the cost differs

| Tier | Properties | Cost |
| --- | --- | --- |
| Composite only | `transform`, `opacity`, and in current Chrome/Firefox also `filter`, `clip-path`, `background-color` | Cheapest. Browsers promote these to their own layer. |
| Composite only | `transform`, `opacity` | Cheapest. Browsers promote these to their own layer. |
| Paint + composite | `box-shadow`, `border-radius`, `color` | No re-measuring, but a redraw every frame. |
| Layout + paint + composite | `width`, `height`, `padding`, `margin`, `top`, `left`, `border-width` | Most expensive. One growing element can move everything around it. |

`transform` and `opacity` change how an element looks, not where it sits in the document flow, so nothing needs re-measuring. Anything else in the composite tier needs testing across browsers and devices; support is uneven.
`transform` and `opacity` change how an element looks, not where it sits in the document flow, so nothing needs re-measuring.

**Swapping down a tier:**

| Instead of | Animate |
| --- | --- |
| `width` / `height` / `padding` to grow or shrink | `scale()` |
| `top` / `left` / `margin` to move | `translate()` (percentages are relative to the element's own size) |
| `display` / `visibility` swaps | `opacity` |
| `box-shadow` | `filter: drop-shadow(…)` |
| `display` / `visibility` swaps | `opacity`, then `visibility: hidden` once it ends so it stops taking clicks |
| `box-shadow` | `filter: drop-shadow(…)` (Chrome composites `filter`; other engines may repaint, so measure) |

The last one is the one people miss. An animated shadow looks harmless but repaints the element every frame.

Two things follow:

- **Layout animations don't always drop frames.** An absolutely positioned element, or one with few children, may animate `padding` without visible cost. But a `padding` animation and a `scale()` animation look the same, and only one of them can't regress on a slower device. Pick the one with no downside.
- **Layout animations don't always drop frames.** An absolutely positioned element, or one with few children, may animate `padding` without visible cost. But when `scale()` gives the look you want (it scales children too and keeps the layout space), only it can't regress on a slower device. Pick it.
- **Layout properties also move the wrong things.** Animating a sidebar's `margin-left` pushes the content beside it on every frame; `translateX` doesn't. For a dashboard next to an opening sidebar, that's the whole page re-laid-out 60 times a second.

## Where It Runs
Expand Down
9 changes: 3 additions & 6 deletions plugins/design-skills/skills/apple-design/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ Apple deliberately replaced the physics triplet (mass/stiffness/damping) with tw
| Rotation | `0.8` | `0.4` |
| Drawer / sheet | `0.8` | `0.3` |

**Web mapping (Motion / Framer Motion):** the `bounce` + `duration` spring API maps closely to Apple's damping + response. A safe house style is `damping: 1.0` springs everywhere by default; reserve bounce for momentum-driven, physical interactions.
**Web mapping (Motion / Framer Motion):** the `bounce` + `duration` spring API maps closely to Apple's damping + response. A safe house style is `bounce: 0` springs everywhere by default (Motion's `damping` is a physics coefficient, not Apple's damping ratio); reserve bounce for momentum-driven, physical interactions.

```js
import { animate } from 'motion';
Expand Down Expand Up @@ -144,7 +144,6 @@ Note: the physics-textbook `v²/(2·decel)` is *not* what Apple ships — use th
- **Enter and exit along the same path.** A panel that slides in from the right must dismiss to the right. In-from-right / out-the-bottom feels disconnected and confusing.
- **Anchor interactions to their source.** A menu, popover, or sheet should originate from the element that triggered it — set `transform-origin` to the trigger, so the spatial relationship between button and content is obvious. (This is the same origin-awareness point as popovers scaling from their trigger, not their center.)
- **Mirror the easing on reversible transitions** so the outbound path matches the return path (use inverse cubic-bézier control points for the two directions).

## 8. Hint in the direction of the gesture

Expand Down Expand Up @@ -172,9 +171,8 @@ function rubberband(overshoot, dimension, constant = 0.55) {

Smoothness is about *what's in the frames*, not just the frame rate.

- Keep the per-frame positional change below the perception threshold to avoid strobing.
- For very fast motion, a subtle **motion blur / stretch** encodes speed and reads better than a hard sharp streak.
- `requestAnimationFrame` is the web's display-synced clock (Apple uses `CADisplayLink`). Animate only compositor-friendly properties — `transform` and `opacity` — and hint with `will-change` where motion is imminent.
- `requestAnimationFrame` is the web's display-synced clock (Apple uses `CADisplayLink`). Animate only compositor-friendly properties — `transform` and `opacity` — and add `will-change` only after you measure a shift or dropped frames (see `../animation-performance/SKILL.md`).

## 12. Materials & depth — translucency conveys hierarchy

Expand Down Expand Up @@ -280,8 +278,7 @@ Tactical rules that serve these:
| Flick landing point | Project momentum | `current + (v/1000)·d/(1−d)`, `d ≈ 0.998` |
| Interrupt cleanly | Start from presentation (live) value | read the on-screen transform |
| Avoid reversal "brick wall" | Carry velocity through re-target | spring that blends velocity |
| Reversible transition | Mirror the easing curve | inverse cubic-bézier |
| Decide reverse vs. commit | Use velocity **sign**, not position | at release |
| Decide reverse vs. commit | Snap to the point nearest the projected endpoint | at release |
| 1:1 drag | Pointer Events + capture | respect the grab offset |
| Feedback | On pointer-down, continuous | never only at the end |
| Boundary | Rubber-band, don't hard-stop | progressive resistance |
Expand Down
Loading