refactor(module)!: implement design system with CSS variables (#2298)

2026-01-14 12:14:41 +01:00 · 2024-10-07 14:48:02 +02:00
parent 3cf5535b2f
commit 9368c6a639
279 changed files with 6533 additions and 6994 deletions
--- a/README.md
+++ b/README.md
@@ -40,11 +40,13 @@ export default defineNuxtConfig({
 })
 ```

-3. Import Tailwind and Nuxt UI in your `app.vue` or in your [CSS](https://nuxt.com/docs/getting-started/styling#the-css-property):
+3. Import Tailwind CSS and Nuxt UI in your `app.vue` or [CSS](https://nuxt.com/docs/getting-started/styling#the-css-property):

-```css [main.css]
+```vue [app.vue]
+<style>
@import "tailwindcss";
@import "@nuxt/ui";
+</style>
 ```

 ## Documentation
--- a/docs/app/app.config.ts
+++ b/docs/app/app.config.ts
@@ -7,7 +7,7 @@ export default defineAppConfig({
  ui: {
    colors: {
      primary: 'green',
-      gray: 'slate'
+      neutral: 'slate'
    }
  }
 })
--- a/docs/app/app.vue
+++ b/docs/app/app.vue
@@ -1,16 +1,17 @@
 <script setup lang="ts">
 import { withoutTrailingSlash } from 'ufo'
+import colors from 'tailwindcss/colors'
 // import { debounce } from 'perfect-debounce'
-// import type { ContentSearchFile } from '@nuxt/ui-pro'
+import type { ContentSearchFile } from '@nuxt/ui-pro'

 const route = useRoute()
 const appConfig = useAppConfig()
-// const colorMode = useColorMode()
+const colorMode = useColorMode()
 const runtimeConfig = useRuntimeConfig()
 const { integrity, api } = runtimeConfig.public.content

 const { data: navigation } = await useAsyncData('navigation', () => fetchContentNavigation(), { default: () => [] })
-const { data: files } = await useLazyFetch<any[]>(`${api.baseURL}/search${integrity ? '-' + integrity : ''}`, { default: () => [] })
+const { data: files } = await useLazyFetch<ContentSearchFile[]>(`${api.baseURL}/search${integrity ? '-' + integrity : ''}`, { default: () => [] })

 const searchTerm = ref('')

@@ -50,12 +51,12 @@ const links = computed(() => {
  }].filter(Boolean)
 })

-// const color = computed(() => colorMode.value === 'dark' ? '#18181b' : 'white')
+const color = computed(() => colorMode.value === 'dark' ? (colors as any)[appConfig.ui.colors.neutral][900] : 'white')

 useHead({
  meta: [
-    { name: 'viewport', content: 'width=device-width, initial-scale=1' }
-    // { key: 'theme-color', name: 'theme-color', content: color }
+    { name: 'viewport', content: 'width=device-width, initial-scale=1' },
+    { key: 'theme-color', name: 'theme-color', content: color }
  ],
  link: [
    { rel: 'icon', type: 'image/svg+xml', href: '/icon.svg' },
@@ -121,6 +122,6 @@ provide('navigation', navigation)
 }

 :root {
-  --container-width: 90rem;
+  --ui-container-width: 90rem;
 }
 </style>
--- a/docs/app/components/Footer.vue
+++ b/docs/app/components/Footer.vue
@@ -23,15 +23,15 @@ const route = useRoute()

  <UFooter>
    <template #left>
-      <NuxtLink v-if="route.path.startsWith('/pro')" to="https://ui.nuxt.com/pro/purchase" target="_blank" class="text-sm text-gray-500 dark:text-gray-400">
-        Purchase <span class="text-gray-900 dark:text-white">Nuxt UI Pro</span>
+      <NuxtLink v-if="route.path.startsWith('/pro')" to="https://ui.nuxt.com/pro/purchase" target="_blank" class="text-sm text-[--ui-text-muted]">
+        Purchase <span class="text-[--ui-text-highlighted]">Nuxt UI Pro</span>
      </NuxtLink>
-      <NuxtLink v-else to="https://github.com/nuxt/ui" target="_blank" class="text-sm text-gray-500 dark:text-gray-400">
-        Published under <span class="text-gray-900 dark:text-white">MIT License</span>
+      <NuxtLink v-else to="https://github.com/nuxt/ui" target="_blank" class="text-sm text-[--ui-text-muted]">
+        Published under <span class="text-[--ui-text-highlighted]">MIT License</span>
      </NuxtLink>
    </template>

-    <!-- <UNavigationMenu :items="items" variant="link" color="gray" /> -->
+    <!-- <UNavigationMenu :items="items" variant="link" color="neutral" /> -->

    <template #right>
      <UButton
@@ -39,7 +39,7 @@ const route = useRoute()
        icon="i-simple-icons-nuxtdotjs"
        to="https://nuxt.com"
        target="_blank"
-        color="gray"
+        color="neutral"
        variant="ghost"
      />
      <UButton
@@ -47,7 +47,7 @@ const route = useRoute()
        icon="i-simple-icons-discord"
        to="https://chat.nuxt.dev"
        target="_blank"
-        color="gray"
+        color="neutral"
        variant="ghost"
      />
      <UButton
@@ -55,7 +55,7 @@ const route = useRoute()
        icon="i-simple-icons-x"
        to="https://x.com/nuxt_js"
        target="_blank"
-        color="gray"
+        color="neutral"
        variant="ghost"
      />
      <UButton
@@ -63,7 +63,7 @@ const route = useRoute()
        icon="i-simple-icons-github"
        to="https://github.com/nuxt/ui"
        target="_blank"
-        color="gray"
+        color="neutral"
        variant="ghost"
      />
    </template>
--- a/docs/app/components/Header.vue
+++ b/docs/app/components/Header.vue
@@ -16,7 +16,7 @@ const navigation = inject<Ref<NavItem[]>>('navigation')
 <template>
  <UHeader :ui="{ left: 'min-w-0' }">
    <template #left>
-      <NuxtLink to="/" class="flex items-end gap-2 font-bold text-xl text-gray-900 dark:text-white min-w-0" aria-label="Nuxt UI">
+      <NuxtLink to="/" class="flex items-end gap-2 font-bold text-xl text-[--ui-text-highlighted] min-w-0" aria-label="Nuxt UI">
        <Logo class="w-auto h-6 shrink-0" />

        <UBadge :label="`v${config.version}`" variant="subtle" size="sm" class="-mb-[2px] rounded font-semibold inline-block truncate" />
@@ -35,7 +35,7 @@ const navigation = inject<Ref<NavItem[]>>('navigation')
      <ColorModeButton />

      <UButton
-        color="gray"
+        color="neutral"
        variant="ghost"
        to="https://github.com/nuxt/ui/tree/v3"
        target="_blank"
--- a/docs/app/components/Logo.vue
+++ b/docs/app/components/Logo.vue
@@ -4,8 +4,8 @@
    <path d="M726 92H739C742.314 92 745 89.3137 745 86V60H773V92H800V116H773V159C773 169.5 778.057 174 787 174H800V200H783C759.948 200 745 185.071 745 160V116H726V92Z" fill="currentColor" />
    <path d="M591 92V154C591 168.004 585.742 179.809 578 188C570.258 196.191 559.566 200 545 200C530.434 200 518.742 196.191 511 188C503.389 179.809 498 168.004 498 154V92H514C517.412 92 520.769 92.622 523 95C525.231 97.2459 526 98.5652 526 102V154C526 162.059 526.457 167.037 530 171C533.543 174.831 537.914 176 545 176C552.217 176 555.457 174.831 559 171C562.543 167.037 563 162.059 563 154V102C563 98.5652 563.769 96.378 566 94C567.96 91.9107 570.028 91.9599 573 92C573.411 92.0055 574.586 92 575 92H591Z" fill="currentColor" />
    <path d="M676 144L710 92H684C680.723 92 677.812 93.1758 676 96L660 120L645 97C643.188 94.1758 639.277 92 636 92H611L645 143L608 200H634C637.25 200 640.182 196.787 642 194L660 167L679 195C680.818 197.787 683.75 200 687 200H713L676 144Z" fill="currentColor" />
-    <path d="M168 200H279C282.542 200 285.932 198.756 289 197C292.068 195.244 295.23 193.041 297 190C298.77 186.959 300.002 183.51 300 179.999C299.998 176.488 298.773 173.04 297 170.001L222 41C220.23 37.96 218.067 35.7552 215 34C211.933 32.2448 207.542 31 204 31C200.458 31 197.067 32.2448 194 34C190.933 35.7552 188.77 37.96 187 41L168 74L130 9.99764C128.228 6.95784 126.068 3.75491 123 2C119.932 0.245087 116.542 0 113 0C109.458 0 106.068 0.245087 103 2C99.9323 3.75491 96.7717 6.95784 95 9.99764L2 170.001C0.226979 173.04 0.00154312 176.488 1.90993e-06 179.999C-0.0015393 183.51 0.229648 186.959 2 190C3.77035 193.04 6.93245 195.244 10 197C13.0675 198.756 16.4578 200 20 200H90C117.737 200 137.925 187.558 152 164L186 105L204 74L259 168H186L168 200ZM89 168H40L113 42L150 105L125.491 147.725C116.144 163.01 105.488 168 89 168Z" fill="var(--color-primary-DEFAULT)" />
-    <path d="M958 60.0001H938C933.524 60.0001 929.926 59.9395 927 63C924.074 65.8905 925 67.5792 925 72V141C925 151.372 923.648 156.899 919 162C914.352 166.931 908.468 169 899 169C889.705 169 882.648 166.931 878 162C873.352 156.899 873 151.372 873 141V72.0001C873 67.5793 872.926 65.8906 870 63.0001C867.074 59.9396 863.476 60.0001 859 60.0001H840V141C840 159.023 845.016 173.458 855 184C865.156 194.542 879.893 200 899 200C918.107 200 932.844 194.542 943 184C953.156 173.458 958 159.023 958 141V60.0001Z" fill="var(--color-primary-DEFAULT)" />
-    <path fill-rule="evenodd" clip-rule="evenodd" d="M1000 60.0233L1020 60V77L1020 128V156.007L1020 181L1020 189.004C1020 192.938 1019.98 194.429 1017 197.001C1014.02 199.725 1009.56 200 1005 200H986.001V181.006L986 130.012V70.0215C986 66.1576 986.016 64.5494 989 62.023C991.819 59.6358 995.437 60.0233 1000 60.0233Z" fill="var(--color-primary-DEFAULT)" />
+    <path d="M168 200H279C282.542 200 285.932 198.756 289 197C292.068 195.244 295.23 193.041 297 190C298.77 186.959 300.002 183.51 300 179.999C299.998 176.488 298.773 173.04 297 170.001L222 41C220.23 37.96 218.067 35.7552 215 34C211.933 32.2448 207.542 31 204 31C200.458 31 197.067 32.2448 194 34C190.933 35.7552 188.77 37.96 187 41L168 74L130 9.99764C128.228 6.95784 126.068 3.75491 123 2C119.932 0.245087 116.542 0 113 0C109.458 0 106.068 0.245087 103 2C99.9323 3.75491 96.7717 6.95784 95 9.99764L2 170.001C0.226979 173.04 0.00154312 176.488 1.90993e-06 179.999C-0.0015393 183.51 0.229648 186.959 2 190C3.77035 193.04 6.93245 195.244 10 197C13.0675 198.756 16.4578 200 20 200H90C117.737 200 137.925 187.558 152 164L186 105L204 74L259 168H186L168 200ZM89 168H40L113 42L150 105L125.491 147.725C116.144 163.01 105.488 168 89 168Z" fill="var(--ui-primary)" />
+    <path d="M958 60.0001H938C933.524 60.0001 929.926 59.9395 927 63C924.074 65.8905 925 67.5792 925 72V141C925 151.372 923.648 156.899 919 162C914.352 166.931 908.468 169 899 169C889.705 169 882.648 166.931 878 162C873.352 156.899 873 151.372 873 141V72.0001C873 67.5793 872.926 65.8906 870 63.0001C867.074 59.9396 863.476 60.0001 859 60.0001H840V141C840 159.023 845.016 173.458 855 184C865.156 194.542 879.893 200 899 200C918.107 200 932.844 194.542 943 184C953.156 173.458 958 159.023 958 141V60.0001Z" fill="var(--ui-primary)" />
+    <path fill-rule="evenodd" clip-rule="evenodd" d="M1000 60.0233L1020 60V77L1020 128V156.007L1020 181L1020 189.004C1020 192.938 1019.98 194.429 1017 197.001C1014.02 199.725 1009.56 200 1005 200H986.001V181.006L986 130.012V70.0215C986 66.1576 986.016 64.5494 989 62.023C991.819 59.6358 995.437 60.0233 1000 60.0233Z" fill="var(--ui-primary)" />
  </svg>
 </template>
--- a/docs/app/components/color-mode/ColorModeButton.vue
+++ b/docs/app/components/color-mode/ColorModeButton.vue
@@ -2,7 +2,7 @@
  <ClientOnly v-if="!colorMode?.forced">
    <UButton
      :icon="isDark ? appConfig.ui.icons.dark : appConfig.ui.icons.light"
-      color="gray"
+      color="neutral"
      variant="ghost"
      v-bind="{
        ...$attrs
--- a/docs/app/components/color-picker/ColorPicker.vue
+++ b/docs/app/components/color-picker/ColorPicker.vue
@@ -3,11 +3,11 @@
    <template #default="{ open }">
      <UButton
        icon="i-heroicons-swatch-20-solid"
-        color="gray"
+        color="neutral"
        :variant="open ? 'soft' : 'ghost'"
        square
        aria-label="Color picker"
-        :ui="{ leadingIcon: 'text-primary-500 dark:text-primary-400' }"
+        :ui="{ leadingIcon: 'text-[--ui-primary]' }"
      />
    </template>

@@ -24,21 +24,36 @@

      <fieldset class="grid grid-cols-5 gap-px">
        <legend class="text-[11px] font-bold mb-1">
-          Gray
+          Neutral
        </legend>

-        <ColorPickerPill v-for="color in grayColors" :key="color" :color="color" :selected="gray" @select="gray = color" />
+        <ColorPickerPill v-for="color in neutralColors" :key="color" :color="color" :selected="neutral" @select="neutral = color" />
      </fieldset>
    </template>
  </UPopover>
 </template>

 <script setup lang="ts">
+import colors from 'tailwindcss/colors'
+import { omit } from '#ui/utils'
+
 const appConfig = useAppConfig()

 // Computed

-const primaryColors = ['red', 'orange', 'amber', 'yellow', 'lime', 'green', 'emerald', 'teal', 'cyan', 'sky', 'blue', 'indigo', 'violet', 'purple', 'fuchsia', 'pink', 'rose']
+const neutralColors = ['slate', 'gray', 'zinc', 'neutral', 'stone']
+const neutral = computed({
+  get() {
+    return appConfig.ui.colors.neutral
+  },
+  set(option) {
+    appConfig.ui.colors.neutral = option
+    window.localStorage.setItem('nuxt-ui-neutral', appConfig.ui.colors.neutral)
+  }
+})
+
+const colorsToOmit = ['inherit', 'current', 'transparent', 'black', 'white', ...neutralColors]
+const primaryColors = Object.keys(omit(colors, colorsToOmit as any))
 const primary = computed({
  get() {
    return appConfig.ui.colors.primary
@@ -48,15 +63,4 @@ const primary = computed({
    window.localStorage.setItem('nuxt-ui-primary', appConfig.ui.colors.primary)
  }
 })
-
-const grayColors = ['slate', 'cool', 'zinc', 'neutral', 'stone']
-const gray = computed({
-  get() {
-    return appConfig.ui.colors.gray
-  },
-  set(option) {
-    appConfig.ui.colors.gray = option
-    window.localStorage.setItem('nuxt-ui-gray', appConfig.ui.colors.gray)
-  }
-})
 </script>
--- a/docs/app/components/color-picker/ColorPickerPill.vue
+++ b/docs/app/components/color-picker/ColorPickerPill.vue
@@ -1,7 +1,7 @@
 <template>
  <UTooltip :text="color" class="capitalize" :portal="false">
    <UButton
-      color="gray"
+      color="neutral"
      square
      :variant="color === selected ? 'soft' : 'ghost'"
      @click.stop.prevent="$emit('select')"
--- a/docs/app/components/content/ComponentCode.vue
+++ b/docs/app/components/content/ComponentCode.vue
@@ -86,7 +86,7 @@ const options = computed(() => {
          value: variant,
          label: variant,
          chip: key.toLowerCase().endsWith('color') ? { color: variant } : undefined
-        })).filter(variant => key.toLowerCase().endsWith('color') ? !['error'].includes(variant.value) : true)
+        }))

    return {
      name: key,
@@ -214,15 +214,15 @@ const { data: ast } = await useAsyncData(`component-code-${name}-${hash({ props:
 <template>
  <div class="my-5">
    <div>
-      <div v-if="options.length" class="flex items-center gap-2.5 border border-gray-200 dark:border-gray-700 border-b-0 relative rounded-t-md px-4 py-2.5 overflow-x-auto">
+      <div v-if="options.length" class="flex items-center gap-2.5 border border-[--ui-color-neutral-200] dark:border-[--ui-color-neutral-700] border-b-0 relative rounded-t-md px-4 py-2.5 overflow-x-auto">
        <template v-for="option in options" :key="option.name">
          <UFormField
            :label="option.label"
            size="sm"
-            class="inline-flex ring ring-gray-300 dark:ring-gray-700 rounded"
+            class="inline-flex ring ring-[--ui-border-accented] rounded"
            :ui="{
-              wrapper: 'bg-gray-50 dark:bg-gray-800/50 rounded-l flex border-r border-gray-300 dark:border-gray-700',
-              label: 'text-gray-500 dark:text-gray-400 px-2 py-1.5',
+              wrapper: 'bg-[--ui-bg-elevated]/50 rounded-l flex border-r border-[--ui-border-accented]',
+              label: 'text-[--ui-text-muted] px-2 py-1.5',
              container: 'mt-0'
            }"
          >
@@ -231,7 +231,7 @@ const { data: ast } = await useAsyncData(`component-code-${name}-${hash({ props:
              :model-value="getComponentProp(option.name)"
              :items="option.items"
              value-key="value"
-              color="gray"
+              color="neutral"
              variant="soft"
              class="rounded rounded-l-none min-w-12"
              :search-input="false"
@@ -254,7 +254,7 @@ const { data: ast } = await useAsyncData(`component-code-${name}-${hash({ props:
              v-else
              :type="option.type?.includes('number') ? 'number' : 'text'"
              :model-value="getComponentProp(option.name)"
-              color="gray"
+              color="neutral"
              variant="soft"
              :ui="{ base: 'rounded rounded-l-none min-w-12' }"
              @update:model-value="setComponentProp(option.name, $event)"
@@ -263,7 +263,7 @@ const { data: ast } = await useAsyncData(`component-code-${name}-${hash({ props:
        </template>
      </div>

-      <div class="flex justify-center border border-b-0 border-gray-200 dark:border-gray-700 relative p-4 z-[1]" :class="[!options.length && 'rounded-t-md', props.class]">
+      <div class="flex justify-center border border-b-0 border-[--ui-color-neutral-200] dark:border-[--ui-color-neutral-700] relative p-4 z-[1]" :class="[!options.length && 'rounded-t-md', props.class]">
        <component :is="name" v-bind="{ ...componentProps, ...componentEvents }">
          <template v-for="slot in Object.keys(slots || {})" :key="slot" #[slot]>
            <ContentSlot :name="slot" unwrap="p">
--- a/docs/app/components/content/ComponentExample.vue
+++ b/docs/app/components/content/ComponentExample.vue
@@ -114,8 +114,8 @@ const optionsValues = ref(props.options?.reduce((acc, option) => {
 <template>
  <div class="my-5">
    <div v-if="preview">
-      <div class="border border-gray-200 dark:border-gray-700 relative z-[1]" :class="[{ 'border-b-0 rounded-t-md': props.source, 'rounded-md': !props.source }]">
-        <div v-if="props.options?.length || !!slots.options" class="flex gap-4 p-4 border-b border-gray-200 dark:border-gray-700">
+      <div class="border border-[--ui-color-neutral-200] dark:border-[--ui-color-neutral-700] relative z-[1]" :class="[{ 'border-b-0 rounded-t-md': props.source, 'rounded-md': !props.source }]">
+        <div v-if="props.options?.length || !!slots.options" class="flex gap-4 p-4 border-b border-[--ui-color-neutral-200] dark:border-[--ui-color-neutral-700]">
          <slot name="options" />

          <UFormField
@@ -124,10 +124,10 @@ const optionsValues = ref(props.options?.reduce((acc, option) => {
            :label="option.label"
            :name="option.name"
            size="sm"
-            class="inline-flex ring ring-gray-300 dark:ring-gray-700 rounded"
+            class="inline-flex ring ring-[--ui-border-accented] rounded"
            :ui="{
-              wrapper: 'bg-gray-50 dark:bg-gray-800/50 rounded-l flex border-r border-gray-300 dark:border-gray-700',
-              label: 'text-gray-500 dark:text-gray-400 px-2 py-1.5',
+              wrapper: 'bg-[--ui-bg-elevated]/50 rounded-l flex border-r border-[--ui-border-accented]',
+              label: 'text-[--ui-text-muted] px-2 py-1.5',
              container: 'mt-0'
            }"
          >
@@ -137,7 +137,7 @@ const optionsValues = ref(props.options?.reduce((acc, option) => {
              :items="option.items"
              :search-input="false"
              :value-key="option.name.toLowerCase().endsWith('color') ? 'value' : undefined"
-              color="gray"
+              color="neutral"
              variant="soft"
              class="rounded rounded-l-none min-w-12"
              :multiple="option.multiple"
@@ -158,7 +158,7 @@ const optionsValues = ref(props.options?.reduce((acc, option) => {
            <UInput
              v-else
              :model-value="get(optionsValues, option.name)"
-              color="gray"
+              color="neutral"
              variant="soft"
              :ui="{ base: 'rounded rounded-l-none min-w-12' }"
              @update:model-value="set(optionsValues, option.name, $event)"
--- a/docs/app/components/content/ComponentProps.vue
+++ b/docs/app/components/content/ComponentProps.vue
@@ -77,7 +77,7 @@ const metaProps: ComputedRef<ComponentMeta['props']> = computed(() => {
        <ProseTd>
          <HighlightInlineType v-if="prop.type" :type="prop.type" />

-          <MDC v-if="prop.description" :value="prop.description" class="text-gray-600 dark:text-gray-300 mt-1" />
+          <MDC v-if="prop.description" :value="prop.description" class="text-[--ui-text-toned] mt-1" />

          <ComponentPropsSchema v-if="prop.schema" :prop="prop" :ignore="ignore" />
        </ProseTd>
--- a/docs/app/components/content/ComponentPropsSchema.vue
+++ b/docs/app/components/content/ComponentPropsSchema.vue
@@ -40,7 +40,7 @@ const schemaProps = computed(() => {
      <ProseLi v-for="schemaProp in schemaProps" :key="schemaProp.name">
        <HighlightInlineType :type="`${schemaProp.name}${schemaProp.required === false ? '?' : ''}: ${schemaProp.type}`" />

-        <MDC v-if="schemaProp.description" :value="schemaProp.description" class="text-gray-500 dark:text-gray-400 my-1" />
+        <MDC v-if="schemaProp.description" :value="schemaProp.description" class="text-[--ui-text-muted] my-1" />
      </ProseLi>
    </ProseUl>
  </Collapsible>
--- a/docs/app/components/content/ComponentSlots.vue
+++ b/docs/app/components/content/ComponentSlots.vue
@@ -31,7 +31,7 @@ const meta = await fetchComponentMeta(name as any)
        <ProseTd>
          <HighlightInlineType v-if="slot.type" :type="slot.type" />

-          <MDC v-if="slot.description" :value="slot.description" class="text-gray-600 dark:text-gray-300 mt-1" />
+          <MDC v-if="slot.description" :value="slot.description" class="text-[--ui-text-toned] mt-1" />
        </ProseTd>
      </ProseTr>
    </ProseTbody>
--- a/docs/app/components/content/ComponentTheme.vue
+++ b/docs/app/components/content/ComponentTheme.vue
@@ -13,7 +13,7 @@ function stripCompoundVariants(component?: any) {
  if (component?.compoundVariants) {
    component.compoundVariants = component.compoundVariants.filter((compoundVariant: any) => {
      if (compoundVariant.color) {
-        if (!['primary', 'gray'].includes(compoundVariant.color)) {
+        if (!['primary', 'neutral'].includes(compoundVariant.color)) {
          strippedCompoundVariants.value = true

          return false
@@ -21,7 +21,7 @@ function stripCompoundVariants(component?: any) {
      }

      if (compoundVariant.highlightColor) {
-        if (!['primary', 'gray'].includes(compoundVariant.highlightColor)) {
+        if (!['primary', 'neutral'].includes(compoundVariant.highlightColor)) {
          strippedCompoundVariants.value = true

          return false
--- a/docs/app/components/content/Placeholder.vue
+++ b/docs/app/components/content/Placeholder.vue
@@ -1,6 +1,6 @@
 <template>
-  <div class="relative overflow-hidden rounded border border-dashed border-gray-400 dark:border-gray-500 opacity-75 px-4 flex items-center justify-center">
-    <svg class="absolute inset-0 h-full w-full stroke-gray-900/10 dark:stroke-white/10" fill="none">
+  <div class="relative overflow-hidden rounded border border-dashed border-[--ui-border-accented] opacity-75 px-4 flex items-center justify-center">
+    <svg class="absolute inset-0 h-full w-full stroke-[--ui-border-inverted]/10" fill="none">
      <defs>
        <pattern
          id="pattern-5c1e4f0e-62d5-498b-8ff0-cf77bb448c8e"
--- a/docs/app/components/content/examples/accordion/AccordionContentSlotExample.vue
+++ b/docs/app/components/content/examples/accordion/AccordionContentSlotExample.vue
@@ -18,7 +18,7 @@ const items = [
 <template>
  <UAccordion :items="items">
    <template #content="{ item }">
-      <p class="pb-3.5 text-sm text-gray-500 dark:text-gray-400">
+      <p class="pb-3.5 text-sm text-[--ui-text-muted]">
        This is the {{ item.label }} panel.
      </p>
    </template>
--- a/docs/app/components/content/examples/accordion/AccordionCustomSlotExample.vue
+++ b/docs/app/components/content/examples/accordion/AccordionCustomSlotExample.vue
@@ -9,7 +9,7 @@ const items = [
    label: 'Colors',
    icon: 'i-heroicons-swatch',
    slot: 'colors',
-    content: 'Choose a primary and a gray color from your Tailwind CSS theme.'
+    content: 'Choose a primary and a neutral color from your Tailwind CSS theme.'
  },
  {
    label: 'Components',
@@ -22,7 +22,7 @@ const items = [
 <template>
  <UAccordion :items="items">
    <template #colors="{ item }">
-      <p class="text-sm pb-3.5 text-primary-500 dark:text-primary-400">
+      <p class="text-sm pb-3.5 text-[--ui-primary]">
        {{ item.content }}
      </p>
    </template>
--- a/docs/app/components/content/examples/accordion/AccordionModelValueExample.vue
+++ b/docs/app/components/content/examples/accordion/AccordionModelValueExample.vue
@@ -8,7 +8,7 @@ const items = [
  {
    label: 'Colors',
    icon: 'i-heroicons-swatch',
-    content: 'Choose a primary and a gray color from your Tailwind CSS theme.'
+    content: 'Choose a primary and a neutral color from your Tailwind CSS theme.'
  },
  {
    label: 'Components',
--- a/docs/app/components/content/examples/avatar-group/AvatarGroupChipExample.vue
+++ b/docs/app/components/content/examples/avatar-group/AvatarGroupChipExample.vue
@@ -1,20 +1,20 @@
 <template>
  <UAvatarGroup>
-    <UChip inset color="green">
+    <UChip inset color="success">
      <UAvatar
        src="https://avatars.githubusercontent.com/u/739984?v=4"
        alt="Benjamin Canac"
      />
    </UChip>

-    <UChip inset color="amber">
+    <UChip inset color="warning">
      <UAvatar
        src="https://avatars.githubusercontent.com/u/25613751?v=4"
        alt="Romain Hamel"
      />
    </UChip>

-    <UChip inset color="red">
+    <UChip inset color="error">
      <UAvatar
        src="https://avatars.githubusercontent.com/u/19751938?v=4"
        alt="Neil Richter"
--- a/docs/app/components/content/examples/avatar-group/AvatarGroupLinkExample.vue
+++ b/docs/app/components/content/examples/avatar-group/AvatarGroupLinkExample.vue
@@ -3,7 +3,7 @@
    <ULink
      to="https://github.com/benjamincanac"
      target="_blank"
-      class="hover:ring-primary-500 dark:hover:ring-primary-400 transition"
+      class="hover:ring-[--ui-primary] transition"
      raw
    >
      <UAvatar
@@ -15,7 +15,7 @@
    <ULink
      to="https://github.com/romhml"
      target="_blank"
-      class="hover:ring-primary-500 dark:hover:ring-primary-400 transition"
+      class="hover:ring-[--ui-primary] transition"
      raw
    >
      <UAvatar
@@ -27,7 +27,7 @@
    <ULink
      to="https://github.com/noook"
      target="_blank"
-      class="hover:ring-primary-500 dark:hover:ring-primary-400 transition"
+      class="hover:ring-[--ui-primary] transition"
      raw
    >
      <UAvatar
--- a/docs/app/components/content/examples/breadcrumb/BreadcrumbCustomSlotExample.vue
+++ b/docs/app/components/content/examples/breadcrumb/BreadcrumbCustomSlotExample.vue
@@ -25,7 +25,7 @@ const items = [{
  <UBreadcrumb :items="items">
    <template #dropdown="{ item }">
      <UDropdownMenu :items="item.children">
-        <UButton :icon="item.icon" color="gray" variant="link" class="p-0.5" />
+        <UButton :icon="item.icon" color="neutral" variant="link" class="p-0.5" />
      </UDropdownMenu>
    </template>
  </UBreadcrumb>
--- a/docs/app/components/content/examples/breadcrumb/BreadcrumbSeparatorSlotExample.vue
+++ b/docs/app/components/content/examples/breadcrumb/BreadcrumbSeparatorSlotExample.vue
@@ -14,7 +14,7 @@ const items = [{
 <template>
  <UBreadcrumb :items="items">
    <template #separator>
-      <span class="mx-2 text-gray-500 dark:text-gray-400">/</span>
+      <span class="mx-2 text-[--ui-text-muted]">/</span>
    </template>
  </UBreadcrumb>
 </template>
--- a/docs/app/components/content/examples/button-group/ButtonGroupDropdownExample.vue
+++ b/docs/app/components/content/examples/button-group/ButtonGroupDropdownExample.vue
@@ -20,11 +20,11 @@ const items = [{

 <template>
  <UButtonGroup>
-    <UButton color="gray" variant="subtle" label="Settings" />
+    <UButton color="neutral" variant="subtle" label="Settings" />

    <UDropdownMenu :items="items">
      <UButton
-        color="gray"
+        color="neutral"
        variant="outline"
        icon="i-heroicons-chevron-down-20-solid"
      />
--- a/docs/app/components/content/examples/button-group/ButtonGroupTooltipExample.vue
+++ b/docs/app/components/content/examples/button-group/ButtonGroupTooltipExample.vue
@@ -1,10 +1,10 @@
 <template>
  <UButtonGroup>
-    <UInput color="gray" variant="outline" placeholder="Enter token" />
+    <UInput color="neutral" variant="outline" placeholder="Enter token" />

    <UTooltip text="Copy to clipboard">
      <UButton
-        color="gray"
+        color="neutral"
        variant="subtle"
        icon="i-heroicons-clipboard-document"
      />
--- a/docs/app/components/content/examples/chip/ChipShowExample.vue
+++ b/docs/app/components/content/examples/chip/ChipShowExample.vue
@@ -2,7 +2,7 @@
 const statuses = ['online', 'away', 'busy', 'offline']
 const status = ref(statuses[0])

-const color = computed(() => status.value ? { online: 'green', away: 'amber', busy: 'red', offline: 'gray' }[status.value] as any : 'online')
+const color = computed(() => status.value ? { online: 'success', away: 'warning', busy: 'error', offline: 'neutral' }[status.value] as any : 'online')

 const show = computed(() => status.value !== 'offline')

--- a/docs/app/components/content/examples/collapsible/CollapsibleIconExample.vue
+++ b/docs/app/components/content/examples/collapsible/CollapsibleIconExample.vue
@@ -3,7 +3,7 @@
    <UButton
      class="group"
      label="Open"
-      color="gray"
+      color="neutral"
      variant="subtle"
      trailing-icon="i-heroicons-chevron-down-20-solid"
      :ui="{
--- a/docs/app/components/content/examples/collapsible/CollapsibleOpenExample.vue
+++ b/docs/app/components/content/examples/collapsible/CollapsibleOpenExample.vue
@@ -10,7 +10,7 @@ defineShortcuts({
  <UCollapsible v-model:open="open" class="w-48">
    <UButton
      label="Open"
-      color="gray"
+      color="neutral"
      variant="subtle"
      trailing-icon="i-heroicons-chevron-down-20-solid"
      block
--- a/docs/app/components/content/examples/command-palette/CommandPaletteOpenExample.vue
+++ b/docs/app/components/content/examples/command-palette/CommandPaletteOpenExample.vue
@@ -14,7 +14,7 @@ const users = [
  <UModal v-model:open="open">
    <UButton
      label="Search users..."
-      color="gray"
+      color="neutral"
      variant="subtle"
      icon="i-heroicons-magnifying-glass"
    />
--- a/docs/app/components/content/examples/context-menu/ContextMenuCustomSlotExample.vue
+++ b/docs/app/components/content/examples/context-menu/ContextMenuCustomSlotExample.vue
@@ -13,7 +13,7 @@ const items = [{

 <template>
  <UContextMenu :items="items" class="w-48">
-    <div class="flex items-center justify-center rounded-md border border-dashed border-gray-300 dark:border-gray-700 text-sm aspect-video w-72">
+    <div class="flex items-center justify-center rounded-md border border-dashed border-[--ui-border-accented] text-sm aspect-video w-72">
      Right click here
    </div>

@@ -22,7 +22,7 @@ const items = [{
    </template>

    <template #refresh-trailing>
-      <UIcon v-if="loading" name="i-heroicons-arrow-path-20-solid" class="shrink-0 size-5 text-primary-500 dark:text-primary-400 animate-spin" />
+      <UIcon v-if="loading" name="i-heroicons-arrow-path-20-solid" class="shrink-0 size-5 text-[--ui-primary] animate-spin" />
    </template>
  </UContextMenu>
 </template>
--- a/docs/app/components/content/examples/drawer/DrawerCommandPaletteExample.vue
+++ b/docs/app/components/content/examples/drawer/DrawerCommandPaletteExample.vue
@@ -21,7 +21,7 @@ const groups = computed(() => [{
  <UDrawer>
    <UButton
      label="Search users..."
-      color="gray"
+      color="neutral"
      variant="subtle"
      icon="i-heroicons-magnifying-glass"
    />
@@ -32,7 +32,7 @@ const groups = computed(() => [{
        :loading="status === 'pending'"
        :groups="groups"
        placeholder="Search users..."
-        class="h-96 border-t border-gray-200 dark:border-gray-800"
+        class="h-96 border-t border-[--ui-border]"
      />
    </template>
  </UDrawer>
--- a/docs/app/components/content/examples/drawer/DrawerFooterSlotExample.vue
+++ b/docs/app/components/content/examples/drawer/DrawerFooterSlotExample.vue
@@ -4,15 +4,15 @@ const open = ref(false)

 <template>
  <UDrawer v-model:open="open" title="Drawer with footer" description="This is useful when you want a form in a Drawer." :ui="{ container: 'max-w-xl mx-auto' }">
-    <UButton label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />
+    <UButton label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />

    <template #body>
      <Placeholder class="h-48" />
    </template>

    <template #footer>
-      <UButton label="Submit" color="gray" class="justify-center" />
-      <UButton label="Cancel" color="gray" variant="outline" class="justify-center" @click="open = false" />
+      <UButton label="Submit" color="neutral" class="justify-center" />
+      <UButton label="Cancel" color="neutral" variant="outline" class="justify-center" @click="open = false" />
    </template>
  </UDrawer>
 </template>
--- a/docs/app/components/content/examples/drawer/DrawerOpenExample.vue
+++ b/docs/app/components/content/examples/drawer/DrawerOpenExample.vue
@@ -8,7 +8,7 @@ defineShortcuts({

 <template>
  <UDrawer v-model:open="open">
-    <UButton label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />
+    <UButton label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />

    <template #content>
      <Placeholder class="h-48 m-4" />
--- a/docs/app/components/content/examples/dropdown-menu/DropdownMenuCustomSlotExample.vue
+++ b/docs/app/components/content/examples/dropdown-menu/DropdownMenuCustomSlotExample.vue
@@ -14,10 +14,10 @@ const items = [{

 <template>
  <UDropdownMenu :items="items" class="w-48">
-    <UButton label="Open" color="gray" variant="outline" icon="i-heroicons-bars-3" />
+    <UButton label="Open" color="neutral" variant="outline" icon="i-heroicons-bars-3" />

    <template #profile-trailing>
-      <UIcon name="i-heroicons-check-badge" class="shrink-0 size-5 text-primary-500 dark:text-primary-400" />
+      <UIcon name="i-heroicons-check-badge" class="shrink-0 size-5 text-[--ui-primary]" />
    </template>
  </UDropdownMenu>
 </template>
--- a/docs/app/components/content/examples/dropdown-menu/DropdownMenuOpenExample.vue
+++ b/docs/app/components/content/examples/dropdown-menu/DropdownMenuOpenExample.vue
@@ -19,6 +19,6 @@ const items = [{

 <template>
  <UDropdownMenu v-model:open="open" :items="items" class="w-48">
-    <UButton label="Open" color="gray" variant="outline" icon="i-heroicons-bars-3" />
+    <UButton label="Open" color="neutral" variant="outline" icon="i-heroicons-bars-3" />
  </UDropdownMenu>
 </template>
--- a/docs/app/components/content/examples/form/FormExampleBasic.vue
+++ b/docs/app/components/content/examples/form/FormExampleBasic.vue
@@ -15,7 +15,7 @@ const validate = (state: any): FormError[] => {

 const toast = useToast()
 async function onSubmit(event: FormSubmitEvent<any>) {
-  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'green' })
+  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'success' })
  console.log(event.data)
 }
 </script>
--- a/docs/app/components/content/examples/form/FormExampleElements.vue
+++ b/docs/app/components/content/examples/form/FormExampleElements.vue
@@ -45,7 +45,7 @@ const items = [

 const toast = useToast()
 async function onSubmit(event: FormSubmitEvent<any>) {
-  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'green' })
+  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'success' })
  console.log(event.data)
 }
 </script>
@@ -103,11 +103,11 @@ async function onSubmit(event: FormSubmitEvent<any>) {
    </div>

    <div class="flex gap-2 mt-8">
-      <UButton color="gray" type="submit">
+      <UButton color="neutral" type="submit">
        Submit
      </UButton>

-      <UButton color="gray" variant="outline" @click="form?.clear()">
+      <UButton color="neutral" variant="outline" @click="form?.clear()">
        Clear
      </UButton>
    </div>
--- a/docs/app/components/content/examples/form/FormExampleJoi.vue
+++ b/docs/app/components/content/examples/form/FormExampleJoi.vue
@@ -16,7 +16,7 @@ const state = reactive({

 const toast = useToast()
 async function onSubmit(event: FormSubmitEvent<any>) {
-  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'green' })
+  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'success' })
  console.log(event.data)
 }
 </script>
--- a/docs/app/components/content/examples/form/FormExampleNested.vue
+++ b/docs/app/components/content/examples/form/FormExampleNested.vue
@@ -19,7 +19,7 @@ const state = reactive<Partial<Schema & NestedSchema>>({ })

 const toast = useToast()
 async function onSubmit(event: FormSubmitEvent<any>) {
-  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'green' })
+  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'success' })
  console.log(event.data)
 }
 </script>
--- a/docs/app/components/content/examples/form/FormExampleNestedList.vue
+++ b/docs/app/components/content/examples/form/FormExampleNestedList.vue
@@ -35,7 +35,7 @@ const formItemRef = ref()

 const toast = useToast()
 async function onSubmit(event: FormSubmitEvent<any>) {
-  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'green' })
+  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'success' })
  console.log(event.data)
 }
 </script>
@@ -62,11 +62,11 @@ async function onSubmit(event: FormSubmitEvent<any>) {
    </UForm>

    <div class="flex gap-2">
-      <UButton color="gray" variant="subtle" size="sm" @click="addItem()">
+      <UButton color="neutral" variant="subtle" size="sm" @click="addItem()">
        Add Item
      </UButton>

-      <UButton color="gray" variant="ghost" size="sm" @click="removeItem()">
+      <UButton color="neutral" variant="ghost" size="sm" @click="removeItem()">
        Remove Item
      </UButton>
    </div>
--- a/docs/app/components/content/examples/form/FormExampleOnError.vue
+++ b/docs/app/components/content/examples/form/FormExampleOnError.vue
@@ -15,7 +15,7 @@ const validate = (state: any): FormError[] => {

 const toast = useToast()
 async function onSubmit(event: FormSubmitEvent<any>) {
-  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'green' })
+  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'success' })
  console.log(event.data)
 }

--- a/docs/app/components/content/examples/form/FormExampleValibot.vue
+++ b/docs/app/components/content/examples/form/FormExampleValibot.vue
@@ -16,7 +16,7 @@ const state = reactive({

 const toast = useToast()
 async function onSubmit(event: FormSubmitEvent<Schema>) {
-  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'green' })
+  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'success' })
  console.log(event.data)
 }
 </script>
--- a/docs/app/components/content/examples/form/FormExampleYup.vue
+++ b/docs/app/components/content/examples/form/FormExampleYup.vue
@@ -18,7 +18,7 @@ const state = reactive({

 const toast = useToast()
 async function onSubmit(event: FormSubmitEvent<Schema>) {
-  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'green' })
+  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'success' })
  console.log(event.data)
 }
 </script>
--- a/docs/app/components/content/examples/form/FormExampleZod.vue
+++ b/docs/app/components/content/examples/form/FormExampleZod.vue
@@ -16,7 +16,7 @@ const state = reactive<Partial<Schema>>({

 const toast = useToast()
 async function onSubmit(event: FormSubmitEvent<Schema>) {
-  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'green' })
+  toast.add({ title: 'Success', description: 'The form has been submitted.', color: 'success' })
  console.log(event.data)
 }
 </script>
--- a/docs/app/components/content/examples/input-menu/InputMenuFilterFieldsExample.vue
+++ b/docs/app/components/content/examples/input-menu/InputMenuFilterFieldsExample.vue
@@ -33,7 +33,7 @@ const { data: users, status } = await useFetch('https://jsonplaceholder.typicode
    <template #item-label="{ item }">
      {{ item.label }}

-      <span class="text-gray-500 dark:text-gray-400">
+      <span class="text-[--ui-text-muted]">
        {{ item.email }}
      </span>
    </template>
--- a/docs/app/components/content/examples/input-menu/InputMenuItemsChipExample.vue
+++ b/docs/app/components/content/examples/input-menu/InputMenuItemsChipExample.vue
@@ -4,21 +4,21 @@ const items = ref([
    label: 'bug',
    value: 'bug',
    chip: {
-      color: 'red' as const
-    }
-  },
-  {
-    label: 'enhancement',
-    value: 'enhancement',
-    chip: {
-      color: 'blue' as const
+      color: 'error' as const
    }
  },
  {
    label: 'feature',
    value: 'feature',
    chip: {
-      color: 'violet' as const
+      color: 'success' as const
+    }
+  },
+  {
+    label: 'enhancement',
+    value: 'enhancement',
+    chip: {
+      color: 'info' as const
    }
  }
 ])
--- a/docs/app/components/content/examples/modal/ModalCommandPaletteExample.vue
+++ b/docs/app/components/content/examples/modal/ModalCommandPaletteExample.vue
@@ -21,7 +21,7 @@ const groups = computed(() => [{
  <UModal>
    <UButton
      label="Search users..."
-      color="gray"
+      color="neutral"
      variant="subtle"
      icon="i-heroicons-magnifying-glass"
    />
--- a/docs/app/components/content/examples/modal/ModalExample.vue
+++ b/docs/app/components/content/examples/modal/ModalExample.vue
@@ -9,7 +9,7 @@ defineProps<{
 <template>
  <UModal :title="`This modal was opened programmatically ${count} times`">
    <template #footer>
-      <UButton color="gray" label="Close" @click="modal.close()" />
+      <UButton color="neutral" label="Close" @click="modal.close()" />
    </template>
  </UModal>
 </template>
--- a/docs/app/components/content/examples/modal/ModalFooterSlotExample.vue
+++ b/docs/app/components/content/examples/modal/ModalFooterSlotExample.vue
@@ -4,15 +4,15 @@ const open = ref(false)

 <template>
  <UModal v-model:open="open" title="Modal with footer" description="This is useful when you want a form in a Modal." :ui="{ footer: 'justify-end' }">
-    <UButton label="Open" color="gray" variant="subtle" />
+    <UButton label="Open" color="neutral" variant="subtle" />

    <template #body>
      <Placeholder class="h-48" />
    </template>

    <template #footer>
-      <UButton label="Cancel" color="gray" variant="outline" @click="open = false" />
-      <UButton label="Submit" color="gray" />
+      <UButton label="Cancel" color="neutral" variant="outline" @click="open = false" />
+      <UButton label="Submit" color="neutral" />
    </template>
  </UModal>
 </template>
--- a/docs/app/components/content/examples/modal/ModalNestedExample.vue
+++ b/docs/app/components/content/examples/modal/ModalNestedExample.vue
@@ -5,16 +5,16 @@ const second = ref(false)

 <template>
  <UModal v-model:open="first" title="First modal" :ui="{ footer: 'justify-end' }">
-    <UButton color="gray" variant="subtle" label="Open" />
+    <UButton color="neutral" variant="subtle" label="Open" />

    <template #footer>
-      <UButton label="Close" color="gray" variant="outline" @click="first = false" />
+      <UButton label="Close" color="neutral" variant="outline" @click="first = false" />

      <UModal v-model:open="second" title="Second modal" :ui="{ footer: 'justify-end' }">
-        <UButton label="Open second" color="gray" />
+        <UButton label="Open second" color="neutral" />

        <template #footer>
-          <UButton label="Close" color="gray" variant="outline" @click="second = false" />
+          <UButton label="Close" color="neutral" variant="outline" @click="second = false" />
        </template>
      </UModal>
    </template>
--- a/docs/app/components/content/examples/modal/ModalOpenExample.vue
+++ b/docs/app/components/content/examples/modal/ModalOpenExample.vue
@@ -8,7 +8,7 @@ defineShortcuts({

 <template>
  <UModal v-model:open="open">
-    <UButton label="Open" color="gray" variant="subtle" />
+    <UButton label="Open" color="neutral" variant="subtle" />

    <template #content>
      <Placeholder class="h-48 m-4" />
--- a/docs/app/components/content/examples/modal/ModalProgrammaticExample.vue
+++ b/docs/app/components/content/examples/modal/ModalProgrammaticExample.vue
@@ -16,5 +16,5 @@ function open() {
 </script>

 <template>
-  <UButton label="Open" color="gray" variant="subtle" @click="open" />
+  <UButton label="Open" color="neutral" variant="subtle" @click="open" />
 </template>
--- a/docs/app/components/content/examples/navigation-menu/NavigationMenuModelValueExample.vue
+++ b/docs/app/components/content/examples/navigation-menu/NavigationMenuModelValueExample.vue
@@ -22,7 +22,7 @@ const items = [
      {
        label: 'Colors',
        icon: 'i-heroicons-swatch',
-        description: 'Choose a primary and a gray color from your Tailwind CSS theme.'
+        description: 'Choose a primary and a neutral color from your Tailwind CSS theme.'
      },
      {
        label: 'Theme',
--- a/docs/app/components/content/examples/popover/PopoverCommandPaletteExample.vue
+++ b/docs/app/components/content/examples/popover/PopoverCommandPaletteExample.vue
@@ -1,20 +1,27 @@
 <script setup lang="ts">
-const labels = [{
+const items = ref([
+  {
    label: 'bug',
+    value: 'bug',
    chip: {
-    color: 'red' as const
+      color: 'error' as const
    }
-}, {
+  },
+  {
    label: 'feature',
+    value: 'feature',
    chip: {
-    color: 'green' as const
+      color: 'success' as const
    }
-}, {
+  },
+  {
    label: 'enhancement',
+    value: 'enhancement',
    chip: {
-    color: 'blue' as const
+      color: 'info' as const
    }
-}]
+  }
+])
 const label = ref([])
 </script>

@@ -23,7 +30,7 @@ const label = ref([])
    <UButton
      icon="i-heroicons-tag"
      label="Select labels"
-      color="gray"
+      color="neutral"
      variant="subtle"
    />

@@ -32,7 +39,7 @@ const label = ref([])
        v-model="label"
        multiple
        placeholder="Search labels..."
-        :groups="[{ id: 'labels', items: labels }]"
+        :groups="[{ id: 'labels', items }]"
        :ui="{ input: '[&>input]:h-8' }"
      />
    </template>
--- a/docs/app/components/content/examples/popover/PopoverOpenExample.vue
+++ b/docs/app/components/content/examples/popover/PopoverOpenExample.vue
@@ -8,7 +8,7 @@ defineShortcuts({

 <template>
  <UPopover v-model:open="open">
-    <UButton label="Open" color="gray" variant="subtle" />
+    <UButton label="Open" color="neutral" variant="subtle" />

    <template #content>
      <Placeholder class="size-48 m-4 inline-flex" />
--- a/docs/app/components/content/examples/select-menu/SelectMenuFilterFieldsExample.vue
+++ b/docs/app/components/content/examples/select-menu/SelectMenuFilterFieldsExample.vue
@@ -33,7 +33,7 @@ const { data: users, status } = await useFetch('https://jsonplaceholder.typicode
    <template #item-label="{ item }">
      {{ item.label }}

-      <span class="text-gray-500 dark:text-gray-400">
+      <span class="text-[--ui-text-muted]">
        {{ item.email }}
      </span>
    </template>
--- a/docs/app/components/content/examples/select-menu/SelectMenuItemsChipExample.vue
+++ b/docs/app/components/content/examples/select-menu/SelectMenuItemsChipExample.vue
@@ -4,21 +4,21 @@ const items = ref([
    label: 'bug',
    value: 'bug',
    chip: {
-      color: 'red' as const
-    }
-  },
-  {
-    label: 'enhancement',
-    value: 'enhancement',
-    chip: {
-      color: 'blue' as const
+      color: 'error' as const
    }
  },
  {
    label: 'feature',
    value: 'feature',
    chip: {
-      color: 'violet' as const
+      color: 'success' as const
+    }
+  },
+  {
+    label: 'enhancement',
+    value: 'enhancement',
+    chip: {
+      color: 'info' as const
    }
  }
 ])
--- a/docs/app/components/content/examples/select/SelectItemsChipExample.vue
+++ b/docs/app/components/content/examples/select/SelectItemsChipExample.vue
@@ -4,21 +4,21 @@ const items = ref([
    label: 'bug',
    value: 'bug',
    chip: {
-      color: 'red' as const
-    }
-  },
-  {
-    label: 'enhancement',
-    value: 'enhancement',
-    chip: {
-      color: 'blue' as const
+      color: 'error' as const
    }
  },
  {
    label: 'feature',
    value: 'feature',
    chip: {
-      color: 'violet' as const
+      color: 'success' as const
+    }
+  },
+  {
+    label: 'enhancement',
+    value: 'enhancement',
+    chip: {
+      color: 'info' as const
    }
  }
 ])
--- a/docs/app/components/content/examples/slideover/SlideoverExample.vue
+++ b/docs/app/components/content/examples/slideover/SlideoverExample.vue
@@ -13,7 +13,7 @@ defineProps<{
    </template>

    <template #footer>
-      <UButton color="gray" label="Close" @click="slideover.close()" />
+      <UButton color="neutral" label="Close" @click="slideover.close()" />
    </template>
  </USlideover>
 </template>
--- a/docs/app/components/content/examples/slideover/SlideoverFooterSlotExample.vue
+++ b/docs/app/components/content/examples/slideover/SlideoverFooterSlotExample.vue
@@ -4,15 +4,15 @@ const open = ref(false)

 <template>
  <USlideover v-model:open="open" title="Slideover with footer" description="This is useful when you want a form in a Slideover." :ui="{ footer: 'justify-end' }">
-    <UButton label="Open" color="gray" variant="subtle" />
+    <UButton label="Open" color="neutral" variant="subtle" />

    <template #body>
      <Placeholder class="h-full" />
    </template>

    <template #footer>
-      <UButton label="Cancel" color="gray" variant="outline" @click="open = false" />
-      <UButton label="Submit" color="gray" />
+      <UButton label="Cancel" color="neutral" variant="outline" @click="open = false" />
+      <UButton label="Submit" color="neutral" />
    </template>
  </USlideover>
 </template>
--- a/docs/app/components/content/examples/slideover/SlideoverNestedExample.vue
+++ b/docs/app/components/content/examples/slideover/SlideoverNestedExample.vue
@@ -5,24 +5,24 @@ const second = ref(false)

 <template>
  <USlideover v-model:open="first" title="First slideover" :ui="{ footer: 'justify-end' }">
-    <UButton color="gray" variant="subtle" label="Open" />
+    <UButton color="neutral" variant="subtle" label="Open" />

    <template #body>
      <Placeholder class="h-full" />
    </template>

    <template #footer>
-      <UButton label="Close" color="gray" variant="outline" @click="first = false" />
+      <UButton label="Close" color="neutral" variant="outline" @click="first = false" />

      <USlideover v-model:open="second" title="Second slideover" :ui="{ footer: 'justify-end' }">
-        <UButton label="Open second" color="gray" />
+        <UButton label="Open second" color="neutral" />

        <template #body>
          <Placeholder class="h-full" />
        </template>

        <template #footer>
-          <UButton label="Close" color="gray" variant="outline" @click="second = false" />
+          <UButton label="Close" color="neutral" variant="outline" @click="second = false" />
        </template>
      </USlideover>
    </template>
--- a/docs/app/components/content/examples/slideover/SlideoverOpenExample.vue
+++ b/docs/app/components/content/examples/slideover/SlideoverOpenExample.vue
@@ -8,7 +8,7 @@ defineShortcuts({

 <template>
  <USlideover v-model:open="open">
-    <UButton label="Open" color="gray" variant="subtle" />
+    <UButton label="Open" color="neutral" variant="subtle" />

    <template #content>
      <Placeholder class="h-full m-4" />
--- a/docs/app/components/content/examples/slideover/SlideoverProgrammaticExample.vue
+++ b/docs/app/components/content/examples/slideover/SlideoverProgrammaticExample.vue
@@ -16,5 +16,5 @@ function open() {
 </script>

 <template>
-  <UButton label="Open" color="gray" variant="subtle" @click="open" />
+  <UButton label="Open" color="neutral" variant="subtle" @click="open" />
 </template>
--- a/docs/app/components/content/examples/tabs/TabsCustomSlotExample.vue
+++ b/docs/app/components/content/examples/tabs/TabsCustomSlotExample.vue
@@ -26,7 +26,7 @@ const state = reactive({
 <template>
  <UTabs :items="items" variant="link" class="gap-4 w-full" :ui="{ trigger: 'flex-1' }">
    <template #account="{ item }">
-      <p class="text-gray-500 dark:text-gray-400 mb-4">
+      <p class="text-[--ui-text-muted] mb-4">
        {{ item.description }}
      </p>

@@ -43,7 +43,7 @@ const state = reactive({
    </template>

    <template #password="{ item }">
-      <p class="text-gray-500 dark:text-gray-400 mb-4">
+      <p class="text-[--ui-text-muted] mb-4">
        {{ item.description }}
      </p>

--- a/docs/app/components/content/examples/toast/ToastActionsExample.vue
+++ b/docs/app/components/content/examples/toast/ToastActionsExample.vue
@@ -12,7 +12,7 @@ function showToast() {
    actions: [{
      icon: 'i-heroicons-arrow-path-20-solid',
      label: 'Retry',
-      color: 'gray',
+      color: 'neutral',
      variant: 'outline',
      onClick: (e) => {
        e?.stopPropagation()
@@ -23,5 +23,5 @@ function showToast() {
 </script>

 <template>
-  <UButton label="Show toast" color="gray" variant="outline" @click="showToast" />
+  <UButton label="Show toast" color="neutral" variant="outline" @click="showToast" />
 </template>
--- a/docs/app/components/content/examples/toast/ToastAvatarExample.vue
+++ b/docs/app/components/content/examples/toast/ToastAvatarExample.vue
@@ -17,5 +17,5 @@ function showToast() {
 </script>

 <template>
-  <UButton label="Invite user" color="gray" variant="outline" @click="showToast" />
+  <UButton label="Invite user" color="neutral" variant="outline" @click="showToast" />
 </template>
--- a/docs/app/components/content/examples/toast/ToastCloseExample.vue
+++ b/docs/app/components/content/examples/toast/ToastCloseExample.vue
@@ -16,5 +16,5 @@ function showToast() {
 </script>

 <template>
-  <UButton label="Show toast" color="gray" variant="outline" @click="showToast" />
+  <UButton label="Show toast" color="neutral" variant="outline" @click="showToast" />
 </template>
--- a/docs/app/components/content/examples/toast/ToastCloseIconExample.vue
+++ b/docs/app/components/content/examples/toast/ToastCloseIconExample.vue
@@ -15,5 +15,5 @@ function showToast() {
 </script>

 <template>
-  <UButton label="Show toast" color="gray" variant="outline" @click="showToast" />
+  <UButton label="Show toast" color="neutral" variant="outline" @click="showToast" />
 </template>
--- a/docs/app/components/content/examples/toast/ToastColorExample.vue
+++ b/docs/app/components/content/examples/toast/ToastColorExample.vue
@@ -18,5 +18,5 @@ function showToast() {
 </script>

 <template>
-  <UButton label="Show toast" color="gray" variant="outline" @click="showToast" />
+  <UButton label="Show toast" color="neutral" variant="outline" @click="showToast" />
 </template>
--- a/docs/app/components/content/examples/toast/ToastDescriptionExample.vue
+++ b/docs/app/components/content/examples/toast/ToastDescriptionExample.vue
@@ -12,5 +12,5 @@ function showToast() {
 </script>

 <template>
-  <UButton label="Show toast" color="gray" variant="outline" @click="showToast" />
+  <UButton label="Show toast" color="neutral" variant="outline" @click="showToast" />
 </template>
--- a/docs/app/components/content/examples/toast/ToastExample.vue
+++ b/docs/app/components/content/examples/toast/ToastExample.vue
@@ -14,5 +14,5 @@ function addToCalendar() {
 </script>

 <template>
-  <UButton label="Add to calendar" color="gray" variant="outline" icon="i-heroicons-plus" @click="addToCalendar" />
+  <UButton label="Add to calendar" color="neutral" variant="outline" icon="i-heroicons-plus" @click="addToCalendar" />
 </template>
--- a/docs/app/components/content/examples/toast/ToastIconExample.vue
+++ b/docs/app/components/content/examples/toast/ToastIconExample.vue
@@ -15,5 +15,5 @@ function showToast() {
 </script>

 <template>
-  <UButton label="Show toast" color="gray" variant="outline" @click="showToast" />
+  <UButton label="Show toast" color="neutral" variant="outline" @click="showToast" />
 </template>
--- a/docs/app/components/content/examples/toast/ToastTitleExample.vue
+++ b/docs/app/components/content/examples/toast/ToastTitleExample.vue
@@ -11,5 +11,5 @@ function showToast() {
 </script>

 <template>
-  <UButton label="Show toast" color="gray" variant="outline" @click="showToast" />
+  <UButton label="Show toast" color="neutral" variant="outline" @click="showToast" />
 </template>
--- a/docs/app/components/content/examples/toaster/ToasterDurationExample.vue
+++ b/docs/app/components/content/examples/toaster/ToasterDurationExample.vue
@@ -7,16 +7,16 @@ const appConfig = useAppConfig()
    <UFormField
      label="toaster.duration"
      size="sm"
-      class="inline-flex ring ring-gray-300 dark:ring-gray-700 rounded"
+      class="inline-flex ring ring-[--ui-border-accented] rounded"
      :ui="{
-        wrapper: 'bg-gray-50 dark:bg-gray-800/50 rounded-l flex border-r border-gray-300 dark:border-gray-700',
-        label: 'text-gray-500 dark:text-gray-400 px-2 py-1.5',
+        wrapper: 'bg-[--ui-bg-elevated]/50 rounded-l flex border-r border-[--ui-border-accented]',
+        label: 'text-[--ui-text-muted] px-2 py-1.5',
        container: 'mt-0'
      }"
    >
      <UInput
        v-model="appConfig.toaster.duration"
-        color="gray"
+        color="neutral"
        variant="soft"
        class="rounded rounded-l-none min-w-12"
        :search-input="false"
--- a/docs/app/components/content/examples/toaster/ToasterExpandExample.vue
+++ b/docs/app/components/content/examples/toaster/ToasterExpandExample.vue
@@ -7,17 +7,17 @@ const appConfig = useAppConfig()
    <UFormField
      label="toaster.expand"
      size="sm"
-      class="inline-flex ring ring-gray-300 dark:ring-gray-700 rounded"
+      class="inline-flex ring ring-[--ui-border-accented] rounded"
      :ui="{
-        wrapper: 'bg-gray-50 dark:bg-gray-800/50 rounded-l flex border-r border-gray-300 dark:border-gray-700',
-        label: 'text-gray-500 dark:text-gray-400 px-2 py-1.5',
+        wrapper: 'bg-[--ui-bg-elevated]/50 rounded-l flex border-r border-[--ui-border-accented]',
+        label: 'text-[--ui-text-muted] px-2 py-1.5',
        container: 'mt-0'
      }"
    >
      <USelectMenu
        v-model="appConfig.toaster.expand"
        :items="[true, false]"
-        color="gray"
+        color="neutral"
        variant="soft"
        class="rounded rounded-l-none min-w-12"
        :search-input="false"
--- a/docs/app/components/content/examples/toaster/ToasterPositionExample.vue
+++ b/docs/app/components/content/examples/toaster/ToasterPositionExample.vue
@@ -10,17 +10,17 @@ const appConfig = useAppConfig()
    <UFormField
      label="toaster.position"
      size="sm"
-      class="inline-flex ring ring-gray-300 dark:ring-gray-700 rounded"
+      class="inline-flex ring ring-[--ui-border-accented] rounded"
      :ui="{
-        wrapper: 'bg-gray-50 dark:bg-gray-800/50 rounded-l flex border-r border-gray-300 dark:border-gray-700',
-        label: 'text-gray-500 dark:text-gray-400 px-2 py-1.5',
+        wrapper: 'bg-[--ui-bg-elevated]/50 rounded-l flex border-r border-[--ui-border-accented]',
+        label: 'text-[--ui-text-muted] px-2 py-1.5',
        container: 'mt-0'
      }"
    >
      <USelectMenu
        v-model="appConfig.toaster.position"
        :items="positions"
-        color="gray"
+        color="neutral"
        variant="soft"
        class="rounded rounded-l-none min-w-12"
        :search-input="false"
--- a/docs/app/components/content/examples/tooltip/TooltipOpenExample.vue
+++ b/docs/app/components/content/examples/tooltip/TooltipOpenExample.vue
@@ -8,6 +8,6 @@ defineShortcuts({

 <template>
  <UTooltip v-model:open="open" text="Open on GitHub">
-    <UButton label="Open" color="gray" variant="subtle" />
+    <UButton label="Open" color="neutral" variant="subtle" />
  </UTooltip>
 </template>
--- a/docs/app/pages/roadmap.vue
+++ b/docs/app/pages/roadmap.vue
@@ -16,7 +16,7 @@ const colorMode = useColorMode()

 const token = 'eyJ2aWV3IjoiYm9hcmQiLCJib2FyZFN0YXR1c2VzIjpbInRyaWFnZSIsImJhY2tsb2ciLCJ0b2RvIiwiaW5fcHJvZ3Jlc3MiLCJpbl9yZXZpZXciLCJkb25lIiwicmVsZWFzZWQiXSwiYm9hcmRMaW5rZWRQcnMiOmZhbHNlLCJsaXN0R3JvdXAiOiJzdGF0ZSIsImxpc3RPcmRlciI6ImNyZWF0ZWRfYXQiLCJ0aW1lbGluZVpvb20iOiJtb250aCIsInRpbWVsaW5lT3JkZXIiOiJzdGF0ZSIsInRpbWVsaW5lRGlzcGxheSI6ImFsbF9taWxlc3RvbmVzIiwiZmlsdGVycyI6e30sIm93bmVyIjoibnV4dCIsIm5hbWUiOiJ1aSJ9'

-const src = computed(() => `https://volta.net/embed/${token}?theme=${colorMode.value}&gray=${appConfig.ui.colors.gray}&primary=${appConfig.ui.colors.primary}`)
+const src = computed(() => `https://volta.net/embed/${token}?theme=${colorMode.value}&gray=${appConfig.ui.colors.neutral}&primary=${appConfig.ui.colors.primary}`)
 </script>

 <template>
--- a/docs/app/plugins/colors.ts
+++ b/docs/app/plugins/colors.ts
@@ -4,15 +4,15 @@ export default defineNuxtPlugin({
    const appConfig = useAppConfig()

    if (import.meta.client) {
-      const primary = window.localStorage.getItem('nuxt-ui-primary')
-      if (primary) {
-        appConfig.ui.colors.primary = primary
+      function updateColor(type: 'primary' | 'neutral') {
+        const color = localStorage.getItem(`nuxt-ui-${type}`)
+        if (color) {
+          appConfig.ui.colors[type] = color
+        }
      }

-      const gray = window.localStorage.getItem('nuxt-ui-gray')
-      if (gray) {
-        appConfig.ui.colors.gray = gray
-      }
+      updateColor('primary')
+      updateColor('neutral')
    }

    if (import.meta.server) {
@@ -23,13 +23,21 @@ export default defineNuxtPlugin({
            let html = document.querySelector('style#nuxt-ui-colors').innerHTML;

            if (localStorage.getItem('nuxt-ui-primary')) {
-              html = html.replaceAll('${appConfig.ui.colors.primary}', localStorage.getItem('nuxt-ui-primary'))
+              const primaryColor = localStorage.getItem('nuxt-ui-primary');
+              html = html.replace(
+                /(--ui-color-primary-\\d{2,3}:\\s*var\\()--color-${appConfig.ui.colors.primary}-(\\d{2,3}\\))/g,
+                \`$1--color-\${primaryColor}-$2\`
+              );
            }
-            if (localStorage.getItem('nuxt-ui-gray')) {
-              html = html.replaceAll('${appConfig.ui.colors.gray}', localStorage.getItem('nuxt-ui-gray'))
+            if (localStorage.getItem('nuxt-ui-neutral')) {
+              const neutralColor = localStorage.getItem('nuxt-ui-neutral');
+              html = html.replace(
+                /(--ui-color-neutral-\\d{2,3}:\\s*var\\()--color-${appConfig.ui.colors.neutral}-(\\d{2,3}\\))/g,
+                \`$1--color-\${neutralColor}-$2\`
+              );
            }

-            document.querySelector('style#nuxt-ui-colors').innerHTML = html
+            document.querySelector('style#nuxt-ui-colors').innerHTML = html;
            `.replace(/\s+/g, ' '),
            type: 'text/javascript',
            tagPriority: -1
--- a/docs/content/1.getting-started/2.installation.md
+++ b/docs/content/1.getting-started/2.installation.md
@@ -39,9 +39,7 @@ export default defineNuxtConfig({
 })
 ```

-3. Import Tailwind and Nuxt UI in your `app.vue`{lang="ts-type"} or in your [CSS](https://nuxt.com/docs/getting-started/styling#the-css-property):
-
-::code-group
+3. Import Tailwind CSS and Nuxt UI in your `app.vue`{lang="ts-type"} or [CSS](https://nuxt.com/docs/getting-started/styling#the-css-property):

 ```vue [app.vue]
 <style>
@@ -50,13 +48,6 @@ export default defineNuxtConfig({
 </style>
 ```

-```css [main.css]
-@import "tailwindcss";
-@import "@nuxt/ui";
-```
-
-::
-
 ## Options

 You can customize Nuxt UI by providing options in your `nuxt.config.ts`:
@@ -91,25 +82,40 @@ export default defineNuxtConfig({
 })
 ```

+### `colorMode`
+
+Use the `colorMode` option to enable or disable the `@nuxt/color-mode` module.
+
+- Default: `true`{lang="ts-type"}
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ['@nuxt/ui'],
+  ui: {
+    colorMode: false
+  }
+})
+```
+
 ### `theme.colors`

 Use the `theme.colors` option to choose which Tailwind CSS colors are used to generate classes for components.

- Default: `['red', 'orange', 'amber', 'yellow', 'lime', 'green', 'emerald', 'teal', 'cyan', 'sky', 'blue', 'indigo', 'violet', 'purple', 'fuchsia', 'pink', 'rose']`{lang="ts-type" class="inline"}
+- Default: `['primary', 'secondary', 'success', 'info', 'warning', 'error']`{lang="ts-type" class="inline"}

 ```ts [nuxt.config.ts]
 export default defineNuxtConfig({
  modules: ['@nuxt/ui'],
  ui: {
    theme: {
-      colors: ['blue', 'green', 'red']
+      colors: ['primary', 'error']
    }
  }
 })
 ```

-::note{to="/getting-started/colors#build-colors"}
-This can help reduce the number of CSS classes generated in your bundle.
+::tip{to="/getting-started/theme#colors"}
+You can use this option to remove some colors and reduce your CSS bundle or add new dynamic colors.
 ::

 ### `theme.transitions`
--- a/docs/content/1.getting-started/3.theme.md
+++ b/docs/content/1.getting-started/3.theme.md
@@ -1,6 +1,6 @@
 ---
 title: Theme
-description: 'Learn to customize Nuxt UI components using Tailwind CSS v4 and the Tailwind Variants API.'
+description: 'Learn how to customize Nuxt UI components using Tailwind CSS v4, CSS variables and the Tailwind Variants API for powerful and flexible theming.'
 ---

 ## Tailwind CSS
@@ -11,7 +11,8 @@ Nuxt UI v3 uses Tailwind CSS v4 alpha which doesn't have a documentation yet, le

 Tailwind CSS v4 takes a CSS-first configuration approach, you now customize your theme with CSS variables inside a `@theme` directive:

-```css [main.css]
+```vue [app.vue]
+<style>
@import "tailwindcss";
@import "@nuxt/ui";

@@ -32,6 +33,7 @@ Tailwind CSS v4 takes a CSS-first configuration approach, you now customize your
  --color-green-900: #0A5331;
  --color-green-950: #052E16;
 }
+</style>
 ```

 The `@theme` directive tells Tailwind to make new utilities and variants available based on those variables. It's the equivalent of the `theme.extend` key in Tailwind CSS v3 `tailwind.config.ts` file.
@@ -40,19 +42,19 @@ The `@theme` directive tells Tailwind to make new utilities and variants availab
 You can learn more about this on [https://tailwindcss.com/blog/tailwindcss-v4-alpha](https://tailwindcss.com/blog/tailwindcss-v4-alpha#css-first-configuration).
 ::

-This is exactly what the [`@import "@nuxt/ui";`](https://github.com/nuxt/ui/blob/v3/src/runtime/index.css) is all about, it extends the default Tailwind CSS theme and declares the `primary`, `error` and `gray` colors to be configurable through the [App Config](https://nuxt.com/docs/guide/directory-structure/app-config#app-config-file) but we'll talk more about that in the [Colors](/getting-started/colors) section.
-
 ### `@source`

 You can use the `@source` directive to add explicit content glob patterns if you want to look for Tailwind classes in other files that are not automatically detected.

 This can be useful when writing Tailwind classes in markdown files with `@nuxt/content`:

-```css [main.css]
+```vue [app.vue]
+<style>
@import "tailwindcss";
@import "@nuxt/ui";

@source "../content/**/*.md";
+</style>
 ```

 ::note{to="https://github.com/tailwindlabs/tailwindcss/pull/14078"}
@@ -63,18 +65,264 @@ You can learn more about the `@source` directive in this pull request.

 You can use the `@plugin` directive to import Tailwind CSS plugins.

-```css [main.css]
+```vue [app.vue]
+<style>
@import "tailwindcss";
@import "@nuxt/ui";

@plugin "@tailwindcss/typography";
+</style>
 ```

 ::note{to="https://github.com/tailwindlabs/tailwindcss/pull/14264"}
 You can learn more about the `@plugin` directive in this pull request.
 ::

-## Tailwind Variants API
+## Design system
+
+Nuxt UI extends Tailwind CSS's theming capabilities, providing a flexible design system with pre-configured color aliases and CSS variables. This allows for easy customization and quick adaptation of the UI to your brand's aesthetic.
+
+### Colors
+
+Nuxt UI leverages Nuxt [App Config](https://nuxt.com/docs/guide/directory-structure/app-config#app-config-file) to provide customizable color aliases based on [Tailwind CSS colors](https://tailwindcss.com/docs/customizing-colors#color-palette-reference):
+
+| Color | Default | Description |
+| --- | --- | --- |
+| `primary`{color="primary"} | `green` | Main brand color, used as the default color for components. |
+| `secondary`{color="secondary"} | `blue` | Secondary color to complement the primary color. |
+| `success`{color="success"} | `green` | Used for success states. |
+| `info`{color="info"} | `blue` | Used for informational states. |
+| `warning`{color="warning"} | `yellow` | Used for warning states. |
+| `error`{color="error"} | `red` | Used for form error validation states. |
+| `neutral` | `slate` | Neutral color for backgrounds, text, etc. |
+
+You can configure these color aliases at runtime in your `app.config.ts` file under the `ui.colors` key, allowing for dynamic theme customization without requiring an application rebuild:
+
+```ts [app.config.ts]
+export default defineAppConfig({
+  ui: {
+    colors: {
+      primary: 'blue',
+      neutral: 'zinc'
+    }
+  }
+})
+```
+
+::note
+Try the :prose-icon{name="i-heroicons-swatch-20-solid" class="text-[--ui-primary]"} picker in the header above to change `primary` and `neutral` colors.
+::
+
+These colors are used to style the components but also to generate the `color` variants:
+
+::component-code{slug="button"}
+---
+props:
+  color: primary
+slots:
+  default: Button
+---
+::
+
+::tip
+You can add you own dynamic color aliases in your `app.config.ts`, you just have to make sure to define them in the [`ui.theme.colors`](/getting-started/installation#themecolors) option in your `nuxt.config.ts` file.
+
+```ts [app.config.ts]
+export default defineAppConfig({
+  ui: {
+    colors: {
+      tertiary: 'indigo'
+    }
+  }
+})
+```
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  ui: {
+    theme: {
+      colors: ['primary', 'secondary', 'tertiary', 'info', 'success', 'warning', 'error']
+    }
+  }
+})
+```
+
+::
+
+::note
+These color aliases are not automatically defined as Tailwind CSS colors, so classes like `text-primary-500 dark:text-primary-400` won't be available by default as in Nuxt UI v2. This approach provides more flexibility and prevents overwriting of user-defined Tailwind CSS colors.<br><br>
+
+However, you can generate these classes using Tailwind's `@theme` directive, allowing you to use custom color utility classes while maintaining dynamic color aliases:
+
+```vue [app.vue]
+<style>
+@import "tailwindcss";
+@import "@nuxt/ui";
+
+@theme {
+  --color-primary-50: var(--ui-color-primary-50);
+  --color-primary-100: var(--ui-color-primary-100);
+  --color-primary-200: var(--ui-color-primary-200);
+  --color-primary-300: var(--ui-color-primary-300);
+  --color-primary-400: var(--ui-color-primary-400);
+  --color-primary-500: var(--ui-color-primary-500);
+  --color-primary-600: var(--ui-color-primary-600);
+  --color-primary-700: var(--ui-color-primary-700);
+  --color-primary-800: var(--ui-color-primary-800);
+  --color-primary-900: var(--ui-color-primary-900);
+  --color-primary-950: var(--ui-color-primary-950);
+}
+</style>
+```
+::
+
+### Tokens
+
+Nuxt UI generates CSS variables as design tokens for component styling. These tokens enable consistent theming and support both light and dark modes. You can use them in Tailwind classes like `text-[--ui-primary]`, which automatically adapts to the current color scheme.
+
+::code-group
+
+```css [Light]
+:root {
+  --ui-primary: var(--ui-color-primary-500);
+  --ui-secondary: var(--ui-color-secondary-500);
+  --ui-success: var(--ui-color-success-500);
+  --ui-info: var(--ui-color-info-500);
+  --ui-warning: var(--ui-color-warning-500);
+  --ui-error: var(--ui-color-error-500);
+}
+```
+
+```css [Dark]
+.dark {
+  --ui-primary: var(--ui-color-primary-400);
+  --ui-secondary: var(--ui-color-secondary-400);
+  --ui-success: var(--ui-color-success-400);
+  --ui-info: var(--ui-color-info-400);
+  --ui-warning: var(--ui-color-warning-400);
+  --ui-error: var(--ui-color-error-400);
+}
+```
+
+::
+
+::tip
+You can change which shade is used for each color on light and dark mode:
+
+```vue [app.vue]
+<style>
+@import "tailwindcss";
+@import "@nuxt/ui";
+
+:root {
+  --ui-primary: var(--ui-color-primary-700);
+}
+
+.dark {
+  --ui-primary: var(--ui-color-primary-200);
+}
+</style>
+```
+::
+
+Nuxt UI provides a comprehensive set of design tokens for the `neutral` color palette, ensuring consistent and accessible UI styling across both light and dark modes. These tokens offer fine-grained control over text, background, and border colors:
+
+::code-group
+
+```css [Light]
+:root {
+  /* Least prominent text */
+  --ui-text-dimmed: var(--ui-color-neutral-400);
+  /* Slightly muted text */
+  --ui-text-muted: var(--ui-color-neutral-500);
+  /* Moderately prominent text */
+  --ui-text-toned: var(--ui-color-neutral-600);
+  /* Default text color */
+  --ui-text: var(--ui-color-neutral-700);
+  /* Most prominent text */
+  --ui-text-highlighted: var(--ui-color-neutral-900);
+
+  /* Main background color */
+  --ui-bg: var(--color-white);
+  /* Slightly elevated background */
+  --ui-bg-elevated: var(--ui-color-neutral-100);
+  /* More prominent background */
+  --ui-bg-accented: var(--ui-color-neutral-200);
+  /* Inverted background color */
+  --ui-bg-inverted: var(--ui-color-neutral-900);
+
+  /* Default border color */
+  --ui-border: var(--ui-color-neutral-200);
+  /* More prominent border */
+  --ui-border-accented: var(--ui-color-neutral-300);
+  /* Inverted border color */
+  --ui-border-inverted: var(--ui-color-neutral-900);
+}
+```
+
+```css [Dark]
+.dark {
+  /* Least prominent text */
+  --ui-text-dimmed: var(--ui-color-neutral-500);
+  /* Slightly muted text */
+  --ui-text-muted: var(--ui-color-neutral-400);
+  /* Moderately prominent text */
+  --ui-text-toned: var(--ui-color-neutral-300);
+  /* Default text color */
+  --ui-text: var(--ui-color-neutral-200);
+  /* Most prominent text */
+  --ui-text-highlighted: var(--color-white);
+
+  /* Main background color */
+  --ui-bg: var(--ui-color-neutral-900);
+  /* Slightly elevated background */
+  --ui-bg-elevated: var(--ui-color-neutral-800);
+  /* More prominent background */
+  --ui-bg-accented: var(--ui-color-neutral-700);
+  /* Inverted background color */
+  --ui-bg-inverted: var(--color-white);
+
+  /* Default border color */
+  --ui-border: var(--ui-color-neutral-800);
+  /* More prominent border */
+  --ui-border-accented: var(--ui-color-neutral-700);
+  /* Inverted border color */
+  --ui-border-inverted: var(--color-white);
+}
+```
+
+::
+
+You can easily customize these CSS variables in your `app.vue`{lang="ts-type"} or [CSS](https://nuxt.com/docs/getting-started/styling#the-css-property) to tailor the appearance of your application:
+
+```vue [app.vue]
+<style>
+@import "tailwindcss";
+@import "@nuxt/ui";
+
+:root {
+  --ui-bg: var(--ui-color-neutral-50);
+  --ui-text: var(--ui-color-neutral-900);
+}
+
+.dark {
+  --ui-bg: var(--ui-color-neutral-950);
+  --ui-border: var(--ui-color-neutral-900);
+}
+</style>
+```
+
+::note
+Nuxt UI automatically applies a text and background color on the `<body>` element of your app:
+
+```css
+body {
+  @apply antialiased font-sans text-[--ui-text] bg-[--ui-bg];
+}
+```
+::
+
+## Components theme

 Nuxt UI components are styled using the [Tailwind Variants](https://www.tailwind-variants.org/) API, which provides a powerful way to create variants and manage component styles. Let's explore the key features of this API:

@@ -87,7 +335,7 @@ Components in Nuxt UI can have multiple `slots`, each representing a distinct HT
 ```ts [src/theme/card.ts]
 export default {
  slots: {
-    root: 'bg-white dark:bg-gray-900 ring ring-gray-200 dark:ring-gray-800 divide-y divide-gray-200 dark:divide-gray-800 rounded-lg shadow',
+    root: 'bg-[--ui-bg] ring ring-[--ui-border] divide-y divide-[--ui-border] rounded-lg shadow',
    header: 'p-4 sm:px-6',
    body: 'p-4 sm:p-6',
    footer: 'p-4 sm:px-6'
@@ -135,7 +383,7 @@ export default {

 ::

-::caution
+::note
 Components without slots don't have a [`ui` prop](#ui-prop), only the [`class` prop](#class-prop) is available to override styles.
 ::

@@ -146,18 +394,18 @@ Nuxt UI components use `variants` to change the `slots` styles based on props. H
 ```ts [src/theme/avatar.ts]
 export default {
  slots: {
-    root: 'inline-flex items-center justify-center shrink-0 select-none overflow-hidden rounded-full align-middle bg-gray-100 dark:bg-gray-800',
+    root: 'inline-flex items-center justify-center shrink-0 select-none overflow-hidden rounded-full align-middle bg-[--ui-bg-elevated]',
    image: 'h-full w-full rounded-[inherit] object-cover'
  },
  variants: {
    size: {
-      'sm': {
+      sm: {
        root: 'size-7 text-sm'
      },
-      'md': {
+      md: {
        root: 'size-8 text-base'
      },
-      'lg': {
+      lg: {
        root: 'size-9 text-lg'
      }
    }
@@ -182,7 +430,7 @@ props:

 The `defaultVariants` property specifies the default values for each variant. It determines how a component looks and behaves when no prop is provided. These default values can be customized in your [`app.config.ts`](#appconfigts) to adjust the standard appearance of components throughout your application.

-## Customize components
+## Customize theme

 You have multiple ways to customize the appearance of Nuxt UI components, you can do it for all components at once or on a per-component basis.

@@ -225,18 +473,18 @@ You can also override a component's **slots** using the `ui` prop. This has prio
 ---
 prettier: true
 ignore:
-  - ui.leadingIcon
+  - ui.trailingIcon
  - color
  - variant
  - size
  - icon
 props:
-  icon: i-heroicons-magnifying-glass
+  trailingIcon: i-heroicons-chevron-right
  size: md
-  color: gray
+  color: neutral
  variant: outline
  ui:
-    leadingIcon: 'text-primary-500 dark:text-primary-400 size-3'
+    trailingIcon: 'rotate-90 size-3'
 slots:
  default: |

@@ -244,7 +492,7 @@ slots:
 ---
 ::

-In this example, the `leadingIcon` slot is overwritten even though the `md` size variant would apply a `size-5` class by default.
+In this example, the `trailingIcon` slot is overwritten with `size-3` even though the `md` size variant would apply a `size-5` class to it.

 ### `class` prop

--- a/docs/content/1.getting-started/4.colors.md
+++ b/docs/content/1.getting-started/4.colors.md
@@ -1,168 +0,0 @@
---
-title: Colors
-description: 'Learn to customize Nuxt UI component colors, enhancing your application visual theme.'
---
-
-## Build colors
-
-Nuxt UI components provide dynamic `color` variants. By default, these variants classes are generated based on the default Tailwind CSS colors. Let's take the [Button](/components/button) component as an example:
-
-::component-code{slug="button"}
---
-props:
-  color: 'green'
-slots:
-  default: Button
---
-::
-
-You can change these colors with the [`theme.colors`](/getting-started/installation#themecolors) option in your `nuxt.config.ts` to select only the colors you're actually using.
-
-For example, if you added a custom `cerise` color and only use the default `blue` and `green` colors in your application, you can configure the `colors` option like this:
-
-::code-group
-
-```ts [nuxt.config.ts]
-export default defineNuxtConfig({
-  modules: ['@nuxt/ui'],
-  ui: {
-    theme: {
-      colors: ['cerise', 'blue', 'green']
-    }
-  }
-})
-```
-
-```css [main.css]
-@import "tailwindcss";
-@import "@nuxt/ui";
-
-@theme {
-  --color-cerise-50: #FEF2F4;
-  --color-cerise-100: #FDE6E9;
-  --color-cerise-200: #FBD0D9;
-  --color-cerise-300: #F7AAB9;
-  --color-cerise-400: #F27A93;
-  --color-cerise-500: #E63F66;
-  --color-cerise-600: #D42A5B;
-  --color-cerise-700: #B21E4B;
-  --color-cerise-800: #951C45;
-  --color-cerise-900: #801B40;
-  --color-cerise-950: #470A1F;
-}
-```
-::
-
-::caution
-Make sure to use color ranges from `50` to `950`. You can use tools like [UI Colors](https://uicolors.app/) to generate your palette.
-::
-
-This configuration will ensure that only classes for those three colors are generated in your final CSS bundle. When you use the `color` prop, it will be typed and provide autocompletion in your editor with those three colors.
-
-```vue
-<template>
-  <UButton color="cerise">Button</UButton>
-</template>
-```
-
-## Runtime colors
-
-### Default aliases
-
-Nuxt UI introduces three key color aliases used to style components:
-
- `primary`: Main brand color, used as the default color for components.
-  - Default: `green`{color="green"}
- `error`: For form error validation states.
-  - Default: `red`{color="red"}
- `gray`: Neutral color for backgrounds, text, etc.
-  - Default: `slate`
-  - `slate | cool | zinc | neutral | stone`
-
-::warning{to="https://tailwindcss.com/docs/customizing-colors#default-color-palette" target="_blank"}
-The Tailwind CSS `gray` color is renamed to `cool` in Nuxt UI to avoid conflicts with the `gray` alias.
-::
-
-You can configure these aliases in your `app.config.ts` file under the `ui.colors` key:
-
-```ts [app.config.ts]
-export default defineAppConfig({
-  ui: {
-    colors: {
-      primary: 'blue',
-      error: 'orange',
-      gray: 'zinc'
-    }
-  }
-})
-```
-
-This powerful feature leverages Nuxt [App Config](https://nuxt.com/docs/guide/directory-structure/app-config#app-config-file), enabling dynamic styling of all components at runtime. It allows for real-time theme customization without requiring an application rebuild.
-
-::tip
-We recommend using these colors in your application whenever possible with classes like `text-primary-500 dark:text-primary-400`, `border-gray-200 dark:border-gray-800` or `bg-white dark:bg-gray-900` for example.
-::
-
-::important
-These alias colors don't need to be explicitly listed in the `colors` option of your `nuxt.config.ts`. Also, if you've set `primary` to a custom color (e.g., `cerise`), you don't need to list `cerise` in the `colors` array.
-::
-
-::note
-You can try this out by using the :prose-icon{name="i-heroicons-swatch-20-solid" class="text-primary-500 dark:text-primary-400"} menu in the header of this documentation.
-::
-
-### Custom aliases
-
-You can also add your own color aliases to be configurable at runtime in your `app.config.ts` file:
-
-1. Define the alias color by using CSS variables to let Tailwind know about it:
-
-```css [main.css]
-@import "tailwindcss";
-@import "@nuxt/ui";
-
-@theme {
-  --color-secondary-50: var(--color-secondary-50);
-  --color-secondary-100: var(--color-secondary-100);
-  --color-secondary-200: var(--color-secondary-200);
-  --color-secondary-300: var(--color-secondary-300);
-  --color-secondary-400: var(--color-secondary-400);
-  --color-secondary-500: var(--color-secondary-500);
-  --color-secondary-600: var(--color-secondary-600);
-  --color-secondary-700: var(--color-secondary-700);
-  --color-secondary-800: var(--color-secondary-800);
-  --color-secondary-900: var(--color-secondary-900);
-  --color-secondary-950: var(--color-secondary-950);
-}
-```
-
-2. Set a default value for the color alias in your `app.config.ts` file:
-
-```ts [app.config.ts]
-export default defineAppConfig({
-  ui: {
-    colors: {
-      secondary: 'indigo'
-    }
-  }
-})
-```
-
-3. Add this color to the `colors` option of your `nuxt.config.ts` file to generate classes:
-
-```ts [nuxt.config.ts]
-export default defineNuxtConfig({
-  modules: ['@nuxt/ui'],
-  ui: {
-    colors: ['secondary']
-  }
-})
-```
-
-4. You can use the `secondary` color alias in your application and use classes like `text-secondary-500 dark:text-secondary-400`:
-
-```vue
-<template>
-  <UButton color="secondary">Button</UButton>
-</template>
-```
--- a/docs/content/1.getting-started/4.icons.md
+++ b/docs/content/1.getting-started/4.icons.md
--- a/docs/content/1.getting-started/5.fonts.md
+++ b/docs/content/1.getting-started/5.fonts.md
@@ -12,8 +12,6 @@ links:

 Nuxt UI automatically registers the `@nuxt/fonts` module for you, so there's no additional setup required. To use a font in your Nuxt UI application, you can simply declare it in your CSS:

-::code-group
-
 ```vue [app.vue]
 <style>
@import "tailwindcss";
@@ -25,17 +23,6 @@ Nuxt UI automatically registers the `@nuxt/fonts` module for you, so there's no
 </style>
 ```

-```css [main.css]
-@import "tailwindcss";
-@import "@nuxt/ui";
-
-@theme {
-  --font-family-sans: 'Public Sans', sans-serif;
-}
-```
-
-::
-
 That's it! Nuxt Fonts will detect this and you should immediately see the web font loaded in your browser.

 ::tip{to="https://fonts.nuxt.com/advanced" target="_blank"}
--- a/docs/content/1.getting-started/6.color-mode.md
+++ b/docs/content/1.getting-started/6.color-mode.md
--- a/docs/content/2.composables/use-toast.md
+++ b/docs/content/2.composables/use-toast.md
@@ -42,7 +42,7 @@ function showToast() {
  toast.add({
    title: 'Success',
    description: 'Your action was completed successfully.',
-    color: 'green'
+    color: 'success'
  })
 }
 </script>
--- a/docs/content/3.components/accordion.md
+++ b/docs/content/3.components/accordion.md
@@ -39,7 +39,7 @@ props:
      content: 'You have nothing to do, @nuxt/icon will handle it automatically.'
    - label: 'Colors'
      icon: 'i-heroicons-swatch'
-      content: 'Choose a primary and a gray color from your Tailwind CSS theme.'
+      content: 'Choose a primary and a neutral color from your Tailwind CSS theme.'
    - label: 'Components'
      icon: 'i-heroicons-cube-transparent'
      content: 'You can customize components by using the `class` / `ui` props or in your app.config.ts.'
@@ -68,7 +68,7 @@ props:
      content: 'You have nothing to do, @nuxt/icon will handle it automatically.'
    - label: 'Colors'
      icon: 'i-heroicons-swatch'
-      content: 'Choose a primary and a gray color from your Tailwind CSS theme.'
+      content: 'Choose a primary and a neutral color from your Tailwind CSS theme.'
    - label: 'Components'
      icon: 'i-heroicons-cube-transparent'
      content: 'You can customize components by using the `class` / `ui` props or in your app.config.ts.'
@@ -97,7 +97,7 @@ props:
      content: 'You have nothing to do, @nuxt/icon will handle it automatically.'
    - label: 'Colors'
      icon: 'i-heroicons-swatch'
-      content: 'Choose a primary and a gray color from your Tailwind CSS theme.'
+      content: 'Choose a primary and a neutral color from your Tailwind CSS theme.'
    - label: 'Components'
      icon: 'i-heroicons-cube-transparent'
      content: 'You can customize components by using the `class` / `ui` props or in your app.config.ts.'
@@ -127,7 +127,7 @@ props:
      content: 'You have nothing to do, @nuxt/icon will handle it automatically.'
    - label: 'Colors'
      icon: 'i-heroicons-swatch'
-      content: 'Choose a primary and a gray color from your Tailwind CSS theme.'
+      content: 'Choose a primary and a neutral color from your Tailwind CSS theme.'
      disabled: true
    - label: 'Components'
      icon: 'i-heroicons-cube-transparent'
@@ -139,7 +139,7 @@ props:

 Use the `trailing-icon` prop to customize the trailing [Icon](/components/icon) of each item. Defaults to `i-heroicons-chevron-down-20-solid`.

-::note
+::tip
 You can also set an icon for a specific item by using the `trailingIcon` property in the item object.
 ::

@@ -161,7 +161,7 @@ props:
      trailingIcon: 'i-heroicons-plus-20-solid'
    - label: 'Colors'
      icon: 'i-heroicons-swatch'
-      content: 'Choose a primary and a gray color from your Tailwind CSS theme.'
+      content: 'Choose a primary and a neutral color from your Tailwind CSS theme.'
    - label: 'Components'
      icon: 'i-heroicons-cube-transparent'
      content: 'You can customize components by using the `class` / `ui` props or in your app.config.ts.'
@@ -202,7 +202,7 @@ props:
 ---
 ::

-::note
+::tip
 The `#body` slot includes some pre-defined styles, use the [`#content` slot](#with-content-slot) if you want to start from scratch.
 ::

--- a/docs/content/3.components/alert.md
+++ b/docs/content/3.components/alert.md
@@ -78,7 +78,7 @@ ignore:
  - description
  - icon
 props:
-  color: gray
+  color: neutral
  title: 'Heads up!'
  description: 'You can change the primary color in your app config.'
  icon: 'i-heroicons-command-line'
@@ -97,7 +97,7 @@ ignore:
  - description
  - icon
 props:
-  color: gray
+  color: neutral
  variant: solid
  title: 'Heads up!'
  description: 'You can change the primary color in your app config.'
@@ -186,7 +186,7 @@ props:
  actions:
    - label: Action 1
    - label: Action 2
-      color: gray
+      color: neutral
      variant: subtle
 ---
 ::
--- a/docs/content/3.components/badge.md
+++ b/docs/content/3.components/badge.md
@@ -35,7 +35,7 @@ Use the `color` prop to change the color of the Badge.
 ::component-code
 ---
 props:
-  color: gray
+  color: neutral
 slots:
  default: Badge
 ---
@@ -48,7 +48,7 @@ Use the `variant` props to change the variant of the Badge.
 ::component-code
 ---
 props:
-  color: gray
+  color: neutral
  variant: outline
 slots:
  default: Badge
--- a/docs/content/3.components/button-group.md
+++ b/docs/content/3.components/button-group.md
@@ -17,11 +17,11 @@ prettier: true
 slots:
  default: |

-    <UButton color="gray" variant="subtle" label="Button" />
-    <UButton color="gray" variant="outline" icon="i-heroicons-chevron-down-20-solid" />
+    <UButton color="neutral" variant="subtle" label="Button" />
+    <UButton color="neutral" variant="outline" icon="i-heroicons-chevron-down-20-solid" />
 ---
-:u-button{color="gray" variant="subtle" label="Button"}
-:u-button{color="gray" variant="outline" icon="i-heroicons-chevron-down-20-solid"}
+:u-button{color="neutral" variant="subtle" label="Button"}
+:u-button{color="neutral" variant="outline" icon="i-heroicons-chevron-down-20-solid"}
 ::

 ### Size
@@ -36,11 +36,11 @@ props:
 slots:
  default: |

-    <UButton color="gray" variant="subtle" label="Button" />
-    <UButton color="gray" variant="outline" icon="i-heroicons-chevron-down-20-solid" />
+    <UButton color="neutral" variant="subtle" label="Button" />
+    <UButton color="neutral" variant="outline" icon="i-heroicons-chevron-down-20-solid" />
 ---
-:u-button{color="gray" variant="subtle" label="Button"}
-:u-button{color="gray" variant="outline" icon="i-heroicons-chevron-down-20-solid"}
+:u-button{color="neutral" variant="subtle" label="Button"}
+:u-button{color="neutral" variant="outline" icon="i-heroicons-chevron-down-20-solid"}
 ::

 ### Orientation
@@ -55,11 +55,11 @@ props:
 slots:
  default: |

-    <UButton color="gray" variant="subtle" label="Submit" />
-    <UButton color="gray" variant="outline" label="Cancel" />
+    <UButton color="neutral" variant="subtle" label="Submit" />
+    <UButton color="neutral" variant="outline" label="Cancel" />
 ---
-:u-button{color="gray" variant="subtle" label="Submit"}
-:u-button{color="gray" variant="outline" label="Cancel"}
+:u-button{color="neutral" variant="subtle" label="Submit"}
+:u-button{color="neutral" variant="outline" label="Cancel"}
 ::

 ## Examples
@@ -74,12 +74,12 @@ prettier: true
 slots:
  default: |

-    <UInput color="gray" variant="outline" placeholder="Enter token" />
+    <UInput color="neutral" variant="outline" placeholder="Enter token" />

-    <UButton color="gray" variant="subtle" icon="i-heroicons-clipboard-document" />
+    <UButton color="neutral" variant="subtle" icon="i-heroicons-clipboard-document" />
 ---
-:u-input{color="gray" variant="outline" placeholder="Enter token"}
-:u-button{color="gray" variant="subtle" icon="i-heroicons-clipboard-document"}
+:u-input{color="neutral" variant="outline" placeholder="Enter token"}
+:u-button{color="neutral" variant="subtle" icon="i-heroicons-clipboard-document"}
 ::

 ### With tooltip
--- a/docs/content/3.components/button.md
+++ b/docs/content/3.components/button.md
@@ -52,7 +52,7 @@ Use the `color` prop to change the color of the Button.
 ::component-code
 ---
 props:
-  color: gray
+  color: neutral
 slots:
  default: Button
 ---
@@ -65,7 +65,7 @@ Use the `variant` prop to change the variant of the Button.
 ::component-code
 ---
 props:
-  color: gray
+  color: neutral
  variant: outline
 slots:
  default: Button
@@ -211,10 +211,10 @@ ignore:
  - icon
 props:
  icon: i-heroicons-rocket-launch
-  color: gray
+  color: neutral
  variant: outline
  ui:
-    leadingIcon: 'text-primary-500 dark:text-primary-400'
+    leadingIcon: 'text-[--ui-primary]'
 slots:
  default: |

--- a/docs/content/3.components/carousel.md
+++ b/docs/content/3.components/carousel.md
@@ -7,7 +7,7 @@ links:
 navigation:
  badge:
    label: Todo
-    color: gray
+    color: neutral
  disabled: true
 ---

--- a/docs/content/3.components/checkbox.md
+++ b/docs/content/3.components/checkbox.md
@@ -129,7 +129,7 @@ ignore:
  - label
  - defaultValue
 props:
-  color: gray
+  color: neutral
  defaultValue: true
  label: Check me
 ---
--- a/docs/content/3.components/chip.md
+++ b/docs/content/3.components/chip.md
@@ -16,9 +16,9 @@ prettier: true
 slots:
  default: |

-    <UButton icon="i-heroicons-envelope" color="gray" variant="subtle" />
+    <UButton icon="i-heroicons-envelope" color="neutral" variant="subtle" />
 ---
-:u-button{icon="i-heroicons-envelope" color="gray" variant="subtle"}
+:u-button{icon="i-heroicons-envelope" color="neutral" variant="subtle"}
 ::

 ### Color
@@ -29,13 +29,13 @@ Use the `color` prop to change the color of the Chip.
 ---
 prettier: true
 props:
-  color: gray
+  color: neutral
 slots:
  default: |

-    <UButton icon="i-heroicons-envelope" color="gray" variant="subtle" />
+    <UButton icon="i-heroicons-envelope" color="neutral" variant="subtle" />
 ---
-:u-button{icon="i-heroicons-envelope" color="gray" variant="subtle"}
+:u-button{icon="i-heroicons-envelope" color="neutral" variant="subtle"}
 ::

 ### Size
@@ -50,9 +50,9 @@ props:
 slots:
  default: |

-    <UButton icon="i-heroicons-envelope" color="gray" variant="subtle" />
+    <UButton icon="i-heroicons-envelope" color="neutral" variant="subtle" />
 ---
-:u-button{icon="i-heroicons-envelope" color="gray" variant="subtle"}
+:u-button{icon="i-heroicons-envelope" color="neutral" variant="subtle"}
 ::

 ### Text
@@ -68,9 +68,9 @@ props:
 slots:
  default: |

-    <UButton icon="i-heroicons-envelope" color="gray" variant="subtle" />
+    <UButton icon="i-heroicons-envelope" color="neutral" variant="subtle" />
 ---
-:u-button{icon="i-heroicons-envelope" color="gray" variant="subtle"}
+:u-button{icon="i-heroicons-envelope" color="neutral" variant="subtle"}
 ::

 ### Position
@@ -85,9 +85,9 @@ props:
 slots:
  default: |

-    <UButton icon="i-heroicons-envelope" color="gray" variant="subtle" />
+    <UButton icon="i-heroicons-envelope" color="neutral" variant="subtle" />
 ---
-:u-button{icon="i-heroicons-envelope" color="gray" variant="subtle"}
+:u-button{icon="i-heroicons-envelope" color="neutral" variant="subtle"}
 ::

 ### Inset
--- a/docs/content/3.components/collapsible.md
+++ b/docs/content/3.components/collapsible.md
@@ -25,14 +25,14 @@ props:
 slots:
  default: |

-    <UButton label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-down-20-solid" block />
+    <UButton label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-down-20-solid" block />

  content: |

    <Placeholder class="h-48" />
 ---

-:u-button{label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-down-20-solid" block}
+:u-button{label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-down-20-solid" block}

 #content
 :placeholder{class="h-48"}
@@ -53,14 +53,14 @@ props:
 slots:
  default: |

-    <UButton label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-down-20-solid" block />
+    <UButton label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-down-20-solid" block />

  content: |

    <Placeholder class="h-48" />
 ---

-:u-button{label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-down-20-solid" block}
+:u-button{label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-down-20-solid" block}

 #content
 :placeholder{class="h-48"}
--- a/docs/content/3.components/command-palette.md
+++ b/docs/content/3.components/command-palette.md
@@ -355,7 +355,7 @@ class: '!p-0'
 ---
 ::

-::note
+::tip
 You can also use the `select` field on each item and/or the `@update:model-value` event.
 ::

--- a/docs/content/3.components/context-menu.md
+++ b/docs/content/3.components/context-menu.md
@@ -90,12 +90,12 @@ props:
 slots:
  default: |

-    <div class="flex items-center justify-center rounded-md border border-dashed border-gray-300 dark:border-gray-700 text-sm aspect-video w-72">
+    <div class="flex items-center justify-center rounded-md border border-dashed border-[--ui-border-accented] text-sm aspect-video w-72">
      Right click here
    </div>
 ---

-:div{class="flex items-center justify-center rounded-md border border-dashed border-gray-300 dark:border-gray-700 text-sm aspect-video w-72"}[Right click here]
+:div{class="flex items-center justify-center rounded-md border border-dashed border-[--ui-border-accented] text-sm aspect-video w-72"}[Right click here]
 ::

 ::note
@@ -131,12 +131,12 @@ props:
 slots:
  default: |

-    <div class="flex items-center justify-center rounded-md border border-dashed border-gray-300 dark:border-gray-700 text-sm aspect-video w-72">
+    <div class="flex items-center justify-center rounded-md border border-dashed border-[--ui-border-accented] text-sm aspect-video w-72">
      Right click here
    </div>
 ---

-:div{class="flex items-center justify-center rounded-md border border-dashed border-gray-300 dark:border-gray-700 text-sm aspect-video w-72"}[Right click here]
+:div{class="flex items-center justify-center rounded-md border border-dashed border-[--ui-border-accented] text-sm aspect-video w-72"}[Right click here]
 ::

 ### Disabled
@@ -164,12 +164,12 @@ props:
 slots:
  default: |

-    <div class="flex items-center justify-center rounded-md border border-dashed border-gray-300 dark:border-gray-700 text-sm aspect-video w-72">
+    <div class="flex items-center justify-center rounded-md border border-dashed border-[--ui-border-accented] text-sm aspect-video w-72">
      Right click here
    </div>
 ---

-:div{class="flex items-center justify-center rounded-md border border-dashed border-gray-300 dark:border-gray-700 text-sm aspect-video w-72"}[Right click here]
+:div{class="flex items-center justify-center rounded-md border border-dashed border-[--ui-border-accented] text-sm aspect-video w-72"}[Right click here]
 ::

 ## Examples
--- a/docs/content/3.components/drawer.md
+++ b/docs/content/3.components/drawer.md
@@ -21,14 +21,14 @@ prettier: true
 slots:
  default: |

-    <UButton label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />
+    <UButton label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />

  content: |

    <Placeholder class="h-48 m-4" />
 ---

-:u-button{label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}
+:u-button{label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}

 #content
 :placeholder{class="h-48 m-4"}
@@ -48,14 +48,14 @@ props:
 slots:
  default: |

-    <UButton label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />
+    <UButton label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />

  body: |

    <Placeholder class="h-48" />
 ---

-:u-button{label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}
+:u-button{label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}

 #body
 :placeholder{class="h-48"}
@@ -76,14 +76,14 @@ props:
 slots:
  default: |

-    <UButton label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />
+    <UButton label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />

  body: |

    <Placeholder class="h-48" />
 ---

-:u-button{label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}
+:u-button{label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}

 #body
 :placeholder{class="h-48"}
@@ -105,14 +105,14 @@ props:
 slots:
  default: |

-    <UButton label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />
+    <UButton label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />

  content: |

    <Placeholder class="h-96 m-4" />
 ---

-:u-button{label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}
+:u-button{label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}

 #content
 :placeholder{class="h-96 m-4"}
@@ -130,14 +130,14 @@ props:
 slots:
  default: |

-    <UButton label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />
+    <UButton label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />

  content: |

    <Placeholder class="w-96 m-4" />
 ---

-:u-button{label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}
+:u-button{label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}

 #content
 :placeholder{class="w-96 m-4"}
@@ -155,14 +155,14 @@ props:
 slots:
  default: |

-    <UButton label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />
+    <UButton label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />

  content: |

    <Placeholder class="h-48 m-4" />
 ---

-:u-button{label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}
+:u-button{label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}

 #content
 :placeholder{class="h-48 m-4"}
@@ -180,14 +180,14 @@ props:
 slots:
  default: |

-    <UButton label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />
+    <UButton label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />

  content: |

    <Placeholder class="h-48 m-4" />
 ---

-:u-button{label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}
+:u-button{label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}

 #content
 :placeholder{class="h-48 m-4"}
@@ -205,26 +205,26 @@ props:
 slots:
  default: |

-    <UButton label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />
+    <UButton label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid" />

  content: |

    <Placeholder class="h-48 m-4" />
 ---

-:u-button{label="Open" color="gray" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}
+:u-button{label="Open" color="neutral" variant="subtle" trailing-icon="i-heroicons-chevron-up-20-solid"}

 #content
 :placeholder{class="h-screen m-4"}
 ::

-::important
+::warning
 Make sure to add the `vaul-drawer-wrapper` directive to a parent element of your app to make this work.

 ```vue [app.vue]
 <template>
  <UApp>
-    <div class="bg-white dark:bg-gray-900" vaul-drawer-wrapper>
+    <div class="bg-[--ui-bg]" vaul-drawer-wrapper>
      <NuxtLayout>
        <NuxtPage />
      </NuxtLayout>
@@ -238,7 +238,7 @@ export default defineNuxtConfig({
  app: {
    rootAttrs: {
      'vaul-drawer-wrapper': '',
-      'class': 'bg-white dark:bg-gray-900'
+      'class': 'bg-[--ui-bg]'
    }
  }
 })
--- a/docs/content/3.components/dropdown-menu.md
+++ b/docs/content/3.components/dropdown-menu.md
@@ -91,10 +91,10 @@ props:
 slots:
  default: |

-    <UButton icon="i-heroicons-bars-3" color="gray" variant="outline" />
+    <UButton icon="i-heroicons-bars-3" color="neutral" variant="outline" />
 ---

-:u-button{icon="i-heroicons-bars-3" color="gray" variant="outline"}
+:u-button{icon="i-heroicons-bars-3" color="neutral" variant="outline"}
 ::

 ::note
@@ -143,10 +143,10 @@ props:
 slots:
  default: |

-    <UButton label="Open" icon="i-heroicons-bars-3" color="gray" variant="outline" />
+    <UButton label="Open" icon="i-heroicons-bars-3" color="neutral" variant="outline" />
 ---

-:u-button{label="Open" icon="i-heroicons-bars-3" color="gray" variant="outline"}
+:u-button{label="Open" icon="i-heroicons-bars-3" color="neutral" variant="outline"}
 ::

 ### Arrow
@@ -175,10 +175,10 @@ props:
 slots:
  default: |

-    <UButton label="Open" icon="i-heroicons-bars-3" color="gray" variant="outline" />
+    <UButton label="Open" icon="i-heroicons-bars-3" color="neutral" variant="outline" />
 ---

-:u-button{label="Open" icon="i-heroicons-bars-3" color="gray" variant="outline"}
+:u-button{label="Open" icon="i-heroicons-bars-3" color="neutral" variant="outline"}
 ::

 ### Size
@@ -209,13 +209,13 @@ props:
 slots:
  default: |

-    <UButton size="xl" label="Open" icon="i-heroicons-bars-3" color="gray" variant="outline" />
+    <UButton size="xl" label="Open" icon="i-heroicons-bars-3" color="neutral" variant="outline" />
 ---

-:u-button{size="xl" label="Open" icon="i-heroicons-bars-3" color="gray" variant="outline"}
+:u-button{size="xl" label="Open" icon="i-heroicons-bars-3" color="neutral" variant="outline"}
 ::

-::caution
+::warning
 The `size` prop will not be proxied to the Button, you need to set it yourself.
 ::

@@ -248,10 +248,10 @@ props:
 slots:
  default: |

-    <UButton label="Open" icon="i-heroicons-bars-3" color="gray" variant="outline" />
+    <UButton label="Open" icon="i-heroicons-bars-3" color="neutral" variant="outline" />
 ---

-:u-button{label="Open" icon="i-heroicons-bars-3" color="gray" variant="outline"}
+:u-button{label="Open" icon="i-heroicons-bars-3" color="neutral" variant="outline"}
 ::

 ## Examples
--- a/docs/content/3.components/form-field.md
+++ b/docs/content/3.components/form-field.md
@@ -138,7 +138,7 @@ slots:
 :u-input{placeholder="Enter your email" class="w-full"}
 ::

-::tip{to="/getting-started/colors"}
+::tip{to="/getting-started/theme#colors"}
 This sets the `color` to `error` on the form control. You can change it globally in your `app.config.ts`.
 ::

--- a/Show More
+++ b/Show More