Upgrade Guide

Upgrading the design system from version 2.x → 3.x

Follow this guide to upgrade your project to version 3.x which uses TailwindCSS version 4.x.

The UAE Design System v3 is built on Tailwind CSS v4, bringing significant performance improvements and modern CSS features. This guide will walk you through the upgrade process step by step.

Before you start

Make sure you have a backup of your project or are working in a version-controlled environment before beginning the upgrade process.

Upgrade steps

Follow these steps to upgrade your project to Tailwind CSS v4 with the UAE Design System plugin.

1
Prepare your Tailwind configuration
Before switching to the new version of the UAE Design System, it's recommended to bring your Tailwind CSS setup up to date.

Start by removing the old UAE Design System references from your tailwind.config.js so the Tailwind upgrade tool can handle updates without conflicts.

tailwind.config.js
```
 module.exports = {
   content: ['./src/**/*.{html,js}'],
   // other stuff...
-  plugins: [
-  require('@aegov/design-system'),
-  require('@tailwindcss/typography'),
-  require('@tailwindcss/forms'),
- ],
 }
```
Then, run the Tailwind upgrade utility:
```
npx @tailwindcss/upgrade
```
2
Install UAE Design System v3
Next, install the latest release of the UAE Design System:
```
npm i -D @aegov/design-system@latest
```
After installing, include it in your CSS entry file:

App.css
```
/* New Tailwind v4 syntax */
@layer base;
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";
@plugin "@aegov/design-system";

/* User overrides work as expected */
@theme {
  /* Your config settings will be here */
}
```
You're Almost Done!

At this point, your project should be running with v3. If anything doesn't look right, check the docs or reach out to the UAE Design System support channels.

Key changes in v4

Understanding the major differences between Tailwind CSS v3 and v4 will help you make the most of the upgrade.

CSS-First Configuration

Configuration is now done directly in CSS using the @theme directive instead of a JavaScript tailwind.config.js file. This makes your project cleaner and configuration more intuitive.

Simplified Installation

Uses a single @import "tailwindcss" statement instead of multiple @tailwind directives, making setup simpler and more straightforward.

Automatic Content Detection

No need to configure the content array—Tailwind automatically detects your template files and generates only the CSS you need.

Performance Improvements

Full rebuilds are over 3.5x faster, and incremental builds are over 8x faster than v3, significantly improving your development experience.

Modern CSS Features

Leverages native cascade layers, registered custom properties, color-mix(), and logical properties for better browser integration.

Migrating your theme configuration

If you have custom theme configurations in your tailwind.config.js, you'll need to migrate them to CSS using the @theme directive.

Example Migration

Before (v3) - tailwind.config.js:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        'brand-blue': '#0066cc',
        'brand-red': '#dc2626',
      },
      spacing: {
        '128': '32rem',
      },
      borderRadius: {
        '4xl': '2rem',
      }
    }
  }
}

After (v4) - In your CSS file:

/* In your CSS file */
@theme {
  --color-brand-blue: #0066cc;
  --color-brand-red: #dc2626;
  --spacing-128: 32rem;
  --radius-4xl: 2rem;
}

Learn More

For detailed information on extending the default theme and migrating your configuration, visit the official Tailwind CSS documentation on theme configuration.

Troubleshooting

Common issues you might encounter during the upgrade and how to resolve them.

Styles not applying after upgrade

Make sure you've updated your CSS file with the correct v4 syntax:

Check that you're using @import "tailwindcss" instead of @tailwind directives
Verify that @plugin "@aegov/design-system" is included in your CSS file
Ensure you've removed the old tailwind.config.js file or it's not conflicting

Build errors

If you encounter build errors:

Clear your build cache and node_modules folder, then reinstall dependencies
Make sure all Tailwind-related packages are updated to v4-compatible versions
Check that your build tool (Vite, PostCSS, etc.) is configured correctly for v4

Custom theme values not working

If your custom theme values aren't applying:

Verify you're using the correct CSS variable naming convention (e.g., --color-brand instead of colors.brand)
Make sure the @theme directive is placed after the @plugin directives
Check that you're referencing the variables correctly in your HTML classes

Getting PostCSS errors

If you encounter PostCSS errors after upgrading, you may need to install additional dependencies and update your PostCSS configuration.

Install required packages:

npm i postcss postcss-cli tailwindcss @tailwindcss/postcss

Update postcss.config.js:

// postcss.config.js
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {}
  }
};

Custom CSS classes showing unknown utility errors

If you have added custom CSS in your CSS file, you might encounter errors like Cannot apply unknown utility class `text-whitely-50` during the initial upgrade. Don't worry about this error—continue with the following steps:

Step 1: Install the latest Design System version

npm i -D @aegov/design-system@latest

Step 2: Manually remove old version from package.json

After installation, open your package.json file and manually remove the old version reference (e.g., "@aegov/design-system": "^2.3.0").

Step 3: Run the upgrade command again

Execute the Tailwind upgrade utility once more to complete the migration:

npx @tailwindcss/upgrade

This command will automatically update old Tailwind classes to their v4 equivalents across your code files (e.g., shrink-0 → shrink-0). The error with custom classes should now be resolved.

Learn About Class Changes

For a complete list of what's changed in Tailwind CSS v4 and which classes are automatically migrated, visit the official Tailwind CSS v4 upgrade guide.

Additional Resources

Learn more about Tailwind CSS v4 and the upgrade process.