From 27a4421d6e1c5d2ba3d87e327983c405cef06d93 Mon Sep 17 00:00:00 2001
From: Anthony Lio <lionnet.ant@gmail.com>
Date: Tue, 1 Sep 2026 22:04:41 +0300
Subject: [PATCH] fix(docs): stop sidebar from jumping on scroll (#49807)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## What kind of change does this PR introduce?

bug fix to stop sidebar jump on scroll within docs

## What is the current behavior?

the docs sidebar shifts up by 1px as soon as scrolling start as the top
bar height include bottom border causing the jump as height token differ
from the whole height

## What is the new behavior?

favor box shadow instead of a border for the bottom line, so height
matches the token and nothing needs to compensate any more which allows
to remove some `+1px` elsewhere

+ also drops a nested `lg:sticky` in the sidebar that did nothing inside
an already-sticky parent

| state | preview |
| -------|------|
| before | <video
src="https://github.com/user-attachments/assets/b4bbfa2d-6595-4711-bb2b-bd2bf3aded8a"
/> |
| after | <video
src="https://github.com/user-attachments/assets/f044aebc-ef14-42c1-8564-3b290399d00b"
/> |

## Additional context

- header now uses the existing `subhighlight-border` utility, which was
not used anywhere else it seems, could also be renamed?
- could be down the other way by keeping border and fixing the jump

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Bug Fixes**
* Improved documentation navigation alignment by removing unnecessary
spacing from sticky sidebars, table of contents, and section headings.
* Updated desktop navigation behavior for more consistent scrolling and
viewport layout.
* Refined the top navigation bar’s border styling for a cleaner
appearance.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 apps/docs/app/contributing/ContributingToC.tsx              | 2 +-
 .../docs/components/Navigation/NavigationMenu/TopNavBar.tsx | 2 +-
 apps/docs/features/docs/GuidesMdx.template.tsx              | 3 +--
 apps/docs/features/ui/guide/Guide.tsx                       | 3 +--
 apps/docs/layouts/MainSkeleton.tsx                          | 6 +++---
 apps/docs/layouts/ref/RefSubLayout.tsx                      | 2 +-
 6 files changed, 8 insertions(+), 10 deletions(-)

diff --git a/apps/docs/app/contributing/ContributingToC.tsx b/apps/docs/app/contributing/ContributingToC.tsx
index 12b19d20dfc..5208a236516 100644
--- a/apps/docs/app/contributing/ContributingToC.tsx
+++ b/apps/docs/app/contributing/ContributingToC.tsx
@@ -39,7 +39,7 @@ export function ContributingToc({ className }: { className?: string }) {
         '[--local-top-spacing:5rem]',
         'border-l thin-scrollbar overflow-y-auto px-2 hidden lg:block',
         'col-span-3 self-start sticky',
-        'top-[calc(var(--header-height)+1px+2rem)] max-h-[calc(100vh-var(--header-height)-3rem)]',
+        'top-[calc(var(--header-height)+2rem)] max-h-[calc(100vh-var(--header-height)-3rem)]',
         className
       )}
     />
diff --git a/apps/docs/components/Navigation/NavigationMenu/TopNavBar.tsx b/apps/docs/components/Navigation/NavigationMenu/TopNavBar.tsx
index 3791cb923fa..4e5312c9091 100644
--- a/apps/docs/components/Navigation/NavigationMenu/TopNavBar.tsx
+++ b/apps/docs/components/Navigation/NavigationMenu/TopNavBar.tsx
@@ -33,7 +33,7 @@ const TopNavBar: FC = () => {
     <>
       <nav
         aria-label="top bar"
-        className="w-full z-40 flex flex-col border-b backdrop-blur-sm backdrop-filter bg-default/75"
+        className="w-full z-40 flex flex-col subhighlight-border backdrop-blur-sm backdrop-filter bg-default/75"
       >
         <div className="w-full px-5 lg:pl-10 flex justify-between h-(--header-height) gap-3">
           <div className="hidden lg:flex h-full items-center justify-center gap-2">
diff --git a/apps/docs/features/docs/GuidesMdx.template.tsx b/apps/docs/features/docs/GuidesMdx.template.tsx
index 0a3786630b6..142ecea3b72 100644
--- a/apps/docs/features/docs/GuidesMdx.template.tsx
+++ b/apps/docs/features/docs/GuidesMdx.template.tsx
@@ -143,10 +143,9 @@ const GuideTemplate = ({
             'sticky',
             /**
              * --header-height: height of nav
-             * 1px: height of nav border
              * 3rem: content padding
              */
-            'top-[calc(var(--header-height)+1px+3rem)]',
+            'top-[calc(var(--header-height)+3rem)]',
             // 4rem accounts for 3rem of top padding + 1rem of extra breathing room
             'max-h-[calc(100vh-var(--header-height)-4rem)]'
           )}
diff --git a/apps/docs/features/ui/guide/Guide.tsx b/apps/docs/features/ui/guide/Guide.tsx
index 6c586e9297b..f60bc0da19a 100644
--- a/apps/docs/features/ui/guide/Guide.tsx
+++ b/apps/docs/features/ui/guide/Guide.tsx
@@ -53,10 +53,9 @@ export function Guide({ meta, children, className }: GuideProps) {
                 'sticky',
                 /**
                  * --header-height: height of nav
-                 * 1px: height of nav border
                  * 3rem: content padding
                  */
-                'top-[calc(var(--header-height)+1px+3rem)]',
+                'top-[calc(var(--header-height)+3rem)]',
                 // 4rem accounts for 3rem of top padding + 1rem of extra breathing room
                 'max-h-[calc(100vh-var(--header-height)-4rem)]'
               )}
diff --git a/apps/docs/layouts/MainSkeleton.tsx b/apps/docs/layouts/MainSkeleton.tsx
index 5ae70b4386c..0799e49106f 100644
--- a/apps/docs/layouts/MainSkeleton.tsx
+++ b/apps/docs/layouts/MainSkeleton.tsx
@@ -324,11 +324,11 @@ const NavContainer = memo(function NavContainer({ children }: PropsWithChildren)
     >
       <div
         className={cn(
-          'top-0 lg:top-(--header-height)',
+          'top-0',
           'h-full',
-          'relative lg:sticky',
+          'relative',
           'w-full lg:w-auto',
-          'h-fit lg:h-screen overflow-y-scroll lg:overflow-auto',
+          'h-fit lg:h-full overflow-y-scroll lg:overflow-auto',
           'overscroll-contain',
           'backdrop-blur-sm backdrop-filter bg-background',
           'flex flex-col grow'
diff --git a/apps/docs/layouts/ref/RefSubLayout.tsx b/apps/docs/layouts/ref/RefSubLayout.tsx
index e30ed7989fe..761ea65fb3e 100644
--- a/apps/docs/layouts/ref/RefSubLayout.tsx
+++ b/apps/docs/layouts/ref/RefSubLayout.tsx
@@ -122,7 +122,7 @@ const StickyHeader: FC<StickyHeader> = ({ icon, ...props }) => {
           id={props.slug}
           data-ref-id={props.id}
           className={cn(
-            'text-2xl font-medium text-foreground scroll-mt-[calc(32px+2rem)] lg:scroll-mt-[calc(var(--header-height)+1px+4rem)]',
+            'text-2xl font-medium text-foreground scroll-mt-[calc(32px+2rem)] lg:scroll-mt-[calc(var(--header-height)+4rem)]',
             !icon && 'mb-8',
             props.monoFont && 'font-mono'
           )}