diff --git a/docs/content/docs/chat/bottom-tray.mdx b/docs/content/docs/chat/bottom-tray.mdx
index b096dbc2..7f5e3419 100644
--- a/docs/content/docs/chat/bottom-tray.mdx
+++ b/docs/content/docs/chat/bottom-tray.mdx
@@ -20,7 +20,7 @@ export function App() {
 }
 ```
 
-{/* add visual: gif showing the BottomTray widget in collapsed and expanded states */}
+![BottomTray widget in collapsed and expanded states](/docs/images/chat/bottom-tray.gif)
 
 ## Controlled open state
 
diff --git a/docs/content/docs/chat/copilot.mdx b/docs/content/docs/chat/copilot.mdx
index 93688f00..911e7a8f 100644
--- a/docs/content/docs/chat/copilot.mdx
+++ b/docs/content/docs/chat/copilot.mdx
@@ -20,7 +20,7 @@ export function App() {
 }
 ```
 
-{/* add visual: image showing the Copilot sidebar layout next to the main app content */}
+![Copilot sidebar layout example](/docs/images/chat/copilot.png)
 
 ## Common configuration
 
diff --git a/docs/content/docs/chat/fullscreen.mdx b/docs/content/docs/chat/fullscreen.mdx
index 01ba2488..9ea56ca8 100644
--- a/docs/content/docs/chat/fullscreen.mdx
+++ b/docs/content/docs/chat/fullscreen.mdx
@@ -19,7 +19,7 @@ export function App() {
 }
 ```
 
-{/* add visual: image showing the FullScreen layout with sidebar, thread list, and main conversation area */}
+![FullScreen layout example](/docs/images/chat/fullscreen.png)
 
 ## Common configuration
 
diff --git a/docs/content/docs/chat/genui.mdx b/docs/content/docs/chat/genui.mdx
index f5eb57ca..e4e173ef 100644
--- a/docs/content/docs/chat/genui.mdx
+++ b/docs/content/docs/chat/genui.mdx
@@ -64,7 +64,16 @@ In this setup:
 
 This is the minimal complete pattern for GenUI in a chat interface. For a non-chat renderer or custom layout, use `openuiLibrary` and `openuiPromptOptions` from the same import path.
 
-{/* add visual: image showing the difference between a plain text assistant response and a GenUI-rendered component response */}
+<div className="grid md:grid-cols-2 gap-6 my-6">
+  <div>
+    <p className="text-sm text-center font-medium mb-2">Plain text response</p>
+    ![Plain text response](/docs/images/chat/genui-text-response.png)
+  </div>
+  <div>
+    <p className="text-sm text-center font-medium mb-2">GenUI response</p>
+    ![GenUI rendered response](/docs/images/chat/genui-response.png)
+  </div>
+</div>
 
 ## Use your own library
 
diff --git a/docs/content/docs/chat/installation.mdx b/docs/content/docs/chat/installation.mdx
index 3fa87a66..0b49eaa8 100644
--- a/docs/content/docs/chat/installation.mdx
+++ b/docs/content/docs/chat/installation.mdx
@@ -76,7 +76,7 @@ export default function Page() {
 
 At this stage, the page should render the layout shell. It will not send working chat requests until you add a backend.
 
-{/* add visual: image showing the expected baseline render after styles are imported and a built-in layout is mounted */}
+![Expected baseline render after styles are imported](/docs/images/chat/fullscreen.png)
 
 ## Related guides
 
diff --git a/docs/content/docs/chat/theming.mdx b/docs/content/docs/chat/theming.mdx
index b490885e..945c060e 100644
--- a/docs/content/docs/chat/theming.mdx
+++ b/docs/content/docs/chat/theming.mdx
@@ -54,7 +54,16 @@ import { FullScreen } from "@openuidev/react-ui";
 
 `disableThemeProvider` only skips the wrapper. It does not remove any chat functionality.
 
-{/* add visual: image showing the default chat theme beside a custom dark theme override */}
+<div className="grid md:grid-cols-2 gap-6 my-6">
+  <div>
+    <p className="text-sm text-center font-medium mb-2">Light (default)</p>
+    ![FullScreen light theme](/docs/images/chat/fullscreen.png)
+  </div>
+  <div>
+    <p className="text-sm text-center font-medium mb-2">Dark</p>
+    ![FullScreen dark theme](/docs/images/chat/fullscreen-dark.png)
+  </div>
+</div>
 
 ## Related guides
 
diff --git a/docs/content/docs/chat/welcome.mdx b/docs/content/docs/chat/welcome.mdx
index 280bd355..ea6b7dc8 100644
--- a/docs/content/docs/chat/welcome.mdx
+++ b/docs/content/docs/chat/welcome.mdx
@@ -73,7 +73,16 @@ Use `variant="short"` for compact pill buttons or `variant="long"` for more desc
 />
 ```
 
-{/* add visual: image showing the empty state with a welcome message and both short and long conversation starter variants */}
+<div className="grid md:grid-cols-2 gap-6 my-6">
+  <div>
+    <p className="text-sm text-center font-medium mb-2">`"short"` variant</p>
+    ![Short conversation starters](/docs/images/chat/starters-short.png)
+  </div>
+  <div>
+    <p className="text-sm text-center font-medium mb-2">`"long"` variant</p>
+    ![Long conversation starters](/docs/images/chat/starters-long.png)
+  </div>
+</div>
 
 ## Related guides
 
diff --git a/docs/public/docs/images/chat/bottom-tray.gif b/docs/public/docs/images/chat/bottom-tray.gif
new file mode 100644
index 00000000..951c01e1
Binary files /dev/null and b/docs/public/docs/images/chat/bottom-tray.gif differ
diff --git a/docs/public/docs/images/chat/bottom-tray.png b/docs/public/docs/images/chat/bottom-tray.png
new file mode 100644
index 00000000..380ba596
Binary files /dev/null and b/docs/public/docs/images/chat/bottom-tray.png differ
diff --git a/docs/public/docs/images/chat/copilot.png b/docs/public/docs/images/chat/copilot.png
new file mode 100644
index 00000000..e3fa8d5e
Binary files /dev/null and b/docs/public/docs/images/chat/copilot.png differ
diff --git a/docs/public/docs/images/chat/fullscreen-dark.png b/docs/public/docs/images/chat/fullscreen-dark.png
new file mode 100644
index 00000000..d8c484aa
Binary files /dev/null and b/docs/public/docs/images/chat/fullscreen-dark.png differ
diff --git a/docs/public/docs/images/chat/fullscreen.png b/docs/public/docs/images/chat/fullscreen.png
new file mode 100644
index 00000000..70259d49
Binary files /dev/null and b/docs/public/docs/images/chat/fullscreen.png differ
diff --git a/docs/public/docs/images/chat/genui-response.png b/docs/public/docs/images/chat/genui-response.png
new file mode 100644
index 00000000..0cf39b97
Binary files /dev/null and b/docs/public/docs/images/chat/genui-response.png differ
diff --git a/docs/public/docs/images/chat/genui-text-response.png b/docs/public/docs/images/chat/genui-text-response.png
new file mode 100644
index 00000000..968dab7a
Binary files /dev/null and b/docs/public/docs/images/chat/genui-text-response.png differ
diff --git a/docs/public/docs/images/chat/starters-long.png b/docs/public/docs/images/chat/starters-long.png
new file mode 100644
index 00000000..844065da
Binary files /dev/null and b/docs/public/docs/images/chat/starters-long.png differ
diff --git a/docs/public/docs/images/chat/starters-short.png b/docs/public/docs/images/chat/starters-short.png
new file mode 100644
index 00000000..24b4a5f0
Binary files /dev/null and b/docs/public/docs/images/chat/starters-short.png differ