From 8317533ea978b00b86f9e633c108a614f4f24164 Mon Sep 17 00:00:00 2001
From: Antony Bouyon <antony.bouyon@believe.com>
Date: Wed, 21 Jan 2026 13:49:16 +0100
Subject: [PATCH] fix: improve useMediaQuery examples

Signed-off-by: Antony Bouyon <antony.bouyon@believe.com>
---
 .../app/hooks/use-media-query/components.tsx  | 15 +++++------
 .../src/app/hooks/use-media-query/example.css | 25 +++++++++++++++++++
 .../src/app/hooks/use-media-query/snippets.ts | 23 +++++++++--------
 docs-ui/src/app/hooks/use-styles/page.mdx     |  7 ++++--
 4 files changed, 50 insertions(+), 20 deletions(-)
 create mode 100644 docs-ui/src/app/hooks/use-media-query/example.css

diff --git a/docs-ui/src/app/hooks/use-media-query/components.tsx b/docs-ui/src/app/hooks/use-media-query/components.tsx
index 0d8edd944b..1ebcd64dfa 100644
--- a/docs-ui/src/app/hooks/use-media-query/components.tsx
+++ b/docs-ui/src/app/hooks/use-media-query/components.tsx
@@ -1,13 +1,12 @@
 'use client';
 import { useMediaQuery } from '@backstage/ui/src/hooks/useMediaQuery';
+import './example.css';
 
 export function UseMediaQueryThemeExample() {
   const isDarkMode = useMediaQuery('(prefers-color-scheme: dark)');
 
   return (
-    <div>
-      {isDarkMode ? 'User prefers Dark mode' : 'User prefers Light mode'}
-    </div>
+    <p>{isDarkMode ? 'User prefers Dark mode' : 'User prefers Light mode'}</p>
   );
 }
 
@@ -17,11 +16,11 @@ export function UseMediaQueryResponsiveExample() {
   const isDesktop = useMediaQuery('(min-width: 1025px)');
 
   return (
-    <div>
+    <p>
       {isMobile && '<MobileLayout />'}
       {isTablet && '<TabletLayout />'}
       {isDesktop && '<DesktopLayout />'}
-    </div>
+    </p>
   );
 }
 
@@ -31,12 +30,14 @@ export function UseMediaQueryPreferencesExample() {
   );
 
   return (
-    <div className={prefersReducedMotion ? 'no-animations' : ''}>Content</div>
+    <p className={prefersReducedMotion ? 'no-animations' : 'animated-border'}>
+      Content
+    </p>
   );
 }
 
 export function UseMediaQueryOrientationExample() {
   const isPortrait = useMediaQuery('(orientation: portrait)');
 
-  return <div>{isPortrait ? 'Portrait mode' : 'Landscape mode'}</div>;
+  return <p>{isPortrait ? 'Portrait mode' : 'Landscape mode'}</p>;
 }
diff --git a/docs-ui/src/app/hooks/use-media-query/example.css b/docs-ui/src/app/hooks/use-media-query/example.css
new file mode 100644
index 0000000000..5fb132f9f4
--- /dev/null
+++ b/docs-ui/src/app/hooks/use-media-query/example.css
@@ -0,0 +1,25 @@
+@keyframes borderSlide {
+  0%,
+  100% {
+    transform: translateX(-90%);
+  }
+  50% {
+    transform: translateX(190%);
+  }
+}
+
+.animated-border {
+  position: relative;
+  overflow: hidden;
+}
+
+.animated-border::after {
+  content: '';
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  width: 50%;
+  height: 2px;
+  background-color: currentColor;
+  animation: borderSlide 5s ease-in-out infinite;
+}
diff --git a/docs-ui/src/app/hooks/use-media-query/snippets.ts b/docs-ui/src/app/hooks/use-media-query/snippets.ts
index 78423ef516..157da945f0 100644
--- a/docs-ui/src/app/hooks/use-media-query/snippets.ts
+++ b/docs-ui/src/app/hooks/use-media-query/snippets.ts
@@ -4,9 +4,12 @@ function MyComponent() {
   const isDarkMode = useMediaQuery('(prefers-color-scheme: dark)');
 
   return (
-    <div>
-      {isDarkMode ? 'Dark mode enabled' : 'Light mode enabled'}
-    </div>
+    <p>
+      {isDarkMode
+        ? 'User prefers Dark mode'
+        : 'User prefers Light mode'
+      }
+    </p>
   );
 }`;
 
@@ -18,11 +21,11 @@ function ResponsiveLayout() {
   const isDesktop = useMediaQuery('(min-width: 1025px)');
 
   return (
-    <div>
+    <p>
       {isMobile && <MobileLayout />}
       {isTablet && <TabletLayout />}
       {isDesktop && <DesktopLayout />}
-    </div>
+    </p>
   );
 }`;
 
@@ -32,11 +35,9 @@ function AccessibleComponent() {
   const prefersReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
 
   return (
-    <div
-      className={prefersReducedMotion ? 'no-animations' : ''}
-    >
+    <p className={prefersReducedMotion ? 'no-animations' : 'animated-border'}>
       Content
-    </div>
+    </p>
   );
 }`;
 
@@ -46,8 +47,8 @@ function OrientationAware() {
   const isPortrait = useMediaQuery('(orientation: portrait)');
 
   return (
-    <div>
+    <p>
       {isPortrait ? 'Portrait mode' : 'Landscape mode'}
-    </div>
+    </p>
   );
 }`;
diff --git a/docs-ui/src/app/hooks/use-styles/page.mdx b/docs-ui/src/app/hooks/use-styles/page.mdx
index ca235c4778..080a283dcc 100644
--- a/docs-ui/src/app/hooks/use-styles/page.mdx
+++ b/docs-ui/src/app/hooks/use-styles/page.mdx
@@ -33,6 +33,7 @@ The `useStyles` hook is the core styling utility that processes component defini
 <CodeBlock code={useStylesUsageSnippet} />
 
 ## Parameters
+
 <PropsTable data={useStylesPropsDefs} isHook />
 
 ## Return Value
@@ -47,7 +48,10 @@ A component definition describes how a component should be styled:
 
 <CodeBlock code={useStylesDefsSnippet} />
 
-<Banner variant="info" text="The data-attributes definition should be kebab-case instead of camelCase." />
+<Banner
+  variant="info"
+  text="The data-attributes definition should be kebab-case instead of camelCase."
+/>
 
 ### Data Attributes
 
@@ -55,5 +59,4 @@ Data attributes enable state-based styling through CSS selectors. The hook autom
 
 <CodeBlock code={useStylesAttributesSnippet} />
 
-
 <ChangelogComponent component="use-styles" />