Foundation

Motion

Motion is a tokenized interaction contract for hover, press, focus, overlays, disclosure, tabs, toasts, loading, feedback, and reduced-motion behavior.

Duration tokens

Name	Token	Value	Use
Instant	`--n-duration-instant`	`80ms`	Reduced-motion and technical synchronization.
Fast	`--n-duration-fast`	`140ms`	Press, focus, and compact acknowledgement.
Normal	`--n-duration-normal`	`220ms`	Hover, reveals, overlays, and feedback.
Slow	`--n-duration-slow`	`360ms`	Page-level reveals used sparingly.

Easing tokens

Name	Token	Value	Use
Standard	`--n-easing-standard`	`cubic-bezier(0.2, 0, 0, 1)`	Default state changes.
Enter	`--n-easing-enter`	`cubic-bezier(0, 0, 0.2, 1)`	Content appearing.
Exit	`--n-easing-exit`	`cubic-bezier(0.4, 0, 1, 1)`	Content leaving.
Expressive	`--n-easing-expressive`	`cubic-bezier(0.16, 1, 0.3, 1)`	Success feedback and larger reveals.

Semantic motion

Semantic motion variables describe intent and point to duration and easing tokens. Component source should use these aliases instead of repeating raw timing values. Hover feedback always transitions with the semantic hover pair; instant timing is not used for ordinary pointer interaction.

Token
`--n-motion-hover-duration`
`--n-motion-press-duration`
`--n-motion-focus-duration`
`--n-motion-reveal-duration`
`--n-motion-collapse-duration`
`--n-motion-overlay-enter-duration`
`--n-motion-overlay-exit-duration`
`--n-motion-page-enter-duration`
`--n-motion-data-refresh-duration`
`--n-motion-success-feedback-duration`
`--n-motion-error-feedback-duration`

Tailwind motion recipes

motionClasses exposes complete, statically detectable Tailwind class strings. The former n-motion-* visual utility classes are not part of the post-migration contract.

Name	Token	Authoring	Use
Interactive control	`motionClasses.interactive`	`Static Tailwind recipe`	Composable hover, press, and focus transitions for actions.
Form control	`motionClasses.control`	`Static Tailwind recipe`	Composable hover and focus transitions without press scaling.
Hover	`motionClasses.hover`	`Static Tailwind recipe`	Background, border, color, and opacity transitions.
Press	`motionClasses.press`	`Static Tailwind recipe`	Subtle press scale with reduced-motion fallback.
Focus	`motionClasses.focus`	`Static Tailwind recipe`	Focus ring and border transitions.
Overlay enter	`motionClasses.overlayEnter`	`Static Tailwind recipe`	Opacity plus small translate/scale.
Disclosure	`motionClasses.disclosure`	`Static Tailwind recipe`	Height and opacity for open/close content.
Tab indicator	`motionClasses.tabIndicator`	`Static Tailwind recipe`	Active indicator movement.
Skeleton	`motionClasses.skeleton`	`Static Tailwind recipe`	Calm loading pulse with reduced-motion fallback.

Optional Motion adapter

Install motion only when a composition needs presence, interruption, coordinated sequencing, gestures, or layout continuity that would make CSS state orchestration fragile. Nerio Core never imports Motion, and unrelated adapter subpaths do not resolve the optional peer.

1pnpm add motion @nerio-ui/adapters

1"use client";23import {4  NerioMotionConfig,5  motionTransitions,6  motionVariants,7  useNerioReducedMotion,8} from "@nerio-ui/adapters/motion";9import { AnimatePresence, LazyMotion, domAnimation } from "motion/react";10import * as m from "motion/react-m";1112export function Presence({ visible }: { visible: boolean }) {13  return (14    <NerioMotionConfig>15      <LazyMotion features={domAnimation} strict>16        <AnimatePresence initial={false}>17          {visible ? (18            <m.div19              key="panel"20              initial="hidden"21              animate="visible"22              exit="exit"23              variants={motionVariants.fadeScale}24              transition={motionTransitions.normal}25            />26          ) : null}27        </AnimatePresence>28      </LazyMotion>29    </NerioMotionConfig>30  );31}

The adapter entrypoint is client-only. Keep the use client boundary at the smallest interactive composition. NerioMotionConfig always sets reducedMotion="user". Use initial={false} when server-rendered state is already visible so hydration does not replay an entrance. useNerioReducedMotion provides a server-stable snapshot and updates mounted compositions when the operating-system preference changes.

domAnimation covers variants, presence, and tap, hover, and focus gestures. Load domMax only for layout, pan, or drag capabilities. Strict mode catches an accidental full motion component inside a LazyMotion boundary; use m from motion/react-m there.

Focused examples

These examples keep animation restrained and expose stable end states for browser verification. They do not replace existing Core component motion.

Presence

A coordinated enter and exit that preserves a deterministic end state.

Release notes ready

Interruption

Rapid reversals continue from the current value instead of restarting.

Layout

The larger feature bundle is loaded only for layout continuity.

PlanBuildReview

Reduced motion

User preference removes transform travel while preserving opacity and state.

System motion active

Choose the smallest motion layer

Layer	Use for	Avoid when
CSS and Tailwind	Hover, press, focus, color, opacity, small transforms, and reliable Base UI states.	The change requires coordinated presence, interruption, or shared layout.
Optional Motion adapter	Presence, interruption, layout continuity, gestures, and product-level sequences.	A shared CSS recipe already expresses the complete interaction.
View Transitions API	Browser-owned page or route transitions with stable old and new document states.	The interaction is gesture-driven or needs element-level interruption.

Reduced motion

Preference	Behavior	Examples
Default	Core components use short durations and avoid layout-heavy motion.	Hover, focus, overlays, and skeleton loading resolve through CSS variables.
Reduced motion	Large movement collapses to opacity or immediate state changes.	Press scale, overlay translation, and repeated skeleton movement are removed or minimized.

Usage

1import { cn, motionClasses } from "@nerio-ui/ui";23<button4  type="button"5  className={cn(6    "rounded-n-control border border-n-border bg-n-surface px-n-4 py-n-2 text-n-text focus-visible:outline-0 focus-visible:shadow-(--n-focus-ring)",7    motionClasses.interactive,8  )}9>10  Save changes11</button>

Use shared motion recipes before adding component-specific Tailwind transitions.
Keep Core motion subtle; expressive motion belongs in product compositions and Pro examples.
Do not add animation libraries for basic hover, focus, overlay, or loading behavior.

Source installation and removal

1pnpm add motion2pnpm nerio add motion-adapter34import {5  NerioMotionConfig,6  motionTransitions,7  motionVariants,8  useNerioReducedMotion,9} from "@/components/nerio/lib/motion-adapter";

Removing the adapter does not change Core components: replace Motion compositions with CSS recipes or static end states, remove the copied adapter file, then uninstall motion. No hidden provider or Core migration is required.