Tailwind CSS Configuration | Next.js Supabase SaaS Kit

Configure Tailwind CSS 4, extend the design system, and customize styles across your Makerkit monorepo application.

Makerkit uses Tailwind CSS 4 with Shadcn UI for styling. All style configuration lives in apps/web/styles/, with the main entry point at globals.css. This guide covers how to customize Tailwind, add new packages to the content paths, and extend the design system.

Style File Structure

The styling system uses these files in apps/web/styles/:

apps/web/styles/
├── globals.css         # Main entry point, imports everything
├── shadcn-ui.css       # Theme colors (light/dark mode variables)
├── theme.css           # Maps CSS variables to Tailwind's @theme
├── theme.utilities.css # Custom utility classes
├── makerkit.css        # Makerkit-specific component styles
└── markdoc.css         # Content/documentation styles

Tailwind CSS 4 Configuration

Tailwind CSS 4 uses CSS-based configuration instead of JavaScript. The @theme directive in theme.css defines your design tokens:

@theme {
  /* Colors mapped from shadcn-ui.css variables */
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  /* Border radius */
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  /* Font families */
  --font-sans: -apple-system, var(--font-sans);
  --font-heading: var(--font-heading);
  /* Custom animations */
  --animate-fade-up: fade-up 0.5s;
  --animate-accordion-down: accordion-down 0.2s ease-out;
}

These tokens become available as Tailwind utilities: bg-primary, text-foreground, rounded-lg, etc.

Adding Content Paths for New Packages

When you create a new package in the monorepo, Tailwind needs to know where to scan for class names. Update apps/web/tailwind.config.ts:

import type { Config } from 'tailwindcss';
export default {
  content: [
    './app/**/*.{ts,tsx}',
    './components/**/*.{ts,tsx}',
    // Existing packages
    '../../packages/ui/src/**/*.tsx',
    '../../packages/billing/gateway/src/**/*.tsx',
    '../../packages/features/auth/src/**/*.tsx',
    '../../packages/features/notifications/src/**/*.tsx',
    '../../packages/features/admin/src/**/*.tsx',
    '../../packages/features/accounts/src/**/*.tsx',
    '../../packages/features/team-accounts/src/**/*.tsx',
    // Add your new package here
    '../../packages/features/your-feature/src/**/*.tsx',
    // Exclude node_modules
    '!**/node_modules',
  ],
} satisfies Config;

For packages using JSX (not TSX), update the glob pattern:

'../../packages/features/your-feature/src/**/*.{tsx,jsx}',

Custom Utility Classes

Add custom utilities in theme.utilities.css:

@layer utilities {
  /* Text balance for headings */
  .text-balance {
    text-wrap: balance;
  }
  /* Hide scrollbar but allow scrolling */
  .scrollbar-hidden {
    -ms-overflow-style: none;
    scrollbar-width: none;
  }
  .scrollbar-hidden::-webkit-scrollbar {
    display: none;
  }
  /* Gradient text */
  .text-gradient {
    background: linear-gradient(to right, var(--primary), var(--accent));
    -webkit-background-clip: text;
    -webkit-text-fill-color: transparent;
    background-clip: text;
  }
}

Extending the Theme

Add custom design tokens in theme.css:

@theme {
  /* Custom spacing */
  --spacing-18: 4.5rem;
  --spacing-22: 5.5rem;
  /* Custom colors */
  --color-brand: oklch(65% 0.2 250);
  --color-brand-light: oklch(85% 0.1 250);
  /* Custom font sizes */
  --font-size-xxs: 0.625rem;
  /* Custom shadows */
  --shadow-glow: 0 0 20px rgba(var(--primary), 0.3);
  /* Custom transitions */
  --transition-bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55);
}

Use these in your components:

<div className="p-18 bg-brand shadow-glow transition-all duration-300 ease-bounce">
  Content
</div>

Component-Level Styles

For complex component styles, use @layer components in makerkit.css:

@layer components {
  .card-hover {
    @apply transition-all duration-200;
    @apply hover:shadow-lg hover:-translate-y-0.5;
  }
  .btn-gradient {
    @apply bg-gradient-to-r from-primary to-accent;
    @apply text-primary-foreground;
    @apply hover:opacity-90 transition-opacity;
  }
  .input-focus {
    @apply focus:ring-2 focus:ring-ring focus:ring-offset-2;
    @apply focus:outline-none;
  }
}

Shadcn UI Component Customization

Override Shadcn component styles by targeting their classes. Common customizations:

@layer base {
  :root {
    /* Make buttons more rounded */
    --radius: 0.75rem;
    /* Stronger focus rings */
    --ring: var(--color-blue-500);
  }
}
@layer components {
  /* Custom button variants */
  .btn-primary-gradient {
    @apply bg-gradient-to-r from-blue-600 to-indigo-600;
    @apply hover:from-blue-700 hover:to-indigo-700;
  }
  /* Card with subtle border */
  .card-outlined {
    @apply border border-border/50;
    @apply hover:border-border transition-colors;
  }
}

Dark Mode Utilities

Create dark-mode-aware utilities:

@layer utilities {
  .glass {
    @apply bg-white/80 backdrop-blur-sm;
    @apply dark:bg-neutral-900/80;
  }
  .surface-elevated {
    @apply bg-white shadow-sm;
    @apply dark:bg-neutral-800 dark:shadow-none;
  }
  .border-subtle {
    @apply border-gray-200;
    @apply dark:border-neutral-700;
  }
}

Legacy Tailwind v3 Support

If you need to support Tailwind v3 (not recommended for new projects), the configuration file is at tooling/tailwind/index.ts. This approach uses JavaScript configuration:

import type { Config } from 'tailwindcss';
export default {
  content: [
    '../../packages/ui/src/**/*.tsx',
    // ... other paths
  ],
  theme: {
    extend: {
      colors: {
        border: 'hsl(var(--border))',
        input: 'hsl(var(--input))',
        ring: 'hsl(var(--ring))',
        background: 'hsl(var(--background))',
        foreground: 'hsl(var(--foreground))',
        primary: {
          DEFAULT: 'hsl(var(--primary))',
          foreground: 'hsl(var(--primary-foreground))',
        },
      },
    },
  },
} satisfies Config;

We recommend migrating to Tailwind CSS 4. See the Tailwind CSS 4 migration guide for instructions.

Common Mistakes

Missing content paths: New packages won't have their Tailwind classes compiled if you forget to add them to the content array. Styles will appear missing in production even if they work in development.

Using @apply excessively: Reserve @apply for reusable component patterns. For one-off styles, use utility classes directly in JSX. Excessive @apply increases CSS bundle size.

Forgetting @layer directives: Custom styles without @layer can have specificity issues. Always wrap custom styles in @layer base, @layer components, or @layer utilities.

Hardcoding colors: Use theme variables (bg-primary, text-foreground) instead of hardcoded colors (bg-blue-500). This ensures consistency and makes theme changes easier.

Verification

After modifying Tailwind configuration:

  1. Restart the dev server (Tailwind config changes require a restart)
  2. Run pnpm build to verify all classes compile correctly
  3. Check production build for missing styles: pnpm build && pnpm start
  4. Verify dark mode works for any new utilities
# Quick verification commands
pnpm dev          # Development server
pnpm build        # Production build (catches missing content paths)
pnpm typecheck    # Type checking

Frequently Asked Questions

Why are my Tailwind classes not working in production?
The most common cause is missing content paths in tailwind.config.ts. Add your package path to the content array and rebuild. Classes must exist in scanned files to be included in the production CSS bundle.
How do I add a completely custom color?
Define it in theme.css using the @theme directive: --color-brand: oklch(65% 0.2 250). Then use it as bg-brand or text-brand in your components.
Should I use @apply or inline utilities?
Prefer inline utilities for most cases. Use @apply only for frequently repeated patterns that need to stay in sync. Inline utilities are more explicit and easier to maintain.
How do I override Shadcn component styles?
Add overrides in shadcn-ui.css within @layer components. Target the specific component classes or create variant classes. You can also pass className props to override individual instances.

Next Steps