From 351529009dff9587320a7ca9f7707519bc0d0177 Mon Sep 17 00:00:00 2001
From: Ross Lovas <rosslovas@users.noreply.github.com>
Date: Tue, 18 Aug 2026 10:33:58 +0930
Subject: [PATCH] Implement responsive navigation design

---
 src/assets/icons/bars.svg         |   3 +
 src/assets/icons/close.svg        |   3 +
 src/components/Menu.astro         |  38 ++++-
 src/components/ProfileMenu.astro  | 139 ++++++++++++++---
 src/components/TopNav.astro       | 227 ++++++++++++++++++++++++++-
 src/components/TopNavSearch.astro |  11 ++
 src/pages/components.mdx          |  41 -----
 src/scripts/modules/nav-sticky.js |   6 +
 src/scripts/top-nav-drawer.ts     | 142 +++++++++++++++++
 src/styles/button.css             |   6 +
 src/styles/main.css               |  22 +++
 tests/profile-menu.spec.ts        |  26 ++--
 tests/topnav-responsive.spec.ts   | 246 ++++++++++++++++++++++++++++++
 tests/topnav-signedin.spec.ts     |  22 +--
 14 files changed, 838 insertions(+), 94 deletions(-)
 create mode 100644 src/assets/icons/bars.svg
 create mode 100644 src/assets/icons/close.svg
 create mode 100644 src/scripts/top-nav-drawer.ts
 create mode 100644 tests/topnav-responsive.spec.ts

diff --git a/src/assets/icons/bars.svg b/src/assets/icons/bars.svg
new file mode 100644
index 0000000000..9ad10944c1
--- /dev/null
+++ b/src/assets/icons/bars.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" width="20" height="20" aria-hidden="true">
+  <path d="M2.5 5.417a.833.833 0 0 1 .833-.834h13.334a.833.833 0 0 1 0 1.667H3.333a.833.833 0 0 1-.833-.833m0 4.583a.833.833 0 0 1 .833-.833h13.334a.833.833 0 0 1 0 1.666H3.333A.833.833 0 0 1 2.5 10m0 4.583a.833.833 0 0 1 .833-.833h13.334a.833.833 0 0 1 0 1.667H3.333a.833.833 0 0 1-.833-.834" />
+</svg>
diff --git a/src/assets/icons/close.svg b/src/assets/icons/close.svg
new file mode 100644
index 0000000000..7e35d6fcd4
--- /dev/null
+++ b/src/assets/icons/close.svg
@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" width="20" height="20" aria-hidden="true">
+  <path d="M15.589 4.411a.833.833 0 0 1 0 1.178L11.178 10l4.411 4.411a.833.833 0 1 1-1.178 1.178L10 11.178l-4.411 4.411a.833.833 0 0 1-1.178-1.178L8.822 10 4.411 5.589a.833.833 0 0 1 1.178-1.178L10 8.822l4.411-4.411a.833.833 0 0 1 1.178 0" />
+</svg>
diff --git a/src/components/Menu.astro b/src/components/Menu.astro
index 5c7c58e821..0e6677760c 100644
--- a/src/components/Menu.astro
+++ b/src/components/Menu.astro
@@ -33,6 +33,8 @@ type Props = HTMLAttributes<'details'> & {
   align?: 'start' | 'end';
   density?: 'default' | 'compact';
   width?: string;
+  // Render inline rather than as a popup
+  inline?: boolean;
 };
 
 const {
@@ -41,6 +43,7 @@ const {
   align = 'start',
   density = 'default',
   width,
+  inline = false,
   class: className,
   ...rest
 } = Astro.props satisfies Props;
@@ -73,14 +76,15 @@ const iconDetails = (name: string | undefined) => {
     'menu',
     `menu--${align}`,
     density === 'compact' && 'menu--compact',
+    inline && 'menu--inline',
     className,
   ]}
-  style={width ? `--menu-width: ${width}` : undefined}
-  data-menu
+  style={width && !inline ? `--menu-width: ${width}` : undefined}
+  data-menu={inline ? undefined : ''}
   {...rest}
 >
   <slot name="trigger" />
-  <ul class="menu__list" role="menu" aria-label={label}>
+  <ul class="menu__list" role={inline ? undefined : 'menu'} aria-label={label}>
     {
       items.map((item) => {
         if (item.kind === 'divider') {
@@ -91,7 +95,7 @@ const iconDetails = (name: string | undefined) => {
           return (
             <li
               class="menu__item menu__item--detail"
-              role="presentation"
+              role={inline ? undefined : 'presentation'}
               {...item.data}
             >
               <span class="menu__label" data-menu-label>
@@ -121,11 +125,11 @@ const iconDetails = (name: string | undefined) => {
           // The list is the menu, so the items between it and the actions are
           // not part of that structure; `menuitem` goes on the action so it is
           // the thing announced and the thing arrow keys move between.
-          <li role="none">
+          <li role={inline ? undefined : 'none'}>
             <Action
               class={actionClass}
-              role="menuitem"
-              tabindex="-1"
+              role={inline ? undefined : 'menuitem'}
+              tabindex={inline ? undefined : '-1'}
               {...actionProps}
               {...item.data}
             >
@@ -351,4 +355,24 @@ const iconDetails = (name: string | undefined) => {
   img.menu__icon {
     object-fit: contain;
   }
+
+  .menu--inline .menu__list {
+    position: static;
+    position-area: none;
+    width: auto;
+    min-width: 0;
+    max-width: none;
+    margin: 0;
+    padding: 0;
+    background: none;
+    border-radius: 0;
+    box-shadow: none;
+    opacity: 1;
+    transform: none;
+    transition: none;
+  }
+
+  .menu--inline:not([open])::details-content {
+    transition: none;
+  }
 </style>
diff --git a/src/components/ProfileMenu.astro b/src/components/ProfileMenu.astro
index 3baf476518..925103c16c 100644
--- a/src/components/ProfileMenu.astro
+++ b/src/components/ProfileMenu.astro
@@ -8,6 +8,7 @@ type Props = HTMLAttributes<'div'> & {
   controlCenterHref?: string;
   profileHref?: string;
   signOutHref?: string;
+  inline?: boolean;
 };
 
 const {
@@ -18,6 +19,8 @@ const {
   // Arbitrary subpaths of /docs are blocked on the server side, returning to /docs is the best we can do
   signOutHref = 'https://octopus.com/signout?ReturnUrl=/docs',
 
+  inline = false,
+
   class: className,
   ...rest
 } = Astro.props satisfies Props;
@@ -30,32 +33,58 @@ const leaving = {
 };
 
 const items: MenuItem[] = [
-  {
-    // Details start out empty, signed-in-user.ts fills things in through Menu's hooks
-    kind: 'detail',
-    label: '',
-    description: '',
-    data: { 'data-user-details': '' },
-  },
+  // Omit name/email when inline, as they're used as the row you press to expand the menu
+  ...(inline
+    ? []
+    : [
+        {
+          // Details start out empty, signed-in-user.ts fills things in through Menu's hooks
+          kind: 'detail' as const,
+          label: '',
+          description: '',
+          data: { 'data-user-details': '' },
+        },
+      ]),
   { label: 'Control Center', href: controlCenterHref, ...leaving },
   { label: 'Profile', href: profileHref, ...leaving },
-  { kind: 'divider' },
+  ...(inline ? [] : [{ kind: 'divider' as const }]),
   { label: 'Sign out', href: signOutHref },
 ];
 ---
 
-<div class:list={['profile-menu', className]} {...rest}>
-  <Menu label={label} items={items} align="end" width="16rem">
-    <summary
-      slot="trigger"
-      class="profile-menu__trigger"
-      aria-label={label}
-      aria-haspopup="menu"
-    >
-      <Avatar size="medium" shape="circle" alt="" data-user-avatar>
-        <span data-user-initials></span>
-      </Avatar>
-    </summary>
+<div
+  class:list={['profile-menu', inline && 'profile-menu--inline', className]}
+  {...rest}
+>
+  <Menu
+    label={label}
+    items={items}
+    align="end"
+    width="16rem"
+    inline={inline}
+    density={inline ? 'compact' : 'default'}
+  >
+    {
+      inline ? (
+        <summary slot="trigger" class="profile-menu__row" data-user-details>
+          <span class="profile-menu__labels">
+            <span class="profile-menu__name" data-menu-label />
+            <span class="profile-menu__email" data-menu-description />
+          </span>
+        </summary>
+      ) : (
+        <summary
+          slot="trigger"
+          class="profile-menu__trigger"
+          aria-label={label}
+          aria-haspopup="menu"
+        >
+          <Avatar size="medium" shape="circle" alt="" data-user-avatar>
+            <span data-user-initials />
+          </Avatar>
+        </summary>
+      )
+    }
   </Menu>
 </div>
 
@@ -93,4 +122,74 @@ const items: MenuItem[] = [
     background-color: currentColor;
     mask: url('../assets/icons/external-link.svg') center / 80% no-repeat;
   }
+
+  .profile-menu--inline {
+    display: block;
+  }
+
+  .profile-menu__row {
+    display: flex;
+    align-items: center;
+    gap: var(--space8);
+    padding-block: var(--space6);
+    list-style: none;
+    color: var(--colorTextPrimary);
+    text-decoration: none;
+    cursor: pointer;
+  }
+
+  .profile-menu__row::-webkit-details-marker {
+    display: none;
+  }
+
+  .profile-menu__row:focus-visible {
+    outline: var(--borderWidth2) solid var(--colorBorderSelected);
+    outline-offset: var(--borderWidth2);
+  }
+
+  .profile-menu__labels {
+    display: flex;
+    flex: 1 1 auto;
+    flex-direction: column;
+    min-width: 0;
+    color: var(--colorTextPrimary);
+    text-decoration: none;
+  }
+
+  .profile-menu__name {
+    font: var(--textBodyRegularLarge);
+    overflow-wrap: anywhere;
+  }
+
+  .profile-menu__email {
+    color: var(--colorTextSecondary);
+    font: var(--textBodyRegularSmall);
+    overflow-wrap: anywhere;
+  }
+
+  .profile-menu__row::after {
+    content: '';
+    flex: none;
+    width: 1.25rem;
+    height: 1.25rem;
+    background-color: var(--colorIconTertiary);
+    mask: url('../assets/icons/chevron-right.svg') center / contain no-repeat;
+  }
+
+  :global([open]) > .profile-menu__row::after {
+    mask-image: url('../assets/icons/chevron-down.svg');
+  }
+
+  .profile-menu--inline :global(.menu__item) {
+    padding-inline: 0;
+    padding-block: var(--space6);
+    font: var(--textBodyRegularLarge);
+  }
+
+  .profile-menu--inline :global(.menu--inline .menu__list) {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space12);
+    margin-block-start: var(--space12);
+  }
 </style>
diff --git a/src/components/TopNav.astro b/src/components/TopNav.astro
index 99efe3a085..6b0e6b55d4 100644
--- a/src/components/TopNav.astro
+++ b/src/components/TopNav.astro
@@ -1,6 +1,7 @@
 ---
 import Logo from '../assets/octopus-logo-v2.svg';
 import Button from './Button.astro';
+import Menu, { type MenuItem } from './Menu.astro';
 import ProfileMenu from './ProfileMenu.astro';
 import TopNavSearch from './TopNavSearch.astro';
 import { SITE } from '../config';
@@ -28,6 +29,19 @@ const currentLabel = links
   .sort((a, b) => b.href.length - a.href.length)[0]?.label;
 
 const signInHref = `${SITE.url}/signin?ReturnUrl=${encodeURIComponent(Astro.url.pathname)}`;
+const startForFreeHref = 'https://octopus.com/free-signup';
+
+// When the page is narrow the links in the bar collapse into a menu; these are the menu items
+const sectionItems: MenuItem[] = links.map(({ label, href }) => ({
+  label,
+  href,
+  ...(label === currentLabel
+    ? {
+        iconEnd: 'top-nav__check-icon',
+        data: { 'aria-current': 'page' },
+      }
+    : {}),
+}));
 ---
 
 <header class="top-nav">
@@ -55,8 +69,50 @@ const signInHref = `${SITE.url}/signin?ReturnUrl=${encodeURIComponent(Astro.url.
         ))
       }
     </nav>
+    <div class="top-nav__sections">
+      <Menu label="Sections" items={sectionItems}>
+        <Button
+          slot="trigger"
+          as="summary"
+          label={currentLabel ?? links[0].label}
+          iconEnd="fa-solid fa-caret-down"
+          aria-haspopup="menu"
+        />
+      </Menu>
+    </div>
+  </div>
+
+  <div class="top-nav__panel" id="top-nav-panel" data-top-nav-panel>
+    {showSearch && <TopNavSearch lang={lang} />}
+
+    {
+      // top-nav-drawer.ts moves the site nav tree in here when the page is narrow
+    }
+    <div class="top-nav__drawer-nav" data-top-nav-nav-slot></div>
+
+    <div class="top-nav__drawer-footer">
+      <div class="top-nav__drawer-actions" data-signed-out-only>
+        <Button
+          label="Start for free"
+          href={startForFreeHref}
+          importance="loud"
+        />
+        <Button label="Sign in" href={signInHref} />
+      </div>
+      <div class="top-nav__drawer-theme">
+        <span class="top-nav__drawer-theme-label">Theme</span>
+        <Button
+          icon="theme-switcher__moon_icon"
+          aria-label="Toggle theme"
+          data-theme-toggle-button
+        />
+      </div>
+      <div class="top-nav__drawer-profile" data-signed-in-only hidden>
+        <ProfileMenu inline />
+      </div>
+    </div>
   </div>
-  {showSearch && <TopNavSearch lang={lang} />}
+
   <div class="top-nav__trailing">
     <Button
       icon="theme-switcher__moon_icon"
@@ -68,17 +124,26 @@ const signInHref = `${SITE.url}/signin?ReturnUrl=${encodeURIComponent(Astro.url.
     <Button label="Sign in" href={signInHref} data-signed-out-only />
     <Button
       label="Start for free"
-      href="https://octopus.com/free-signup"
+      href={startForFreeHref}
       importance="loud"
       data-signed-out-only
     />
     <ProfileMenu data-signed-in-only hidden />
+    <Button
+      class="top-nav__drawer-toggle"
+      icon="top-nav__bars-icon"
+      aria-label="Open navigation"
+      aria-expanded="false"
+      aria-controls="top-nav-panel"
+      data-top-nav-toggle
+    />
   </div>
 </header>
 
 <script>
   import '../scripts/signed-in-user';
   import '../scripts/theme-switcher';
+  import '../scripts/top-nav-drawer';
 </script>
 
 <style>
@@ -120,6 +185,10 @@ const signInHref = `${SITE.url}/signin?ReturnUrl=${encodeURIComponent(Astro.url.
     transition-timing-function: ease-in-out;
   }
 
+  .top-nav__panel {
+    display: contents;
+  }
+
   .top-nav__leading {
     display: flex;
     align-items: center;
@@ -186,4 +255,158 @@ const signInHref = `${SITE.url}/signin?ReturnUrl=${encodeURIComponent(Astro.url.
     color: var(--colorTextSelected);
     font: var(--textBodyBoldMedium);
   }
+
+  .top-nav__sections :global(.top-nav__check-icon) {
+    margin-inline-start: auto;
+    width: 1.25rem;
+    height: 1.25rem;
+    background-color: var(--colorIconSelected);
+    mask: url('../assets/icons/check.svg') center / contain no-repeat;
+  }
+
+  /* Hide things that are only displayed when the page is narrow by default */
+  .top-nav__sections,
+  .top-nav__drawer-nav,
+  .top-nav__drawer-footer,
+  .top-nav__drawer-toggle {
+    display: none;
+  }
+
+  @media (max-width: 1130px) {
+    .top-nav {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: var(--space16);
+    }
+
+    .top-nav__leading {
+      gap: var(--space24);
+      min-width: 0;
+      padding-inline: var(--space16);
+    }
+
+    .top-nav__logo-mark {
+      height: 1.75rem;
+    }
+
+    .top-nav__links {
+      display: none;
+    }
+
+    .top-nav__sections {
+      display: block;
+    }
+
+    .top-nav__trailing {
+      gap: var(--space8);
+      padding-inline: var(--space16);
+    }
+
+    .top-nav__trailing > :not(.top-nav__drawer-toggle),
+    .top-nav__trailing :global(.profile-menu) {
+      display: none;
+    }
+
+    .top-nav__drawer-toggle {
+      display: inline-flex;
+    }
+
+    /* The sections menu is the width of the page rather than hanging off the button that opens it */
+    .top-nav__sections :global(.menu__list) {
+      position: fixed;
+      position-area: none;
+      inset-block-start: calc(var(--header-height) - var(--space12));
+      margin-block-start: 0;
+      inset-inline: var(--space16);
+      inset-block-end: auto;
+      width: auto;
+      min-width: 0;
+      max-width: none;
+    }
+
+    .top-nav__panel {
+      position: fixed;
+      inset-block-start: var(--header-height);
+      inset-inline: 0;
+      inset-block-end: 0;
+      z-index: 9;
+      display: none;
+      grid-template-rows: auto minmax(0, 1fr) auto;
+      background: var(--colorBackgroundPrimaryDefault);
+    }
+
+    .top-nav__panel[data-open] {
+      display: grid;
+    }
+
+    .top-nav__drawer-nav {
+      display: grid;
+      grid-template-rows: minmax(0, 1fr);
+      min-height: 0;
+    }
+
+    .top-nav__drawer-nav :global(.site-nav) {
+      position: static;
+      display: grid;
+      grid-template-rows: minmax(0, 1fr);
+      align-self: stretch;
+      min-height: 0;
+      height: auto;
+      padding: 0;
+      border-inline-end: 0;
+    }
+
+    .top-nav__drawer-nav :global(.site-nav > .site-nav__list) {
+      align-self: stretch;
+      min-height: 0;
+      height: auto;
+      padding-block: var(--space8) var(--space16);
+      padding-inline: var(--space16);
+    }
+
+    .top-nav__drawer-footer {
+      display: flex;
+      flex-direction: column;
+      gap: var(--space12);
+      padding: var(--space16);
+      border-block-start: var(--borderWidth1) solid var(--colorBorderPrimary);
+    }
+
+    .top-nav__drawer-actions {
+      display: flex;
+      gap: var(--space12);
+    }
+
+    .top-nav__drawer-actions[hidden] {
+      display: none;
+    }
+
+    .top-nav__drawer-actions :global(.btn) {
+      flex: 1 1 0;
+      max-width: none;
+    }
+
+    .top-nav__drawer-theme {
+      display: flex;
+      align-items: center;
+      justify-content: space-between;
+      gap: var(--space12);
+      padding-block: var(--space6);
+    }
+
+    .top-nav__drawer-theme-label {
+      color: var(--colorTextPrimary);
+      font: var(--textBodyRegularLarge);
+    }
+
+    .top-nav__drawer-profile {
+      padding-block-start: var(--space12);
+      border-block-start: var(--borderWidth1) solid var(--colorBorderPrimary);
+    }
+
+    .top-nav__drawer-profile[hidden] {
+      display: none;
+    }
+  }
 </style>
diff --git a/src/components/TopNavSearch.astro b/src/components/TopNavSearch.astro
index 8483c2252b..1a6ab73ef6 100644
--- a/src/components/TopNavSearch.astro
+++ b/src/components/TopNavSearch.astro
@@ -148,4 +148,15 @@ const siteUrl = Astro.site ? Astro.site.href : '';
     cursor: pointer;
     caret-color: transparent;
   }
+
+  @media (max-width: 1130px) {
+    .top-nav-search.site-search__wrapper {
+      grid-column: auto;
+      padding: var(--space16);
+    }
+
+    .top-nav-search__shortcut {
+      display: none;
+    }
+  }
 </style>
diff --git a/src/pages/components.mdx b/src/pages/components.mdx
index 19c6c62fbc..8e9d24c43a 100644
--- a/src/pages/components.mdx
+++ b/src/pages/components.mdx
@@ -19,7 +19,6 @@ import Image from 'src/components/Image.astro';
 import Link from 'src/components/Link.astro';
 import DocsSearch from 'src/components/DocsSearch.astro';
 import SplitButton from 'src/components/SplitButton.astro';
-import TopNav from 'src/components/TopNav.astro';
 import sparklesIcon from 'src/assets/icons/sparkles.svg';
 import helmIcon from 'src/assets/icons/helm.svg';
 
@@ -342,46 +341,6 @@ name it with `role="img"` and an `aria-label`.
 The badge is `inline-flex`, so it sits inside a heading or a paragraph as well
 as it does on its own.
 
-### TopNav
-
-Temporary showcase for the new, work-in-progress TopNav component.
-
-{
-// Temporary hack: the nav needs more width than the cap on this page's main column, so the column takes the grid's
-// leftover space and everything except the nav is held back at the width the column normally maxes out at
-}
-
-<style>{`
-  @media (min-width: 1131px) {
-    .content-group {
-      grid-template-columns:
-        var(--navigation-width)
-        var(--grid-gap-main)
-        minmax(300px, 1fr)
-        var(--toc-offset)
-        calc(var(--toc-width) + var(--space16))
-        0;
-    }
-
-    main > :not(article),
-    article > :not(.page-content),
-    .page-content > :not(.top-nav-showcase) {
-      max-width: var(--content-width-article);
-      margin-inline: auto;
-    }
-  }
-
-  .top-nav-showcase {
-    overflow-x: auto;
-  }
-`}</style>
-
-<div class="top-nav-showcase">
-  <TopNav />
-</div>
-
-The search field in that nav opens the DocsSearch overlay documented below.
-
 ### DocsSearch
 
 The site search overlay. One instance serves the whole page: any element carrying
diff --git a/src/scripts/modules/nav-sticky.js b/src/scripts/modules/nav-sticky.js
index 312819cdc8..564266faed 100644
--- a/src/scripts/modules/nav-sticky.js
+++ b/src/scripts/modules/nav-sticky.js
@@ -59,6 +59,12 @@ function addStickyNavigation(
   function hideNavigation() {
     const navigation = qs(navigationSelector);
 
+    // Stop hiding the nav tree once the new nav's drawer is ready
+    if (document.documentElement.dataset.navDrawer === 'ready') {
+      navigation.style.display = '';
+      return;
+    }
+
     if (window.innerWidth <= 1130) {
       navigation.style.display = 'none';
     } else {
diff --git a/src/scripts/top-nav-drawer.ts b/src/scripts/top-nav-drawer.ts
new file mode 100644
index 0000000000..64ce26ac30
--- /dev/null
+++ b/src/scripts/top-nav-drawer.ts
@@ -0,0 +1,142 @@
+import { removeScroll, resetScroll } from './modules/scrollbar.js';
+
+// Matches the responsive design's collapse width breakpoint in TopNav.astro
+const COMPACT_QUERY = '(max-width: 1130px)';
+
+const PANEL_SELECTOR = '[data-top-nav-panel]';
+const TOGGLE_SELECTOR = '[data-top-nav-toggle]';
+const NAV_SLOT_SELECTOR = '[data-top-nav-nav-slot]';
+const SITE_NAV_SELECTOR = '#site-nav';
+
+const ICON_SELECTOR = '.btn__icon';
+const BARS_ICON = 'top-nav__bars-icon';
+const CLOSE_ICON = 'top-nav__close-icon';
+
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'button:not(:disabled)',
+  'input:not(:disabled)',
+  'summary',
+  '[tabindex]',
+]
+  .map((selector) => `${selector}:not([tabindex="-1"])`)
+  .join(', ');
+
+const panel = document.querySelector<HTMLElement>(PANEL_SELECTOR);
+const toggle = document.querySelector<HTMLElement>(TOGGLE_SELECTOR);
+const navSlot = document.querySelector<HTMLElement>(NAV_SLOT_SELECTOR);
+
+const siteNav = document.querySelector<HTMLElement>(SITE_NAV_SELECTOR);
+const navHome = siteNav?.parentElement ?? null;
+const navHomeNextSibling = siteNav?.nextElementSibling ?? null;
+
+const compact = window.matchMedia(COMPACT_QUERY);
+
+function isOpen() {
+  return panel?.hasAttribute('data-open') ?? false;
+}
+
+function setIcon(name: string) {
+  const icon = toggle?.querySelector(ICON_SELECTOR);
+  icon?.classList.remove(name === BARS_ICON ? CLOSE_ICON : BARS_ICON);
+  icon?.classList.add(name);
+}
+
+function open() {
+  if (!panel || !toggle || isOpen()) return;
+
+  panel.setAttribute('data-open', '');
+  toggle.setAttribute('aria-expanded', 'true');
+  toggle.setAttribute('aria-label', 'Close navigation');
+  setIcon(CLOSE_ICON);
+  removeScroll();
+}
+
+function close({ restoreFocus = false } = {}) {
+  if (!panel || !toggle || !isOpen()) return;
+
+  const hadFocus = panel.contains(document.activeElement);
+
+  panel.removeAttribute('data-open');
+  toggle.setAttribute('aria-expanded', 'false');
+  toggle.setAttribute('aria-label', 'Open navigation');
+  setIcon(BARS_ICON);
+  resetScroll();
+
+  if (restoreFocus || hadFocus) toggle.focus();
+}
+
+/** Move the nav tree between the sidebar (when wide) and the drawer (when narrow). */
+function placeNav(isCompact: boolean) {
+  if (!siteNav || !navSlot || !navHome) return;
+
+  if (isCompact) {
+    if (siteNav.parentElement !== navSlot) {
+      navSlot.append(siteNav);
+    }
+    // Undo nav-sticky.js hiding the tree
+    siteNav.style.display = '';
+  } else if (siteNav.parentElement !== navHome) {
+    navHome.insertBefore(siteNav, navHomeNextSibling);
+  }
+}
+
+function focusable() {
+  if (!panel || !toggle) return [];
+
+  const inPanel = [
+    ...panel.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+  ].filter((element) => element.offsetParent !== null);
+
+  return [toggle, ...inPanel];
+}
+
+if (panel && toggle) {
+  toggle.addEventListener('click', () => {
+    if (isOpen()) close({ restoreFocus: true });
+    else open();
+  });
+
+  // Ensure a link to a heading on the page you're already on closes the drawer
+  panel.addEventListener('click', (event) => {
+    const target = event.target;
+    if (target instanceof Element && target.closest('a[href]')) close();
+  });
+
+  document.addEventListener('keydown', (event) => {
+    if (!isOpen()) return;
+
+    if (event.key === 'Escape') {
+      // Only close the drawer if nothing else that listens for the escape key is already open
+      if (document.querySelector('[data-menu][open], dialog[open]')) return;
+      close({ restoreFocus: true });
+      return;
+    }
+
+    if (event.key !== 'Tab') return;
+
+    const elements = focusable();
+    if (elements.length === 0) return;
+
+    const first = elements[0];
+    const last = elements[elements.length - 1];
+    const active = document.activeElement as HTMLElement | null;
+
+    if (event.shiftKey && active === first) {
+      event.preventDefault();
+      last.focus();
+    } else if (!event.shiftKey && active === last) {
+      event.preventDefault();
+      first.focus();
+    }
+  });
+
+  compact.addEventListener('change', (event) => {
+    placeNav(event.matches);
+    if (!event.matches) close();
+  });
+
+  placeNav(compact.matches);
+
+  document.documentElement.dataset.navDrawer = 'ready';
+}
diff --git a/src/styles/button.css b/src/styles/button.css
index 292108cfbe..01e756d879 100644
--- a/src/styles/button.css
+++ b/src/styles/button.css
@@ -55,6 +55,12 @@ summary.btn::-webkit-details-marker {
   display: none;
 }
 
+/* Prevent the global rule that displays every anchor within a summary as a link from also affecting buttons */
+summary.btn > * {
+  color: inherit;
+  text-decoration: none;
+}
+
 .btn__label {
   padding-inline: var(--space4);
 }
diff --git a/src/styles/main.css b/src/styles/main.css
index 34d67b2b29..0277702a36 100644
--- a/src/styles/main.css
+++ b/src/styles/main.css
@@ -3085,6 +3085,28 @@ html[data-nav='new'] .new-top-nav {
 html[data-nav='new'] .site-header {
   display: none;
 }
+
+.top-nav__bars-icon,
+.top-nav__close-icon {
+  background-color: var(--colorIconPrimary);
+  mask: url('../assets/icons/bars.svg') center / contain no-repeat;
+}
+
+.top-nav__close-icon {
+  mask-image: url('../assets/icons/close.svg');
+}
+
+@media (max-width: 1130px) {
+  html[data-nav='new'][data-nav-drawer='ready'] .content-group .site-nav {
+    display: none;
+  }
+
+  html[data-nav='new'][data-nav-drawer='ready']
+    .skip-links
+    a[href='#site-nav'] {
+    display: none;
+  }
+}
 /* TopNav component end */
 
 .inline-note {
diff --git a/tests/profile-menu.spec.ts b/tests/profile-menu.spec.ts
index bb2c33d692..e5612c743f 100644
--- a/tests/profile-menu.spec.ts
+++ b/tests/profile-menu.spec.ts
@@ -1,8 +1,10 @@
 import { test, expect, type Page } from '@playwright/test';
 
-const showcase = '/components';
+const docsPage = '/docs/?newnav';
 
-const profile = '.top-nav-showcase .top-nav .profile-menu';
+// Match the full width avatar menu; the inline one used when the page narrows is tested in
+// topnav-responsive.spec.ts
+const profile = '.top-nav .profile-menu:not(.profile-menu--inline)';
 const trigger = `${profile} summary`;
 const list = `${profile} .menu__list`;
 
@@ -15,7 +17,7 @@ async function signIn(
     {
       name: 'OctopusSignedInUser',
       value: encodeURIComponent(JSON.stringify(user)),
-      url: new URL(showcase, baseURL).toString(),
+      url: new URL(docsPage, baseURL).toString(),
     },
   ]);
 }
@@ -25,21 +27,18 @@ async function signedIn(page: Page, baseURL: string | undefined) {
     fullName: 'John Doe',
     email: 'jd@example.com',
   });
-  await page.goto(showcase);
+  await page.goto(docsPage);
 }
 
 test('there is no profile menu until someone is signed in', async ({
   page,
 }) => {
-  await page.goto(showcase);
+  await page.goto(docsPage);
 
   await expect(page.locator(profile)).toBeHidden();
 });
 
-test('the avatar opens the menu', async ({
-  page,
-  baseURL,
-}) => {
+test('the avatar opens the menu', async ({ page, baseURL }) => {
   await signedIn(page, baseURL);
 
   await expect(page.locator(list)).toBeHidden();
@@ -107,9 +106,10 @@ test('sign out is drawn as plain text rather than as a link', async ({
       }));
 
   const controlCenter = await paint(0);
-  expect(controlCenter.underline, 'an ordinary link row keeps its underline').toBe(
-    'underline'
-  );
+  expect(
+    controlCenter.underline,
+    'an ordinary link row keeps its underline'
+  ).toBe('underline');
 
   const signOut = await paint(2);
   expect(signOut.underline, 'sign out should not be underlined').toBe('none');
@@ -129,7 +129,7 @@ test('the email line is dropped when there is no name', async ({
   baseURL,
 }) => {
   await signIn(page, baseURL, { email: 'jd@example.com' });
-  await page.goto(showcase);
+  await page.goto(docsPage);
   await page.locator(trigger).click();
 
   const details = page.locator(`${list} [data-user-details]`);
diff --git a/tests/topnav-responsive.spec.ts b/tests/topnav-responsive.spec.ts
new file mode 100644
index 0000000000..353d434eb4
--- /dev/null
+++ b/tests/topnav-responsive.spec.ts
@@ -0,0 +1,246 @@
+import { test, expect, type Page } from '@playwright/test';
+
+const docsPage = '/docs/?newnav';
+const sectionPage = '/docs/getting-started/?newnav';
+
+const nav = '.top-nav';
+const inlineLinks = `${nav} .top-nav__links`;
+const sectionsTrigger = `${nav} .top-nav__sections summary`;
+const sectionsList = `${nav} .top-nav__sections .menu__list`;
+const toggle = '[data-top-nav-toggle]';
+const panel = '[data-top-nav-panel]';
+const search = `${panel} .top-nav-search`;
+const drawerNav = `${panel} [data-top-nav-nav-slot] #site-nav`;
+const drawerActions = `${panel} .top-nav__drawer-actions`;
+const drawerTheme = `${panel} .top-nav__drawer-theme`;
+const drawerProfile = `${panel} .top-nav__drawer-profile`;
+
+const mobile = { width: 390, height: 844 };
+
+async function signIn(
+  page: Page,
+  baseURL: string | undefined,
+  user: Record<string, string>
+) {
+  await page.context().addCookies([
+    {
+      name: 'OctopusSignedInUser',
+      value: encodeURIComponent(JSON.stringify(user)),
+      url: new URL(docsPage, baseURL).toString(),
+    },
+  ]);
+}
+
+test.describe('top nav at narrow widths', () => {
+  test.use({ viewport: mobile });
+
+  test('collapses the bar to a logo, a sections menu, and one button', async ({
+    page,
+  }) => {
+    await page.goto(docsPage);
+
+    await expect(page.locator(`${nav} .top-nav__logo`)).toBeVisible();
+    await expect(page.locator(sectionsTrigger)).toHaveText('Docs');
+    await expect(page.locator(toggle)).toBeVisible();
+
+    // Everything the bar can no longer fit has been moved into the drawer
+    await expect(page.locator(inlineLinks)).toBeHidden();
+    await expect(page.locator(search)).toBeHidden();
+    await expect(page.locator(panel)).toBeHidden();
+    await expect(
+      page.locator(`${nav} .top-nav__trailing`).getByText('Start for free')
+    ).toBeHidden();
+  });
+
+  test('does not overflow the viewport', async ({ page }) => {
+    await page.goto(docsPage);
+
+    const overflow = await page.evaluate(
+      () =>
+        document.documentElement.scrollWidth -
+        document.documentElement.clientWidth
+    );
+    expect(overflow).toBeLessThanOrEqual(0);
+  });
+
+  test('the button opens a drawer holding search, the nav tree, and the footer', async ({
+    page,
+  }) => {
+    await page.goto(docsPage);
+
+    await expect(page.locator(toggle)).toHaveAttribute(
+      'aria-expanded',
+      'false'
+    );
+    await page.locator(toggle).click();
+
+    await expect(page.locator(toggle)).toHaveAttribute('aria-expanded', 'true');
+    await expect(page.locator(panel)).toBeVisible();
+    await expect(page.locator(search)).toBeVisible();
+    await expect(page.locator(drawerNav)).toBeVisible();
+    await expect(page.locator(drawerTheme).getByText('Theme')).toBeVisible();
+
+    // When signed out the action buttons are visible, not the profile
+    await expect(page.locator(drawerActions)).toBeVisible();
+    await expect(page.locator(drawerProfile)).toBeHidden();
+  });
+
+  test('keeps section rows expanding in place inside the drawer', async ({
+    page,
+  }) => {
+    await page.goto(sectionPage);
+    await page.locator(toggle).click();
+
+    // Find a closed page section
+    const groups = page.locator(`${drawerNav} details.site-nav__group`);
+    const count = await groups.count();
+
+    let closed = -1;
+    for (let i = 0; i < count; i++) {
+      if ((await groups.nth(i).getAttribute('open')) === null) {
+        closed = i;
+        break;
+      }
+    }
+
+    expect(
+      closed,
+      'there should be a closed section to expand'
+    ).toBeGreaterThan(-1);
+
+    const group = groups.nth(closed);
+
+    const label = group.locator('> summary > .site-nav__label');
+    const name = await label.textContent();
+
+    await expect(group).not.toHaveAttribute('open', '');
+    await label.click();
+
+    await expect(group).toHaveAttribute('open', '');
+    await expect(group.locator('> .site-nav__list')).toBeVisible();
+    await expect(label).toHaveText(name!);
+  });
+
+  test('checks the section the reader is in, in the sections menu', async ({
+    page,
+  }) => {
+    await page.goto(docsPage);
+    await page.locator(sectionsTrigger).click();
+
+    await expect(page.locator(sectionsList)).toBeVisible();
+    await expect(
+      page.locator(`${sectionsList} [aria-current="page"]`)
+    ).toHaveText('Docs');
+    await expect(
+      page.locator(`${sectionsList} [aria-current="page"] .top-nav__check-icon`)
+    ).toBeVisible();
+  });
+
+  test('closes the drawer when Escape is pressed, hands focus back to the button', async ({
+    page,
+  }) => {
+    await page.goto(docsPage);
+    await page.locator(toggle).click();
+    await expect(page.locator(panel)).toBeVisible();
+
+    await page.keyboard.press('Escape');
+
+    await expect(page.locator(panel)).toBeHidden();
+    await expect(page.locator(toggle)).toBeFocused();
+  });
+
+  test('shows the signed-in user account info in the drawer footer', async ({
+    page,
+    baseURL,
+  }) => {
+    await signIn(page, baseURL, {
+      fullName: 'John Doe',
+      email: 'jd@example.com',
+    });
+    await page.goto(docsPage);
+    await page.locator(toggle).click();
+
+    await expect(page.locator(drawerActions)).toBeHidden();
+    await expect(page.locator(drawerProfile)).toBeVisible();
+    await expect(
+      page.locator(`${drawerProfile} .profile-menu__name`)
+    ).toHaveText('John Doe');
+    await expect(
+      page.locator(`${drawerProfile} .profile-menu__email`)
+    ).toHaveText('jd@example.com');
+
+    const links = page.locator(`${drawerProfile} .menu__action`);
+    await expect(links.first()).toBeHidden();
+
+    await page.locator(`${drawerProfile} .profile-menu__row`).click();
+
+    await expect(links.first()).toBeVisible();
+    await expect(links).toHaveText([/Control Center/, /Profile/, /Sign out/]);
+  });
+
+  test('every account link in the drawer footer can be reached via keyboard', async ({
+    page,
+    baseURL,
+  }) => {
+    await signIn(page, baseURL, {
+      fullName: 'John Doe',
+      email: 'jd@example.com',
+    });
+    await page.goto(docsPage);
+    await page.locator(toggle).click();
+
+    const row = page.locator(`${drawerProfile} .profile-menu__row`);
+    await row.focus();
+    await page.keyboard.press('Enter');
+
+    const links = page.locator(`${drawerProfile} .menu__action`);
+    await expect(links.first()).toBeVisible();
+
+    for (const label of ['Control Center', 'Profile', 'Sign out']) {
+      await page.keyboard.press('Tab');
+      await expect(links.filter({ hasText: label })).toBeFocused();
+    }
+  });
+
+  test('keeps focus inside the drawer once the account menu is expanded', async ({
+    page,
+    baseURL,
+  }) => {
+    await signIn(page, baseURL, {
+      fullName: 'John Doe',
+      email: 'jd@example.com',
+    });
+    await page.goto(docsPage);
+    await page.locator(toggle).click();
+    await page.locator(`${drawerProfile} .profile-menu__row`).click();
+
+    const row = page.locator(`${drawerProfile} .profile-menu__row`);
+    await row.focus();
+
+    for (let i = 0; i < 4; i++) await page.keyboard.press('Tab');
+
+    await expect(page.locator(toggle)).toBeFocused();
+  });
+});
+
+test.describe('top nav across collapse width breakpoint', () => {
+  test('moves the nav tree between the sidebar and the drawer', async ({
+    page,
+  }) => {
+    await page.setViewportSize({ width: 1280, height: 800 });
+    await page.goto(docsPage);
+
+    const sidebar = page.locator('.content-group #site-nav');
+    await expect(sidebar).toBeVisible();
+
+    // Shrink the viewport...
+    await page.setViewportSize(mobile);
+    await expect(page.locator(drawerNav)).toHaveCount(1);
+    await expect(page.locator('.content-group #site-nav')).toHaveCount(0);
+
+    // ...then expand it again
+    await page.setViewportSize({ width: 1280, height: 800 });
+    await expect(sidebar).toBeVisible();
+    await expect(page.locator('#site-nav')).toHaveCount(1);
+  });
+});
diff --git a/tests/topnav-signedin.spec.ts b/tests/topnav-signedin.spec.ts
index 3d0471157f..22c9ed2263 100644
--- a/tests/topnav-signedin.spec.ts
+++ b/tests/topnav-signedin.spec.ts
@@ -1,8 +1,8 @@
 import { test, expect, type Page } from '@playwright/test';
 
-const showcase = '/components';
+const docsPage = '/docs/?newnav';
 
-const nav = '.top-nav-showcase .top-nav';
+const nav = '.top-nav';
 const trailing = `${nav} .top-nav__trailing`;
 const avatar = `${nav} [data-user-avatar]`;
 
@@ -15,7 +15,7 @@ async function signIn(
     {
       name: 'OctopusSignedInUser',
       value: encodeURIComponent(JSON.stringify(user)),
-      url: new URL(showcase, baseURL).toString(),
+      url: new URL(docsPage, baseURL).toString(),
     },
   ]);
 }
@@ -24,7 +24,7 @@ test.describe('top nav signed-in state', () => {
   test('shows the sign in and sign up buttons when signed out', async ({
     page,
   }) => {
-    await page.goto(showcase);
+    await page.goto(docsPage);
 
     await expect(page.locator(trailing).getByText('Sign in')).toBeVisible();
     await expect(
@@ -41,7 +41,7 @@ test.describe('top nav signed-in state', () => {
       fullName: 'John Doe',
       email: 'jd@example.com',
     });
-    await page.goto(showcase);
+    await page.goto(docsPage);
 
     await expect(page.locator(trailing).getByText('Sign in')).toBeHidden();
     await expect(
@@ -66,7 +66,7 @@ test.describe('top nav signed-in state', () => {
     baseURL,
   }) => {
     await signIn(page, baseURL, { fullName: 'John' });
-    await page.goto(showcase);
+    await page.goto(docsPage);
 
     await expect(page.locator(`${avatar} [data-user-initials]`)).toHaveText(
       'JO'
@@ -78,7 +78,7 @@ test.describe('top nav signed-in state', () => {
     baseURL,
   }) => {
     await signIn(page, baseURL, { email: 'jd@example.com' });
-    await page.goto(showcase);
+    await page.goto(docsPage);
 
     await expect(page.locator(`${avatar} [data-user-initials]`)).toHaveText(
       'JD'
@@ -96,7 +96,7 @@ test.describe('top nav signed-in state', () => {
         baseURL
       ).toString(),
     });
-    await page.goto(showcase);
+    await page.goto(docsPage);
 
     const image = page.locator(`${avatar} [data-avatar-image]`);
     const src = new URL((await image.getAttribute('src')) ?? '', baseURL);
@@ -117,7 +117,7 @@ test.describe('top nav signed-in state', () => {
         baseURL
       ).toString(),
     });
-    await page.goto(showcase);
+    await page.goto(docsPage);
 
     await expect(page.locator(`${avatar} [data-avatar-image]`)).toBeVisible();
     await expect(page.locator(`${avatar} [data-avatar-fallback]`)).toBeHidden();
@@ -134,7 +134,7 @@ test.describe('top nav signed-in state', () => {
         baseURL
       ).toString(),
     });
-    await page.goto(showcase);
+    await page.goto(docsPage);
 
     await expect(
       page.locator(`${avatar} [data-avatar-fallback]`)
@@ -147,7 +147,7 @@ test.describe('top nav signed-in state', () => {
       fullName: 'John Doe',
       profileImageUrl: 'javascript:alert(1)',
     });
-    await page.goto(showcase);
+    await page.goto(docsPage);
 
     await expect(
       page.locator(`${avatar} [data-avatar-fallback]`)