feat(docs): redesign sidebar and top bar to be minimal Vercel-style

Merged
KI
3mo ago
+52-130

Summary

  • Redesign the docs sidebar from the bordered "Better Auth" accordion style (section icons, chevrons, full-bleed row borders) to a minimal Vercel-style nav: input-style search box with a ⌘K chip, static group labels, and quiet rounded links.
  • Remove all top bar borders; the sticky header and the sidebar scroller now use fade-out edges instead of hard lines.
  • Drop framer-motion from the docs app (only used by the old accordion) and add @superset/ui for the shared OverflowFadeContainer.

Why / Context

The old sidebar was visually heavy — every section header was a bordered collapsible button with an icon and animated chevron, and rows had full-width hover blocks. This restyles it to match Vercel's docs: whitespace-separated groups, clear type hierarchy (medium-weight headers over muted items), and an active page marked by a subtle bg-accent pill at regular weight.

How It Works

  • Sidebar.tsx drops the collapse state/framer-motion entirely; groups are always expanded (six flat groups didn't need an accordion). The search stays pinned while the list scrolls inside OverflowFadeContainer (fadeEdges: top+bottom) — the same component the desktop DashboardSidebar uses, so items dissolve at the edges instead of clipping.
  • The sticky top bar scrolls the window (not an inner container), so it gets the visual equivalent: a 20px background → transparent gradient strip below the header. No scroll listener needed; it's invisible at the top of the page.
  • SidebarContent.tsx keeps parsing the "<Icon> <Title>" separator format from meta.json (strips the legacy icon prefix), so no content changes were needed. Mobile nav (NavigationMobile) got the same label/item treatment.

Manual QA Checklist

Verified via headless Chromium against the dev server, light + dark, at desktop viewport:

  • Sidebar renders all groups/items; active page shows the accent pill
  • Search box opens the fumadocs search dialog (⌘K binding unchanged)
  • Sidebar list fades under the pinned search box and at the bottom edge when scrollable
  • Page content fades out under the sticky top bar when scrolled
  • No console errors; screenshots visually inspected in both themes

Not covered: real mobile-device pass on NavigationMobile (styling-only change, same markup structure).

Testing

  • bun run typecheck (docs app)
  • bun run lint (exit 0, warnings-as-errors)

Design Decisions

  • Static groups instead of collapsible: the accordion chrome was most of the visual noise, Vercel's groups are static, and six groups fit comfortably; removing it also deleted the framer-motion dependency.
  • Gradient strip instead of mask for the top bar: mask-image only works on a scroll container, and the docs page scrolls the window; an always-on gradient below the sticky header produces the identical fade with zero JS.

Summary by cubic

Redesigned the docs sidebar and sticky top bar to a minimal Vercel-style nav with static groups, a simple ⌘K search, and fade-out scroll edges. This simplifies navigation, removes heavy borders/animations, and improves readability.

  • New Features

    • Sidebar: static group labels, rounded links, input-style search with ⌘K; list uses fade edges via @superset/ui’s OverflowFadeContainer.
    • Top bar: borders removed; adds a subtle gradient fade below the sticky header.
    • Mobile nav: matches label/item styling; unified active link pill via AsideLink.

  • Dependencies

    • Removed framer-motion; added @superset/ui.

Summary by CodeRabbit

  • Style
    • Refreshed the documentation sidebar with a cleaner static layout, updated spacing, and simplified section presentation.
    • Restyled the sidebar search control and added a visible keyboard shortcut.
    • Improved active and inactive link colors and spacing.
    • Added a subtle fade beneath the navigation header.
    • Simplified mobile navigation with more compact spacing and reduced visual clutter.