CSS Animations and Transitions Explained — Timing, Keyframes and Real-World Patterns

/* ── Base button styles ──────────────────────────────────────── */
.cta-button {
  display: inline-block;
  padding: 14px 28px;
  background-color: #4f46e5;   /* indigo-600 */
  color: #ffffff;
  border: none;
  border-radius: 8px;
  font-size: 1rem;
  font-weight: 600;
  cursor: pointer;

  /*
   * ALWAYS put transition on the base state, not the :hover.
   * This ensures the animation plays when the user LEAVES the
   * hover state too — not just when they enter it.
   *
   * Syntax: transition: property duration timing-function delay;
   * We're transitioning TWO properties, separated by a comma.
   * transform handles the lift; background-color handles the tint.
   */
  transition:
    transform 180ms ease-out,
    background-color 180ms ease-out,
    box-shadow 180ms ease-out;
}

/* ── Hover state — only define the DESTINATION, not the motion ─ */
.cta-button:hover {
  background-color: #4338ca;   /* slightly darker indigo-700 */

  /*
   * translateY(-3px) nudges the button UP by 3px.
   * We use transform instead of changing margin-top or top
   * because transform lives on the compositor thread —
   * the browser can animate it without touching layout at all.
   */
  transform: translateY(-3px);
  box-shadow: 0 8px 20px rgba(79, 70, 229, 0.4);
}

/* ── Active (click) state — snap down fast for tactile feel ───── */
.cta-button:active {
  transform: translateY(0px);   /* returns to baseline instantly */
  box-shadow: none;
  transition-duration: 80ms;    /* faster on click = feels snappy */
}

/* ── Keyframe definition — the choreography script ───────────── */
/*
 * This creates a 'pulse-ring' effect used on notification badges,
 * live indicators, and 'recording' dots across most modern SaaS apps.
 * The ring expands outward and fades simultaneously.
 */
@keyframes pulse-ring {
  0% {
    /*
     * Start at true size, fully visible.
     * scale(1) = no scaling applied yet.
     */
    transform: scale(1);
    opacity: 0.75;
  }
  70% {
    /*
     * Expand to 1.6× the original size by the 70% mark.
     * We go past halfway before starting to fade so the
     * expansion is visible before it disappears.
     */
    transform: scale(1.6);
    opacity: 0;
  }
  100% {
    /* Reset cleanly so the next loop starts at scale(1). */
    transform: scale(1.6);
    opacity: 0;
  }
}

/* ── The live indicator dot ───────────────────────────────────── */
.live-indicator {
  position: relative;
  display: inline-flex;
  align-items: center;
  gap: 8px;
}

.live-dot {
  width: 12px;
  height: 12px;
  border-radius: 50%;
  background-color: #22c55e;   /* green-500 */
}

/* ── The expanding ring — a pseudo-element clone of the dot ────── */
.live-dot::before {
  content: '';
  position: absolute;
  inset: 0;                    /* shorthand for top/right/bottom/left: 0 */
  border-radius: 50%;
  background-color: #22c55e;

  /*
   * animation shorthand breakdown:
   *   pulse-ring   → @keyframes name
   *   1.5s         → one cycle takes 1.5 seconds
   *   ease-out     → starts fast, eases to a stop (feels natural for expansion)
   *   0s           → no delay on first play
   *   infinite     → keep looping forever
   *
   * We animate the ::before pseudo-element so the base
   * .live-dot stays visually stable at the centre.
   */
  animation: pulse-ring 1.5s ease-out 0s infinite;
}

/* ── Respect users who prefer reduced motion ─────────────────── */
/*
 * This is NOT optional. Users with vestibular disorders
 * can experience nausea from looping animations.
 * prefers-reduced-motion is the accessibility escape hatch.
 */
@media (prefers-reduced-motion: reduce) {
  .live-dot::before {
    animation: none;    /* kill the animation entirely for affected users */
  }
}

/* ── Keyframes for the card entrance ─────────────────────────── */
@keyframes card-enter {
  from {
    /*
     * Cards start 20px below their natural position AND invisible.
     * translateY(20px) moves DOWN (positive Y = down in CSS).
     * We move them UP to 0 as the animation plays.
     */
    opacity: 0;
    transform: translateY(20px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

/* ── Each card starts invisible and slides up into place ──────── */
.feature-card {
  opacity: 0;   /* start hidden BEFORE the animation begins */

  /*
   * animation-fill-mode: both
   *   'backwards' → apply the 'from' keyframe during the delay period
   *                 (prevents flash of the element before delay expires)
   *   'forwards'  → hold the 'to' keyframe after animation completes
   *   'both'      → does both of the above — almost always what you want
   *
   * animation-delay reads the CSS custom property --stagger-index.
   * Each card sets its own index inline: style="--stagger-index: 2"
   * so the delay = index × 80ms (0, 80ms, 160ms, 240ms...)
   */
  animation:
    card-enter
    400ms
    cubic-bezier(0.16, 1, 0.3, 1)   /* ease-out-expo — fast then soft landing */
    calc(var(--stagger-index, 0) * 80ms)
    both;
}

/*
 * HTML usage (in your template/JSX):
 *
 * <div class="feature-card" style="--stagger-index: 0">Card One</div>
 * <div class="feature-card" style="--stagger-index: 1">Card Two</div>
 * <div class="feature-card" style="--stagger-index: 2">Card Three</div>
 * <div class="feature-card" style="--stagger-index: 3">Card Four</div>
 */

/* ── Reduced motion override ──────────────────────────────────── */
@media (prefers-reduced-motion: reduce) {
  .feature-card {
    animation: none;
    opacity: 1;   /* make sure cards are visible even with no animation */
  }
}