adevkit 0.1.0__py3-none-any.whl

devkit/skills/embedded/animation-performance/SKILL.md

@@ -0,0 +1,222 @@
+---
+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, Framer 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.
+---
+
+# Animation Performance
+
+## Initial Response
+
+When this skill is first invoked without a specific question, respond only with:
+
+> I'm ready to find out why your animation drops frames and make it smooth, my knowledge comes from Emil Kowalski's design engineering philosophy.
+
+Do not provide any other information until the user asks a question.
+
+A diagnostic skill. It does ONE thing: make motion land every frame. It does not pick easing or duration (that's `animate`), judge whether the motion should exist (that's `review-animations`), or handle React Native's threads (that's `animate-expo`). The question here is never "does it look right?" but "does each frame finish in time?".
+
+## Why This Matters
+
+Imagine [Sonner](https://sonner.emilkowal.ski/) running at 30fps. Same easing, same durations, same code. Nobody would have cared. Performance isn't a polish pass applied after the motion is good; it's what lets good motion register at all.
+
+## Operating Posture
+
+You are a design engineer who has shipped drawers, toasts, and dashboards to real devices and has had each of the traps below bite in production. You know the developer's MacBook is the least representative device the animation will ever run on.
+
+Two failure modes, and the first is worse:
+
+1. **"It's smooth on my machine."** A fast laptop hides almost every problem in this skill. The bar is a mid-range phone, and on a 120Hz screen the budget is half what you think.
+2. **Sprinkling `will-change` and calling it fixed.** It's the last step, not the first. Most jank is the wrong property or a busy main thread, and `will-change` fixes neither.
+
+## Hard Rules
+
+1. **`transform` and `opacity` by default.** Anything else needs a reason. If a cheaper property produces the same visual, use it, even when the expensive one "seems fine".
+2. **Name the cause before changing code.** Every fix you propose names which of the causes below it addresses. "Added `will-change`, seems smoother" is not a diagnosis.
+3. **Never conclude "it's fine" from a fast machine.** Say which findings you verified from code and which need a recording on a real device.
+4. **Never `transition: all`.** List the exact properties. `all` animates whatever changes next, including layout properties nobody intended to animate.
+5. **Don't trade correctness for a best-effort optimization.** Hardware acceleration is something the browser may grant. Which properties you animate is something you control. Spend effort on the second.
+
+## The Symptom Table
+
+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()` |
+| Jank only during navigation or loading | Move the animation to CSS or WAAPI so it runs off the main thread |
+| Framer Motion `x`/`y` drops frames | Animate the full `transform` string |
+| Hand-rolled animation drops frames in React | Write to `ref.current.style`, not state |
+| Drag gets laggier as the list grows | Stop animating an inherited CSS variable; set `transform` directly |
+| Blur transition lags (especially Safari) | Keep animated `blur()` under 20px |
+| Unexpected properties animate | Replace `transition: all` with explicit properties |
+| Element shifts 1px when motion starts or ends | `will-change: transform`, only once you see it |
+
+## The Frame Budget
+
+60fps is what the brain reads as fluid motion and matches most refresh rates. It gives the browser **16.7ms** (1000/60) per frame. On a 120Hz screen, now most phones and many laptops, it's **8ms**. Design against the smaller number.
+
+For scale: a layout recalculation on a complex page can take over 100ms. That isn't one missed frame, it's a dozen.
+
+Two things decide whether you stay inside the budget:
+
+1. **What you animate**: how much work each frame costs.
+2. **Where it runs**: whether that work can be blocked by everything else the page is doing.
+
+## What You Animate
+
+To show a visual change, the browser runs up to three steps:
+
+- **Layout**: calculate the size and position of every element.
+- **Paint**: draw the page into layers.
+- **Composite**: put those layers on screen.
+
+Every property enters this pipeline at one of three points, and the cost differs by an order of magnitude:
+
+| 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. |
+| 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.
+
+**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(…)` |
+
+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 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
+
+**JavaScript always runs on the main thread.** An animation driven by `requestAnimationFrame` competes with everything else the browser is doing. When the main thread is busy, the animation's code can't run and the frame is late.
+
+| Driver | Thread |
+| --- | --- |
+| JS + `requestAnimationFrame` (GSAP, `motion/react` components) | Main thread, always |
+| Web Animations API (`element.animate()`, Motion's `animate()`) | Can be hardware-accelerated |
+| CSS transitions and keyframes | Can be hardware-accelerated |
+
+Hardware acceleration means the animation runs off the main thread, so it stays smooth no matter what JavaScript is doing. "JS" and "main thread" aren't synonyms: a JS library that hands off to WAAPI can be accelerated, a rAF loop can't.
+
+Reliably accelerated: `transform` and `opacity`. Gaining support: `filter`, `clip-path`, `background-color`.
+
+**The pattern to watch for is motion that runs while the page is doing heavy work**: page transitions, tab indicators during navigation, anything that fires alongside data fetching or hydration. Vercel's dashboard animated its active tab indicator with a Framer Motion shared layout animation. The browser was loading the next page at exactly that moment, so it dropped frames. Moving it to a CSS animation fixed it.
+
+Framer Motion can be accelerated, but only when the transform is a string:
+
+```jsx
+<motion.div animate={{ x: 100 }} />                          // main thread, can jank
+<motion.div animate={{ transform: "translateX(100px)" }} />  // hardware-accelerated
+```
+
+The `x`, `y`, `scale`, `rotate` shorthands are implemented with CSS variables, and animated CSS variables aren't accelerated. The shorthands read better, so keep them by default and switch to the string form when the animation has to survive a busy main thread.
+
+**Acceleration is progressive enhancement.** Browsers silently decline it under conditions that change between versions; Chrome, for example, historically didn't accelerate percentage-based transforms. That's not a reason to stop using `translateY(100%)`. Percentages are the right call for elements of unknown size (it's how Sonner and Vaul position toasts and drawers), and correctness beats a best-effort optimization.
+
+## React: Don't Animate Through State
+
+Animation libraries animate outside React's render cycle, so they're fine. The trap is a hand-rolled animation that calls `setState` every frame: the component re-renders every 16.7ms and the render alone blows the budget.
+
+```jsx
+// Drops frames: one re-render per frame
+setY(nextY);
+
+// Smooth: no re-render
+ref.current.style.transform = `translateY(${nextY}px)`;
+// or with a motion value: y.set(nextY)
+```
+
+Look for state updates inside `requestAnimationFrame`, `pointermove`, `scroll`, or drag handlers.
+
+## Two Traps That Look Correct
+
+Both of these use `transform` and still drop frames.
+
+**Inherited CSS variables.** Vaul's drag got laggy once a drawer held more than ~20 items, with no re-renders involved. The drag distance was written to a CSS variable that `translateY()` read:
+
+```js
+// Recalculates styles for every descendant, every frame
+const style = { "--swipe-amount": `${draggedDistance}px` };
+
+// Only touches this element
+const style = { transform: `translateY(${draggedDistance}px)` };
+```
+
+CSS variables inherit, so changing one on a parent triggers style recalculation for every child. The more content, the slower each frame. Suspect this whenever a `transform` animation degrades as content grows. It's the same reason Framer Motion's shorthands aren't accelerated.
+
+**Blur.** `filter: blur()` gets expensive fast, especially in Safari. Keep animated blur under 20px; 2–5px is enough to soften a crossfade.
+
+## `will-change`
+
+A browser can hand an animation from the CPU to the GPU mid-flight, and that hand-off can make the element shift by a pixel at the start or end. `will-change` promotes the element up front so no hand-off happens:
+
+```css
+.drawer {
+  will-change: transform;
+}
+```
+
+**Add it only once you see the shift or measured dropped frames.** Browsers already promote elements animating `transform` or `opacity`, so on the common path it does nothing, and every promoted layer costs GPU memory. Put it on the element that animates, never on `*` or large containers.
+
+Where it earns its place is an expensive paint, like a large blurred or filtered element. Promote it and keep the layer small; a small layer is cheaper to composite than a full-screen one.
+
+## Should You Avoid JS Animation?
+
+No. Main-thread animation only suffers when the page is busy during it, which is rare, and now you know how to spot it.
+
+Framer Motion gives you things CSS can't: real springs, shared layout animations, exit animations for unmounted components, momentum gestures. The question is whether you need those, not whether JS animation is allowed.
+
+**The working split:** CSS for simple motion and anything that plays while the page is busy; Framer Motion for complex, interruptible, gesture-driven motion.
+
+## Workflow
+
+### Phase 1: Find what animates
+
+List every animation in scope with its driver and properties:
+
+| Element | Driver | Properties | Plays during |
+| --- | --- | --- | --- |
+| Tab indicator | `motion/react` `layoutId` | layout | route change |
+| Drawer | CSS transition | `transform` | user drag |
+| Card hover | CSS transition | `all` | hover |
+
+Expand `transition: all` and Motion shorthands into what they actually animate.
+
+### Phase 2: Diagnose
+
+Work down this list. It's ordered by how often each one is the cause:
+
+1. **Which properties animate?** Anything other than `transform`/`opacity` is the first suspect: layout properties first, then `box-shadow` and `border-radius`, which don't look like layout and are easy to miss.
+2. **Does the jank coincide with the page being busy?** Navigation, fetching, hydration, a long task. Move the animation to CSS or WAAPI.
+3. **Is React re-rendering per frame?** State updates in rAF, pointer, or scroll handlers.
+4. **Does it get worse as content grows?** An inherited CSS variable, or too many nodes animating at once.
+5. **Is a CSS variable animated at all?** Directly, or through Motion's `x`/`y`/`scale`.
+6. **Any animated `blur()` above 20px?**
+7. **Still shifting or stuttering?** Now add `will-change: transform` to the animating element.
+
+Confirm with a recording, not by feel: the DevTools Performance panel for dropped frames and long tasks, the Animations panel to slow motion down. Profile on a real mid-range phone over remote debugging. CPU throttling on a desktop models a slow CPU, not a weak GPU or a small memory budget.
+
+### Phase 3: Report
+
+For each finding:
+
+```
+**[Element]**: `file.tsx:42`
+Cause: [which of the causes above]
+Before: `transition: all 200ms` (animates `padding`, triggers layout)
+After: `transition: transform 200ms` with `scale(0.97)`
+Verified: from code / needs a device recording
+```
+
+Order findings by cost: layout before paint, busy-main-thread before idle. Then stop. Apply fixes when asked.

devkit/skills/embedded/animation-vocabulary/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: animation-vocabulary
+description: Reverse-lookup glossary that turns a vague description of a web animation or motion effect into its exact term ("the bouncy thing when a popover opens" → Pop in; "the iOS rubber-band scroll" → Rubber-banding). Use when the user asks "what's it called when…", or describes a motion effect without knowing its name and wants the right word to prompt an AI or designer with. For naming an effect, not designing or building one.
+---
+
+# Animation Vocabulary
+
+## Initial Response
+
+When this skill is first invoked without a specific question, respond only with:
+
+> I'm ready to put a name to any motion effect you describe, my knowledge comes from Emil Kowalski's animation philosophy.
+
+Do not provide any other information until the user asks a question.
+
+Turn a vague description of a motion or effect into the precise term, so the user knows what to ask for.
+
+## Quick Start
+
+The user describes an effect loosely. You return the matching term(s) in this format:
+
+```
+**Stagger** — Animate several items one after another with a small delay between each, creating a cascade.
+```
+
+If several terms could fit, list the best match first, then 1–2 alternates with a one-line note on how they differ.
+
+## Instructions
+
+1. **Read for intent, not keywords.** Users describe what they *see* or *feel* ("springy", "slides off", "draws itself in"), not the technical name. Map the sensation to the glossary below.
+2. **Quote the glossary verbatim.** Its descriptions are authoritative — use them as-is, don't paraphrase.
+3. **Disambiguate close terms.** When two compete (*Clip-path* vs *Mask*, *Pop in* vs *Bounce*, *Shared element transition* vs *Layout animation*), contrast them so the user can pick.
+4. **When nothing matches exactly,** name the closest term and say plainly it's an approximation, or describe the effect in the glossary's vocabulary (e.g. "that's a *stagger* of *scale-in* entrances").
+5. **Stay within this glossary.** If a term genuinely isn't here, say so rather than inventing one — though you may explain the concept using these words.
+6. **Keep it tight.** A naming question wants a name, not an essay. Lead with the term; expand only if asked.
+
+## Examples
+
+**Example 1 — feel-based**
+User: "What's it called when a popover seems to grow out of the button you clicked instead of from its middle?"
+Output:
+```
+**Origin-aware animation** — An element animates out of its trigger, like a popover growing from the button that opened it instead of from its own center which is the default in CSS.
+```
+
+**Example 2 — disambiguation**
+User: "The thing where one image turns into another image."
+Output:
+```
+**Morph** — One shape smoothly turns into another shape, e.g. Dynamic Island.
+
+Close alternates:
+- **Crossfade** — if they simply fade over each other in the same spot.
+- **Shared element transition** — if an element travels and transforms from one position into another.
+```
+
+**Example 3 — physics feel**
+User: "That iOS scroll where it resists and snaps back when you pull too far."
+Output:
+```
+**Rubber-banding** — Resistance and snap-back when you drag past a boundary (the iOS overscroll feel).
+```
+
+## Glossary
+
+_A curated snapshot mirroring the project's `/vocabulary` page; keep the two in sync when either changes._
+
+### Entrances & Exits — how elements appear and disappear
+- **Fade in / Fade out** — Element appears or disappears by changing opacity.
+- **Slide in** — Element enters by sliding in from off-screen (left, right, top, or bottom).
+- **Scale in** — Element grows from smaller to full size as it appears, often paired with a fade.
+- **Pop in** — Element appears with a slight overshoot, like it bounces into place.
+- **Reveal** — Content is uncovered gradually, often by animating a clip-path or mask.
+- **Enter / Exit** — The animation an element plays when it's added to or removed from the screen.
+
+### Sequencing & Timing — coordinating multiple elements or moments
+- **Keyframes** — Defined points in an animation (0%, 50%, 100%) that the browser fills the gaps between.
+- **Interpolation / Tween** — Generating all the in-between frames between a start and end value, so motion is continuous.
+- **Stagger** — Animate several items one after another with a small delay between each, creating a cascade.
+- **Orchestration** — Deliberately timing multiple animations so they feel like one coordinated motion.
+- **Delay** — Time before an animation starts.
+- **Duration** — How long an animation takes.
+- **Fill mode** — Whether an element keeps its first or last frame's styles before the animation starts or after it ends (e.g. forwards).
+- **Stepped animation** — An animation that is divided into discrete steps, like a countdown timer.
+
+### Movement & Transforms — changing an element's position, size, or angle
+- **Translate** — Move an element along the X or Y axis.
+- **Scale** — Make an element bigger or smaller.
+- **Rotate** — Spin an element around a point.
+- **Skew** — Slant an element along the X or Y axis, shearing it out of its rectangular shape.
+- **3D tilt / Flip** — Rotate in 3D space (rotateX / rotateY) to add depth.
+- **Perspective** — How strong the 3D effect looks — a lower value exaggerates depth, like the viewer is closer.
+- **Transform origin** — The anchor point a scale or rotation grows or spins from.
+- **Origin-aware animation** — An element animates out of its trigger, like a popover growing from the button that opened it instead of from its own center which is the default in CSS.
+
+### Transitions Between States — connecting one state, view, or element to another
+- **Crossfade** — One element fades out as another fades in, in the same spot.
+- **Continuity transition** — A change that keeps the user oriented by visually connecting before and after. For example, making the same rectangle bigger and smaller.
+- **Morph** — One shape smoothly turns into another shape, e.g. Dynamic Island.
+- **Shared element transition** — An element travels and transforms from one position into another, like a thumbnail expanding into a card.
+- **Layout animation** — When an element's size or position changes, it animates to the new spot instead of snapping.
+- **Accordion / Collapse** — A section smoothly expands and collapses its height to show or hide content.
+- **Direction-aware transition** — Content slides one way going forward and the opposite way going back, so navigation has a sense of direction.
+
+### Scroll — motion tied to scrolling or navigating between views
+- **Scroll reveal** — Elements fade or slide into place as they enter the viewport.
+- **Scroll-driven animation** — An animation whose progress is tied directly to scroll position.
+- **Parallax** — Background and foreground move at different speeds while scrolling, creating depth.
+- **Page transition** — An animation that plays when navigating from one page or route to another.
+- **View transition** — The browser morphs between two states or pages, connecting shared elements.
+
+### Feedback & Interaction — responding to the user's actions
+- **Hover effect** — Visual change when the cursor moves over an element.
+- **Press / Tap feedback** — A subtle scale-down when an element is clicked, so it feels physical.
+- **Hold to confirm** — A progress effect that fills up while the user holds a button.
+- **Drag** — Moving an element by grabbing it, often with momentum when released.
+- **Drag to reorder** — Dragging items in a list to rearrange them, while the others shift to make room.
+- **Swipe to dismiss** — Dragging an element off-screen to close it, like a drawer or toast.
+- **Rubber-banding** — Resistance and snap-back when you drag past a boundary (the iOS overscroll feel).
+- **Shake / Wiggle** — A quick side-to-side jitter signaling an error or rejected input.
+- **Ripple** — A circle expanding from the point of a tap, confirming the press.
+
+### Easing — how speed changes over an animation
+- **Easing** — The rate at which an animation speeds up or slows down.
+- **Ease-out** — Starts fast, ends slow. The default for most UI and anything responding to the user.
+- **Ease-in** — Starts slow, ends fast. Usually avoided; can feel sluggish.
+- **Ease-in-out** — Slow, fast, slow. Good for elements already on screen moving from A to B.
+- **Linear** — Constant speed. Avoid for UI; reserve for spinners or marquees.
+- **Cubic-bezier** — A custom easing curve you define for precise control.
+- **Asymmetric easing** — A curve that accelerates and decelerates at different rates. Feels more alive than a symmetric one.
+
+### Spring Animations — physics-based motion as an alternative to fixed-duration easing
+- **Spring** — Motion driven by physics (tension, mass, damping) rather than a set duration.
+- **Stiffness / Tension** — How strongly the spring pulls toward its target. Higher feels snappier.
+- **Damping** — How quickly a spring settles. Lower damping means more bounce and oscillation.
+- **Mass** — How heavy the animated element feels. More mass makes it slower and more sluggish.
+- **Bounce** — A spring that overshoots and settles, adding playfulness.
+- **Perceptual duration** — How long a spring feels finished, even though it keeps micro-settling underneath.
+- **Momentum** — Motion that carries velocity, especially after a drag or interruption.
+- **Velocity** — How fast and in which direction an element is moving. A spring carries it into the next animation when interrupted, so a flicked element keeps its speed.
+- **Interruptible animation** — An animation that can be smoothly redirected mid-flight instead of finishing first.
+
+### Looping & Ambient Motion — animations that run on their own
+- **Marquee** — Text or content that scrolls continuously in a loop.
+- **Loop** — An animation that repeats, a set number of times or infinitely.
+- **Alternate (yoyo)** — A loop that plays forward then reverses each iteration, instead of jumping back to the start.
+- **Orbit** — An element circling around another in a continuous path.
+- **Pulse** — A gentle repeating scale or opacity change to draw attention.
+- **Float** — A gentle, continuous up-and-down drift that makes a static element feel alive and weightless.
+- **Idle animation** — Subtle motion that plays while an element is just sitting there, waiting to be interacted with.
+
+### Polish & Effects — the small touches that separate good from great
+- **Blur** — A blur filter used to soften an element or mask tiny imperfections.
+- **Clip-path** — Clipping an element to a shape, used for reveals, masks, and before/after sliders.
+- **Mask** — Hiding or revealing parts of an element using a shape or gradient — like clip-path, but with soft, fadeable edges.
+- **Before / after slider** — A draggable divider that wipes between two overlaid images to compare them.
+- **Line drawing** — An SVG path that draws itself in, like an invisible pen tracing it.
+- **Text morph** — Text that animates character by character when it changes, drawing attention to the new value.
+- **Skeleton / Shimmer** — A placeholder with a moving sheen shown while content loads.
+- **Number ticker** — Digits rolling or counting up to a value.
+- **Tabular numbers** — Fixed-width digits so numbers don't shift around as they change. Essential for tickers, timers, and counters.
+- **Typewriter** — Text appearing one character at a time, as if being typed.
+
+### Performance — what keeps motion smooth instead of stuttering
+- **Frame rate (FPS)** — Frames drawn per second. 60fps is the baseline for smooth motion; 120fps on newer displays.
+- **Jank** — Visible stutter when the browser drops frames because it can't keep up with the animation.
+- **Dropped frame** — A frame the browser missed its deadline to draw, causing a tiny hitch in motion.
+- **Compositing** — Letting the GPU move or fade an element on its own layer without redoing layout or paint.
+- **will-change** — A CSS hint that an element is about to animate, so the browser can promote it to its own layer ahead of time.
+- **Layout thrashing** — Animating properties like width, height, top, or left that force the browser to recalculate layout every frame, causing jank.
+
+### Principles to Know — concepts that guide when and how to animate
+- **Purposeful animation** — Motion should serve a function — orient, give feedback, show relationships — not just decorate.
+- **Anticipation** — A small wind-up in the opposite direction before a move, hinting at what's about to happen.
+- **Follow-through** — Parts of an element keep moving and settle slightly after the main motion stops, adding weight.
+- **Squash & stretch** — Deforming an element as it moves to convey weight, speed, and flexibility.
+- **Perceived performance** — The right animation makes an interface feel faster, even when it isn't.
+- **Frequency of use** — The more often a user sees an animation, the shorter and subtler it should be.
+- **Spatial consistency** — Animating so an element keeps its identity and position across states, so users never lose track of where things went.
+- **Hardware acceleration** — Animating transform and opacity lets the GPU keep motion smooth.
+- **Reduced motion** — Respecting the user's prefers-reduced-motion setting by toning down or removing motion.