transitions-polish
Skill92 starsChanged 2 months agoMITView on GitHub
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".
6 other projects use a version of this, 2 of them edited.
Adopted by
Most recently taken up by
- sid-lakhani/agents-configword for word, first seen Oct 20, 2026
- mia-cx/skillsword for word, first seen Oct 16, 2026
- Jakubantalik/transitions.devedited, first seen Oct 8, 2026
- ElyzeSolutions/skillsword for word, first seen Aug 6, 2026
- sanmidable/skillsedited, first seen Jul 18, 2026
- AnasX7/skillsword for word, first seen Feb 18, 2026
Other versions6 projects use a version of this.
Word for word · 4
- mia-cx/skills★ 4100% same
- sid-lakhani/agents-config★ 2100% same
- AnasX7/skills★ 1100% same
- ElyzeSolutions/skills★ 1100% same
Edited · 2
- Jakubantalik/transitions.dev★ 6.2k99% same
- sanmidable/skills★ 298% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository65 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- animate-expoSkill
- animateSkill
- animation-vocabularySkill
- apple-designSkill
- ask-mattSkill
- ask-sonnerSkill
- better-accessibilitySkill
- better-colorsSkill
- better-interfaceSkill
- better-layoutSkill
- better-typographySkill
- better-uiSkill
- better-writingSkill
- breakSkill
- claude-handoffSkill
- codebase-designSkill
- code-reviewSkill
- diagnosing-bugsSkill
- domain-modelingSkill
- emil-design-engSkill
- explain-interfaceSkill
- find-animation-opportunitiesSkill
- git-guardrails-claude-codeSkill
- grillingSkill
- grill-meSkill
- grill-with-docsSkill
- handoffSkill
- implementSkill
- implement-specSkill
- improve-animationsSkill
- improve-codebase-architectureSkill
- interface-reviewSkill
- loop-meSkill
- migrate-to-shoehornSkill
- mobile-ios-designSkill
- pick-ui-librarySkill
- prototypeSkill
- prototypeSkill
- refine-liveSkill
- researchSkill
- resolving-merge-conflictsSkill
- retroSkill
- review-animationsSkill
- scaffold-exercisesSkill
- setup-matt-pocock-skillsSkill
- setup-pre-commitSkill
- setup-ts-deep-modulesSkill
- tddSkill
- teachSkill
- to-questionnaireSkill
- to-specSkill
- to-ticketsSkill
- transitions-devSkill
- triageSkill
- variantSkill
- wait-whatSkill
- wayfinderSkill
- wizardSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 98
Delay vs duration: if motion feels late, prefer trimming the duration over adding delay.
- Very specific: line 126
If the user has not run transitions review in this session, run the same scan from transitions review first (steps 1–4) to build the change …
- Very specific: line 130
Keep the file's existing unit/format (0.25s vs 250ms) unless switching to var(--…).
- Very specific: line 133
If _root.css is not yet in the project, offer to install it (once) before or alongside the polish pass.
- Distinctive: line 134
Keep the diff small. End with a one-line summary of files touched.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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
| 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: 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:
- Scan the whole project — not just stylesheets, but inline
style=/ CSS-in-JS, styled-components,<style>blocks, and Tailwind arbitrary values (duration-[300ms],[transition-timing-function:...]) — for all five dimensions: durations (…ms/…s), easings (cubic-bezier(...)/ keywords), translate distances (translate*(…px)),scale(...), andblur(...). Read@keyframesvia theanimationthat drives them. - For each value, infer what the motion does from the surrounding selectors / component names (modal close, dropdown open, tooltip, badge appear, page slide, text reveal, shake, hover lift, …). Look the usage up in the token tables above and pick the token whose documented usage matches — usage first, never nearest number. Do not suggest whole-transition recipe swaps; that is
transitions-dev'stransitions applydomain. - Apply the polish rules: check open/close asymmetry, hover in/out, stagger totals, and delays — not just whether a single value is on-grid.
- Output a numbered list grouped by file, showing only values that should change:
path/to/Component.css:L42—modal close: 300ms → var(--duration-quick) (150ms)— close should be quicker than the 250ms open.path/to/List.css:L20—stagger: 120ms → var(--duration-stagger) (40ms)— 8 items × 120ms = 960ms total, last item feels late.- Skip values whose usage matches no token — list them as
no matching token usageand leave them.
- Do not edit anything. End with: "Run
transitions polishto apply these changes, or confirm any line to apply individually."
transitions polish — apply motion-token refinements
Trigger phrases: transitions polish, "polish my transitions", "refine the motion", "tune the timing / easing", "apply the motion tokens", "fix the stagger", "tokenize my animations".
Behaviour:
- If the user has not run
transitions reviewin this session, run the same scan from transitions review first (steps 1–4) to build the change list. If they named a specific file, line, or value, scope the scan to that context. - Surface a short proposal: how many values would change, grouped by file, with one example line. Ask for confirmation before editing.
- On confirmation, apply the token changes to the source:
- Replace hardcoded durations/easings/distances/scales/blur with
var(--…)references where the project's_root.css(this skill's_root.css) is already imported; otherwise write the token's literal value and note that importing_root.csswould let future tweaks happen in one place. - Keep the file's existing unit/format (
0.25svs250ms) unless switching tovar(--…). - Touch only the motion values being polished — no reformatting, no unrelated edits.
- Handle plain CSS, CSS Modules, styled-components/emotion, Tailwind utilities/config, inline
styleobjects, and Motion/Framer variants.
- Replace hardcoded durations/easings/distances/scales/blur with
- If
_root.cssis not yet in the project, offer to install it (once) before or alongside the polish pass. - Keep the diff small. End with a one-line summary of files touched.
Relationship to the Refine panel
When this skill is installed in a project, the transitions.dev Refine panel's Small refinement tab automatically inlines the compact rules in _refine-rules.md into its agent prompt, so per-click suggestions honor these rules with zero extra file reads. transitions review mirrors that audit at project scale; transitions polish writes the accepted tweaks to source.
Future expansion
Natural next additions to this skill: performance hygiene (transition: all, animating width/top/box-shadow instead of transform/opacity, will-change misuse), missing prefers-reduced-motion detection, a cross-project consistency audit (same-purpose transitions using different values), Tailwind/Framer token adapters, and a "motion polish score" report.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

