Tailwind CSS v4 Modern Patterns

# Tailwind CSS v4 Modern Patterns for Google Antigravity

Master modern styling with Tailwind CSS v4 in your Google Antigravity IDE projects. This comprehensive guide covers CSS variables, container queries, component patterns, and design systems optimized for Gemini 3 agentic development.

## Configuration Setup

Configure Tailwind CSS v4 with CSS-first approach:

```css
/* app/globals.css */
@import "tailwindcss";

/* Custom theme using CSS variables */
@theme {
  /* Colors */
  --color-brand-50: oklch(0.97 0.01 280);
  --color-brand-100: oklch(0.93 0.03 280);
  --color-brand-500: oklch(0.55 0.25 280);
  --color-brand-600: oklch(0.48 0.25 280);
  --color-brand-700: oklch(0.40 0.22 280);
  
  /* Semantic colors */
  --color-surface: var(--color-zinc-900);
  --color-surface-elevated: var(--color-zinc-800);
  --color-surface-overlay: var(--color-zinc-700);
  
  --color-text-primary: var(--color-zinc-50);
  --color-text-secondary: var(--color-zinc-400);
  --color-text-muted: var(--color-zinc-500);
  
  /* Spacing scale */
  --spacing-page: 1.5rem;
  --spacing-section: 4rem;
  --spacing-card: 1.25rem;
  
  /* Typography */
  --font-display: "Cal Sans", system-ui, sans-serif;
  --font-body: "Inter", system-ui, sans-serif;
  --font-mono: "JetBrains Mono", monospace;
  
  /* Shadows */
  --shadow-card: 0 4px 6px -1px rgb(0 0 0 / 0.2), 
                 0 2px 4px -2px rgb(0 0 0 / 0.2);
  --shadow-elevated: 0 20px 25px -5px rgb(0 0 0 / 0.3),
                     0 8px 10px -6px rgb(0 0 0 / 0.3);
  
  /* Animations */
  --ease-bounce: cubic-bezier(0.34, 1.56, 0.64, 1);
  --ease-smooth: cubic-bezier(0.4, 0, 0.2, 1);
  
  /* Container sizes */
  --container-sm: 640px;
  --container-md: 768px;
  --container-lg: 1024px;
  --container-xl: 1280px;
}

/* Dark mode overrides */
@media (prefers-color-scheme: dark) {
  :root {
    --color-surface: var(--color-zinc-950);
    --color-surface-elevated: var(--color-zinc-900);
  }
}
```

## Component Patterns

Build reusable component styles:

```typescript
// components/ui/Button.tsx
import { cva, type VariantProps } from 'class-variance-authority';
import { cn } from '@/lib/utils';

const buttonVariants = cva(
  // Base styles
  `inline-flex items-center justify-center gap-2 rounded-lg
   font-medium transition-all duration-200 ease-smooth
   focus-visible:outline-none focus-visible:ring-2 
   focus-visible:ring-brand-500 focus-visible:ring-offset-2
   disabled:pointer-events-none disabled:opacity-50`,
  {
    variants: {
      variant: {
        default: `bg-brand-600 text-white hover:bg-brand-700
                  shadow-sm hover:shadow-md active:scale-[0.98]`,
        secondary: `bg-surface-elevated text-text-primary
                    border border-zinc-700 hover:bg-surface-overlay
                    hover:border-zinc-600`,
        ghost: `text-text-secondary hover:text-text-primary
                hover:bg-surface-elevated`,
        destructive: `bg-red-600 text-white hover:bg-red-700`,
        link: `text-brand-500 underline-offset-4 hover:underline`,
      },
      size: {
        sm: 'h-8 px-3 text-sm',
        md: 'h-10 px-4 text-sm',
        lg: 'h-12 px-6 text-base',
        icon: 'h-10 w-10',
      },
    },
    defaultVariants: {
      variant: 'default',
      size: 'md',
    },
  }
);

interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  isLoading?: boolean;
}

export function Button({
  className,
  variant,
  size,
  isLoading,
  children,
  ...props
}: ButtonProps) {
  return (
    <button
      className={cn(buttonVariants({ variant, size }), className)}
      disabled={isLoading || props.disabled}
      {...props}
    >
      {isLoading ? (
        <>
          <span className="animate-spin">⏳</span>
          Loading...
        </>
      ) : (
        children
      )}
    </button>
  );
}
```

## Container Queries

Implement responsive components with container queries:

```typescript
// components/PromptCard.tsx
export function PromptCard({ prompt }: { prompt: Prompt }) {
  return (
    <article className="@container group">
      <div
        className={cn(
          'rounded-xl bg-surface-elevated border border-zinc-800',
          'p-4 @sm:p-5 @lg:p-6',
          'transition-all duration-200',
          'hover:border-zinc-700 hover:shadow-card'
        )}
      >
        {/* Layout changes based on container width */}
        <div className="flex flex-col @md:flex-row @md:items-start gap-4">
          {/* Image - hidden on small containers */}
          {prompt.image && (
            <div className="hidden @sm:block shrink-0">
              <img
                src={prompt.image}
                alt=""
                className="w-16 h-16 @lg:w-20 @lg:h-20 rounded-lg object-cover"
              />
            </div>
          )}
          
          <div className="flex-1 min-w-0">
            <h3 className="font-semibold text-text-primary truncate @lg:text-lg">
              {prompt.title}
            </h3>
            
            {/* Description - more lines on larger containers */}
            <p className="mt-1 text-sm text-text-secondary line-clamp-2 @md:line-clamp-3">
              {prompt.description}
            </p>
            
            {/* Tags - show more on larger containers */}
            <div className="mt-3 flex flex-wrap gap-1.5">
              {prompt.tags.slice(0, 3).map((tag) => (
                <span
                  key={tag}
                  className="px-2 py-0.5 text-xs rounded-full bg-surface-overlay text-text-secondary"
                >
                  {tag}
                </span>
              ))}
              {/* Additional tags on larger containers */}
              <span className="hidden @lg:inline-flex">
                {prompt.tags.slice(3, 5).map((tag) => (
                  <span
                    key={tag}
                    className="px-2 py-0.5 text-xs rounded-full bg-surface-overlay text-text-secondary"
                  >
                    {tag}
                  </span>
                ))}
              </span>
            </div>
          </div>
          
          {/* Stats - rearrange based on container */}
          <div className="flex @md:flex-col items-center gap-4 @md:gap-2 text-text-muted">
            <span className="flex items-center gap-1 text-sm">
              <StarIcon className="w-4 h-4" />
              {prompt.starCount}
            </span>
            <span className="flex items-center gap-1 text-sm">
              <EyeIcon className="w-4 h-4" />
              {prompt.viewCount}
            </span>
          </div>
        </div>
      </div>
    </article>
  );
}
```

## Animation Patterns

Create smooth animations with Tailwind:

```css
/* app/animations.css */
@import "tailwindcss";

/* Custom animations */
@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

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

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

@theme {
  --animate-fade-in: fade-in 0.2s ease-out;
  --animate-slide-up: slide-up 0.3s ease-out;
  --animate-scale-in: scale-in 0.2s ease-out;
}
```

```typescript
// components/Modal.tsx
export function Modal({ isOpen, onClose, children }: ModalProps) {
  if (!isOpen) return null;

  return (
    <div className="fixed inset-0 z-50">
      {/* Backdrop */}
      <div
        className="fixed inset-0 bg-black/60 backdrop-blur-sm animate-fade-in"
        onClick={onClose}
      />
      
      {/* Content */}
      <div className="fixed inset-0 flex items-center justify-center p-4">
        <div
          className={cn(
            'w-full max-w-lg bg-surface-elevated rounded-2xl',
            'shadow-elevated border border-zinc-800',
            'animate-scale-in'
          )}
        >
          {children}
        </div>
      </div>
    </div>
  );
}
```

## Grid Patterns

Build responsive grid layouts:

```typescript
// components/PromptGrid.tsx
export function PromptGrid({ prompts }: { prompts: Prompt[] }) {
  return (
    <div
      className={cn(
        'grid gap-4',
        // Auto-fit with minimum column width
        'grid-cols-[repeat(auto-fill,minmax(280px,1fr))]',
        // Or explicit breakpoints
        // 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4'
      )}
    >
      {prompts.map((prompt, index) => (
        <div
          key={prompt.id}
          style={{ animationDelay: `${index * 50}ms` }}
          className="animate-slide-up"
        >
          <PromptCard prompt={prompt} />
        </div>
      ))}
    </div>
  );
}

// Masonry-like grid with CSS columns
export function MasonryGrid({ items }: { items: Item[] }) {
  return (
    <div className="columns-1 sm:columns-2 lg:columns-3 xl:columns-4 gap-4 space-y-4">
      {items.map((item) => (
        <div key={item.id} className="break-inside-avoid">
          <ItemCard item={item} />
        </div>
      ))}
    </div>
  );
}
```

## Best Practices

1. **Use CSS variables** for theming and design tokens
2. **Leverage container queries** for component-level responsiveness
3. **Create variant systems** with class-variance-authority
4. **Implement consistent spacing** with custom spacing scale
5. **Use oklch colors** for better color manipulation
6. **Add meaningful animations** for state transitions
7. **Organize styles** with layer-based architecture