feat(module): define tailwind utilities

[benjamincanac]

🔗 Linked issue

Resolves #3628

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

This is a proposal to define tailwind utilities to avoid writing CSS variables:

1. Colors

For each of our color aliases (design system), we define a --color-primary: var(--ui-primary) in Tailwind CSS @theme which lets us write:

• text-(--ui-primary) -> text-primary
• bg-(--ui-error)/10 -> bg-error/10
• ...

2. Neutral

By adding an @utility for each variable, this let us write:

• text-(--ui-text-muted) -> text-muted
• border-(--ui-border) -> border-default
• ...

4. Radius

It is a pain at the moment to write rounded classes so my suggestion is to override the default Tailwind CSS rounded-sm, rounded-md, etc. to use our --ui-radius CSS variable (which keeps the flexibility to change all of them at once):

• rounded-(--ui-radius) -> rounded-sm
• rounded-[calc(var(--ui-radius)*1.5)] -> rounded-md
• ...

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[pkg-pr-new]

npm i https://pkg.pr.new/@nuxt/ui@3629

commit: cc8d229

[nuxthub-admin]

✅ Deployed ui3

Deployed ui3 cc8d229 to preview

🔗	pr-3628.ui-6q2.pages.dev
📌	0204218b.ui-6q2.pages.dev
📱	View QR Code

📋 View deployment logs

[moshetanzer]

This is great. Will make migration easier and code cleaner.

[stijns96]

I think I even asked this already somewhere in one of my issues, but this would be so helpful. I really hate the fact that I constantly somehow have to remember what is available.

The only thing to keep in mind (what I still find a bit confusing) is adding custom styles, or get rid of the already existing tw colors. If I set colors to initial, the build is probably (thought I've tested it already, could be V2) going to break due to missing colors.

[jits]

This is an excellent proposal 🎉

daisyUI does something similar (example).

[XStarlink]

This library has become a joy to use with v3, the updated components, and its design system!
Thanks @benjamincanac for taking my proposal into account so quickly—that was really fast!

[sandros94]

The only thing to keep in mind (what I still find a bit confusing) is adding custom styles, or get rid of the already existing tw colors. If I set colors to initial, the build is probably (thought I've tested it already, could be V2) going to break due to missing colors.

The module requires a set of colors to be always defined to work properly (read more in theme's color section). Essentially it needs to know which are the new color values for them

[XStarlink]

@benjamincanac Do you think it would be interesting to add shades for text-primary, like text-primary-50, text-primary-100, and text-primary-200... ?

[benjamincanac]

@XStarlink We already have that in the 3.0.0, this PR adds the text-primary default without shade.

Here's where it's defined if you're interested: https://github.com/nuxt/ui/blob/v3/src/templates.ts#L90

[XStarlink]

@benjamincanac

Wow, excellent!
I hadn’t noticed that we could do that, I thought we had to access it using text-(--ui-color-primary-200) since the Theme page in the docs explained it with CSS variables. But I should have just tested it before asking...

Thanks for your incredible work!

[memic84]

@XStarlink We already have that in the 3.0.0, this PR adds the text-primary default without shade.

Here's where it's defined if you're interested: v3/src/templates.ts#L90

Sorry for asking this here, but i am a bit confused where to set the shades to work correctly.

I already have a tailwind setup v4 with --color-primary and with shades. Should these be added to app.config.ts to ui.colors.primary, as an object? Or just defined in my css file?

Does this mean, that in the current version bg-primary should also work as text-primary?

[sandros94]

I already have a tailwind setup v4 with --color-primary and with shades. Should these be added to app.config.ts to ui.colors.primary, as an object? Or just defined in my css file?

you should define them in your css file (either by overriding one of tailwinds colors or creating your own) and then set in the app.config.ts which one to use:

• assets/css/main.css
• app.config.ts

Does this mean, that in the current version bg-primary should also work as text-primary?

This very PR adds the support for using the default color, so directly using text-primary or bg-primary.
What is already available is text-primary-500 and bg-primary-500, since we do already define all the shades for each color this module provides

[memic84]

I am a bit confused with the new tailwind v4 config and not sure what's happening inside nuxt/ui.

I do have the color reset for the tailwind colors, as i don't use those: --color-*: initial;

And combined with the theme(static), it seems that i don't have access to bg-primary-400 for example in nuxt itself. This did work before without the static part.

It doesn't seem right to define all the shades in app.config and nuxt.config as a separate color, right?

Is there maybe a example project with the new config for v3?

It seems that in my project the tailwindcss classes (spacing, height) aren't all created after switching to nuxt/ui.

I still have my initial installation of tailwindcss as a vite plugin, is that correct or should nuxt/ui handle all that?

Also i am using layers, i guess that nuxt/ui has support for that.

UPDATE:
Got it cleared up, there's is a issue with tailwind >= 4.0.8 as also known here: #3374

@import "tailwindcss" theme(static);
@import "@nuxt/ui";

@theme static {
	--color-*: initial;
    --color-black: #000000;
    --color-white: #FFFFFF;
    --color-gray-50: #f9f9f9;
    --color-gray-100: #ececeb;
    --color-gray-200: #dbdcdd;
    --color-gray-300: #d1d3d5;
    --color-gray-400: #b1b3b5;
    --color-gray-500: #878d91;
    --color-gray-600: #737b82;
    --color-gray-700: #676c71;
    --color-gray-800: #595d61;
    --color-gray-900: #3d4045;
    --color-gray-950: #25272a;
    --color-gray: #737b82;
    --color-primary-50: #fff7f0;
    --color-primary-100: #ffead7;
    --color-primary-200: #ffd5b3;
    --color-primary-300: #ffb380;
    --color-primary-400: #ff8c4d;
    --color-primary-500: #ff6000;
    --color-primary-600: #ff5800;
    --color-primary-700: #e1410d;
    --color-primary-800: #c43600;
    --color-primary-900: #a02d00;
    --color-primary-950: #541800;
    --color-primary: #ff5800;
    --body-bg: #ffffff;
    --body-text-primary: #595d61;
    --body-text-secondary: #676c71;
    --body-text-tertiary: #878d91;
}

:root {
  --ui-bg: var(--body-bg);
  --ui-text: var(--body-text-primary);
  --ui-primary: var(--color-primary);
  --ui-gray: var(--color-gray);
  --ui-black: var(--color-black);
  --ui-white: var(--color-white);
}

nuxt.config.ts

  ui: {
    theme: {
      colors: ['primary', 'gray']
    },
    colorMode: false
  },

app.config.ts

  ui: {
    colors: {
      primary: 'primary',
      gray: 'gray'
    }
  }