Animation Guidelines

Overview

Animation philosophy and duration/easing tokens are defined in foundations/motion.md. This guide covers the operational framework for applying them.

Every animation must pass the three gates before it ships.

The Three Gates

Before adding any animation to a Verdigris surface, it must pass all three checks:

Gate 1: Purpose

“What job does this animation do?”

The answer must be one of:

If the answer is “it looks nice” or “the competitor does it,” the animation fails Gate 1.

Gate 2: Duration Appropriate?

“Is the timing fast enough to feel responsive but slow enough to be perceived?”

Use the duration decision tree below. If the animation would need a duration outside the token scale (longer than duration.spin at 800ms), reconsider whether it belongs.

Gate 3: Reduced-Motion Fallback

“What happens when prefers-reduced-motion: reduce is active?”

Every animation must have a defined fallback. See reduced-motion.md for the full guide. If you cannot define a graceful fallback, the animation fails Gate 3.

Duration Decision Tree

Use design tokens from tokens/motion/duration.json:

Is the animation responding to direct user input (hover, click, focus)?
├── YES: Is it a simple state change (opacity, color, focus ring)?
│   ├── YES → duration.fast (150ms)
│   └── NO: Does it involve spatial movement (translate, scale)?
│       ├── Small movement (button hover, input focus) → duration.normal (200ms)
│       └── Larger movement (card lift, image zoom) → duration.moderate (300ms)
└── NO: Is it an entrance/reveal animation?
    ├── YES: Single element (hero heading, section title) → duration.slow (500ms)
    │         Staggered group (card grid, feature list) → duration.slow (500ms) per item, staggered
    └── NO: Is it continuous/looping (spinner, progress)?
        └── YES → duration.spin (800ms) with easing.linear

Token Reference

Easing Decision Tree

Use design tokens from tokens/motion/easing.json:

Is the element entering the viewport?
├── YES → easing.out (ease-out) — fast start, gentle landing
└── NO: Is the animation continuous/looping?
    ├── YES → easing.linear (linear) — constant speed, no acceleration
    └── NO → easing.default (ease) — general purpose for state transitions

Token Reference

Performance Budgets

CSS Animations

• Animate only transform and opacity. These properties are compositor-friendly and do not trigger layout or paint. Animating width, height, margin, padding, top, left, or box-shadow alone causes layout thrashing.
• Exception: box-shadow may be transitioned alongside transform for hover-lift effects (the shadow change is perceived as part of the elevation shift, and the transform is the primary animation). This is the pattern used in the www codebase:

/* From www index.css — box-shadow transitions alongside transform */
@utility hover-lift {
  transition: transform 0.3s ease, box-shadow 0.3s ease;
}

• Maximum simultaneous animations: Keep to 3 or fewer elements animating concurrently on mobile. Stagger large groups.
• No animation on page-blocking resources. Hero slide-up uses animation: slide-up 0.5s ease-out both which is CSS-only and does not block JS parsing.

WebGL / Three.js

For the waveform background (WavesBackground component):

Measurement

Use the browser Performance panel to verify:

• No layout shifts caused by animations (CLS impact = 0)
• Animation frames stay under 16ms (60fps target)
• No forced synchronous layouts in animation callbacks

Common Patterns

The Verdigris system uses a small set of repeatable animation patterns. Each is documented in its own file:

Spinner Pattern (from Patina)

@keyframes spin-around {
  0%   { transform: rotate(-90deg); }
  100% { transform: rotate(270deg); }
}

.spinner {
  animation: spin-around 800ms linear infinite; /* duration.spin + easing.linear */
}

@media (prefers-reduced-motion: reduce) {
  .spinner {
    animation: none;
    /* Show a static indicator instead — e.g., a pulsing opacity or static icon */
  }
}

Button Hover (from www)

.button-primary {
  transition: all 0.2s ease; /* duration.normal + easing.default */
}

.button-primary:hover {
  background-color: hsl(153 67% 32%); /* Darkened primary */
}

Do’s

1. Do: Use the token scale for all durations. Never hardcode a timing value that does not correspond to a token.

2. Do: Combine transform and opacity for entrance animations. The hero slide-up is the canonical example:

   @keyframes slide-up {
     from { opacity: 0; transform: translateY(30px); }
     to   { opacity: 1; transform: translateY(0); }
   }
   

3. Do: Gate all hover animations behind the compound media query (see hover-states.md).

4. Do: Test every animation with prefers-reduced-motion: reduce enabled before shipping.

Don’ts

1. Don’t: Animate width, height, margin, or padding. These trigger layout recalculation on every frame.

2. Don’t: Use animation durations longer than 800ms (duration.spin). If the animation feels like it needs more time, break it into staggered steps.

3. Don’t: Add animation without a prefers-reduced-motion fallback. This is a hard requirement, not a suggestion.

4. Don’t: Use animation-delay values greater than 300ms for interactive feedback. Users perceive delays over 300ms as broken, not animated.

5. Don’t: Use JavaScript-driven animation libraries (Framer Motion, GSAP) for effects achievable with CSS transitions and keyframes. The www codebase replaced Framer Motion with CSS slide-up for hero animations specifically to eliminate JS from the critical paint path.

Related

• foundations/motion.md — Token rationale and philosophy
• foundations/accessibility.md — WCAG requirements
• scroll-reveal.md — Intersection Observer patterns
• hover-states.md — Hover interaction patterns
• reduced-motion.md — Accessibility fallbacks
• tokens/motion/duration.json — Duration tokens
• tokens/motion/easing.json — Easing tokens