CSS-in-JS vs Tailwind vs CSS Modules

s-variance-authority'; import type { ButtonHTMLAttributes } from 'react';

const buttonVariants = cva( 'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50', { variants: { variant: { primary: 'bg-[var(--color-primary)] text-white hover:bg-[var(--color-primary-hover)]', secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200', }, size: { sm: 'h-8 px-3 text-sm', md: 'h-10 px-4 text-base', lg: 'h-12 px-6 text-lg', }, }, defaultVariants: { variant: 'primary', size: 'md', }, } );

interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {}

export function Button({ className, variant, size, ...props }: ButtonProps) { return ( <button className={buttonVariants({ variant, size, className })} {...props} /> ); }

**CSS-in-JS (Runtime Dynamic Styling)**
```tsx
// src/components/DynamicBadge/index.tsx
import { styled } from '@emotion/react';
import type { ReactNode } from 'react';

interface BadgeProps {
  children: ReactNode;
  active: boolean;
  theme: 'light' | 'dark';
}

const Badge = styled.span<{ active: boolean; theme: 'light' | 'dark' }>`
  display: inline-flex;
  align-items: center;
  padding: 0.25rem 0.75rem;
  border-radius: 9999px;
  font-size: 0.75rem;
  font-weight: 500;
  background: ${({ active, theme }) =>
    active
      ? theme === 'dark'
        ? '#3b82f6'
        : '#2563eb'
      : theme === 'dark'
      ? '#334155'
      : '#e2e8f0'};
  color: ${({ active }) => (active ? '#ffffff' : '#0f172a')};
`;

export function DynamicBadge({ children, active, theme }: BadgeProps) {
  return <Badge active={active} theme={theme}>{children}</Badge>;
}

Step 4: Architecture Rationale

• Use CSS Modules for component isolation and layout structure. Hashed class names prevent collisions without runtime overhead.
• Use Tailwind for utility composition, spacing, typography, and responsive breakpoints. Enforce design tokens via tailwind.config.ts to prevent arbitrary value sprawl.
• Use CSS-in-JS exclusively for props-driven dynamic styling that cannot be resolved at build time. Limit usage to interactive states, user-driven themes, or data-visual components.
• Maintain a single PostCSS pipeline to avoid duplicate transformations. Configure class-variance-authority or cva to bridge Tailwind utilities with TypeScript type safety.

Pitfall Guide

1. Runtime CSS-in-JS on SSR/SSG causing hydration mismatches Runtime style injection during server rendering creates style sheets that don't match client hydration. This triggers CLS, forces style recalculations, and breaks streaming SSR. Mitigation: Use static extraction plugins (@emotion/react with extractCritical, styled-components babel plugin) or migrate dynamic styles to CSS variables.

2. Tailwind arbitrary value abuse breaking design consistency Developers bypass the design system by using bg-[#ff5733] or w-[375px]. This fragments the token graph, disables purging heuristics, and creates maintenance debt. Mitigation: Enforce tailwind.config.ts token usage, enable @tailwindcss/typography and @tailwindcss/forms, and configure ESLint rules to flag arbitrary values in CI.

3. CSS Modules class name collisions in nested/shared components When multiple components import the same module or use global selectors, scoping breaks. This occurs when developers mix .global classes with module imports. Mitigation: Prefix module classes with [name]__, avoid global selectors in .module.css, and use :global() explicitly only for third-party library overrides.

4. Ignoring critical CSS extraction for Tailwind/CSS-in-JS Shipping full utility libraries or runtime style sheets to production inflates initial payload. Modern bundlers don't automatically extract critical styles for above-the-fold content. Mitigation: Configure next/font and next/image to minimize blocking resources, use critters or next-purgecss for static extraction, and defer non-critical style injection.

5. Over-engineering theme providers for simple applications Wrapping entire component trees in context providers for single-button state changes introduces unnecessary re-renders and hydration complexity. Mitigation: Use CSS custom properties toggled via data-theme attributes on <html> or <body>. Reserve React context for complex state synchronization, not style switching.

6. Failing to configure content paths correctly Tailwind's AOT engine scans files to generate utilities. Missing paths result in missing styles or bloated output. CSS-in-JS requires explicit babel/webpack configuration to extract styles. Mitigation: Validate content array in tailwind.config.ts, run npx tailwindcss build --dry to preview output, and audit bundle with webpack-bundle-analyzer.

7. Mixing paradigms without explicit boundaries Combining Tailwind utilities, CSS Modules, and CSS-in-JS in the same component creates specificity wars, unpredictable cascade behavior, and debugging nightmares. Mitigation: Establish team conventions: CSS Modules for structure, Tailwind for utilities, CSS-in-JS only for runtime props. Enforce via linting and code review checklists.

Production Bundle

Action Checklist

• Audit current styling stack: Identify runtime vs compile-time vs static patterns in use
• Configure PostCSS pipeline: Single pass for CSS Modules, Tailwind, and autoprefixer
• Define design tokens: Map colors, spacing, typography to CSS custom properties
• Enforce utility discipline: Configure ESLint to flag arbitrary Tailwind values
• Extract critical CSS: Implement build-time extraction for SSR/SSG routes
• Benchmark bundle size: Run next build and analyze CSS/JS payload deltas
• Establish boundary rules: Document which paradigm handles structure, utilities, and dynamic props
• Add type safety: Use class-variance-authority or @stitches/react for variant composition

Decision Matrix

Configuration Template

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

const config: Config = {
  content: [
    './src/**/*.{ts,tsx,mdx}',
    './app/**/*.{ts,tsx,mdx}',
  ],
  theme: {
    extend: {
      colors: {
        primary: 'var(--color-primary)',
        surface: 'var(--color-surface)',
        text: 'var(--color-text)',
      },
      borderRadius: {
        md: 'var(--radius-md)',
      },
      boxShadow: {
        sm: 'var(--shadow-sm)',
      },
      fontFamily: {
        sans: 'var(--font-sans)',
      },
    },
  },
  plugins: [],
  future: {
    hoverOnlyWhenSupported: true,
  },
};

export default config;

// tsconfig.json (relevant section)
{
  "compilerOptions": {
    "plugins": [
      { "name": "next" }
    ],
    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "isolatedModules": true,
    "strict": true,
    "noUncheckedIndexedAccess": true
  }
}

// postcss.config.mjs
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
    'postcss-modules': {
      generateScopedName: '[name]__[local]___[hash:base64:5]',
      localsConvention: 'camelCase',
      globalModulePaths: [/node_modules/],
    },
  },
};

Quick Start Guide

1. Initialize project with npx create-next-app@latest my-app --typescript --tailwind --app. This scaffolds Next.js 14 with TypeScript and Tailwind preconfigured.
2. Install CSS Modules support: npm i -D postcss postcss-modules autoprefixer. Create postcss.config.mjs using the template above.
3. Define tokens in src/tokens/design-tokens.css and import it in your root layout. Replace hardcoded values in tailwind.config.ts with var() references.
4. Add class-variance-authority for type-safe variant composition: npm i class-variance-authority clsx tailwind-merge. Create a cn() utility to merge classes safely.
5. Run npm run dev and verify output with npx tailwindcss build --dry to confirm AOT generation. Audit bundle with npx @next/bundle-analyzer to validate CSS/JS payload distribution.