From d5219c7e9ed2d59406363e0c5a959cfb0df99292 Mon Sep 17 00:00:00 2001
From: btea <2356281422@qq.com>
Date: Fri, 31 Jul 2026 12:11:42 +0800
Subject: [PATCH 1/3] feat(web): make the top navigation bar sticky

---
 .changeset/sticky-navigation-bar.md           |  5 +++
 .../web/ui/components/MetaBar/index.jsx       |  3 ++
 .../generators/web/ui/components/NavBar.jsx   | 36 ++++++++++---------
 packages/core/src/generators/web/ui/index.css | 19 ++++++++++
 4 files changed, 46 insertions(+), 17 deletions(-)
 create mode 100644 .changeset/sticky-navigation-bar.md

diff --git a/.changeset/sticky-navigation-bar.md b/.changeset/sticky-navigation-bar.md
new file mode 100644
index 00000000..fd4dedfc
--- /dev/null
+++ b/.changeset/sticky-navigation-bar.md
@@ -0,0 +1,5 @@
+---
+'@node-core/doc-kit': minor
+---
+
+Make the web top navigation bar sticky while scrolling, and offset the sticky meta bar, anchor scrolling, and Radix popups so they are not covered by it
diff --git a/packages/core/src/generators/web/ui/components/MetaBar/index.jsx b/packages/core/src/generators/web/ui/components/MetaBar/index.jsx
index 261498ea..b234522b 100644
--- a/packages/core/src/generators/web/ui/components/MetaBar/index.jsx
+++ b/packages/core/src/generators/web/ui/components/MetaBar/index.jsx
@@ -62,6 +62,9 @@ export default ({ metadata, headings = [], readingTime }) => {
   return (
     <MetaBar
       heading="Table of Contents"
+      // Offset the sticky position by the sticky navigation bar's height,
+      // otherwise the navigation bar covers the top of the meta bar
+      style={{ top: 'var(--header-height)' }}
       headings={{
         items: headings.map(({ value, stability, ...heading }) => ({
           ...heading,
diff --git a/packages/core/src/generators/web/ui/components/NavBar.jsx b/packages/core/src/generators/web/ui/components/NavBar.jsx
index c0484e80..c0f8b8f9 100644
--- a/packages/core/src/generators/web/ui/components/NavBar.jsx
+++ b/packages/core/src/generators/web/ui/components/NavBar.jsx
@@ -16,23 +16,25 @@ export default ({ metadata }) => {
   const [themePreference, setThemePreference] = useTheme();
 
   return (
-    <NavBar
-      Logo={Logo}
-      sidebarItemTogglerAriaLabel="Toggle navigation menu"
-      navItems={[]}
-    >
-      {showSearchBox && <SearchBox pathname={metadata.path} />}
-      <ThemeToggle
-        onChange={setThemePreference}
-        currentTheme={themePreference}
-      />
-      <a
-        href={`https://github.com/${repository}`}
-        aria-label={`View ${repository} on GitHub`}
-        className={styles.ghIconWrapper}
+    <div className="nav-bar-sticky">
+      <NavBar
+        Logo={Logo}
+        sidebarItemTogglerAriaLabel="Toggle navigation menu"
+        navItems={[]}
       >
-        <GitHubIcon />
-      </a>
-    </NavBar>
+        {showSearchBox && <SearchBox pathname={metadata.path} />}
+        <ThemeToggle
+          onChange={setThemePreference}
+          currentTheme={themePreference}
+        />
+        <a
+          href={`https://github.com/${repository}`}
+          aria-label={`View ${repository} on GitHub`}
+          className={styles.ghIconWrapper}
+        >
+          <GitHubIcon />
+        </a>
+      </NavBar>
+    </div>
   );
 };
diff --git a/packages/core/src/generators/web/ui/index.css b/packages/core/src/generators/web/ui/index.css
index 1b375458..27d25efa 100644
--- a/packages/core/src/generators/web/ui/index.css
+++ b/packages/core/src/generators/web/ui/index.css
@@ -10,6 +10,25 @@
   --font-ibm-plex-mono: 'IBM Plex Mono', monospace;
 }
 
+/* Keep the top navigation bar visible while scrolling */
+.nav-bar-sticky {
+  position: sticky;
+  top: 0;
+  z-index: 40;
+}
+
+/* Radix popups (theme switcher, selects) must paint above the sticky
+   navigation bar; they render in a portal and slightly overlap the bar.
+   `!important` is needed because Radix sets an inline `z-index: auto` */
+[data-radix-popper-content-wrapper] {
+  z-index: 50 !important;
+}
+
+/* Keep anchored headings below the sticky navigation bar */
+main [id] {
+  scroll-margin-top: calc(var(--header-height, 4rem) + 1rem);
+}
+
 main {
   /* Code should inherit its font size */
   code {

From 3c242816890be6e7106571846f8d954b91a9065e Mon Sep 17 00:00:00 2001
From: btea <2356281422@qq.com>
Date: Fri, 31 Jul 2026 12:48:03 +0800
Subject: [PATCH 2/3] fix: apply review

---
 .../core/src/generators/web/ui/components/MetaBar/index.jsx | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/core/src/generators/web/ui/components/MetaBar/index.jsx b/packages/core/src/generators/web/ui/components/MetaBar/index.jsx
index b234522b..6ddf4643 100644
--- a/packages/core/src/generators/web/ui/components/MetaBar/index.jsx
+++ b/packages/core/src/generators/web/ui/components/MetaBar/index.jsx
@@ -63,8 +63,10 @@ export default ({ metadata, headings = [], readingTime }) => {
     <MetaBar
       heading="Table of Contents"
       // Offset the sticky position by the sticky navigation bar's height,
-      // otherwise the navigation bar covers the top of the meta bar
-      style={{ top: 'var(--header-height)' }}
+      // otherwise the navigation bar covers the top of the meta bar.
+      // `--header-height` comes from `@node-core/ui-components` base styles;
+      // fall back to its current value (4rem) in case it is ever renamed
+      style={{ top: 'var(--header-height, 4rem)' }}
       headings={{
         items: headings.map(({ value, stability, ...heading }) => ({
           ...heading,

From bc8cf119bb5441b63be76318e4ed7c1ed95d04d0 Mon Sep 17 00:00:00 2001
From: btea <2356281422@qq.com>
Date: Fri, 31 Jul 2026 13:09:06 +0800
Subject: [PATCH 3/3] fix(web): clip overflowing hidden sidebar toggler in
 sticky nav

The NavBar's invisible mobile menu checkbox is translated 200% above the
bar. Inside the sticky wrapper's stacking context it painted above the
announcement banner and intercepted clicks on its close button.
---
 packages/core/src/generators/web/ui/index.css | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/core/src/generators/web/ui/index.css b/packages/core/src/generators/web/ui/index.css
index 27d25efa..e053f252 100644
--- a/packages/core/src/generators/web/ui/index.css
+++ b/packages/core/src/generators/web/ui/index.css
@@ -10,11 +10,14 @@
   --font-ibm-plex-mono: 'IBM Plex Mono', monospace;
 }
 
-/* Keep the top navigation bar visible while scrolling */
+/* Keep the top navigation bar visible while scrolling. The hidden sidebar
+   toggler checkbox inside the NavBar is translated above the bar, so clip it:
+   inside this stacking context it would otherwise cover the banner above */
 .nav-bar-sticky {
   position: sticky;
   top: 0;
   z-index: 40;
+  overflow: hidden;
 }
 
 /* Radix popups (theme switcher, selects) must paint above the sticky