Tailwind CSS Architecture for Large Applications

The Tailwind Scaling Problem

Tailwind CSS is excellent for small to medium projects. On large applications (50+ components, multiple developers), you hit real problems: inconsistent spacing, duplicated class strings, components that are impossible to read, and no single source of truth for your design system.

This guide covers the patterns we use at TechSaaS to scale Tailwind across a 23-page Next.js application.

Pattern 1: Design Tokens in tailwind.config.ts

Your tailwind config is your design system. Extend it with semantic tokens:

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

const config: Config = {
  content: ['./src/**/*.{ts,tsx}'],
  theme: {
    extend: {
      colors: {
        // Semantic colors (not blue-500, but 'primary')
        primary: {
          50: '#eff6ff',
          100: '#dbeafe',
          500: '#3b82f6',
          600: '#2563eb',
          700: '#1d4ed8',
          900: '#1e3a5f',
        },
        surface: {
          DEFAULT: '#ffffff',
          secondary: '#f8fafc',
          tertiary: '#f1f5f9',
        },
        content: {
          DEFAULT: '#0f172a',
          secondary: '#475569',
          tertiary: '#94a3b8',
        },
        success: { DEFAULT: '#10b981', light: '#d1fae5' },
        warning: { DEFAULT: '#f59e0b', light: '#fef3c7' },
        danger:  { DEFAULT: '#ef4444', light: '#fee2e2' },
      },
      spacing: {
        // Consistent spacing scale
        'section': '5rem',
        'card': '1.5rem',
        'input': '0.75rem',
      },
      borderRadius: {
        'card': '0.75rem',
        'button': '0.5rem',
        'input': '0.375rem',
      },
      fontSize: {
        'heading-1': ['2.25rem', { lineHeight: '2.5rem', fontWeight: '700' }],
        'heading-2': ['1.875rem', { lineHeight: '2.25rem', fontWeight: '600' }],
        'heading-3': ['1.5rem', { lineHeight: '2rem', fontWeight: '600' }],
        'body': ['1rem', { lineHeight: '1.75rem' }],
        'caption': ['0.875rem', { lineHeight: '1.25rem' }],
      },
      boxShadow: {
        'card': '0 1px 3px rgba(0, 0, 0, 0.08), 0 1px 2px rgba(0, 0, 0, 0.06)',
        'card-hover': '0 4px 12px rgba(0, 0, 0, 0.1)',
        'dropdown': '0 10px 40px rgba(0, 0, 0, 0.12)',
      },
    },
  },
  plugins: [],
};

export default config;

Now your components use semantic names:

// Instead of: bg-white border border-gray-200 shadow-sm rounded-lg p-6
// Write:
<div className="bg-surface shadow-card rounded-card p-card">

Pattern 2: Component Class Composition with CVA

Class Variance Authority (CVA) creates type-safe component variants:

npm install class-variance-authority clsx tailwind-merge

// lib/utils.ts
import { type ClassValue, clsx } from 'clsx';
import { twMerge } from 'tailwind-merge';

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

// 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 font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 disabled:opacity-50 disabled:pointer-events-none',
  {
    variants: {
      variant: {
        primary: 'bg-primary-600 text-white hover:bg-primary-700',
        secondary: 'bg-surface border border-gray-200 text-content hover:bg-surface-secondary',
        danger: 'bg-danger text-white hover:bg-red-600',
        ghost: 'text-content-secondary hover:bg-surface-tertiary',
        link: 'text-primary-600 underline-offset-4 hover:underline',
      },
      size: {
        sm: 'h-8 px-3 text-caption rounded-button',
        md: 'h-10 px-4 text-body rounded-button',
        lg: 'h-12 px-6 text-body rounded-button',
        icon: 'h-10 w-10 rounded-button',
      },
    },
    defaultVariants: {
      variant: 'primary',
      size: 'md',
    },
  }
);

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

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

Usage:

<Button>Primary</Button>
<Button variant="secondary" size="lg">Secondary Large</Button>
<Button variant="danger" size="sm">Delete</Button>
<Button variant="ghost" size="icon"><TrashIcon /></Button>

Pattern 3: Card Component System

// components/ui/card.tsx
const cardVariants = cva(
  'bg-surface rounded-card border border-gray-100 transition-shadow',
  {
    variants: {
      padding: {
        none: '',
        sm: 'p-4',
        md: 'p-card',
        lg: 'p-8',
      },
      interactive: {
        true: 'hover:shadow-card-hover cursor-pointer',
        false: 'shadow-card',
      },
    },
    defaultVariants: {
      padding: 'md',
      interactive: false,
    },
  }
);

export function Card({ className, padding, interactive, ...props }: CardProps) {
  return <div className={cn(cardVariants({ padding, interactive }), className)} {...props} />;
}

export function CardHeader({ className, ...props }: HTMLAttributes<HTMLDivElement>) {
  return <div className={cn('mb-4', className)} {...props} />;
}

export function CardTitle({ className, ...props }: HTMLAttributes<HTMLHeadingElement>) {
  return <h3 className={cn('text-heading-3 text-content', className)} {...props} />;
}

export function CardDescription({ className, ...props }: HTMLAttributes<HTMLParagraphElement>) {
  return <p className={cn('text-body text-content-secondary', className)} {...props} />;
}

Pattern 4: Responsive Layout Utilities

Create reusable layout components instead of repeating responsive classes:

// components/ui/container.tsx
export function Container({ children, className }: PropsWithChildren<{ className? }>) {
  return (
    <div className={cn('mx-auto w-full max-w-7xl px-4 sm:px-6 lg:px-8', className)}>
      {children}
    </div>
  );
}

// components/ui/section.tsx
export function Section({ children, className }: PropsWithChildren<{ className? }>) {
  return (
    <section className={cn('py-section', className)}>
      <Container>{children}</Container>
    </section>
  );
}

// components/ui/grid.tsx
interface GridProps {
  cols?: 1 | 2 | 3 | 4;
  gap?: 'sm' | 'md' | 'lg';
}

const gridCols = {
  1: 'grid-cols-1',
  2: 'grid-cols-1 md:grid-cols-2',
  3: 'grid-cols-1 md:grid-cols-2 lg:grid-cols-3',
  4: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-4',
};

const gridGaps = { sm: 'gap-4', md: 'gap-6', lg: 'gap-8' };

export function Grid({ cols = 3, gap = 'md', children }: PropsWithChildren<GridProps>) {
  return <div className={cn('grid', gridCols[cols], gridGaps[gap])}>{children}</div>;
}

Pattern 5: Tailwind Plugin for Custom Utilities

// tailwind.config.ts plugins section
import plugin from 'tailwindcss/plugin';

plugins: [
  plugin(function ({ addUtilities }) {
    addUtilities({
      '.text-balance': {
        'text-wrap': 'balance',
      },
      '.scrollbar-hide': {
        '-ms-overflow-style': 'none',
        'scrollbar-width': 'none',
        '&::-webkit-scrollbar': {
          display: 'none',
        },
      },
    });
  }),
],

Team Conventions

Document and enforce these with ESLint:

1. No arbitrary values: Use text-primary-600 not text-[#2563eb]
2. Semantic colors only: Use bg-surface not bg-white
3. Component variants over inline: Use <Button variant="danger"> not <button className="bg-red-500...">
4. Max className length: If a className string exceeds ~120 characters, extract to a CVA variant or component
5. Responsive mobile-first: Always start with mobile, then add md: and lg: breakpoints

These patterns have kept our TechSaaS codebase maintainable as it grew from 5 pages to 23 pages. Tailwind scales beautifully when you add the right abstractions on top.