diff --git a/packages/components/src/docs/Migration/ui-video.mdx b/packages/components/src/docs/Migration/ui-video.mdx
new file mode 100644
index 000000000..8bcba9e3f
--- /dev/null
+++ b/packages/components/src/docs/Migration/ui-video.mdx
@@ -0,0 +1,87 @@
+# Migration Guide: From `ui-video` to `sd-video`
+
+The new `sd-video` is designed to replace the `ui-video`. Instead of mainly providing content via attributes, the `sd-video` component uses slots to allow for more flexibility and customization.
+
+## 💾 Slots
+
+### ✨ New Slots
+
+#### [default]
+
+The default slot is used to pass a video player element.
+
+#### [play-icon]
+
+The slot for the video's play icon.
+
+#### [poster]
+
+Slot to specify an image to be shown before initial play of the wrapped video. This acts like the `poster` attribute on the native video tag.
+
+<hr />
+
+## ⚙️ Attributes
+
+### ✨ New Attributes
+
+#### [playing]
+
+Setting this to `true` will hide the play icon and the overlay.
+
+#### [isBelowBreakpoint]
+
+Used to set a reactive property to trigger breakpoint re-renders.
+
+### ❌ Removed Attributes
+
+The following attributes have been removed from the new sd-video component:
+
+1. [videoId]
+2. [copyrightText]
+3. [looped]
+4. [muted]
+5. [src]
+6. [errorText]
+7. [contain]
+
+<hr />
+
+## 🥳 Events
+
+### 🔄 Updated Events
+
+#### [sd-play]
+
+Renamed from `uiVideoPlay` to `sd-play`.
+
+### ❌ Removed Events:
+
+The following events have been removed from the new sd-video component:
+
+1. [uiVideoPause]
+2. [uiVideoError]
+
+<hr />
+
+## 🦻 Event Listeners
+
+### ❌ Removed Event Listeners:
+
+The following event listeners have been removed from the new sd-video component:
+
+1. [message]
+2. [uiVideoIframeMessage]
+3. [uiSliderSlideChange]
+
+<hr />
+
+## 🧪 Methods
+
+### ❌ Removed Methods:
+
+The following methods have been removed from the new sd-video component:
+
+1. [playPause]
+2. [errorPlayVideo]
+
+<hr />