Motion Foundations
The base layer of the motion system. Defines every value, constraint, and
rule that downstream skills (motion-patterns, motion-advanced) inherit.
Load this skill before any animation work begins.
When to Activate
- Starting any animated component from scratch
- Setting up tokens, spring presets, or easing values
- Implementing
prefers-reduced-motion support
- Debugging hydration mismatches from animation initial states
- Evaluating whether an animation should exist at all
Outputs
This skill produces:
- A shared
motionTokens object (duration, easing, distance, scale)
- A shared
springs preset map (5 named configs)
- A
shouldAnimate() gate used by all components
- Accessibility-compliant animation defaults via
useReducedMotion
- SSR-safe initial states with zero hydration warnings
Principles
Motion must do at least one of the following or it must be removed:
- Guide attention
- Communicate state
- Preserve spatial continuity
Responsiveness always outranks smoothness. A 60 fps animation that causes
input delay is worse than no animation.
Rules
These are non-negotiable. They apply to every component in the system.
- Use
motion/react only. Never import from framer-motion. Never mix the two in the same tree.
initial must match server output. If the server renders opacity: 1, the initial prop must also be opacity: 1. No exceptions.
- Reduced motion overrides everything. When
useReducedMotion() returns true or prefersReduced is true, all transforms are disabled. Opacity-only fades at ≤ 0.2s are the only permitted fallback.
- Never animate layout properties.
width, height, top, left, margin, padding are banned from animate. Use transform and opacity only.
- All token values come from
motionTokens. Hardcoded durations and easings in component files are forbidden.
- All spring configs come from the
springs map. Inline stiffness/damping values are forbidden.
"use client" is required on every file that imports from motion/react.
- Never read
window or navigator at module level. Always guard with typeof window !== "undefined".
Decision Guidance
Choosing a duration
| Token |
Use when |
instant |
Tooltip show/hide, focus ring, badge update |
fast |
Button feedback, icon swap, chip toggle |
normal |
Modal open, card expand, page element enter |
slow |
Hero entrance, full-page transition |
crawl |
Deliberate storytelling; use sparingly |
Choosing a spring
| Preset |
Use when |
snappy |
Default UI — buttons, chips, nav items |
gentle |
Cards, modals, panels landing softly |
bouncy |
Playful moments — empty states, onboarding |
instant |
Tooltips, popovers, dropdowns |
release |
Drag release — natural physics feel |
When to disable animation entirely
Disable (make shouldAnimate() return false) when:
prefersReduced is true
isLowEnd is true and the animation is non-essential
- The element is off-screen and will never enter the viewport
- The animation is purely decorative with no UX purpose
Core Concepts
Token system
// lib/motion-tokens.ts
export const motionTokens = {
duration: {
instant: 0.08,
fast: 0.18,
normal: 0.35,
slow: 0.6,
crawl: 1.0,
},
easing: {
smooth: [0.22, 1, 0.36, 1],
sharp: [0.4, 0, 0.2, 1],
bounce: [0.34, 1.56, 0.64, 1],
linear: [0, 0, 1, 1],
},
distance: {
xs: 4,
sm: 8,
md: 16,
lg: 24,
xl: 48,
},
scale: {
subtle: 0.98,
press: 0.95,
pop: 1.04,
},
}
export const springs = {
snappy: { type: "spring", stiffness: 300, damping: 30 },
gentle: { type: "spring", stiffness: 120, damping: 14 },
bouncy: { type: "spring", stiffness: 400, damping: 10 },
instant: { type: "spring", stiffness: 600, damping: 35 },
release: { type: "spring", stiffness: 200, damping: 20, restDelta: 0.001 },
}
Runtime flags
// lib/motion-config.ts
export const motionConfig = {
isLowEnd() {
return (
typeof navigator !== "undefined" &&
navigator.hardwareConcurrency <= 4
)
},
prefersReduced() {
return (
typeof window !== "undefined" &&
window.matchMedia("(prefers-reduced-motion: reduce)").matches
)
},
shouldAnimate({ essential = false } = {}) {
if (this.prefersReduced()) return false
if (!essential && this.isLowEnd()) return false
return true
},
duration() {
return this.isLowEnd() || this.prefersReduced()
? motionTokens.duration.instant
: motionTokens.duration.normal
},
}
Accessibility
Priority order (highest to lowest):
prefers-reduced-motion: reduce — disables all transforms, limits opacity transitions to ≤ 0.2s
- Low-end device detection — reduces duration, removes non-essential animations
- Design preference — everything else
Motion must degrade gracefully. It must never disappear abruptly in a way
that causes layout shift or confuses orientation.
// hooks/use-reduced-motion.tsx
"use client"
import { useReducedMotion } from "motion/react"
export function useSafeMotion(fullY: number = 16) {
const reduce = useReducedMotion()
return {
initial: { opacity: 0, y: reduce ? 0 : fullY },
animate: { opacity: 1, y: 0 },
exit: { opacity: 0, y: reduce ? 0 : -fullY },
}
}
/* globals.css */
@media (prefers-reduced-motion: reduce) {
.motion-safe-transition { transition: opacity 0.15s; }
.motion-reduce-transform { transform: none !important; }
}
<!-- Tailwind -->
<div class="motion-safe:animate-fade motion-reduce:opacity-100"></div>
SSR / hydration safety
Rule: initial must always match what the server renders.
// WRONG — server renders opacity:1 but initial says 0 → hydration mismatch
<motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} />
// CORRECT — use AnimatePresence or defer to client mount
"use client"
const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])
<motion.div
initial={{ opacity: mounted ? 0 : 1 }}
animate={{ opacity: 1 }}
/>
Code Examples
End-to-end: tokens + springs + accessibility + SSR guard
// components/fade-in-card.tsx
"use client"
import { useState, useEffect } from "react"
import { motion } from "motion/react"
import { motionTokens, springs } from "@/lib/motion-tokens"
import { useSafeMotion } from "@/hooks/use-reduced-motion"
import { motionConfig } from "@/lib/motion-config"
interface FadeInCardProps {
children: React.ReactNode
delay?: number
}
export function FadeInCard({ children, delay = 0 }: FadeInCardProps) {
// SSR guard — initial must match server output (opacity: 1)
const [mounted, setMounted] = useState(false)
useEffect(() => setMounted(true), [])
// Accessibility — disables transform when reduced motion is preferred
const safeMotion = useSafeMotion(motionTokens.distance.md)
// Device gate — skip animation on low-end hardware
if (!motionConfig.shouldAnimate() || !mounted) {
return <div>{children}</div>
}
return (
<motion.div
initial={safeMotion.initial}
animate={safeMotion.animate}
exit={safeMotion.exit}
transition={{
...springs.gentle,
delay,
}}
whileHover={{ scale: motionTokens.scale.pop }}
whileTap={{ scale: motionTokens.scale.press }}
>
{children}
</motion.div>
)
}
Constraints / Non-Goals
This skill does not cover:
- UI component patterns (button, modal, stagger) → see
motion-patterns
- Drag, gestures, SVG, text animations, custom hooks → see
motion-advanced
- CSS-only animations or Tailwind
animate-* classes without motion/react
- Third-party animation libraries (GSAP, anime.js, etc.)
- Motion design decisions (when to animate, what to emphasize) — that is a design concern, not a code constraint
Anti-Patterns
| Anti-pattern |
Rule violated |
Fix |
import { motion } from "framer-motion" |
Rule 1 |
Use motion/react |
initial={{ opacity: 0 }} on SSR component |
Rule 2 |
Add mount guard |
Skipping useReducedMotion check |
Rule 3 |
Use useSafeMotion hook |
animate={{ width: "100%" }} |
Rule 4 |
Use scaleX transform instead |
transition={{ duration: 0.4 }} inline |
Rule 5 |
Use motionTokens.duration.normal |
{ stiffness: 300, damping: 30 } inline |
Rule 6 |
Use springs.snappy |
Missing "use client" directive |
Rule 7 |
Add to top of file |
navigator.hardwareConcurrency at module level |
Rule 8 |
Wrap in typeof navigator !== "undefined" |
Related Skills
motion-patterns — consumes tokens and springs defined here to build button, modal, stagger, page transition, and scroll patterns. Does not redefine any values.
motion-advanced — consumes tokens and springs defined here for drag, SVG, text, and gesture patterns. Adds useAnimate sequences and custom hooks on top of this foundation.
1---2name: motion-foundations3description: Motion tokens, spring presets, performance rules, device adaptation, accessibility enforcement, and SSR safety for React / Next.js using motion/react. Foundation layer — all other motion skills depend on this.4version: 1.05tags: [motion, animation, performance, accessibility]6category: frontend7author: jeff8metadata:9 source: https://skillmd.com/skills/mhassan0000/motion-foundations10---1112# Motion Foundations1314The base layer of the motion system. Defines every value, constraint, and15rule that downstream skills (`motion-patterns`, `motion-advanced`) inherit.16Load this skill before any animation work begins.1718## When to Activate1920- Starting any animated component from scratch21- Setting up tokens, spring presets, or easing values22- Implementing `prefers-reduced-motion` support23- Debugging hydration mismatches from animation initial states24- Evaluating whether an animation should exist at all2526## Outputs2728This skill produces:2930- A shared `motionTokens` object (duration, easing, distance, scale)31- A shared `springs` preset map (5 named configs)32- A `shouldAnimate()` gate used by all components33- Accessibility-compliant animation defaults via `useReducedMotion`34- SSR-safe initial states with zero hydration warnings3536## Principles3738Motion must do at least one of the following or it must be removed:3940- Guide attention41- Communicate state42- Preserve spatial continuity4344Responsiveness always outranks smoothness. A 60 fps animation that causes45input delay is worse than no animation.4647## Rules4849These are non-negotiable. They apply to every component in the system.50511. **Use `motion/react` only.** Never import from `framer-motion`. Never mix the two in the same tree.522. **`initial` must match server output.** If the server renders `opacity: 1`, the `initial` prop must also be `opacity: 1`. No exceptions.533. **Reduced motion overrides everything.** When `useReducedMotion()` returns `true` or `prefersReduced` is `true`, all transforms are disabled. Opacity-only fades at ≤ 0.2s are the only permitted fallback.544. **Never animate layout properties.** `width`, `height`, `top`, `left`, `margin`, `padding` are banned from `animate`. Use `transform` and `opacity` only.555. **All token values come from `motionTokens`.** Hardcoded durations and easings in component files are forbidden.566. **All spring configs come from the `springs` map.** Inline `stiffness`/`damping` values are forbidden.577. **`"use client"` is required** on every file that imports from `motion/react`.588. **Never read `window` or `navigator` at module level.** Always guard with `typeof window !== "undefined"`.5960## Decision Guidance6162### Choosing a duration6364| Token | Use when |65| --------- | -------------------------------------------- |66| `instant` | Tooltip show/hide, focus ring, badge update |67| `fast` | Button feedback, icon swap, chip toggle |68| `normal` | Modal open, card expand, page element enter |69| `slow` | Hero entrance, full-page transition |70| `crawl` | Deliberate storytelling; use sparingly |7172### Choosing a spring7374| Preset | Use when |75| --------- | ------------------------------------------ |76| `snappy` | Default UI — buttons, chips, nav items |77| `gentle` | Cards, modals, panels landing softly |78| `bouncy` | Playful moments — empty states, onboarding |79| `instant` | Tooltips, popovers, dropdowns |80| `release` | Drag release — natural physics feel |8182### When to disable animation entirely8384Disable (make `shouldAnimate()` return `false`) when:8586- `prefersReduced` is `true`87- `isLowEnd` is `true` and the animation is non-essential88- The element is off-screen and will never enter the viewport89- The animation is purely decorative with no UX purpose9091## Core Concepts9293### Token system9495```ts96// lib/motion-tokens.ts97export const motionTokens = {98 duration: {99 instant: 0.08,100 fast: 0.18,101 normal: 0.35,102 slow: 0.6,103 crawl: 1.0,104 },105 easing: {106 smooth: [0.22, 1, 0.36, 1],107 sharp: [0.4, 0, 0.2, 1],108 bounce: [0.34, 1.56, 0.64, 1],109 linear: [0, 0, 1, 1],110 },111 distance: {112 xs: 4,113 sm: 8,114 md: 16,115 lg: 24,116 xl: 48,117 },118 scale: {119 subtle: 0.98,120 press: 0.95,121 pop: 1.04,122 },123}124125export const springs = {126 snappy: { type: "spring", stiffness: 300, damping: 30 },127 gentle: { type: "spring", stiffness: 120, damping: 14 },128 bouncy: { type: "spring", stiffness: 400, damping: 10 },129 instant: { type: "spring", stiffness: 600, damping: 35 },130 release: { type: "spring", stiffness: 200, damping: 20, restDelta: 0.001 },131}132```133134### Runtime flags135136```ts137// lib/motion-config.ts138export const motionConfig = {139 isLowEnd() {140 return (141 typeof navigator !== "undefined" &&142 navigator.hardwareConcurrency <= 4143 )144 },145146 prefersReduced() {147 return (148 typeof window !== "undefined" &&149 window.matchMedia("(prefers-reduced-motion: reduce)").matches150 )151 },152153 shouldAnimate({ essential = false } = {}) {154 if (this.prefersReduced()) return false155 if (!essential && this.isLowEnd()) return false156 return true157 },158159 duration() {160 return this.isLowEnd() || this.prefersReduced()161 ? motionTokens.duration.instant162 : motionTokens.duration.normal163 },164}165```166167### Accessibility168169**Priority order (highest to lowest):**1701711. `prefers-reduced-motion: reduce` — disables all transforms, limits opacity transitions to ≤ 0.2s1722. Low-end device detection — reduces duration, removes non-essential animations1733. Design preference — everything else174175Motion must degrade gracefully. It must never disappear abruptly in a way176that causes layout shift or confuses orientation.177178```tsx179// hooks/use-reduced-motion.tsx180"use client"181import { useReducedMotion } from "motion/react"182183export function useSafeMotion(fullY: number = 16) {184 const reduce = useReducedMotion()185 return {186 initial: { opacity: 0, y: reduce ? 0 : fullY },187 animate: { opacity: 1, y: 0 },188 exit: { opacity: 0, y: reduce ? 0 : -fullY },189 }190}191```192193```css194/* globals.css */195@media (prefers-reduced-motion: reduce) {196 .motion-safe-transition { transition: opacity 0.15s; }197 .motion-reduce-transform { transform: none !important; }198}199```200201```html202<!-- Tailwind -->203<div class="motion-safe:animate-fade motion-reduce:opacity-100"></div>204```205206### SSR / hydration safety207208**Rule: `initial` must always match what the server renders.**209210```tsx211// WRONG — server renders opacity:1 but initial says 0 → hydration mismatch212<motion.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} />213214// CORRECT — use AnimatePresence or defer to client mount215"use client"216const [mounted, setMounted] = useState(false)217useEffect(() => setMounted(true), [])218219<motion.div220 initial={{ opacity: mounted ? 0 : 1 }}221 animate={{ opacity: 1 }}222/>223```224225## Code Examples226227### End-to-end: tokens + springs + accessibility + SSR guard228229```tsx230// components/fade-in-card.tsx231"use client"232233import { useState, useEffect } from "react"234import { motion } from "motion/react"235import { motionTokens, springs } from "@/lib/motion-tokens"236import { useSafeMotion } from "@/hooks/use-reduced-motion"237import { motionConfig } from "@/lib/motion-config"238239interface FadeInCardProps {240 children: React.ReactNode241 delay?: number242}243244export function FadeInCard({ children, delay = 0 }: FadeInCardProps) {245 // SSR guard — initial must match server output (opacity: 1)246 const [mounted, setMounted] = useState(false)247 useEffect(() => setMounted(true), [])248249 // Accessibility — disables transform when reduced motion is preferred250 const safeMotion = useSafeMotion(motionTokens.distance.md)251252 // Device gate — skip animation on low-end hardware253 if (!motionConfig.shouldAnimate() || !mounted) {254 return <div>{children}</div>255 }256257 return (258 <motion.div259 initial={safeMotion.initial}260 animate={safeMotion.animate}261 exit={safeMotion.exit}262 transition={{263 ...springs.gentle,264 delay,265 }}266 whileHover={{ scale: motionTokens.scale.pop }}267 whileTap={{ scale: motionTokens.scale.press }}268 >269 {children}270 </motion.div>271 )272}273```274275## Constraints / Non-Goals276277This skill does **not** cover:278279- UI component patterns (button, modal, stagger) → see `motion-patterns`280- Drag, gestures, SVG, text animations, custom hooks → see `motion-advanced`281- CSS-only animations or Tailwind `animate-*` classes without `motion/react`282- Third-party animation libraries (GSAP, anime.js, etc.)283- Motion design decisions (when to animate, what to emphasize) — that is a design concern, not a code constraint284285## Anti-Patterns286287| Anti-pattern | Rule violated | Fix |288| --------------------------------------- | ------- | ------------------------------- |289| `import { motion } from "framer-motion"` | Rule 1 | Use `motion/react` |290| `initial={{ opacity: 0 }}` on SSR component | Rule 2 | Add mount guard |291| Skipping `useReducedMotion` check | Rule 3 | Use `useSafeMotion` hook |292| `animate={{ width: "100%" }}` | Rule 4 | Use `scaleX` transform instead |293| `transition={{ duration: 0.4 }}` inline | Rule 5 | Use `motionTokens.duration.normal` |294| `{ stiffness: 300, damping: 30 }` inline | Rule 6 | Use `springs.snappy` |295| Missing `"use client"` directive | Rule 7 | Add to top of file |296| `navigator.hardwareConcurrency` at module level | Rule 8 | Wrap in `typeof navigator !== "undefined"` |297298## Related Skills299300- **`motion-patterns`** — consumes tokens and springs defined here to build button, modal, stagger, page transition, and scroll patterns. Does not redefine any values.301- **`motion-advanced`** — consumes tokens and springs defined here for drag, SVG, text, and gesture patterns. Adds `useAnimate` sequences and custom hooks on top of this foundation.