@apply Abuse Broke Tailwind Tree-Shaking — 450KB CSS Bundle

/* ============================================
   Tailwind v4 — CSS-First Configuration
   ============================================ */

@import "tailwindcss";

/* ---- Content paths (replaces content array in config) ---- */
/* Tailwind scans these paths for class usage */
@source "../app/**/*.{ts,tsx}";
@source "../components/**/*.{ts,tsx}";
@source "../lib/**/*.{ts,tsx}";

/* ---- Design tokens via @theme ---- */
/* Each value becomes a CSS custom property AND a Tailwind utility */
/* --color-primary -> bg-primary, text-primary, border-primary */
/* --spacing-md -> p-md, m-md, gap-md, etc. */

@theme {
  /* Colors */
  --color-background: hsl(0 0% 100%);
  --color-foreground: hsl(240 10% 3.9%);
  --color-primary: hsl(240 5.9% 10%);
  --color-primary-foreground: hsl(0 0% 98%);
  --color-secondary: hsl(240 4.8% 95.9%);
  --color-secondary-foreground: hsl(240 5.9% 10%);
  --color-muted: hsl(240 4.8% 95.9%);
  --color-muted-foreground: hsl(240 3.8% 46.1%);
  --color-accent: hsl(240 4.8% 95.9%);
  --color-accent-foreground: hsl(240 5.9% 10%);
  --color-destructive: hsl(0 84.2% 60.2%);
  --color-destructive-foreground: hsl(0 0% 98%);
  --color-border: hsl(240 5.9% 90%);
  --color-input: hsl(240 5.9% 90%);
  --color-ring: hsl(240 5.9% 10%);

  /* Spacing scale */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;
  --spacing-2xl: 3rem;

  /* Border radius */
  --radius-sm: 0.25rem;
  --radius-md: 0.375rem;
  --radius-lg: 0.5rem;
  --radius-xl: 0.75rem;

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

  /* Animations */
  --animate-accordion-down: accordion-down 0.2s ease-out;
  --animate-accordion-up: accordion-up 0.2s ease-out;
  --animate-fade-in: fade-in 0.3s ease-out;
  --animate-slide-up: slide-up 0.3s ease-out;
}

/* ---- Keyframes for custom animations ---- */
@keyframes accordion-down {
  from { height: 0; }
  to { height: var(--radix-accordion-content-height); }
}

@keyframes accordion-up {
  from { height: var(--radix-accordion-content-height); }
  to { height: 0; }
}

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

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

/* ---- Dark mode variant ---- */
@custom-variant dark (&:is(.dark *));

/* ---- Dark theme overrides ---- */
.dark {
  --color-background: hsl(240 10% 3.9%);
  --color-foreground: hsl(0 0% 98%);
  --color-primary: hsl(0 0% 98%);
  --color-primary-foreground: hsl(240 5.9% 10%);
  --color-secondary: hsl(240 3.7% 15.9%);
  --color-secondary-foreground: hsl(0 0% 98%);
  --color-muted: hsl(240 3.7% 15.9%);
  --color-muted-foreground: hsl(240 5% 64.9%);
  --color-accent: hsl(240 3.7% 15.9%);
  --color-accent-foreground: hsl(0 0% 98%);
  --color-destructive: hsl(0 62.8% 30.6%);
  --color-destructive-foreground: hsl(0 0% 98%);
  --color-border: hsl(240 3.7% 15.9%);
  --color-input: hsl(240 3.7% 15.9%);
  --color-ring: hsl(240 4.9% 83.9%);
}

/* ---- Custom utility (replaces plugins for simple cases) ---- */
@utility text-balance {
  text-wrap: balance;
}

@utility scrollbar-thin {
  scrollbar-width: thin;
  scrollbar-color: var(--color-border) transparent;
}

/* ---- Base layer customizations ---- */
@layer base {
  * {
    @apply border-border;
  }

  body {
    @apply bg-background text-foreground;
    font-feature-settings: "rlig" 1, "calt" 1;
  }
}

// ============================================
// Component Extraction — The Right Way to Reuse Styles
// ============================================

// ---- WRONG: @apply creates opaque abstractions ----
// This is a CSS class that hides the actual utilities
// Tailwind cannot tree-shake this reliably

/* styles.css */
/* .btn-primary {
  @apply inline-flex items-center justify-center
    rounded-md bg-primary px-4 py-2 text-sm
    font-medium text-primary-foreground
    transition-colors hover:bg-primary/90
    focus-visible:outline-none focus-visible:ring-2
    focus-visible:ring-ring focus-visible:ring-offset-2
    disabled:pointer-events-none disabled:opacity-50;
} */

// ---- CORRECT: Extract as a React component ----
// Styles are visible, tree-shakeable, and co-located

// File: components/ui/button.tsx
import * as React from 'react'
import { Slot } from '@radix-ui/react-slot'
import { cva, type VariantProps } from 'class-variance-authority'
import { cn } from '@/lib/utils'

const buttonVariants = cva(
  // Base classes — applied to all variants
  'inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
        outline: 'border border-input bg-background hover:bg-accent hover:text-accent-foreground',
        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
        ghost: 'hover:bg-accent hover:text-accent-foreground',
        link: 'text-primary underline-offset-4 hover:underline',
      },
      size: {
        default: 'h-10 px-4 py-2',
        sm: 'h-9 rounded-md px-3',
        lg: 'h-11 rounded-md px-8',
        icon: 'h-10 w-10',
      },
    },
    defaultVariants: {
      variant: 'default',
      size: 'default',
    },
  }
)

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

const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, asChild = false, ...props }, ref) => {
    const Comp = asChild ? Slot : 'button'
    return (
      <Comp
        className={cn(buttonVariants({ variant, size, className }))}
        ref={ref}
        {...props}
      />
    )
  }
)
Button.displayName = 'Button'

export { Button, buttonVariants }

// ---- Usage ----
// Clear, explicit, no hidden abstractions

import { Button } from '@/components/ui/button'

export function ActionBar() {
  return (
    <div className="flex gap-2">
      <Button variant="default" size="sm">Save</Button>
      <Button variant="outline" size="sm">Cancel</Button>
      <Button variant="destructive" size="sm">Delete</Button>
    </div>
  )
}

// ---- WRONG: @apply for layout patterns ----
/* .page-container {
  @apply mx-auto max-w-7xl px-4 sm:px-6 lg:px-8;
} */

// ---- CORRECT: Extract as a layout component ----
// File: components/ui/container.tsx

export function Container({
  children,
  className,
}: {
  children: React.ReactNode
  className?: string
}) {
  return (
    <div className={cn('mx-auto max-w-7xl px-4 sm:px-6 lg:px-8', className)}>
      {children}
    </div>
  )
}

// ---- WRONG: @apply for card patterns ----
/* .card {
  @apply rounded-lg border bg-card text-card-foreground shadow-sm;
} */

// Extract as CardHeader, CardContent, etc.

export function CardHeader({
  children,
  className,
}: {
  children: React.ReactNode
  className?: string
}) {
  return (
    <div className={cn('flex flex-col space-y-1.5 p-6', className)}>
      {children}
    </div>
  )
}

export function CardContent({
  children,
  className,
}: {
  children: React.ReactNode
  className?: string
}) {
  return (
    <div className={cn('p-6 pt-0', className)}>
      {children}
    </div>
  )
}

// ---- The cn() utility: merge class names safely ----
// File: lib/utils.ts

import { type ClassValue, clsx } from 'clsx'
import { twMerge } from 'tailwind-merge'

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

// cn() resolves conflicts:
// cn('px-4 py-2', 'px-6') => 'py-2 px-6' (px-6 overrides px-4)
// clsx alone would produce 'px-4 py-2 px-6' — both applied, last wins by CSS order
// twMerge understands Tailwind — resolves the conflict correctly

// ============================================
// Class Organization — Sorting, Grouping, Readability
// ============================================

// ---- Grouped class list with comments ----
// Each comment marks a styling concern

import { cn } from '@/lib/utils'

export function Card({
  children,
  isActive,
  className,
}: {
  children: React.ReactNode
  isActive: boolean
  className?: string
}) {
  return (
    <div
      className={cn(
        // Layout
        'flex flex-col',

        // Spacing
        'gap-4 p-6',

        // Sizing
        'w-full max-w-md',

        // Typography
        'text-sm leading-relaxed',

        // Visual
        'rounded-lg border bg-card shadow-sm',

        // Interactive
        'transition-all hover:shadow-md',

        // Responsive
        'sm:flex-row sm:items-center',

        // Dark mode
        'dark:bg-card dark:shadow-none',

        // Conditional
        isActive && 'border-primary ring-2 ring-primary/20',

        // Custom overrides
        className
      )}
    >
      {children}
    </div>
  )
}

// ---- Tailwind v4: @utility for genuinely reusable patterns ----
// Only for patterns that cannot be components (global styles, base layer)

/* globals.css */
/* @utility prose {
  color: var(--color-foreground);
  max-width: 65ch;
  line-height: 1.75;
}

@utility prose h1,
@utility prose h2,
@utility prose h3 {
  color: var(--color-foreground);
  font-weight: 700;
  margin-top: 2em;
  margin-bottom: 0.5em;
}

@utility prose p {
  margin-bottom: 1em;
}

@utility prose a {
  color: var(--color-primary);
  text-decoration: underline;
} */

// ---- File organization: Where to put components ----
// Flat structure for small projects, domain-based for large projects

/*
Small project (< 50 components):
  components/
    ui/          <- Primitive components (button, input, card)
    layout/      <- Layout components (header, sidebar, footer)
    features/    <- Feature-specific components

Large project (50+ components):
  components/
    ui/          <- Primitive components (shared across features)
      button.tsx
      input.tsx
      card.tsx
      dialog.tsx
    layout/      <- Layout primitives
      container.tsx
      grid.tsx
      stack.tsx
    dashboard/   <- Dashboard domain
      stats-card.tsx
      activity-feed.tsx
      chart-widget.tsx
    billing/     <- Billing domain
      invoice-form.tsx
      payment-method.tsx
      subscription-card.tsx
    settings/    <- Settings domain
      profile-form.tsx
      notification-prefs.tsx
      danger-zone.tsx
*/

// ---- Tailwind IntelliSense setup ----
// File: .vscode/settings.json
// {
//   "tailwindCSS.experimental.classRegex": [
//     ["cva\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
//     ["cn\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
//     ["clsx\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
//     ["twMerge\\(([^)]*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
//   ],
//   "tailwindCSS.classAttributes": ["class", "className", "ngClass"],
//   "editor.quickSuggestions": {
//     "strings": "on"
//   }
// }

// ============================================
// shadcn/ui Integration — Theming and Customization
// ============================================

// ---- How shadcn/ui reads theme values ----
// Components use CSS variables via Tailwind's arbitrary value syntax

// shadcn/ui button (simplified):
// bg-primary -> background-color: var(--color-primary)
// text-primary-foreground -> color: var(--color-primary-foreground)
// border-input -> border-color: var(--color-input)

// To change the button color, update --color-primary in globals.css
// Do NOT override with: .btn { background: red !important }

// ---- WRONG: Overriding shadcn/ui styles from outside ----
// This creates specificity wars and maintenance debt

/* .my-button-override {
  background: #3b82f6 !important;
  color: white !important;
} */

// ---- CORRECT: Update CSS variables in globals.css ----
// This changes ALL components that use --color-primary

/* globals.css */
/* @theme {
  --color-primary: hsl(221.2 83.2% 53.3%);  // Blue instead of dark
  --color-primary-foreground: hsl(0 0% 100%);
} */

// ---- CORRECT: Extend the component for custom needs ----
// Modify the component itself, not override from outside

// File: components/ui/button.tsx (modified)
import { cva, type VariantProps } from 'class-variance-authority'

const buttonVariants = cva(
  'inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors',
  {
    variants: {
      variant: {
        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
        // Add custom variants here — they use your theme variables
        brand: 'bg-brand text-brand-foreground hover:bg-brand/90',
        success: 'bg-emerald-600 text-white hover:bg-emerald-700',
      },
      size: {
        default: 'h-10 px-4 py-2',
        sm: 'h-9 rounded-md px-3',
        lg: 'h-11 rounded-md px-8',
        icon: 'h-10 w-10',
        // Add custom sizes
        xl: 'h-12 rounded-lg px-10 text-base',
      },
    },
    defaultVariants: {
      variant: 'default',
      size: 'default',
    },
  }
)

// ---- shadcn/ui CLI: Adding components ----
// npx shadcn@latest add button
// npx shadcn@latest add dialog
// npx shadcn@latest add form
// npx shadcn@latest add data-table

// ---- shadcn/ui components.json ----
// File: components.json
// {
//   "$schema": "https://ui.shadcn.com/schema.json",
//   "style": "new-york",
//   "rsc": true,
//   "tsx": true,
//   "tailwind": {
//     "config": "",
//     "css": "app/globals.css",
//     "baseColor": "neutral",
//     "cssVariables": true
//   },
//   "aliases": {
//     "components": "@/components",
//     "utils": "@/lib/utils",
//     "ui": "@/components/ui",
//     "lib": "@/lib",
//     "hooks": "@/hooks"
//   }
// }

// ---- Composing shadcn/ui components ----
// Combine primitives to build feature components

// File: components/dashboard/stats-card.tsx
import { Card, CardHeader, CardTitle, CardContent } from '@/components/ui/card'
import { cn } from '@/lib/utils'

interface StatsCardProps {
  title: string
  value: string | number
  change?: number
  className?: string
}

export function StatsCard({ title, value, change, className }: StatsCardProps) {
  return (
    <Card className={cn('', className)}>
      <CardHeader className="pb-2">
        <CardTitle className="text-sm font-medium text-muted-foreground">
          {title}
        </CardTitle>
      </CardHeader>
      <CardContent>
        <div className="text-2xl font-bold">{value}</div>
        {change !== undefined && (
          <p
            className={cn(
              'text-xs',
              change >= 0 ? 'text-emerald-600' : 'text-red-600'
            )}
          >
            {change >= 0 ? '+' : ''}{change}% from last month
          </p>
        )}
      </CardContent>
    </Card>
  )
}

// ---- Usage: shadcn/ui + custom components together ----

import { Button } from '@/components/ui/button'
import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from '@/components/ui/dialog'
import { StatsCard } from '@/components/dashboard/stats-card'

export function Dashboard() {
  return (
    <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-4">
      <StatsCard title="Total Revenue" value="$45,231.89" change={20.1} />
      <StatsCard title="Subscriptions" value="+2,350" change={180.1} />
      <StatsCard title="Active Users" value="+12,234" change={19} />
      <StatsCard title="Churn Rate" value="-2.4%" change={-4.5} />

      <Dialog>
        <DialogTrigger asChild>
          <Button variant="outline">Create Invoice</Button>
        </DialogTrigger>
        <DialogContent>
          <DialogHeader>
            <DialogTitle>New Invoice</DialogTitle>
          </DialogHeader>
          {/* Form content */}
        </DialogContent>
      </Dialog>
    </div>
  )
}

// ============================================
// Tailwind Performance — Bundle Size Optimization
// ============================================

// ---- Rule 1: Content paths must be precise ----
// Include only files that use Tailwind classes

/* globals.css */
/* @source "../app/**/*.{ts,tsx}";
@source "../components/**/*.{ts,tsx}";
@source "../lib/**/*.{ts,tsx}";
// Do NOT include:
// @source "../**/*.{ts,tsx}";  <- Too broad, scans node_modules
// @source "../.next/**/*";     <- Build artifacts, includes generated code */

// ---- Rule 2: Never construct class names dynamically ----
// Tailwind scans for literal class strings — it cannot evaluate expressions

// WRONG: Dynamic class construction — Tailwind cannot detect these
function getBadgeColor(status: string) {
  const colors: Record<string, string> = {
    active: 'bg-green-500 text-white',
    inactive: 'bg-gray-500 text-white',
    pending: 'bg-yellow-500 text-black',
  }
  return colors[status] ?? 'bg-gray-500 text-white'
}

// This works at runtime, but Tailwind cannot detect the classes
// during build. They may be purged if not used elsewhere.

// CORRECT: Use a lookup object with full class strings
// AND list all possible classes in a safelist comment

/* safelist comment — ensures Tailwind includes these classes */
/*
tailwind safelist:
bg-green-500 text-white
bg-gray-500 text-white
bg-yellow-500 text-black
*/

// OR: Use cva for variants (preferred)
import { cva } from 'class-variance-authority'

const badgeVariants = cva(
  'inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium',
  {
    variants: {
      status: {
        active: 'bg-green-500 text-white',
        inactive: 'bg-gray-500 text-white',
        pending: 'bg-yellow-500 text-black',
      },
    },
    defaultVariants: {
      status: 'active',
    },
  }
)

// cva outputs full class strings — Tailwind detects them during build

// ---- Rule 3: Avoid template literals for class names ----

// WRONG: Template literal — Tailwind cannot parse this
const size = 'md'
const className = `p-${size === 'sm' ? '2' : size === 'md' ? '4' : '6'}`

// CORRECT: Map sizes to full class strings
const sizeClasses = {
  sm: 'p-2',
  md: 'p-4',
  lg: 'p-6',
} as const

const className2 = sizeClasses[size as keyof typeof sizeClasses]

// ---- Bundle size monitoring in CI ----
// File: scripts/check-css-size.sh

// #!/bin/bash
// # Build CSS and check size
// npx tailwindcss --input app/globals.css --output /tmp/tw-output.css --minify
// SIZE=$(wc -c < /tmp/tw-output.css)
// MAX_SIZE=150000  # 150KB max
//
// if [ $SIZE -gt $MAX_SIZE ]; then
//   echo "CSS bundle too large: ${SIZE} bytes (max: ${MAX_SIZE})"
//   echo "Check for @apply usage or dynamic class construction"
//   exit 1
// fi
//
// echo "CSS bundle OK: ${SIZE} bytes"

// ---- Performance comparison ----
/*
Scenario                    | CSS Size (minified) | Gzipped
---------------------------|--------------------|--------
Clean Tailwind (10 pages)  | 12KB               | 3KB
With @apply (180 classes)  | 450KB              | 92KB
Component extraction        | 142KB              | 22KB
After optimization          | 45KB               | 8KB
*/

// ---- Tailwind v4: Built-in performance features ----
// v4 uses Lightning CSS for faster builds and smaller output

/* Key v4 performance improvements:
- Lightning CSS replaces PostCSS — 10x faster builds
- Automatic content detection in v4 — no content array needed for most projects
- Smaller default utility set — only generates utilities used in your project
- @utility directives are tree-shakeable — unlike @apply in v3
*/

// io.thecodeforge — javascript tutorial

// Product grid with responsive columns, no custom CSS
import { products } from './api/products'

export default function ProductGrid() {
  return (
    <div className="grid grid-cols-2 gap-4 md:grid-cols-3 lg:grid-cols-4 xl:grid-cols-5">
      {products.map((product) => (
        <div key={product.id} className="border rounded-lg p-4 shadow-sm hover:shadow-md transition-shadow">
          <img src={product.image} alt={product.name} className="w-full h-48 object-cover rounded" />
          <h3 className="mt-2 font-medium">{product.name}</h3>
          <p className="text-sm text-gray-600">${product.price}</p>
        </div>
      ))}
    </div>
  )
}

// io.thecodeforge — javascript tutorial

// Consistent spacing throughout a card component
export default function Card({ title, children }) {
  return (
    <div className="max-w-sm rounded-lg border border-gray-200 shadow-sm bg-white">
      {/* Always p-4 for card padding */}
      <div className="p-4">
        {/* Titles always get mb-3 */}
        <h2 className="text-lg font-semibold text-gray-900 mb-3">{title}</h2>
        {/* Body content always uses gap-3 for internal spacing */}
        <div className="flex flex-col gap-3">
          {children}
        </div>
        {/* Action footer always gets mt-4 */}
        <div className="flex justify-end mt-4 pt-3 border-t border-gray-100">
          <button className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700 transition-colors">
            Action
          </button>
        </div>
      </div>
    </div>
  )
}

// io.thecodeforge — javascript tutorial

// Global typography normalization in your CSS entry point
// No utility classes needed on headings

@layer base {
  h1 {
    @apply text-3xl font-bold text-gray-900 mb-4 leading-tight;
  }
  h2 {
    @apply text-2xl font-semibold text-gray-800 mb-3 leading-snug;
  }
  h3 {
    @apply text-xl font-medium text-gray-700 mb-2 leading-normal;
  }
  p {
    @apply text-base text-gray-600 leading-relaxed mb-4;
  }
  a {
    @apply text-blue-600 underline hover:text-blue-800 transition-colors;
  }
}

// Then in your React code:
// <h1>This gets styled automatically</h1>
// <p>So does this. No classes needed.</p>

// io.thecodeforge — javascript tutorial

function ResponsiveCardGrid() {
  // Container query: adapts to parent width, not viewport
  return (
    <div class="@container">
      <div class="grid grid-cols-[repeat(auto-fill,minmax(280px,1fr))] gap-4">
        <div class="@[600px]:flex-row flex-col bg-gray-100 p-4 rounded">
          <img src="/thumb.png" class="w-full @[600px]:w-32" />
          <div class="mt-2 @[600px]:mt-0 @[600px]:ml-4">
            <h3 class="text-lg font-semibold">Item Title</h3>
            <p class="text-sm text-gray-600">Content adapts to container width, not viewport.</p>
          </div>
        </div>
      </div>
    </div>
  );
}

export default ResponsiveCardGrid;

// io.thecodeforge — javascript tutorial

/* No tailwind.config.js needed */
@import 'tailwindcss';

@theme {
  --color-brand: #f06;
  --color-surface: oklch(0.97 0.01 286);
  --font-display: 'Inter', sans-serif;
  --breakpoint-wide: 90rem;
}

@plugin '@tailwindcss/typography';

@layer base {
  body {
    font-family: var(--font-display);
    background-color: var(--color-surface);
  }
}

@layer utilities {
  .text-balance {
    text-wrap: balance;
  }
}