feat(module): add theme.prefix option (#5341)

Author: benjamincanac

docs/app/components/home/HomeContributors.vue

@@ -100,7 +100,7 @@ const { width } = useElementSize(el)
 }
 
 .dark .circle:after {
-  --highlight-color: var(--color-white);
+  --highlight-color: white;
 }
 
 .animation-paused.circle:after,

docs/content/docs/1.getting-started/2.installation/1.nuxt.md

@@ -256,7 +256,7 @@ Use the `prefix` option to change the prefix of the components.
 
 - Default: `U`{lang="ts-type"}
 
-```ts [nuxt.config.ts]
+```ts [nuxt.config.ts] {4-6}
 export default defineNuxtConfig({
   modules: ['@nuxt/ui'],
   css: ['~/assets/css/main.css'],
@@ -272,7 +272,7 @@ Use the `fonts` option to enable or disable the [`@nuxt/fonts`](https://github.c
 
 - Default: `true`{lang="ts-type"}
 
-```ts [nuxt.config.ts]
+```ts [nuxt.config.ts] {4-6}
 export default defineNuxtConfig({
   modules: ['@nuxt/ui'],
   css: ['~/assets/css/main.css'],
@@ -288,7 +288,7 @@ Use the `colorMode` option to enable or disable the [`@nuxt/color-mode`](https:/
 
 - Default: `true`{lang="ts-type"}
 
-```ts [nuxt.config.ts]
+```ts [nuxt.config.ts] {4-6}
 export default defineNuxtConfig({
   modules: ['@nuxt/ui'],
   css: ['~/assets/css/main.css'],
@@ -304,7 +304,7 @@ Use the `theme.colors` option to define the dynamic color aliases used to genera
 
 - Default: `['primary', 'secondary', 'success', 'info', 'warning', 'error']`{lang="ts-type" class="inline"}
 
-```ts [nuxt.config.ts]
+```ts [nuxt.config.ts] {4-8}
 export default defineNuxtConfig({
   modules: ['@nuxt/ui'],
   css: ['~/assets/css/main.css'],
@@ -326,7 +326,7 @@ Use the `theme.transitions` option to enable or disable transitions on component
 
 - Default: `true`{lang="ts-type"}
 
-```ts [nuxt.config.ts]
+```ts [nuxt.config.ts] {4-8}
 export default defineNuxtConfig({
   modules: ['@nuxt/ui'],
   css: ['~/assets/css/main.css'],
@@ -348,7 +348,7 @@ Use the `theme.defaultVariants` option to override the default `color` and `size
 
 - Default: `{ color: 'primary', size: 'md' }`{lang="ts-type"}
 
-```ts [nuxt.config.ts]
+```ts [nuxt.config.ts] {4-11}
 export default defineNuxtConfig({
   modules: ['@nuxt/ui'],
   css: ['~/assets/css/main.css'],
@@ -363,13 +363,71 @@ export default defineNuxtConfig({
 })
 ```
 
+### `theme.prefix` :badge{label="Soon"}
+
+Use the `theme.prefix` option to configure the same prefix you set on your Tailwind CSS import. This ensures Nuxt UI components use the correct prefixed utility classes and CSS variables.
+
+::code-group
+
+```ts [nuxt.config.ts] {4-8}
+export default defineNuxtConfig({
+  modules: ['@nuxt/ui'],
+  css: ['~/assets/css/main.css'],
+  ui: {
+    theme: {
+      prefix: 'tw'
+    }
+  }
+})
+```
+
+```css [app/assets/css/main.css] {1}
+@import "tailwindcss" prefix(tw);
+@import "@nuxt/ui";
+```
+
+::
+
+::warning{to="https://fonts.nuxt.com/get-started/configuration#processcssvariables"}
+You might need to enable `fonts.processCSSVariables` to use the prefix option with the `@nuxt/fonts` module:
+
+```ts [nuxt.config.ts] {9-11}
+export default defineNuxtConfig({
+  modules: ['@nuxt/ui'],
+  css: ['~/assets/css/main.css'],
+  ui: {
+    theme: {
+      prefix: 'tw'
+    }
+  },
+  fonts: {
+    processCSSVariables: true
+  }
+})
+```
+::
+
+This will automatically prefix all Tailwind utility classes and CSS variables in Nuxt UI component themes:
+
+```html
+<!-- Without prefix -->
+<button class="px-2 py-1 text-xs hover:bg-primary/75">Button</button>
+
+<!-- With prefix: tw -->
+<button class="tw:px-2 tw:py-1 tw:text-xs tw:hover:bg-primary/75">Button</button>
+```
+
+::note{to="https://tailwindcss.com/docs/styling-with-utility-classes#using-the-prefix-option" target="_blank"}
+Learn more about using a prefix in the Tailwind CSS documentation.
+::
+
 ### `mdc`
 
 Use the `mdc` option to force the import of Nuxt UI `<Prose>` components even if `@nuxtjs/mdc` or `@nuxt/content` is not installed.
 
 - Default: `false`{lang="ts-type"}
 
-```ts [nuxt.config.ts]
+```ts [nuxt.config.ts] {4-6}
 export default defineNuxtConfig({
   modules: ['@nuxt/ui'],
   css: ['~/assets/css/main.css'],
@@ -385,7 +443,7 @@ Use the `content` option to force the import of Nuxt UI `<Prose>` and `<UContent
 
 - Default: `false`{lang="ts-type"}
 
-```ts [nuxt.config.ts]
+```ts [nuxt.config.ts] {4-6}
 export default defineNuxtConfig({
   modules: ['@nuxt/ui'],
   css: ['~/assets/css/main.css'],
@@ -404,7 +462,7 @@ Use the `experimental.componentDetection` option to enable automatic component d
 
 **Enable automatic detection:**
 
-```ts [nuxt.config.ts]
+```ts [nuxt.config.ts] {4-8}
 export default defineNuxtConfig({
   modules: ['@nuxt/ui'],
   css: ['~/assets/css/main.css'],
@@ -418,7 +476,7 @@ export default defineNuxtConfig({
 
 **Include additional components for dynamic usage:**
 
-```ts [nuxt.config.ts]
+```ts [nuxt.config.ts] {4-8}
 export default defineNuxtConfig({
   modules: ['@nuxt/ui'],
   css: ['~/assets/css/main.css'],

docs/content/docs/1.getting-started/2.installation/2.vue.md

@@ -518,7 +518,7 @@ Use the `prefix` option to change the prefix of the components.
 
 - Default: `U`{lang="ts-type"}
 
-```ts [vite.config.ts]
+```ts [vite.config.ts] {9}
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
 import ui from '@nuxt/ui/vite'
@@ -537,7 +537,7 @@ export default defineConfig({
 
 Use the `ui` option to provide configuration for Nuxt UI.
 
-```ts [vite.config.ts]
+```ts [vite.config.ts] {9-14}
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
 import ui from '@nuxt/ui/vite'
@@ -563,7 +563,7 @@ Use the `colorMode` option to enable or disable the color mode integration from
 
 - Default: `true`{lang="ts-type"}
 
-```ts [vite.config.ts]
+```ts [vite.config.ts] {9}
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
 import ui from '@nuxt/ui/vite'
@@ -584,7 +584,7 @@ Use the `theme.colors` option to define the dynamic color aliases used to genera
 
 - Default: `['primary', 'secondary', 'success', 'info', 'warning', 'error']`{lang="ts-type" class="inline"}
 
-```ts [vite.config.ts]
+```ts [vite.config.ts] {9-11}
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
 import ui from '@nuxt/ui/vite'
@@ -611,7 +611,7 @@ Use the `theme.transitions` option to enable or disable transitions on component
 
 - Default: `true`{lang="ts-type"}
 
-```ts [vite.config.ts]
+```ts [vite.config.ts] {9-11}
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
 import ui from '@nuxt/ui/vite'
@@ -638,7 +638,7 @@ Use the `theme.defaultVariants` option to override the default `color` and `size
 
 - Default: `{ color: 'primary', size: 'md' }`{lang="ts-type"}
 
-```ts [vite.config.ts]
+```ts [vite.config.ts] {9-14}
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
 import ui from '@nuxt/ui/vite'
@@ -658,11 +658,55 @@ export default defineConfig({
 })
 ```
 
+### `theme.prefix` :badge{label="Soon"}
+
+Use the `theme.prefix` option to configure the same prefix you set on your Tailwind CSS import. This ensures Nuxt UI components use the correct prefixed utility classes and CSS variables.
+
+::code-group
+
+```ts [vite.config.ts] {9-11}
+import { defineConfig } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import ui from '@nuxt/ui/vite'
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    ui({
+      theme: {
+        prefix: 'tw'
+      }
+    })
+  ]
+})
+```
+
+```css [assets/main.css] {1}
+@import "tailwindcss" prefix(tw);
+@import "@nuxt/ui";
+```
+
+::
+
+This will automatically prefix all Tailwind utility classes and CSS variables in Nuxt UI component themes:
+
+```html
+<!-- Without prefix -->
+<button class="px-2 py-1 text-xs hover:bg-primary/75">Button</button>
+
+<!-- With prefix: tw -->
+<button class="tw:px-2 tw:py-1 tw:text-xs tw:hover:bg-primary/75">Button</button>
+```
+
+::note{to="https://tailwindcss.com/docs/styling-with-utility-classes#using-the-prefix-option" target="_blank"}
+Learn more about using a prefix in the Tailwind CSS documentation.
+::
+
 ### `inertia`
 
 Use the `inertia` option to enable compatibility with [Inertia.js](https://inertiajs.com/).
 
-```ts [vite.config.ts]
+```ts [vite.config.ts] {9}
 import { defineConfig } from 'vite'
 import vue from '@vitejs/plugin-vue'
 import ui from '@nuxt/ui/vite'

docs/content/docs/1.getting-started/5.theme/2.css-variables.md

@@ -126,7 +126,7 @@ Each utility class uses a CSS variable to set its color for light and dark modes
   --ui-text-toned: var(--ui-color-neutral-600);
   --ui-text: var(--ui-color-neutral-700);
   --ui-text-highlighted: var(--ui-color-neutral-900);
-  --ui-text-inverted: var(--color-white);
+  --ui-text-inverted: white;
 }
 ```
 
@@ -136,7 +136,7 @@ Each utility class uses a CSS variable to set its color for light and dark modes
   --ui-text-muted: var(--ui-color-neutral-400);
   --ui-text-toned: var(--ui-color-neutral-300);
   --ui-text: var(--ui-color-neutral-200);
-  --ui-text-highlighted: var(--color-white);
+  --ui-text-highlighted: white;
   --ui-text-inverted: var(--ui-color-neutral-900);
 }
 ```
@@ -155,7 +155,7 @@ You can customize these CSS variables in your `main.css` file:
 }
 
 .dark {
-  --ui-text: var(--color-white);
+  --ui-text: white;
 }
 ```
 ::
@@ -189,7 +189,7 @@ Each utility class uses a CSS variable to set its color for light and dark modes
 
 ```css [Light]
 :root {
-  --ui-bg: var(--color-white);
+  --ui-bg: white;
   --ui-bg-muted: var(--ui-color-neutral-50);
   --ui-bg-elevated: var(--ui-color-neutral-100);
   --ui-bg-accented: var(--ui-color-neutral-200);
@@ -203,7 +203,7 @@ Each utility class uses a CSS variable to set its color for light and dark modes
   --ui-bg-muted: var(--ui-color-neutral-800);
   --ui-bg-elevated: var(--ui-color-neutral-800);
   --ui-bg-accented: var(--ui-color-neutral-700);
-  --ui-bg-inverted: var(--color-white);
+  --ui-bg-inverted: white;
 }
 ```
 
@@ -265,7 +265,7 @@ Each utility class uses a CSS variable to set its color for light and dark modes
   --ui-border: var(--ui-color-neutral-800);
   --ui-border-muted: var(--ui-color-neutral-700);
   --ui-border-accented: var(--ui-color-neutral-700);
-  --ui-border-inverted: var(--color-white);
+  --ui-border-inverted: white;
 }
 ```
 
@@ -346,7 +346,7 @@ Nuxt UI provides a `--ui-container` CSS variable that controls the maximum width
 
 ```css
 :root {
-  --ui-container: var(--container-7xl);
+  --ui-container: 80rem; /* var(--container-7xl) */
 }
 ```
 

playgrounds/nuxt/app/components/ThemeDropdown.vue

@@ -48,13 +48,15 @@ const items = computed<DropdownMenuItem[]>(() => [{
     />
 
     <template #item-leading="{ item }">
-      <span
-        :style="{
-          '--chip-light': `var(--color-${(item as any).chip}-500)`,
-          '--chip-dark': `var(--color-${(item as any).chip}-400)`
-        }"
-        class="ms-0.5 size-2 rounded-full bg-(--chip-light) dark:bg-(--chip-dark)"
-      />
+      <div class="inline-flex items-center justify-center shrink-0 size-5">
+        <span
+          class="rounded-full ring ring-bg bg-(--chip-light) dark:bg-(--chip-dark) size-2"
+          :style="{
+            '--chip-light': `var(--color-${(item as any).chip}-500)`,
+            '--chip-dark': `var(--color-${(item as any).chip}-400)`
+          }"
+        />
+      </div>
     </template>
   </UDropdownMenu>
 </template>