From b650fe2cc3370a9daad5424d1dc2237f0f355151 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 21 May 2026 12:47:46 +0200
Subject: [PATCH 01/33] Match docs content width to homepage

---
 docs/src/app/(docs)/layout.css | 15 +++++++--------
 docs/src/css/index.css         |  5 -----
 2 files changed, 7 insertions(+), 13 deletions(-)

diff --git a/docs/src/app/(docs)/layout.css b/docs/src/app/(docs)/layout.css
index 2f4f615366c..9e6f6baa975 100644
--- a/docs/src/app/(docs)/layout.css
+++ b/docs/src/app/(docs)/layout.css
@@ -14,14 +14,15 @@
 
 @layer components {
   .RootLayout {
+    --main-content-width: 44.75rem;
+    --sidebar-width: 17.5rem;
+
     z-index: 0;
     position: relative;
-
-    --root-layout-padding-x: 0rem;
-    padding-inline: var(--root-layout-padding-x);
+    padding-inline: 0;
 
     @media (--show-side-nav) {
-      --root-layout-padding-x: 3rem;
+      padding-inline: 3rem;
 
       &::before,
       &::after {
@@ -52,7 +53,7 @@
     flex-direction: column;
     margin-inline: auto;
     min-height: 100dvh;
-    max-width: calc(var(--breakpoint-max-layout-width) - var(--root-layout-padding-x) * 2);
+    max-width: calc(var(--sidebar-width) + var(--main-content-width) + var(--sidebar-width));
 
     @media (--show-side-nav) {
       padding-block: var(--header-height);
@@ -101,8 +102,6 @@
   }
 
   .ContentLayoutRoot {
-    --sidebar-width: 17.5rem;
-
     display: grid;
     align-items: start;
     padding-top: var(--header-height);
@@ -126,7 +125,7 @@
 
   .ContentLayoutMain {
     min-width: 0;
-    max-width: 48rem;
+    max-width: var(--main-content-width);
     width: 100%;
 
     margin: 0 auto;
diff --git a/docs/src/css/index.css b/docs/src/css/index.css
index d4fc926bbce..316d2a70784 100644
--- a/docs/src/css/index.css
+++ b/docs/src/css/index.css
@@ -228,9 +228,6 @@
       0 10px 32px var(--blackA-5), 0 1px 1px var(--blackA-1), 0 4px 6px var(--blackA-2),
       0 1px 1px var(--blackA-2), 0 24px 68px var(--blackA-4);
 
-    /* Breakpoints (use custom-media.css where possible) */
-    --breakpoint-max-layout-width: 89rem; /* 1424px - this is a 1440px device minus 16px scrollbar */
-
     --ease-out-fast: cubic-bezier(0.45, 1.005, 0, 1.005);
     --ease-in-slow: cubic-bezier(0.375, 0.015, 0.545, 0.455);
     --header-height: 3rem;
@@ -389,8 +386,6 @@
     --ease-out-fast: initial;
     --ease-in-slow: initial;
     --header-height: initial;
-
-    --breakpoint-max-layout-width: initial;
   }
 }
 

From d4dd9392892eb2159a762fbb13fa81ff2ca8d9e9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Wed, 27 May 2026 13:20:11 +0200
Subject: [PATCH 02/33] Remove body background

---
 docs/src/app/(docs)/layout.css | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/docs/src/app/(docs)/layout.css b/docs/src/app/(docs)/layout.css
index 9e6f6baa975..ab3a6493351 100644
--- a/docs/src/app/(docs)/layout.css
+++ b/docs/src/app/(docs)/layout.css
@@ -6,8 +6,6 @@
     position: relative; /* iOS 26 `position: absolute` backdrops */
     min-width: 320px;
     line-height: 1.5;
-    /* It's also the iOS footer overscroll background */
-    background-color: var(--color-background);
     color: var(--color-foreground);
   }
 }
@@ -90,7 +88,6 @@
 
   .RootLayoutFooter {
     @media (--lg) {
-      background-color: var(--color-background);
       width: 100%;
       height: var(--header-height);
       position: absolute;

From fdf662c43914a8899cee582bcabaa632617fdacf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Wed, 27 May 2026 15:35:49 +0200
Subject: [PATCH 03/33] Grid-based layout

---
 docs/src/app/(docs)/layout.css                | 87 ++++---------------
 docs/src/app/(docs)/layout.tsx                |  2 +
 docs/src/app/(website)/layout.tsx             | 45 +++++++++-
 docs/src/app/(website)/page.tsx               |  1 +
 docs/src/components/Header.css                |  1 +
 docs/src/components/QuickNav/QuickNav.css     | 25 ++++--
 docs/src/components/QuickNav/QuickNav.tsx     | 15 +++-
 docs/src/components/SideNav.css               | 28 ++----
 docs/src/components/SideNav.tsx               |  7 +-
 .../src/components/TestBackgroundShortcut.tsx | 33 +++++++
 docs/src/css/custom-media.css                 |  1 -
 11 files changed, 146 insertions(+), 99 deletions(-)
 create mode 100644 docs/src/components/TestBackgroundShortcut.tsx

diff --git a/docs/src/app/(docs)/layout.css b/docs/src/app/(docs)/layout.css
index ab3a6493351..4a306d5562c 100644
--- a/docs/src/app/(docs)/layout.css
+++ b/docs/src/app/(docs)/layout.css
@@ -12,35 +12,31 @@
 
 @layer components {
   .RootLayout {
-    --main-content-width: 44.75rem;
-    --sidebar-width: 17.5rem;
+    --content-layout-gap: 2.5rem;
+    --content-layout-max-width: 48rem;
 
     z-index: 0;
     position: relative;
-    padding-inline: 0;
+    padding-inline: 1.5rem;
 
-    @media (--show-side-nav) {
+    @media (--md) {
+      --content-layout-gap: 3rem;
       padding-inline: 3rem;
+    }
 
-      &::before,
-      &::after {
+    @media (--show-side-nav) {
+      --content-layout-max-width: 92.5rem;
+
+      &::before {
         content: '';
         position: absolute;
-        background-color: var(--color-gridline);
-        height: 1px;
+        z-index: 1;
+        top: var(--header-height);
         right: 0;
         left: 0;
-      }
-
-      &::before {
-        top: var(--header-height);
+        height: 1px;
         margin-top: -1px;
-      }
-
-      &::after {
-        bottom: var(--header-height);
-        margin-bottom: -1px;
-        z-index: 1;
+        background-color: var(--color-gridline);
       }
     }
   }
@@ -51,31 +47,11 @@
     flex-direction: column;
     margin-inline: auto;
     min-height: 100dvh;
-    max-width: calc(var(--sidebar-width) + var(--main-content-width) + var(--sidebar-width));
+    max-width: var(--content-layout-max-width);
 
     @media (--show-side-nav) {
       padding-block: var(--header-height);
       padding-bottom: 0;
-
-      &::before,
-      &::after {
-        content: '';
-        position: absolute;
-        top: 0;
-        bottom: 0;
-        width: 1px;
-        background-color: var(--color-gridline);
-      }
-
-      &::before {
-        left: 0;
-        margin-left: -1px;
-      }
-
-      &::after {
-        right: 0;
-        margin-right: -1px;
-      }
     }
   }
 
@@ -86,43 +62,22 @@
     background-color: var(--color-content);
   }
 
-  .RootLayoutFooter {
-    @media (--lg) {
-      width: 100%;
-      height: var(--header-height);
-      position: absolute;
-      z-index: 1;
-      left: 0;
-      right: 0;
-      bottom: 0;
-    }
-  }
-
   .ContentLayoutRoot {
     display: grid;
     align-items: start;
+    gap: var(--content-layout-gap);
     padding-top: var(--header-height);
-    padding-inline: 1.5rem;
-    grid-template-columns: 1fr;
-
-    @media (--sm) {
-      padding-inline: 2.5rem;
-    }
+    grid-template-columns: repeat(8, minmax(0, 1fr));
 
     @media (--show-side-nav) {
       padding-top: 0;
-      padding-inline: 0;
-      grid-template-columns: var(--sidebar-width) 1fr 3rem;
-    }
-
-    @media (--show-quick-nav) {
-      grid-template-columns: var(--sidebar-width) 1fr var(--sidebar-width);
     }
   }
 
   .ContentLayoutMain {
+    grid-column: 1 / -1;
+    grid-row: 1;
     min-width: 0;
-    max-width: var(--main-content-width);
     width: 100%;
 
     margin: 0 auto;
@@ -130,9 +85,5 @@
     @media (--show-side-nav) {
       margin: 0;
     }
-
-    @media (--show-quick-nav) {
-      margin: 0;
-    }
   }
 }
diff --git a/docs/src/app/(docs)/layout.tsx b/docs/src/app/(docs)/layout.tsx
index 26a24155378..ee254a96f50 100644
--- a/docs/src/app/(docs)/layout.tsx
+++ b/docs/src/app/(docs)/layout.tsx
@@ -10,6 +10,7 @@ import * as SideNav from 'docs/src/components/SideNav';
 import * as QuickNav from 'docs/src/components/QuickNav/QuickNav';
 import { Header, titleMap } from 'docs/src/components/Header';
 import { MAIN_CONTENT_ID } from 'docs/src/components/SkipNav';
+import { TestBackgroundShortcut } from 'docs/src/components/TestBackgroundShortcut';
 import { sitemap } from 'docs/src/app/sitemap';
 
 const showPrivatePages = process.env.SHOW_PRIVATE_PAGES === 'true';
@@ -49,6 +50,7 @@ export default function Layout({ children }: React.PropsWithChildren) {
         />
       </head>
       <body suppressHydrationWarning>
+        <TestBackgroundShortcut />
         <GoogleAnalytics>
           <DocsProviders>
             <div className="RootLayout">
diff --git a/docs/src/app/(website)/layout.tsx b/docs/src/app/(website)/layout.tsx
index 3a238f3213f..dc1c614c495 100644
--- a/docs/src/app/(website)/layout.tsx
+++ b/docs/src/app/(website)/layout.tsx
@@ -7,6 +7,7 @@ import type { Metadata, Viewport } from 'next/types';
 import { GoogleAnalytics } from 'docs/src/components/GoogleAnalytics';
 import { Link } from 'docs/src/components/Link';
 import { Logo } from 'docs/src/components/Logo';
+import { TestBackgroundShortcut } from 'docs/src/components/TestBackgroundShortcut';
 
 export default function Layout({ children }: React.PropsWithChildren) {
   return (
@@ -29,11 +30,53 @@ export default function Layout({ children }: React.PropsWithChildren) {
         />
       </head>
       <body suppressHydrationWarning className="Body bui-p-6 bp2:bui-py-7 bp2:bui-px-9">
+        <TestBackgroundShortcut />
         <GoogleAnalytics>
           <div
             className="bui-bs-bb bui-d-g bui-gtc-8 bui-g-8 bp2:bui-g-9"
-            style={{ maxWidth: '1480px', marginInline: 'auto' }}
+            style={{
+              isolation: 'isolate',
+              maxWidth: '1480px',
+              marginInline: 'auto',
+              position: 'relative',
+            }}
           >
+            <div
+              aria-hidden="true"
+              className="bui-gcs-1 bui-gce-9 bp2:bui-gce-3"
+              style={{
+                backgroundColor: 'var(--test-bg)',
+                insetBlock: 0,
+                insetInline: 0,
+                pointerEvents: 'none',
+                position: 'absolute',
+                zIndex: -1,
+              }}
+            ></div>
+            <div
+              aria-hidden="true"
+              className="bui-d-n bp2:bui-d-b bui-gcs-3 bui-gce-7"
+              style={{
+                backgroundColor: 'var(--test-bg)',
+                insetBlock: 0,
+                insetInline: 0,
+                pointerEvents: 'none',
+                position: 'absolute',
+                zIndex: -1,
+              }}
+            ></div>
+            <div
+              aria-hidden="true"
+              className="bui-d-n bp2:bui-d-b bui-gcs-7 bui-gce-9"
+              style={{
+                backgroundColor: 'var(--test-bg)',
+                insetBlock: 0,
+                insetInline: 0,
+                pointerEvents: 'none',
+                position: 'absolute',
+                zIndex: -1,
+              }}
+            ></div>
             <header className="bui-d-c">
               <div className="bui-gcs-1 bui-gce-4">
                 <Logo aria-label="Base UI" />
diff --git a/docs/src/app/(website)/page.tsx b/docs/src/app/(website)/page.tsx
index 63ca1e2721d..4f6e8f1d641 100644
--- a/docs/src/app/(website)/page.tsx
+++ b/docs/src/app/(website)/page.tsx
@@ -86,6 +86,7 @@ export default function Homepage() {
       <div className="bui-gcs-1 bui-gce-9 bp3:bui-gcs-3">
         <div className="Separator" role="separator" aria-hidden="true"></div>
       </div>
+
       <section className="bui-d-c">
         <div className="bui-gcs-1 bui-gce-9 bp2:bui-gce-3">
           <h2 className="Text sz-2">Made for the makers</h2>
diff --git a/docs/src/components/Header.css b/docs/src/components/Header.css
index 4a2d82ccc50..449b796d9cb 100644
--- a/docs/src/components/Header.css
+++ b/docs/src/components/Header.css
@@ -30,6 +30,7 @@
       position: static;
       box-shadow: none;
       background-color: transparent;
+      padding-inline: 0;
     }
 
     @media print {
diff --git a/docs/src/components/QuickNav/QuickNav.css b/docs/src/components/QuickNav/QuickNav.css
index 179bf741d68..76f5b245966 100644
--- a/docs/src/components/QuickNav/QuickNav.css
+++ b/docs/src/components/QuickNav/QuickNav.css
@@ -5,9 +5,15 @@
     /* Quick Nav's container shouldn't have any paddings to maintain correct positioning */
     padding: 0;
     position: relative;
+    display: grid;
+    gap: var(--content-layout-gap);
+    grid-template-columns: repeat(8, minmax(0, 1fr));
   }
 
   .QuickNavContent {
+    grid-column: 1 / -1;
+    grid-row: 1;
+    min-width: 0;
     padding-top: 1.5rem;
     padding-bottom: 5rem;
 
@@ -16,12 +22,16 @@
     }
 
     @media (--show-side-nav) {
-      padding-bottom: 8rem;
+      grid-column: 3 / 9;
+      padding-bottom: var(--header-height);
+    }
+
+    @media (--xl) {
+      grid-column: 3 / 7;
     }
   }
 
   .QuickNavRoot {
-    --quick-nav-margin-x: 2rem;
     --quick-nav-scrollbar-thumb-width: 0.25rem;
     --quick-nav-scrollbar-width: 1.5rem;
 
@@ -35,22 +45,23 @@
     font-size: var(--font-size-15);
     line-height: 1.375rem;
     z-index: 1;
+    grid-column: 7 / 9;
+    grid-row: 1;
+    align-self: start;
+    min-width: 0;
     position: sticky;
     top: 0;
-    width: 0;
-    float: right;
     contain: layout;
     display: none;
 
-    @media (--show-quick-nav) {
+    @media (--xl) {
       display: block;
     }
   }
 
   .QuickNavInner {
     position: relative;
-    left: var(--quick-nav-margin-x);
-    width: calc(var(--sidebar-width) - var(--quick-nav-margin-x));
+    width: 100%;
   }
 
   .QuickNavViewport {
diff --git a/docs/src/components/QuickNav/QuickNav.tsx b/docs/src/components/QuickNav/QuickNav.tsx
index 9f1b63d7302..746e452c961 100644
--- a/docs/src/components/QuickNav/QuickNav.tsx
+++ b/docs/src/components/QuickNav/QuickNav.tsx
@@ -11,12 +11,23 @@ export function Container({ className, ...props }: React.ComponentProps<'div'>)
 }
 
 export function Content({ className, ...props }: React.ComponentProps<'div'>) {
-  return <div className={clsx('QuickNavContent', className)} {...props} />;
+  return (
+    <div
+      className={clsx('QuickNavContent', className)}
+      {...props}
+      style={{ backgroundColor: 'var(--test-bg)' }}
+    />
+  );
 }
 
 export function Root({ children, className, ...props }: React.ComponentProps<'div'>) {
   return (
-    <nav aria-label="On this page" className={clsx('QuickNavRoot', className)} {...props}>
+    <nav
+      aria-label="On this page"
+      className={clsx('QuickNavRoot', className)}
+      {...props}
+      style={{ backgroundColor: 'var(--test-bg)' }}
+    >
       <div className="QuickNavInner">
         <ScrollArea.Root>
           <ScrollArea.Viewport className="QuickNavViewport">{children}</ScrollArea.Viewport>
diff --git a/docs/src/components/SideNav.css b/docs/src/components/SideNav.css
index c8bc243d683..be51f4b00b4 100644
--- a/docs/src/components/SideNav.css
+++ b/docs/src/components/SideNav.css
@@ -9,17 +9,12 @@
       var(--side-nav-item-height) / 2 - var(--side-nav-item-line-height) / 2
     );
 
-    --side-nav-scrollbar-thumb-width: 0.25rem;
-    --side-nav-scrollbar-width: 1.5rem;
-    --side-nav-scrollbar-gap-left: 1rem;
-    --side-nav-scrollbar-gap-right: 2.5rem;
-    margin-right: calc(
-      var(--side-nav-scrollbar-gap-right) - var(--side-nav-scrollbar-width) / 2 +
-        var(--side-nav-scrollbar-thumb-width) / 2
-    );
-
     font-size: var(--font-size-15);
     line-height: 1.375rem;
+    z-index: 1;
+    grid-column: 1 / 3;
+    grid-row: 1;
+    min-width: 0;
     position: sticky;
     top: 0;
 
@@ -31,13 +26,8 @@
   }
 
   .SideNavViewport {
-    max-height: 100dvh;
-    padding: 0.75rem
-      calc(
-        var(--side-nav-scrollbar-gap-left) + var(--side-nav-scrollbar-width) / 2 +
-          var(--side-nav-scrollbar-thumb-width) / 2
-      )
-      5rem 1.5rem;
+    max-height: calc(100dvh - var(--header-height));
+    padding: 0.75rem 1.5rem 0.75rem 0;
 
     /* Scroll containers are focusable */
     outline: 0;
@@ -57,10 +47,10 @@
   .SideNavScrollbar {
     display: flex;
     padding-top: 1.5rem;
-    padding-bottom: 4.5rem;
+    padding-bottom: 1.5rem;
 
     /* Click target width */
-    width: var(--side-nav-scrollbar-width);
+    width: 1.5rem;
 
     opacity: 0;
     transition: opacity 200ms 500ms;
@@ -84,7 +74,7 @@
       display: block;
       height: 100%;
       /* Visible thumb width */
-      width: var(--side-nav-scrollbar-thumb-width);
+      width: 0.25rem;
       border-radius: var(--radius-4);
       background-color: var(--gray-p2);
     }
diff --git a/docs/src/components/SideNav.tsx b/docs/src/components/SideNav.tsx
index 3a346c81712..c4ffe0ddea0 100644
--- a/docs/src/components/SideNav.tsx
+++ b/docs/src/components/SideNav.tsx
@@ -10,7 +10,12 @@ import './SideNav.css';
 
 export function Root(props: React.ComponentProps<'div'>) {
   return (
-    <nav aria-label="Main navigation" {...props} className={clsx('SideNavRoot', props.className)}>
+    <nav
+      aria-label="Main navigation"
+      {...props}
+      className={clsx('SideNavRoot', props.className)}
+      style={{ backgroundColor: 'var(--test-bg)' }}
+    >
       <ScrollArea.Root>
         <ScrollArea.Viewport data-side-nav-viewport className="SideNavViewport">
           {props.children}
diff --git a/docs/src/components/TestBackgroundShortcut.tsx b/docs/src/components/TestBackgroundShortcut.tsx
new file mode 100644
index 00000000000..b4a6fecdc79
--- /dev/null
+++ b/docs/src/components/TestBackgroundShortcut.tsx
@@ -0,0 +1,33 @@
+import * as React from 'react';
+import Script from 'next/script';
+
+export function TestBackgroundShortcut() {
+  return (
+    <Script id="test-background-shortcut" strategy="afterInteractive">
+      {`
+        (() => {
+          if (window.__baseUiTestBackgroundShortcut) {
+            return;
+          }
+
+          window.__baseUiTestBackgroundShortcut = true;
+
+          window.addEventListener(
+            'keydown',
+            (event) => {
+              if (event.metaKey && event.code === 'KeyB') {
+                event.preventDefault();
+
+                const root = document.documentElement;
+                const currentValue = root.style.getPropertyValue('--test-bg').trim();
+
+                root.style.setProperty('--test-bg', currentValue === 'lightgreen' ? '' : 'lightgreen');
+              }
+            },
+            { capture: true },
+          );
+        })();
+      `}
+    </Script>
+  );
+}
diff --git a/docs/src/css/custom-media.css b/docs/src/css/custom-media.css
index c904ba34668..874c3c4dff5 100644
--- a/docs/src/css/custom-media.css
+++ b/docs/src/css/custom-media.css
@@ -6,4 +6,3 @@
 /* stylelint-disable-next-line custom-media-pattern */
 @custom-media --2xl (min-width: 96rem); /* 1536px */
 @custom-media --show-side-nav (min-width: 64rem);
-@custom-media --show-quick-nav (min-width: 84rem);

From 0fdb3a49fcee9181297f0bd8046a551a2e8e3af1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Wed, 27 May 2026 23:20:22 +0200
Subject: [PATCH 04/33] Fixed everything

---
 docs/src/app/(docs)/layout.css            | 34 +++++++++++++----------
 docs/src/components/Header.css            | 29 ++++++++-----------
 docs/src/components/QuickNav/QuickNav.css | 24 ++++++++--------
 docs/src/components/SideNav.css           | 11 +++++---
 4 files changed, 49 insertions(+), 49 deletions(-)

diff --git a/docs/src/app/(docs)/layout.css b/docs/src/app/(docs)/layout.css
index 4a306d5562c..74a4dbd9e27 100644
--- a/docs/src/app/(docs)/layout.css
+++ b/docs/src/app/(docs)/layout.css
@@ -14,30 +14,36 @@
   .RootLayout {
     --content-layout-gap: 2.5rem;
     --content-layout-max-width: 48rem;
+    --root-layout-padding-inline: 1.5rem;
 
     z-index: 0;
     position: relative;
-    padding-inline: 1.5rem;
+    padding-inline: var(--root-layout-padding-inline);
 
     @media (--md) {
       --content-layout-gap: 3rem;
-      padding-inline: 3rem;
+      --root-layout-padding-inline: 3rem;
     }
 
     @media (--show-side-nav) {
       --content-layout-max-width: 92.5rem;
-
-      &::before {
-        content: '';
-        position: absolute;
-        z-index: 1;
-        top: var(--header-height);
-        right: 0;
-        left: 0;
-        height: 1px;
-        margin-top: -1px;
-        background-color: var(--color-gridline);
-      }
+      --content-layout-width: min(
+        var(--content-layout-max-width),
+        calc(100% - var(--root-layout-padding-inline) - var(--root-layout-padding-inline))
+      );
+      --content-layout-inline-offset: calc((100% - var(--content-layout-width)) / 2);
+      --content-layout-column-width: calc(
+        (
+            var(--content-layout-width) - var(--content-layout-gap) - var(--content-layout-gap) -
+              var(--content-layout-gap) - var(--content-layout-gap) - var(--content-layout-gap) -
+              var(--content-layout-gap) - var(--content-layout-gap)
+          ) /
+          8
+      );
+      --content-layout-sidebar-width: calc(
+        var(--content-layout-column-width) + var(--content-layout-column-width) +
+          var(--content-layout-gap)
+      );
     }
   }
 
diff --git a/docs/src/components/Header.css b/docs/src/components/Header.css
index 449b796d9cb..a24707bdf7a 100644
--- a/docs/src/components/Header.css
+++ b/docs/src/components/Header.css
@@ -4,39 +4,32 @@
   .Header {
     font-size: var(--font-size-15);
     line-height: 1.375rem;
-    position: absolute;
+    position: fixed;
     left: 0;
     top: 0;
     height: var(--header-height);
     width: 100%;
+    background-color: var(--color-content);
+    z-index: 3;
+
+    @media print {
+      /* Prevent the header to be visible on each printed page */
+      position: absolute;
+    }
   }
 
   .HeaderInner {
     height: inherit;
+    width: calc(100% - var(--root-layout-padding-inline) - var(--root-layout-padding-inline));
+    max-width: var(--content-layout-max-width);
     display: flex;
     align-items: center;
     justify-content: space-between;
-    padding-inline: 1.5rem;
-
-    position: fixed;
-    top: 0;
-    inset-inline: 0;
-    box-shadow: inset 0 -1px var(--color-gridline);
-    /* It's also the iOS header overscroll background */
-    background-color: var(--gray-s2);
-    z-index: 2;
+    margin-inline: auto;
 
     @media (--show-side-nav) {
-      position: static;
-      box-shadow: none;
-      background-color: transparent;
       padding-inline: 0;
     }
-
-    @media print {
-      /* Prevent the header to be visible on each printed page */
-      position: absolute;
-    }
   }
 
   .HeaderLink,
diff --git a/docs/src/components/QuickNav/QuickNav.css b/docs/src/components/QuickNav/QuickNav.css
index 76f5b245966..04718db13ee 100644
--- a/docs/src/components/QuickNav/QuickNav.css
+++ b/docs/src/components/QuickNav/QuickNav.css
@@ -14,16 +14,11 @@
     grid-column: 1 / -1;
     grid-row: 1;
     min-width: 0;
-    padding-top: 1.5rem;
-    padding-bottom: 5rem;
-
-    @media (--sm) {
-      padding-top: 2rem;
-    }
+    padding-top: 0.75rem;
+    padding-bottom: 1.5rem;
 
     @media (--show-side-nav) {
       grid-column: 3 / 9;
-      padding-bottom: var(--header-height);
     }
 
     @media (--xl) {
@@ -49,13 +44,16 @@
     grid-row: 1;
     align-self: start;
     min-width: 0;
-    position: sticky;
-    top: 0;
     contain: layout;
     display: none;
 
     @media (--xl) {
       display: block;
+      position: fixed;
+      top: var(--header-height);
+      right: var(--content-layout-inline-offset);
+      bottom: 0;
+      width: var(--content-layout-sidebar-width);
     }
   }
 
@@ -65,10 +63,10 @@
   }
 
   .QuickNavViewport {
-    max-height: 100dvh;
+    max-height: calc(100dvh - var(--header-height));
     padding-top: 0.75rem;
     padding-right: var(--quick-nav-scrollbar-width);
-    padding-bottom: 4.5rem;
+    padding-bottom: 0.75rem;
     padding-left: 0;
 
     /* Scroll containers are focusable */
@@ -82,8 +80,8 @@
 
   .QuickNavScrollbar {
     display: flex;
-    padding-top: 1.5rem;
-    padding-bottom: 4.5rem;
+    padding-top: 0.75rem;
+    padding-bottom: 0.75rem;
 
     /* Click target width */
     width: var(--quick-nav-scrollbar-width);
diff --git a/docs/src/components/SideNav.css b/docs/src/components/SideNav.css
index be51f4b00b4..573e10440ab 100644
--- a/docs/src/components/SideNav.css
+++ b/docs/src/components/SideNav.css
@@ -15,13 +15,16 @@
     grid-column: 1 / 3;
     grid-row: 1;
     min-width: 0;
-    position: sticky;
-    top: 0;
 
     display: none;
 
     @media (--show-side-nav) {
       display: block;
+      position: fixed;
+      top: var(--header-height);
+      bottom: 0;
+      left: var(--content-layout-inline-offset);
+      width: var(--content-layout-sidebar-width);
     }
   }
 
@@ -46,8 +49,8 @@
 
   .SideNavScrollbar {
     display: flex;
-    padding-top: 1.5rem;
-    padding-bottom: 1.5rem;
+    padding-top: 0.75rem;
+    padding-bottom: 0.75rem;
 
     /* Click target width */
     width: 1.5rem;

From 6e3d289e961e3b6de39663dd5a86f8166cdd8da2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 00:13:22 +0200
Subject: [PATCH 05/33] Fix table columns dimensions

---
 .../AttributesReferenceTable.tsx              |  4 +++-
 .../CssVariablesReferenceTable.tsx            |  4 +++-
 .../ReferenceTable/ReferenceTable.css         | 20 ++++++++++++-------
 3 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/docs/src/components/ReferenceTable/AttributesReferenceTable.tsx b/docs/src/components/ReferenceTable/AttributesReferenceTable.tsx
index 63da0e07698..7e145b92669 100644
--- a/docs/src/components/ReferenceTable/AttributesReferenceTable.tsx
+++ b/docs/src/components/ReferenceTable/AttributesReferenceTable.tsx
@@ -81,7 +81,9 @@ export function AttributesReferenceTable({
                     {name}
                   </TableCode>
                 </Table.RowHeader>
-                <Table.Cell colSpan={2}>{attribute.description}</Table.Cell>
+                <Table.Cell className="ReferenceDescriptionCell" colSpan={2}>
+                  {attribute.description}
+                </Table.Cell>
               </Table.Row>
             );
           })}
diff --git a/docs/src/components/ReferenceTable/CssVariablesReferenceTable.tsx b/docs/src/components/ReferenceTable/CssVariablesReferenceTable.tsx
index 6efea4a0a50..c8680f1707d 100644
--- a/docs/src/components/ReferenceTable/CssVariablesReferenceTable.tsx
+++ b/docs/src/components/ReferenceTable/CssVariablesReferenceTable.tsx
@@ -82,7 +82,9 @@ export function CssVariablesReferenceTable({
                 <Table.RowHeader>
                   <TableCode style={{ color: 'var(--color-navy)' }}>{name}</TableCode>
                 </Table.RowHeader>
-                <Table.Cell colSpan={2}>{cssVariable.description}</Table.Cell>
+                <Table.Cell className="ReferenceDescriptionCell" colSpan={2}>
+                  {cssVariable.description}
+                </Table.Cell>
               </Table.Row>
             );
           })}
diff --git a/docs/src/components/ReferenceTable/ReferenceTable.css b/docs/src/components/ReferenceTable/ReferenceTable.css
index 4e0b608d9ec..8f0d544a0ad 100644
--- a/docs/src/components/ReferenceTable/ReferenceTable.css
+++ b/docs/src/components/ReferenceTable/ReferenceTable.css
@@ -90,6 +90,12 @@
     width: 66.6667%;
   }
 
+  .ReferenceDescriptionCell .TableCellInner {
+    display: block;
+    white-space: normal;
+    overflow-x: visible;
+  }
+
   .ReferenceReturnTypeColumn {
     width: 40%;
   }
@@ -159,32 +165,32 @@
     }
 
     .ReferenceHeaderRow {
-      grid-template-columns: 5fr 7fr 4.5fr 2.5rem;
+      grid-template-columns: 6fr 6fr 4.5fr 2.5rem;
     }
 
     .ReferenceTrigger {
       scroll-margin-top: 0;
-      grid-template-columns: 5fr 7fr 4.5fr 2.5rem;
+      grid-template-columns: 6fr 6fr 4.5fr 2.5rem;
     }
 
     [data-hide-default] > .ReferenceHeaderRow {
-      grid-template-columns: 5fr 7fr 2.5rem;
+      grid-template-columns: 6fr 6fr 2.5rem;
     }
 
     [data-hide-default] .ReferenceTrigger {
-      grid-template-columns: 5fr 7fr 2.5rem;
+      grid-template-columns: 6fr 6fr 2.5rem;
     }
 
     .ReferenceWideNameColumn {
-      width: calc(5 / 16.5 * 100%);
+      width: calc(6 / 16.5 * 100%);
     }
 
     .ReferenceWideDescriptionColumn {
-      width: calc(11.5 / 16.5 * 100%);
+      width: calc(10.5 / 16.5 * 100%);
     }
 
     .ReferenceContent {
-      grid-template-columns: 5fr 11.5fr 2.5rem;
+      grid-template-columns: 6fr 10.5fr 2.5rem;
     }
   }
 

From 97a6cb6c005f6791f4d763f32a55bfa81b1cfa5a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 00:32:31 +0200
Subject: [PATCH 06/33] New "show code" button design

---
 docs/src/components/Demo/Demo.css          | 68 ++++++++++++++++------
 docs/src/components/Demo/DemoCodeBlock.tsx |  8 ++-
 2 files changed, 57 insertions(+), 19 deletions(-)

diff --git a/docs/src/components/Demo/Demo.css b/docs/src/components/Demo/Demo.css
index 7cab65eb81f..6882dee8d11 100644
--- a/docs/src/components/Demo/Demo.css
+++ b/docs/src/components/Demo/Demo.css
@@ -192,6 +192,38 @@
     }
   }
 
+  .DemoCodeBlockCollapsible {
+    position: relative;
+    display: flex;
+    flex-direction: column;
+
+    &:not([data-open], [data-compact]) {
+      .DemoCollapseButton {
+        position: absolute;
+        left: 50%;
+        bottom: 0.75rem;
+        transform: translateX(-50%);
+      }
+    }
+
+    &[data-open] {
+      .DemoCollapseButton {
+        position: sticky;
+        bottom: 0.75rem;
+        align-self: center;
+        margin-top: -2.25rem;
+        margin-bottom: 0.75rem;
+      }
+    }
+
+    &[data-compact]:not([data-open]) {
+      .DemoCollapseButton {
+        align-self: center;
+        margin-block: 0.75rem;
+      }
+    }
+  }
+
   .DemoCodeBlockRoot {
     display: flex;
     flex-direction: column;
@@ -202,6 +234,7 @@
       &::before {
         content: '';
         position: absolute;
+        z-index: 1;
         pointer-events: none;
         height: 7.5rem;
         bottom: 0;
@@ -272,40 +305,41 @@
   .DemoCollapseButton {
     font-size: var(--font-size-13);
     line-height: 1.25rem;
-    background-color: var(--gray-s2);
+    font-weight: var(--font-weight-400);
+    background-color: white;
     cursor: default;
-    width: 100%;
-    color: var(--gray-t2);
-    height: 2.25rem;
-    border-top: 1px solid var(--gray-c2);
-    border-bottom-left-radius: 0.375rem;
-    border-bottom-right-radius: 0.375rem;
-    border-bottom: 1px solid transparent;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    color: var(--color-foreground);
+    height: 2rem;
+    padding-inline: 0.75rem;
+    border: 1px solid var(--gray-c2);
+    border-radius: var(--radius-pill);
     background-clip: padding-box;
-    margin-bottom: -1px;
+    position: relative;
+    white-space: nowrap;
+    z-index: 2;
     -webkit-user-select: none;
     user-select: none;
 
+    @media (prefers-color-scheme: dark) {
+      background-color: var(--gray-c2);
+    }
+
     &[data-sticky] {
-      position: sticky;
-      bottom: -1px;
       z-index: 1;
     }
 
     @media (hover: hover) {
       &:hover {
-        background-color: var(--gray-c1);
+        background-color: var(--gray-s2);
       }
     }
 
-    &:active {
-      background-color: color-mix(in oklch, var(--gray-c1), var(--gray-t2) 5%);
-    }
-
     &:focus-visible {
       outline: 2px solid var(--gray-t2);
       outline-offset: -1px;
-      z-index: 1;
     }
   }
 }
diff --git a/docs/src/components/Demo/DemoCodeBlock.tsx b/docs/src/components/Demo/DemoCodeBlock.tsx
index 6bc06f67bb5..eca31b9b704 100644
--- a/docs/src/components/Demo/DemoCodeBlock.tsx
+++ b/docs/src/components/Demo/DemoCodeBlock.tsx
@@ -57,7 +57,11 @@ export function DemoCodeBlock({
   }
 
   return (
-    <React.Fragment>
+    <div
+      className="DemoCodeBlockCollapsible"
+      data-open={collapsibleOpen ? '' : undefined}
+      data-compact={compact ? '' : undefined}
+    >
       <Root
         render={
           <Collapsible.Panel
@@ -91,6 +95,6 @@ export function DemoCodeBlock({
       >
         {collapsibleOpen ? 'Hide' : 'Show'} code
       </Collapsible.Trigger>
-    </React.Fragment>
+    </div>
   );
 }

From 52df18525f80fc9f1a26f724e41f5a31d396497f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 00:35:36 +0200
Subject: [PATCH 07/33] Move "View as Markdown" link below subtitle

---
 docs/src/components/Subtitle/Subtitle.css | 9 +--------
 1 file changed, 1 insertion(+), 8 deletions(-)

diff --git a/docs/src/components/Subtitle/Subtitle.css b/docs/src/components/Subtitle/Subtitle.css
index acc5f5224bd..1d06ff89dcf 100644
--- a/docs/src/components/Subtitle/Subtitle.css
+++ b/docs/src/components/Subtitle/Subtitle.css
@@ -2,18 +2,11 @@
   .Subtitle {
     display: flex;
     flex-direction: column;
-    align-items: baseline;
-    justify-content: space-between;
+    align-items: flex-start;
     font-size: var(--font-size-18);
     line-height: 1.75rem;
     text-wrap: pretty;
     color: var(--gray-t1);
     margin-bottom: 1.25rem;
-    gap: 0.5rem;
-
-    @media (min-width: 48rem) {
-      flex-direction: row;
-      gap: 2rem;
-    }
   }
 }

From f09bace59f92763b816e91920601bf22f3a9b8a0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 00:41:01 +0200
Subject: [PATCH 08/33] font-size 15-> 14, reduce sidebar items' height

---
 docs/src/components/Header.css                          | 4 ++--
 docs/src/components/Menu.css                            | 2 +-
 docs/src/components/QuickNav/QuickNav.css               | 4 ++--
 docs/src/components/ReferenceTable/ReferenceTable.css   | 2 +-
 docs/src/components/ReleaseTimeline/ReleaseTimeline.css | 2 +-
 docs/src/components/Select.css                          | 2 +-
 docs/src/components/SideNav.css                         | 4 ++--
 7 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/docs/src/components/Header.css b/docs/src/components/Header.css
index a24707bdf7a..bc6f8d90f3e 100644
--- a/docs/src/components/Header.css
+++ b/docs/src/components/Header.css
@@ -2,7 +2,7 @@
 
 @layer components {
   .Header {
-    font-size: var(--font-size-15);
+    font-size: var(--font-size-14);
     line-height: 1.375rem;
     position: fixed;
     left: 0;
@@ -158,7 +158,7 @@
   }
 
   .HeaderVersion {
-    font-size: var(--font-size-15);
+    font-size: var(--font-size-14);
     line-height: 1.375rem;
     color: var(--gray-t1);
   }
diff --git a/docs/src/components/Menu.css b/docs/src/components/Menu.css
index 1e3d7d9ad9b..b55e6142d0a 100644
--- a/docs/src/components/Menu.css
+++ b/docs/src/components/Menu.css
@@ -73,7 +73,7 @@
     }
 
     @media (pointer: coarse) {
-      font-size: var(--font-size-15);
+      font-size: var(--font-size-14);
       height: 2.25rem;
     }
   }
diff --git a/docs/src/components/QuickNav/QuickNav.css b/docs/src/components/QuickNav/QuickNav.css
index 04718db13ee..7dcbc292e74 100644
--- a/docs/src/components/QuickNav/QuickNav.css
+++ b/docs/src/components/QuickNav/QuickNav.css
@@ -31,13 +31,13 @@
     --quick-nav-scrollbar-width: 1.5rem;
 
     /* Use line height instead of fixed item height in case text breaks into multiple lines */
-    --quick-nav-item-height: 2rem;
+    --quick-nav-item-height: 1.75rem;
     --quick-nav-item-line-height: 1.375rem;
     --quick-nav-item-padding-y: calc(
       var(--quick-nav-item-height) / 2 - var(--quick-nav-item-line-height) / 2
     );
 
-    font-size: var(--font-size-15);
+    font-size: var(--font-size-14);
     line-height: 1.375rem;
     z-index: 1;
     grid-column: 7 / 9;
diff --git a/docs/src/components/ReferenceTable/ReferenceTable.css b/docs/src/components/ReferenceTable/ReferenceTable.css
index 8f0d544a0ad..ef7b6abff83 100644
--- a/docs/src/components/ReferenceTable/ReferenceTable.css
+++ b/docs/src/components/ReferenceTable/ReferenceTable.css
@@ -77,7 +77,7 @@
     flex-direction: column;
     gap: 0.75rem;
     padding: 1rem;
-    font-size: var(--font-size-15);
+    font-size: var(--font-size-14);
     line-height: 1.375rem;
     text-wrap: pretty;
   }
diff --git a/docs/src/components/ReleaseTimeline/ReleaseTimeline.css b/docs/src/components/ReleaseTimeline/ReleaseTimeline.css
index fb7defdc508..e2a0bf97a4a 100644
--- a/docs/src/components/ReleaseTimeline/ReleaseTimeline.css
+++ b/docs/src/components/ReleaseTimeline/ReleaseTimeline.css
@@ -111,7 +111,7 @@
     background-color: var(--gray-c2);
     border-radius: var(--radius-8);
     padding: 1.25rem;
-    font-size: var(--font-size-15);
+    font-size: var(--font-size-14);
     color: var(--color-foreground);
     line-height: 1.375rem;
   }
diff --git a/docs/src/components/Select.css b/docs/src/components/Select.css
index 235df296ec5..61a175bd57b 100644
--- a/docs/src/components/Select.css
+++ b/docs/src/components/Select.css
@@ -72,7 +72,7 @@
     }
 
     @media (pointer: coarse) {
-      font-size: var(--font-size-15);
+      font-size: var(--font-size-14);
       height: 2.25rem;
       grid-template-columns: 0.5rem 1rem 0.5rem auto 1.5rem;
     }
diff --git a/docs/src/components/SideNav.css b/docs/src/components/SideNav.css
index 573e10440ab..65854c64c14 100644
--- a/docs/src/components/SideNav.css
+++ b/docs/src/components/SideNav.css
@@ -3,13 +3,13 @@
 @layer components {
   .SideNavRoot {
     /* Match quick nav spacing so side nav and quick nav are visually aligned */
-    --side-nav-item-height: 2rem;
+    --side-nav-item-height: 1.75rem;
     --side-nav-item-line-height: 1.375rem;
     --side-nav-item-padding-y: calc(
       var(--side-nav-item-height) / 2 - var(--side-nav-item-line-height) / 2
     );
 
-    font-size: var(--font-size-15);
+    font-size: var(--font-size-14);
     line-height: 1.375rem;
     z-index: 1;
     grid-column: 1 / 3;

From 614ce9ce4c7655fd38d14f7716d53cd222edaac4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 01:11:56 +0200
Subject: [PATCH 09/33] Adjust spacing

---
 docs/src/css/mdx-components.css | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/src/css/mdx-components.css b/docs/src/css/mdx-components.css
index 287df9e4aa7..5720045631d 100644
--- a/docs/src/css/mdx-components.css
+++ b/docs/src/css/mdx-components.css
@@ -87,7 +87,7 @@
 
   .MdSubtitle {
     margin-top: -0.5rem;
-    margin-bottom: 1.25rem;
+    margin-bottom: 0.5rem;
   }
 
   .MdReferenceBlock {

From b6ef703e7cf1b46e0589a53f0bbc709ee6b04c1c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 01:39:44 +0200
Subject: [PATCH 10/33] Make demo bg gray

---
 docs/src/components/Demo/Demo.css | 17 ++++++++++-------
 docs/src/components/Demo/Demo.tsx |  6 +++++-
 2 files changed, 15 insertions(+), 8 deletions(-)

diff --git a/docs/src/components/Demo/Demo.css b/docs/src/components/Demo/Demo.css
index 6882dee8d11..a0c5517b195 100644
--- a/docs/src/components/Demo/Demo.css
+++ b/docs/src/components/Demo/Demo.css
@@ -2,9 +2,9 @@
 
 @layer components {
   .DemoRoot {
-    background-color: var(--color-content);
+    background-color: rgb(0 0 0 / 2%);
     border: 1px solid var(--gray-c2);
-    border-radius: var(--radius-6);
+    border-radius: var(--radius-12);
     margin-bottom: var(--space-24);
 
     --shadow-1:
@@ -32,8 +32,8 @@
     position: relative;
 
     background-color: var(--color-content);
-    border-top-left-radius: var(--radius-6);
-    border-top-right-radius: var(--radius-6);
+    border-top-left-radius: var(--radius-12);
+    border-top-right-radius: var(--radius-12);
 
     /* Scroll */
     overflow: auto hidden;
@@ -67,9 +67,8 @@
     line-height: 1.25rem;
     white-space: nowrap;
     color: var(--gray-t2);
-    background-color: var(--gray-s2);
     background-clip: padding-box;
-    border-block: 1px solid var(--gray-c2);
+    border-bottom: 1px solid var(--gray-c2);
     display: flex;
     align-items: center;
     gap: 2rem;
@@ -219,7 +218,7 @@
     &[data-compact]:not([data-open]) {
       .DemoCollapseButton {
         align-self: center;
-        margin-block: 0.75rem;
+        margin-block: 0.5rem;
       }
     }
   }
@@ -302,6 +301,10 @@
     }
   }
 
+  .DemoCollapsibleRoot {
+    border-top: 1px solid var(--gray-c2);
+  }
+
   .DemoCollapseButton {
     font-size: var(--font-size-13);
     line-height: 1.25rem;
diff --git a/docs/src/components/Demo/Demo.tsx b/docs/src/components/Demo/Demo.tsx
index cf27e2514a7..d85cc158952 100644
--- a/docs/src/components/Demo/Demo.tsx
+++ b/docs/src/components/Demo/Demo.tsx
@@ -190,7 +190,11 @@ export function Demo({
           )}
         </DemoPlayground>
       </div>
-      <Collapsible.Root open={demo.expanded} onOpenChange={onOpenChange}>
+      <Collapsible.Root
+        className="DemoCollapsibleRoot"
+        open={demo.expanded}
+        onOpenChange={onOpenChange}
+      >
         <div role="figure" aria-label="Component demo code">
           {(compact ? demo.expanded : true) && (
             <div className="DemoToolbar">

From 13f28f2b7734f400ced9dfcfa34eee1b10d41209 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 01:44:01 +0200
Subject: [PATCH 11/33] Update page bg

---
 docs/src/app/(docs)/layout.css                 | 2 +-
 docs/src/app/(website)/css/components/Body.css | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/src/app/(docs)/layout.css b/docs/src/app/(docs)/layout.css
index 74a4dbd9e27..30a69b2c7b8 100644
--- a/docs/src/app/(docs)/layout.css
+++ b/docs/src/app/(docs)/layout.css
@@ -7,6 +7,7 @@
     min-width: 320px;
     line-height: 1.5;
     color: var(--color-foreground);
+    background-color: var(--color-content);
   }
 }
 
@@ -65,7 +66,6 @@
     display: flex;
     flex-grow: 1;
     flex-direction: column;
-    background-color: var(--color-content);
   }
 
   .ContentLayoutRoot {
diff --git a/docs/src/app/(website)/css/components/Body.css b/docs/src/app/(website)/css/components/Body.css
index 5a90d5dcdfb..96bafa3d3f1 100644
--- a/docs/src/app/(website)/css/components/Body.css
+++ b/docs/src/app/(website)/css/components/Body.css
@@ -3,6 +3,6 @@
     box-sizing: border-box;
     margin: 0;
     color: var(--gray-t2);
-    background-color: var(--gray-s1);
+    background-color: var(--color-content);
   }
 }

From 1c5a34e7f381dacedbe3d832f04238369c846e9d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 01:53:40 +0200
Subject: [PATCH 12/33] Adjust colors to fix overflow gradient

---
 docs/src/components/Demo/Demo.css | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/src/components/Demo/Demo.css b/docs/src/components/Demo/Demo.css
index a0c5517b195..bc1e63f1643 100644
--- a/docs/src/components/Demo/Demo.css
+++ b/docs/src/components/Demo/Demo.css
@@ -2,7 +2,7 @@
 
 @layer components {
   .DemoRoot {
-    background-color: rgb(0 0 0 / 2%);
+    background-color: var(--gray-s2);
     border: 1px solid var(--gray-c2);
     border-radius: var(--radius-12);
     margin-bottom: var(--space-24);

From c8504e1cd84162a6058b0c37c1d2189affdd0d43 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 11:05:24 +0200
Subject: [PATCH 13/33] Cleanup test code

---
 docs/src/app/(docs)/layout.tsx                |  2 -
 docs/src/app/(website)/layout.tsx             | 40 -------------------
 docs/src/components/QuickNav/QuickNav.tsx     | 15 +------
 docs/src/components/SideNav.tsx               |  7 +---
 .../src/components/TestBackgroundShortcut.tsx | 33 ---------------
 5 files changed, 3 insertions(+), 94 deletions(-)
 delete mode 100644 docs/src/components/TestBackgroundShortcut.tsx

diff --git a/docs/src/app/(docs)/layout.tsx b/docs/src/app/(docs)/layout.tsx
index ee254a96f50..26a24155378 100644
--- a/docs/src/app/(docs)/layout.tsx
+++ b/docs/src/app/(docs)/layout.tsx
@@ -10,7 +10,6 @@ import * as SideNav from 'docs/src/components/SideNav';
 import * as QuickNav from 'docs/src/components/QuickNav/QuickNav';
 import { Header, titleMap } from 'docs/src/components/Header';
 import { MAIN_CONTENT_ID } from 'docs/src/components/SkipNav';
-import { TestBackgroundShortcut } from 'docs/src/components/TestBackgroundShortcut';
 import { sitemap } from 'docs/src/app/sitemap';
 
 const showPrivatePages = process.env.SHOW_PRIVATE_PAGES === 'true';
@@ -50,7 +49,6 @@ export default function Layout({ children }: React.PropsWithChildren) {
         />
       </head>
       <body suppressHydrationWarning>
-        <TestBackgroundShortcut />
         <GoogleAnalytics>
           <DocsProviders>
             <div className="RootLayout">
diff --git a/docs/src/app/(website)/layout.tsx b/docs/src/app/(website)/layout.tsx
index dc1c614c495..75ff11a7ac3 100644
--- a/docs/src/app/(website)/layout.tsx
+++ b/docs/src/app/(website)/layout.tsx
@@ -7,7 +7,6 @@ import type { Metadata, Viewport } from 'next/types';
 import { GoogleAnalytics } from 'docs/src/components/GoogleAnalytics';
 import { Link } from 'docs/src/components/Link';
 import { Logo } from 'docs/src/components/Logo';
-import { TestBackgroundShortcut } from 'docs/src/components/TestBackgroundShortcut';
 
 export default function Layout({ children }: React.PropsWithChildren) {
   return (
@@ -30,53 +29,14 @@ export default function Layout({ children }: React.PropsWithChildren) {
         />
       </head>
       <body suppressHydrationWarning className="Body bui-p-6 bp2:bui-py-7 bp2:bui-px-9">
-        <TestBackgroundShortcut />
         <GoogleAnalytics>
           <div
             className="bui-bs-bb bui-d-g bui-gtc-8 bui-g-8 bp2:bui-g-9"
             style={{
-              isolation: 'isolate',
               maxWidth: '1480px',
               marginInline: 'auto',
-              position: 'relative',
             }}
           >
-            <div
-              aria-hidden="true"
-              className="bui-gcs-1 bui-gce-9 bp2:bui-gce-3"
-              style={{
-                backgroundColor: 'var(--test-bg)',
-                insetBlock: 0,
-                insetInline: 0,
-                pointerEvents: 'none',
-                position: 'absolute',
-                zIndex: -1,
-              }}
-            ></div>
-            <div
-              aria-hidden="true"
-              className="bui-d-n bp2:bui-d-b bui-gcs-3 bui-gce-7"
-              style={{
-                backgroundColor: 'var(--test-bg)',
-                insetBlock: 0,
-                insetInline: 0,
-                pointerEvents: 'none',
-                position: 'absolute',
-                zIndex: -1,
-              }}
-            ></div>
-            <div
-              aria-hidden="true"
-              className="bui-d-n bp2:bui-d-b bui-gcs-7 bui-gce-9"
-              style={{
-                backgroundColor: 'var(--test-bg)',
-                insetBlock: 0,
-                insetInline: 0,
-                pointerEvents: 'none',
-                position: 'absolute',
-                zIndex: -1,
-              }}
-            ></div>
             <header className="bui-d-c">
               <div className="bui-gcs-1 bui-gce-4">
                 <Logo aria-label="Base UI" />
diff --git a/docs/src/components/QuickNav/QuickNav.tsx b/docs/src/components/QuickNav/QuickNav.tsx
index 746e452c961..9f1b63d7302 100644
--- a/docs/src/components/QuickNav/QuickNav.tsx
+++ b/docs/src/components/QuickNav/QuickNav.tsx
@@ -11,23 +11,12 @@ export function Container({ className, ...props }: React.ComponentProps<'div'>)
 }
 
 export function Content({ className, ...props }: React.ComponentProps<'div'>) {
-  return (
-    <div
-      className={clsx('QuickNavContent', className)}
-      {...props}
-      style={{ backgroundColor: 'var(--test-bg)' }}
-    />
-  );
+  return <div className={clsx('QuickNavContent', className)} {...props} />;
 }
 
 export function Root({ children, className, ...props }: React.ComponentProps<'div'>) {
   return (
-    <nav
-      aria-label="On this page"
-      className={clsx('QuickNavRoot', className)}
-      {...props}
-      style={{ backgroundColor: 'var(--test-bg)' }}
-    >
+    <nav aria-label="On this page" className={clsx('QuickNavRoot', className)} {...props}>
       <div className="QuickNavInner">
         <ScrollArea.Root>
           <ScrollArea.Viewport className="QuickNavViewport">{children}</ScrollArea.Viewport>
diff --git a/docs/src/components/SideNav.tsx b/docs/src/components/SideNav.tsx
index c4ffe0ddea0..3a346c81712 100644
--- a/docs/src/components/SideNav.tsx
+++ b/docs/src/components/SideNav.tsx
@@ -10,12 +10,7 @@ import './SideNav.css';
 
 export function Root(props: React.ComponentProps<'div'>) {
   return (
-    <nav
-      aria-label="Main navigation"
-      {...props}
-      className={clsx('SideNavRoot', props.className)}
-      style={{ backgroundColor: 'var(--test-bg)' }}
-    >
+    <nav aria-label="Main navigation" {...props} className={clsx('SideNavRoot', props.className)}>
       <ScrollArea.Root>
         <ScrollArea.Viewport data-side-nav-viewport className="SideNavViewport">
           {props.children}
diff --git a/docs/src/components/TestBackgroundShortcut.tsx b/docs/src/components/TestBackgroundShortcut.tsx
deleted file mode 100644
index b4a6fecdc79..00000000000
--- a/docs/src/components/TestBackgroundShortcut.tsx
+++ /dev/null
@@ -1,33 +0,0 @@
-import * as React from 'react';
-import Script from 'next/script';
-
-export function TestBackgroundShortcut() {
-  return (
-    <Script id="test-background-shortcut" strategy="afterInteractive">
-      {`
-        (() => {
-          if (window.__baseUiTestBackgroundShortcut) {
-            return;
-          }
-
-          window.__baseUiTestBackgroundShortcut = true;
-
-          window.addEventListener(
-            'keydown',
-            (event) => {
-              if (event.metaKey && event.code === 'KeyB') {
-                event.preventDefault();
-
-                const root = document.documentElement;
-                const currentValue = root.style.getPropertyValue('--test-bg').trim();
-
-                root.style.setProperty('--test-bg', currentValue === 'lightgreen' ? '' : 'lightgreen');
-              }
-            },
-            { capture: true },
-          );
-        })();
-      `}
-    </Script>
-  );
-}

From 29e9ca99c165fae779e0f20cfefac1f6b4b15316 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 11:17:10 +0200
Subject: [PATCH 14/33] Avoid focus ring being cut

---
 docs/src/components/SideNav.css | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/src/components/SideNav.css b/docs/src/components/SideNav.css
index 65854c64c14..6b3b51c3dc0 100644
--- a/docs/src/components/SideNav.css
+++ b/docs/src/components/SideNav.css
@@ -130,7 +130,7 @@
     &:focus-visible {
       z-index: 1;
       outline: 2px solid var(--gray-t2);
-      outline-offset: -1px;
+      outline-offset: -2px;
     }
   }
 

From 8e13a47aa1db6d1e5656db634c7f7bf6bcc672b0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 13:13:54 +0200
Subject: [PATCH 15/33] Prevent show/hide code button from obscuring the code

---
 docs/src/components/Demo/Demo.css | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/docs/src/components/Demo/Demo.css b/docs/src/components/Demo/Demo.css
index bc1e63f1643..d10232f8e06 100644
--- a/docs/src/components/Demo/Demo.css
+++ b/docs/src/components/Demo/Demo.css
@@ -200,7 +200,7 @@
       .DemoCollapseButton {
         position: absolute;
         left: 50%;
-        bottom: 0.75rem;
+        bottom: 0.5rem;
         transform: translateX(-50%);
       }
     }
@@ -208,10 +208,9 @@
     &[data-open] {
       .DemoCollapseButton {
         position: sticky;
-        bottom: 0.75rem;
+        bottom: 0.5rem;
         align-self: center;
-        margin-top: -2.25rem;
-        margin-bottom: 0.75rem;
+        margin-bottom: 0.5rem;
       }
     }
 

From 5c21cc4d6e08793e49bcfea5a417e25f0f774ae9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 14:51:04 +0200
Subject: [PATCH 16/33] Include show/hide code button in scrolling container

---
 docs/src/components/Demo/Demo.css          |  5 +++
 docs/src/components/Demo/DemoCodeBlock.tsx | 43 +++++++++++-----------
 2 files changed, 26 insertions(+), 22 deletions(-)

diff --git a/docs/src/components/Demo/Demo.css b/docs/src/components/Demo/Demo.css
index d10232f8e06..8edb6c8821c 100644
--- a/docs/src/components/Demo/Demo.css
+++ b/docs/src/components/Demo/Demo.css
@@ -215,6 +215,11 @@
     }
 
     &[data-compact]:not([data-open]) {
+      .DemoCodeBlockRoot::before,
+      .DemoCodeBlockViewport {
+        display: none;
+      }
+
       .DemoCollapseButton {
         align-self: center;
         margin-block: 0.5rem;
diff --git a/docs/src/components/Demo/DemoCodeBlock.tsx b/docs/src/components/Demo/DemoCodeBlock.tsx
index eca31b9b704..197dc48532e 100644
--- a/docs/src/components/Demo/DemoCodeBlock.tsx
+++ b/docs/src/components/Demo/DemoCodeBlock.tsx
@@ -62,22 +62,29 @@ export function DemoCodeBlock({
       data-open={collapsibleOpen ? '' : undefined}
       data-compact={compact ? '' : undefined}
     >
-      <Root
-        render={
-          <Collapsible.Panel
-            keepMounted={compact ? undefined : true}
-            hidden={compact ? undefined : false}
-          />
-        }
-      >
-        <ScrollArea.Viewport
-          aria-hidden={!collapsibleOpen}
-          data-closed={collapsibleOpen ? undefined : ''}
-          className="DemoCodeBlockViewport"
-          {...(!collapsibleOpen && { tabIndex: undefined, style: { overflow: undefined } })}
+      <Root data-closed={collapsibleOpen ? undefined : ''}>
+        <Collapsible.Panel
+          keepMounted={compact ? undefined : true}
+          hidden={compact ? undefined : false}
+          render={
+            <ScrollArea.Viewport
+              aria-hidden={!collapsibleOpen}
+              data-closed={collapsibleOpen ? undefined : ''}
+              className="DemoCodeBlockViewport"
+              {...(!collapsibleOpen && { tabIndex: undefined, style: { overflow: undefined } })}
+            />
+          }
         >
           <div className="DemoSourceBrowser">{selectedFile}</div>
-        </ScrollArea.Viewport>
+        </Collapsible.Panel>
+
+        <Collapsible.Trigger
+          ref={collapsibleTriggerRef}
+          className="DemoCollapseButton"
+          data-sticky={collapsibleOpen ? '' : undefined}
+        >
+          {collapsibleOpen ? 'Hide' : 'Show'} code
+        </Collapsible.Trigger>
 
         {collapsibleOpen && (
           <React.Fragment>
@@ -87,14 +94,6 @@ export function DemoCodeBlock({
           </React.Fragment>
         )}
       </Root>
-
-      <Collapsible.Trigger
-        ref={collapsibleTriggerRef}
-        className="DemoCollapseButton"
-        data-sticky={collapsibleOpen ? '' : undefined}
-      >
-        {collapsibleOpen ? 'Hide' : 'Show'} code
-      </Collapsible.Trigger>
     </div>
   );
 }

From f923fa12279e67912a53613c5ed8d79042ef7a38 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 14:54:59 +0200
Subject: [PATCH 17/33] Fix gradient obscuring the border

---
 docs/src/components/Demo/Demo.css | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/src/components/Demo/Demo.css b/docs/src/components/Demo/Demo.css
index 8edb6c8821c..0a3c2be5b34 100644
--- a/docs/src/components/Demo/Demo.css
+++ b/docs/src/components/Demo/Demo.css
@@ -243,6 +243,8 @@
         bottom: 0;
         left: 0;
         right: 0;
+        border-bottom-left-radius: calc(var(--radius-12) - 1px);
+        border-bottom-right-radius: calc(var(--radius-12) - 1px);
         background: linear-gradient(to bottom, rgb(255 255 255 / 0), rgb(255 255 255 / 60%));
       }
 

From f649b178cf896b2909aa75b418643f204c04543d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 15:20:56 +0200
Subject: [PATCH 18/33] Prettier floating button

---
 docs/src/components/Demo/Demo.css | 61 ++++++++++++++++++++++++-------
 1 file changed, 47 insertions(+), 14 deletions(-)

diff --git a/docs/src/components/Demo/Demo.css b/docs/src/components/Demo/Demo.css
index 0a3c2be5b34..58f4f066f8d 100644
--- a/docs/src/components/Demo/Demo.css
+++ b/docs/src/components/Demo/Demo.css
@@ -312,28 +312,42 @@
   }
 
   .DemoCollapseButton {
-    font-size: var(--font-size-13);
-    line-height: 1.25rem;
-    font-weight: var(--font-weight-400);
-    background-color: white;
-    cursor: default;
+    position: relative;
     display: inline-flex;
     align-items: center;
     justify-content: center;
+    flex-shrink: 0;
+    gap: var(--space-8);
+    border: none;
     color: var(--color-foreground);
-    height: 2rem;
-    padding-inline: 0.75rem;
-    border: 1px solid var(--gray-c2);
-    border-radius: var(--radius-pill);
-    background-clip: padding-box;
-    position: relative;
+    font-family: inherit;
+    font-size: var(--font-size-13);
+    font-weight: 500;
+    line-height: 1;
+    vertical-align: top;
+    height: var(--space-28);
+    padding-inline: var(--space-12);
+    border-radius: var(--radius-8);
+    background: linear-gradient(to bottom, hsl(0deg 0% 0% / 8%), hsl(0deg 0% 0% / 16%));
     white-space: nowrap;
     z-index: 2;
     -webkit-user-select: none;
     user-select: none;
+    -webkit-tap-highlight-color: transparent;
 
-    @media (prefers-color-scheme: dark) {
-      background-color: var(--gray-c2);
+    &::before {
+      content: '';
+      position: absolute;
+      z-index: -1;
+      inset: 1px;
+      border-radius: calc(var(--radius-8) - 1px);
+      background: linear-gradient(to bottom, white 25%, hsl(0deg 0% 98%));
+      pointer-events: none;
+      box-shadow:
+        inset 0 0 0 1px white,
+        0 1px 1px hsl(0deg 0% 0% / 4%),
+        0 1px 2px hsl(0deg 0% 0% / 4%),
+        0 2px 4px -2px hsl(0deg 0% 0% / 4%);
     }
 
     &[data-sticky] {
@@ -342,7 +356,26 @@
 
     @media (hover: hover) {
       &:hover {
-        background-color: var(--gray-s2);
+        background: linear-gradient(to bottom, hsl(0deg 0% 0% / 16%), hsl(0deg 0% 0% / 32%));
+      }
+    }
+
+    @media (prefers-color-scheme: dark) {
+      background: linear-gradient(to bottom, hsl(0deg 0% 100% / 16%), hsl(0deg 0% 100% / 24%));
+
+      &::before {
+        background: linear-gradient(to bottom, var(--gray-c2), var(--gray-c1));
+        box-shadow:
+          inset 0 0 0 1px hsl(0deg 0% 100% / 8%),
+          0 1px 1px hsl(0deg 0% 0% / 16%),
+          0 1px 2px hsl(0deg 0% 0% / 16%),
+          0 2px 4px -2px hsl(0deg 0% 0% / 24%);
+      }
+
+      @media (hover: hover) {
+        &:hover {
+          background: linear-gradient(to bottom, hsl(0deg 0% 100% / 24%), hsl(0deg 0% 100% / 36%));
+        }
       }
     }
 

From 8c17c3147aba045b6553fd10a33493f0a35bc0b5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 15:58:59 +0200
Subject: [PATCH 19/33] Tweak radius

---
 docs/src/components/Accordion.css           | 12 +++++-----
 docs/src/components/CodeBlock/CodeBlock.css | 12 +++++-----
 docs/src/components/Demo/Demo.css           | 25 +++++----------------
 docs/src/components/Table.css               |  2 +-
 4 files changed, 19 insertions(+), 32 deletions(-)

diff --git a/docs/src/components/Accordion.css b/docs/src/components/Accordion.css
index b224b9172e0..4d4037cd710 100644
--- a/docs/src/components/Accordion.css
+++ b/docs/src/components/Accordion.css
@@ -16,11 +16,11 @@
 
     border: 1px solid var(--gray-c2);
     border-collapse: separate;
-    border-radius: var(--radius-6);
+    border-radius: var(--radius-12);
   }
 
   .AccordionHeaderRow {
-    border-radius: var(--radius-6) var(--radius-6) 0 0;
+    border-radius: calc(var(--radius-12) - 1px) calc(var(--radius-12) - 1px) 0 0;
     border-bottom: 1px solid var(--gray-c2);
     background-color: var(--gray-s2);
   }
@@ -76,8 +76,8 @@
     }
 
     .AccordionItem:not([open]):last-child & {
-      border-bottom-left-radius: var(--radius-6);
-      border-bottom-right-radius: var(--radius-6);
+      border-bottom-left-radius: calc(var(--radius-12) - 1px);
+      border-bottom-right-radius: calc(var(--radius-12) - 1px);
     }
   }
 
@@ -110,8 +110,8 @@
     }
 
     .AccordionItem:last-child & {
-      border-bottom-left-radius: var(--radius-6);
-      border-bottom-right-radius: var(--radius-6);
+      border-bottom-left-radius: calc(var(--radius-12) - 1px);
+      border-bottom-right-radius: calc(var(--radius-12) - 1px);
     }
   }
 
diff --git a/docs/src/components/CodeBlock/CodeBlock.css b/docs/src/components/CodeBlock/CodeBlock.css
index 4dfcbe6cd92..91bde317b07 100644
--- a/docs/src/components/CodeBlock/CodeBlock.css
+++ b/docs/src/components/CodeBlock/CodeBlock.css
@@ -3,7 +3,7 @@
     align-self: stretch;
     background-color: var(--color-content);
     border: 1px solid var(--gray-c2);
-    border-radius: var(--radius-6);
+    border-radius: var(--radius-12);
 
     & code .frame {
       padding-left: 0.75rem;
@@ -35,8 +35,8 @@
     padding-inline-end: 0.25rem;
     height: 2.25rem;
     gap: 1rem;
-    border-top-left-radius: inherit;
-    border-top-right-radius: inherit;
+    border-top-left-radius: calc(var(--radius-12) - 1px);
+    border-top-right-radius: calc(var(--radius-12) - 1px);
     border-bottom: 1px solid var(--gray-c2);
 
     /* Scroll */
@@ -74,8 +74,8 @@
 
   .CodeBlockViewport {
     outline: 0;
-    border-bottom-right-radius: var(--radius-6);
-    border-bottom-left-radius: var(--radius-6);
+    border-bottom-right-radius: calc(var(--radius-12) - 1px);
+    border-bottom-left-radius: calc(var(--radius-12) - 1px);
     overscroll-behavior-x: contain;
 
     &:focus-visible {
@@ -126,7 +126,7 @@
   .CodeBlockPre,
   .CodeBlockRoot .CodeBlockPreInline {
     padding: 0.5rem 0;
-    border-radius: var(--radius-6);
+    border-radius: calc(var(--radius-12) - 1px);
   }
 
   .CodeBlockPreContainer {
diff --git a/docs/src/components/Demo/Demo.css b/docs/src/components/Demo/Demo.css
index 58f4f066f8d..89e01a737c8 100644
--- a/docs/src/components/Demo/Demo.css
+++ b/docs/src/components/Demo/Demo.css
@@ -2,24 +2,11 @@
 
 @layer components {
   .DemoRoot {
+    --demo-radius: var(--radius-12);
     background-color: var(--gray-s2);
     border: 1px solid var(--gray-c2);
-    border-radius: var(--radius-12);
+    border-radius: var(--demo-radius);
     margin-bottom: var(--space-24);
-
-    --shadow-1:
-      0 1px 1px 0 var(--blackA-1), 0 2px 1px -1px var(--blackA-1), 0 1px 3px 0 var(--blackA-1);
-    --shadow-2:
-      0 1px 1px 0 var(--blackA-1), 0 1px 3px -1px var(--blackA-1), 0 4px 8px -2px var(--blackA-1);
-    --shadow-3:
-      0 1px 1px 0 var(--blackA-1), 0 2px 6px -1px var(--blackA-1), 0 6px 12px -3px var(--blackA-1),
-      0 8px 16px -4px var(--blackA-1);
-    --shadow-4:
-      0 1px 1px 0 var(--blackA-1), 0 2px 4px -1px var(--blackA-1), 0 4px 8px -2px var(--blackA-1),
-      0 12px 32px -6px var(--blackA-3), 0 20px 48px -10px var(--blackA-1);
-    --shadow-5:
-      0 10px 32px var(--blackA-5), 0 1px 1px var(--blackA-1), 0 4px 6px var(--blackA-2),
-      0 1px 1px var(--blackA-2), 0 24px 68px var(--blackA-4);
   }
 
   .DemoPlaygroundExternalLink {
@@ -32,8 +19,8 @@
     position: relative;
 
     background-color: var(--color-content);
-    border-top-left-radius: var(--radius-12);
-    border-top-right-radius: var(--radius-12);
+    border-top-left-radius: calc(var(--demo-radius) - 1px);
+    border-top-right-radius: calc(var(--demo-radius) - 1px);
 
     /* Scroll */
     overflow: auto hidden;
@@ -243,8 +230,8 @@
         bottom: 0;
         left: 0;
         right: 0;
-        border-bottom-left-radius: calc(var(--radius-12) - 1px);
-        border-bottom-right-radius: calc(var(--radius-12) - 1px);
+        border-bottom-left-radius: calc(var(--demo-radius) - 1px);
+        border-bottom-right-radius: calc(var(--demo-radius) - 1px);
         background: linear-gradient(to bottom, rgb(255 255 255 / 0), rgb(255 255 255 / 60%));
       }
 
diff --git a/docs/src/components/Table.css b/docs/src/components/Table.css
index d80238cee9b..c2602e41865 100644
--- a/docs/src/components/Table.css
+++ b/docs/src/components/Table.css
@@ -5,7 +5,7 @@
     color: var(--gray-t1);
     border: 1px solid var(--gray-c2);
     border-collapse: separate;
-    border-radius: var(--radius-6);
+    border-radius: var(--radius-12);
     white-space: nowrap;
     overflow: hidden;
   }

From 139948eb035d30cf69e869d0f67b778ca4365e50 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 15:59:17 +0200
Subject: [PATCH 20/33] Fix button border on dark mode

---
 docs/src/components/Demo/Demo.css | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docs/src/components/Demo/Demo.css b/docs/src/components/Demo/Demo.css
index 89e01a737c8..2f78b706cfb 100644
--- a/docs/src/components/Demo/Demo.css
+++ b/docs/src/components/Demo/Demo.css
@@ -353,7 +353,6 @@
       &::before {
         background: linear-gradient(to bottom, var(--gray-c2), var(--gray-c1));
         box-shadow:
-          inset 0 0 0 1px hsl(0deg 0% 100% / 8%),
           0 1px 1px hsl(0deg 0% 0% / 16%),
           0 1px 2px hsl(0deg 0% 0% / 16%),
           0 2px 4px -2px hsl(0deg 0% 0% / 24%);

From 2dc1878441b5071d6baa664372949336d6760b86 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 16:03:50 +0200
Subject: [PATCH 21/33] Adjust subtitle spacing

---
 docs/src/components/Subtitle/Subtitle.css | 3 ++-
 docs/src/css/mdx-components.css           | 5 -----
 docs/src/mdx-components.tsx               | 2 +-
 3 files changed, 3 insertions(+), 7 deletions(-)

diff --git a/docs/src/components/Subtitle/Subtitle.css b/docs/src/components/Subtitle/Subtitle.css
index 1d06ff89dcf..61c58ac056c 100644
--- a/docs/src/components/Subtitle/Subtitle.css
+++ b/docs/src/components/Subtitle/Subtitle.css
@@ -7,6 +7,7 @@
     line-height: 1.75rem;
     text-wrap: pretty;
     color: var(--gray-t1);
-    margin-bottom: 1.25rem;
+    margin-bottom: 1.5rem;
+    gap: var(--space-12);
   }
 }
diff --git a/docs/src/css/mdx-components.css b/docs/src/css/mdx-components.css
index 5720045631d..7f56107ded9 100644
--- a/docs/src/css/mdx-components.css
+++ b/docs/src/css/mdx-components.css
@@ -85,11 +85,6 @@
     margin-block: 1.25rem;
   }
 
-  .MdSubtitle {
-    margin-top: -0.5rem;
-    margin-bottom: 0.5rem;
-  }
-
   .MdReferenceBlock {
     margin-top: 1.25rem;
     margin-bottom: 1.5rem;
diff --git a/docs/src/mdx-components.tsx b/docs/src/mdx-components.tsx
index 182bd9c9004..e7222e32d75 100644
--- a/docs/src/mdx-components.tsx
+++ b/docs/src/mdx-components.tsx
@@ -81,7 +81,7 @@ export const mdxComponents: MDXComponents = {
     // rendering one here would produce a duplicate.
     return null;
   },
-  Subtitle: (props) => <Subtitle className="MdSubtitle" {...props} />,
+  Subtitle: (props) => <Subtitle {...props} />,
 };
 
 export function useMDXComponents(): MDXComponents {

From f9724f2871b5a612b3b869242bb2167e7ef3bacc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 19:29:09 +0200
Subject: [PATCH 22/33] Twix

---
 docs/src/components/Header.css            |  65 ++++++----
 docs/src/components/Header.tsx            |  35 +-----
 docs/src/components/QuickNav/QuickNav.css |   2 +-
 docs/src/components/Search/SearchBar.css  | 138 +++++-----------------
 docs/src/components/Search/SearchBar.tsx  |  23 ++--
 docs/src/components/SideNav.css           |   8 +-
 docs/src/components/SideNav.tsx           |   4 +-
 docs/src/components/SkipNav.css           |   3 +-
 docs/src/css/index.css                    |   6 +
 9 files changed, 97 insertions(+), 187 deletions(-)

diff --git a/docs/src/components/Header.css b/docs/src/components/Header.css
index bc6f8d90f3e..d5161a731bf 100644
--- a/docs/src/components/Header.css
+++ b/docs/src/components/Header.css
@@ -12,13 +12,37 @@
     background-color: var(--color-content);
     z-index: 3;
 
+    @media (--lg) {
+      background-color: transparent;
+    }
+
     @media print {
       /* Prevent the header to be visible on each printed page */
       position: absolute;
     }
   }
 
+  .Header::before {
+    content: '';
+    position: absolute;
+    inset: 0;
+    display: none;
+    pointer-events: none;
+    background: linear-gradient(
+      to bottom,
+      var(--color-content) 0%,
+      color-mix(in oklab, var(--color-content), transparent 12%) 10%,
+      transparent 100%
+    );
+
+    @media (--lg) {
+      display: block;
+    }
+  }
+
   .HeaderInner {
+    position: relative;
+    z-index: 1;
     height: inherit;
     width: calc(100% - var(--root-layout-padding-inline) - var(--root-layout-padding-inline));
     max-width: var(--content-layout-max-width);
@@ -27,7 +51,9 @@
     justify-content: space-between;
     margin-inline: auto;
 
-    @media (--show-side-nav) {
+    @media (--lg) {
+      align-items: start;
+      padding-top: var(--space-32);
       padding-inline: 0;
     }
   }
@@ -37,6 +63,7 @@
     display: flex;
     align-items: center;
     gap: 0.375rem;
+    height: var(--space-32);
     padding: 0.25rem 0.5rem;
     margin: -0.25rem -0.5rem;
     border-radius: var(--radius-6);
@@ -94,10 +121,6 @@
       color: var(--gray-p1);
     }
 
-    & svg {
-      margin-top: -0.125rem;
-    }
-
     &:focus-visible {
       border-radius: var(--radius-6);
       outline: 2px solid var(--gray-t2);
@@ -107,10 +130,23 @@
 
   .HeaderDesktopActions {
     display: none;
-    gap: 1.5rem;
 
     @media (--lg) {
       display: flex;
+      justify-content: flex-end;
+      width: calc(
+        (
+            100% - var(--content-layout-gap) - var(--content-layout-gap) -
+              var(--content-layout-gap) - var(--content-layout-gap) - var(--content-layout-gap) -
+              var(--content-layout-gap) - var(--content-layout-gap)
+          ) /
+          4 + var(--content-layout-gap)
+      );
+    }
+
+    @media (--xl) {
+      justify-content: start;
+      padding-left: 0.5rem;
     }
   }
 
@@ -149,21 +185,4 @@
     height: 2px;
     background-color: currentColor;
   }
-
-  .HeaderResourceRow {
-    display: flex;
-    flex: 1;
-    align-items: baseline;
-    justify-content: space-between;
-  }
-
-  .HeaderVersion {
-    font-size: var(--font-size-14);
-    line-height: 1.375rem;
-    color: var(--gray-t1);
-  }
-
-  .HeaderGitHubIcon {
-    margin-top: -2px;
-  }
 }
diff --git a/docs/src/components/Header.tsx b/docs/src/components/Header.tsx
index 49b971ef578..e451adcc863 100644
--- a/docs/src/components/Header.tsx
+++ b/docs/src/components/Header.tsx
@@ -1,8 +1,6 @@
 import NextLink from 'next/link';
-import { GitHubIcon } from 'docs/src/icons/GitHubIcon';
 import * as MobileNav from './MobileNav';
 import { sitemap } from '../app/sitemap';
-import { NpmIcon } from '../icons/NpmIcon';
 import { Logo } from './Logo';
 import { SkipNav } from './SkipNav';
 import { Search } from './Search';
@@ -13,6 +11,7 @@ export const titleMap: Record<string, string> = {
 };
 
 export const HEADER_HEIGHT = 48;
+export const DESKTOP_HEADER_HEIGHT = 82;
 
 const showPrivatePages = process.env.SHOW_PRIVATE_PAGES === 'true';
 
@@ -26,19 +25,6 @@ export function Header() {
         </NextLink>
         <div className="HeaderDesktopActions">
           <Search containedScroll enableKeyboardShortcut />
-          <a
-            className="HeaderLink"
-            href="https://www.npmjs.com/package/@base-ui/react"
-            rel="noopener"
-            aria-label={`npm version ${process.env.LIB_VERSION}`}
-          >
-            <NpmIcon />
-            {process.env.LIB_VERSION}
-          </a>
-          <a className="HeaderLink" href="https://github.com/mui/base-ui" rel="noopener">
-            <GitHubIcon />
-            GitHub
-          </a>
         </div>
         <div className="HeaderMobileActions">
           <div className="HeaderMobileSearch">
@@ -85,25 +71,6 @@ export function Header() {
                       </MobileNav.List>
                     </MobileNav.Section>
                   ))}
-                  <MobileNav.Section>
-                    <MobileNav.Heading>Resources</MobileNav.Heading>
-                    <MobileNav.List>
-                      <MobileNav.Item
-                        href="https://www.npmjs.com/package/@base-ui/react"
-                        rel="noopener"
-                      >
-                        <NpmIcon />
-                        <span className="HeaderResourceRow">
-                          npm package
-                          <span className="HeaderVersion">{process.env.LIB_VERSION}</span>
-                        </span>
-                      </MobileNav.Item>
-                      <MobileNav.Item href="https://github.com/mui/base-ui" rel="noopener">
-                        <GitHubIcon className="HeaderGitHubIcon" />
-                        GitHub
-                      </MobileNav.Item>
-                    </MobileNav.List>
-                  </MobileNav.Section>
                 </MobileNav.Popup>
               </MobileNav.Portal>
             </MobileNav.Root>
diff --git a/docs/src/components/QuickNav/QuickNav.css b/docs/src/components/QuickNav/QuickNav.css
index 7dcbc292e74..07d5f225132 100644
--- a/docs/src/components/QuickNav/QuickNav.css
+++ b/docs/src/components/QuickNav/QuickNav.css
@@ -19,6 +19,7 @@
 
     @media (--show-side-nav) {
       grid-column: 3 / 9;
+      padding-top: 0;
     }
 
     @media (--xl) {
@@ -64,7 +65,6 @@
 
   .QuickNavViewport {
     max-height: calc(100dvh - var(--header-height));
-    padding-top: 0.75rem;
     padding-right: var(--quick-nav-scrollbar-width);
     padding-bottom: 0.75rem;
     padding-left: 0;
diff --git a/docs/src/components/Search/SearchBar.css b/docs/src/components/Search/SearchBar.css
index e1334e4ca6f..93e92ef211d 100644
--- a/docs/src/components/Search/SearchBar.css
+++ b/docs/src/components/Search/SearchBar.css
@@ -28,82 +28,51 @@
   }
 
   .SearchTrigger {
-    position: relative;
-    display: flex;
+    display: inline-flex;
     align-items: center;
-    justify-content: center;
-    gap: var(--space-8);
+    gap: 0.25rem;
     height: var(--space-32);
-    padding-inline: 0.875rem;
-    margin: 0;
-    border: none;
-    border-radius: 9999px;
-    background-color: hsl(0deg 0% 0% / 5%);
+    width: fit-content;
+    padding: 0.25rem 0.5rem;
+    margin: -0.25rem -0.5rem;
+    border: 0;
+    border-radius: var(--radius-6);
+    background: transparent;
     font: inherit;
-    font-size: var(--font-size-16);
-    font-weight: var(--font-weight-400);
-    line-height: 1.5;
-    color: var(--gray-t2);
+    font-size: var(--font-size-15);
+    line-height: 1.375rem;
+    color: currentColor;
+    text-align: left;
     -webkit-user-select: none;
     user-select: none;
-    outline: none;
-
-    @media (prefers-color-scheme: dark) {
-      background-color: var(--gray-c2);
-    }
-  }
-
-  .SearchTrigger::before {
-    content: '';
-    position: absolute;
-    inset: 1px;
-    border-radius: 9999px;
-    background-color: var(--color-popup);
-    z-index: 0;
+    outline: 0;
 
-    @media (prefers-color-scheme: dark) {
-      background-color: var(--gray-c1);
+    @media not (hover: hover) {
+      &:active {
+        color: var(--gray-p1);
+        background-color: var(--gray-c1);
+      }
     }
   }
 
-  .SearchTrigger::after {
-    content: '';
-    position: absolute;
-    inset: 1px;
-    border-radius: 9999px;
-    box-shadow: 0 1px 2px hsl(0deg 0% 0% / 5%);
-    z-index: 0;
-    pointer-events: none;
-  }
-
-  .SearchTrigger > * {
-    position: relative;
-    z-index: 1;
-  }
-
-  .SearchTrigger:hover {
-    background-color: hsl(0deg 0% 0% / 15%);
-
-    @media (prefers-color-scheme: dark) {
-      background-color: var(--gray-c3);
-    }
+  .SearchTriggerShortcut {
+    color: var(--gray-t1);
   }
 
-  .SearchTrigger:hover::before {
-    @media (prefers-color-scheme: dark) {
-      background-color: oklch(21.5% 0.5% 264deg);
-    }
+  .SearchTrigger kbd {
+    font: inherit;
   }
 
-  .SearchTrigger:hover .SearchTriggerKbd {
-    @media (prefers-color-scheme: dark) {
-      border-color: var(--gray-c3);
+  @media (hover: hover) {
+    .SearchTrigger:hover {
+      background-color: var(--gray-c1);
     }
   }
 
   .SearchTrigger:focus-visible {
+    z-index: 1;
     outline: 2px solid var(--gray-t2);
-    outline-offset: -1px;
+    outline-offset: -2px;
   }
 
   .SearchTrigger[data-disabled] {
@@ -112,58 +81,7 @@
   }
 
   .SearchTrigger[data-disabled]:hover {
-    background-color: hsl(0deg 0% 0% / 5%);
-  }
-
-  .SearchTriggerIcon {
-    width: 1rem;
-    height: 1rem;
-    color: var(--gray-p1);
-  }
-
-  .SearchTriggerKbd {
-    display: none;
-    height: 20px;
-    line-height: 1;
-    align-items: center;
-    gap: 0.25rem;
-    padding-inline: 0.375rem;
-    border-radius: 9999px;
-    border: 1px solid var(--gray-c3);
-    background-color: var(--gray-s2);
-    pointer-events: none;
-    color: var(--gray-t2);
-
-    @media (--lg) {
-      display: inline-flex;
-      margin-right: -0.5rem;
-    }
-  }
-
-  .SearchTriggerKbd kbd {
-    line-height: 1;
-  }
-
-  .SearchTriggerKbd kbd:first-child {
-    display: inline-flex;
-    margin-top: 1px;
-  }
-
-  .SearchTriggerCmd {
-    font-size: var(--font-size-18);
-  }
-
-  .SearchTriggerCtrl {
-    font-size: var(--font-size-13);
-  }
-
-  .SearchTriggerPlus {
-    font-size: var(--font-size-13);
-    color: var(--gray-t1);
-  }
-
-  .SearchTriggerK {
-    font-size: 0.8125rem;
+    background-color: transparent;
   }
 
   .SearchBreadcrumbPart {
diff --git a/docs/src/components/Search/SearchBar.tsx b/docs/src/components/Search/SearchBar.tsx
index 13576581e1c..a751521d5b1 100644
--- a/docs/src/components/Search/SearchBar.tsx
+++ b/docs/src/components/Search/SearchBar.tsx
@@ -225,7 +225,7 @@ export function SearchBar({
     }
 
     const handleKeyDown = (event: KeyboardEvent) => {
-      if ((event.metaKey || event.ctrlKey) && event.key === 'k') {
+      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') {
         event.preventDefault();
         event.stopPropagation();
 
@@ -371,19 +371,14 @@ export function SearchBar({
 
   return (
     <React.Fragment>
-      <Button onClick={handleOpenDialog} aria-label="Search" className={`SearchTrigger`}>
-        <MagnifyingGlassIcon className="SearchTriggerIcon" />
-        <div className="SearchTriggerKbd">
-          {showCmdSymbol ? (
-            <kbd className="SearchTriggerCmd">⌘</kbd>
-          ) : (
-            <React.Fragment>
-              <kbd className="SearchTriggerCtrl">Ctrl</kbd>
-              <span className="SearchTriggerPlus">+</span>
-            </React.Fragment>
-          )}
-          <kbd className="SearchTriggerK">K</kbd>
-        </div>
+      <Button onClick={handleOpenDialog} aria-label="Search" className="SearchTrigger">
+        Search
+        {enableKeyboardShortcut && (
+          <span className="SearchTriggerShortcut">
+            ({showCmdSymbol ? <kbd>⌘</kbd> : <kbd>Ctrl+</kbd>}
+            <kbd>k</kbd>)
+          </span>
+        )}
       </Button>
       <Dialog.Root open={dialogOpen} onOpenChange={handleCloseDialog}>
         <Dialog.Portal>
diff --git a/docs/src/components/SideNav.css b/docs/src/components/SideNav.css
index 6b3b51c3dc0..feacbdfa083 100644
--- a/docs/src/components/SideNav.css
+++ b/docs/src/components/SideNav.css
@@ -30,7 +30,7 @@
 
   .SideNavViewport {
     max-height: calc(100dvh - var(--header-height));
-    padding: 0.75rem 1.5rem 0.75rem 0;
+    padding: 0 1.5rem 0.75rem 0;
 
     /* Scroll containers are focusable */
     outline: 0;
@@ -41,7 +41,7 @@
       pointer-events: none;
       position: absolute;
       outline: 2px solid var(--gray-t2);
-      outline-offset: -2px;
+      outline-offset: 2px;
       /* Don't inset the outline on the right */
       right: -2px;
     }
@@ -110,6 +110,10 @@
     -webkit-user-select: none;
     user-select: none;
 
+    @media (--show-side-nav) {
+      max-width: 10rem;
+    }
+
     @media (hover: hover) {
       &:hover {
         background-color: var(--gray-s2);
diff --git a/docs/src/components/SideNav.tsx b/docs/src/components/SideNav.tsx
index 3a346c81712..766e1728a7f 100644
--- a/docs/src/components/SideNav.tsx
+++ b/docs/src/components/SideNav.tsx
@@ -5,7 +5,7 @@ import NextLink from 'next/link';
 import { usePathname } from 'next/navigation';
 import { ScrollArea } from '@base-ui/react/scroll-area';
 import scrollIntoView from 'scroll-into-view-if-needed';
-import { HEADER_HEIGHT } from './Header';
+import { DESKTOP_HEADER_HEIGHT } from './Header';
 import './SideNav.css';
 
 export function Root(props: React.ComponentProps<'div'>) {
@@ -62,7 +62,7 @@ export function Item(props: ItemProps) {
   React.useEffect(() => {
     if (ref.current && active) {
       const scrollMargin = (SCROLL_MARGIN * rem.current) / 16;
-      const headerHeight = (HEADER_HEIGHT * rem.current) / 16;
+      const headerHeight = (DESKTOP_HEADER_HEIGHT * rem.current) / 16;
       const viewport = document.querySelector('[data-side-nav-viewport]');
 
       if (!viewport) {
diff --git a/docs/src/components/SkipNav.css b/docs/src/components/SkipNav.css
index bcdd08ca5df..ae5d858dcf5 100644
--- a/docs/src/components/SkipNav.css
+++ b/docs/src/components/SkipNav.css
@@ -14,10 +14,11 @@
     &:focus-visible {
       clip: auto;
       clip-path: none;
-      height: var(--header-height);
+      height: calc(var(--header-height) - 1px);
       overflow: visible;
       width: auto;
       white-space: normal;
+      top: 1px;
       left: 0;
       z-index: 1;
       display: inline-flex;
diff --git a/docs/src/css/index.css b/docs/src/css/index.css
index 316d2a70784..1974c02762a 100644
--- a/docs/src/css/index.css
+++ b/docs/src/css/index.css
@@ -233,6 +233,12 @@
     --header-height: 3rem;
   }
 
+  @media (--lg) {
+    :root {
+      --header-height: 5.125rem;
+    }
+  }
+
   /* ═══ Dark mode overrides ═══ */
 
   @media (prefers-color-scheme: dark) {

From 8be1daaeaabd3be3da85765c4483798755b41c25 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 19:41:53 +0200
Subject: [PATCH 23/33] Fix media query

---
 docs/src/css/index.css | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/docs/src/css/index.css b/docs/src/css/index.css
index 1974c02762a..38572a85a87 100644
--- a/docs/src/css/index.css
+++ b/docs/src/css/index.css
@@ -231,10 +231,8 @@
     --ease-out-fast: cubic-bezier(0.45, 1.005, 0, 1.005);
     --ease-in-slow: cubic-bezier(0.375, 0.015, 0.545, 0.455);
     --header-height: 3rem;
-  }
 
-  @media (--lg) {
-    :root {
+    @media (--lg) {
       --header-height: 5.125rem;
     }
   }

From feb458b6f48bc111bb1f4523d1f4dcaa8cc0d363 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 19:46:11 +0200
Subject: [PATCH 24/33] Fix subtitle spacing

---
 docs/src/components/Subtitle/Subtitle.css | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/src/components/Subtitle/Subtitle.css b/docs/src/components/Subtitle/Subtitle.css
index 61c58ac056c..a0aa71eb834 100644
--- a/docs/src/components/Subtitle/Subtitle.css
+++ b/docs/src/components/Subtitle/Subtitle.css
@@ -10,4 +10,8 @@
     margin-bottom: 1.5rem;
     gap: var(--space-12);
   }
+
+  .MdH1 + .Subtitle {
+    margin-top: -0.75rem;
+  }
 }

From 334dbde260ab098ff6fa6faa615a745fe8a5193d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Thu, 28 May 2026 19:48:25 +0200
Subject: [PATCH 25/33] Make show code button pill shaped

---
 docs/src/components/Demo/Demo.css | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/src/components/Demo/Demo.css b/docs/src/components/Demo/Demo.css
index 2f78b706cfb..b9cc29a36b6 100644
--- a/docs/src/components/Demo/Demo.css
+++ b/docs/src/components/Demo/Demo.css
@@ -314,7 +314,7 @@
     vertical-align: top;
     height: var(--space-28);
     padding-inline: var(--space-12);
-    border-radius: var(--radius-8);
+    border-radius: var(--radius-pill);
     background: linear-gradient(to bottom, hsl(0deg 0% 0% / 8%), hsl(0deg 0% 0% / 16%));
     white-space: nowrap;
     z-index: 2;
@@ -327,7 +327,7 @@
       position: absolute;
       z-index: -1;
       inset: 1px;
-      border-radius: calc(var(--radius-8) - 1px);
+      border-radius: var(--radius-pill);
       background: linear-gradient(to bottom, white 25%, hsl(0deg 0% 98%));
       pointer-events: none;
       box-shadow:

From d1a2dee2158b72b87a7d0b0b301d54f7e688bff7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Fri, 29 May 2026 08:31:56 +0200
Subject: [PATCH 26/33] Fix vertical alignment on cells

---
 docs/src/components/ReferenceTable/ReferenceTable.css | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/src/components/ReferenceTable/ReferenceTable.css b/docs/src/components/ReferenceTable/ReferenceTable.css
index ef7b6abff83..c13abea0e66 100644
--- a/docs/src/components/ReferenceTable/ReferenceTable.css
+++ b/docs/src/components/ReferenceTable/ReferenceTable.css
@@ -90,8 +90,13 @@
     width: 66.6667%;
   }
 
+  .ReferenceDescriptionCell {
+    vertical-align: middle;
+  }
+
   .ReferenceDescriptionCell .TableCellInner {
     display: block;
+    min-height: 0;
     white-space: normal;
     overflow-x: visible;
   }

From 5a6996ca8c2eb0baa4251043d76fce981fecfcdb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Fri, 29 May 2026 09:39:28 +0200
Subject: [PATCH 27/33] Fix header pointer events

---
 docs/src/components/Header.css | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/docs/src/components/Header.css b/docs/src/components/Header.css
index d5161a731bf..55ffc7773b3 100644
--- a/docs/src/components/Header.css
+++ b/docs/src/components/Header.css
@@ -14,6 +14,7 @@
 
     @media (--lg) {
       background-color: transparent;
+      pointer-events: none;
     }
 
     @media print {
@@ -55,6 +56,10 @@
       align-items: start;
       padding-top: var(--space-32);
       padding-inline: 0;
+
+      > * {
+        pointer-events: auto;
+      }
     }
   }
 

From 5fbd8a66304747bc66f6b55870af79345a63c6cc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Fri, 29 May 2026 10:26:25 +0200
Subject: [PATCH 28/33] Tweak sidebars outlines

---
 docs/src/components/Header.css            |  1 -
 docs/src/components/QuickNav/QuickNav.css | 18 +++++++++++++-----
 docs/src/components/SideNav.css           |  8 +++-----
 3 files changed, 16 insertions(+), 11 deletions(-)

diff --git a/docs/src/components/Header.css b/docs/src/components/Header.css
index 55ffc7773b3..271d01973b4 100644
--- a/docs/src/components/Header.css
+++ b/docs/src/components/Header.css
@@ -151,7 +151,6 @@
 
     @media (--xl) {
       justify-content: start;
-      padding-left: 0.5rem;
     }
   }
 
diff --git a/docs/src/components/QuickNav/QuickNav.css b/docs/src/components/QuickNav/QuickNav.css
index 07d5f225132..bb78e137e3f 100644
--- a/docs/src/components/QuickNav/QuickNav.css
+++ b/docs/src/components/QuickNav/QuickNav.css
@@ -55,6 +55,9 @@
       right: var(--content-layout-inline-offset);
       bottom: 0;
       width: var(--content-layout-sidebar-width);
+      /* Avoid links' focus outline from being cut */
+      margin-top: -3px;
+      margin-left: -3px;
     }
   }
 
@@ -74,7 +77,7 @@
 
     &:focus-visible {
       outline: 2px solid var(--gray-t2);
-      outline-offset: -2px;
+      outline-offset: 1px;
     }
   }
 
@@ -125,16 +128,21 @@
     }
   }
 
+  .QuickNavViewport > .QuickNavList {
+    /* Avoid links' focus outline from being cut */
+    margin-top: 3px;
+    margin-left: 3px;
+  }
+
   .QuickNavLink {
-    display: flex;
-    padding: var(--quick-nav-item-padding-y) 0.5rem;
-    margin-inline: 0 -0.5rem;
+    display: inline-flex;
+    padding-block: var(--quick-nav-item-padding-y);
     border-radius: var(--radius-6);
 
     &:focus-visible {
       z-index: 1;
       outline: 2px solid var(--gray-t2);
-      outline-offset: -2px;
+      outline-offset: 1px;
     }
 
     @media (hover: hover) {
diff --git a/docs/src/components/SideNav.css b/docs/src/components/SideNav.css
index feacbdfa083..e9fc847cb69 100644
--- a/docs/src/components/SideNav.css
+++ b/docs/src/components/SideNav.css
@@ -37,13 +37,11 @@
 
     .SideNavRoot:has(&:focus-visible)::before {
       content: '';
-      inset: 0;
+      /* Avoid links' active state from being cut */
+      inset: 0 0 0 -3px;
       pointer-events: none;
       position: absolute;
-      outline: 2px solid var(--gray-t2);
-      outline-offset: 2px;
-      /* Don't inset the outline on the right */
-      right: -2px;
+      border: 2px solid var(--gray-t2);
     }
   }
 

From bff37caf3086b6c4befdba0bff311e3430c3d45c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Fri, 29 May 2026 10:29:54 +0200
Subject: [PATCH 29/33] Adjust padding bottom on sidebars

---
 docs/src/components/QuickNav/QuickNav.css | 2 +-
 docs/src/components/SideNav.css           | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/src/components/QuickNav/QuickNav.css b/docs/src/components/QuickNav/QuickNav.css
index bb78e137e3f..be42a461fb0 100644
--- a/docs/src/components/QuickNav/QuickNav.css
+++ b/docs/src/components/QuickNav/QuickNav.css
@@ -69,7 +69,7 @@
   .QuickNavViewport {
     max-height: calc(100dvh - var(--header-height));
     padding-right: var(--quick-nav-scrollbar-width);
-    padding-bottom: 0.75rem;
+    padding-bottom: 1.5rem;
     padding-left: 0;
 
     /* Scroll containers are focusable */
diff --git a/docs/src/components/SideNav.css b/docs/src/components/SideNav.css
index e9fc847cb69..bd09b74ba9f 100644
--- a/docs/src/components/SideNav.css
+++ b/docs/src/components/SideNav.css
@@ -30,7 +30,7 @@
 
   .SideNavViewport {
     max-height: calc(100dvh - var(--header-height));
-    padding: 0 1.5rem 0.75rem 0;
+    padding: 0 1.5rem 1.5rem 0;
 
     /* Scroll containers are focusable */
     outline: 0;

From 82214c4ffdfe523027a1caa86621f9df0ad4c06b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Fri, 29 May 2026 11:06:17 +0200
Subject: [PATCH 30/33] Remove light color scheme media queries

---
 docs/src/components/Demo/Demo.css | 18 ++++++++----------
 docs/src/components/Menu.css      | 22 +++++++++-------------
 docs/src/components/Select.css    | 23 ++++++++++-------------
 3 files changed, 27 insertions(+), 36 deletions(-)

diff --git a/docs/src/components/Demo/Demo.css b/docs/src/components/Demo/Demo.css
index b9cc29a36b6..dcf9f321e6e 100644
--- a/docs/src/components/Demo/Demo.css
+++ b/docs/src/components/Demo/Demo.css
@@ -156,19 +156,17 @@
       color: var(--color-foreground);
       font-weight: var(--font-weight-700);
       background-color: white;
-
-      @media (prefers-color-scheme: light) {
-        box-shadow:
-          0 0 1px var(--blackA-4),
-          0 0.5px 1px var(--blackA-3),
-          0 1px 3px var(--blackA-1),
-          0 2px 4px -1px var(--blackA-1),
-          0 4px 12px -2px var(--blackA-1),
-          0 4px 16px -4px var(--blackA-1);
-      }
+      box-shadow:
+        0 0 1px var(--blackA-4),
+        0 0.5px 1px var(--blackA-3),
+        0 1px 3px var(--blackA-1),
+        0 2px 4px -1px var(--blackA-1),
+        0 4px 12px -2px var(--blackA-1),
+        0 4px 16px -4px var(--blackA-1);
 
       @media (prefers-color-scheme: dark) {
         background-color: var(--gray-c2);
+        box-shadow: none;
       }
     }
 
diff --git a/docs/src/components/Menu.css b/docs/src/components/Menu.css
index b55e6142d0a..b7fa2f9786e 100644
--- a/docs/src/components/Menu.css
+++ b/docs/src/components/Menu.css
@@ -13,22 +13,18 @@
     background-color: var(--color-popup);
     overflow: hidden;
     cursor: default;
-    -webkit-user-select: none;
-    user-select: none;
     padding-block: 0.25rem;
-
     /* Make sure the layout doesn't fall apart on extreme zoom on mobile */
     min-width: min-content;
-
-    @media (prefers-color-scheme: light) {
-      box-shadow:
-        0 0 1px var(--blackA-4),
-        0 0.5px 1px var(--blackA-3),
-        0 1px 3px var(--blackA-1),
-        0 2px 4px -1px var(--blackA-1),
-        0 4px 12px -2px var(--blackA-1),
-        0 4px 16px -4px var(--blackA-1);
-    }
+    box-shadow:
+      0 0 1px var(--blackA-4),
+      0 0.5px 1px var(--blackA-3),
+      0 1px 3px var(--blackA-1),
+      0 2px 4px -1px var(--blackA-1),
+      0 4px 12px -2px var(--blackA-1),
+      0 4px 16px -4px var(--blackA-1);
+    -webkit-user-select: none;
+    user-select: none;
 
     @media (prefers-color-scheme: dark) {
       box-shadow: inset 0 0 0 1px var(--gray-c3);
diff --git a/docs/src/components/Select.css b/docs/src/components/Select.css
index 61a175bd57b..5372f873f69 100644
--- a/docs/src/components/Select.css
+++ b/docs/src/components/Select.css
@@ -13,22 +13,19 @@
     background-color: var(--color-popup);
     overflow: hidden;
     cursor: default;
-    -webkit-user-select: none;
-    user-select: none;
-    padding-block: 0.25rem;
 
+    padding-block: 0.25rem;
     /* Make sure the layout doesn't fall apart on extreme zoom on mobile */
     min-width: min-content;
-
-    @media (prefers-color-scheme: light) {
-      box-shadow:
-        0 0 1px var(--blackA-4),
-        0 0.5px 1px var(--blackA-3),
-        0 1px 3px var(--blackA-1),
-        0 2px 4px -1px var(--blackA-1),
-        0 4px 12px -2px var(--blackA-1),
-        0 4px 16px -4px var(--blackA-1);
-    }
+    box-shadow:
+      0 0 1px var(--blackA-4),
+      0 0.5px 1px var(--blackA-3),
+      0 1px 3px var(--blackA-1),
+      0 2px 4px -1px var(--blackA-1),
+      0 4px 12px -2px var(--blackA-1),
+      0 4px 16px -4px var(--blackA-1);
+    -webkit-user-select: none;
+    user-select: none;
 
     @media (prefers-color-scheme: dark) {
       box-shadow: inset 0 0 0 1px var(--gray-c3);

From 7db3c2d98fc7201f042b5e8bd0060ac51abbf2a8 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Fri, 29 May 2026 11:09:16 +0200
Subject: [PATCH 31/33] Hide demo tabs when there's only one file

---
 docs/src/components/Demo/Demo.css             | 16 ----------------
 docs/src/components/Demo/DemoFileSelector.tsx |  8 ++------
 2 files changed, 2 insertions(+), 22 deletions(-)

diff --git a/docs/src/components/Demo/Demo.css b/docs/src/components/Demo/Demo.css
index dcf9f321e6e..94ffcbaa2ac 100644
--- a/docs/src/components/Demo/Demo.css
+++ b/docs/src/components/Demo/Demo.css
@@ -111,22 +111,6 @@
     }
   }
 
-  .DemoFilename {
-    font-family: var(--font-mono);
-    color: var(--color-foreground);
-    font-weight: bold;
-    user-select: text;
-    border-radius: var(--radius-4);
-
-    &:hover {
-      text-decoration: underline;
-    }
-
-    &:focus-visible {
-      outline: 2px solid var(--gray-t2);
-    }
-  }
-
   .DemoTabsList {
     display: flex;
     gap: 2px;
diff --git a/docs/src/components/Demo/DemoFileSelector.tsx b/docs/src/components/Demo/DemoFileSelector.tsx
index 13b589370ba..20bd557a60e 100644
--- a/docs/src/components/Demo/DemoFileSelector.tsx
+++ b/docs/src/components/Demo/DemoFileSelector.tsx
@@ -57,12 +57,8 @@ export function DemoFileSelector({
     }
   }, []);
 
-  if (files.length === 1) {
-    return (
-      <a className="DemoFilename" href={files[0].slug ? `#${files[0].slug}` : undefined}>
-        {files[0].name}
-      </a>
-    );
+  if (files.length <= 1) {
+    return null;
   }
 
   return (

From a9f89789bb6c6edff3f8d73c899235f611011932 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Fri, 29 May 2026 11:38:51 +0200
Subject: [PATCH 32/33] wot

---
 docs/src/components/Demo/Demo.css | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/docs/src/components/Demo/Demo.css b/docs/src/components/Demo/Demo.css
index 94ffcbaa2ac..87049b62dab 100644
--- a/docs/src/components/Demo/Demo.css
+++ b/docs/src/components/Demo/Demo.css
@@ -85,11 +85,6 @@
 
   .DemoToolbarActions {
     position: relative;
-    /* Apply sticky only on wider viewports to avoid actions taking up most of it */
-    @media (min-width: 48rem) {
-      position: sticky;
-      padding-left: 1rem;
-    }
     right: 0;
     display: flex;
     align-items: center;
@@ -99,6 +94,12 @@
     height: 100%;
     gap: 0.25rem;
 
+    /* Apply sticky only on wider viewports to avoid actions taking up most of it */
+    @media (min-width: 48rem) {
+      position: sticky;
+      padding-left: 1rem;
+    }
+
     &::before {
       content: '';
       position: absolute;

From 4a8a91da1167b012ed0fbd7cfe2d397308474493 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Aar=C3=B3n=20Garc=C3=ADa=20Herv=C3=A1s?= <aaron@mui.com>
Date: Fri, 29 May 2026 12:20:00 +0200
Subject: [PATCH 33/33] Fix TOC alignment

---
 docs/src/components/QuickNav/QuickNav.css | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/docs/src/components/QuickNav/QuickNav.css b/docs/src/components/QuickNav/QuickNav.css
index be42a461fb0..3a6ac82cd7e 100644
--- a/docs/src/components/QuickNav/QuickNav.css
+++ b/docs/src/components/QuickNav/QuickNav.css
@@ -55,15 +55,16 @@
       right: var(--content-layout-inline-offset);
       bottom: 0;
       width: var(--content-layout-sidebar-width);
-      /* Avoid links' focus outline from being cut */
-      margin-top: -3px;
-      margin-left: -3px;
     }
   }
 
   .QuickNavInner {
     position: relative;
     width: 100%;
+
+    /* Avoid links' focus outline from being cut */
+    margin-top: -3px;
+    margin-left: -3px;
   }
 
   .QuickNavViewport {