Transitions Polish

Transitions Polish

An add-on to the `transitions-dev` 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 Motion tokens tab exposes. Copy this skill's `_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

Easings

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

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

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

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: when the usage clearly calls for one (a page slide with no blur lane) suggest adding --blur-medium.

Polish rules — when a value is right

Open/close asymmetry

Opening is an invitation; closing should get out of the way. Closes are faster and quieter than opens.

• Duration: dropdown/modal open 250ms → close 150ms (--duration-fast → --duration-quick); panel open 400ms → close 350ms (--duration-slow → --duration-medium); toast close 350ms (--duration-medium).
• Symmetric exceptions — same duration + easing both ways, do NOT split: page side-by-side (250ms), tabs sliding (250ms), accordion (250ms), icon swap (250ms), text swap (150ms). These read as a single reversible motion, not an open/close pair.
• Distance & blur: the enter phase carries the distance and blur; the exit can drop or shrink them so a close doesn't fling content across the screen.
• Easing: most opens and closes share --ease-smooth-out. Overshoot curves belong to entrances only (badge pop, number pop-in) — never bounce a close.

Hover in vs hover out

• In: quick and direct — a short --duration-fast-or-less lift with --ease-smooth-out.
• Out: softer and springier — the return can take longer and use --ease-bounce-strong (avatar return, cubic-bezier(0.34, 3.85, 0.64, 1)) so the row settles instead of snapping. This is the one place the out is more elaborate than the in.

Stagger and delay

• Stagger offset: --duration-stagger (40ms) per item; step up to --duration-micro (80ms) for a few large items. Keep the total stagger (offset × item count) under ~300ms so the last item doesn't feel late — for long lists, cap the number of staggered items or shrink the offset.
• Intent delay: a tooltip waits --duration-micro (80ms) before appearing so a passing cursor doesn't trigger it; the success-check path draw uses the same 80ms beat. A delay is right when you want to filter accidental triggers or sequence two things — not to pad a slow animation.
• Delay vs duration: if motion feels late, prefer trimming the duration over adding delay. Reserve delay for stagger, intent gating, and deliberate sequencing.
• Never delay a close or a hover-out — dismissal must feel instant.

Commands

The skill exposes two namespaced verbs. Every command starts with transitions so the invocation never collides with verbs from other skills installed in the same project. review reports; polish applies.

transitions review — audit motion against the tokens

Trigger phrases: transitions review, "review my animations", "audit the motion", "scan for ad-hoc transitions", "tokenize my animations", "where are my durations off", "align to the motion tokens", "make the timing consistent".

Behaviour: