From 18d0265c08bfcb537a6c0db757c0327602db06b4 Mon Sep 17 00:00:00 2001
From: Michael Brevard <yonshi29@gmail.com>
Date: Tue, 10 Dec 2024 11:35:38 +0200
Subject: [PATCH 01/14] docs: migration guide

---
 docs/content/1.getting-started/8.migration.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
 create mode 100644 docs/content/1.getting-started/8.migration.md

diff --git a/docs/content/1.getting-started/8.migration.md b/docs/content/1.getting-started/8.migration.md
new file mode 100644
index 0000000000..052cc699fa
--- /dev/null
+++ b/docs/content/1.getting-started/8.migration.md
@@ -0,0 +1,15 @@
+---
+title: Migration
+description: 'Migration guide from Nuxt UI v2.x to Nuxt UI v3.x'
+---
+
+Nuxt UI v3 has had many changes from Nuxt UI v2. While most of the functionality was kept, some breaking changes are inevitable in a major release.
+
+Below is a comprehensive migration guide to help you transition to Nuxt UI v3 quickly and efficiently.
+
+### Renamed components
+The following changes require you to simply change the name in the project. No further modification are needed:
+
+1. `UDivider` was renamed to `USeparator`
+2. `UDropdown` was renamed to `UDropdownMenu`
+3. The panel slot in `UPopup` (`<template #panel>`) was renamed to `content` (`<template #content>`)

From 3f00ef3b37ea35d1ae409432ef23bd5324a619f8 Mon Sep 17 00:00:00 2001
From: Michael Brevard <yonshi29@gmail.com>
Date: Tue, 10 Dec 2024 11:42:08 +0200
Subject: [PATCH 02/14] wip: add functional avatar change

---
 docs/content/1.getting-started/8.migration.md | 24 +++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/docs/content/1.getting-started/8.migration.md b/docs/content/1.getting-started/8.migration.md
index 052cc699fa..9462baea26 100644
--- a/docs/content/1.getting-started/8.migration.md
+++ b/docs/content/1.getting-started/8.migration.md
@@ -8,8 +8,24 @@ Nuxt UI v3 has had many changes from Nuxt UI v2. While most of the functionality
 Below is a comprehensive migration guide to help you transition to Nuxt UI v3 quickly and efficiently.
 
 ### Renamed components
-The following changes require you to simply change the name in the project. No further modification are needed:
+The following changes require you to simply change the names in your projects. No further modifications are needed:
 
-1. `UDivider` was renamed to `USeparator`
-2. `UDropdown` was renamed to `UDropdownMenu`
-3. The panel slot in `UPopup` (`<template #panel>`) was renamed to `content` (`<template #content>`)
+1. `UDivider` was renamed to `USeparator`.
+2. `UDropdown` was renamed to `UDropdownMenu`.
+3. The panel slot in `UPopup` (`<template #panel>`) was renamed to `content` (`<template #content>`).
+
+### Changed components
+The following changes require you to change some functionality in the projects:
+
+1. `UAvatar` can no longer be the trigger in `UDropdownMenu`. You can use a `UButton` with the `avatar` prop in stead:
+   ```diff
+   // v2
+   <UDropdown>
+   - <UAvatar :src="profilePicture"/>
+   </UDropdown>
+
+   // v3
+   <UDropdownMenu>
+   + <UButton :avatar="{src: profilePicture}" />
+   </UDropdownMenu>
+  ```

From 6b760b6c4967b49e4bd898428a92477fe8d53a29 Mon Sep 17 00:00:00 2001
From: Michael Brevard <yonshi29@gmail.com>
Date: Tue, 10 Dec 2024 15:22:23 +0200
Subject: [PATCH 03/14] wip: add form group change and remove avatar change

---
 docs/content/1.getting-started/8.migration.md | 17 +++--------------
 1 file changed, 3 insertions(+), 14 deletions(-)

diff --git a/docs/content/1.getting-started/8.migration.md b/docs/content/1.getting-started/8.migration.md
index 9462baea26..fa8349aa08 100644
--- a/docs/content/1.getting-started/8.migration.md
+++ b/docs/content/1.getting-started/8.migration.md
@@ -12,20 +12,9 @@ The following changes require you to simply change the names in your projects. N
 
 1. `UDivider` was renamed to `USeparator`.
 2. `UDropdown` was renamed to `UDropdownMenu`.
-3. The panel slot in `UPopup` (`<template #panel>`) was renamed to `content` (`<template #content>`).
+3. The panel slot in `UPopover` (`<template #panel>`) was renamed to `content` (`<template #content>`).
+4. `UFormGroup` was renamed to `UFormField`.
 
 ### Changed components
 The following changes require you to change some functionality in the projects:
-
-1. `UAvatar` can no longer be the trigger in `UDropdownMenu`. You can use a `UButton` with the `avatar` prop in stead:
-   ```diff
-   // v2
-   <UDropdown>
-   - <UAvatar :src="profilePicture"/>
-   </UDropdown>
-
-   // v3
-   <UDropdownMenu>
-   + <UButton :avatar="{src: profilePicture}" />
-   </UDropdownMenu>
-  ```
+// W.I.P

From f9a47ea4d7dbad44d6490b1dee7fdf06d4747996 Mon Sep 17 00:00:00 2001
From: Michael Brevard <yonshi29@gmail.com>
Date: Tue, 10 Dec 2024 15:35:43 +0200
Subject: [PATCH 04/14] wip: add all changes from v3 issue

---
 docs/content/1.getting-started/8.migration.md | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/docs/content/1.getting-started/8.migration.md b/docs/content/1.getting-started/8.migration.md
index fa8349aa08..54469d4562 100644
--- a/docs/content/1.getting-started/8.migration.md
+++ b/docs/content/1.getting-started/8.migration.md
@@ -14,7 +14,19 @@ The following changes require you to simply change the names in your projects. N
 2. `UDropdown` was renamed to `UDropdownMenu`.
 3. The panel slot in `UPopover` (`<template #panel>`) was renamed to `content` (`<template #content>`).
 4. `UFormGroup` was renamed to `UFormField`.
+5. `URange` was renamed to `USlider`.
+6. `UToggle` was renamed to `USwitch`.
+7. `UNotification` was renamed to `UToast`
 
 ### Changed components
 The following changes require you to change some functionality in the projects:
-// W.I.P
+
+1. `UVerticalNavigation`/`UHorizontalNavigation` have been unified under `UNavigationMenu`, and their `links` prop was renamed to `items`:
+
+   ```diff
+   // v2
+   - <UVerticalNavigation :links="links" />
+
+   // v3
+   + <UNavigationMenu orientation="vertical" :items="links" />
+  ```

From 7ccca37aea1f756c8286f87af48dbeb8e2d4b0de Mon Sep 17 00:00:00 2001
From: Michael Brevard <yonshi29@gmail.com>
Date: Tue, 10 Dec 2024 15:36:56 +0200
Subject: [PATCH 05/14] wip: add horizontal navigation example

---
 docs/content/1.getting-started/8.migration.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/content/1.getting-started/8.migration.md b/docs/content/1.getting-started/8.migration.md
index 54469d4562..ca84245971 100644
--- a/docs/content/1.getting-started/8.migration.md
+++ b/docs/content/1.getting-started/8.migration.md
@@ -26,7 +26,9 @@ The following changes require you to change some functionality in the projects:
    ```diff
    // v2
    - <UVerticalNavigation :links="links" />
+   - <UHorizontalNavigation :links="links" />
 
    // v3
    + <UNavigationMenu orientation="vertical" :items="links" />
+   + <UNavigationMenu orientation="horizontal" :items="links" />
   ```

From 0d94a89237063bb6813c9864c6c07c014d7f1e78 Mon Sep 17 00:00:00 2001
From: Michael Brevard <yonshi29@gmail.com>
Date: Thu, 9 Jan 2025 11:06:19 +0200
Subject: [PATCH 06/14] docs: add color list migration

---
 docs/content/1.getting-started/8.migration.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/docs/content/1.getting-started/8.migration.md b/docs/content/1.getting-started/8.migration.md
index ca84245971..f759158478 100644
--- a/docs/content/1.getting-started/8.migration.md
+++ b/docs/content/1.getting-started/8.migration.md
@@ -32,3 +32,12 @@ The following changes require you to change some functionality in the projects:
    + <UNavigationMenu orientation="vertical" :items="links" />
    + <UNavigationMenu orientation="horizontal" :items="links" />
   ```
+
+2. The `color` prop in all components no longer accepts the list of defined TailwindCSS colors. It now only accepts one of the colors defined in [the theme](/getting-started/theme#colors).
+
+  ```diff
+  - <UButton color="red">
+  + <UButton color="error">
+      Label
+    </UButton
+  ```

From 3f8daeba8853b30c56e9cfa9a74a1b3836f8403a Mon Sep 17 00:00:00 2001
From: Michael Brevard <yonshi29@gmail.com>
Date: Thu, 9 Jan 2025 11:07:12 +0200
Subject: [PATCH 07/14] chore: fix spacing

---
 docs/content/1.getting-started/8.migration.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/content/1.getting-started/8.migration.md b/docs/content/1.getting-started/8.migration.md
index f759158478..5727a542fd 100644
--- a/docs/content/1.getting-started/8.migration.md
+++ b/docs/content/1.getting-started/8.migration.md
@@ -31,7 +31,7 @@ The following changes require you to change some functionality in the projects:
    // v3
    + <UNavigationMenu orientation="vertical" :items="links" />
    + <UNavigationMenu orientation="horizontal" :items="links" />
-  ```
+   ```
 
 2. The `color` prop in all components no longer accepts the list of defined TailwindCSS colors. It now only accepts one of the colors defined in [the theme](/getting-started/theme#colors).
 

From d056e51a1c64adc0b06a6af878e67e5c2f870138 Mon Sep 17 00:00:00 2001
From: Michael Brevard <yonshi29@gmail.com>
Date: Thu, 9 Jan 2025 11:07:36 +0200
Subject: [PATCH 08/14] chore: add closing triangle parenthesis

---
 docs/content/1.getting-started/8.migration.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/content/1.getting-started/8.migration.md b/docs/content/1.getting-started/8.migration.md
index 5727a542fd..e2655cab18 100644
--- a/docs/content/1.getting-started/8.migration.md
+++ b/docs/content/1.getting-started/8.migration.md
@@ -39,5 +39,5 @@ The following changes require you to change some functionality in the projects:
   - <UButton color="red">
   + <UButton color="error">
       Label
-    </UButton
+    </UButton>
   ```

From 5473501a4d9ea58722f928c81376ef54e544b616 Mon Sep 17 00:00:00 2001
From: Michael Brevard <yonshi29@gmail.com>
Date: Tue, 14 Jan 2025 16:05:32 +0200
Subject: [PATCH 09/14] docs: add tailwind v4 beta and beginning of app.config
 changes

---
 docs/content/1.getting-started/8.migration.md | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/docs/content/1.getting-started/8.migration.md b/docs/content/1.getting-started/8.migration.md
index e2655cab18..f9c7715988 100644
--- a/docs/content/1.getting-started/8.migration.md
+++ b/docs/content/1.getting-started/8.migration.md
@@ -7,6 +7,10 @@ Nuxt UI v3 has had many changes from Nuxt UI v2. While most of the functionality
 
 Below is a comprehensive migration guide to help you transition to Nuxt UI v3 quickly and efficiently.
 
+
+### TailwindCSS changes
+Since Nuxt UI relies on Tailwind CSS under-the-hood, all migration changes necessary in TailwindCSS also apply to Nuxt UI. To migrate your Tailwind configuration, including custom theme and utility usage, please follow [TailwindCSS's migration guide](https://tailwindcss.com/docs/v4-beta).
+
 ### Renamed components
 The following changes require you to simply change the names in your projects. No further modifications are needed:
 
@@ -41,3 +45,20 @@ The following changes require you to change some functionality in the projects:
       Label
     </UButton>
   ```
+
+### Changed configuration
+The following changes require you to change some configuration in `app.config.ts`:
+
+1. The color configuration has been moved into the `colors` object. The `gray` configuration has been renamed to `neutral` to follow the [new theme structure](/getting-started/theme#colors)
+  ```diff
+  export default defineAppConfig({
+	  ui: {
+  -   primary: 'green',
+  -   gray: 'cool'
+  +   colors: {
+  +     primary: 'green',
+  +     neutral: 'slate'
+  +   }
+    }
+  })
+  ```

From 9393f28655228cc3df08c12202beec8897f3d833 Mon Sep 17 00:00:00 2001
From: Michael Brevard <yonshi29@gmail.com>
Date: Tue, 14 Jan 2025 16:11:12 +0200
Subject: [PATCH 10/14] chore: better wording

---
 docs/content/1.getting-started/8.migration.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/content/1.getting-started/8.migration.md b/docs/content/1.getting-started/8.migration.md
index f9c7715988..d78efbebf4 100644
--- a/docs/content/1.getting-started/8.migration.md
+++ b/docs/content/1.getting-started/8.migration.md
@@ -9,7 +9,7 @@ Below is a comprehensive migration guide to help you transition to Nuxt UI v3 qu
 
 
 ### TailwindCSS changes
-Since Nuxt UI relies on Tailwind CSS under-the-hood, all migration changes necessary in TailwindCSS also apply to Nuxt UI. To migrate your Tailwind configuration, including custom theme and utility usage, please follow [TailwindCSS's migration guide](https://tailwindcss.com/docs/v4-beta).
+Since Nuxt UI relies on TailwindCSS under-the-hood, the migration required for TailwindCSS also affects Nuxt UI. To migrate your Tailwind configuration, including your custom theme and utility usage, please follow [TailwindCSS's migration guide](https://tailwindcss.com/docs/v4-beta).
 
 ### Renamed components
 The following changes require you to simply change the names in your projects. No further modifications are needed:

From 14a6fbcbfc41373ef13a0faded0deb47dcffabbf Mon Sep 17 00:00:00 2001
From: Michael Brevard <yonshi29@gmail.com>
Date: Tue, 14 Jan 2025 16:26:32 +0200
Subject: [PATCH 11/14] docs: add color alias change

---
 docs/content/1.getting-started/8.migration.md | 23 ++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/docs/content/1.getting-started/8.migration.md b/docs/content/1.getting-started/8.migration.md
index d78efbebf4..53a440487d 100644
--- a/docs/content/1.getting-started/8.migration.md
+++ b/docs/content/1.getting-started/8.migration.md
@@ -25,7 +25,7 @@ The following changes require you to simply change the names in your projects. N
 ### Changed components
 The following changes require you to change some functionality in the projects:
 
-1. `UVerticalNavigation`/`UHorizontalNavigation` have been unified under `UNavigationMenu`, and their `links` prop was renamed to `items`:
+1. `UVerticalNavigation`/`UHorizontalNavigation` have been unified under `UNavigationMenu`, and their `links` prop was renamed to `items`. You can control their direction using the `orientation` prop:
 
    ```diff
    // v2
@@ -47,9 +47,9 @@ The following changes require you to change some functionality in the projects:
   ```
 
 ### Changed configuration
-The following changes require you to change some configuration in `app.config.ts`:
+The following changes require you to change some configuration in `app.config.ts` or throughout your app:
 
-1. The color configuration has been moved into the `colors` object. The `gray` configuration has been renamed to `neutral` to follow the [new theme structure](/getting-started/theme#colors)
+1. The color configuration in `app.config.ts` has been moved into the `colors` object. The `gray` configuration has been renamed to `neutral` to follow the [new theme structure](/getting-started/theme#colors)
   ```diff
   export default defineAppConfig({
 	  ui: {
@@ -62,3 +62,20 @@ The following changes require you to change some configuration in `app.config.ts
     }
   })
   ```
+
+2. The color alias system in Nuxt UI v3 has been changed, and no longer generates by default like in Nuxt UI v2. That means, you won't have `text-primary` by default, as this can conflict with and override user-defined CSS. In order to be able to use them, you may generate them directly in your `@theme`:
+  ```diff
+  // This example demonstrates the app.vue file for simplicity purposes. However, the template can be present in any one of your pages, layouts, or components.
+  <template>
+    <div class="text-primary">
+      This uses the dynamic primary color that updates based on color scheme!
+    </div>
+  </template>
+  +<style>
+  +@import "tailwindcss";
+  +@import "@nuxt/ui";
+  +@theme {
+  +  --color-primary: var(--ui-primary);
+  +}
+  ```
+  

From c3b902e5f30d28cf43780fd4adb358f2b5a336cf Mon Sep 17 00:00:00 2001
From: Michael Brevard <yonshi29@gmail.com>
Date: Tue, 14 Jan 2025 16:37:24 +0200
Subject: [PATCH 12/14] docs: better wording for color alias change

---
 docs/content/1.getting-started/8.migration.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/content/1.getting-started/8.migration.md b/docs/content/1.getting-started/8.migration.md
index 53a440487d..c32c262fb4 100644
--- a/docs/content/1.getting-started/8.migration.md
+++ b/docs/content/1.getting-started/8.migration.md
@@ -63,7 +63,7 @@ The following changes require you to change some configuration in `app.config.ts
   })
   ```
 
-2. The color alias system in Nuxt UI v3 has been changed, and no longer generates by default like in Nuxt UI v2. That means, you won't have `text-primary` by default, as this can conflict with and override user-defined CSS. In order to be able to use them, you may generate them directly in your `@theme`:
+2. The color alias system in Nuxt UI v3 has been changed, and no longer generates by default like in Nuxt UI v2, as this can conflict with and override user-defined CSS. That means, you won't have utilities like `text-primary`, `bg-primary-400`, `focus-visible:ring-primary-700`, etc, by default. In order to be able to use them, you can generate them directly in your `@theme`:
   ```diff
   // This example demonstrates the app.vue file for simplicity purposes. However, the template can be present in any one of your pages, layouts, or components.
   <template>

From 79d5fc3a1a0055c4ba23dccca448476229ca1318 Mon Sep 17 00:00:00 2001
From: Michael Brevard <yonshi29@gmail.com>
Date: Tue, 14 Jan 2025 16:48:51 +0200
Subject: [PATCH 13/14] chore: reorder changes based on chronological order,
 add usage change

---
 docs/content/1.getting-started/8.migration.md | 80 +++++++++++--------
 1 file changed, 47 insertions(+), 33 deletions(-)

diff --git a/docs/content/1.getting-started/8.migration.md b/docs/content/1.getting-started/8.migration.md
index c32c262fb4..71e7d257f1 100644
--- a/docs/content/1.getting-started/8.migration.md
+++ b/docs/content/1.getting-started/8.migration.md
@@ -11,6 +11,53 @@ Below is a comprehensive migration guide to help you transition to Nuxt UI v3 qu
 ### TailwindCSS changes
 Since Nuxt UI relies on TailwindCSS under-the-hood, the migration required for TailwindCSS also affects Nuxt UI. To migrate your Tailwind configuration, including your custom theme and utility usage, please follow [TailwindCSS's migration guide](https://tailwindcss.com/docs/v4-beta).
 
+### Changed configuration
+The following changes require you to change some configuration in `app.config.ts` or throughout your app:
+
+1. The color configuration in `app.config.ts` has been moved into the `colors` object. The `gray` configuration has been renamed to `neutral` to follow the [new theme structure](/getting-started/theme#colors)
+  ```diff
+  export default defineAppConfig({
+	  ui: {
+  -   primary: 'green',
+  -   gray: 'cool'
+  +   colors: {
+  +     primary: 'green',
+  +     neutral: 'slate'
+  +   }
+    }
+  })
+  ```
+2. In order to use Nuxt UI v3, import TailwindCSS followed by Nuxt UI in your `app.vue` style or in your main CSS file that you'll reference in the `css` array of your `nuxt.config.ts`:
+   ```vue [app.vue]
+   <template>
+      <div>
+        <NuxtPage />
+      </div>
+   </template>
+   <style>
+   +@import "tailwindcss";
+   +@import "@nuxt/ui";
+   </style>
+   ```
+   ::note{to="/components/app"} The you can alternatively wrap your app with the `UApp` component, which provides global configurations and is required for **Toast** and **Tooltip** components to work.
+   ::
+
+4. The color alias system in Nuxt UI v3 has been changed, and no longer generates by default like in Nuxt UI v2, as this can conflict with and override user-defined CSS. That means, you won't have utilities like `text-primary`, `bg-primary-400`, `focus-visible:ring-primary-700`, etc, by default. In order to be able to use them, you can generate them directly in your `@theme`:
+  ```diff
+  // This example demonstrates the app.vue file for simplicity purposes. However, the template can be present in any one of your pages, layouts, or components.
+  <template>
+    <div class="text-primary">
+      This uses the dynamic primary color that updates based on color scheme!
+    </div>
+  </template>
+  +<style>
+  +@import "tailwindcss";
+  +@import "@nuxt/ui";
+  +@theme {
+  +  --color-primary: var(--ui-primary);
+  +}
+  ```
+
 ### Renamed components
 The following changes require you to simply change the names in your projects. No further modifications are needed:
 
@@ -45,37 +92,4 @@ The following changes require you to change some functionality in the projects:
       Label
     </UButton>
   ```
-
-### Changed configuration
-The following changes require you to change some configuration in `app.config.ts` or throughout your app:
-
-1. The color configuration in `app.config.ts` has been moved into the `colors` object. The `gray` configuration has been renamed to `neutral` to follow the [new theme structure](/getting-started/theme#colors)
-  ```diff
-  export default defineAppConfig({
-	  ui: {
-  -   primary: 'green',
-  -   gray: 'cool'
-  +   colors: {
-  +     primary: 'green',
-  +     neutral: 'slate'
-  +   }
-    }
-  })
-  ```
-
-2. The color alias system in Nuxt UI v3 has been changed, and no longer generates by default like in Nuxt UI v2, as this can conflict with and override user-defined CSS. That means, you won't have utilities like `text-primary`, `bg-primary-400`, `focus-visible:ring-primary-700`, etc, by default. In order to be able to use them, you can generate them directly in your `@theme`:
-  ```diff
-  // This example demonstrates the app.vue file for simplicity purposes. However, the template can be present in any one of your pages, layouts, or components.
-  <template>
-    <div class="text-primary">
-      This uses the dynamic primary color that updates based on color scheme!
-    </div>
-  </template>
-  +<style>
-  +@import "tailwindcss";
-  +@import "@nuxt/ui";
-  +@theme {
-  +  --color-primary: var(--ui-primary);
-  +}
-  ```
   

From 1d8db1cbebacffc87931a3ea1afc1904e1e54e09 Mon Sep 17 00:00:00 2001
From: Michael Brevard <yonshi29@gmail.com>
Date: Tue, 14 Jan 2025 16:49:37 +0200
Subject: [PATCH 14/14] chore: remove plus signs

---
 docs/content/1.getting-started/8.migration.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/content/1.getting-started/8.migration.md b/docs/content/1.getting-started/8.migration.md
index 71e7d257f1..6c271b48ec 100644
--- a/docs/content/1.getting-started/8.migration.md
+++ b/docs/content/1.getting-started/8.migration.md
@@ -35,8 +35,8 @@ The following changes require you to change some configuration in `app.config.ts
       </div>
    </template>
    <style>
-   +@import "tailwindcss";
-   +@import "@nuxt/ui";
+   @import "tailwindcss";
+   @import "@nuxt/ui";
    </style>
    ```
    ::note{to="/components/app"} The you can alternatively wrap your app with the `UApp` component, which provides global configurations and is required for **Toast** and **Tooltip** components to work.