How karaUI moves
The checklist we use inside karaUI: ask whether an element should move at all, pick its curve from the shared tokens, keep it short, and write the reduced-motion version at the same time.
Decision framework
Most motion problems are settled by a few questions asked up front, well before anyone tweaks a duration.
Something clicked dozens of times per session has to respond at once. Keep the flourish for screens that come up once in a while, like onboarding or an empty state.
A toolbar button gets a quick dip. A first-run welcome can afford a longer entrance.
Good reasons to move: showing where a panel came from, acknowledging a tap, signalling a new state, or easing a jump in content. Looking nice is not on the list.
No job, no animation. Delete it and check whether anyone misses it.
Things arriving get ease-out. Things travelling across the screen get ease-in-out. Progress bars run linear. Anything the pointer drags or flicks gets a spring.
Pick the curve from what the element is doing; habit is a poor guide.
When the OS asks for less motion, fades and color changes can stay. Slides, zooms and parallax should go.
Plan this variant up front, alongside the full version.
Motion tokens
Every karaUI component pulls its easing and springs from lib/ease.ts. Pick a token by what the element is doing; the library then feels consistent even though each piece moves differently.
Compare the curves
Both dots travel the same track in the same time.
Starts fast and coasts to a stop, which suits elements arriving or leaving.
Speeds up, then slows down, which suits an element moving between two spots.
SPRING_PRESS
Short and firm; used on buttons and anything else you press.
SPRING_LAYOUT
For pills, indicators and shared surfaces that glide between positions.
Timing
Bigger surfaces and longer distances need more time; frequent actions need less. Treat the ranges below as a first guess and adjust by eye.
Most UI motion in karaUI finishes inside 300ms. Go longer only for a demo that teaches something, a gesture the user is driving, or a big change in layout.
Recipes
Each card shows a live demo, the reason the motion exists, a common way to get it wrong, and the code with its reduced-motion branch.
Shrink the control slightly the moment it is pressed, so the user knows the tap landed even if the work behind it takes a while.
import { motion, useReducedMotion } from "motion/react";
import { SPRING_PRESS } from "@/lib/ease";
const reduce = useReducedMotion();
<motion.button
whileTap={reduce ? undefined : { scale: 0.97 }}
transition={SPRING_PRESS}
>
Continue
</motion.button>Move an icon the way its real-world object would: a bell rocks from the top, a download arrow dips toward the tray below it.
const reduce = useReducedMotion();
const canHover = useHoverCapable();
<motion.span
style={{ transformOrigin: "top center" }}
animate={active && canHover && !reduce
? { rotate: [0, 12, -8, 4, 0] }
: { rotate: 0 }}
transition={{ duration: 0.28, ease: EASE_OUT }}
>
<Bell />
</motion.span>Bring in the one surface that matters with a small upward drift and a light blur, and let it settle before the user starts reading it.
New surface
Ready before focus.
const reduce = useReducedMotion();
<motion.div
initial={{
opacity: 0,
transform: reduce ? "none" : "translateY(8px)",
filter: reduce ? "none" : "blur(4px)",
}}
animate={{
opacity: 1,
transform: "translateY(0px)",
filter: "blur(0px)",
}}
transition={{ duration: 0.22, ease: EASE_OUT }}
/>When a compact control grows, keep the original shape on screen and resize it; only once there is room should the label fade in.
<motion.div layout transition={CONTINUITY_SPRING}>
<motion.button layout transition={CONTINUITY_SPRING}>
<motion.span layout="position">
<PanelTopOpen />
</motion.span>
<AnimatePresence mode="popLayout" initial={false}>
{expanded ? (
<motion.span
layout
variants={CONTINUITY_LABEL}
initial="hidden"
animate="visible"
exit="exit"
transition={CONTINUITY_SPRING}
>
Open panel
</motion.span>
) : null}
</AnimatePresence>
</motion.button>
</motion.div>Switching tabs or filters? Clear the old view quickly, bring the new one in a touch slower, and move each only a few pixels.
<AnimatePresence mode="wait" initial={false}>
<motion.div
key={tab}
initial={{ opacity: 0, transform: "translateY(4px)" }}
animate={{ opacity: 1, transform: "translateY(0px)" }}
exit={{
opacity: 0,
transform: "translateY(-4px)",
transition: { duration: 0.12, ease: EASE_OUT },
}}
transition={{ duration: 0.18, ease: EASE_OUT }}
/>
</AnimatePresence>Accessibility
Turning everything off is the wrong fix. Keep the cues that help people follow along and drop the movement that can make them feel unwell.
Opacity, color and instant state swaps stay. Parallax, big translates, repeated scaling and springy overshoot are removed.
const reduce = useReducedMotion();
const hidden = {
opacity: 0,
transform: reduce ? "none" : "translateY(8px)",
};
const visible = {
opacity: 1,
transform: "translateY(0px)",
};