fix(docs): stop sidebar from jumping on scroll (#49807)

## 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

@@ -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
       )}
     />

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">

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)]'
           )}

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)]'
               )}

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'

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'
           )}