Utilities & motion

Motion helpers

Shared timing, easing, offsets, reveal recipes, and subtle hover behavior for Framer Motion.

motionDurationmotionOffsetmotionEasestaggerDelayfadeUpMotioninViewFadeUpMotionsubtleHoverMotionborderHoverMotion

Component workbench

Configure the production component, inspect it at responsive widths, copy synchronized JSX, and share the exact state from one workspace.

Motion contract applied

Delay 0s, offset 20px, duration 0.5s.

Generated example

This JSX stays synchronized with the controls and uses only public package APIs.

tsx

'use client';

import { motion } from 'framer-motion';
import { fadeUpMotion } from '@ai-created/ui';

export function Example() {
  return (
    <motion.section {...fadeUpMotion(0, 20, 0.5)}>
      Motion follows shared timing and distance conventions.
    </motion.section>
  );
}

Import

tsx

import { fadeUpMotion, inViewFadeUpMotion, staggerDelay } from '@ai-created/ui';

Install from a reviewed release

Replace the version placeholder with the release tag your product has reviewed.

shell

npm install --install-links "git+https://github.com/TheMarco/ai-created-ui.git#vX.Y.Z"

Load semantic tokens

css

@import '@ai-created/ui/styles/tokens.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

Extend Tailwind

module.exports = {
  presets: [require('@ai-created/ui/tailwind-preset')],
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@ai-created/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
};

Anatomy

Named regions define what belongs to the component, what remains optional, and where semantic responsibility lives.

Duration scale

Required

Six named timings from instant to ambient.

Offset scale

Required

Reveal and hover travel distances.

Easing scale

Required

Standard cubic bezier and named Framer easings.

Reveal helpers

Required

Serializable Framer Motion prop objects for mount and in-view entrance.

Hover helpers

Required

Serializable lift and border-emphasis prop objects.

Construction and authoring

The Figma-equivalent asset model, auto-layout, resizing, properties, slots, content bounds, localization, and governance contract.

Asset kind

helper

Design library name

Code-only asset

Maturity

stable

Last reviewed

2026-08-29

Canvas applicability

Functions and timing constants have no reusable Figma component geometry. Document approved motion tokens and prototype examples instead.

Auto layout

Direction: none
Gap: Not applicable
Padding: Not applicable
Alignment: Not applicable
Wrap: Not applicable

Motion helper functions return Framer Motion props and emit no layout container.

Resizing

Width: not-applicable
Height: not-applicable
Minimum width: Not applicable
Maximum width: Not applicable
Minimum height: Not applicable
Maximum height: Not applicable
Overflow: not-applicable

Motion helper functions own transforms and timing, not geometry constraints.

Exposed design properties

Property	Type	Default	Code mapping	Options or notes
Delay	number	0	fadeUpMotion or inViewFadeUpMotion delay argument	No additional constraint
Vertical offset	number	20	y argument or motionOffset token	No additional constraint
Duration	number	0.5	duration argument or motionDuration token	No additional constraint
Hover distance	number	2	subtleHoverMotion or borderHoverMotion distance argument	No additional constraint

Nested assets and slots

motionDuration

helper / required

Approved timing constants.

motionDuration

motionOffset

helper / required

Approved translation distances.

motionOffset

motionEase

helper / required

Approved easing curves.

motionEase

Motion element

slot / required

Consumer-owned Framer Motion element receiving helper output.

Spread returned props onto motion.*

Content limits

Concurrent effects

One primary entrance or hover effect per element

Overflow: Remove competing transforms and ambient loops.

Motion should clarify hierarchy without becoming decoration.

Staggered collections

Keep total sequence short enough that the last item is not delayed from use

Overflow: Reduce step or animate groups rather than every row.

Content must remain promptly available.

Localization and RTL

Transforms must not encode reading direction unless a product-specific helper explicitly does so.
Test reduced motion.
Test layout in both directions to ensure transforms do not imply the wrong flow.

Responsive behavior

No intrinsic geometry; the receiving element owns responsive behavior.

Not applicable to helper

Reduce or remove spatial motion where small screens make displacement distracting.
Do not delay interactivity while animation completes.

Authoring limits

Figma prototype easing and timing are reference approximations, not the canonical implementation.
Do not create a detached component for each animation helper.
ThemeProvider is required for the shared reduced-motion policy.
Helper output may be overridden by later Framer Motion props.
Auto layout, component resizing, text limits, and instance swapping are not owned by motion helpers.

Accountable owner

Design systems motion foundations owner

Canonical source: src/lib/motion.ts

Token or helper changes require reduced-motion review and regression checks on every consumer category.
A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.
The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change.

Read the system construction standard

Visual specification

These measurements and semantic tokens define the supported visual contract. Local overrides should preserve the same hierarchy and interaction cues.

Durations

150 / 200 / 300 / 500 / 600 / 1500ms

Reveal offsets

16 / 20 / 30px

Hover offsets

2 / 4px

Default stagger

100ms per item

Rules

Use motion to clarify hierarchy or state, not to decorate every element.
Prefer shared values over one-off durations and distances.
In-view reveals run once by default.
Do not rely on motion alone to communicate meaning.

Token dependencies

--motion-fast

CSS equivalent of 200ms interactions.

--motion-base

CSS equivalent of 300ms transitions.

--motion-slow

CSS equivalent of 500ms reveals/cross-fades.

--color-border-strong

Default borderHoverMotion emphasis.

States and behavior

A component is not complete until its passive, interactive, disabled, and exceptional states remain understandable in both themes.

entry

Trigger: fadeUpMotion props mount.
Visual response: Opacity moves 0→1 while y moves to 0.
Behavior: Runs immediately with optional delay.

in view

Trigger: inViewFadeUpMotion enters viewport.
Visual response: Same fade-up treatment.
Behavior: Runs once when observed.

hover

Trigger: Pointer hover on a motion element.
Visual response: Element lifts 2px or 4px; border helper also strengthens border.
Behavior: Returns over the shared fast duration.

reduced motion

Trigger: User requests reduced motion under ThemeProvider MotionConfig.
Visual response: Framer Motion reduces transform motion according to user preference; global CSS collapses animation durations.
Behavior: Meaning and interaction remain available without animation.

Accessibility contract

Semantics, accessible naming, keyboard behavior, focus and announcements are implementation requirements, not optional documentation.

Semantics: Helpers return presentation props only and do not alter DOM semantics.
Accessible name: Not applicable.

Render motion elements with the correct semantic element and focus behavior.
Use within ThemeProvider so MotionConfig honors the user preference.
Never delay essential content or input availability behind animation.
Avoid hover-only information.

Keyboard behavior

No component-specific keyboard behavior. Native document behavior remains unchanged.

Implementation

Use the public package API and preserve the controlled-state, native-attribute, and ref contracts described below.

tsx

import { fadeUpMotion, inViewFadeUpMotion, staggerDelay } from '@ai-created/ui';

Server Component compatible

Helpers return plain serializable-compatible Framer Motion prop objects.
staggerDelay is deterministic and supports custom step/base.
borderHoverMotion accepts a CSS color string and defaults to the strong-border token.
Consumers provide the motion.* element and semantic tag.

tsx

<motion.article {...inViewFadeUpMotion(staggerDelay(index))}>...</motion.article>

Public API

These props and helpers are compatibility contracts. Changes require migration guidance and release notes.

Prop	Type	Default	Contract
motionDuration	readonly timing object	shared values	Instant, fast, base, reveal, section, and ambient durations.
motionOffset	readonly offset object	shared values	Small, medium, large, and hover distances.
motionEase	readonly easing object	shared values	Standard, in-out, and out easing.
staggerDelay	(index, step?, base?) => number	step 0.1, base 0	Calculates a list-item delay.
fadeUpMotion	(delay?, y?, duration?) => MotionProps	shared reveal values	Returns mount animation props.
inViewFadeUpMotion	(delay?, y?, duration?) => MotionProps	shared reveal values	Returns one-time viewport reveal props.
subtleHoverMotion	(distance?) => MotionProps	2px	Returns subtle hover lift props.
borderHoverMotion	(distance?, borderColor?) => MotionProps	4px, border-strong	Returns lift plus border emphasis.

Usage guidance

These rules keep the component recognizable across products without preventing deliberate composition.

Do

Use subtle consistent motion for hierarchy changes.
Test the result with reduced motion enabled.

Do not

Do not stagger large lists so late content feels blocked.
Do not apply hover lift to controls where movement harms targeting.

Testing contract

The component should be verified as rendered UI, an interaction model, an accessibility surface, and a theme-aware visual artifact.

Unit

Constants stay immutable and helpers return exact expected prop shapes.
staggerDelay handles zero, custom base, and custom step.

Interaction

In-view fires once and hover returns to rest.
Reduced-motion configuration suppresses nonessential movement.

Accessibility

No content or state is conveyed only through movement.

Visual

Record representative entry, stagger, hover, and reduced-motion states.

Related specifications

theme themed-hero-image surface