/transitions-polish

name: transitions-polish
license: Free for personal and commercial use; see LICENSE.txt (no redistribution of the library itself)
description: Polish 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 transitions-dev skill, focused on tuning what already animates rather than adding new transitions. Use when the user asks to "polish my transitions", "refine the motion", "tune the timing / easing", "make the animation feel better / less janky", "tighten the durations", "fix the stagger", "align to the motion tokens", "audit the motion", "review my animations", "scan for ad-hoc transitions", "tokenize my animations", or runs the commands transitions review or transitions polish. Also drives the Refine panel's Small refinement feature. Triggers on "motion polish", "transition polish", "refine motion", "timing feels off", "too slow / too fast", "stagger", "delay", "open close timing", "hover in out".

Transitions Polish

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).

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.

Core doctrine: match on usage, never on the nearest number

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.

The five dimensions

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.

Durations

| Token | Value | Usage | | --- | --- | --- | | `--duration-stagger` | `40ms` | per-item stagger offset | | `--duration-micro` | `80ms` | tooltip/path delay, shake segment, large stagger | | `--duration-quick` | `150ms` | modal/dropdown close, text swap, tooltip appear | | `--duration-fast` | `250ms` | icon swap, dropdown/modal open, tabs sliding, page slide | | `--duration-medium` | `350ms` | panel close, toast close | | `--duration-slow` | `400ms` | panel open, skeleton content reveal, input clear | | `--duration-very-slow` | `500ms` | emphasis moments, badge appear, text reveal, success check |

Easings

| Token | Value | Usage | | --- | --- | --- | | `--ease-smooth-out` | `cubic-bezier(0.22, 1, 0.36, 1)` | modal/dropdown/panel open + close, page slide, resize, position change | | `--ease-in-out` | `ease-in-out` | icon swap, text swap, text reveal, skeleton reveal | | `--ease-out` | `ease-out` | tooltip open / close | | `--ease-linear` | `linear` | shimmer, skeleton pulse, spinner | | `--ease-bounce` | `cubic-bezier(0.34, 1.36, 0.64, 1)` | badge pop open | | `--ease-bounce-strong` | `cubic-bezier(0.34, 3.85, 0.64, 1)` | bouncy hover-out (avatar return) |

`--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.

Distances

| Token | Value | Usage | | --- | --- | --- | | `--distance-micro` | `4px` | text swap | | `--distance-small` | `6px` | error shake (small segment) | | `--distance-base` | `8px` | badge diagonal reveal, page slide, error shake (large segment) | | `--distance-medium` | `12px` | text reveal | | `--distance-large` | `30px` | check badge appear |

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`.

Scales

| Token | Value | Usage | | --- | --- | --- | | `--scale-large` | `0.96` | modal open / close | | `--scale-medium` | `0.97` | dropdown open | | `--scale-small` | `0.98` | tooltip open | | `--scale-tiny` | `0.99` | dropdown close |

The captured value is the non-resting "pre" scale the surface animates *from*; it always settles to `1`. Bigger surfaces start from further away (`0.96` modal), small hints barely scale (`0.98`–`0.99`). A pre-scale below `~0.9` reads as a "zoom" and rarely fits UI chrome — snap it to the usage token.

Blur

| Token | Value | Usage | | --- | --- | --- | | `--blur-small` | `2px` | panel reveal, icon swap, text swap, skeleton reveal, number pop-in | | `--blur-medium` | `3px` | page slide, text reveal | | `--blur-large` | `8px` | success check open |

Blur is the non-resting "pre" blur, settling to `0`. Use it to soften a swap or slide, never on a plain fade or a color/theme change. Blur can be **absent** as well as off-token