docs: design fixes to toc and related elements (medusajs#12747)

shahednasser · web-flow · commit 98de6b6ca350 · 2025-06-27T10:34:15.000+03:00
* docs: design fixes to toc and related elements

* change header styling

* fix heading styles

* design fixes

* fix showing badges in toc
diff --git a/www/apps/book/config/index.ts b/www/apps/book/config/index.ts
@@ -27,8 +27,8 @@ export const config: DocsConfig = {
   version: {
     ...globalConfig.version,
     bannerImage: {
-      light: basePathUrl("/images/get-started-card.png"),
-      dark: basePathUrl("/images/get-started-card-dark.png"),
+      light: basePathUrl("/images/release.png"),
+      dark: basePathUrl("/images/release-dark.png"),
     },
   },
 }
diff --git a/www/apps/book/public/images/release-dark.png b/www/apps/book/public/images/release-dark.png
diff --git a/www/apps/book/public/images/release.png b/www/apps/book/public/images/release.png
diff --git a/www/apps/cloud/config/index.ts b/www/apps/cloud/config/index.ts
@@ -27,8 +27,8 @@ export const config: DocsConfig = {
   version: {
     ...globalConfig.version,
     bannerImage: {
-      light: basePathUrl("/images/get-started-card.png"),
-      dark: basePathUrl("/images/get-started-card-dark.png"),
+      light: basePathUrl("/images/release.png"),
+      dark: basePathUrl("/images/release-dark.png"),
     },
   },
 }
diff --git a/www/apps/cloud/public/images/release-dark.png b/www/apps/cloud/public/images/release-dark.png
diff --git a/www/apps/cloud/public/images/release.png b/www/apps/cloud/public/images/release.png
diff --git a/www/apps/resources/config/index.ts b/www/apps/resources/config/index.ts
@@ -26,8 +26,8 @@ export const config: DocsConfig = {
   version: {
     ...globalConfig.version,
     bannerImage: {
-      light: basePathUrl("/images/get-started-card.png"),
-      dark: basePathUrl("/images/get-started-card-dark.png"),
+      light: basePathUrl("/images/release.png"),
+      dark: basePathUrl("/images/release-dark.png"),
     },
   },
 }
diff --git a/www/apps/resources/public/images/release-dark.png b/www/apps/resources/public/images/release-dark.png
diff --git a/www/apps/resources/public/images/release.png b/www/apps/resources/public/images/release.png
diff --git a/www/apps/user-guide/config/index.ts b/www/apps/user-guide/config/index.ts
@@ -27,8 +27,8 @@ export const config: DocsConfig = {
   version: {
     ...globalConfig.version,
     bannerImage: {
-      light: basePathUrl("/images/get-started-card.png"),
-      dark: basePathUrl("/images/get-started-card-dark.png"),
+      light: basePathUrl("/images/release.png"),
+      dark: basePathUrl("/images/release-dark.png"),
     },
   },
 }
diff --git a/www/apps/user-guide/public/images/release-dark.png b/www/apps/user-guide/public/images/release-dark.png
diff --git a/www/apps/user-guide/public/images/release.png b/www/apps/user-guide/public/images/release.png
diff --git a/www/packages/docs-ui/src/components/Card/Layout/Mini/index.tsx b/www/packages/docs-ui/src/components/Card/Layout/Mini/index.tsx
@@ -25,6 +25,8 @@ export const CardLayoutMini = ({
   onClose,
   className,
   imageDimensions = { width: 45, height: 36 },
+  iconClassName,
+  cardRef,
 }: CardProps) => {
   const isExternal = useIsExternalLink({ href })
 
@@ -39,6 +41,7 @@ export const CardLayoutMini = ({
         "w-fit transition-[shadow,background]",
         className
       )}
+      ref={cardRef}
     >
       <div
         className={clsx(
@@ -57,7 +60,8 @@ export const CardLayoutMini = ({
             src={image}
             className={clsx(
               "shadow-elevation-card-rest dark:shadow-elevation-card-rest-dark",
-              "rounded-docs_xs"
+              "rounded-docs_xs",
+              iconClassName
             )}
             width={imageDimensions.width}
             height={imageDimensions.height}
@@ -73,7 +77,8 @@ export const CardLayoutMini = ({
             {...themeImage}
             className={clsx(
               "shadow-elevation-card-rest dark:shadow-elevation-card-rest-dark",
-              "rounded-docs_xs"
+              "rounded-docs_xs",
+              iconClassName
             )}
             width={imageDimensions.width}
             height={imageDimensions.height}
@@ -113,7 +118,7 @@ export const CardLayoutMini = ({
           <Button
             variant="transparent-clear"
             onClick={onClose}
-            className="!p-[2.5px] z-[2] hover:!bg-transparent focus:!shadow-none focus:!bg-transparent"
+            className="!p-[2.5px] z-[2] hover:!bg-medusa-button-transparent-hover focus:!shadow-none focus:!bg-transparent"
           >
             <XMark />
           </Button>
diff --git a/www/packages/docs-ui/src/components/Card/index.tsx b/www/packages/docs-ui/src/components/Card/index.tsx
@@ -32,6 +32,7 @@ export type CardProps = {
   closeable?: boolean
   onClose?: () => void
   hrefProps?: Partial<LinkProps & React.AllHTMLAttributes<HTMLAnchorElement>>
+  cardRef?: React.Ref<HTMLDivElement>
 }
 
 export const Card = ({ type = "default", ...props }: CardProps) => {
diff --git a/www/packages/docs-ui/src/components/ContentMenu/Products/index.tsx b/www/packages/docs-ui/src/components/ContentMenu/Products/index.tsx
@@ -42,13 +42,19 @@ export const ContentMenuProducts = () => {
         <a
           key={index}
           href={getProductUrl(product)}
-          className="flex gap-docs_0.5 items-center"
+          className="flex gap-docs_0.5 items-center group"
         >
           <BorderedIcon
             wrapperClassName={clsx("bg-medusa-bg-base")}
             icon={getProductImageUrl(product)}
+            iconWidth={16}
+            iconHeight={16}
           />
-          <span className="text-medusa-fg-subtle text-x-small-plus">
+          <span
+            className={
+              "text-medusa-fg-subtle text-x-small-plus group-hover:text-medusa-fg-base transition-colors"
+            }
+          >
             {product.title}
           </span>
         </a>
diff --git a/www/packages/docs-ui/src/components/ContentMenu/Toc/index.tsx b/www/packages/docs-ui/src/components/ContentMenu/Toc/index.tsx
@@ -18,8 +18,11 @@ export const ContentMenuToc = () => {
     maxLevel: 4,
   })
 
-  const formatHeadingContent = (content: string | null): string => {
-    return content?.replaceAll(/#$/g, "") || ""
+  const formatHeadingContent = (heading: HTMLHeadingElement): string => {
+    return Array.from(heading.childNodes)
+      .filter((child) => child.nodeType === Node.TEXT_NODE && child.textContent)
+      .map((textNode) => textNode.textContent!.trim())
+      .join("")
   }
 
   const formatHeadingObject = ({
@@ -28,7 +31,7 @@ export const ContentMenuToc = () => {
   }: ActiveOnScrollItem): ToCItemUi => {
     const level = parseInt(heading.tagName.replace("H", ""))
     return {
-      title: formatHeadingContent(heading.textContent),
+      title: formatHeadingContent(heading),
       id: heading.id,
       level,
       children: children?.map(formatHeadingObject),
@@ -68,7 +71,7 @@ export const ContentMenuToc = () => {
 
   return (
     <div className="h-max max-h-full overflow-y-hidden flex relative flex-col">
-      <div className="absolute -left-px top-0 h-full w-[1.5px] bg-medusa-border-base" />
+      <div className="absolute left-0 top-docs_0.5 h-[calc(100%-8px)] w-[1.5px] bg-medusa-border-base" />
       {items !== null && (
         <TocList
           items={items}
@@ -109,9 +112,7 @@ const TocItem = ({ item, activeItemId }: TocItemProps) => {
       <Link
         href={`#${item.id}`}
         className={clsx(
-          "text-x-small-plus block w-full border-l-[1.5px]",
-          item.id === activeItemId &&
-            "border-medusa-fg-base text-medusa-fg-base",
+          "text-x-small-plus block w-full relative",
           item.id !== activeItemId &&
             "text-medusa-fg-muted hover:text-medusa-fg-base border-transparent"
         )}
@@ -125,6 +126,9 @@ const TocItem = ({ item, activeItemId }: TocItemProps) => {
           scrollToElement(elm)
         }}
       >
+        {item.id === activeItemId && (
+          <span className="absolute left-0 top-0 w-[1.5px] h-full bg-medusa-fg-base rounded-full" />
+        )}
         {item.title}
       </Link>
       {(item.children?.length ?? 0) > 0 && (
diff --git a/www/packages/docs-ui/src/components/ContentMenu/Version/index.tsx b/www/packages/docs-ui/src/components/ContentMenu/Version/index.tsx
@@ -11,6 +11,7 @@ export const ContentMenuVersion = () => {
   } = useSiteConfig()
   const [showNewVersion, setShowNewVersion] = useState(false)
   const { isBrowser } = useIsBrowser()
+  const cardRef = React.useRef<HTMLDivElement>(null)
 
   useEffect(() => {
     if (!isBrowser) {
@@ -32,6 +33,14 @@ export const ContentMenuVersion = () => {
     localStorage.setItem(LOCAL_STORAGE_KEY, version.number)
   }
 
+  useEffect(() => {
+    if (!showNewVersion || version.hide || !cardRef.current) {
+      return
+    }
+
+    cardRef.current.classList.add("animate", "animate-fadeInDown")
+  }, [showNewVersion, version.hide, cardRef])
+
   return (
     <Card
       type="mini"
@@ -50,9 +59,14 @@ export const ContentMenuVersion = () => {
         height: 40,
       }}
       className={clsx(
-        "!border-0",
-        (!showNewVersion || version.hide) && "invisible"
+        "!border-0 !bg-medusa-bg-component hover:!bg-medusa-bg-component-hover",
+        "hover:!bg-medusa-bg-component-hover animation-fill-forwards",
+        "opacity-0"
+      )}
+      iconClassName={clsx(
+        "!shadow-none border-[0.5px] border-medusa-alphas-alpha-250"
       )}
+      cardRef={cardRef}
     />
   )
 }
diff --git a/www/packages/docs-ui/src/components/Heading/H1/index.tsx b/www/packages/docs-ui/src/components/Heading/H1/index.tsx
@@ -10,7 +10,7 @@ export const H1 = ({ className, ...props }: H1Props) => {
     <div className="flex items-start justify-between gap-2 h1-wrapper">
       <h1
         className={clsx(
-          "h1-docs [&_code]:!h1-docs [&_code]:!font-mono mb-docs_1 text-medusa-fg-base",
+          "text-h1 [&_code]:!text-h1 [&_code]:!font-mono mb-docs_1 text-medusa-fg-base",
           props.id && "scroll-m-docs_7",
           className
         )}
diff --git a/www/packages/docs-ui/src/components/Heading/H2/index.tsx b/www/packages/docs-ui/src/components/Heading/H2/index.tsx
@@ -19,7 +19,7 @@ export const H2 = ({ className, children, passRef, ...props }: H2Props) => {
   return (
     <h2
       className={clsx(
-        "h2-docs [&_code]:!h2-docs [&_code]:!font-mono mb-docs_1 mt-docs_2 text-medusa-fg-base",
+        "text-h2 [&_code]:!text-h2 [&_code]:!font-mono mb-docs_1 mt-docs_2 text-medusa-fg-base",
         props.id && [
           "group/h2",
           showCollapsedNavbar && "scroll-m-docs_7",
diff --git a/www/packages/docs-ui/src/components/Heading/H3/index.tsx b/www/packages/docs-ui/src/components/Heading/H3/index.tsx
@@ -15,7 +15,7 @@ export const H3 = ({ className, children, ...props }: H3Props) => {
   return (
     <h3
       className={clsx(
-        "h3-docs [&_code]:!h3-docs [&_code]:!font-mono my-docs_1 text-medusa-fg-base",
+        "text-h3 [&_code]:!text-h3 [&_code]:!font-mono my-docs_1 text-medusa-fg-base",
         props.id && [
           "group/h3",
           showCollapsedNavbar && "scroll-m-docs_7",
diff --git a/www/packages/docs-ui/src/components/Link/index.tsx b/www/packages/docs-ui/src/components/Link/index.tsx
@@ -32,8 +32,8 @@ export const Link = ({
         variant === "default" &&
           "text-medusa-fg-interactive hover:text-medusa-fg-interactive-hover",
         variant === "content" && [
-          "border-b border-medusa-border-strong hover:border-medusa-fg-interactive",
-          "transition-all duration-200",
+          "underline decoration-medusa-fg-muted hover:decoration-medusa-fg-interactive",
+          "decoration-[1.5px] font-medium transition-[text-decoration-color]",
         ],
         withIcon && "flex gap-0.25 items-center group",
         className
diff --git a/www/packages/docs-ui/src/components/MDXComponents/index.tsx b/www/packages/docs-ui/src/components/MDXComponents/index.tsx
@@ -120,7 +120,8 @@ export const MDXComponents: MDXComponentsType = {
     const { key, ...rest } = props
     return <ZoomImg {...rest} />
   },
-  a: Link,
+  a: (props) => <Link {...props} variant="content" />,
+  // a: Link,
   strong: ({ className, ...props }: React.HTMLAttributes<HTMLElement>) => {
     return <strong className={clsx("txt-medium-plus", className)} {...props} />
   },
diff --git a/www/packages/docs-ui/src/components/MainNav/Items/Dropdown/index.tsx b/www/packages/docs-ui/src/components/MainNav/Items/Dropdown/index.tsx
@@ -46,7 +46,7 @@ export const MainNavItemDropdown = ({
     return (
       <div
         className={clsx(
-          "cursor-pointer flex gap-docs_0.25 items-center px-docs_0.25 py-docs_0.5",
+          "cursor-pointer flex gap-docs_0.25 items-center py-docs_0.25 px-docs_0.5",
           isActive && "text-medusa-fg-base",
           !isActive && [
             "text-medusa-fg-muted hover:text-medusa-fg-subtle",
diff --git a/www/packages/docs-ui/src/components/MainNav/Version/index.tsx b/www/packages/docs-ui/src/components/MainNav/Version/index.tsx
@@ -15,7 +15,10 @@ export const MainNavVersion = () => {
     <Link
       href={version.releaseUrl}
       target="_blank"
-      className={clsx(version.hide && "hidden", "px-docs_0.5 py-docs_0.25")}
+      className={clsx(
+        version.hide && "hidden",
+        "px-docs_0.5 py-docs_0.25 hover:bg-medusa-button-transparent-hover rounded-docs_sm"
+      )}
     >
       <Tooltip html="View the release notes<br/>on GitHub">
         <span className="relative text-compact-small-plus block">
diff --git a/www/packages/docs-ui/src/components/MainNav/index.tsx b/www/packages/docs-ui/src/components/MainNav/index.tsx
@@ -102,7 +102,7 @@ export const MainNav = ({ className, itemsClassName }: MainNavProps) => {
                 ],
               }}
               isActive={false}
-              className="text-medusa-fg-subtle"
+              className="text-medusa-fg-subtle hover:bg-medusa-button-transparent-hover rounded-docs_sm"
               wrapperClassName="z-10"
             />
           </div>
diff --git a/www/packages/docs-ui/src/components/Menu/SubMenu/index.tsx b/www/packages/docs-ui/src/components/Menu/SubMenu/index.tsx
@@ -4,7 +4,7 @@ import React, { useState } from "react"
 import { Menu, MenuProps } from ".."
 import clsx from "clsx"
 import { MenuItemSubMenu } from "types"
-import { ChevronRight } from "@medusajs/icons"
+import { TriangleRightMini } from "@medusajs/icons"
 import Link from "next/link"
 
 type MenuSubMenuProps = Pick<MenuProps, "itemsOnClick"> & {
@@ -34,7 +34,7 @@ export const MenuSubMenu = ({ item, itemsOnClick }: MenuSubMenuProps) => {
       >
         <span className="text-compact-small">{item.title}</span>
         <span className="text-medusa-fg-subtle mt-[2.5px] block">
-          <ChevronRight />
+          <TriangleRightMini />
         </span>
       </Component>
       {open && (
diff --git a/www/packages/docs-ui/src/layouts/main-content.tsx b/www/packages/docs-ui/src/layouts/main-content.tsx
@@ -71,7 +71,8 @@ export const MainContentLayout = ({
           className={clsx(
             "pt-docs_4 lg:pt-docs_6 pb-docs_8 lg:pb-docs_4",
             showContentMenu &&
-              "grid grid-cols-1 lg:mx-auto lg:grid-cols-[1fr_221px]",
+              "grid grid-cols-1 lg:mx-auto",
+            desktopSidebarOpen && "lg:grid-cols-[1fr_221px]",
             chatOpened && showCollapsedNavbar && "pl-docs_1",
             contentClassName
           )}
diff --git a/www/packages/tailwind/base.tailwind.config.js b/www/packages/tailwind/base.tailwind.config.js
@@ -193,6 +193,11 @@ module.exports = {
               },
             },
           },
+          alphas: {
+            alpha: {
+              250: "var(--docs-alphas-alpha-250)",
+            }
+          }
         },
       },
       boxShadow: {
@@ -347,21 +352,21 @@ module.exports = {
         h2: [
           "18px",
           {
-            lineHeight: "28px",
+            lineHeight: "160%",
             fontWeight: "500",
           },
         ],
         h3: [
           "16px",
           {
-            lineHeight: "150%",
+            lineHeight: "160%",
             fontWeight: "500",
           },
         ],
         h4: [
-          "1rem",
+          "14px",
           {
-            lineHeight: "20px",
+            lineHeight: "160%",
             fontWeight: "500",
           },
         ],
diff --git a/www/packages/tailwind/theme-presets.js b/www/packages/tailwind/theme-presets.js
@@ -49,7 +49,7 @@ const light = {
   "--docs-button-danger-hover": "rgba(190, 18, 60, 1)",
   "--docs-button-danger-pressed": "rgba(159, 18, 57, 1)",
   "--docs-button-transparent": "rgba(255, 255, 255, 0)",
-  "--docs-button-transparent-hover": "rgba(244, 244, 245, 1)",
+  "--docs-button-transparent-hover": "rgba(24, 24, 27, 0.06)",
   "--docs-button-transparent-pressed": "rgba(228, 228, 231, 1)",
 
   "--docs-tags-neutral-bg": "rgba(244, 244, 245, 1)",
@@ -103,6 +103,7 @@ const light = {
 
   "--docs-alpha-white-alpha-6": "rgba(255, 255, 255, 0.06)",
   "--docs-alpha-white-alpha-12": "rgba(255, 255, 255, 0.12)",
+  "--docs-alphas-alpha-250": "rgba(24, 24, 27, 0.1)",
 }
 
 const dark = {
@@ -207,6 +208,8 @@ const dark = {
   "--docs-contrast-border-base": "rgba(82, 82, 91, 1)",
   "--docs-contrast-border-top": "rgba(24, 24, 27, 1)",
   "--docs-contrast-border-bot": "rgba(255, 255, 255, 0.08)",
+
+  "--docs-alphas-alpha-250": "rgba(255, 255, 255, 0.1)",
 }
 
 module.exports = {
