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..6c271b48ec
--- /dev/null
+++ b/docs/content/1.getting-started/8.migration.md
@@ -0,0 +1,95 @@
+---
+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.
+
+
+### 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:
+
+1. `UDivider` was renamed to `USeparator`.
+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:
+
+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
+   - <UVerticalNavigation :links="links" />
+   - <UHorizontalNavigation :links="links" />
+
+   // 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).
+
+  ```diff
+  - <UButton color="red">
+  + <UButton color="error">
+      Label
+    </UButton>
+  ```
+