css-foundations

name	css-foundations
description	Unified CSS/styling foundations — CSS architecture (modules, CSS-in-JS, cascade layers, container queries), CSS custom properties (design tokens, theming, runtime manipulation), CSS Grid (templates, auto-placement, subgrid), dark mode implementation, responsive design patterns (fluid typography, container queries, aspect ratios), general animation patterns, Framer Motion, Tailwind animate plugin.
layer	domain
category	frontend
triggers	["--color","@layer","AnimatePresence","CSS-in-JS","GSAP","animate-in","animate-out","animation","auto-fill","auto-fit","breakpoint","cascade layer","color scheme","container query","css animation","css architecture","css custom properties","css custom property","css grid","css module","css nesting","css scope","css var","css variable","css variables","dark mode","dark theme","design token","fluid typography","framer motion","framer-motion","grid area","grid layout","grid template","keyframes","layoutId","light mode","logical properties","looks bad on mobile","micro-interaction","mobile first","mobile layout","mobile responsive","motion","motion.div","page transition","prefers-color-scheme","responsive design","responsive grid","scroll animation","spring animation","styled-components","subgrid","tablet layout","tailwind animate","tailwind animation","tailwind keyframes","tailwindcss-animate","theme switch","theme toggle","transition","useAnimate","whileHover","whileTap"]

css-foundations

Unified CSS/styling foundations — CSS architecture (modules, CSS-in-JS, cascade layers, container queries), CSS custom properties (design tokens, theming, runtime manipulation), CSS Grid (templates, auto-placement, subgrid), dark mode implementation, responsive design patterns (fluid typography, container queries, aspect ratios), general animation patterns, Framer Motion, Tailwind animate plugin.

Absorbs

• css-architecture
• css-variables
• css-grid
• dark-mode
• responsive-design
• animation
• framer-motion
• tailwind-animate

---

From css-architecture

CSS architecture patterns — CSS modules, CSS-in-JS, cascade layers, container queries, logical properties, and scalable styling strategies

CSS Architecture Patterns

Purpose

Provide expert guidance on scalable CSS architecture using modern features: cascade layers, container queries, CSS nesting, logical properties, custom properties, and the tradeoffs between CSS modules, CSS-in-JS, and utility-first approaches. Focus on maintainability, specificity control, and progressive enhancement.

Key Patterns

Cascade Layers (@layer)

Layers give explicit control over specificity ordering, regardless of selector specificity or source order:

/* Define layer order — first declared = lowest priority */
@layer reset, base, tokens, components, utilities, overrides;

/* Reset layer — lowest specificity */
@layer reset {
  *, *::before, *::after {
    box-sizing: border-box;
    margin: 0;
    padding: 0;
  }

  html {
    -webkit-text-size-adjust: 100%;
    text-size-adjust: 100%;
  }
}

/* Base layer — element defaults */
@layer base {
  body {
    font-family: var(--font-sans);
    font-size: var(--text-base);
    line-height: 1.6;
    color: var(--color-text-primary);
    background-color: var(--color-surface);
  }

  a {
    color: var(--color-link);
    text-decoration-thickness: 1px;
    text-underline-offset: 0.15em;
  }

  img, video, svg {
    display: block;
    max-width: 100%;
    height: auto;
  }
}

/* Token layer — design tokens as custom properties */
@layer tokens {
  :root {
    --color-brand-500: oklch(0.55 0.18 250);
    --color-brand-600: oklch(0.48 0.18 250);
    --color-text-primary: oklch(0.15 0.02 250);
    --color-text-secondary: oklch(0.45 0.03 250);
    --color-surface: oklch(0.99 0.005 250);
    --color-border: oklch(0.85 0.02 250);
    --color-link: var(--color-brand-600);

    --font-sans: system-ui, -apple-system, sans-serif;
    --font-mono: 'JetBrains Mono', ui-monospace, monospace;

    --text-sm: 0.875rem;
    --text-base: 1rem;
    --text-lg: 1.125rem;
    --text-xl: 1.25rem;
    --text-2xl: 1.625rem;

    --space-1: 0.25rem;
    --space-2: 0.5rem;
    --space-3: 0.75rem;
    --space-4: 1rem;
    --space-6: 1.5rem;
    --space-8: 2rem;
    --space-12: 3rem;
    --space-16: 4rem;

    --radius-md: 0.5rem;
    --radius-lg: 0.75rem;
    --radius-xl: 1rem;

    --shadow-sm: 0 1px 2px oklch(0 0 0 / 0.05);
    --shadow-md: 0 4px 6px -1px oklch(0 0 0 / 0.1);
  }

  /* Dark mode tokens */
  @media (prefers-color-scheme: dark) {
    :root {
      --color-text-primary: oklch(0.95 0.01 250);
      --color-text-secondary: oklch(0.70 0.02 250);
      --color-surface: oklch(0.13 0.02 250);
      --color-border: oklch(0.30 0.02 250);
    }
  }
}

/* Components layer — all component styles */
@layer components {
  .btn {
    display: inline-flex;
    align-items: center;
    justify-content: center;
    padding: var(--space-4) var(--space-6);
    min-height: 2.625rem;
    font-size: var(--text-base);
    font-weight: 500;
    border-radius: var(--radius-md);
    transition: all 200ms ease;
    cursor: pointer;

    &:focus-visible {
      outline: 2px solid var(--color-brand-500);
      outline-offset: 2px;
    }

    &:disabled {
      opacity: 0.5;
      pointer-events: none;
    }
  }
}

/* Utilities layer — high specificity utility classes */
@layer utilities {
  .sr-only {
    position: absolute;
    width: 1px;
    height: 1px;
    padding: 0;
    margin: -1px;
    overflow: hidden;
    clip: rect(0, 0, 0, 0);
    white-space: nowrap;
    border: 0;
  }

  .truncate {
    overflow: hidden;
    text-overflow: ellipsis;
    white-space: nowrap;
  }
}

/* Overrides layer — highest priority, escape hatch */
@layer overrides {
  /* Third-party library style fixes */
}

Why layers matter: Without layers, a .btn class with specificity 0-1-0 can be overridden by any element selector in a later stylesheet. With layers, component styles always beat base styles regardless of specificity.

Container Queries

Style children based on parent size, not viewport:

/* Define containment context */
.card-grid {
  container-type: inline-size;
  container-name: card-grid;
}

/* Respond to container width */
@container card-grid (min-width: 40rem) {
  .card {
    flex-direction: row;
    gap: var(--space-6);
  }

  .card-image {
    width: 40%;
    flex-shrink: 0;
  }
}

@container card-grid (min-width: 60rem) {
  .card {
    gap: var(--space-8);
  }

  .card-title {
    font-size: var(--text-xl);
  }
}

/* Container query units */
.card-title {
  font-size: clamp(var(--text-base), 3cqi, var(--text-xl));
  /* cqi = 1% of container inline size */
}

When to use containers vs media queries:

• Container queries: Component-level responsiveness (cards, widgets, sidebars)
• Media queries: Page-level layout changes (grid columns, section padding)

CSS Nesting

Native nesting reduces repetition and improves readability:

.card {
  padding: var(--space-6);
  border-radius: var(--radius-lg);
  background: var(--color-surface);
  box-shadow: var(--shadow-sm);
  transition: all 200ms ease;

  /* Hover state */
  &:hover {
    box-shadow: var(--shadow-md);
    transform: translateY(-1px);
  }

  /* Focus-visible for keyboard navigation */
  &:focus-visible {
    outline: 2px solid var(--color-brand-500);
    outline-offset: 2px;
  }

  /* Child elements */
  & .card-title {
    font-size: var(--text-lg);
    font-weight: 600;
    color: var(--color-text-primary);
    margin-block-end: var(--space-2);
  }

  & .card-body {
    font-size: var(--text-base);
    color: var(--color-text-secondary);
    line-height: 1.6;
  }

  /* Modifier patterns */
  &.is-featured {
    border-left: 4px solid var(--color-brand-500);
  }

  /* Responsive via media query inside component */
  @media (min-width: 48rem) {
    padding: var(--space-8);
  }

  /* Reduced motion */
  @media (prefers-reduced-motion: reduce) {
    transition: none;

    &:hover {
      transform: none;
    }
  }
}

Logical Properties

Use logical properties for internationalization-ready layouts:

.component {
  /* Instead of directional properties */
  margin-block-start: var(--space-4);    /* margin-top */
  margin-block-end: var(--space-4);      /* margin-bottom */
  margin-inline-start: var(--space-6);   /* margin-left in LTR */
  margin-inline-end: var(--space-6);     /* margin-right in LTR */

  padding-block: var(--space-4);         /* top + bottom */
  padding-inline: var(--space-6);        /* left + right (LTR) */

  border-inline-start: 3px solid var(--color-brand-500);  /* border-left in LTR */

  /* Sizing */
  inline-size: 100%;         /* width */
  max-inline-size: 40rem;    /* max-width */
  block-size: auto;          /* height */
  min-block-size: 2.625rem;  /* min-height */

  /* Positioning */
  inset-block-start: 0;      /* top */
  inset-inline-end: 0;       /* right in LTR */
}

CSS Modules

Scoped class names without runtime cost:

/* components/card.module.css */
.root {
  padding: var(--space-6);
  border-radius: var(--radius-lg);
  background: var(--color-surface);
  box-shadow: var(--shadow-sm);
  transition: all 200ms ease;
}

.root:hover {
  box-shadow: var(--shadow-md);
}

.title {
  font-size: var(--text-lg);
  font-weight: 600;
  composes: truncate from './utils.module.css';
}

.body {
  color: var(--color-text-secondary);
}

// components/card.tsx
import styles from './card.module.css';
import { cn } from '@/lib/utils';

export function Card({ className, ...props }: CardProps) {
  return (
    <div className={cn(styles.root, className)} {...props}>
      <h3 className={styles.title}>{props.title}</h3>
      <div className={styles.body}>{props.children}</div>
    </div>
  );
}

Custom Properties (Advanced)

Dynamic theming with custom properties:

/* Component-scoped custom properties */
.btn {
  --btn-bg: var(--color-brand-600);
  --btn-color: white;
  --btn-border: transparent;
  --btn-hover-bg: var(--color-brand-700);

  background: var(--btn-bg);
  color: var(--btn-color);
  border: 1px solid var(--btn-border);

  &:hover {
    background: var(--btn-hover-bg);
  }

  /* Variants override the custom properties */
  &.btn-secondary {
    --btn-bg: transparent;
    --btn-color: var(--color-text-primary);
    --btn-border: var(--color-border);
    --btn-hover-bg: oklch(0 0 0 / 0.05);
  }

  &.btn-ghost {
    --btn-bg: transparent;
    --btn-color: var(--color-text-secondary);
    --btn-border: transparent;
    --btn-hover-bg: oklch(0 0 0 / 0.05);
  }
}

Responsive tokens with clamp:

:root {
  /* Fluid typography */
  --text-fluid-base: clamp(1rem, 0.5vw + 0.875rem, 1.125rem);
  --text-fluid-xl: clamp(1.25rem, 1.5vw + 0.875rem, 2rem);
  --text-fluid-3xl: clamp(2rem, 3vw + 1rem, 3.5rem);

  /* Fluid spacing */
  --space-fluid-section: clamp(3rem, 5vw + 1rem, 6rem);
}

@scope (CSS Scoping)

Limit style reach to a specific DOM subtree:

@scope (.card) to (.card-actions) {
  /* Styles only apply inside .card but stop before .card-actions */
  p {
    color: var(--color-text-secondary);
    line-height: 1.6;
  }

  a {
    color: var(--color-brand-600);
  }
}

Choosing a CSS Strategy

Approach	Best For	Tradeoffs
Tailwind CSS	Rapid development, consistent design	Large class strings, learning curve
CSS Modules	Scoped styles, zero runtime, SSR	No dynamic styles, verbose imports
Vanilla CSS (layers)	Full control, modern features	Manual scoping, larger teams need conventions
CSS-in-JS (Panda/Vanilla Extract)	Type-safe styles, design systems	Build complexity, zero-runtime options limited

Recommendation for most projects: Tailwind CSS + CSS Modules for edge cases (third-party styling, complex selectors).

Best Practices

1. Use cascade layers — Control specificity explicitly rather than fighting it with !important.
2. Custom properties for theming — Define tokens as CSS custom properties for runtime theming and dark mode.
3. Container queries for components — Components should respond to their container, not the viewport.
4. Logical properties — Use block/inline terminology for RTL/LTR support.
5. clamp() for fluid design — Replace breakpoint-based font/spacing jumps with smooth scaling.
6. Minimize nesting depth — Keep CSS nesting to 3 levels max for readability.
7. Prefer :where() for low-specificity defaults — :where(.btn) has zero specificity, easy to override.
8. Use :is() for grouping — :is(h1, h2, h3) { ... } instead of repeating selectors.
9. prefers-reduced-motion — Always provide reduced-motion alternatives for animations.
10. No !important — If you need it, your layer architecture needs fixing.

Common Pitfalls

Pitfall	Problem	Fix
Specificity wars	!important chains, fragile overrides	Use @layer for explicit ordering
Global styles leaking	Components affected by unrelated styles	CSS Modules, @scope, or Tailwind
Fixed viewport breakpoints	Components break when placed in sidebars	Container queries for component styles
Directional properties	Broken in RTL languages	Logical properties (margin-inline-start)
Overusing nesting	Deep selectors, high specificity	Max 3 levels, use flat class names
Forgetting dark mode	Variables reset unexpectedly	Test both themes, use semantic tokens
calc() units mismatch	calc(100% - 16px) mixed units	Consistent units, test edge cases
Missing fallbacks for new features	Broken in older browsers	@supports queries for progressive enhancement

---

From css-variables

CSS custom properties for design tokens, theming, dynamic styles, dark mode, and runtime theme switching without JavaScript

CSS Variables Specialist

Purpose

CSS custom properties (variables) are the foundation of modern theming, design token systems, and dynamic styling. Unlike preprocessor variables (Sass/Less), CSS variables are live in the browser — they cascade, inherit, can be scoped to any selector, and can be changed at runtime without JavaScript. This skill covers architecture, theming patterns, performance, and integration with frameworks.

Key Concepts

Custom Properties vs Preprocessor Variables

Feature	CSS Custom Properties	Sass Variables
Runtime changes	Yes (live in DOM)	No (compiled away)
Cascade/inheritance	Yes	No
Scoped to selectors	Yes	Scoped to blocks
Media query responsive	Yes	No
JavaScript access	getComputedStyle / setProperty	Not possible
Fallback values	var(--x, fallback)	Default params

The Variable Cascade

/* Variables cascade and inherit just like any CSS property */
:root {
  --color-primary: #2563eb;     /* Global default */
}

.card {
  --color-primary: #7c3aed;     /* Scoped override — only .card and children */
}

.card .button {
  background: var(--color-primary);  /* Gets #7c3aed, not #2563eb */
}

Workflow

Step 1: Define Design Token Layers

Organize variables in semantic layers — primitive tokens feed semantic tokens which feed component tokens:

/* === Layer 1: Primitive Tokens (raw values) === */
:root {
  /* Colors — scale */
  --blue-50: #eff6ff;
  --blue-100: #dbeafe;
  --blue-200: #bfdbfe;
  --blue-300: #93c5fd;
  --blue-400: #60a5fa;
  --blue-500: #3b82f6;
  --blue-600: #2563eb;
  --blue-700: #1d4ed8;
  --blue-800: #1e40af;
  --blue-900: #1e3a8a;
  --blue-950: #172554;

  --gray-50: #f9fafb;
  --gray-100: #f3f4f6;
  --gray-200: #e5e7eb;
  --gray-300: #d1d5db;
  --gray-400: #9ca3af;
  --gray-500: #6b7280;
  --gray-600: #4b5563;
  --gray-700: #374151;
  --gray-800: #1f2937;
  --gray-900: #111827;
  --gray-950: #030712;

  /* Spacing — based on 4px grid */
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-3: 0.75rem;
  --space-4: 1rem;
  --space-6: 1.5rem;
  --space-8: 2rem;
  --space-12: 3rem;
  --space-16: 4rem;

  /* Typography */
  --font-sans: 'Inter', system-ui, -apple-system, sans-serif;
  --font-mono: 'JetBrains Mono', ui-monospace, monospace;

  --text-xs: 0.75rem;
  --text-sm: 0.875rem;
  --text-base: 1rem;
  --text-lg: 1.125rem;
  --text-xl: 1.25rem;
  --text-2xl: 1.5rem;
  --text-3xl: 1.875rem;

  /* Radii */
  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
  --radius-lg: 0.75rem;
  --radius-xl: 1rem;
  --radius-2xl: 1.5rem;
  --radius-full: 9999px;

  /* Shadows */
  --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
  --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1);
}

/* === Layer 2: Semantic Tokens (purpose-driven) === */
:root {
  /* Surfaces */
  --color-bg: var(--gray-50);
  --color-bg-elevated: #ffffff;
  --color-bg-sunken: var(--gray-100);
  --color-bg-overlay: rgb(0 0 0 / 0.5);

  /* Text */
  --color-text: var(--gray-900);
  --color-text-secondary: var(--gray-600);
  --color-text-tertiary: var(--gray-400);
  --color-text-inverse: #ffffff;

  /* Interactive */
  --color-primary: var(--blue-600);
  --color-primary-hover: var(--blue-700);
  --color-primary-active: var(--blue-800);
  --color-primary-subtle: var(--blue-50);

  /* Feedback */
  --color-success: #16a34a;
  --color-warning: #d97706;
  --color-error: #dc2626;
  --color-info: var(--blue-500);

  /* Borders */
  --color-border: var(--gray-200);
  --color-border-strong: var(--gray-300);
  --color-border-focus: var(--blue-500);

  /* Transitions */
  --duration-fast: 150ms;
  --duration-normal: 200ms;
  --duration-slow: 300ms;
  --ease-default: cubic-bezier(0.4, 0, 0.2, 1);
}

/* === Layer 3: Component Tokens (optional, for complex systems) === */
:root {
  --button-bg: var(--color-primary);
  --button-bg-hover: var(--color-primary-hover);
  --button-text: var(--color-text-inverse);
  --button-radius: var(--radius-md);
  --button-padding: var(--space-4) var(--space-6);

  --card-bg: var(--color-bg-elevated);
  --card-border: var(--color-border);
  --card-radius: var(--radius-xl);
  --card-padding: var(--space-6);
  --card-shadow: var(--shadow-sm);

  --input-bg: var(--color-bg-elevated);
  --input-border: var(--color-border);
  --input-border-focus: var(--color-border-focus);
  --input-radius: var(--radius-md);
  --input-padding: var(--space-3) var(--space-4);
}

Step 2: Implement Dark Mode

/* Dark theme via data attribute (preferred — no FOUC) */
[data-theme="dark"] {
  --color-bg: var(--gray-950);
  --color-bg-elevated: var(--gray-900);
  --color-bg-sunken: var(--gray-800);

  --color-text: var(--gray-50);
  --color-text-secondary: var(--gray-400);
  --color-text-tertiary: var(--gray-600);

  --color-primary: var(--blue-400);
  --color-primary-hover: var(--blue-300);
  --color-primary-active: var(--blue-200);
  --color-primary-subtle: rgb(59 130 246 / 0.15);

  --color-border: var(--gray-800);
  --color-border-strong: var(--gray-700);

  --card-shadow: 0 4px 6px -1px rgb(0 0 0 / 0.3);
}

/* Respect system preference as fallback */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --color-bg: var(--gray-950);
    --color-bg-elevated: var(--gray-900);
    /* ...same overrides... */
  }
}

Step 3: Theme Switching with JavaScript

type Theme = 'light' | 'dark' | 'system';

function setTheme(theme: Theme): void {
  const root = document.documentElement;

  if (theme === 'system') {
    root.removeAttribute('data-theme');
    localStorage.removeItem('theme');
  } else {
    root.setAttribute('data-theme', theme);
    localStorage.setItem('theme', theme);
  }
}

// Initialize on page load (put in <head> to prevent FOUC)
function initTheme(): void {
  const stored = localStorage.getItem('theme') as Theme | null;
  if (stored && stored !== 'system') {
    document.documentElement.setAttribute('data-theme', stored);
  }
}

<!-- Anti-FOUC script — place in <head> before any CSS -->
<script>
  (function() {
    var t = localStorage.getItem('theme');
    if (t === 'dark' || t === 'light') {
      document.documentElement.setAttribute('data-theme', t);
    }
  })();
</script>

Step 4: Dynamic Values at Runtime

// Read a CSS variable value
const primaryColor = getComputedStyle(document.documentElement)
  .getPropertyValue('--color-primary')
  .trim();

// Set a CSS variable dynamically
document.documentElement.style.setProperty('--color-primary', '#e11d48');

// Scoped to a specific element
const card = document.querySelector('.card');
card.style.setProperty('--card-bg', 'linear-gradient(135deg, #667eea, #764ba2)');

/* Use dynamic values from JavaScript for animations */
.progress-bar {
  width: var(--progress, 0%);
  transition: width var(--duration-normal) var(--ease-default);
}

// Animate progress
element.style.setProperty('--progress', '75%');

Step 5: Integration with Tailwind CSS v4

/* Tailwind v4 uses CSS variables natively */
@theme {
  --color-primary: #2563eb;
  --color-primary-hover: #1d4ed8;
  --color-surface: #ffffff;
  --color-surface-elevated: #f9fafb;
  --radius-card: 0.75rem;
}

<!-- Use directly in Tailwind classes -->
<div class="bg-(--color-surface) rounded-(--radius-card) shadow-sm">
  <button class="bg-(--color-primary) hover:bg-(--color-primary-hover)">
    Click
  </button>
</div>

Step 6: Responsive Variables with Media Queries

:root {
  --content-width: 90vw;
  --section-padding: var(--space-8);
  --heading-size: var(--text-2xl);
}

@media (min-width: 768px) {
  :root {
    --content-width: 80vw;
    --section-padding: var(--space-12);
    --heading-size: var(--text-3xl);
  }
}

@media (min-width: 1280px) {
  :root {
    --content-width: min(70vw, 80rem);
    --section-padding: var(--space-16);
  }
}

Best Practices

• Use the three-layer token architecture: primitive, semantic, component
• Name semantic tokens by purpose, not value (--color-text, not --dark-gray)
• Always provide fallback values for critical variables: var(--color-bg, #ffffff)
• Use data-theme attribute instead of class for theme switching (cleaner specificity)
• Put the anti-FOUC script in <head> before stylesheets
• Avoid deeply nested var() references (max 3 levels deep for readability)
• Use CSS variables for anything that changes between themes, breakpoints, or states
• Keep primitive tokens private (prefix with --_ if convention helps) and expose only semantic tokens

Common Pitfalls

Pitfall	Fix
Flash of unstyled content (FOUC) on theme switch	Add inline <script> in <head> to set data-theme before CSS loads
Variables not inheriting across Shadow DOM	Pass variables through :host or use ::part() selectors
Performance issues with thousands of variables	Only define variables you use; avoid generating unused scales
Fallback value not working as expected	var(--x, red) uses fallback only when --x is not set — not when it is invalid
Dark mode contrast failures	Test with WCAG contrast checker; dark themes often need lighter text than expected
Circular references causing silent failure	CSS silently ignores circular var() references — browser DevTools will show invalid
Using variables inside url()	url(var(--bg-image)) does NOT work — use background shorthand or JS instead

Examples

Multi-Brand Theming

/* Brand A */
[data-brand="alpha"] {
  --color-primary: #2563eb;
  --color-primary-hover: #1d4ed8;
  --font-sans: 'Inter', sans-serif;
  --radius-md: 0.5rem;
}

/* Brand B */
[data-brand="beta"] {
  --color-primary: #7c3aed;
  --color-primary-hover: #6d28d9;
  --font-sans: 'Plus Jakarta Sans', sans-serif;
  --radius-md: 1rem;
}

/* Components use semantic tokens — zero brand-specific code */
.button {
  background: var(--color-primary);
  font-family: var(--font-sans);
  border-radius: var(--radius-md);
  padding: var(--space-4) var(--space-6);
  color: var(--color-text-inverse);
  transition: background var(--duration-fast) var(--ease-default);
}

.button:hover {
  background: var(--color-primary-hover);
}

Color with Opacity Using Modern CSS

:root {
  /* Store as raw channels for opacity flexibility */
  --primary-rgb: 37 99 235;
  --error-rgb: 220 38 38;
}

.overlay {
  /* Use with modern color functions */
  background: rgb(var(--primary-rgb) / 0.1);
  border: 1px solid rgb(var(--primary-rgb) / 0.3);
}

/* Or use oklch for perceptually uniform colors */
:root {
  --primary-oklch: 0.55 0.2 260;
}

.button {
  background: oklch(var(--primary-oklch));
}

.button:hover {
  background: oklch(var(--primary-oklch) / 0.9);
}

React Component with CSS Variables

interface ProgressProps {
  value: number;
  color?: string;
}

function Progress({ value, color }: ProgressProps) {
  return (
    <div
      className="progress"
      style={{
        '--progress-value': `${Math.min(100, Math.max(0, value))}%`,
        '--progress-color': color,
      } as React.CSSProperties}
      role="progressbar"
      aria-valuenow={value}
      aria-valuemin={0}
      aria-valuemax={100}
    >
      <div className="progress-bar" />
    </div>
  );
}

.progress {
  height: 0.5rem;
  background: var(--color-bg-sunken);
  border-radius: var(--radius-full);
  overflow: hidden;
}

.progress-bar {
  height: 100%;
  width: var(--progress-value, 0%);
  background: var(--progress-color, var(--color-primary));
  border-radius: var(--radius-full);
  transition: width var(--duration-normal) var(--ease-default);
}

---

From css-grid

CSS Grid layout patterns — grid templates, auto-placement, subgrid, named areas, and responsive grids.

CSS Grid Layout Patterns

Purpose

Provide expert guidance on CSS Grid layout for building complex, responsive page layouts. Covers grid templates, auto-placement, subgrid, named areas, and intrinsic sizing patterns. Focuses on modern CSS Grid (including subgrid) with Tailwind CSS equivalents.

Key Patterns

Responsive Grid Without Media Queries

Auto-fit with minmax — the most useful pattern:

.card-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 18rem), 1fr));
  gap: 1.5rem;
}

The min(100%, 18rem) prevents overflow on small screens where 18rem exceeds container width.

Tailwind equivalent:

<div class="grid grid-cols-[repeat(auto-fit,minmax(min(100%,18rem),1fr))] gap-6">
  <!-- cards -->
</div>

auto-fit vs auto-fill:

Property	Behavior	Use When
auto-fit	Collapses empty tracks, items stretch to fill	Few items, want them to fill width
auto-fill	Keeps empty tracks, items stay at min size	Many items, consistent column width

/* auto-fit: 2 items stretch to fill 4-column space */
.stretch { grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); }

/* auto-fill: 2 items stay at 200px, empty tracks preserved */
.fixed { grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); }

Named Grid Areas

Classic page layout:

.page-layout {
  display: grid;
  grid-template-areas:
    "header  header  header"
    "sidebar content aside"
    "footer  footer  footer";
  grid-template-columns: 16rem 1fr 14rem;
  grid-template-rows: auto 1fr auto;
  min-height: 100dvh;
  gap: 0;
}

.header  { grid-area: header; }
.sidebar { grid-area: sidebar; }
.content { grid-area: content; }
.aside   { grid-area: aside; }
.footer  { grid-area: footer; }

/* Collapse sidebar on mobile */
@media (max-width: 768px) {
  .page-layout {
    grid-template-areas:
      "header"
      "content"
      "footer";
    grid-template-columns: 1fr;
  }
  .sidebar, .aside { display: none; }
}

Subgrid

Subgrid allows child grids to inherit the parent's track sizing, ensuring alignment across nested components:

/* Parent grid defines columns */
.card-list {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 20rem), 1fr));
  gap: 1.5rem;
}

/* Each card aligns its internal rows to siblings */
.card {
  display: grid;
  grid-template-rows: subgrid;
  grid-row: span 3;  /* card takes 3 rows: image, title, description */
  gap: 0.75rem;
  padding: 1.5rem;
  border-radius: 0.75rem;
  box-shadow: 0 1px 3px rgb(0 0 0 / 0.1);
}

.card img    { grid-row: 1; object-fit: cover; border-radius: 0.5rem; }
.card h3     { grid-row: 2; align-self: start; }
.card p      { grid-row: 3; align-self: start; }

Subgrid for form alignment:

.form {
  display: grid;
  grid-template-columns: auto 1fr;
  gap: 1rem 1.5rem;
}

.form-field {
  display: grid;
  grid-column: 1 / -1;
  grid-template-columns: subgrid;
  align-items: center;
}

.form-field label { grid-column: 1; }
.form-field input { grid-column: 2; padding: 0.75rem 1rem; border-radius: 0.5rem; }

Explicit Grid Placement

Dashboard with mixed-size widgets:

.dashboard {
  display: grid;
  grid-template-columns: repeat(4, 1fr);
  grid-auto-rows: minmax(10rem, auto);
  gap: 1.5rem;
  padding: 2rem;
}

.widget-large  { grid-column: span 2; grid-row: span 2; }
.widget-wide   { grid-column: span 2; }
.widget-tall   { grid-row: span 2; }
.widget-full   { grid-column: 1 / -1; }

@media (max-width: 768px) {
  .dashboard { grid-template-columns: repeat(2, 1fr); }
  .widget-large { grid-column: 1 / -1; }
}

@media (max-width: 480px) {
  .dashboard { grid-template-columns: 1fr; }
  .widget-large,
  .widget-wide { grid-column: 1 / -1; grid-row: span 1; }
}

Overlapping Grid Items

Grid items can occupy the same cells for layered effects:

.hero {
  display: grid;
  grid-template: 1fr / 1fr;
  min-height: 60vh;
}

.hero > * {
  grid-area: 1 / 1;  /* all children overlap */
}

.hero-image {
  object-fit: cover;
  width: 100%;
  height: 100%;
}

.hero-overlay {
  background: linear-gradient(to top, rgb(0 0 0 / 0.7), transparent);
  z-index: 1;
}

.hero-content {
  z-index: 2;
  align-self: end;
  padding: 4rem;
  color: white;
}

Intrinsic Sizing Patterns

/* Content-sized sidebar, flexible main */
.layout {
  display: grid;
  grid-template-columns: fit-content(20rem) 1fr;
}

/* Minimum content size, then flexible */
.layout-2 {
  display: grid;
  grid-template-columns: minmax(min-content, 20rem) 1fr;
}

/* Auto tracks size to content, fr takes remaining space */
.header-bar {
  display: grid;
  grid-template-columns: auto 1fr auto;
  align-items: center;
  gap: 1rem;
}

Masonry Layout (CSS Grid approach)

True CSS masonry is still experimental, but you can approximate it:

/* Approximation using grid-auto-rows */
.masonry {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(min(100%, 16rem), 1fr));
  grid-auto-rows: 1rem; /* small row unit */
  gap: 1rem;
}

/* Each item spans a calculated number of rows */
.masonry-item-sm { grid-row: span 10; }
.masonry-item-md { grid-row: span 15; }
.masonry-item-lg { grid-row: span 22; }

Tailwind CSS Grid Utilities

<!-- Responsive card grid -->
<div class="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 gap-6">
  <div class="p-6 rounded-xl shadow-sm border">Card</div>
</div>

<!-- Dashboard layout with named areas (requires arbitrary values) -->
<div class="grid grid-cols-[16rem_1fr_14rem] grid-rows-[auto_1fr_auto] min-h-dvh">
  <header class="col-span-full">Header</header>
  <aside>Sidebar</aside>
  <main>Content</main>
  <aside>Right panel</aside>
  <footer class="col-span-full">Footer</footer>
</div>

<!-- Spanning items -->
<div class="grid grid-cols-4 gap-4">
  <div class="col-span-2 row-span-2">Large widget</div>
  <div>Small widget</div>
  <div>Small widget</div>
</div>

Best Practices

1. Use auto-fit with minmax() for responsive grids — Eliminates the need for most media queries in card layouts.
2. Use min(100%, Xrem) inside minmax() — Prevents items from overflowing on very narrow containers.
3. Use named grid areas for page layouts — More readable than line-number placement for complex layouts.
4. Use subgrid for aligned card content — Ensures titles, descriptions, and CTAs align across cards in a row.
5. Prefer gap over margins — Grid gap only applies between items, not at edges. Simpler than managing margins.
6. Use dvh for full-height layouts — 100dvh accounts for mobile browser chrome, unlike 100vh.
7. Combine Grid and Flexbox — Use Grid for 2D layouts, Flexbox for 1D alignment within grid items.
8. Use fr units, not percentages — fr respects gap automatically; percentages don't.
9. Set min-width: 0 on grid children when needed — Grid items default to min-width: auto, which can cause overflow with long text.
10. Test with Grid DevTools — Firefox and Chrome both have Grid overlay inspectors that show tracks and gaps.

Common Pitfalls

Pitfall	Problem	Fix
minmax(200px, 1fr) overflow	On screens < 200px, items overflow	Use minmax(min(100%, 200px), 1fr)
Percentage gaps	Gaps calculated from container, not track	Use rem or px for gap values
auto vs 1fr confusion	auto sizes to content; 1fr shares remaining space	Use 1fr when columns should be equal
Missing min-width: 0	Long words or images overflow grid cells	Add min-width: 0 or overflow: hidden to children
Subgrid without span	Child grid doesn't span enough parent rows	Set grid-row: span N to match subgrid row count
auto-fill when wanting stretch	Items don't fill container width	Use auto-fit to collapse empty tracks
Fixed column count on mobile	Grid doesn't adapt to small screens	Use auto-fit/auto-fill or responsive breakpoints
Forgetting grid-template-rows	Only columns defined, rows auto-sized unexpectedly	Define explicit row templates for complex layouts

---

From dark-mode

Dark mode implementation with CSS custom properties, prefers-color-scheme, Tailwind dark variant, theme persistence in localStorage, class vs media strategy, and smooth transitions

Dark Mode Skill

Purpose

Implement a flicker-free, accessible dark mode that respects user system preferences, persists choice across sessions, and transitions smoothly between themes.

Key Concepts

Strategy: Class vs Media

Strategy	Tailwind Config	Control	Best For
class	darkMode: "class"	Manual toggle + system fallback	Most apps (recommended)
media	darkMode: "media"	System preference only	Blogs, simple sites

CSS Custom Properties (Design Tokens)

/* globals.css */
:root {
  --background: 0 0% 100%;
  --foreground: 0 0% 3.9%;
  --card: 0 0% 100%;
  --card-foreground: 0 0% 3.9%;
  --border: 0 0% 89.8%;
  --ring: 0 0% 3.9%;
}

.dark {
  --background: 0 0% 3.9%;
  --foreground: 0 0% 98%;
  --card: 0 0% 7%;
  --card-foreground: 0 0% 98%;
  --border: 0 0% 14.9%;
  --ring: 0 0% 83.1%;
}

/* Smooth transition between themes */
html.transitioning,
html.transitioning *,
html.transitioning *::before,
html.transitioning *::after {
  transition: background-color 200ms ease, color 200ms ease, border-color 200ms ease !important;
}

Anti-Flash Script (Critical)

Inject an inline <script> in <head> before the body renders. This prevents a white flash when a dark-mode user loads the page. Use React's dangerouslySetInnerHTML on a <script> tag inside app/layout.tsx:

// Inline script content (runs before paint):
(function() {
  try {
    var t = localStorage.getItem("theme");
    if (t === "dark" || (t !== "light" && matchMedia("(prefers-color-scheme:dark)").matches)) {
      document.documentElement.classList.add("dark");
    }
  } catch(e) {}
})()

Add suppressHydrationWarning on the <html> element to avoid React hydration mismatches caused by the class being added before hydration.

Theme Provider (React)

"use client";

import { createContext, useContext, useEffect, useState } from "react";

type Theme = "light" | "dark" | "system";

const ThemeContext = createContext<{
  theme: Theme;
  setTheme: (t: Theme) => void;
}>({ theme: "system", setTheme: () => {} });

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setThemeState] = useState<Theme>("system");

  useEffect(() => {
    const stored = localStorage.getItem("theme") as Theme | null;
    if (stored) setThemeState(stored);
  }, []);

  function setTheme(newTheme: Theme) {
    setThemeState(newTheme);
    localStorage.setItem("theme", newTheme);

    const root = document.documentElement;
    root.classList.add("transitioning");
    root.classList.remove("light", "dark");

    if (newTheme === "system") {
      const isDark = matchMedia("(prefers-color-scheme: dark)").matches;
      root.classList.add(isDark ? "dark" : "light");
      localStorage.removeItem("theme");
    } else {
      root.classList.add(newTheme);
    }

    setTimeout(() => root.classList.remove("transitioning"), 250);
  }

  return (
    <ThemeContext.Provider value={{ theme, setTheme }}>
      {children}
    </ThemeContext.Provider>
  );
}

export const useTheme = () => useContext(ThemeContext);

Toggle Component

"use client";

import { useTheme } from "./theme-provider";

export function ThemeToggle() {
  const { theme, setTheme } = useTheme();

  return (
    <button
      onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
      className="rounded-lg px-4 py-3 text-base transition-all duration-200
                 hover:bg-black/10 dark:hover:bg-white/10
                 focus-visible:ring-2 focus-visible:ring-offset-2
                 motion-reduce:transition-none"
      aria-label={`Switch to ${theme === "dark" ? "light" : "dark"} mode`}
    >
      <span className="dark:hidden">Moon Icon</span>
      <span className="hidden dark:inline">Sun Icon</span>
    </button>
  );
}

Tailwind Usage

{/* Tailwind dark: prefix applies when .dark class is on <html> */}
<div className="bg-white text-gray-900 dark:bg-gray-950 dark:text-gray-50">
  <p className="text-gray-600 dark:text-gray-400">Adapts to theme</p>
</div>

Best Practices

• Inline the anti-flash script: Must run before first paint. Never load it as an external file.
• Use suppressHydrationWarning: On <html> to prevent React hydration mismatch from the class.
• Respect system preference: Default to system, then allow manual override.
• Use HSL tokens: Store colors as HSL channels so opacity modifiers work: bg-background/50.
• Test both modes: Every page, every component. Dark mode is not an afterthought.
• Accessible contrast: Verify WCAG AA (4.5:1 text, 3:1 UI) in both themes.

Common Pitfalls

Pitfall	Fix
White flash on dark-mode page load	Add inline script to <head> before body renders
Hydration mismatch warning	Add suppressHydrationWarning to <html>
Images look wrong in dark mode	Use dark:invert or provide dark variants
Hardcoded colors ignore theme	Use CSS variables or Tailwind dark: prefix everywhere
Transition flicker on first load	Only add transition class during intentional toggles

---

From responsive-design

Responsive design — fluid typography, container queries, aspect ratios, mobile-first CSS, clamp(), modern layout patterns, and accessibility across viewports

Responsive Design Skill

Purpose

Responsive design ensures interfaces work across all viewport sizes. Modern CSS provides powerful tools (clamp, container queries, fluid grids) that replace brittle breakpoint-only approaches. This skill covers fluid typography, container queries, modern layout patterns, responsive images, and mobile-first architecture.

Key Concepts

Mobile-First vs Desktop-First

/* Mobile-First (recommended): Base styles = mobile, enhance upward */
.card {
  padding: 1rem;            /* Mobile default */
  font-size: 1rem;
}

@media (min-width: 48rem) { /* Tablet+ */
  .card {
    padding: 1.5rem;
  }
}

@media (min-width: 64rem) { /* Desktop+ */
  .card {
    padding: 2rem;
  }
}

/* Desktop-First (avoid): Base styles = desktop, override downward */
/* Results in more overrides, larger CSS, harder to maintain */

Common Breakpoints

Name	Width	Target	Tailwind
sm	40rem (640px)	Large phones landscape	sm:
md	48rem (768px)	Tablets	md:
lg	64rem (1024px)	Small laptops	lg:
xl	80rem (1280px)	Desktops	xl:
2xl	96rem (1536px)	Large desktops	2xl:

Use rem, not px — Respects user's font size preference.

Workflow

Step 1: Fluid Typography with clamp()

Instead of breakpoints for font sizes, use clamp() for smooth scaling:

/* clamp(minimum, preferred, maximum) */
/* preferred = viewport-relative value that scales smoothly */

:root {
  /* Formula: clamp(min, vw-calc, max)
     vw-calc = minSize + (maxSize - minSize) * ((100vw - minViewport) / (maxViewport - minViewport))
     Simplified: use a vw value that produces the right range */

  --text-sm: clamp(0.875rem, 0.8rem + 0.2vw, 1rem);
  --text-base: clamp(1rem, 0.9rem + 0.3vw, 1.125rem);
  --text-lg: clamp(1.125rem, 1rem + 0.4vw, 1.375rem);
  --text-xl: clamp(1.25rem, 1rem + 0.75vw, 1.75rem);
  --text-2xl: clamp(1.5rem, 1rem + 1.5vw, 2.5rem);
  --text-3xl: clamp(1.875rem, 1rem + 2.5vw, 3.5rem);
  --text-4xl: clamp(2.25rem, 1rem + 3.5vw, 4.5rem);

  /* Fluid spacing */
  --space-sm: clamp(0.5rem, 0.4rem + 0.3vw, 0.75rem);
  --space-md: clamp(1rem, 0.8rem + 0.6vw, 1.5rem);
  --space-lg: clamp(1.5rem, 1rem + 1.5vw, 3rem);
  --space-xl: clamp(2rem, 1rem + 3vw, 5rem);
  --space-section: clamp(3rem, 2rem + 4vw, 8rem);
}

/* Usage */
h1 { font-size: var(--text-4xl); }
h2 { font-size: var(--text-3xl); }
h3 { font-size: var(--text-2xl); }
p  { font-size: var(--text-base); }

section { padding-block: var(--space-section); }

Tailwind v4 equivalent:

@import "tailwindcss";

@theme {
  --text-fluid-sm: clamp(0.875rem, 0.8rem + 0.2vw, 1rem);
  --text-fluid-base: clamp(1rem, 0.9rem + 0.3vw, 1.125rem);
  --text-fluid-xl: clamp(1.25rem, 1rem + 0.75vw, 1.75rem);
  --text-fluid-3xl: clamp(1.875rem, 1rem + 2.5vw, 3.5rem);
}

Step 2: Container Queries

Container queries let components respond to their container's size, not the viewport. This makes truly reusable components:

/* Define a containment context */
.card-container {
  container-type: inline-size;
  container-name: card;
}

/* Respond to container width */
.card {
  display: grid;
  gap: 1rem;
  padding: 1rem;
}

@container card (min-width: 30rem) {
  .card {
    grid-template-columns: 200px 1fr;
    padding: 1.5rem;
  }
}

@container card (min-width: 50rem) {
  .card {
    grid-template-columns: 300px 1fr auto;
    padding: 2rem;
  }
}

// React component with container query
function ProductCard({ product }: { product: Product }) {
  return (
    // The wrapper establishes the container context
    <div className="@container">
      {/* Tailwind container query syntax */}
      <article className="flex flex-col gap-4 p-4
                          @md:flex-row @md:gap-6 @md:p-6
                          @lg:gap-8 @lg:p-8">
        <img
          src={product.image}
          alt={product.name}
          className="w-full aspect-square object-cover rounded-lg
                     @md:w-48 @md:aspect-auto @md:h-full
                     @lg:w-64"
        />
        <div className="flex flex-col gap-2">
          <h3 className="text-lg font-semibold @lg:text-xl">{product.name}</h3>
          <p className="text-sm text-gray-600 @md:text-base">{product.description}</p>
          <span className="text-lg font-bold @lg:text-xl">${product.price}</span>
        </div>
      </article>
    </div>
  );
}

Step 3: Modern Layout Patterns

Auto-Fit Grid (No Breakpoints)

/* Cards automatically wrap based on available space */
.auto-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(min(100%, 18rem), 1fr));
  gap: var(--space-md);
}

/* min(100%, 18rem) prevents overflow on small screens */

Sidebar Layout (Responsive Without Media Query)

.sidebar-layout {
  display: grid;
  grid-template-columns: fit-content(20rem) minmax(0, 1fr);
  gap: var(--space-lg);
}

/* On narrow viewports, stack with a media query */
@media (max-width: 48rem) {
  .sidebar-layout {
    grid-template-columns: 1fr;
  }
}

Holy Grail Layout

.page {
  display: grid;
  grid-template-rows: auto 1fr auto;
  min-height: 100dvh; /* dvh = dynamic viewport height (accounts for mobile browser chrome) */
}

.page-content {
  display: grid;
  grid-template-columns: minmax(0, 1fr);
  width: min(100% - 2rem, 75rem); /* Max-width with padding, no media query */
  margin-inline: auto;
}

Flexible Spacing with margin-inline: auto

/* Content wrapper that centers and constrains width */
.content-wrapper {
  width: min(100% - var(--space-md) * 2, 75rem);
  margin-inline: auto;
}
/* This single rule replaces: max-width + padding-left + padding-right + margin auto */

Step 4: Responsive Images

<!-- srcset + sizes: browser picks the best image -->
<img
  src="/images/hero-800.jpg"
  srcset="
    /images/hero-400.jpg 400w,
    /images/hero-800.jpg 800w,
    /images/hero-1200.jpg 1200w,
    /images/hero-1600.jpg 1600w
  "
  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 80vw, 1200px"
  alt="Hero image"
  loading="lazy"
  decoding="async"
  fetchpriority="high"
/>

<!-- <picture> for art direction (different crops per viewport) -->
<picture>
  <source media="(max-width: 640px)" srcset="/images/hero-mobile.jpg" />
  <source media="(max-width: 1024px)" srcset="/images/hero-tablet.jpg" />
  <img src="/images/hero-desktop.jpg" alt="Hero image" />
</picture>

// Next.js Image (handles srcset, WebP/AVIF, lazy loading automatically)
import Image from 'next/image';

<Image
  src="/images/hero.jpg"
  alt="Hero image"
  width={1200}
  height={675}
  sizes="(max-width: 640px) 100vw, (max-width: 1024px) 80vw, 1200px"
  priority  // Above the fold — skip lazy loading
  className="w-full h-auto object-cover rounded-xl"
/>

Step 5: Aspect Ratios

/* Native aspect-ratio property */
.video-embed {
  aspect-ratio: 16 / 9;
  width: 100%;
}

.avatar {
  aspect-ratio: 1 / 1;
  width: 3rem;
  border-radius: 50%;
  object-fit: cover;
}

.card-image {
  aspect-ratio: 4 / 3;
  width: 100%;
  object-fit: cover;
  border-radius: 0.75rem;
}

/* Responsive aspect ratio (change per breakpoint) */
.hero {
  aspect-ratio: 1 / 1; /* Square on mobile */
}

@media (min-width: 48rem) {
  .hero {
    aspect-ratio: 16 / 9; /* Widescreen on tablet+ */
  }
}

Step 6: Dynamic Viewport Units

/* Modern viewport units account for mobile browser chrome (address bar, toolbar) */
.full-height {
  height: 100dvh;  /* dvh = dynamic viewport height (changes as chrome shows/hides) */
}

.hero-section {
  min-height: 100svh; /* svh = small viewport height (chrome visible — safe minimum) */
}

.modal-overlay {
  height: 100lvh; /* lvh = large viewport height (chrome hidden — maximum) */
}

/*
  dvh: Changes dynamically as mobile browser chrome appears/disappears
  svh: Smallest possible viewport (when address bar is showing)
  lvh: Largest possible viewport (when address bar is hidden)

  For most cases, use dvh. For hero sections, use svh (prevents content jump).
*/

Step 7: Responsive Text Truncation

/* Single line truncation */
.truncate {
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
}

/* Multi-line truncation (works in all modern browsers) */
.line-clamp-2 {
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

.line-clamp-3 {
  display: -webkit-box;
  -webkit-line-clamp: 3;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

Step 8: Touch Target Sizing

/* WCAG 2.2 requires 24x24px minimum, recommends 44x44px */
.touch-target {
  min-height: 2.75rem; /* 44px — Apple HIG recommendation */
  min-width: 2.75rem;
  padding: 0.75rem 1rem;
}

/* Invisible touch area expansion */
.icon-button {
  position: relative;
  width: 1.5rem;
  height: 1.5rem;
}

.icon-button::before {
  content: '';
  position: absolute;
  inset: -0.5rem; /* Expand touch area by 8px in each direction */
}

Common Pitfalls

1. Using px for breakpoints and font sizes — Use rem. Users who increase their browser's base font size get properly scaled text and breakpoints.
2. Forgetting min-width: 0 in flex/grid children — Flex and grid children have an implicit min-width: auto, causing overflow. Add min-width: 0 or overflow: hidden to prevent horizontal scroll.
3. Using 100vh on mobile — The address bar causes 100vh to be taller than the visible viewport. Use 100dvh or 100svh instead.
4. Media queries only — Over-relying on breakpoints instead of intrinsic sizing (min(), clamp(), auto-fit). Modern CSS can handle most responsive behavior without breakpoints.
5. Not testing with real content — Designs that work with "Lorem ipsum" break with real variable-length content. Test with short and long content.
6. Ignoring landscape orientation — Mobile landscape creates a wide, short viewport. Test with @media (orientation: landscape) and (max-height: 500px).
7. Fixed-width elements — Any width: 500px without max-width: 100% will overflow on mobile. Always use relative or constrained widths.

Quick Reference

/* Fluid typography */
font-size: clamp(1rem, 0.9rem + 0.3vw, 1.25rem);

/* Fluid spacing */
padding: clamp(1rem, 0.5rem + 2vw, 3rem);

/* Max-width container (no media query) */
width: min(100% - 2rem, 75rem);
margin-inline: auto;

/* Auto-fit grid (no media query) */
grid-template-columns: repeat(auto-fit, minmax(min(100%, 18rem), 1fr));

/* Full viewport height (mobile-safe) */
min-height: 100dvh;

/* Responsive aspect ratio */
aspect-ratio: 16 / 9;

/* Container query */
container-type: inline-size;
@container (min-width: 30rem) { ... }

Best Practices

• Mobile-first: Write base styles for mobile, enhance with min-width queries
• Intrinsic sizing first: Use clamp(), min(), max(), auto-fit before reaching for media queries
• Container queries for components: Components should respond to their container, not the viewport
• Test at every width: Drag the browser edge — the layout should be usable at every single pixel width, not just breakpoint snaps
• Use rem everywhere: Respects user font size preferences for accessibility
• dvh over vh: Always use dynamic viewport units on mobile
• Prefers-reduced-motion: Wrap animations in @media (prefers-reduced-motion: no-preference) or use motion-reduce: in Tailwind

---

From animation

Frontend animation patterns — Framer Motion, CSS animations, GSAP, scroll-driven animations, and motion design principles

Animation & Motion Design

Purpose

Provide expert guidance on frontend animation implementation using Framer Motion, CSS animations, GSAP, and native scroll-driven animations. Focus on performant, accessible motion that enhances user experience without degrading performance or excluding users who prefer reduced motion.

Core Principles

1. Purpose over decoration — Every animation should serve a purpose: guide attention, provide feedback, show relationships, or smooth transitions.
2. 60fps or nothing — Animate only transform and opacity for GPU-accelerated performance. Avoid animating width, height, top, left, margin, or padding.
3. Respect user preferences — Always implement prefers-reduced-motion alternatives.
4. Duration guidelines — Micro-interactions: 100-200ms. Transitions: 200-400ms. Complex sequences: 400-800ms. Never exceed 1s for UI animations.

Key Patterns

Framer Motion Fundamentals

Basic animations:

import { motion } from 'framer-motion';

// Simple entrance animation
function FadeIn({ children }: { children: React.ReactNode }) {
  return (
    <motion.div
      initial={{ opacity: 0, y: 12 }}
      animate={{ opacity: 1, y: 0 }}
      transition={{ duration: 0.3, ease: 'easeOut' }}
    >
      {children}
    </motion.div>
  );
}

// Exit animation
function Toast({ message, onClose }: ToastProps) {
  return (
    <motion.div
      initial={{ opacity: 0, y: 20, scale: 0.95 }}
      animate={{ opacity: 1, y: 0, scale: 1 }}
      exit={{ opacity: 0, y: -10, scale: 0.95 }}
      transition={{ type: 'spring', stiffness: 300, damping: 25 }}
      className="p-6 rounded-xl shadow-lg bg-white"
    >
      {message}
      <button onClick={onClose}>Dismiss</button>
    </motion.div>
  );
}

AnimatePresence for exit animations:

import { AnimatePresence, motion } from 'framer-motion';

function NotificationList({ notifications }: { notifications: Notification[] }) {
  return (
    <AnimatePresence mode="popLayout">
      {notifications.map(n => (
        <motion.div
          key={n.id}
          layout
          initial={{ opacity: 0, height: 0 }}
          animate={{ opacity: 1, height: 'auto' }}
          exit={{ opacity: 0, height: 0 }}
          transition={{ type: 'spring', stiffness: 400, damping: 30 }}
          className="overflow-hidden"
        >
          <div className="p-6 rounded-xl shadow-sm border mb-3">
            {n.message}
          </div>
        </motion.div>
      ))}
    </AnimatePresence>
  );
}

Layout animations:

function ExpandableCard({ isExpanded, onClick, title, content }: Props) {
  return (
    <motion.div
      layout
      onClick={onClick}
      className="p-6 rounded-xl shadow-sm cursor-pointer"
      transition={{ type: 'spring', stiffness: 300, damping: 30 }}
    >
      <motion.h3 layout="position" className="text-lg font-semibold">
        {title}
      </motion.h3>
      <AnimatePresence>
        {isExpanded && (
          <motion.div
            initial={{ opacity: 0 }}
            animate={{ opacity: 1 }}
            exit={{ opacity: 0 }}
            className="mt-4 text-base text-gray-600"
          >
            {content}
          </motion.div>
        )}
      </AnimatePresence>
    </motion.div>
  );
}

Stagger children:

const containerVariants = {
  hidden: {},
  visible: {
    transition: {
      staggerChildren: 0.08,
      delayChildren: 0.1,
    },
  },
};

const itemVariants = {
  hidden: { opacity: 0, y: 16 },
  visible: {
    opacity: 1,
    y: 0,
    transition: { type: 'spring', stiffness: 300, damping: 24 },
  },
};

function StaggerList({ items }: { items: Item[] }) {
  return (
    <motion.ul
      variants={containerVariants}
      initial="hidden"
      animate="visible"
      className="space-y-4"
    >
      {items.map(item => (
        <motion.li
          key={item.id}
          variants={itemVariants}
          className="p-6 rounded-xl shadow-sm"
        >
          {item.name}
        </motion.li>
      ))}
    </motion.ul>
  );
}

Scroll-triggered with whileInView:

function ScrollReveal({ children }: { children: React.ReactNode }) {
  return (
    <motion.div
      initial={{ opacity: 0, y: 40 }}
      whileInView={{ opacity: 1, y: 0 }}
      viewport={{ once: true, margin: '-100px' }}
      transition={{ duration: 0.5, ease: [0.25, 0.1, 0.25, 1] }}
    >
      {children}
    </motion.div>
  );
}

CSS Animations

Keyframe animations:

@keyframes fade-in-up {
  from {
    opacity: 0;
    transform: translateY(1rem);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

@keyframes pulse {
  0%, 100% { opacity: 1; }
  50% { opacity: 0.5; }
}

@keyframes shimmer {
  0% { background-position: -200% 0; }
  100% { background-position: 200% 0; }
}

.animate-fade-in-up {
  animation: fade-in-up 0.3s ease-out forwards;
}

.animate-pulse {
  animation: pulse 2s ease-in-out infinite;
}

/* Skeleton loading shimmer */
.skeleton {
  background: linear-gradient(
    90deg,
    var(--color-surface) 25%,
    oklch(0 0 0 / 0.05) 50%,
    var(--color-surface) 75%
  );
  background-size: 200% 100%;
  animation: shimmer 1.5s infinite;
  border-radius: var(--radius-md);
}

/* Reduced motion */
@media (prefers-reduced-motion: reduce) {
  .animate-fade-in-up,
  .animate-pulse {
    animation: none;
    opacity: 1;
    transform: none;
  }

  .skeleton {
    animation: none;
  }
}

CSS transitions for micro-interactions:

.btn {
  transition: all 200ms ease;

  &:hover {
    transform: translateY(-1px);
    box-shadow: var(--shadow-md);
  }

  &:active {
    transform: translateY(0);
    box-shadow: var(--shadow-sm);
  }
}

.card {
  transition: box-shadow 200ms ease, transform 200ms ease;

  &:hover {
    box-shadow: var(--shadow-lg);
    transform: translateY(-2px);
  }
}

.link {
  position: relative;

  &::after {
    content: '';
    position: absolute;
    bottom: -2px;
    left: 0;
    width: 0;
    height: 2px;
    background: var(--color-brand-600);
    transition: width 200ms ease;
  }

  &:hover::after {
    width: 100%;
  }
}

@media (prefers-reduced-motion: reduce) {
  .btn, .card, .link::after {
    transition: none;
  }

  .btn:hover, .card:hover {
    transform: none;
  }
}

Scroll-Driven Animations (CSS)

Native CSS scroll-driven animations (no JavaScript):

/* Progress bar that fills as user scrolls */
.scroll-progress {
  position: fixed;
  top: 0;
  left: 0;
  width: 100%;
  height: 3px;
  background: var(--color-brand-500);
  transform-origin: left;
  animation: grow-width linear;
  animation-timeline: scroll();
}

@keyframes grow-width {
  from { transform: scaleX(0); }
  to { transform: scaleX(1); }
}

/* Element reveals on scroll into view */
.scroll-reveal {
  animation: fade-in-up linear both;
  animation-timeline: view();
  animation-range: entry 0% entry 100%;
}

@keyframes fade-in-up {
  from {
    opacity: 0;
    transform: translateY(2rem);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

/* Parallax-like effect */
.parallax-element {
  animation: parallax linear;
  animation-timeline: scroll();
}

@keyframes parallax {
  from { transform: translateY(0); }
  to { transform: translateY(-100px); }
}

@media (prefers-reduced-motion: reduce) {
  .scroll-reveal,
  .parallax-element {
    animation: none;
    opacity: 1;
    transform: none;
  }
}

GSAP Patterns

Basic timeline:

import { useRef } from 'react';
import { useGSAP } from '@gsap/react';
import gsap from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';

gsap.registerPlugin(ScrollTrigger);

function HeroSection() {
  const containerRef = useRef<HTMLDivElement>(null);

  useGSAP(() => {
    const tl = gsap.timeline({ defaults: { ease: 'power3.out' } });

    tl.from('.hero-title', { y: 60, opacity: 0, duration: 0.8 })
      .from('.hero-subtitle', { y: 40, opacity: 0, duration: 0.6 }, '-=0.4')
      .from('.hero-cta', { y: 30, opacity: 0, duration: 0.5 }, '-=0.3');

    // Respect reduced motion
    if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
      tl.progress(1).kill();
    }
  }, { scope: containerRef });

  return (
    <div ref={containerRef} className="py-16">
      <h1 className="hero-title text-4xl font-bold">Welcome</h1>
      <p className="hero-subtitle text-xl text-gray-600 mt-4">Subtitle here</p>
      <button className="hero-cta mt-8 px-6 py-4 text-base rounded-lg bg-brand-600 text-white">
        Get Started
      </button>
    </div>
  );
}

Scroll-triggered sections:

function ScrollSection() {
  const sectionRef = useRef<HTMLDivElement>(null);

  useGSAP(() => {
    const cards = gsap.utils.toArray<HTMLElement>('.reveal-card');

    cards.forEach((card, i) => {
      gsap.from(card, {
        y: 60,
        opacity: 0,
        duration: 0.6,
        delay: i * 0.1,
        scrollTrigger: {
          trigger: card,
          start: 'top 85%',
          end: 'top 20%',
          toggleActions: 'play none none reverse',
        },
      });
    });
  }, { scope: sectionRef });

  return (
    <section ref={sectionRef} className="py-16">
      {items.map(item => (
        <div key={item.id} className="reveal-card p-6 rounded-xl shadow-sm mb-6">
          {item.content}
        </div>
      ))}
    </section>
  );
}

Reduced Motion Pattern

Always provide a comprehensive reduced-motion strategy:

// Hook for checking reduced motion preference
function usePrefersReducedMotion() {
  const [prefersReduced, setPrefersReduced] = useState(false);

  useEffect(() => {
    const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
    setPrefersReduced(mq.matches);

    const handler = (e: MediaQueryListEvent) => setPrefersReduced(e.matches);
    mq.addEventListener('change', handler);
    return () => mq.removeEventListener('change', handler);
  }, []);

  return prefersReduced;
}

// Usage with Framer Motion
function AnimatedComponent({ children }: { children: React.ReactNode }) {
  const prefersReduced = usePrefersReducedMotion();

  return (
    <motion.div
      initial={prefersReduced ? false : { opacity: 0, y: 20 }}
      animate={{ opacity: 1, y: 0 }}
      transition={prefersReduced
        ? { duration: 0 }
        : { type: 'spring', stiffness: 300, damping: 25 }
      }
    >
      {children}
    </motion.div>
  );
}

Page Transitions (Next.js)

// app/template.tsx — runs on every navigation
'use client';

import { motion } from 'framer-motion';

export default function Template({ children }: { children: React.ReactNode }) {
  return (
    <motion.div
      initial={{ opacity: 0 }}
      animate={{ opacity: 1 }}
      transition={{ duration: 0.2, ease: 'easeOut' }}
    >
      {children}
    </motion.div>
  );
}

Best Practices

1. GPU-only properties — Animate only transform (translate, scale, rotate) and opacity. Everything else triggers layout/paint.
2. will-change sparingly — Only apply to elements about to animate, remove after.
3. Spring physics for UI — Springs feel natural. Use type: 'spring' in Framer Motion with stiffness: 200-400, damping: 20-30.
4. layout prop for FLIP — Framer Motion's layout prop handles layout animations automatically.
5. AnimatePresence for exit — Required for exit animations; wrap lists and conditionally rendered elements.
6. Stagger delays: 50-100ms — Keep stagger intervals short for perceptual grouping.
7. ease-out for entrances, ease-in for exits — Match motion to real-world physics.
8. Avoid simultaneous animations — Stagger or sequence related animations to reduce cognitive load.
9. Test on low-end devices — Animations that are smooth on M-series Macs may jank on budget phones.
10. prefers-reduced-motion is mandatory — Never ship animations without reduced motion support.

Common Pitfalls

Pitfall	Problem	Fix
Animating width/height	Triggers layout recalculation every frame	Animate transform: scale() instead, or use layout prop
Missing AnimatePresence	Exit animations don't play	Wrap parent with AnimatePresence
layout on too many elements	Performance degrades with many layout animations	Apply only to elements that actually change position
Long durations	UI feels sluggish	200-400ms for transitions, 100-200ms for micro-interactions
No reduced motion fallback	Excludes users with vestibular disorders	Always check prefers-reduced-motion
Animating on mount in lists	All items animate at once on page load	Use whileInView or stagger with viewport detection
GSAP without cleanup	Memory leaks, zombie animations	Use useGSAP hook or kill timelines in cleanup
will-change on everything	Excessive GPU memory usage	Apply just before animation, remove after

---

From framer-motion

Production-ready animation library for React — motion components, variants, AnimatePresence, layout animations, gestures, scroll-triggered

Framer Motion

• layer: domain
• category: animation
• riskLevel: low
• triggers: animate, motion, framer, transition, gesture, spring, stagger, AnimatePresence

Overview

Production-ready animation library for React. Declarative API with spring physics, layout animations, gesture support, and scroll-driven effects. Pairs with React's component model for composable, performant motion.

When to Use

• Adding enter/exit/layout transitions to React components
• Gesture-driven interactions (hover, tap, drag, pan)
• Scroll-triggered reveals or parallax effects
• Shared-layout animations across routes or states
• Orchestrating staggered or sequenced animations

Key Patterns

Motion Components

Use motion.div, motion.span, etc. — drop-in replacements that accept animation props.

Animate Prop & Variants

Define initial, animate, and exit states inline or via named variants for reuse across children.

AnimatePresence

Wrap conditional elements to animate mount/unmount. Use mode="wait" for sequential transitions and always provide a unique key.

Layout Animations

Add layout prop for automatic size/position transitions. Use layoutId for shared-element animations across components.

Gesture Animations

whileHover, whileTap, whileFocus, whileDrag — declarative gesture states. Combine drag with dragConstraints and dragElastic.

Scroll-Triggered Animations

useScroll() returns scrollYProgress. Pair with useTransform or useMotionValueEvent to drive animations from scroll position.

Spring Physics

Default transition uses springs. Tune with type: "spring", stiffness, damping, mass. Use type: "tween" with duration for linear/eased motion.

Stagger Children

In parent variants, set transition: { staggerChildren: 0.05 }. Children inherit variant names and animate in sequence.

useAnimate (Imperative)

const [scope, animate] = useAnimate() — run sequenced or conditional animations outside the declarative model. Useful for complex orchestration.

Anti-Patterns

• Animating layout-triggering properties (width, height) without layout prop — causes jank; use layout or transform-based animations instead.
• Missing key on AnimatePresence children — exit animations silently break.
• Over-stiff springs — stiffness > 500 without proportional damping causes oscillation. Test with damping: 2 * Math.sqrt(stiffness) for critical damping.
• Animating unmeasured elements — layout requires the element to be in the DOM before measuring; avoid combining with display: none.
• Ignoring prefers-reduced-motion — wrap animations with useReducedMotion() and provide static fallbacks.
• Re-creating variants on every render — define variants outside the component or memoize them.

Related Skills

react | animation | css-architecture | design-systems

---

From tailwind-animate

Tailwind CSS animation utilities, tailwindcss-animate plugin, enter/exit/loop animations, and motion-safe patterns

Tailwind Animate Patterns

Purpose

Provide expert guidance on CSS animations using Tailwind CSS and the tailwindcss-animate plugin, including enter/exit animations, looping animations, staggered sequences, and accessibility-compliant motion patterns.

Core Patterns

1. Plugin Installation & Configuration

npm install tailwindcss-animate

Tailwind v4 (CSS-first):

/* globals.css */
@import "tailwindcss";
@plugin "tailwindcss-animate";

@theme {
  /* Custom animation durations */
  --animate-duration: 200ms;
  --animate-delay: 0ms;

  /* Custom keyframes */
  --animate-fade-in: fade-in 0.2s ease-out;
  --animate-fade-out: fade-out 0.2s ease-out;
  --animate-slide-in-from-top: slide-in-from-top 0.3s ease-out;
  --animate-slide-in-from-bottom: slide-in-from-bottom 0.3s ease-out;
  --animate-slide-in-from-left: slide-in-from-left 0.3s ease-out;
  --animate-slide-in-from-right: slide-in-from-right 0.3s ease-out;
  --animate-scale-in: scale-in 0.2s ease-out;
  --animate-spin-slow: spin 3s linear infinite;
}

@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

@keyframes fade-out {
  from { opacity: 1; }
  to { opacity: 0; }
}

@keyframes slide-in-from-top {
  from { opacity: 0; transform: translateY(-1rem); }
  to { opacity: 1; transform: translateY(0); }
}

@keyframes slide-in-from-bottom {
  from { opacity: 0; transform: translateY(1rem); }
  to { opacity: 1; transform: translateY(0); }
}

@keyframes slide-in-from-left {
  from { opacity: 0; transform: translateX(-1rem); }
  to { opacity: 1; transform: translateX(0); }
}

@keyframes slide-in-from-right {
  from { opacity: 0; transform: translateX(1rem); }
  to { opacity: 1; transform: translateX(0); }
}

@keyframes scale-in {
  from { opacity: 0; transform: scale(0.95); }
  to { opacity: 1; transform: scale(1); }
}

Tailwind v3 (config-based):

// tailwind.config.ts
import type { Config } from 'tailwindcss';
import animate from 'tailwindcss-animate';

export default {
  plugins: [animate],
} satisfies Config;

2. Enter/Exit Animations with tailwindcss-animate

The plugin provides animate-in and animate-out base classes combined with directional modifiers:

// Fade in
<div className="animate-in fade-in duration-200">
  Fades in
</div>

// Slide in from bottom with fade
<div className="animate-in fade-in slide-in-from-bottom-4 duration-300">
  Slides up and fades in
</div>

// Slide in from left
<div className="animate-in fade-in slide-in-from-left-8 duration-300">
  Slides from left
</div>

// Scale in (zoom)
<div className="animate-in fade-in zoom-in-95 duration-200">
  Scales up from 95% with fade
</div>

// Exit animations
<div className="animate-out fade-out slide-out-to-bottom-4 duration-200">
  Slides down and fades out
</div>

// Spin out
<div className="animate-out fade-out spin-out-180 duration-300">
  Spins and fades out
</div>

// Combine with fill-mode to persist end state
<div className="animate-in fade-in duration-300 fill-mode-forwards">
  Stays visible after animation
</div>

3. Staggered List Animations

// Staggered children using animation-delay
function StaggeredList({ items }: { items: string[] }) {
  return (
    <ul className="space-y-2">
      {items.map((item, i) => (
        <li
          key={item}
          className="animate-in fade-in slide-in-from-bottom-2 duration-300 fill-mode-both"
          style={{ animationDelay: `${i * 75}ms` }}
        >
          <div className="p-4 rounded-lg border border-border shadow-sm">
            {item}
          </div>
        </li>
      ))}
    </ul>
  );
}

// Using CSS custom properties for delay
function StaggeredGrid({ cards }: { cards: CardData[] }) {
  return (
    <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">
      {cards.map((card, i) => (
        <div
          key={card.id}
          className="animate-in fade-in zoom-in-95 slide-in-from-bottom-4 duration-500 fill-mode-both"
          style={{ animationDelay: `${i * 100}ms` }}
        >
          <Card card={card} />
        </div>
      ))}
    </div>
  );
}

4. Dialog/Modal Animations

// Dialog with overlay + content animation
function AnimatedDialog({ open, onClose, children }: DialogProps) {
  return (
    <Dialog open={open} onOpenChange={onClose}>
      {/* Backdrop */}
      <DialogOverlay
        className={cn(
          'fixed inset-0 z-50 bg-black/50 backdrop-blur-sm',
          'data-[state=open]:animate-in data-[state=open]:fade-in-0',
          'data-[state=closed]:animate-out data-[state=closed]:fade-out-0',
          'duration-200'
        )}
      />

      {/* Content */}
      <DialogContent
        className={cn(
          'fixed left-1/2 top-1/2 z-50 -translate-x-1/2 -translate-y-1/2',
          'w-full max-w-lg p-8 rounded-2xl bg-white shadow-lg',
          'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
          'data-[state=open]:slide-in-from-left-1/2 data-[state=open]:slide-in-from-top-[48%]',
          'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
          'data-[state=closed]:slide-out-to-left-1/2 data-[state=closed]:slide-out-to-top-[48%]',
          'duration-200'
        )}
      >
        {children}
      </DialogContent>
    </Dialog>
  );
}

5. Dropdown/Popover Animations

// Dropdown with origin-aware animation
<DropdownMenuContent
  className={cn(
    'z-50 min-w-[8rem] overflow-hidden rounded-xl border border-border bg-white p-1 shadow-md',
    'data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95',
    'data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95',
    'data-[side=bottom]:slide-in-from-top-2',
    'data-[side=left]:slide-in-from-right-2',
    'data-[side=right]:slide-in-from-left-2',
    'data-[side=top]:slide-in-from-bottom-2',
    'duration-200'
  )}
/>

6. Looping / Continuous Animations

/* globals.css */
@keyframes pulse-soft {
  0%, 100% { opacity: 1; }
  50% { opacity: 0.6; }
}

@keyframes bounce-gentle {
  0%, 100% { transform: translateY(0); }
  50% { transform: translateY(-0.25rem); }
}

@keyframes shimmer {
  0% { background-position: -200% 0; }
  100% { background-position: 200% 0; }
}

@theme {
  --animate-pulse-soft: pulse-soft 2s ease-in-out infinite;
  --animate-bounce-gentle: bounce-gentle 1s ease-in-out infinite;
  --animate-shimmer: shimmer 1.5s ease-in-out infinite;
}

// Skeleton loading with shimmer
function Skeleton({ className }: { className?: string }) {
  return (
    <div
      className={cn(
        'rounded-lg bg-gradient-to-r from-gray-200 via-gray-100 to-gray-200',
        'bg-[length:200%_100%] animate-shimmer',
        'motion-reduce:animate-none motion-reduce:bg-gray-200',
        className
      )}
    />
  );
}

// Notification badge pulse
<span className="relative flex h-3 w-3">
  <span className="animate-ping absolute inline-flex h-full w-full rounded-full bg-red-400 opacity-75 motion-reduce:animate-none" />
  <span className="relative inline-flex rounded-full h-3 w-3 bg-red-500" />
</span>

// Loading spinner
<svg className="animate-spin h-5 w-5 text-brand-600 motion-reduce:animate-none" viewBox="0 0 24 24">
  <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4" fill="none" />
  <path className="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4z" />
</svg>

7. Scroll-Triggered Animations

'use client';

import { useEffect, useRef, useState } from 'react';
import { cn } from '@/lib/utils';

function useInView(options?: IntersectionObserverInit) {
  const ref = useRef<HTMLDivElement>(null);
  const [isInView, setIsInView] = useState(false);

  useEffect(() => {
    const element = ref.current;
    if (!element) return;

    const observer = new IntersectionObserver(
      ([entry]) => {
        if (entry.isIntersecting) {
          setIsInView(true);
          observer.unobserve(element); // Only animate once
        }
      },
      { threshold: 0.1, ...options }
    );

    observer.observe(element);
    return () => observer.disconnect();
  }, [options]);

  return { ref, isInView };
}

function AnimateOnScroll({
  children,
  className,
  delay = 0,
}: {
  children: React.ReactNode;
  className?: string;
  delay?: number;
}) {
  const { ref, isInView } = useInView();

  return (
    <div
      ref={ref}
      className={cn(
        'transition-all duration-500 motion-reduce:transition-none',
        isInView
          ? 'opacity-100 translate-y-0'
          : 'opacity-0 translate-y-4',
        className
      )}
      style={{ transitionDelay: `${delay}ms` }}
    >
      {children}
    </div>
  );
}

Best Practices

1. Always respect prefers-reduced-motion -- use motion-reduce:animate-none or motion-reduce:transition-none on every animation.
2. Keep durations short -- 150-300ms for micro-interactions, 300-500ms for entrance animations. Never exceed 1s for UI transitions.
3. Use fill-mode-both for staggered animations so elements stay invisible before their delay starts and visible after they finish.
4. Combine animate-in with directional classes -- fade-in alone is subtle; pair with slide-in-from-* or zoom-in-* for impact.
5. Use data-[state=*] selectors with Radix UI / shadcn/ui for enter/exit animations tied to component state.
6. Limit simultaneous animations -- stagger items by 50-100ms to create a natural flow rather than animating everything at once.
7. Use CSS animations over JS where possible -- GPU-accelerated transform and opacity are the cheapest properties to animate.
8. Add will-change-transform only when needed for complex animations, remove after animation completes to free GPU memory.

Anti-Patterns

Anti-Pattern	Problem	Fix
Animating width/height/margin	Triggers expensive layout recalculations	Use transform: scale() or translate() instead
No motion-reduce fallback	Causes motion sickness for vestibular disorders	Always add motion-reduce:animate-none
Animation duration > 1s for UI	Feels sluggish, blocks interaction	Keep UI transitions 150-500ms
Animating everything on page load	Overwhelming, slows perceived performance	Animate only above-fold hero elements
Using animate-bounce for loading	Distracting, not semantically meaningful	Use animate-spin or animate-pulse for loading
animation-delay without opacity: 0 initial	Content flashes then animates	Use fill-mode-both or set initial opacity-0
Staggering 20+ items	Long wait before last items appear	Cap staggered items at 8-10, load rest instantly

Decision Guide

Scenario	Approach
Simple fade/slide entrance	animate-in fade-in slide-in-from-bottom-4 duration-300
Dialog open/close	data-[state=open]:animate-in + data-[state=closed]:animate-out
Staggered list items	animate-in with style={{ animationDelay }} + fill-mode-both
Loading skeleton	Custom shimmer keyframe with animate-shimmer
Notification badge	animate-ping on pseudo-element
Hover micro-interaction	transition-all duration-200 (not keyframe animation)
Complex choreographed sequences	Use Framer Motion instead of pure CSS
Scroll-triggered reveal	IntersectionObserver + Tailwind transition classes
Exit animations	animate-out fade-out slide-out-to-* with tailwindcss-animate