VDL Motion System

The VDL motion system (packages/design-tokens/src/motion.css) provides centralized keyframes, easing functions, and animation utilities for the entire ecosystem.

Principles

1. Motion communicates state, not decoration -- every animation serves a purpose
2. Spring physics for interactive elements -- natural, responsive feedback
3. Staggered reveals for lists and grids -- progressive disclosure of content
4. Respect reduced motion -- all animations honor prefers-reduced-motion

Easing Functions

Standard Curves

Spring Physics (v5.0)

Spring curves simulate physical spring behavior with overshoot, creating natural-feeling interactive feedback.

Directional Curves (v5.0)

Duration Scale

Entrance Animations

Core Entrances

Usage

<!-- Card entrance -->
<div class="vdl-animate-fade-in-up">
  <h2>Vault Performance</h2>
</div>

<!-- Modal -->
<dialog class="vdl-animate-scale-in">
  <p>Confirm transaction</p>
</dialog>

Transaction Animations (v5.0)

DeFi-specific animations for transaction states and interactions.

Pending State

<!-- Breathing dot for pending transactions -->
<span class="vdl-animate-pulse-breathe">
  <span class="w-2 h-2 rounded-full bg-amber-9"></span>
</span>

vdl-pulse-breathe: Gentle scale + opacity oscillation (2s cycle). Communicates "in progress" without urgency.

Compound Ring

<!-- Expanding ring for vault compound events -->
<div class="vdl-animate-ring-expand">
  <CompoundIcon />
</div>

vdl-ring-expand: Expanding ring that fades out (1.5s cycle). Represents value being compounded into the vault.

Spring Pop

<!-- Button feedback -->
<button class="vdl-animate-spring-pop">
  Stake
</button>

vdl-spring-pop: Quick scale 0.9 → 1.05 → 1.0 with spring easing. Satisfying click feedback for primary actions.

Slide Up Spring

<!-- Bottom sheet / toast -->
<div class="vdl-animate-slide-up-spring">
  Transaction confirmed
</div>

vdl-slide-up-spring: Slides up from bottom with slight overshoot (500ms). For toasts, bottom sheets, success confirmations.

Staggered Reveals (v5.0)

Progressive disclosure for lists and grids. Children animate in sequence with a configurable delay.

Usage

<ul class="vdl-stagger-children">
  <li>First (0ms delay)</li>
  <li>Second (50ms delay)</li>
  <li>Third (100ms delay)</li>
  <!-- ... up to 8+ items -->
</ul>

Configuration

Children 1-8 get incremental delays. Children 9+ share the same maximum delay to prevent excessive wait times.

Custom Delay

.fast-stagger {
  --vdl-stagger-delay: 30ms;
}

.dramatic-stagger {
  --vdl-stagger-delay: 80ms;
}

Continuous Animations

Data Display

Tabular Numbers

<span class="vdl-data-num">1,234,567.89</span>

The .vdl-data-num class applies tabular-nums lining-nums and Inter's data-specific OpenType features. Use for all financial values to ensure columns align.

Accessibility

Reduced Motion

All VDL animations respect prefers-reduced-motion: reduce:

@media (prefers-reduced-motion: reduce) {
  .vdl-animate-* {
    animation: none;
  }
  .vdl-stagger-children > * {
    animation: none;
    opacity: 1;
    transform: none;
  }
}

When reduced motion is active:

• All animations are disabled
• Staggered children appear immediately at full opacity
• Elements snap to their final position
• Content remains fully accessible

Implementation Checklist

• Always use VDL animation classes (not custom @keyframes)
• Test with prefers-reduced-motion: reduce enabled
• Ensure no information is lost when animations are disabled
• Avoid animations that could trigger vestibular disorders (large parallax, rapid flashing)

Tailwind Animation Tokens

These are exposed in tailwind-v4.css as --animate-* values:

@theme {
  --animate-fade-in: vdl-fade-in 400ms var(--vdl-ease-smooth);
  --animate-spring-pop: vdl-spring-pop 300ms var(--vdl-ease-spring-medium);
  --animate-shimmer: vdl-shimmer 2s linear infinite;
  /* ... */
}

Usage: class="animate-fade-in", class="animate-spring-pop".