Intent

Define the semantic purpose of motion. Intent answers "WHY does this animate?" before determining "HOW does it animate?"

Standards Reference

Quick Reference

Load from: tokens/intent.tokens.json

Primary Intents

Intent Selection Guide

What's the PURPOSE of this animation?

├── User needs to understand something
│   └── CLARIFY
│       └── Measured pace, clear motion
│       └── e.g., tooltip appears, state indicator changes
│
├── User needs to find or go somewhere
│   └── GUIDE
│       └── Deliberate path, attention-directing
│       └── e.g., navigation highlight, onboarding pointer
│
├── User action needs acknowledgment
│   └── CONFIRM
│       └── Quick response, satisfying feedback
│       └── e.g., button press, form submit, toggle
│
├── User needs to be alerted
│   └── WARN
│       └── Urgent, attention-demanding
│       └── e.g., error shake, limit reached, invalid input
│
├── User achieved something
│   └── CELEBRATE
│       └── Expressive, delightful
│       └── e.g., goal completion, milestone, reward
│
└── Something new is appearing
    └── REVEAL
        └── Theatrical, anticipation-building
        └── e.g., content unlock, surprise feature, hero entrance

Intent Patterns

Clarify

Make something understood through motion.

Characteristics:

• Measured pace (duration × 1.2)
• Moderate intensity (0.4)
• Clear, readable motion
• No distracting secondary effects

Patterns: fade-in, reveal, highlight, expand-detail

Framer Motion:

const clarifyVariants = {
  hidden: { opacity: 0, y: 10 },
  visible: {
    opacity: 1,
    y: 0,
    transition: {
      duration: 0.36, // 300ms × 1.2
      ease: [0.0, 0.0, 0.2, 1] // standard-decelerate
    }
  }
};

// Clarifying tooltip
<motion.div
  variants={clarifyVariants}
  initial="hidden"
  animate="visible"
>
  {explanatoryContent}
</motion.div>

GSAP:

// Clarify intent: state indicator change
gsap.to('.status-indicator', {
  backgroundColor: '#2196F3',
  scale: 1.1,
  duration: 0.36,
  ease: 'power2.out'
});

gsap.to('.status-text', {
  opacity: 1,
  y: 0,
  duration: 0.36,
  delay: 0.1,
  ease: 'power2.out'
});

Guide

Direct attention and show the way.

Characteristics:

• Deliberate pace (duration × 1.1)
• Medium intensity (0.5)
• Demands attention without interrupting
• Clear directional motion

Patterns: slide-to, spotlight, path-trace, pointer-follow

Framer Motion:

// Guiding onboarding highlight
const guideVariants = {
  initial: {
    boxShadow: '0 0 0 0 rgba(33, 150, 243, 0)',
    scale: 1
  },
  highlight: {
    boxShadow: [
      '0 0 0 0 rgba(33, 150, 243, 0)',
      '0 0 0 8px rgba(33, 150, 243, 0.3)',
      '0 0 0 0 rgba(33, 150, 243, 0)'
    ],
    scale: [1, 1.02, 1],
    transition: {
      duration: 1.5,
      repeat: 2,
      ease: 'easeInOut'
    }
  }
};

GSAP:

// Guide intent: navigation spotlight
const spotlight = gsap.timeline({ repeat: 2 });

spotlight.to('.target-element', {
  boxShadow: '0 0 0 8px rgba(33, 150, 243, 0.3)',
  scale: 1.02,
  duration: 0.75,
  ease: 'power2.inOut'
})
.to('.target-element', {
  boxShadow: '0 0 0 0 rgba(33, 150, 243, 0)',
  scale: 1,
  duration: 0.75,
  ease: 'power2.inOut'
});

Confirm

Acknowledge user action immediately.

Characteristics:

• Responsive pace (duration × 0.9)
• Medium-high intensity (0.6)
• Satisfying, tactile feel
• Often paired with haptic feedback

Patterns: scale-pulse, checkmark, color-flash, ripple

Framer Motion:

// Confirm intent: button press
const confirmVariants = {
  idle: { scale: 1 },
  pressed: {
    scale: 0.95,
    transition: { duration: 0.05 }
  },
  confirmed: {
    scale: [0.95, 1.05, 1],
    transition: {
      duration: 0.27, // 300ms × 0.9
      times: [0, 0.5, 1],
      type: 'spring',
      stiffness: 300,
      damping: 15
    }
  }
};

// With checkmark
const checkmarkVariants = {
  hidden: { pathLength: 0, opacity: 0 },
  visible: {
    pathLength: 1,
    opacity: 1,
    transition: {
      pathLength: { duration: 0.3, ease: 'easeOut' },
      opacity: { duration: 0.1 }
    }
  }
};

GSAP:

// Confirm intent: form field validation
function confirmValid(field) {
  gsap.timeline()
    .to(field, {
      borderColor: '#4CAF50',
      duration: 0.1
    })
    .to('.checkmark', {
      scale: 1,
      opacity: 1,
      duration: 0.27,
      ease: 'back.out(2)'
    }, '-=0.05');
}

Warn

Alert user to problems urgently.

Characteristics:

• Urgent pace (duration × 0.85)
• High intensity (0.8)
• Demands immediate attention
• Often includes repetition

Patterns: shake, pulse-ring, flash-border, bounce-reject

Important: Never rely on motion alone for warnings. Pair with color, icon, and text.

Framer Motion:

// Warn intent: error shake
const warnVariants = {
  shake: {
    x: [0, -10, 10, -10, 10, 0],
    transition: {
      duration: 0.4,
      times: [0, 0.2, 0.4, 0.6, 0.8, 1],
      ease: 'easeInOut'
    }
  }
};

// Warn intent: pulse ring
const pulseRingVariants = {
  pulse: {
    boxShadow: [
      '0 0 0 0 rgba(244, 67, 54, 0.4)',
      '0 0 0 10px rgba(244, 67, 54, 0)',
    ],
    transition: {
      duration: 0.8,
      repeat: 1
    }
  }
};

GSAP:

// Warn intent: invalid input
function warnInvalid(input) {
  gsap.timeline()
    .to(input, {
      x: 10,
      duration: 0.08,
      ease: 'power2.inOut',
      repeat: 3,
      yoyo: true
    })
    .to(input, {
      borderColor: '#f44336',
      duration: 0.1
    }, 0);
}

Celebrate

Mark achievements with joy.

Characteristics:

• Expressive pace (duration × 1.3)
• Maximum intensity (1.0)
• Secondary effects enabled (particles, glows)
• Extended for savoring

Patterns: burst, confetti, scale-bounce, glow-pulse, particle-shower

Framer Motion:

// Celebrate intent: success burst
const celebrateVariants = {
  initial: { scale: 0, opacity: 0 },
  celebrate: {
    scale: [0, 1.3, 1],
    opacity: 1,
    transition: {
      duration: 0.39, // 300ms × 1.3
      type: 'spring',
      stiffness: 200,
      damping: 10
    }
  }
};

// With glow
const glowVariants = {
  glow: {
    boxShadow: [
      '0 0 20px rgba(76, 175, 80, 0)',
      '0 0 40px rgba(76, 175, 80, 0.5)',
      '0 0 20px rgba(76, 175, 80, 0)'
    ],
    transition: { duration: 0.8 }
  }
};

Reveal

Unveil new content theatrically.

Characteristics:

• Theatrical pace (duration × 1.4)
• Medium-high intensity (0.7)
• Anticipation phase (25% of duration)
• Dramatic easing

Patterns: curtain-pull, mask-reveal, blur-to-sharp, emerge-from-depth

Framer Motion:

// Reveal intent: content unlock
const revealVariants = {
  hidden: {
    opacity: 0,
    filter: 'blur(10px)',
    scale: 0.9
  },
  revealed: {
    opacity: 1,
    filter: 'blur(0px)',
    scale: 1,
    transition: {
      duration: 0.42, // 300ms × 1.4
      ease: [0.05, 0.7, 0.1, 1]
    }
  }
};

Intent Combinations

Common intent sequences:

Context Modifiers

Reduced Motion

For prefers-reduced-motion: reduce:

Cross-References

• See emotional-journey/ for emotion-intent mapping
• See narrative-arc/ for intent intensity within story phases
• See consequence/ for intent triggering chains
• See easing/ for intent-appropriate curves

References

• references/intent-parameter-map.md — Complete parameter mappings