$npx -y skills add Jakubantalik/transitions.dev --skill transitions-polishPolish and refine existing motion against the transitions.dev motion-token scale — duration, distance, scale, blur, and easing — plus the rules for WHEN each token applies (open/close asymmetry, hover-in vs hover-out, stagger offsets, and intent delays). An add-on to the transiti
| 1 | # Transitions Polish |
| 2 | |
| 3 | An **add-on** to the [`transitions-dev`](../transitions-dev/SKILL.md) skill. Where `transitions-dev` installs whole transitions, this skill **polishes motion that already exists**: it scans the five motion-token dimensions — **duration, distance, scale, blur, easing** — and suggests the token each value should reference, plus the higher-order rules for *when* a value is right (open/close asymmetry, hover in/out, stagger, delay). |
| 4 | |
| 5 | Install it alongside `transitions-dev`, or on its own — the token values are restated below so this skill can audit a project standalone. When it is installed, the transitions.dev **Refine panel** automatically feeds these rules into every **Small refinement** job. |
| 6 | |
| 7 | ## Core doctrine: match on usage, never on the nearest number |
| 8 | |
| 9 | A value is not "wrong" because it is off by 20ms. It is wrong when it does not fit **what the motion does**. Always infer the usage first — modal close, dropdown open, tooltip, badge appear, page slide, text reveal, shake — then pick the token whose documented usage matches. A `300ms` modal close maps to `--duration-quick` (150ms) because both are "modal close", even though the numbers differ. If a value's usage matches **no** token usage, leave it untouched. Never force a swap just because a number is close. |
| 10 | |
| 11 | ## The five dimensions |
| 12 | |
| 13 | Same scale the [transitions.dev](https://transitions.dev) Motion tokens tab exposes. Copy this skill's [`_root.css`](./_root.css) into your project once; once imported, reference any token as `var(--…)`. The `transitions-dev` transitions ship literal values, so they work without these tokens — install this skill to tune them against the shared scale. |
| 14 | |
| 15 | ### Durations |
| 16 | |
| 17 | | Token | Value | Usage | |
| 18 | | --- | --- | --- | |
| 19 | | `--duration-stagger` | `40ms` | per-item stagger offset | |
| 20 | | `--duration-micro` | `80ms` | tooltip/path delay, shake segment, large stagger | |
| 21 | | `--duration-quick` | `150ms` | modal/dropdown close, text swap, tooltip appear | |
| 22 | | `--duration-fast` | `250ms` | icon swap, dropdown/modal open, tabs sliding, page slide | |
| 23 | | `--duration-medium` | `350ms` | panel close, toast close | |
| 24 | | `--duration-slow` | `400ms` | panel open, skeleton content reveal, input clear | |
| 25 | | `--duration-very-slow` | `500ms` | emphasis moments, badge appear, text reveal, success check | |
| 26 | |
| 27 | ### Easings |
| 28 | |
| 29 | | Token | Value | Usage | |
| 30 | | --- | --- | --- | |
| 31 | | `--ease-smooth-out` | `cubic-bezier(0.22, 1, 0.36, 1)` | modal/dropdown/panel open + close, page slide, resize, position change | |
| 32 | | `--ease-in-out` | `ease-in-out` | icon swap, text swap, text reveal, skeleton reveal | |
| 33 | | `--ease-out` | `ease-out` | tooltip open / close | |
| 34 | | `--ease-linear` | `linear` | shimmer, skeleton pulse, spinner | |
| 35 | | `--ease-bounce` | `cubic-bezier(0.34, 1.36, 0.64, 1)` | badge pop open | |
| 36 | | `--ease-bounce-strong` | `cubic-bezier(0.34, 3.85, 0.64, 1)` | bouncy hover-out (avatar return) | |
| 37 | |
| 38 | `--ease-smooth-out` is the default. Nudge generic `ease`, `ease-in`, or any hand-rolled `cubic-bezier(...)` / `linear(...)` toward it **only** for surface motion (open/close, slide, resize, position). Leave the other five token easings alone — they are already on-grid and each carries its own intent. |
| 39 | |
| 40 | ### Distances |
| 41 | |
| 42 | | Token | Value | Usage | |
| 43 | | --- | --- | --- | |
| 44 | | `--distance-micro` | `4px` | text swap | |
| 45 | | `--distance-small` | `6px` | error shake (small segment) | |
| 46 | | `--distance-base` | `8px` | badge diagonal reveal, page slide, error shake (large segment) | |
| 47 | | `--distance-medium` | `12px` | text reveal | |
| 48 | | `--distance-large` | `30px` | check badge appear | |
| 49 | |
| 50 | Travel distance scales *down* with frequency and *up* with ceremony: an in-place text swap barely moves (`4px`), a page slide travels a readable `8px`, a one-off celebratory badge can sweep `30px`. If a translate distance is larger than `~40px` for anything but a full panel/drawer, it usually reads as sluggish — pull it toward `--distance-base`. |
| 51 | |
| 52 | ### Scales |
| 53 | |
| 54 | | Token | Value | Usage | |
| 55 | | --- | --- | --- | |
| 56 | | `--scale-large` | `0.96` |