@tamsensedev/runner 0.13.0 → 0.18.0

package/library/skills/motion-design/SKILL.md

@@ -1,106 +1,106 @@
----
-name: motion-design
-description: Use when adding, changing or reviewing UI animation or transitions: press and hover feedback, menus, dialogs, drawers, toasts, list changes, view transitions, marketing-page motion. Covers whether to animate at all, durations, easing, performance, interruption and reduced motion, CSS first, then the project's motion library.
----
-
-# Motion design
-
-Motion should be felt, not watched. Good motion explains a change (where the menu came from, that the click registered, what was removed) and then gets out of the way. Generated UI tends to do the opposite: a fade-up on every block, hover lifts on every card, bounce easing, 400ms dropdowns.
-
-The project's motion tokens, existing transitions and installed animation library win over every value here. If the codebase already animates dialogs at 200ms with its own curve, new dialogs do the same.
-
-## Decide before you animate
-
-### 1. Should this animate at all?
-
-| How often people see it | Decision |
-|---|---|
-| 100+ times a day (keyboard shortcuts, command palette, typing, list navigation by keys) | No animation |
-| Tens of times a day (hover, tab switches, row selection) | Instant, or a 100 to 150ms colour or opacity change |
-| Occasionally (menus, dialogs, drawers, toasts, expanding sections) | Standard animation |
-| Rarely (first run, a completed setup, an empty state the first time) | May carry a little more character |
-
-Never animate keyboard-initiated actions. Product screens load into the task: no orchestrated page-load sequences.
-
-### 2. What is it for?
-
-Valid purposes: feedback (the press registered), state (open, selected, saved), spatial continuity (the toast leaves the way it came, the drawer slides from its edge), preventing a jarring jump (content appearing or disappearing), and on marketing pages, explaining how something works. "It looks nice" is not a purpose for something seen often.
-
-### 3. Easing
-
-- Entering or exiting: **ease-out**. Default curve `cubic-bezier(0.23, 1, 0.32, 1)`.
-- Moving or morphing on screen: **ease-in-out**, `cubic-bezier(0.77, 0, 0.175, 1)`.
-- Hover and colour changes: `ease`.
-- Constant motion (progress, marquee): `linear`.
-- Drawers and sheets: `cubic-bezier(0.32, 0.72, 0, 1)` reads like native mobile sheets.
-- Never `ease-in` for UI: it delays the first frame, exactly when the person is watching. No bounce or elastic curves by reflex.
-
-### 4. Duration
-
-| Element | Duration |
-|---|---|
-| Press feedback | 100 to 160ms |
-| Hover, colour | 100 to 150ms |
-| Tooltip, small popover | 125 to 200ms |
-| Dropdown, select, menu | 150 to 250ms |
-| Dialog, drawer, sheet | 200 to 300ms (large drawers up to 500ms) |
-| Layout or view transition | 250 to 400ms |
-| Authored moment on a marketing page | 500 to 800ms |
-
-UI motion stays under 300ms. Exits are faster and quieter than entrances (about 75% of the enter time, a small offset rather than the full distance).
-
-## Rules
-
-1. **Animate `transform` and `opacity`.** They skip layout and paint. Animate `width`, `height`, `top`, `left` or margins only with a technique built for it (FLIP, grid-template-rows `0fr` to `1fr`, View Transitions). `filter`, `clip-path` and shadows are fine on small, bounded elements.
-2. **Never `transition: all`.** Name the properties.
-3. **Interruptible by default.** Use CSS transitions (or springs) for anything the person can trigger again mid-way; they retarget. Keyframes restart from zero; keep them for one-shot sequences.
-4. **Nothing appears from nothing.** Enter from `scale(0.95)` to `scale(0.97)` with opacity 0, never `scale(0)`.
-5. **Origin-aware popovers.** Menus, popovers and tooltips scale from their trigger (`transform-origin` at the trigger side). Dialogs stay centred.
-6. **Stagger only real lists**, 30 to 80ms between items, total under about 300ms, and never block interaction while it plays.
-7. **Press feedback**: `scale(0.97)` on `:active` for buttons (not below 0.95).
-8. **Tooltips**: a short delay before the first one; once one is open, neighbours open instantly with no animation.
-9. **Hover motion only for fine pointers**: wrap it in `@media (hover: hover) and (pointer: fine)`.
-10. **Content is visible by default.** If a script fails or an observer never fires, nothing stays hidden. Scroll reveals start from an already-visible state or have a no-script fallback.
-11. **Reduced motion means fewer and gentler, not none.** Under `prefers-reduced-motion: reduce`, remove movement, scaling and parallax; keep short opacity and colour changes that confirm state. Stop decorative loops. Autoplaying motion over 5 seconds needs a pause control.
-12. **Motion is never the only signal.** Every animated state change also has a static cue (colour, icon, text).
-13. **`will-change` only to cure an observed first-frame stutter**, on the element and only during the animation.
-14. **No new dependency for an effect the stack can already express.** CSS transitions, `@starting-style`, the Web Animations API and View Transitions cover most UI needs.
-
-## Implement with what the project has
-
-In order: CSS transitions and keyframes; the Web Animations API for programmatic control; the project's existing library (Vue `<Transition>`, Svelte transitions, Angular animations, Motion for React, GSAP); View Transitions for continuity between states or routes. Recipes for each are in [references/recipes.md](references/recipes.md).
-
-## Marketing pages
-
-A page read once may carry one authored moment: a hero sequence, one interactive demo, a single scroll-linked reveal whose scroll relationship means something. One strong idea beats an identical fade-up on every section. Keep it under about 800ms, make it skippable by scrolling, give it a reduced-motion version, and keep the page complete without it.
-
-## Check
-
-- Play it at slow speed (DevTools Animations panel at 10%, or multiply durations by 5 temporarily). Look for two states overlapping in a crossfade, wrong origins, properties out of sync, a jump at the end.
-- Trigger it twice quickly and mid-way: it reverses smoothly, nothing sticks.
-- Toggle reduced motion (DevTools rendering panel, or Playwright `reducedMotion: 'reduce'`): state changes still read.
-- Throttle the CPU 4x: no dropped frames on the common path.
-- A screenshot taken mid-load shows no blank bands where a reveal did not fire.
-
-## Common mistakes
-
-| Mistake | Fix |
-|---|---|
-| `transition: all 300ms` | `transition: transform 200ms var(--ease-out), opacity 200ms var(--ease-out)` |
-| `scale(0)` entrance | `scale(0.95)` with opacity 0 |
-| `ease-in` on a dropdown | ease-out, custom curve |
-| Popover scaling from its centre | `transform-origin` at the trigger |
-| Animation on a keyboard shortcut | Remove it |
-| 400ms dropdown | 150 to 250ms |
-| Keyframes on a toggle that can be re-triggered | A transition |
-| Hover scale that fires on tap | Gate with the hover and pointer media query |
-| Every section fades up on scroll | Remove; one authored moment at most, on marketing pages |
-| Exit as slow as the enter | Shorter, smaller exit |
-
-## Output in reviews
-
-A table with **Before**, **After** and **Why**, one row per issue, citing `file:line`.
-
-Related: `interface-polish`, `interface-design`, `accessibility`.
-
-Sources: adapted from emilkowalski/skills emil-design-eng (MIT, changed: framework-neutral, React and Motion specifics moved to examples, "initial response" step removed), jakubkrehel/make-interfaces-feel-better animations reference (MIT) and pbakaus/impeccable animate and operate references (Apache-2.0, changed: rewritten, ask steps removed).
+---
+name: motion-design
+description: Use when adding, changing or reviewing UI animation or transitions: press and hover feedback, menus, dialogs, drawers, toasts, list changes, view transitions, marketing-page motion. Covers whether to animate at all, durations, easing, performance, interruption and reduced motion, CSS first, then the project's motion library.
+---
+
+# Motion design
+
+Motion should be felt, not watched. Good motion explains a change (where the menu came from, that the click registered, what was removed) and then gets out of the way. Generated UI tends to do the opposite: a fade-up on every block, hover lifts on every card, bounce easing, 400ms dropdowns.
+
+The project's motion tokens, existing transitions and installed animation library win over every value here. If the codebase already animates dialogs at 200ms with its own curve, new dialogs do the same.
+
+## Decide before you animate
+
+### 1. Should this animate at all?
+
+| How often people see it | Decision |
+|---|---|
+| 100+ times a day (keyboard shortcuts, command palette, typing, list navigation by keys) | No animation |
+| Tens of times a day (hover, tab switches, row selection) | Instant, or a 100 to 150ms colour or opacity change |
+| Occasionally (menus, dialogs, drawers, toasts, expanding sections) | Standard animation |
+| Rarely (first run, a completed setup, an empty state the first time) | May carry a little more character |
+
+Never animate keyboard-initiated actions. Product screens load into the task: no orchestrated page-load sequences.
+
+### 2. What is it for?
+
+Valid purposes: feedback (the press registered), state (open, selected, saved), spatial continuity (the toast leaves the way it came, the drawer slides from its edge), preventing a jarring jump (content appearing or disappearing), and on marketing pages, explaining how something works. "It looks nice" is not a purpose for something seen often.
+
+### 3. Easing
+
+- Entering or exiting: **ease-out**. Default curve `cubic-bezier(0.23, 1, 0.32, 1)`.
+- Moving or morphing on screen: **ease-in-out**, `cubic-bezier(0.77, 0, 0.175, 1)`.
+- Hover and colour changes: `ease`.
+- Constant motion (progress, marquee): `linear`.
+- Drawers and sheets: `cubic-bezier(0.32, 0.72, 0, 1)` reads like native mobile sheets.
+- Never `ease-in` for UI: it delays the first frame, exactly when the person is watching. No bounce or elastic curves by reflex.
+
+### 4. Duration
+
+| Element | Duration |
+|---|---|
+| Press feedback | 100 to 160ms |
+| Hover, colour | 100 to 150ms |
+| Tooltip, small popover | 125 to 200ms |
+| Dropdown, select, menu | 150 to 250ms |
+| Dialog, drawer, sheet | 200 to 300ms (large drawers up to 500ms) |
+| Layout or view transition | 250 to 400ms |
+| Authored moment on a marketing page | 500 to 800ms |
+
+UI motion stays under 300ms. Exits are faster and quieter than entrances (about 75% of the enter time, a small offset rather than the full distance).
+
+## Rules
+
+1. **Animate `transform` and `opacity`.** They skip layout and paint. Animate `width`, `height`, `top`, `left` or margins only with a technique built for it (FLIP, grid-template-rows `0fr` to `1fr`, View Transitions). `filter`, `clip-path` and shadows are fine on small, bounded elements.
+2. **Never `transition: all`.** Name the properties.
+3. **Interruptible by default.** Use CSS transitions (or springs) for anything the person can trigger again mid-way; they retarget. Keyframes restart from zero; keep them for one-shot sequences.
+4. **Nothing appears from nothing.** Enter from `scale(0.95)` to `scale(0.97)` with opacity 0, never `scale(0)`.
+5. **Origin-aware popovers.** Menus, popovers and tooltips scale from their trigger (`transform-origin` at the trigger side). Dialogs stay centred.
+6. **Stagger only real lists**, 30 to 80ms between items, total under about 300ms, and never block interaction while it plays.
+7. **Press feedback**: `scale(0.97)` on `:active` for buttons (not below 0.95).
+8. **Tooltips**: a short delay before the first one; once one is open, neighbours open instantly with no animation.
+9. **Hover motion only for fine pointers**: wrap it in `@media (hover: hover) and (pointer: fine)`.
+10. **Content is visible by default.** If a script fails or an observer never fires, nothing stays hidden. Scroll reveals start from an already-visible state or have a no-script fallback.
+11. **Reduced motion means fewer and gentler, not none.** Under `prefers-reduced-motion: reduce`, remove movement, scaling and parallax; keep short opacity and colour changes that confirm state. Stop decorative loops. Autoplaying motion over 5 seconds needs a pause control.
+12. **Motion is never the only signal.** Every animated state change also has a static cue (colour, icon, text).
+13. **`will-change` only to cure an observed first-frame stutter**, on the element and only during the animation.
+14. **No new dependency for an effect the stack can already express.** CSS transitions, `@starting-style`, the Web Animations API and View Transitions cover most UI needs.
+
+## Implement with what the project has
+
+In order: CSS transitions and keyframes; the Web Animations API for programmatic control; the project's existing library (Vue `<Transition>`, Svelte transitions, Angular animations, Motion for React, GSAP); View Transitions for continuity between states or routes. Recipes for each are in [references/recipes.md](references/recipes.md).
+
+## Marketing pages
+
+A page read once may carry one authored moment: a hero sequence, one interactive demo, a single scroll-linked reveal whose scroll relationship means something. One strong idea beats an identical fade-up on every section. Keep it under about 800ms, make it skippable by scrolling, give it a reduced-motion version, and keep the page complete without it.
+
+## Check
+
+- Play it at slow speed (DevTools Animations panel at 10%, or multiply durations by 5 temporarily). Look for two states overlapping in a crossfade, wrong origins, properties out of sync, a jump at the end.
+- Trigger it twice quickly and mid-way: it reverses smoothly, nothing sticks.
+- Toggle reduced motion (DevTools rendering panel, or Playwright `reducedMotion: 'reduce'`): state changes still read.
+- Throttle the CPU 4x: no dropped frames on the common path.
+- A screenshot taken mid-load shows no blank bands where a reveal did not fire.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| `transition: all 300ms` | `transition: transform 200ms var(--ease-out), opacity 200ms var(--ease-out)` |
+| `scale(0)` entrance | `scale(0.95)` with opacity 0 |
+| `ease-in` on a dropdown | ease-out, custom curve |
+| Popover scaling from its centre | `transform-origin` at the trigger |
+| Animation on a keyboard shortcut | Remove it |
+| 400ms dropdown | 150 to 250ms |
+| Keyframes on a toggle that can be re-triggered | A transition |
+| Hover scale that fires on tap | Gate with the hover and pointer media query |
+| Every section fades up on scroll | Remove; one authored moment at most, on marketing pages |
+| Exit as slow as the enter | Shorter, smaller exit |
+
+## Output in reviews
+
+A table with **Before**, **After** and **Why**, one row per issue, citing `file:line`.
+
+Related: `interface-polish`, `interface-design`, `accessibility`.
+
+Sources: adapted from emilkowalski/skills emil-design-eng (MIT, changed: framework-neutral, React and Motion specifics moved to examples, "initial response" step removed), jakubkrehel/make-interfaces-feel-better animations reference (MIT) and pbakaus/impeccable animate and operate references (Apache-2.0, changed: rewritten, ask steps removed).