Tailwind CSS v4 and shadcn/ui Compatibility Guide

Tailwind CSS v4 and shadcn/ui Compatibility Guide

This document outlines the solutions implemented to ensure compatibility between Tailwind CSS v4 and shadcn/ui components in the Bartendie authentication UI.

Overview

Bartendie uses Tailwind CSS v4.1.10 with shadcn/ui components. This combination required specific configuration adjustments to ensure proper styling and functionality.

Configuration Solutions

1. PostCSS Configuration

File: frontend/postcss.config.js

export default {
  plugins: {
    '@tailwindcss/postcss': {},
    autoprefixer: {},
  },
}

Key Points:

• Uses @tailwindcss/postcss plugin instead of the traditional tailwindcss plugin
• This is the recommended approach for Tailwind CSS v4

2. Tailwind Configuration

File: frontend/tailwind.config.js

/** @type {import('tailwindcss').Config} */
export default {
  darkMode: ["class"],
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {
      borderRadius: {
        lg: "var(--radius)",
        md: "calc(var(--radius) - 2px)",
        sm: "calc(var(--radius) - 4px)",
      },
      colors: {
        // CSS custom properties for theming
        background: "hsl(var(--background))",
        foreground: "hsl(var(--foreground))",
        // ... other color definitions
      },
    },
  },
  plugins: [require("tailwindcss-animate")],
}

Key Features:

• Uses CSS custom properties for theming
• Maintains compatibility with shadcn/ui color system
• Supports dark mode with class-based strategy

3. CSS Setup with v4 Syntax

File: frontend/src/index.css

@import "tw-animate-css";

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

@tailwind base;
@tailwind components;
@tailwind utilities;

:root {
  --radius: 0.5rem;
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  /* ... other CSS variables */
}

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  /* ... dark mode variables */
}

@layer base {
  * {
    border-color: hsl(var(--border));
    outline-color: hsl(var(--ring) / 0.5);
  }
  body {
    background-color: hsl(var(--background));
    color: hsl(var(--foreground));
  }
}

Key Features:

• @custom-variant dark - New v4 syntax for custom variants
• CSS custom properties for consistent theming
• Base layer styles for global consistency

New Tailwind CSS v4 Features Used

1. Enhanced Shadow Utilities

// In shadcn/ui components
"shadow-xs hover:bg-primary/90"

• shadow-xs - New extra-small shadow utility in v4
• Provides more granular shadow control

2. Advanced Selector Syntax

// In button component
"has-[>svg]:px-3"

• has-[] - New CSS :has() selector support
• Enables conditional styling based on child elements

3. Size Utilities

// In button component
"size-9"

• size-* - New unified width/height utilities
• Replaces separate w-* and h-* classes for square elements

4. Improved Dark Mode

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

• More efficient dark mode implementation
• Better performance than traditional class-based approach

Component Compatibility

Authentication Components

All authentication components successfully use v4 features:

1. LoginPage.tsx - Uses new shadow and spacing utilities
2. RegisterPage.tsx - Implements advanced form styling
3. AccountSettingsPage.tsx - Leverages new layout utilities
4. ForgotPasswordPage.tsx - Uses enhanced color system

shadcn/ui Components

Compatible components include:

• Button - Uses shadow-xs, has-[] selectors, size-* utilities
• Input - Implements new focus-visible styles
• Card - Uses enhanced shadow and border utilities
• Checkbox - Leverages new state-based styling
• Label - Uses improved typography utilities

Build Process

Development

npm run dev

• Vite development server with hot reload
• Real-time CSS compilation with v4 features
• No compatibility warnings or errors

Production

npm run build

• Successful production builds
• Optimized CSS output with v4 utilities
• No breaking changes or compatibility issues

Best Practices

1. CSS Variable Usage

/* Preferred approach for theming */
background-color: hsl(var(--background));
color: hsl(var(--foreground));

2. Component Styling

// Use CSS variables for consistent theming
className="bg-background text-foreground border-border"

3. Dark Mode Implementation

// Use the class-based dark mode strategy
<div className="dark:bg-background dark:text-foreground">

Troubleshooting

Common Issues and Solutions

1. CSS Variables Not Working

   • Ensure CSS variables are defined in :root
   • Check that hsl() function is used correctly

2. Dark Mode Not Applying

   • Verify @custom-variant dark is defined
   • Check that darkMode: ["class"] is set in config

3. Build Errors

   • Ensure @tailwindcss/postcss plugin is used
   • Verify all imports are correct in CSS file

Dependencies

{
  "dependencies": {
    "@tailwindcss/postcss": "^4.1.10",
    "tailwindcss": "^4.1.10",
    "tailwindcss-animate": "^1.0.7"
  }
}

Conclusion

The Tailwind CSS v4 and shadcn/ui integration in Bartendie is fully functional with:

• ✅ Proper configuration for v4 features
• ✅ Compatible component implementations
• ✅ Successful development and production builds
• ✅ Enhanced styling capabilities with new v4 utilities

This setup provides a solid foundation for future UI development with modern Tailwind CSS features and shadcn/ui components.