Tailwind 4 no more config.js

[raedweb]

Dear Team,

As per docuemnt installation show sthat tailwind configuration file and in version 4 no need for it as can be inside
https://designsystem.gov.ae/docs/installation

What is your advice?

/* your tailwind.config.js file */

module.exports = {
content: ["./src/**/*.{html,js}"],
future: {
hoverOnlyWhenSupported: false,
},
theme: {
extend: {},
},
plugins: [
require('@aegov/design-system'),
require('@tailwindcss/typography'),
require('@tailwindcss/forms')
],
}

[fatimamassou]

You’re right that Tailwind v4 allows inline configuration and no longer strictly requires a tailwind.config.js.

However, with SPFx 1.22 + Heft, the limitation is the SPFx build pipeline, not Tailwind:

• SPFx does not process PostCSS or Tailwind directives.

• Only precompiled, plain CSS is supported.

• Tailwind plugins (like @aegov/design-system, forms, typography) must be resolved before SPFx builds.1

Because of this, even with Tailwind v4, keeping a Tailwind config and precompiling via the CLI is currently the safest approach for SPFx.

Hope this helps

[moiz-conceptlz]

@raedweb @fatimamassou

As of this day, the Design System version 2.3.x is not compatible with TailwindCSS 4.x

The new version of the design system - which is version 3.0.x will be 100% compatible with TailwindCSS 4.x. This version will be released on 12th Jan 2026 (2 days from now)

[raedweb]

Hi Moiz and Fatima,

Thank you for the great teamwork.

As we are starting with Tailwind CSS 4, I have a few questions related to the UAE Design System. From my understanding, the UAE Design System is built on top of Tailwind CSS. Could you please clarify the following points:

1. Do I only need to install the UAE Design System for documentation purposes using npm i @aegov/design-system? Or do I also need to install Tailwind CSS separately using npm install tailwindcss @tailwindcss/cli?
2. If we install only the UAE Design System, will all the elements and components available in the public Tailwind CSS library work seamlessly? Could you please elaborate to help me understand better?
3. If we need to install the UAE Design System but want to customize the theme for the university, what would be your recommendation?
4. Since my website has many pages built on Bootstrap, what is your advice on the best approach to gradually migrate to the UAE Design System with Tailwind CSS? To avoid conflicts, I have seen suggestions about using prefix configuration. Can we proceed with that, or do you have other recommendations?
   5.From your team’s expertise, will any design or layout built with Bootstrap and custom CSS render correctly with Tailwind? Are there any tools to help convert Bootstrap-based layouts to Tailwind, or what would you recommend?

Looking forward to your confirmation and advice.

Regards,
Raed Shehada

[fatimamassou]

Hi @raedweb,

Thank you for your questions.

In short:

• The UAE Design System does not replace Tailwind CSS. Tailwind CSS (v4) still needs to be installed separately. The UAE Design System builds on top of it and provides tokens, components, and guidelines.

• All standard Tailwind utilities work normally alongside the UAE Design System.

• For university branding, we recommend extending the Tailwind theme in tailwind.config.js while keeping the UAE Design System as the base.

• A gradual migration from Bootstrap is the safest approach. Using a Tailwind prefix is a good way to avoid conflicts while both frameworks coexist.

• Bootstrap layouts won’t automatically convert to Tailwind. There’s no reliable automated tool, so we suggest progressive refactoring component by component.

Happy to discuss or review the setup if needed.

Best regards,
Fatima

[moiz-conceptlz]

Hello @raedweb

I will explain and clarify all your questions.

But first, do not use the @aegov/design-system (version 2.3.x) with TailwindCSS 4.x. Please wait for the release of @aegov/design-system version 3.0.x

Now, your questions:

1. @aegov/design-system is a TailwindCSS plugin. This means when you install this via npm, it will automatically download and install TailwindCSS 3.x and all other required dependencies. This plugin is a core part of development and not for documentation. It must be used to ensure all classes required for the design system are generated.

2. When you install @aegov/design-system, TailwindCSS will also be installed as a dependency. This means you can use every functionality of TailwindCSS itself in any part of your project which is not using a component. You can code other parts of your website or anything else that is a custom requirement using the classes of TailwindCSS.

3. You can certainly do this.

• Install the design system plugin
• Add it to the config file
• use components where you need and anything you dont want to use a default component, create your own
• add classes to your own component or template directly of tailwindCSS
• compile the project

4. Prefix will cause an issue with the UAE Design System components. We already have a prefix called aegov-* and therefore it may not be the best approach. Now you have 2 options.

• carefully check page templates and make changes, upgrading the code of classes, removing bootstrap, adding TailwindCSS and making changes as required. This will result is very clean and well managed code for the future.
• override the boostrap classes by creating a class in your CSS file, and instead of adding TailwindCSS as classes in the HTML, add them using the @apply directive in the CSS file. Here is a link to functions and directives to understand how to use @apply for a custom CSS class - https://tailwindcss.com/docs/functions-and-directives

5. There are many tools online that do conversions. I do not trust any of them for 100% results. You must first understand that there is a critical difference between Bootstrap and TailwindCSS. Bootstrap is a CSS framework which has opinionated results. It means, in a sense - Bootstrap itself is a design system. There is fixed colours and design set for elements. TailwindCSS is a utility framework. It has no design elements attached to it. It only provides an easy and manageable way of writing CSS. It is my opinion, using convertors will still need a lot of oversight in terms of making sure things are actually converted correctly.