docs: migration guide

docs/content/1.getting-started/8.migration.md

@@ -0,0 +1,31 @@
+---
+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 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>`).
+
+### 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>
+  ```