From c38f6d07c21fcb1e76347c85a0535b2fc7b9c77d Mon Sep 17 00:00:00 2001
From: Shahed Nasser <shahednasser@gmail.com>
Date: Tue, 4 Jun 2024 10:41:24 +0300
Subject: [PATCH] docs: update design + colors (#7593)

Update design and colors in docs to match those in Figma
---
 www/apps/api-reference/app/globals.css        |   2 +-
 .../CodeSection/RequestSamples/index.tsx      |  25 +-
 .../ui/src/components/package-install.tsx     |  23 +-
 www/apps/ui/src/providers/search.tsx          |   7 +-
 www/apps/ui/src/styles/globals.css            |   2 +-
 .../AiAssistant/CommandIcon/index.tsx         |  24 -
 .../AiAssistant/ThreadItem/Actions/index.tsx  |   2 +-
 .../src/components/AiAssistant/index.tsx      |   8 +-
 .../docs-ui/src/components/Badge/index.tsx    |  30 +-
 .../docs-ui/src/components/Button/index.tsx   |  72 +--
 .../docs-ui/src/components/Card/index.tsx     |   7 +-
 .../CodeBlock/Actions/Copy/index.tsx          |  42 ++
 .../components/CodeBlock/Actions/index.tsx    | 109 +++++
 .../src/components/CodeBlock/Header/index.tsx |  79 ++--
 .../src/components/CodeBlock/Line/index.tsx   |  10 +-
 .../src/components/CodeBlock/index.tsx        | 309 ++++++------
 .../src/components/CodeTabs/Item/index.tsx    |  24 +-
 .../docs-ui/src/components/CodeTabs/index.tsx |  90 ++--
 .../components/Icons/AiAssistant/index.tsx    | 442 ++++++++++++++++++
 .../src/components/Icons/ShadedBg/index.tsx   | 248 ++++++++++
 .../docs-ui/src/components/Icons/index.tsx    |   2 +
 .../src/components/Input/Text/index.tsx       |   2 +-
 .../docs-ui/src/components/Kbd/index.tsx      |   6 +-
 .../components/LearningPath/Icon/index.tsx    |   2 +-
 .../components/LearningPath/Steps/index.tsx   |   4 +-
 .../src/components/LearningPath/index.tsx     |   2 +-
 .../src/components/LegacyCodeTabs/index.tsx   | 172 -------
 .../src/components/Modal/Header/index.tsx     |   2 +-
 .../docs-ui/src/components/Modal/index.tsx    |   2 +-
 .../components/Navbar/MobileMenu/index.tsx    |   8 +-
 .../src/components/Note/Layout/index.tsx      |  15 +-
 .../Item/Layout/Default/index.tsx             |   2 +-
 .../src/components/Npm2YarnCode/index.tsx     |  72 +--
 .../docs-ui/src/components/Rating/index.tsx   |   2 +-
 .../components/Search/ModalOpener/index.tsx   |   2 +-
 .../components/Search/Suggestions/index.tsx   |   8 +-
 .../docs-ui/src/components/Search/index.tsx   |   2 +-
 .../src/components/Select/Dropdown/index.tsx  |   2 +-
 .../src/components/Sidebar/Item/index.tsx     |  13 +-
 .../docs-ui/src/components/TextArea/index.tsx |   2 +-
 .../docs-ui/src/components/Tooltip/index.tsx  |  10 +-
 .../docs-ui/src/components/TypeList/index.tsx |   2 +-
 www/packages/docs-ui/src/components/index.ts  |   2 -
 www/packages/tailwind/base.tailwind.config.js | 188 ++++----
 www/packages/tailwind/theme-presets.js        | 236 +++++-----
 45 files changed, 1511 insertions(+), 804 deletions(-)
 delete mode 100644 www/packages/docs-ui/src/components/AiAssistant/CommandIcon/index.tsx
 create mode 100644 www/packages/docs-ui/src/components/CodeBlock/Actions/Copy/index.tsx
 create mode 100644 www/packages/docs-ui/src/components/CodeBlock/Actions/index.tsx
 create mode 100644 www/packages/docs-ui/src/components/Icons/AiAssistant/index.tsx
 create mode 100644 www/packages/docs-ui/src/components/Icons/ShadedBg/index.tsx
 delete mode 100644 www/packages/docs-ui/src/components/LegacyCodeTabs/index.tsx

diff --git a/www/apps/api-reference/app/globals.css b/www/apps/api-reference/app/globals.css
index 88cbdb7db1..197a81cac6 100644
--- a/www/apps/api-reference/app/globals.css
+++ b/www/apps/api-reference/app/globals.css
@@ -44,7 +44,7 @@
   }
 
   pre *::selection {
-    @apply !bg-medusa-code-text-highlight;
+    @apply !bg-medusa-contrast-bg-highlight;
   }
 
   body[data-modal="opened"] {
diff --git a/www/apps/api-reference/components/Tags/Operation/CodeSection/RequestSamples/index.tsx b/www/apps/api-reference/components/Tags/Operation/CodeSection/RequestSamples/index.tsx
index becb39b0ba..58dbf7aa27 100644
--- a/www/apps/api-reference/components/Tags/Operation/CodeSection/RequestSamples/index.tsx
+++ b/www/apps/api-reference/components/Tags/Operation/CodeSection/RequestSamples/index.tsx
@@ -1,5 +1,5 @@
 import type { Code } from "@/types/openapi"
-import { LegacyCodeTabs } from "docs-ui"
+import { CodeBlock, CodeTab, CodeTabs } from "docs-ui"
 import slugify from "slugify"
 
 export type TagOperationCodeSectionRequestSamplesProps = {
@@ -12,18 +12,17 @@ const TagOperationCodeSectionRequestSamples = ({
   return (
     <div>
       <h3>Request samples</h3>
-      <LegacyCodeTabs
-        tabs={codeSamples.map((codeSample) => ({
-          label: codeSample.label,
-          value: slugify(codeSample.label),
-          code: {
-            ...codeSample,
-            collapsed: true,
-            className: "!mb-0",
-          },
-        }))}
-        className="mt-2 !mb-0"
-      />
+      <CodeTabs className="mt-2 !mb-0" group="request-examples">
+        {codeSamples.map((codeSample, index) => (
+          <CodeTab
+            key={index}
+            label={codeSample.label}
+            value={slugify(codeSample.label)}
+          >
+            <CodeBlock {...codeSample} collapsed={true} className="!mb-0" />
+          </CodeTab>
+        ))}
+      </CodeTabs>
     </div>
   )
 }
diff --git a/www/apps/ui/src/components/package-install.tsx b/www/apps/ui/src/components/package-install.tsx
index 345813e50e..3119572e9b 100644
--- a/www/apps/ui/src/components/package-install.tsx
+++ b/www/apps/ui/src/components/package-install.tsx
@@ -1,5 +1,5 @@
 import { clx } from "@medusajs/ui"
-import { LegacyCodeTabs } from "docs-ui"
+import { CodeBlock, CodeTab, CodeTabs } from "docs-ui"
 
 type PackageInstallProps = {
   packageName: string
@@ -20,15 +20,20 @@ const PackageInstall = ({
   const npm = `npm install ${pkg} ${devDependency ? "--save-dev" : "--save"}`
   const pnpm = `pnpm add ${devDependency ? "-D " : ""}${pkg}`
 
+  const tabs = [
+    { code: { lang: "bash", source: npm }, label: "npm", value: "npm" },
+    { code: { lang: "bash", source: yarn }, label: "yarn", value: "yarn" },
+    { code: { lang: "bash", source: pnpm }, label: "pnpm", value: "pnpm" },
+  ]
+
   return (
-    <LegacyCodeTabs
-      tabs={[
-        { code: { lang: "bash", source: npm }, label: "npm", value: "npm" },
-        { code: { lang: "bash", source: yarn }, label: "yarn", value: "yarn" },
-        { code: { lang: "bash", source: pnpm }, label: "pnpm", value: "pnpm" },
-      ]}
-      className={clx("my-4", className)}
-    />
+    <CodeTabs group="npm2yarn" className={clx("my-4", className)}>
+      {tabs.map((tab, index) => (
+        <CodeTab label={tab.label} value={tab.value} key={index}>
+          <CodeBlock {...tab.code} />
+        </CodeTab>
+      ))}
+    </CodeTabs>
   )
 }
 
diff --git a/www/apps/ui/src/providers/search.tsx b/www/apps/ui/src/providers/search.tsx
index 95a6754f9a..dfc4ed6332 100644
--- a/www/apps/ui/src/providers/search.tsx
+++ b/www/apps/ui/src/providers/search.tsx
@@ -1,7 +1,7 @@
 "use client"
 
 import {
-  AiAssistantCommandIcon,
+  AiAssistantIcon,
   AiAssistantProvider,
   SearchProvider as UiSearchProvider,
   searchFiltersV1,
@@ -40,7 +40,7 @@ const SearchProvider = ({ children }: SearchProviderProps) => {
       commands={[
         {
           name: "ai-assistant",
-          icon: <AiAssistantCommandIcon />,
+          icon: <AiAssistantIcon />,
           component: (
             <AiAssistantProvider
               apiUrl={process.env.NEXT_PUBLIC_AI_ASSISTANT_URL || "temp"}
@@ -53,7 +53,8 @@ const SearchProvider = ({ children }: SearchProviderProps) => {
           ),
           title: "AI Assistant",
           badge: {
-            variant: "purple",
+            variant: "blue",
+            badgeType: "shaded",
             children: "Beta",
           },
         },
diff --git a/www/apps/ui/src/styles/globals.css b/www/apps/ui/src/styles/globals.css
index cda80045d0..b1170c9cdc 100644
--- a/www/apps/ui/src/styles/globals.css
+++ b/www/apps/ui/src/styles/globals.css
@@ -15,7 +15,7 @@
   }
 
   pre *::selection {
-    @apply !bg-medusa-code-text-highlight;
+    @apply !bg-medusa-contrast-bg-highlight;
   }
 
   body {
diff --git a/www/packages/docs-ui/src/components/AiAssistant/CommandIcon/index.tsx b/www/packages/docs-ui/src/components/AiAssistant/CommandIcon/index.tsx
deleted file mode 100644
index 852142a610..0000000000
--- a/www/packages/docs-ui/src/components/AiAssistant/CommandIcon/index.tsx
+++ /dev/null
@@ -1,24 +0,0 @@
-import { SparklesSolid } from "@medusajs/icons"
-import clsx from "clsx"
-import React from "react"
-
-export type AiAssistantCommandIconProps =
-  React.AllHTMLAttributes<HTMLSpanElement>
-
-export const AiAssistantCommandIcon = ({
-  className,
-  ...props
-}: AiAssistantCommandIconProps) => {
-  return (
-    <span
-      className={clsx(
-        "bg-button-inverted bg-medusa-button-inverted dark:bg-button-inverted-dark",
-        "rounded-md p-[2px] text-medusa-fg-on-inverted flex",
-        className
-      )}
-      {...props}
-    >
-      <SparklesSolid />
-    </span>
-  )
-}
diff --git a/www/packages/docs-ui/src/components/AiAssistant/ThreadItem/Actions/index.tsx b/www/packages/docs-ui/src/components/AiAssistant/ThreadItem/Actions/index.tsx
index f02dd2a93a..5840f301d4 100644
--- a/www/packages/docs-ui/src/components/AiAssistant/ThreadItem/Actions/index.tsx
+++ b/www/packages/docs-ui/src/components/AiAssistant/ThreadItem/Actions/index.tsx
@@ -75,7 +75,7 @@ export const AiAssistantThreadItemActions = ({
 const ActionButton = ({ children, className, ...props }: ButtonProps) => {
   return (
     <Button
-      variant="clear"
+      variant="transparent"
       className={clsx(
         "text-medusa-fg-muted hover:text-medusa-fg-subtle",
         "hover:bg-medusa-bg-subtle-hover",
diff --git a/www/packages/docs-ui/src/components/AiAssistant/index.tsx b/www/packages/docs-ui/src/components/AiAssistant/index.tsx
index 340f31ff64..0d372b50f4 100644
--- a/www/packages/docs-ui/src/components/AiAssistant/index.tsx
+++ b/www/packages/docs-ui/src/components/AiAssistant/index.tsx
@@ -2,7 +2,6 @@
 
 import React, { useState, useEffect, useCallback, useMemo, useRef } from "react"
 import {
-  AiAssistantCommandIcon,
   Badge,
   Button,
   InputText,
@@ -12,6 +11,7 @@ import {
   SearchHitGroupName,
   Tooltip,
   Link,
+  AiAssistantIcon,
 } from "@/components"
 import { useAiAssistant, useSearch } from "@/providers"
 import { ArrowUturnLeft, XMarkMini } from "@medusajs/icons"
@@ -300,7 +300,7 @@ export const AiAssistant = () => {
         )}
       >
         <Button
-          variant="clear"
+          variant="transparent"
           onClick={() => setCommand(null)}
           className="text-medusa-fg-subtle p-[5px]"
         >
@@ -320,7 +320,7 @@ export const AiAssistant = () => {
           disabled={loading}
         />
         <Button
-          variant="clear"
+          variant="transparent"
           onClick={() => {
             setQuestion("")
             inputRef.current?.focus()
@@ -395,7 +395,7 @@ export const AiAssistant = () => {
               "flex items-center gap-docs_0.75 text-compact-small-plus"
             )}
           >
-            <AiAssistantCommandIcon />
+            <AiAssistantIcon />
             <span className="text-medusa-fg-subtle">Medusa AI Assistant</span>
             <Badge variant="purple">Beta</Badge>
           </div>
diff --git a/www/packages/docs-ui/src/components/Badge/index.tsx b/www/packages/docs-ui/src/components/Badge/index.tsx
index 3a33e67a57..6bc692e1ef 100644
--- a/www/packages/docs-ui/src/components/Badge/index.tsx
+++ b/www/packages/docs-ui/src/components/Badge/index.tsx
@@ -1,5 +1,6 @@
 import React from "react"
 import clsx from "clsx"
+import { ShadedBgIcon } from "../.."
 
 export type BadgeVariant =
   | "purple"
@@ -8,17 +9,28 @@ export type BadgeVariant =
   | "blue"
   | "red"
   | "neutral"
+  | "code"
+
+export type BadgeType = "default" | "shaded"
 
 export type BadgeProps = {
   className?: string
   variant: BadgeVariant
+  badgeType?: BadgeType
 } & React.HTMLAttributes<HTMLSpanElement>
 
-export const Badge = ({ className, variant, children }: BadgeProps) => {
+export const Badge = ({
+  className,
+  variant,
+  badgeType = "default",
+  children,
+}: BadgeProps) => {
   return (
     <span
       className={clsx(
-        "text-compact-x-small-plus px-docs_0.25 py-0 rounded-docs_sm border border-solid text-center",
+        "text-compact-x-small-plus text-center",
+        badgeType === "default" &&
+          "px-docs_0.25 py-0 rounded-docs_sm border border-solid",
         variant === "purple" &&
           "bg-medusa-tag-purple-bg text-medusa-tag-purple-text border-medusa-tag-purple-border",
         variant === "orange" &&
@@ -31,11 +43,23 @@ export const Badge = ({ className, variant, children }: BadgeProps) => {
           "bg-medusa-tag-red-bg text-medusa-tag-red-text border-medusa-tag-red-border",
         variant === "neutral" &&
           "bg-medusa-tag-neutral-bg text-medusa-tag-neutral-text border-medusa-tag-neutral-border",
+        variant === "code" &&
+          "bg-medusa-contrast-bg-subtle text-medusa-contrast-fg-secondary border-medusa-contrast-border-bot",
+        badgeType === "shaded" && "px-[3px] !bg-transparent relative",
+        // needed for tailwind utilities
         "badge",
         className
       )}
     >
-      {children}
+      {badgeType === "shaded" && (
+        <ShadedBgIcon
+          variant={variant}
+          className={clsx("absolute top-0 left-0 w-full h-full")}
+        />
+      )}
+      <span className={clsx(badgeType === "shaded" && "relative z-[1]")}>
+        {children}
+      </span>
     </span>
   )
 }
diff --git a/www/packages/docs-ui/src/components/Button/index.tsx b/www/packages/docs-ui/src/components/Button/index.tsx
index 6977e09716..7e5338b685 100644
--- a/www/packages/docs-ui/src/components/Button/index.tsx
+++ b/www/packages/docs-ui/src/components/Button/index.tsx
@@ -1,7 +1,11 @@
 import clsx from "clsx"
 import React from "react"
 
-export type ButtonVariants = "primary" | "secondary" | "clear"
+export type ButtonVariants =
+  | "primary"
+  | "secondary"
+  | "transparent"
+  | "transparent-clear"
 
 export type ButtonType = "default" | "icon"
 
@@ -24,39 +28,54 @@ export const Button = ({
 }: ButtonProps) => {
   const variantClasses = {
     primary: [
-      "py-[5px] px-docs_0.75 rounded-docs_sm cursor-pointer",
-      "bg-button-inverted bg-medusa-button-inverted dark:bg-button-inverted-dark",
-      "hover:bg-medusa-button-inverted-hover hover:bg-no-image hover:no-underline",
-      "active:bg-medusa-button-inverted-pressed active:bg-no-image",
-      "focus:bg-medusa-button-inverted-pressed focus:bg-no-image",
-      "shadow-button-colored active:shadow-button-colored-focused focus:shadow-button-colored-focused transition-shadow",
-      "dark:shadow-button-colored-dark dark:active:shadow-button-colored-focused-dark dark:focus:shadow-button-colored-focused-dark",
-      "disabled:!bg-no-image disabled:bg-medusa-bg-disabled",
-      "disabled:cursor-not-allowed disabled:border-medusa-border-base",
-      "text-compact-small-plus text-medusa-fg-on-inverted",
-      "[&_a]:text-medusa-fg-on-inverted",
+      "px-[10px] py-[6px] rounded-docs_sm cursor-pointer",
+      "bg-medusa-button-inverted",
+      "hover:bg-medusa-button-inverted-hover hover:no-underline",
+      "active:bg-medusa-button-inverted-pressed",
+      "focus:bg-medusa-button-inverted",
+      "shadow-button-inverted focus:shadow-button-inverted-focused transition-shadow",
+      "dark:shadow-button-inverted-dark dark:focus:shadow-button-inverted-focused-dark",
+      "disabled:bg-medusa-bg-disabled disabled:shadow-button-neutral dark:disabled:shadow-button-neutral-dark",
+      "disabled:cursor-not-allowed",
+      "text-compact-small-plus text-medusa-contrast-fg-primary",
+      "[&_a]:text-medusa-contrast-fg-primary",
       "disabled:text-medusa-fg-disabled",
       "[&_a]:disabled:text-medusa-fg-disabled",
-      "border border-medusa-border-loud",
       "select-none",
     ],
     secondary: [
-      "py-[5px] px-docs_0.75 rounded-docs_sm cursor-pointer",
-      "bg-button-neutral bg-medusa-button-neutral dark:bg-button-neutral-dark",
-      "hover:bg-medusa-button-neutral-hover hover:bg-no-image hover:no-underline",
-      "active:bg-medusa-button-neutral-pressed active:bg-no-image",
-      "focus:bg-medusa-button-neutral-pressed focus:bg-no-image",
-      "disabled:!bg-no-image disabled:bg-medusa-bg-disabled",
-      "disabled:cursor-not-allowed",
-      "border border-solid border-medusa-border-base",
+      "px-[10px] py-[6px] rounded-docs_sm cursor-pointer",
+      "bg-medusa-button-neutral",
+      "hover:bg-medusa-button-neutral-hover hover:no-underline",
+      "active:bg-medusa-button-neutral-pressed",
+      "focus:bg-medusa-button-neutral",
+      "disabled:bg-medusa-bg-disabled disabled:shadow-button-neutral dark:disabled:shadow-button-neutral-dark",
+      "disabled:cursor-not-allowed disabled:text-medusa-fg-disabled",
       "text-compact-small-plus text-medusa-fg-base",
       "[&_a]:text-medusa-fg-base",
-      "shadow-button-neutral focus:shadow-button-neutral-focused active:shadow-button-neutral-focused transition-shadow",
-      "dark:shadow-button-neutral dark:focus:shadow-button-neutral-focused dark:active:shadow-button-neutral-focused",
+      "shadow-button-neutral focus:shadow-button-neutral-focused active:shadow-button-neutral transition-shadow",
+      "dark:shadow-button-neutral dark:focus:shadow-button-neutral-focused dark:active:shadow-button-neutral",
       "select-none",
     ],
-    clear: [
-      "bg-transparent shadow-none border-0 outline-none cursor-pointer text-fg-medusa-subtle",
+    transparent: [
+      "px-[10px] py-[6px] rounded-docs_sm cursor-pointer",
+      "bg-transparent shadow-none border-0 outline-none",
+      "text-compact-small-plus text-medusa-fg-base",
+      "hover:bg-medusa-button-transparent-hover",
+      "active:bg-medusa-button-transparent-pressed",
+      "focus:bg-medusa-bg-base focus:shadow-button-neutral-focused dark:focus:shadow-button-neutral-focused-dark",
+      "disabled:bg-transparent disabled:shadow-button-neutral dark:disabled:shadow-button-neutral-dark",
+      "disabled:cursor-not-allowed disabled:text-medusa-fg-disabled",
+    ],
+    transparentClear: [
+      "px-[10px] py-[6px] rounded-docs_sm cursor-pointer",
+      "bg-transparent shadow-none border-0 outline-none",
+      "text-compact-small-plus text-medusa-fg-muted",
+      "hover:bg-medusa-button-transparent-hover",
+      "active:bg-medusa-button-transparent-pressed",
+      "focus:bg-medusa-bg-base focus:shadow-button-neutral-focused dark:focus:shadow-button-neutral-focused-dark",
+      "disabled:bg-transparent disabled:shadow-button-neutral dark:disabled:shadow-button-neutral-dark",
+      "disabled:cursor-not-allowed disabled:text-medusa-fg-disabled",
     ],
   }
 
@@ -66,7 +85,8 @@ export const Button = ({
         "inline-flex flex-row justify-center items-center gap-[6px]",
         variant === "primary" && variantClasses.primary,
         variant === "secondary" && variantClasses.secondary,
-        variant === "clear" && variantClasses.clear,
+        variant === "transparent" && variantClasses.transparent,
+        variant === "transparent-clear" && variantClasses.transparentClear,
         buttonType === "icon" && "!px-docs_0.25",
         className
       )}
diff --git a/www/packages/docs-ui/src/components/Card/index.tsx b/www/packages/docs-ui/src/components/Card/index.tsx
index f3325b77aa..de30f18e18 100644
--- a/www/packages/docs-ui/src/components/Card/index.tsx
+++ b/www/packages/docs-ui/src/components/Card/index.tsx
@@ -32,9 +32,10 @@ export const Card = ({
     <div
       className={clsx(
         "bg-medusa-bg-subtle w-full rounded",
-        "shadow-card-rest dark:shadow-card-rest-dark py-docs_0.75 relative px-docs_1",
-        "flex items-start gap-docs_1 transition-shadow",
-        href && "hover:shadow-card-hover dark:hover:shadow-card-hover-dark",
+        "shadow-elevation-card-rest dark:shadow-elevation-card-rest-dark p-docs_0.75 relative",
+        "flex items-start gap-docs_0.75 transition-shadow",
+        href &&
+          "hover:shadow-elevation-card-hover dark:hover:shadow-elevation-card-hover-dark",
         className
       )}
     >
diff --git a/www/packages/docs-ui/src/components/CodeBlock/Actions/Copy/index.tsx b/www/packages/docs-ui/src/components/CodeBlock/Actions/Copy/index.tsx
new file mode 100644
index 0000000000..3f88ee070d
--- /dev/null
+++ b/www/packages/docs-ui/src/components/CodeBlock/Actions/Copy/index.tsx
@@ -0,0 +1,42 @@
+import React, { useEffect, useState } from "react"
+import { CopyButton } from "../../../.."
+import clsx from "clsx"
+import { CheckMini, SquareTwoStack } from "@medusajs/icons"
+
+export type CodeBlockCopyActionProps = {
+  source: string
+  inHeader: boolean
+  iconColor: string
+}
+
+export const CodeBlockCopyAction = ({
+  source,
+  inHeader,
+  iconColor,
+}: CodeBlockCopyActionProps) => {
+  const [copied, setCopied] = useState(false)
+
+  useEffect(() => {
+    if (copied) {
+      setTimeout(() => {
+        setCopied(false)
+      }, 1000)
+    }
+  }, [copied])
+
+  return (
+    <CopyButton
+      text={source}
+      tooltipClassName="font-base"
+      className={clsx(
+        "h-fit",
+        !inHeader && "p-[6px]",
+        inHeader && "px-[6px] pb-[6px]"
+      )}
+      onCopy={() => setCopied(true)}
+    >
+      {!copied && <SquareTwoStack className={clsx(iconColor)} />}
+      {copied && <CheckMini className={clsx(iconColor)} />}
+    </CopyButton>
+  )
+}
diff --git a/www/packages/docs-ui/src/components/CodeBlock/Actions/index.tsx b/www/packages/docs-ui/src/components/CodeBlock/Actions/index.tsx
new file mode 100644
index 0000000000..40a496b90d
--- /dev/null
+++ b/www/packages/docs-ui/src/components/CodeBlock/Actions/index.tsx
@@ -0,0 +1,109 @@
+"use client"
+
+import clsx from "clsx"
+import React, { useMemo } from "react"
+import { CodeBlockStyle, Link, Tooltip } from "@/components"
+import { ExclamationCircle, PlaySolid } from "@medusajs/icons"
+import { useColorMode } from "@/providers"
+import { GITHUB_ISSUES_PREFIX } from "@/constants"
+import { CodeBlockCopyAction } from "./Copy"
+
+export type CodeBlockActionsProps = {
+  source: string
+  isSingleLine?: boolean
+  inHeader: boolean
+  canShowApiTesting?: boolean
+  blockStyle: CodeBlockStyle
+  onApiTesting: React.Dispatch<React.SetStateAction<boolean>>
+  noReport?: boolean
+  noCopy?: boolean
+}
+
+export const CodeBlockActions = ({
+  source,
+  inHeader,
+  isSingleLine = false,
+  canShowApiTesting = false,
+  blockStyle,
+  onApiTesting,
+  noReport = false,
+  noCopy = false,
+}: CodeBlockActionsProps) => {
+  const { colorMode } = useColorMode()
+  const iconColor = useMemo(
+    () =>
+      clsx(
+        blockStyle === "loud" && "text-medusa-contrast-fg-secondary",
+        blockStyle === "subtle" && [
+          colorMode === "light" && "text-medusa-fg-muted",
+          colorMode === "dark" && "text-medusa-fg-secondary",
+        ]
+      ),
+    [blockStyle, colorMode]
+  )
+
+  return (
+    <div
+      className={clsx(
+        "absolute hidden md:flex md:justify-end",
+        "xs:rounded xs:absolute xs:right-0 xs:top-0 xs:w-[calc(10%+24px)] xs:h-full xs:bg-transparent",
+        !inHeader && [
+          "md:right-docs_0.5",
+          isSingleLine && "md:top-docs_0.25",
+          !isSingleLine && "md:top-docs_0.5",
+        ],
+        inHeader && "md:right-docs_1 md:top-docs_0.5"
+      )}
+    >
+      {canShowApiTesting && (
+        <Tooltip
+          text="Test API"
+          tooltipClassName="font-base"
+          className={clsx(
+            "h-fit",
+            !inHeader && "p-[6px]",
+            inHeader && "px-[6px] pb-[6px]"
+          )}
+        >
+          <PlaySolid
+            className={clsx("cursor-pointer", iconColor)}
+            onClick={() => onApiTesting(true)}
+          />
+        </Tooltip>
+      )}
+      {!noReport && (
+        <Tooltip
+          text="Report Issue"
+          tooltipClassName="font-base"
+          className={clsx(
+            "h-fit",
+            !inHeader && "p-[6px]",
+            inHeader && "px-[6px] pb-[6px]"
+          )}
+        >
+          <Link
+            href={`${GITHUB_ISSUES_PREFIX}&title=${encodeURIComponent(
+              `Docs(Code Issue): `
+            )}`}
+            target="_blank"
+            className={clsx(
+              "bg-transparent border-none cursor-pointer rounded",
+              "[&:not(:first-child)]:ml-docs_0.5",
+              "inline-flex justify-center items-center invisible xs:visible"
+            )}
+            rel="noreferrer"
+          >
+            <ExclamationCircle className={clsx(iconColor)} />
+          </Link>
+        </Tooltip>
+      )}
+      {!noCopy && (
+        <CodeBlockCopyAction
+          source={source}
+          inHeader={inHeader}
+          iconColor={iconColor}
+        />
+      )}
+    </div>
+  )
+}
diff --git a/www/packages/docs-ui/src/components/CodeBlock/Header/index.tsx b/www/packages/docs-ui/src/components/CodeBlock/Header/index.tsx
index fff89d779a..3351af81c7 100644
--- a/www/packages/docs-ui/src/components/CodeBlock/Header/index.tsx
+++ b/www/packages/docs-ui/src/components/CodeBlock/Header/index.tsx
@@ -5,6 +5,7 @@ import clsx from "clsx"
 import { CodeBlockStyle } from ".."
 import { useColorMode } from "@/providers"
 import { Badge, BadgeVariant } from "@/components"
+import { CodeBlockActions, CodeBlockActionsProps } from "../Actions"
 
 export type CodeBlockHeaderMeta = {
   badgeLabel?: string
@@ -12,73 +13,69 @@ export type CodeBlockHeaderMeta = {
 }
 
 type CodeBlockHeaderProps = {
-  children?: React.ReactNode
   title?: string
   blockStyle?: CodeBlockStyle
+  actionsProps: CodeBlockActionsProps
 } & CodeBlockHeaderMeta
 
 export const CodeBlockHeader = ({
-  children,
   title,
   blockStyle = "loud",
   badgeLabel,
+  actionsProps,
   badgeColor,
 }: CodeBlockHeaderProps) => {
   const { colorMode } = useColorMode()
 
-  const borderColor = useMemo(
+  const bgColor = useMemo(
     () =>
       clsx(
-        blockStyle === "loud" && [
-          colorMode === "light" && "border-medusa-code-border",
-          colorMode === "dark" && "border-medusa-border-base",
-        ],
+        blockStyle === "loud" && "bg-medusa-contrast-bg-base",
         blockStyle === "subtle" && [
-          colorMode === "light" && "border-medusa-border-base",
-          colorMode === "dark" && "border-medusa-code-border",
+          colorMode === "light" && "bg-medusa-bg-component",
+          colorMode === "dark" && "bg-medusa-code-bg-header",
         ]
       ),
     [blockStyle, colorMode]
   )
+  const titleColor = useMemo(
+    () =>
+      clsx(
+        blockStyle === "loud" && "text-medusa-contrast-fg-secondary",
+        blockStyle === "subtle" && [
+          colorMode === "light" && "text-medusa-fg-subtle",
+          colorMode === "dark" && "text-medusa-contrast-fg-secondary",
+        ]
+      ),
+    [blockStyle, colorMode]
+  )
+
   return (
     <div
       className={clsx(
-        "py-docs_0.75 rounded-t-docs_DEFAULT px-docs_1 mb-0",
-        "flex gap-docs_2 items-start justify-between",
-        blockStyle === "loud" && [
-          colorMode === "light" && "bg-medusa-code-bg-header",
-          colorMode === "dark" && "bg-medusa-bg-base",
-        ],
+        "py-docs_0.5 px-docs_1 mb-0",
+        "rounded-t-docs_lg relative",
         blockStyle === "subtle" && [
-          colorMode === "light" && "bg-medusa-bg-component",
-          colorMode === "dark" && "bg-medusa-code-bg-header",
+          "border border-solid border-b-0",
+          colorMode === "light" && "border-medusa-border-base",
+          colorMode === "dark" && "border-medusa-code-border",
         ],
-        borderColor && `border border-b-0 ${borderColor}`
+        bgColor
       )}
     >
-      {children}
-      {title && (
-        <div
-          className={clsx(
-            "txt-compact-small-plus",
-            blockStyle === "loud" && [
-              colorMode === "light" && "text-medusa-code-text-subtle",
-              colorMode === "dark" && "text-medusa-fg-muted",
-            ],
-            blockStyle === "subtle" && [
-              colorMode === "light" && "text-medusa-fg-subtle",
-              colorMode === "dark" && "text-medusa-code-text-subtle",
-            ]
-          )}
-        >
-          {title}
-        </div>
-      )}
-      {badgeLabel && (
-        <Badge variant={badgeColor || "orange"} className="font-base">
-          {badgeLabel}
-        </Badge>
-      )}
+      <div className={clsx("xs:max-w-[83%]", "flex gap-docs_0.75 items-start")}>
+        {badgeLabel && (
+          <Badge variant={badgeColor || "code"} className="font-base">
+            {badgeLabel}
+          </Badge>
+        )}
+        {title && (
+          <div className={clsx("text-compact-x-small font-base", titleColor)}>
+            {title}
+          </div>
+        )}
+      </div>
+      <CodeBlockActions {...actionsProps} />
     </div>
   )
 }
diff --git a/www/packages/docs-ui/src/components/CodeBlock/Line/index.tsx b/www/packages/docs-ui/src/components/CodeBlock/Line/index.tsx
index fcc2ebac66..d02b2a7898 100644
--- a/www/packages/docs-ui/src/components/CodeBlock/Line/index.tsx
+++ b/www/packages/docs-ui/src/components/CodeBlock/Line/index.tsx
@@ -21,7 +21,6 @@ type CodeBlockLineProps = {
   highlights?: Highlight[]
   lineNumber: number
   showLineNumber: boolean
-  bgColorClassName: string
   lineNumberColorClassName: string
   noLineNumbers?: boolean
 } & Pick<RenderProps, "getLineProps" | "getTokenProps">
@@ -33,7 +32,6 @@ export const CodeBlockLine = ({
   getLineProps,
   getTokenProps,
   showLineNumber,
-  bgColorClassName,
   lineNumberColorClassName,
 }: CodeBlockLineProps) => {
   const lineProps = getLineProps({ line, key: lineNumber })
@@ -204,10 +202,9 @@ export const CodeBlockLine = ({
   }) => (
     <span
       className={clsx(
-        // TODO change code colors and class names based on figma colors
         isHighlighted && [
-          "lg:py-px lg:px-[6px] lg:border-medusa-code-icon lg:rounded-docs_sm",
-          "lg:bg-medusa-code-border lg:cursor-pointer",
+          "lg:py-px lg:px-[6px] lg:border-medusa-contrast-border-top lg:rounded-docs_sm",
+          "lg:bg-medusa-contrast-bg-highlight lg:cursor-pointer",
         ]
       )}
     >
@@ -235,7 +232,7 @@ export const CodeBlockLine = ({
       {...lineProps}
       className={clsx(
         "table-row",
-        isHighlightedLine && "bg-medusa-code-bg-header",
+        isHighlightedLine && "bg-medusa-contrast-bg-highlight",
         lineProps.className
       )}
     >
@@ -244,7 +241,6 @@ export const CodeBlockLine = ({
           className={clsx(
             "mr-docs_1 table-cell select-none",
             "sticky left-0 w-[1%] px-docs_1 text-right",
-            bgColorClassName,
             lineNumberColorClassName
           )}
         >
diff --git a/www/packages/docs-ui/src/components/CodeBlock/index.tsx b/www/packages/docs-ui/src/components/CodeBlock/index.tsx
index 9a3022fd4b..a103b65115 100644
--- a/www/packages/docs-ui/src/components/CodeBlock/index.tsx
+++ b/www/packages/docs-ui/src/components/CodeBlock/index.tsx
@@ -3,14 +3,13 @@
 import React, { useMemo, useState } from "react"
 import clsx from "clsx"
 import { HighlightProps, Highlight, themes } from "prism-react-renderer"
-import { ApiRunner, CopyButton, Tooltip, Link } from "@/components"
+import { ApiRunner } from "@/components"
 import { useColorMode } from "@/providers"
-import { ExclamationCircle, PlaySolid, SquareTwoStack } from "@medusajs/icons"
 import { CodeBlockHeader, CodeBlockHeaderMeta } from "./Header"
 import { CodeBlockLine } from "./Line"
 import { ApiAuthType, ApiDataOptions, ApiMethod } from "types"
 import { CSSTransition } from "react-transition-group"
-import { GITHUB_ISSUES_PREFIX } from "../.."
+import { CodeBlockActions, CodeBlockActionsProps } from "./Actions"
 
 export type Highlight = {
   line: number
@@ -20,6 +19,7 @@ export type Highlight = {
 
 export type CodeBlockMetaFields = {
   title?: string
+  hasTabs?: boolean
   npm2yarn?: boolean
   highlights?: string[][]
   apiTesting?: boolean
@@ -48,6 +48,7 @@ export type CodeBlockProps = {
 
 export const CodeBlock = ({
   source,
+  hasTabs = false,
   lang = "",
   className,
   collapsed = false,
@@ -67,6 +68,10 @@ export const CodeBlock = ({
 
   const { colorMode } = useColorMode()
   const [showTesting, setShowTesting] = useState(false)
+  const hasInnerCodeBlock = useMemo(
+    () => hasTabs || title.length > 0,
+    [hasTabs, title]
+  )
   const canShowApiTesting = useMemo(
     () =>
       apiTesting !== undefined &&
@@ -78,10 +83,7 @@ export const CodeBlock = ({
   const bgColor = useMemo(
     () =>
       clsx(
-        blockStyle === "loud" && [
-          colorMode === "light" && "bg-medusa-code-bg-base",
-          colorMode === "dark" && "bg-medusa-bg-component",
-        ],
+        blockStyle === "loud" && "bg-medusa-contrast-bg-base",
         blockStyle === "subtle" && [
           colorMode === "light" && "bg-medusa-bg-subtle",
           colorMode === "dark" && "bg-medusa-code-bg-base",
@@ -93,13 +95,10 @@ export const CodeBlock = ({
   const lineNumbersColor = useMemo(
     () =>
       clsx(
-        blockStyle === "loud" && [
-          colorMode === "light" && "text-medusa-code-text-subtle",
-          colorMode === "dark" && "text-medusa-fg-muted",
-        ],
+        blockStyle === "loud" && "text-medusa-contrast-fg-secondary",
         blockStyle === "subtle" && [
           colorMode === "light" && "text-medusa-fg-muted",
-          colorMode === "dark" && "text-medusa-code-text-subtle",
+          colorMode === "dark" && "text-medusa-contrast-fg-secondary",
         ]
       ),
     [blockStyle, colorMode]
@@ -108,10 +107,7 @@ export const CodeBlock = ({
   const borderColor = useMemo(
     () =>
       clsx(
-        blockStyle === "loud" && [
-          colorMode === "light" && "border-medusa-code-border",
-          colorMode === "dark" && "border-medusa-border-base",
-        ],
+        blockStyle === "loud" && "border-transparent",
         blockStyle === "subtle" && [
           colorMode === "light" && "border-medusa-border-base",
           colorMode === "dark" && "border-medusa-code-border",
@@ -120,21 +116,48 @@ export const CodeBlock = ({
     [blockStyle, colorMode]
   )
 
-  const iconColor = useMemo(
+  const boxShadow = useMemo(
+    () =>
+      clsx(
+        blockStyle === "loud" &&
+          "shadow-elevation-code-block dark:shadow-elevation-code-block-dark",
+        blockStyle === "subtle" && "shadow-none"
+      ),
+    [blockStyle]
+  )
+
+  const innerBgColor = useMemo(
     () =>
       clsx(
         blockStyle === "loud" && [
-          colorMode === "light" && "text-medusa-code-icon",
-          colorMode === "dark" && "text-medusa-fg-muted",
+          hasInnerCodeBlock && "bg-medusa-contrast-bg-subtle",
+          !hasInnerCodeBlock && "bg-medusa-contrast-bg-base",
         ],
-        blockStyle === "subtle" && [
-          colorMode === "light" && "text-medusa-fg-muted",
-          colorMode === "dark" && "text-medusa-code-icon",
-        ]
+        blockStyle === "subtle" && bgColor
       ),
-    [blockStyle, colorMode]
+    [blockStyle, bgColor, hasInnerCodeBlock]
   )
 
+  const innerBorderClasses = useMemo(
+    () =>
+      clsx(
+        blockStyle === "loud" && [
+          hasInnerCodeBlock &&
+            "border border-solid border-medusa-contrast-border-bot rounded-docs_DEFAULT",
+          !hasInnerCodeBlock && "border-transparent rounded-docs_DEFAULT",
+        ],
+        blockStyle === "subtle" && "border-transparent rounded-docs_DEFAULT"
+      ),
+    [blockStyle, hasInnerCodeBlock]
+  )
+
+  const language = useMemo(() => {
+    const lowerLang = lang.toLowerCase()
+
+    // due to a hydration error in json, for now we just assign it to plain
+    return lowerLang === "json" ? "plain" : lowerLang
+  }, [lang])
+
   if (!source.length) {
     return <></>
   }
@@ -147,164 +170,120 @@ export const CodeBlock = ({
       tooltipText: highlight.length >= 3 ? highlight[2] : undefined,
     }))
 
+  const actionsProps: Omit<CodeBlockActionsProps, "inHeader"> = {
+    source,
+    canShowApiTesting,
+    onApiTesting: setShowTesting,
+    blockStyle,
+    noReport,
+    noCopy,
+  }
+
   return (
     <>
-      {title && (
-        <CodeBlockHeader
-          title={title}
-          blockStyle={blockStyle}
-          badgeLabel={rest.badgeLabel}
-          badgeColor={rest.badgeColor}
-        />
-      )}
       <div
         className={clsx(
-          "relative mb-docs_1 rounded-b-docs_DEFAULT",
-          "w-full max-w-full border",
-          bgColor,
-          borderColor,
-          collapsed && "max-h-[400px] overflow-auto",
-          !title && "rounded-t-docs_DEFAULT",
+          hasInnerCodeBlock && "rounded-docs_lg",
+          !hasInnerCodeBlock && "rounded-docs_DEFAULT",
+          !hasTabs && boxShadow,
           (blockStyle === "loud" || colorMode !== "light") &&
             "code-block-highlight-dark",
           blockStyle === "subtle" &&
             colorMode === "light" &&
-            "code-block-highlight-light",
-          className
+            "code-block-highlight-light"
         )}
       >
-        <Highlight
-          theme={
-            blockStyle === "loud" || colorMode === "dark"
-              ? {
-                  ...themes.vsDark,
-                  plain: {
-                    ...themes.vsDark.plain,
-                    backgroundColor:
-                      blockStyle === "loud"
-                        ? colorMode === "light"
-                          ? "#111827"
-                          : "#27282D"
-                        : "#1B1B1F",
-                  },
-                }
-              : {
-                  ...themes.vsLight,
-                  plain: {
-                    ...themes.vsLight.plain,
-                    backgroundColor: "#F9FAFB",
-                  },
-                }
-          }
-          code={source.trim()}
-          language={lang.toLowerCase()}
-          {...rest}
+        {title && (
+          <CodeBlockHeader
+            title={title}
+            blockStyle={blockStyle}
+            badgeLabel={rest.badgeLabel}
+            badgeColor={rest.badgeColor}
+            actionsProps={{
+              ...actionsProps,
+              inHeader: true,
+            }}
+          />
+        )}
+        <div
+          className={clsx(
+            "relative mb-docs_1",
+            "w-full max-w-full border",
+            bgColor,
+            borderColor,
+            collapsed && "max-h-[400px] overflow-auto",
+            hasInnerCodeBlock && "p-[5px] !pt-0 rounded-b-docs_lg",
+            !hasInnerCodeBlock && "rounded-docs_DEFAULT",
+            className
+          )}
         >
-          {({ className: preClassName, style, tokens, ...rest }) => (
-            <>
-              <pre
-                style={{ ...style, fontStretch: "100%" }}
-                className={clsx(
-                  "relative !my-0 break-words bg-transparent !outline-none",
-                  "overflow-auto break-words rounded-docs_DEFAULT p-0 xs:max-w-[83%]",
-                  preClassName
-                )}
-              >
-                <code
+          <Highlight
+            theme={
+              blockStyle === "loud" || colorMode === "dark"
+                ? themes.vsDark
+                : themes.vsLight
+            }
+            code={source.trim()}
+            language={language}
+            {...rest}
+          >
+            {({
+              className: preClassName,
+              style: { backgroundColor, ...style },
+              tokens,
+              ...rest
+            }) => (
+              <div className={clsx(innerBorderClasses, innerBgColor)}>
+                <pre
+                  style={{ ...style, fontStretch: "100%" }}
                   className={clsx(
-                    "text-code-body font-monospace table min-w-full pb-docs_1.5 print:whitespace-pre-wrap",
-                    tokens.length > 1 && "pt-docs_1 pr-docs_1",
-                    tokens.length <= 1 && "!py-docs_0.25 px-[6px]"
+                    "relative !my-0 break-words bg-transparent !outline-none",
+                    "overflow-auto break-words p-0",
+                    "rounded-docs_DEFAULT",
+                    !hasInnerCodeBlock &&
+                      tokens.length <= 1 &&
+                      "px-docs_0.5 py-[6px]",
+                    !title.length && "xs:max-w-[83%]",
+                    preClassName
                   )}
                 >
-                  {tokens.map((line, i) => {
-                    const highlightedLines = transformedHighlights.filter(
-                      (highlight) => highlight.line - 1 === i
-                    )
+                  <code
+                    className={clsx(
+                      "text-code-body font-monospace table min-w-full print:whitespace-pre-wrap",
+                      tokens.length > 1 && "py-docs_0.75",
+                      tokens.length <= 1 && "!py-[6px] px-docs_0.5"
+                    )}
+                  >
+                    {tokens.map((line, i) => {
+                      const highlightedLines = transformedHighlights.filter(
+                        (highlight) => highlight.line - 1 === i
+                      )
 
-                    return (
-                      <CodeBlockLine
-                        line={line}
-                        lineNumber={i}
-                        highlights={highlightedLines}
-                        showLineNumber={!noLineNumbers && tokens.length > 1}
-                        key={i}
-                        bgColorClassName={bgColor}
-                        lineNumberColorClassName={lineNumbersColor}
-                        {...rest}
-                      />
-                    )
-                  })}
-                </code>
-              </pre>
-              <div
-                className={clsx(
-                  "absolute hidden md:flex md:justify-end",
-                  "xs:rounded xs:absolute xs:right-0 xs:top-0 xs:w-[calc(10%+24px)] xs:h-full xs:bg-transparent",
-                  tokens.length === 1 && "md:right-[6px] md:top-0",
-                  tokens.length > 1 && "md:right-docs_1 md:top-docs_1"
-                )}
-              >
-                {canShowApiTesting && (
-                  <Tooltip
-                    text="Test API"
-                    tooltipClassName="font-base"
-                    className={clsx(
-                      "h-fit",
-                      tokens.length === 1 && "p-[6px]",
-                      tokens.length > 1 && "px-[6px] pb-[6px]"
-                    )}
-                  >
-                    <PlaySolid
-                      className={clsx("cursor-pointer", iconColor)}
-                      onClick={() => setShowTesting(true)}
-                    />
-                  </Tooltip>
-                )}
-                {!noReport && (
-                  <Tooltip
-                    text="Report Issue"
-                    tooltipClassName="font-base"
-                    className={clsx(
-                      "h-fit",
-                      tokens.length === 1 && "p-[6px]",
-                      tokens.length > 1 && "px-[6px] pb-[6px]"
-                    )}
-                  >
-                    <Link
-                      href={`${GITHUB_ISSUES_PREFIX}&title=${encodeURIComponent(
-                        `Docs(Code Issue): `
-                      )}`}
-                      target="_blank"
-                      className={clsx(
-                        blockStyle === "loud" && "hover:bg-medusa-code-bg-base",
-                        "bg-transparent border-none cursor-pointer rounded",
-                        "[&:not(:first-child)]:ml-docs_0.5",
-                        "inline-flex justify-center items-center invisible xs:visible"
-                      )}
-                      rel="noreferrer"
-                    >
-                      <ExclamationCircle className={clsx(iconColor)} />
-                    </Link>
-                  </Tooltip>
-                )}
-                {!noCopy && (
-                  <CopyButton
-                    text={source}
-                    tooltipClassName="font-base"
-                    className={clsx(
-                      "h-fit",
-                      tokens.length === 1 && "p-[6px]",
-                      tokens.length > 1 && "px-[6px] pb-[6px]"
-                    )}
-                  >
-                    <SquareTwoStack className={clsx(iconColor)} />
-                  </CopyButton>
+                      return (
+                        <CodeBlockLine
+                          line={line}
+                          lineNumber={i}
+                          highlights={highlightedLines}
+                          showLineNumber={!noLineNumbers && tokens.length > 1}
+                          key={i}
+                          lineNumberColorClassName={lineNumbersColor}
+                          {...rest}
+                        />
+                      )
+                    })}
+                  </code>
+                </pre>
+                {!title && (
+                  <CodeBlockActions
+                    {...actionsProps}
+                    inHeader={false}
+                    isSingleLine={tokens.length <= 1}
+                  />
                 )}
               </div>
-            </>
-          )}
-        </Highlight>
+            )}
+          </Highlight>
+        </div>
       </div>
       {canShowApiTesting && (
         <CSSTransition
diff --git a/www/packages/docs-ui/src/components/CodeTabs/Item/index.tsx b/www/packages/docs-ui/src/components/CodeTabs/Item/index.tsx
index 5f3d2385c3..187e75709b 100644
--- a/www/packages/docs-ui/src/components/CodeTabs/Item/index.tsx
+++ b/www/packages/docs-ui/src/components/CodeTabs/Item/index.tsx
@@ -29,35 +29,23 @@ export const CodeTab = ({
     <li>
       <button
         className={clsx(
-          "text-compact-small-plus xs:border-0 py-docs_0.25 px-docs_0.75 relative rounded-full border",
+          "text-compact-x-small-plus font-base xs:border-0 pb-docs_0.5 relative",
           !isSelected && [
-            "text-medusa-code-text-subtle border-transparent",
-            blockStyle === "loud" && [
-              colorMode === "light" &&
-                "text-medusa-code-text-subtle hover:bg-medusa-code-bg-base",
-              colorMode === "dark" &&
-                "text-medusa-fg-muted hover:bg-medusa-bg-component",
-            ],
+            blockStyle === "loud" && "text-medusa-contrast-fg-secondary",
             blockStyle === "subtle" && [
               colorMode === "light" &&
                 "text-medusa-fg-subtle hover:bg-medusa-bg-base",
               colorMode === "dark" &&
-                "text-medusa-code-text-subtle hover:bg-medusa-code-bg-base",
+                "text-medusa-contrast-fg-secondary hover:bg-medusa-code-bg-base",
             ],
           ],
           isSelected && [
-            "xs:!bg-transparent",
-            blockStyle === "loud" && [
-              colorMode === "light" &&
-                "border-medusa-code-border text-medusa-code-text-base",
-              colorMode === "dark" &&
-                "border-medusa-border-base text-medusa-fg-base",
-            ],
+            blockStyle === "loud" && "text-medusa-contrast-fg-primary",
             blockStyle === "subtle" && [
               colorMode === "light" &&
-                "xs:border-medusa-border-base text-medusa-code-text-base",
+                "xs:border-medusa-border-base text-medusa-contrast-fg-primary",
               colorMode === "dark" &&
-                "xs:border-medusa-code-border text-medusa-code-text-base",
+                "xs:border-medusa-code-border text-medusa-contrast-fg-primary",
             ],
           ]
         )}
diff --git a/www/packages/docs-ui/src/components/CodeTabs/index.tsx b/www/packages/docs-ui/src/components/CodeTabs/index.tsx
index 0b526d0ff2..c569268c77 100644
--- a/www/packages/docs-ui/src/components/CodeTabs/index.tsx
+++ b/www/packages/docs-ui/src/components/CodeTabs/index.tsx
@@ -2,6 +2,7 @@
 
 import React, { Children, useCallback, useEffect, useMemo, useRef } from "react"
 import {
+  Badge,
   BaseTabType,
   CodeBlockProps,
   CodeBlockStyle,
@@ -9,7 +10,6 @@ import {
   useTabs,
 } from "../.."
 import clsx from "clsx"
-import { CodeBlockHeader } from "../CodeBlock/Header"
 
 type CodeTab = BaseTabType & {
   codeProps: CodeBlockProps
@@ -28,7 +28,6 @@ export const CodeTabs = ({
   children,
   className,
   group = "client",
-  title,
   blockStyle = "loud",
 }: CodeTabProps) => {
   const { colorMode } = useColorMode()
@@ -59,8 +58,9 @@ export const CodeTabs = ({
           ...codeBlock,
           props: {
             ...codeBlock.props,
-            title: undefined,
-            className: clsx("!mt-0 !rounded-t-none", codeBlock.props.className),
+            badgeLabel: undefined,
+            hasTabs: true,
+            className: clsx("!my-0", codeBlock.props.className),
           },
         },
       })
@@ -78,6 +78,28 @@ export const CodeTabs = ({
   const codeTabSelectorRef = useRef<HTMLSpanElement | null>(null)
   const codeTabsWrapperRef = useRef<HTMLDivElement | null>(null)
 
+  const bgColor = useMemo(
+    () =>
+      clsx(
+        blockStyle === "loud" && "bg-medusa-contrast-bg-base",
+        blockStyle === "subtle" && [
+          colorMode === "light" && "bg-medusa-bg-component",
+          colorMode === "dark" && "bg-medusa-code-bg-header",
+        ]
+      ),
+    [blockStyle, colorMode]
+  )
+
+  const boxShadow = useMemo(
+    () =>
+      clsx(
+        blockStyle === "loud" &&
+          "shadow-elevation-code-block dark:shadow-elevation-code-block-dark",
+        blockStyle === "subtle" && "shadow-none"
+      ),
+    [blockStyle]
+  )
+
   const changeTabSelectorCoordinates = useCallback(
     (selectedTabElm: HTMLElement) => {
       if (!codeTabSelectorRef?.current || !codeTabsWrapperRef?.current) {
@@ -90,9 +112,11 @@ export const CodeTabs = ({
         selectedTabsCoordinates.left - tabsWrapperCoordinates.left
       }px`
       codeTabSelectorRef.current.style.width = `${selectedTabsCoordinates.width}px`
-      codeTabSelectorRef.current.style.height = `${selectedTabsCoordinates.height}px`
+      if (blockStyle !== "loud") {
+        codeTabSelectorRef.current.style.height = `${selectedTabsCoordinates.height}px`
+      }
     },
-    []
+    [blockStyle]
   )
 
   useEffect(() => {
@@ -111,34 +135,39 @@ export const CodeTabs = ({
   return (
     <div
       className={clsx(
-        "relative my-docs_1 w-full max-w-full overflow-auto",
+        "my-docs_1 w-full max-w-full",
+        "rounded-docs_lg",
+        bgColor,
+        boxShadow,
         className
       )}
-      ref={codeTabsWrapperRef}
     >
-      <span
+      <div
         className={clsx(
-          "xs:absolute xs:border xs:border-solid",
-          "xs:transition-all xs:duration-200 xs:ease-ease xs:top-[13px] xs:rounded-full",
-          blockStyle === "loud" && [
-            colorMode === "light" &&
-              "xs:border-medusa-code-border xs:bg-medusa-code-bg-base",
-            colorMode === "dark" &&
-              "xs:border-medusa-border-base xs:bg-medusa-bg-component",
-          ],
-          blockStyle === "subtle" && [
-            colorMode === "light" &&
-              "xs:border-medusa-border-base xs:bg-medusa-bg-base",
-            colorMode === "dark" &&
-              "xs:border-medusa-code-border xs:bg-medusa-code-bg-base",
-          ]
+          "flex gap-docs_0.75 relative",
+          "pt-[10px] px-docs_1 pb-px",
+          blockStyle === "loud" &&
+            selectedTab?.codeProps.title &&
+            "border border-solid border-b border-medusa-contrast-border-bot"
         )}
-        ref={codeTabSelectorRef}
-      ></span>
-      <CodeBlockHeader title={selectedTab?.codeProps?.title || title}>
+        ref={codeTabsWrapperRef}
+      >
+        <span
+          className={clsx(
+            "xs:absolute xs:transition-all xs:duration-200 xs:ease-ease xs:bottom-0",
+            blockStyle === "loud" && "bg-medusa-contrast-fg-primary h-px",
+            blockStyle === "subtle" && [
+              colorMode === "light" &&
+                "xs:border-medusa-border-base xs:bg-medusa-bg-base",
+              colorMode === "dark" &&
+                "xs:border-medusa-code-border xs:bg-medusa-code-bg-base",
+            ]
+          )}
+          ref={codeTabSelectorRef}
+        ></span>
         <ul
           className={clsx(
-            "!list-none flex gap-docs_0.25 items-center",
+            "!list-none flex gap-docs_0.75 items-center",
             "p-0 mb-0"
           )}
         >
@@ -164,7 +193,12 @@ export const CodeTabs = ({
             )
           })}
         </ul>
-      </CodeBlockHeader>
+        {selectedTab?.codeProps.badgeLabel && (
+          <Badge variant={selectedTab?.codeProps.badgeColor || "code"}>
+            {selectedTab.codeProps.badgeLabel}
+          </Badge>
+        )}
+      </div>
       {selectedTab?.codeBlock}
     </div>
   )
diff --git a/www/packages/docs-ui/src/components/Icons/AiAssistant/index.tsx b/www/packages/docs-ui/src/components/Icons/AiAssistant/index.tsx
new file mode 100644
index 0000000000..fc52b9f172
--- /dev/null
+++ b/www/packages/docs-ui/src/components/Icons/AiAssistant/index.tsx
@@ -0,0 +1,442 @@
+import React from "react"
+import { IconProps } from "@medusajs/icons/dist/types"
+
+export const AiAssistantIcon = (props: IconProps) => {
+  return (
+    <svg
+      width="19"
+      height="20"
+      viewBox="0 0 19 20"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <g filter="url(#filter0_diii_7480_20594)">
+        <circle
+          cx="9.5"
+          cy="9.00002"
+          r="7.11"
+          fill="url(#paint0_linear_7480_20594)"
+        />
+        <circle
+          cx="9.5"
+          cy="9.00002"
+          r="7.11"
+          fill="url(#paint1_linear_7480_20594)"
+        />
+      </g>
+      <g filter="url(#filter1_f_7480_20594)">
+        <circle cx="9.5" cy="6.5" r="4" fill="url(#paint2_linear_7480_20594)" />
+        <circle
+          cx="9.5"
+          cy="6.5"
+          r="3.9"
+          stroke="url(#paint3_linear_7480_20594)"
+          strokeWidth="0.2"
+        />
+      </g>
+      <g
+        style={{
+          mixBlendMode: "plus-lighter",
+        }}
+        filter="url(#filter2_f_7480_20594)"
+      >
+        <circle cx="12" cy="10" r="4" fill="url(#paint4_linear_7480_20594)" />
+        <circle
+          cx="12"
+          cy="10"
+          r="3.9"
+          stroke="url(#paint5_linear_7480_20594)"
+          strokeWidth="0.2"
+        />
+      </g>
+      <g
+        style={{
+          mixBlendMode: "plus-lighter",
+        }}
+        filter="url(#filter3_f_7480_20594)"
+      >
+        <circle
+          cx="4"
+          cy="4"
+          r="4"
+          transform="matrix(-1 0 0 1 11 4)"
+          fill="url(#paint6_linear_7480_20594)"
+        />
+        <circle
+          cx="4"
+          cy="4"
+          r="3.9"
+          transform="matrix(-1 0 0 1 11 4)"
+          stroke="url(#paint7_linear_7480_20594)"
+          strokeWidth="0.2"
+        />
+      </g>
+      <g
+        style={{
+          mixBlendMode: "plus-lighter",
+        }}
+        filter="url(#filter4_f_7480_20594)"
+      >
+        <circle
+          cx="4"
+          cy="4"
+          r="4"
+          transform="matrix(0 -1 -1 0 13.5 13)"
+          fill="url(#paint8_linear_7480_20594)"
+        />
+        <circle
+          cx="4"
+          cy="4"
+          r="3.9"
+          transform="matrix(0 -1 -1 0 13.5 13)"
+          stroke="url(#paint9_linear_7480_20594)"
+          strokeWidth="0.2"
+        />
+      </g>
+      <g filter="url(#filter5_f_7480_20594)">
+        <circle
+          cx="4"
+          cy="4"
+          r="4"
+          transform="matrix(-1 0 0 1 13.5 7.5)"
+          fill="url(#paint10_linear_7480_20594)"
+        />
+        <circle
+          cx="4"
+          cy="4"
+          r="3.9"
+          transform="matrix(-1 0 0 1 13.5 7.5)"
+          stroke="url(#paint11_linear_7480_20594)"
+          strokeWidth="0.2"
+        />
+      </g>
+      <defs>
+        <filter
+          id="filter0_diii_7480_20594"
+          x="0.389999"
+          y="0.890015"
+          width="18.22"
+          height="18.22"
+          filterUnits="userSpaceOnUse"
+          colorInterpolationFilters="sRGB"
+        >
+          <feFlood floodOpacity="0" result="BackgroundImageFix" />
+          <feColorMatrix
+            in="SourceAlpha"
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+            result="hardAlpha"
+          />
+          <feOffset dy="1" />
+          <feGaussianBlur stdDeviation="1" />
+          <feComposite in2="hardAlpha" operator="out" />
+          <feColorMatrix
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.12 0"
+          />
+          <feBlend
+            mode="normal"
+            in2="BackgroundImageFix"
+            result="effect1_dropShadow_7480_20594"
+          />
+          <feBlend
+            mode="normal"
+            in="SourceGraphic"
+            in2="effect1_dropShadow_7480_20594"
+            result="shape"
+          />
+          <feColorMatrix
+            in="SourceAlpha"
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+            result="hardAlpha"
+          />
+          <feOffset dx="-0.25" dy="-0.25" />
+          <feComposite in2="hardAlpha" operator="arithmetic" k2="-1" k3="1" />
+          <feColorMatrix
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.2 0"
+          />
+          <feBlend
+            mode="normal"
+            in2="shape"
+            result="effect2_innerShadow_7480_20594"
+          />
+          <feColorMatrix
+            in="SourceAlpha"
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+            result="hardAlpha"
+          />
+          <feOffset dx="0.25" dy="0.25" />
+          <feComposite in2="hardAlpha" operator="arithmetic" k2="-1" k3="1" />
+          <feColorMatrix
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0.5 0"
+          />
+          <feBlend
+            mode="normal"
+            in2="effect2_innerShadow_7480_20594"
+            result="effect3_innerShadow_7480_20594"
+          />
+          <feColorMatrix
+            in="SourceAlpha"
+            type="matrix"
+            values="0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 127 0"
+            result="hardAlpha"
+          />
+          <feOffset dx="1" dy="1" />
+          <feGaussianBlur stdDeviation="1" />
+          <feComposite in2="hardAlpha" operator="arithmetic" k2="-1" k3="1" />
+          <feColorMatrix
+            type="matrix"
+            values="0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0.6 0"
+          />
+          <feBlend
+            mode="normal"
+            in2="effect3_innerShadow_7480_20594"
+            result="effect4_innerShadow_7480_20594"
+          />
+        </filter>
+        <filter
+          id="filter1_f_7480_20594"
+          x="5"
+          y="2"
+          width="9"
+          height="9"
+          filterUnits="userSpaceOnUse"
+          colorInterpolationFilters="sRGB"
+        >
+          <feFlood floodOpacity="0" result="BackgroundImageFix" />
+          <feBlend
+            mode="normal"
+            in="SourceGraphic"
+            in2="BackgroundImageFix"
+            result="shape"
+          />
+          <feGaussianBlur
+            stdDeviation="0.25"
+            result="effect1_foregroundBlur_7480_20594"
+          />
+        </filter>
+        <filter
+          id="filter2_f_7480_20594"
+          x="7.5"
+          y="5.5"
+          width="9"
+          height="9"
+          filterUnits="userSpaceOnUse"
+          colorInterpolationFilters="sRGB"
+        >
+          <feFlood floodOpacity="0" result="BackgroundImageFix" />
+          <feBlend
+            mode="normal"
+            in="SourceGraphic"
+            in2="BackgroundImageFix"
+            result="shape"
+          />
+          <feGaussianBlur
+            stdDeviation="0.25"
+            result="effect1_foregroundBlur_7480_20594"
+          />
+        </filter>
+        <filter
+          id="filter3_f_7480_20594"
+          x="2.5"
+          y="3.5"
+          width="9"
+          height="9"
+          filterUnits="userSpaceOnUse"
+          colorInterpolationFilters="sRGB"
+        >
+          <feFlood floodOpacity="0" result="BackgroundImageFix" />
+          <feBlend
+            mode="normal"
+            in="SourceGraphic"
+            in2="BackgroundImageFix"
+            result="shape"
+          />
+          <feGaussianBlur
+            stdDeviation="0.25"
+            result="effect1_foregroundBlur_7480_20594"
+          />
+        </filter>
+        <filter
+          id="filter4_f_7480_20594"
+          x="5"
+          y="4.5"
+          width="9"
+          height="9"
+          filterUnits="userSpaceOnUse"
+          colorInterpolationFilters="sRGB"
+        >
+          <feFlood floodOpacity="0" result="BackgroundImageFix" />
+          <feBlend
+            mode="normal"
+            in="SourceGraphic"
+            in2="BackgroundImageFix"
+            result="shape"
+          />
+          <feGaussianBlur
+            stdDeviation="0.25"
+            result="effect1_foregroundBlur_7480_20594"
+          />
+        </filter>
+        <filter
+          id="filter5_f_7480_20594"
+          x="5"
+          y="7"
+          width="9"
+          height="9"
+          filterUnits="userSpaceOnUse"
+          colorInterpolationFilters="sRGB"
+        >
+          <feFlood floodOpacity="0" result="BackgroundImageFix" />
+          <feBlend
+            mode="normal"
+            in="SourceGraphic"
+            in2="BackgroundImageFix"
+            result="shape"
+          />
+          <feGaussianBlur
+            stdDeviation="0.25"
+            result="effect1_foregroundBlur_7480_20594"
+          />
+        </filter>
+        <linearGradient
+          id="paint0_linear_7480_20594"
+          x1="9.5"
+          y1="1.89002"
+          x2="9.5"
+          y2="16.11"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop offset="0.2" stopColor="#8952FD" />
+          <stop offset="0.8" stopColor="#48EAEB" />
+        </linearGradient>
+        <linearGradient
+          id="paint1_linear_7480_20594"
+          x1="5.11519"
+          y1="8.96784"
+          x2="13.4627"
+          y2="12.0584"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop stopColor="#5B53FF" stopOpacity="0.8" />
+          <stop offset="1" stopColor="white" stopOpacity="0.1" />
+        </linearGradient>
+        <linearGradient
+          id="paint2_linear_7480_20594"
+          x1="9.5"
+          y1="6.5"
+          x2="13.5"
+          y2="6.5"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop stopColor="#5B53FF" stopOpacity="0.1" />
+          <stop offset="1" stopColor="white" stopOpacity="0.3" />
+        </linearGradient>
+        <linearGradient
+          id="paint3_linear_7480_20594"
+          x1="13.5"
+          y1="6.5"
+          x2="9.5"
+          y2="6.5"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop stopColor="white" />
+          <stop offset="1" stopColor="white" stopOpacity="0" />
+        </linearGradient>
+        <linearGradient
+          id="paint4_linear_7480_20594"
+          x1="12"
+          y1="10"
+          x2="16"
+          y2="10"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop stopColor="#5B53FF" stopOpacity="0.1" />
+          <stop offset="1" stopColor="white" stopOpacity="0.3" />
+        </linearGradient>
+        <linearGradient
+          id="paint5_linear_7480_20594"
+          x1="16"
+          y1="10"
+          x2="12"
+          y2="10"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop stopColor="#3B82F6" />
+          <stop offset="1" stopColor="#3B82F6" stopOpacity="0" />
+        </linearGradient>
+        <linearGradient
+          id="paint6_linear_7480_20594"
+          x1="4"
+          y1="4"
+          x2="8"
+          y2="4"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop stopColor="#5B53FF" stopOpacity="0.1" />
+          <stop offset="1" stopColor="white" stopOpacity="0.3" />
+        </linearGradient>
+        <linearGradient
+          id="paint7_linear_7480_20594"
+          x1="8"
+          y1="4"
+          x2="4"
+          y2="4"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop stopColor="#48EAEB" />
+          <stop offset="1" stopColor="#48EAEB" stopOpacity="0" />
+        </linearGradient>
+        <linearGradient
+          id="paint8_linear_7480_20594"
+          x1="4"
+          y1="4"
+          x2="8"
+          y2="4"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop stopColor="#5B53FF" stopOpacity="0.1" />
+          <stop offset="1" stopColor="white" stopOpacity="0.3" />
+        </linearGradient>
+        <linearGradient
+          id="paint9_linear_7480_20594"
+          x1="8"
+          y1="4"
+          x2="4"
+          y2="4"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop stopColor="#3B82F6" />
+          <stop offset="1" stopColor="#3B82F6" stopOpacity="0" />
+        </linearGradient>
+        <linearGradient
+          id="paint10_linear_7480_20594"
+          x1="4"
+          y1="4"
+          x2="8"
+          y2="4"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop stopColor="#5B53FF" stopOpacity="0.1" />
+          <stop offset="1" stopColor="white" stopOpacity="0.3" />
+        </linearGradient>
+        <linearGradient
+          id="paint11_linear_7480_20594"
+          x1="8"
+          y1="4"
+          x2="4"
+          y2="4"
+          gradientUnits="userSpaceOnUse"
+        >
+          <stop stopColor="white" />
+          <stop offset="1" stopColor="white" stopOpacity="0" />
+        </linearGradient>
+      </defs>
+    </svg>
+  )
+}
diff --git a/www/packages/docs-ui/src/components/Icons/ShadedBg/index.tsx b/www/packages/docs-ui/src/components/Icons/ShadedBg/index.tsx
new file mode 100644
index 0000000000..e73f4407d0
--- /dev/null
+++ b/www/packages/docs-ui/src/components/Icons/ShadedBg/index.tsx
@@ -0,0 +1,248 @@
+"use client"
+
+import React, { useMemo } from "react"
+import { IconProps } from "@medusajs/icons/dist/types"
+import { BadgeVariant } from "../../.."
+
+type ShadedBgIconProps = IconProps & {
+  variant?: BadgeVariant
+}
+
+export const ShadedBgIcon = ({
+  variant = "blue",
+  ...props
+}: ShadedBgIconProps) => {
+  const color = useMemo(() => {
+    switch (variant) {
+      case "neutral":
+      case "code":
+        return "#E4E4E7"
+      case "blue":
+        return "#BFDBFE"
+      case "purple":
+        return "#DDD6FE"
+      case "green":
+        return "#A7F3D0"
+      case "orange":
+        return "#FED7AA"
+      case "red":
+        return "#FECDD3"
+    }
+  }, [variant])
+
+  return (
+    <svg
+      width="33"
+      height="20"
+      viewBox="0 0 33 20"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <g clipPath="url(#clip0_7397_14857)">
+        <rect
+          x="10.136"
+          y="-41.6187"
+          width="1.5"
+          height="64"
+          transform="rotate(45 10.136 -41.6187)"
+          fill={color}
+        />
+        <rect
+          x="12.6109"
+          y="-39.1439"
+          width="1.5"
+          height="64"
+          transform="rotate(45 12.6109 -39.1439)"
+          fill={color}
+        />
+        <rect
+          x="15.0858"
+          y="-36.6689"
+          width="1.5"
+          height="64"
+          transform="rotate(45 15.0858 -36.6689)"
+          fill={color}
+        />
+        <rect
+          x="17.5607"
+          y="-34.1941"
+          width="1.5"
+          height="64"
+          transform="rotate(45 17.5607 -34.1941)"
+          fill={color}
+        />
+        <rect
+          x="20.0355"
+          y="-31.7192"
+          width="1.5"
+          height="64"
+          transform="rotate(45 20.0355 -31.7192)"
+          fill={color}
+        />
+        <rect
+          x="22.5104"
+          y="-29.2443"
+          width="1.5"
+          height="64"
+          transform="rotate(45 22.5104 -29.2443)"
+          fill={color}
+        />
+        <rect
+          x="24.9853"
+          y="-26.7695"
+          width="1.5"
+          height="64"
+          transform="rotate(45 24.9853 -26.7695)"
+          fill={color}
+        />
+        <rect
+          x="27.4602"
+          y="-24.2946"
+          width="1.5"
+          height="64"
+          transform="rotate(45 27.4602 -24.2946)"
+          fill={color}
+        />
+        <rect
+          x="29.935"
+          y="-21.8197"
+          width="1.5"
+          height="64"
+          transform="rotate(45 29.935 -21.8197)"
+          fill={color}
+        />
+        <rect
+          x="32.4099"
+          y="-19.3448"
+          width="1.5"
+          height="64"
+          transform="rotate(45 32.4099 -19.3448)"
+          fill={color}
+        />
+        <rect
+          x="34.8848"
+          y="-16.87"
+          width="1.5"
+          height="64"
+          transform="rotate(45 34.8848 -16.87)"
+          fill={color}
+        />
+        <rect
+          x="37.3597"
+          y="-14.3951"
+          width="1.5"
+          height="64"
+          transform="rotate(45 37.3597 -14.3951)"
+          fill={color}
+        />
+        <rect
+          x="39.8345"
+          y="-11.9202"
+          width="1.5"
+          height="64"
+          transform="rotate(45 39.8345 -11.9202)"
+          fill={color}
+        />
+        <rect
+          x="42.3094"
+          y="-9.44537"
+          width="1.5"
+          height="64"
+          transform="rotate(45 42.3094 -9.44537)"
+          fill={color}
+        />
+        <rect
+          x="44.7843"
+          y="-6.97046"
+          width="1.5"
+          height="64"
+          transform="rotate(45 44.7843 -6.97046)"
+          fill={color}
+        />
+        <rect
+          x="47.2592"
+          y="-4.49561"
+          width="1.5"
+          height="64"
+          transform="rotate(45 47.2592 -4.49561)"
+          fill={color}
+        />
+        <rect
+          x="49.734"
+          y="-2.02075"
+          width="1.5"
+          height="64"
+          transform="rotate(45 49.734 -2.02075)"
+          fill={color}
+        />
+        <rect
+          x="52.2089"
+          y="0.454163"
+          width="1.5"
+          height="64"
+          transform="rotate(45 52.2089 0.454163)"
+          fill={color}
+        />
+        <rect
+          x="54.6838"
+          y="2.92902"
+          width="1.5"
+          height="64"
+          transform="rotate(45 54.6838 2.92902)"
+          fill={color}
+        />
+        <rect
+          x="57.1586"
+          y="5.40387"
+          width="1.5"
+          height="64"
+          transform="rotate(45 57.1586 5.40387)"
+          fill={color}
+        />
+        <rect
+          x="59.6335"
+          y="7.87878"
+          width="1.5"
+          height="64"
+          transform="rotate(45 59.6335 7.87878)"
+          fill={color}
+        />
+        <rect
+          x="62.1084"
+          y="10.3536"
+          width="1.5"
+          height="64"
+          transform="rotate(45 62.1084 10.3536)"
+          fill={color}
+        />
+        <rect
+          x="64.5833"
+          y="12.8285"
+          width="1.5"
+          height="64"
+          transform="rotate(45 64.5833 12.8285)"
+          fill={color}
+        />
+        <rect
+          x="67.0581"
+          y="15.3034"
+          width="1.5"
+          height="64"
+          transform="rotate(45 67.0581 15.3034)"
+          fill={color}
+        />
+      </g>
+      <defs>
+        <clipPath id="clip0_7397_14857">
+          <rect
+            width="82"
+            height="64"
+            fill="white"
+            transform="translate(10.136 -41.6187) rotate(45)"
+          />
+        </clipPath>
+      </defs>
+    </svg>
+  )
+}
diff --git a/www/packages/docs-ui/src/components/Icons/index.tsx b/www/packages/docs-ui/src/components/Icons/index.tsx
index 98ed6342ce..715a261432 100644
--- a/www/packages/docs-ui/src/components/Icons/index.tsx
+++ b/www/packages/docs-ui/src/components/Icons/index.tsx
@@ -1,4 +1,6 @@
+export * from "./AiAssistant"
 export * from "./CircleDottedLine"
 export * from "./QuestionMark"
+export * from "./ShadedBg"
 export * from "./ThumbDown"
 export * from "./ThumbUp"
diff --git a/www/packages/docs-ui/src/components/Input/Text/index.tsx b/www/packages/docs-ui/src/components/Input/Text/index.tsx
index a73997cc30..0024bae140 100644
--- a/www/packages/docs-ui/src/components/Input/Text/index.tsx
+++ b/www/packages/docs-ui/src/components/Input/Text/index.tsx
@@ -20,7 +20,7 @@ export const InputText = ({
     <input
       {...props}
       className={clsx(
-        "bg-medusa-bg-field shadow-button-secondary dark:shadow-button-secondary-dark",
+        "bg-medusa-bg-field shadow-border-base dark:shadow-border-base-dark",
         "border-medusa-border-base rounded-docs_sm border border-solid",
         "px-docs_0.75 py-[9px]",
         "hover:bg-medusa-bg-field-hover",
diff --git a/www/packages/docs-ui/src/components/Kbd/index.tsx b/www/packages/docs-ui/src/components/Kbd/index.tsx
index 6d913fce27..414d9b0c75 100644
--- a/www/packages/docs-ui/src/components/Kbd/index.tsx
+++ b/www/packages/docs-ui/src/components/Kbd/index.tsx
@@ -7,10 +7,10 @@ export const Kbd = ({ children, className, ...props }: KbdProps) => {
   return (
     <kbd
       className={clsx(
-        "rounded-docs_sm border-solid py-0 px-[6px]",
+        "rounded-docs_xs border-solid border border-medusa-border-base",
         "inline-flex items-center justify-center",
-        "border-medusa-tag-neutral-border border",
-        "bg-medusa-tag-neutral-bg",
+        "py-0 px-[6px]",
+        "bg-medusa-bg-field",
         "text-medusa-tag-neutral-text",
         "text-compact-x-small-plus font-base shadow-none",
         className
diff --git a/www/packages/docs-ui/src/components/LearningPath/Icon/index.tsx b/www/packages/docs-ui/src/components/LearningPath/Icon/index.tsx
index 6e14fdbca1..337229b544 100644
--- a/www/packages/docs-ui/src/components/LearningPath/Icon/index.tsx
+++ b/www/packages/docs-ui/src/components/LearningPath/Icon/index.tsx
@@ -18,7 +18,7 @@ export const LearningPathIcon = ({
   return (
     <div
       className={clsx(
-        "rounded-full shadow-card-rest dark:shadow-card-rest-dark w-docs_3 h-docs_3 bg-medusa-bg-base",
+        "rounded-full shadow-elevation-card-rest dark:shadow-elevation-card-rest-dark w-docs_3 h-docs_3 bg-medusa-bg-base",
         "flex justify-center items-center flex-none",
         className
       )}
diff --git a/www/packages/docs-ui/src/components/LearningPath/Steps/index.tsx b/www/packages/docs-ui/src/components/LearningPath/Steps/index.tsx
index 661f712f33..fa64f39aa7 100644
--- a/www/packages/docs-ui/src/components/LearningPath/Steps/index.tsx
+++ b/www/packages/docs-ui/src/components/LearningPath/Steps/index.tsx
@@ -63,7 +63,7 @@ export const LearningPathSteps = ({ ...rest }: LearningPathStepsProps) => {
           {!collapsed && (
             <div
               className={clsx(
-                "bg-medusa-bg-base shadow-flyout dark:shadow-flyout-dark rounded",
+                "bg-medusa-bg-base shadow-elevation-flyout dark:shadow-elevation-flyout-dark rounded",
                 "transition-transform origin-bottom-right flex flex-col"
               )}
               ref={stepsRef}
@@ -134,7 +134,7 @@ export const LearningPathSteps = ({ ...rest }: LearningPathStepsProps) => {
             <Button
               variant="secondary"
               className={clsx(
-                "!p-[10px] !shadow-flyout dark:!shadow-flyout-dark !text-medusa-fg-subtle w-fit h-fit",
+                "!p-[10px] !shadow-elevation-flyout dark:!shadow-elevation-flyout-dark !text-medusa-fg-subtle w-fit h-fit",
                 "rounded-full border-0 mr-0 ml-auto fixed md:relative max-[767px]:bottom-docs_1 max-[767px]:right-docs_1 "
               )}
               onClick={() => setCollapsed(false)}
diff --git a/www/packages/docs-ui/src/components/LearningPath/index.tsx b/www/packages/docs-ui/src/components/LearningPath/index.tsx
index 44b5935eb9..e9d87564e3 100644
--- a/www/packages/docs-ui/src/components/LearningPath/index.tsx
+++ b/www/packages/docs-ui/src/components/LearningPath/index.tsx
@@ -35,7 +35,7 @@ export const LearningPath = ({
   return (
     <div
       className={clsx(
-        "rounded shadow-card-rest dark:shadow-card-rest-dark bg-docs-bg-surface mt-docs_1.5 mb-docs_4",
+        "rounded shadow-elevation-card-rest dark:shadow-elevation-card-rest-dark bg-docs-bg-surface mt-docs_1.5 mb-docs_4",
         className
       )}
     >
diff --git a/www/packages/docs-ui/src/components/LegacyCodeTabs/index.tsx b/www/packages/docs-ui/src/components/LegacyCodeTabs/index.tsx
deleted file mode 100644
index 3b1dcdd0eb..0000000000
--- a/www/packages/docs-ui/src/components/LegacyCodeTabs/index.tsx
+++ /dev/null
@@ -1,172 +0,0 @@
-"use client"
-
-import React, { useCallback, useEffect, useMemo, useRef } from "react"
-import clsx from "clsx"
-import { CodeBlock, CodeBlockProps, CodeBlockStyle } from "@/components"
-import { useTabs, BaseTabType, useScrollPositionBlocker } from "@/hooks"
-import { CodeBlockHeader } from "../CodeBlock/Header"
-import { useColorMode } from "../../providers"
-
-export type LegacyTabType = {
-  code?: CodeBlockProps
-  codeBlock?: React.ReactNode
-} & BaseTabType
-
-export type LegacyCodeTabsProps = {
-  tabs: LegacyTabType[]
-  className?: string
-  group?: string
-  title?: string
-  blockStyle?: CodeBlockStyle
-}
-
-export const LegacyCodeTabs = ({
-  tabs,
-  className,
-  group = "client",
-  title,
-  blockStyle = "loud",
-}: LegacyCodeTabsProps) => {
-  const { colorMode } = useColorMode()
-  const { selectedTab, changeSelectedTab } = useTabs<LegacyTabType>({
-    tabs,
-    group,
-  })
-  const tabRefs: (HTMLButtonElement | null)[] = useMemo(() => [], [])
-  const codeTabSelectorRef = useRef<HTMLSpanElement | null>(null)
-  const codeTabsWrapperRef = useRef<HTMLDivElement | null>(null)
-  const { blockElementScrollPositionUntilNextRender } =
-    useScrollPositionBlocker()
-
-  const changeTabSelectorCoordinates = useCallback(
-    (selectedTabElm: HTMLElement) => {
-      if (!codeTabSelectorRef?.current || !codeTabsWrapperRef?.current) {
-        return
-      }
-      const selectedTabsCoordinates = selectedTabElm.getBoundingClientRect()
-      const tabsWrapperCoordinates =
-        codeTabsWrapperRef.current.getBoundingClientRect()
-      codeTabSelectorRef.current.style.left = `${
-        selectedTabsCoordinates.left - tabsWrapperCoordinates.left
-      }px`
-      codeTabSelectorRef.current.style.width = `${selectedTabsCoordinates.width}px`
-      codeTabSelectorRef.current.style.height = `${selectedTabsCoordinates.height}px`
-    },
-    []
-  )
-
-  useEffect(() => {
-    if (codeTabSelectorRef?.current && tabRefs.length) {
-      const selectedTabElm = tabRefs.find(
-        (tab) => tab?.getAttribute("aria-selected") === "true"
-      )
-      if (selectedTabElm) {
-        changeTabSelectorCoordinates(
-          selectedTabElm.parentElement || selectedTabElm
-        )
-      }
-    }
-  }, [codeTabSelectorRef, tabRefs, changeTabSelectorCoordinates, selectedTab])
-
-  return (
-    <div
-      className={clsx(
-        "relative my-docs_1 w-full max-w-full overflow-auto",
-        className
-      )}
-      ref={codeTabsWrapperRef}
-    >
-      <span
-        className={clsx(
-          "xs:absolute xs:border xs:border-solid",
-          "xs:transition-all xs:duration-200 xs:ease-ease xs:top-[13px] xs:rounded-full",
-          blockStyle === "loud" && [
-            colorMode === "light" &&
-              "xs:border-medusa-code-border xs:bg-medusa-code-bg-base",
-            colorMode === "dark" &&
-              "xs:border-medusa-border-base xs:bg-medusa-bg-component",
-          ],
-          blockStyle === "subtle" && [
-            colorMode === "light" &&
-              "xs:border-medusa-border-base xs:bg-medusa-bg-base",
-            colorMode === "dark" &&
-              "xs:border-medusa-code-border xs:bg-medusa-code-bg-base",
-          ]
-        )}
-        ref={codeTabSelectorRef}
-      ></span>
-      <CodeBlockHeader title={selectedTab?.code?.title || title}>
-        <ul
-          className={clsx(
-            "!list-none flex gap-docs_0.25 items-center",
-            "p-0 mb-0"
-          )}
-        >
-          {tabs.map((tab, index) => (
-            <li key={index}>
-              <button
-                className={clsx(
-                  "text-compact-small-plus xs:border-0 py-docs_0.25 px-docs_0.75 relative rounded-full border",
-                  (!selectedTab || selectedTab.value !== tab.value) && [
-                    "text-medusa-code-text-subtle border-transparent",
-                    blockStyle === "loud" && [
-                      colorMode === "light" &&
-                        "text-medusa-code-text-subtle hover:bg-medusa-code-bg-base",
-                      colorMode === "dark" &&
-                        "text-medusa-fg-muted hover:bg-medusa-bg-component",
-                    ],
-                    blockStyle === "subtle" && [
-                      colorMode === "light" &&
-                        "text-medusa-fg-subtle hover:bg-medusa-bg-base",
-                      colorMode === "dark" &&
-                        "text-medusa-code-text-subtle hover:bg-medusa-code-bg-base",
-                    ],
-                  ],
-                  selectedTab?.value === tab.value && [
-                    "xs:!bg-transparent",
-                    blockStyle === "loud" && [
-                      colorMode === "light" &&
-                        "border-medusa-code-border text-medusa-code-text-base",
-                      colorMode === "dark" &&
-                        "border-medusa-border-base text-medusa-fg-base",
-                    ],
-                    blockStyle === "subtle" && [
-                      colorMode === "light" &&
-                        "xs:border-medusa-border-base text-medusa-code-text-base",
-                      colorMode === "dark" &&
-                        "xs:border-medusa-code-border text-medusa-code-text-base",
-                    ],
-                  ]
-                )}
-                ref={(tabControl) => tabRefs.push(tabControl)}
-                onClick={(e) => {
-                  blockElementScrollPositionUntilNextRender(
-                    e.target as HTMLButtonElement
-                  )
-                  changeSelectedTab(tab)
-                }}
-                aria-selected={selectedTab?.value === tab.value}
-                role="tab"
-              >
-                {tab.label}
-              </button>
-            </li>
-          ))}
-        </ul>
-      </CodeBlockHeader>
-      <>
-        {selectedTab?.code && (
-          <CodeBlock
-            {...selectedTab?.code}
-            title={undefined}
-            className={clsx(
-              "!mt-0 !rounded-t-none",
-              selectedTab.code.className
-            )}
-          />
-        )}
-        {selectedTab?.codeBlock && <>{selectedTab.codeBlock}</>}
-      </>
-    </div>
-  )
-}
diff --git a/www/packages/docs-ui/src/components/Modal/Header/index.tsx b/www/packages/docs-ui/src/components/Modal/Header/index.tsx
index 325b8e27c7..bb224f4453 100644
--- a/www/packages/docs-ui/src/components/Modal/Header/index.tsx
+++ b/www/packages/docs-ui/src/components/Modal/Header/index.tsx
@@ -20,7 +20,7 @@ export const ModalHeader = ({ title }: ModalHeaderProps) => {
     >
       <span className={clsx("text-medusa-fg-base text-h2")}>{title}</span>
       <Button
-        variant="clear"
+        variant="transparent"
         className="cursor-pointer"
         onClick={() => closeModal()}
       >
diff --git a/www/packages/docs-ui/src/components/Modal/index.tsx b/www/packages/docs-ui/src/components/Modal/index.tsx
index fe84fb4af9..46671f14ad 100644
--- a/www/packages/docs-ui/src/components/Modal/index.tsx
+++ b/www/packages/docs-ui/src/components/Modal/index.tsx
@@ -101,7 +101,7 @@ export const Modal = ({
         className={clsx(
           "bg-medusa-bg-base rounded-docs_sm",
           "border-medusa-border-base border border-solid",
-          "shadow-modal dark:shadow-modal-dark",
+          "shadow-elevation-modal dark:shadow-elevation-modal-dark",
           "w-[90%] md:h-auto md:w-[75%] lg:w-[560px]",
           modalContainerClassName
         )}
diff --git a/www/packages/docs-ui/src/components/Navbar/MobileMenu/index.tsx b/www/packages/docs-ui/src/components/Navbar/MobileMenu/index.tsx
index 627ed414fb..5163bd7287 100644
--- a/www/packages/docs-ui/src/components/Navbar/MobileMenu/index.tsx
+++ b/www/packages/docs-ui/src/components/Navbar/MobileMenu/index.tsx
@@ -27,10 +27,7 @@ export const NavbarMobileMenu = ({
             {...menuButton}
             buttonProps={{
               ...(menuButton.buttonProps || {}),
-              className: clsx(
-                menuButton.buttonProps?.className,
-                "!border-none !bg-transparent !bg-no-image !shadow-none"
-              ),
+              variant: "transparent",
             }}
           />
           <NavbarLogo
@@ -42,8 +39,7 @@ export const NavbarMobileMenu = ({
             <NavbarSearchModalOpener />
             <NavbarColorModeToggle
               buttonProps={{
-                className:
-                  "!border-none !bg-transparent !bg-no-image !shadow-none ml-docs_1",
+                variant: "transparent",
               }}
             />
           </div>
diff --git a/www/packages/docs-ui/src/components/Note/Layout/index.tsx b/www/packages/docs-ui/src/components/Note/Layout/index.tsx
index fc0d82ea4c..588bf237f2 100644
--- a/www/packages/docs-ui/src/components/Note/Layout/index.tsx
+++ b/www/packages/docs-ui/src/components/Note/Layout/index.tsx
@@ -23,20 +23,19 @@ export const NoteLayout = ({
   return (
     <div
       className={clsx(
-        "p-docs_1 border border-solid  rounded shadow-none",
-        isDefaultStyle &&
-          "bg-medusa-tag-neutral-bg border-medusa-tag-neutral-border",
+        "p-docs_0.75 border border-solid rounded shadow-none",
+        isDefaultStyle && "bg-medusa-bg-component border-medusa-border-base",
         isWarningStyle && "bg-medusa-tag-red-bg border-medusa-tag-red-border",
         isSoonStyle && "bg-medusa-tag-blue-bg border-medusa-tag-blue-border",
-        "[&_a]:no-underline [&_a]:text-medusa-fg-interactive hover:[&_a]:text-medusa-fg-interactive-hover ",
-        "mb-docs_2 alert"
+        "[&_a]:no-underline [&_a]:text-medusa-fg-interactive hover:[&_a]:text-medusa-fg-interactive-hover",
+        "mb-docs_2"
       )}
     >
-      <div className={clsx("flex")}>
-        <span className={clsx("inline-block h-1.5 w-1.5 mr-1")}>{icon}</span>
+      <div className={clsx("flex gap-docs_0.5")}>
+        {icon}
         <div
           className={clsx(
-            isDefaultStyle && "text-medusa-tag-neutral-text",
+            isDefaultStyle && "text-medusa-fg-subtle",
             isWarningStyle && "text-medusa-tag-red-text",
             isSoonStyle && "text-medusa-tag-blue-text",
             "text-medium flex-1 [&>*:last-child]:mb-0",
diff --git a/www/packages/docs-ui/src/components/Notification/Item/Layout/Default/index.tsx b/www/packages/docs-ui/src/components/Notification/Item/Layout/Default/index.tsx
index f9dad395f9..036e91560a 100644
--- a/www/packages/docs-ui/src/components/Notification/Item/Layout/Default/index.tsx
+++ b/www/packages/docs-ui/src/components/Notification/Item/Layout/Default/index.tsx
@@ -27,7 +27,7 @@ export const NotificationItemLayoutDefault: React.FC<
   closeButtonText = "Close",
 }) => {
   return (
-    <div className="bg-medusa-bg-base w-full h-full shadow-flyout dark:shadow-flyout-dark rounded-docs_DEFAULT">
+    <div className="bg-medusa-bg-base w-full h-full shadow-elevation-flyout dark:shadow-elevation-flyout-dark rounded-docs_DEFAULT">
       <div className={clsx("flex gap-docs_1 p-docs_1")}>
         {type !== "none" && (
           <div
diff --git a/www/packages/docs-ui/src/components/Npm2YarnCode/index.tsx b/www/packages/docs-ui/src/components/Npm2YarnCode/index.tsx
index 10088ceaf4..1592c6f678 100644
--- a/www/packages/docs-ui/src/components/Npm2YarnCode/index.tsx
+++ b/www/packages/docs-ui/src/components/Npm2YarnCode/index.tsx
@@ -1,5 +1,5 @@
 import React from "react"
-import { CodeBlockMetaFields, LegacyCodeTabs } from "../.."
+import { CodeBlock, CodeBlockMetaFields, CodeTab, CodeTabs } from "../.."
 import convert from "npm-to-yarn"
 
 type Npm2YarnCodeProps = {
@@ -14,39 +14,43 @@ export const Npm2YarnCode = ({ npmCode, ...rest }: Npm2YarnCodeProps) => {
 
   const { title = "", ...codeOptions } = rest
 
+  const tabs = [
+    {
+      label: "npm",
+      value: "npm",
+      code: {
+        source: npmCode,
+        lang,
+        ...codeOptions,
+      },
+    },
+    {
+      label: "yarn",
+      value: "yarn",
+      code: {
+        source: yarnCode,
+        lang,
+        ...codeOptions,
+      },
+    },
+    {
+      label: "pnpm",
+      value: "pnpm",
+      code: {
+        source: pnpmCode,
+        lang,
+        ...codeOptions,
+      },
+    },
+  ]
+
   return (
-    <LegacyCodeTabs
-      group="npm2yarn"
-      title={title}
-      tabs={[
-        {
-          label: "npm",
-          value: "npm",
-          code: {
-            source: npmCode,
-            lang,
-            ...codeOptions,
-          },
-        },
-        {
-          label: "yarn",
-          value: "yarn",
-          code: {
-            source: yarnCode,
-            lang,
-            ...codeOptions,
-          },
-        },
-        {
-          label: "pnpm",
-          value: "pnpm",
-          code: {
-            source: pnpmCode,
-            lang,
-            ...codeOptions,
-          },
-        },
-      ]}
-    />
+    <CodeTabs group="npm2yarn" title={title}>
+      {tabs.map((tab, index) => (
+        <CodeTab label={tab.label} value={tab.value} key={index}>
+          <CodeBlock {...tab.code} />
+        </CodeTab>
+      ))}
+    </CodeTabs>
   )
 }
diff --git a/www/packages/docs-ui/src/components/Rating/index.tsx b/www/packages/docs-ui/src/components/Rating/index.tsx
index 4759425a7f..1a07d80c3e 100644
--- a/www/packages/docs-ui/src/components/Rating/index.tsx
+++ b/www/packages/docs-ui/src/components/Rating/index.tsx
@@ -81,7 +81,7 @@ export const Rating: React.FC<RatingProps> = ({
             (hoverRating !== 0 && hoverRating - 1 >= i)
           return (
             <Button
-              variant="clear"
+              variant="transparent"
               buttonRef={(element) => {
                 if (starElms.current.length - 1 < i) {
                   starElms.current.push(element as HTMLElement)
diff --git a/www/packages/docs-ui/src/components/Search/ModalOpener/index.tsx b/www/packages/docs-ui/src/components/Search/ModalOpener/index.tsx
index 32b23cd751..3519dbdfa0 100644
--- a/www/packages/docs-ui/src/components/Search/ModalOpener/index.tsx
+++ b/www/packages/docs-ui/src/components/Search/ModalOpener/index.tsx
@@ -47,7 +47,7 @@ export const SearchModalOpener = ({
   return (
     <>
       {isMobile && (
-        <Button variant="clear" onClick={handleOpen}>
+        <Button variant="transparent" onClick={handleOpen}>
           <MagnifyingGlass className="text-medusa-fg-muted" />
         </Button>
       )}
diff --git a/www/packages/docs-ui/src/components/Search/Suggestions/index.tsx b/www/packages/docs-ui/src/components/Search/Suggestions/index.tsx
index 9c91b9e895..57edec6e3e 100644
--- a/www/packages/docs-ui/src/components/Search/Suggestions/index.tsx
+++ b/www/packages/docs-ui/src/components/Search/Suggestions/index.tsx
@@ -30,13 +30,13 @@ export const SearchSuggestions = ({ suggestions }: SearchSuggestionsProps) => {
               onClick={() => setCommand(command)}
               key={index}
               tabIndex={index}
-              className="gap-docs_0.75"
+              className="justify-between"
             >
-              <>
+              <span className="flex gap-docs_0.75">
                 {command.icon}
                 <span>{command.title}</span>
-                {command.badge && <Badge {...command.badge} />}
-              </>
+              </span>
+              {command.badge && <Badge {...command.badge} />}
             </SearchSuggestionItem>
           ))}
         </>
diff --git a/www/packages/docs-ui/src/components/Search/index.tsx b/www/packages/docs-ui/src/components/Search/index.tsx
index 03505afff6..821e67f308 100644
--- a/www/packages/docs-ui/src/components/Search/index.tsx
+++ b/www/packages/docs-ui/src/components/Search/index.tsx
@@ -122,7 +122,7 @@ export const Search = ({
             formRef={searchBoxRef}
           />
           <Button
-            variant="clear"
+            variant="transparent"
             className={clsx(
               "bg-medusa-bg-base block md:hidden",
               "border-0 border-solid",
diff --git a/www/packages/docs-ui/src/components/Select/Dropdown/index.tsx b/www/packages/docs-ui/src/components/Select/Dropdown/index.tsx
index 7636638b8d..e906ec4b49 100644
--- a/www/packages/docs-ui/src/components/Select/Dropdown/index.tsx
+++ b/www/packages/docs-ui/src/components/Select/Dropdown/index.tsx
@@ -125,7 +125,7 @@ export const SelectDropdown = ({
         className={clsx(
           "p-docs_0.25 mb-0 w-full overflow-auto rounded-docs_DEFAULT",
           "bg-medusa-bg-base text-medusa-fg-base",
-          "shadow-flyout dark:shadow-flyout-dark list-none"
+          "shadow-elevation-flyout dark:shadow-elevation-flyout-dark list-none"
         )}
       >
         {addAll &&
diff --git a/www/packages/docs-ui/src/components/Sidebar/Item/index.tsx b/www/packages/docs-ui/src/components/Sidebar/Item/index.tsx
index 968b33e61c..2276d12ae3 100644
--- a/www/packages/docs-ui/src/components/Sidebar/Item/index.tsx
+++ b/www/packages/docs-ui/src/components/Sidebar/Item/index.tsx
@@ -57,18 +57,15 @@ export const SidebarItem = ({
   const classNames = useMemo(
     () =>
       clsx(
-        "flex items-center justify-between gap-docs_0.5 rounded-docs_sm px-docs_0.5 py-[6px] hover:no-underline",
-        "border",
+        "flex items-center justify-between gap-docs_0.5 rounded-docs_xs px-docs_0.5 py-[6px]",
+        "hover:no-underline hover:bg-medusa-bg-component-hover",
         !canHaveTitleStyling && "text-compact-small-plus text-medusa-fg-subtle",
         canHaveTitleStyling &&
           "text-compact-x-small-plus text-medusa-fg-muted uppercase",
+        !item.path && "cursor-default",
         item.path !== undefined &&
-          active && ["!text-medusa-fg-base bg-medusa-bg-base-pressed"],
-        (item.path === undefined || !active) && "border-transparent",
-        item.path !== undefined && active && " border-medusa-border-base",
-        item.path !== undefined &&
-          !active &&
-          "hover:bg-medusa-bg-base-hover border-transparent"
+          active &&
+          "text-medusa-fg-base bg-medusa-bg-component-hover"
       ),
     [canHaveTitleStyling, active, item.path]
   )
diff --git a/www/packages/docs-ui/src/components/TextArea/index.tsx b/www/packages/docs-ui/src/components/TextArea/index.tsx
index 4599cf54f3..b23ee67926 100644
--- a/www/packages/docs-ui/src/components/TextArea/index.tsx
+++ b/www/packages/docs-ui/src/components/TextArea/index.tsx
@@ -13,7 +13,7 @@ export const TextArea = (props: TextAreaProps) => {
     <textarea
       {...props}
       className={clsx(
-        "bg-medusa-bg-field shadow-button-secondary dark:shadow-button-secondary-dark",
+        "bg-medusa-bg-field shadow-border-base dark:shadow-border-base-dark",
         "border-medusa-border-base rounded-docs_sm border border-solid",
         "pt-docs_0.4 px-docs_0.75 text-medium font-base pb-[9px]",
         "hover:bg-medusa-bg-field-hover",
diff --git a/www/packages/docs-ui/src/components/Tooltip/index.tsx b/www/packages/docs-ui/src/components/Tooltip/index.tsx
index 1d16a9cdc5..fd33bac340 100644
--- a/www/packages/docs-ui/src/components/Tooltip/index.tsx
+++ b/www/packages/docs-ui/src/components/Tooltip/index.tsx
@@ -40,16 +40,16 @@ export const Tooltip = ({
         anchorId={elementId}
         // anchorSelect={elementId ? `#${elementId}` : undefined}
         className={clsx(
-          "!border-medusa-border-base !border !border-solid",
-          "!text-compact-x-small-plus !shadow-tooltip dark:!shadow-tooltip-dark !rounded-docs_DEFAULT",
-          "!py-docs_0.4 !z-[399] hidden !px-docs_1 lg:block",
-          "!bg-medusa-bg-base",
-          "!text-medusa-fg-subtle",
+          "!text-compact-x-small !shadow-elevation-tooltip dark:!shadow-elevation-tooltip-dark !rounded-docs_DEFAULT",
+          "!py-docs_0.25 !z-[399] hidden !px-docs_0.5 lg:block",
+          "!bg-medusa-bg-component",
+          "!text-medusa-fg-base",
           tooltipClassName
         )}
         wrapper="span"
         noArrow={true}
         positionStrategy={"fixed"}
+        opacity={1}
         {...tooltipProps}
       >
         {tooltipChildren}
diff --git a/www/packages/docs-ui/src/components/TypeList/index.tsx b/www/packages/docs-ui/src/components/TypeList/index.tsx
index 2c2e42c07e..9e1bdf9174 100644
--- a/www/packages/docs-ui/src/components/TypeList/index.tsx
+++ b/www/packages/docs-ui/src/components/TypeList/index.tsx
@@ -36,7 +36,7 @@ export const TypeList = ({
   return (
     <div
       className={clsx(
-        "bg-docs-bg-surface shadow-card-rest rounded my-docs_1",
+        "bg-docs-bg-surface shadow-elevation-card-rest rounded my-docs_1",
         className
       )}
       {...props}
diff --git a/www/packages/docs-ui/src/components/index.ts b/www/packages/docs-ui/src/components/index.ts
index c20e2eca97..3bf425408e 100644
--- a/www/packages/docs-ui/src/components/index.ts
+++ b/www/packages/docs-ui/src/components/index.ts
@@ -1,5 +1,4 @@
 export * from "./AiAssistant"
-export * from "./AiAssistant/CommandIcon"
 export * from "./ApiRunner"
 export * from "./Badge"
 export * from "./Bannerv2"
@@ -32,7 +31,6 @@ export * from "./Input/Text"
 export * from "./Kbd"
 export * from "./Label"
 export * from "./LearningPath"
-export * from "./LegacyCodeTabs"
 export * from "./Link"
 export * from "./Loading"
 export * from "./Loading/Dots"
diff --git a/www/packages/tailwind/base.tailwind.config.js b/www/packages/tailwind/base.tailwind.config.js
index 3d3463933e..b557ad96e0 100644
--- a/www/packages/tailwind/base.tailwind.config.js
+++ b/www/packages/tailwind/base.tailwind.config.js
@@ -5,8 +5,6 @@ import presets from "./theme-presets"
 module.exports = {
   presets: [require("@medusajs/ui-preset")],
   darkMode: ["class", `[data-theme="dark"]`], // hooks into docusaurus' dark mode settings
-  // TODO: remove anything that can be replaced by the
-  // UI preset
   theme: {
     extend: {
       colors: {
@@ -23,7 +21,11 @@ module.exports = {
               hover: "var(--docs-bg-base-hover)",
               pressed: "var(--docs-bg-base-pressed)",
             },
-            component: "var(--docs-bg-component)",
+            component: {
+              DEFAULT: "var(--docs-bg-component)",
+              hover: "var(--docs-bg-component-hover)",
+              pressed: "var(--docs-bg-component-pressed)",
+            },
             "switch-off": {
               DEFAULT: "var(--docs-bg-switch-off)",
               hover: "var(--docs-bg-switch-off-hover)",
@@ -38,6 +40,10 @@ module.exports = {
             field: {
               DEFAULT: "var(--docs-bg-field)",
               hover: "var(--docs-bg-field-hover)",
+              component: {
+                DEFAULT: "var(--docs-bg-field-component)",
+                hover: "var(--docs-bg-field-component-hover)",
+              },
             },
           },
           fg: {
@@ -58,7 +64,6 @@ module.exports = {
           border: {
             base: "var(--docs-border-base)",
             strong: "var(--docs-border-strong)",
-            loud: "var(--docs-border-loud)",
             interactive: "var(--docs-border-interactive)",
             error: "var(--docs-border-error)",
             danger: "var(--docs-border-danger)",
@@ -85,7 +90,6 @@ module.exports = {
               hover: "var(--docs-button-transparent-hover)",
               pressed: "var(--docs-button-transparent-pressed)",
             },
-            disabled: "var(--docs-button-disabled)",
           },
           tag: {
             neutral: {
@@ -144,22 +148,35 @@ module.exports = {
             },
           },
           code: {
-            text: {
-              base: "var(--docs-code-text-base)",
-              subtle: "var(--docs-code-text-subtle)",
-              highlight: "var(--docs-code-text-highlight)",
-            },
-            icon: "var(--docs-code-icon)",
             bg: {
               base: {
                 DEFAULT: "var(--docs-code-bg-base)",
-                // Need this one for color-fade
-                transparent: "var(--docs-code-bg-transparent)",
               },
               header: "var(--docs-code-bg-header)",
             },
             border: "var(--docs-code-border)",
           },
+          contrast: {
+            bg: {
+              base: {
+                DEFAULT: "var(--docs-contrast-bg-base)",
+                pressed: "var(--docs-contrast-bg-base-pressed)",
+                hover: "var(--docs-contrast-bg-base-hover)",
+              },
+              subtle: "var(--docs-contrast-bg-subtle)",
+              highlight: "var(--docs-contrast-bg-highlight)",
+              alpha: "var(--docs-contrast-bg-alpha)",
+            },
+            fg: {
+              primary: "var(--docs-contrast-fg-primary)",
+              secondary: "var(--docs-contrast-fg-secondary)",
+            },
+            border: {
+              base: "var(--docs-contrast-border-base)",
+              top: "var(--docs-contrast-border-top)",
+              bot: "var(--docs-contrast-border-bot)",
+            },
+          },
         },
         /* docs defaults */
         docs: {
@@ -170,55 +187,61 @@ module.exports = {
         },
       },
       boxShadow: {
-        "card-rest":
-          "0px 2px 4px 0px rgba(3, 7, 18, 0.04), 0px 1px 2px -1px rgba(3, 7, 18, 0.08), 0px 0px 0px 1px rgba(3, 7, 18, 0.08)",
-        "card-rest-dark":
-          "0px 2px 4px 0px rgba(0, 0, 0, 0.40), 0px 1px 2px -1px rgba(255, 255, 255, 0.16), 0px 0px 0px 1px rgba(255, 255, 255, 0.10)",
-        "card-hover":
-          "0px 2px 8px 0px rgba(3, 7, 18, 0.10), 0px 1px 2px -1px rgba(3, 7, 18, 0.08), 0px 0px 0px 1px rgba(3, 7, 18, 0.08)",
-        "card-hover-dark":
-          "0px 2px 8px 0px rgba(0, 0, 0, 0.40), 0px 1px 2px -1px rgba(255, 255, 255, 0.16), 0px 0px 0px 1px rgba(255, 255, 255, 0.10)",
-        tooltip:
-          "0px 4px 8px 0px rgba(3, 7, 18, 0.08), 0px 0px 0px 1px rgba(3, 7, 18, 0.08)",
-        "tooltip-dark":
-          "0px 4px 8px 0px rgba(0, 0, 0, 0.32), 0px 0px 0px 1px rgba(255, 255, 255, 0.10)",
-        flyout:
-          "0px 8px 16px 0px rgba(3, 7, 18, 0.08), 0px 0px 0px 1px rgba(3, 7, 18, 0.08)",
-        "flyout-dark":
-          "0px 8px 16px 0px rgba(0, 0, 0, 0.32), 0px 0px 0px 1px rgba(255, 255, 255, 0.10)",
-        modal:
-          "0px 2px 24px 0px rgba(3, 7, 18, 0.08), 0px 16px 32px 0px rgba(3, 7, 18, 0.08), 0px 0px 0px 1px rgba(3, 7, 18, 0.08), 0px 0px 0px 2px rgba(229, 231, 235, 0.40) inset, 0px 0px 0px 1px #FFF inset",
-        "modal-dark":
-          "0px 2px 24px 0px rgba(0, 0, 0, 0.32), 0px 16px 32px 0px rgba(0, 0, 0, 0.32), 0px 0px 0px 1px rgba(255, 255, 255, 0.10)",
-        "navbar-dark": "0px 1px 0px 0px #2E2E32",
-        "button-colored":
-          "0px 0.5px 0px 0px rgba(3, 7, 18, 0.16), 0px 0.25px 0px 0px rgba(3, 7, 18, 0.16), 0px 1.75px 0px 0px rgba(255, 255, 255, 0.16) inset",
-        "button-colored-dark":
-          "0px 0.5px 0px 0px rgba(0, 0, 0, 0.60), 0px 0.25px 0px 0px rgba(0, 0, 0, 0.60)",
-        "button-colored-focused":
-          "0px 0px 0px 3px rgba(59, 130, 246, 0.60), 0px 0px 0px 1px #FFF, 0px 0.5px 0px 0px rgba(3, 7, 18, 0.20), 0px 0.25px 0px 0px rgba(3, 7, 18, 0.20), 0px 1.75px 0px 0px rgba(255, 255, 255, 0.16) inset",
-        "button-colored-focused-dark":
-          "0px 0px 0px 3px rgba(96, 165, 250, 0.80), 0px 0px 0px 1px #1B1B1F, 0px 0.5px 0px 0px rgba(0, 0, 0, 0.60), 0px 0.25px 0px 0px rgba(0, 0, 0, 0.60)",
+        "elevation-card-rest":
+          "0px 0px 0px 1px rgba(0, 0, 0, 0.08), 0px 1px 2px -1px rgba(0, 0, 0, 0.08), 0px 2px 4px 0px rgba(0, 0, 0, 0.04)",
+        "elevation-card-rest-dark":
+          "0px -1px 0px 0px rgba(255, 255, 255, 0.04), 0px 0px 0px 1px rgba(255, 255, 255, 0.12), 0px 1px 2px 0px rgba(0, 0, 0, 0.32), 0px 2px 4px 0px rgba(0, 0, 0, 0.32)",
+        "elevation-card-hover":
+          "0px 0px 0px 1px rgba(0, 0, 0, 0.08), 0px 1px 2px -1px rgba(0, 0, 0, 0.08), 0px 2px 8px 0px rgba(0, 0, 0, 0.1)",
+        "elevation-card-hover-dark":
+          "0px -1px 0px 0px rgba(255, 255, 255, 0.04), 0px 0px 0px 1px rgba(255, 255, 255, 0.12), 0px 1px 4px 0px rgba(0, 0, 0, 0.48), 0px 2px 8px 0px rgba(0, 0, 0, 0.48)",
+        "elevation-tooltip":
+          "0px 0px 0px 1px rgba(0, 0, 0, 0.08), 0px 2px 4px 0px rgba(0, 0, 0, 0.08), 0px 4px 8px 0px rgba(0, 0, 0, 0.08)",
+        "elevation-tooltip-dark":
+          "0px -1px 0px 0px rgba(255, 255, 255, 0.04), 0px 0px 0px 1px rgba(255, 255, 255, 0.12), 0px 2px 4px 0px rgba(0, 0, 0, 0.32), 0px 4px 8px 0px rgba(0, 0, 0, 0.32)",
+        "elevation-flyout":
+          "0px 0px 0px 1px rgba(0, 0, 0, 0.08), 0px 4px 8px 0px rgba(0, 0, 0, 0.08), 0px 8px 16px 0px rgba(0, 0, 0, 0.08)",
+        "elevation-flyout-dark":
+          "0px -1px 0px 0px rgba(255, 255, 255, 0.04), 0px 0px 0px 1px rgba(255, 255, 255, 0.12), 0px 4px 8px 0px rgba(0, 0, 0, 0.32), 0px 8px 16px 0px rgba(0, 0, 0, 0.32)",
+        "elevation-modal":
+          "0px 0px 0px 1px rgba(255, 255, 255, 1) inset, 0px 0px 0px 1.5px rgba(228, 228, 231, 0.6) inset, 0px 0px 0px 1px rgba(0, 0, 0, 0.08), 0px 8px 16px 0px rgba(0, 0, 0, 0.08), 0px 16px 32px 0px rgba(0, 0, 0, 0.08)",
+        "elevation-modal-dark":
+          "0px 0px 0px 1px rgba(24, 24, 27, 1) inset, 0px 0px 0px 1.5px rgba(255, 255, 255, 0.06) inset, 0px -1px 0px 0px rgba(255, 255, 255, 0.04), 0px 0px 0px 1px rgba(255, 255, 255, 0.12), 0px 8px 16px 0px rgba(0, 0, 0, 0.32), 0px 16px 32px 0px rgba(0, 0, 0, 0.32)",
         "button-neutral":
-          "0px 0.5px 0px 0px rgba(3, 7, 18, 0.16), 0px 0.25px 0px 0px rgba(3, 7, 18, 0.16)",
+          "0px 1px 2px 0px rgba(0, 0, 0, 0.12), 0px 0px 0px 1px rgba(0, 0, 0, 0.08)",
         "button-neutral-dark":
-          "0px 0.5px 0px 0px rgba(0, 0, 0, 0.60), 0px 0.25px 0px 0px rgba(0, 0, 0, 0.60), 0px 1.5px 0px 0px rgba(255, 255, 255, 0.10) inset",
+          "0px -1px 0px 0px rgba(255, 255, 255, 0.06), 0px 0px 0px 1px rgba(255, 255, 255, 0.08), 0px 0px 0px 1px rgba(39, 39, 42, 1), 0px 0px 1px 1.5px rgba(0, 0, 0, 0.24), 0px 2px 2px 0px rgba(0, 0, 0, 0.24)",
         "button-neutral-focused":
-          "0px 0px 0px 3px rgba(59, 130, 246, 0.60), 0px 0px 0px 1px #FFF, 0px 0.5px 0px 0px rgba(3, 7, 18, 0.16), 0px 0.25px 0px 0px rgba(3, 7, 18, 0.16)",
+          "0px 1px 2px 0px rgba(0, 0, 0, 0.12), 0px 0px 0px 1px rgba(0, 0, 0, 0.08), 0px 0px 0px 2px rgba(255, 255, 255, 1), 0px 0px 0px 4px rgba(59, 130, 246, 0.6)",
         "button-neutral-focused-dark":
-          "0px 0px 0px 3px rgba(96, 165, 250, 0.80), 0px 0px 0px 1px #1B1B1F, 0px 0.5px 0px 0px rgba(0, 0, 0, 0.60), 0px 0.25px 0px 0px rgba(0, 0, 0, 0.60), 0px 1.5px 0px 0px rgba(255, 255, 255, 0.10) inset",
-        "button-secondary":
-          "0px 1px 1px 0px rgba(3, 7, 18, 0.06), 0px -1px 0px 0px rgba(3, 7, 18, 0.08) inset",
-        "button-secondary-dark":
-          "0px 1px 1px 0px rgba(3, 7, 18, 0.06), 0px -1px 0px 0px rgba(3, 7, 18, 0.08) inset", // TODO change
-        "button-secondary-focus":
-          "0px 0px 0px 3px rgba(59, 130, 246, 0.60), 0px 0px 0px 1px #FFF, 0px 1px 1px 0px rgba(3, 7, 18, 0.06), 0px -1px 0px 0px rgba(3, 7, 18, 0.08) inset",
-        "button-secondary-focus-dark":
-          "0px 0px 0px 3px rgba(59, 130, 246, 0.60), 0px 0px 0px 1px #FFF, 0px 1px 1px 0px rgba(3, 7, 18, 0.06), 0px -1px 0px 0px rgba(3, 7, 18, 0.08) inset", // TODO change
-        // TODO remove if not used
+          "0px -1px 0px 0px rgba(255, 255, 255, 0.06), 0px 0px 0px 1px rgba(255, 255, 255, 0.08), 0px 0px 0px 1px rgba(39, 39, 42, 1), 0px 0px 0px 2px rgba(24, 24, 27, 1), 0px 0px 0px 4px rgba(96, 165, 250, 0.8)",
+        "button-danger":
+          "0px 0.75px 0px 0px rgba(255, 255, 255, 0.2) inset, 0px 1px 2px 0px rgba(190, 18, 60, 0.4), 0px 0px 0px 1px rgba(190, 18, 60, 1)",
+        "button-danger-dark":
+          "0px -1px 0px 0px rgba(255, 255, 255, 0.16), 0px 0px 0px 1px rgba(255, 255, 255, 0.12), 0px 0px 0px 1px rgba(159, 18, 57, 1), 0px 0px 1px 1.5px rgba(0, 0, 0, 0.24), 0px 2px 2px 0px rgba(0, 0, 0, 0.24)",
+        "button-danger-focused":
+          "0px 0.75px 0px 0px rgba(255, 255, 255, 0.2) inset, 0px 1px 2px 0px rgba(190, 18, 60, 0.4), 0px 0px 0px 1px rgba(190, 18, 60, 1), 0px 0px 0px 2px rgba(255, 255, 255, 1), 0px 0px 0px 4px rgba(59, 130, 246, 0.6)",
+        "button-danger-focused-dark":
+          "0px -1px 0px 0px rgba(255, 255, 255, 0.16), 0px 0px 0px 1px rgba(255, 255, 255, 0.12), 0px 0px 0px 1px rgba(159, 18, 57, 1), 0px 0px 0px 2px rgba(24, 24, 27, 1), 0px 0px 0px 4px rgba(96, 165, 250, 0.8)",
+        "button-inverted":
+          "0px 0.75px 0px 0px rgba(255, 255, 255, 0.2) inset, 0px 1px 2px 0px rgba(0, 0, 0, 0.4), 0px 0px 0px 1px rgba(24, 24, 27, 1)",
+        "button-inverted-dark":
+          "0px -1px 0px 0px rgba(255, 255, 255, 0.12), 0px 0px 0px 1px rgba(255, 255, 255, 0.1), 0px 0px 0px 1px rgba(82, 82, 91, 1), 0px 0px 1px 1.5px rgba(0, 0, 0, 0.24), 0px 2px 2px 0px rgba(0, 0, 0, 0.24)",
+        "button-inverted-focused":
+          "0px 0.75px 0px 0px rgba(255, 255, 255, 0.2) inset, 0px 1px 2px 0px rgba(0, 0, 0, 0.4), 0px 0px 0px 1px rgba(24, 24, 27, 1), 0px 0px 0px 2px rgba(255, 255, 255, 1), 0px 0px 0px 4px rgba(59, 130, 246, 0.6)",
+        "button-inverted-focused-dark":
+          "0px -1px 0px 0px rgba(255, 255, 255, 0.12), 0px 0px 0px 1px rgba(255, 255, 255, 0.12), 0px 0px 0px 1px rgba(82, 82, 91, 1), 0px 0px 0px 2px rgba(24, 24, 27, 1), 0px 0px 0px 4px rgba(96, 165, 250, 0.8)",
+
+        "elevation-code-block":
+          "0px 0px 0px 1px #18181B inset, 0px 0px 0px 1.5px rgba(255, 255, 255, 0.20) inset",
+        "elevation-code-block-dark":
+          "0px 0px 0px 1px #27272A inset, 0px 0px 0px 1.5px rgba(255, 255, 255, 0.10) inset",
         active: "0px 0px 0px 3px #E1F0FF",
         "active-dark": "0px 0px 0px 3px #2C2250",
-        navbar: "0px 1px 0px 0px #E6E8EB",
+        "border-base":
+          "0px 1px 2px 0px rgba(0, 0, 0, 0.12), 0px 0px 0px 1px rgba(0, 0, 0, 0.08)",
+        "border-base-dark":
+          "0px -1px 0px 0px rgba(255, 255, 255, 0.06), 0px 0px 0px 1px rgba(255, 255, 255, 0.12), 0px 0px 0px 1px #18181B, 0px 0px 1px 1.5px rgba(0, 0, 0, 0.24), 0px 2px 2px 0px rgba(0, 0, 0, 0.24)",
       },
       borderRadius: {
         xxs: "2px",
@@ -232,36 +255,10 @@ module.exports = {
       lineHeight: {
         DEFAULT: "24px",
       },
-      backgroundImage: ({ theme }) => ({
-        "button-neutral":
-          "linear-gradient(180deg, rgba(3, 7, 18, 0.00) 0%, rgba(3, 7, 18, 0.03) 100%)",
-        "button-neutral-dark":
-          "linear-gradient(180deg, rgba(255, 255, 255, 0.06) 0%, rgba(255, 255, 255, 0.00) 100%)",
-        "no-image": "none",
-        "button-inverted":
-          "linear-gradient(180deg, rgba(255, 255, 255, 0.16) 0%, rgba(255, 255, 255, 0.00) 100%)",
-        "button-inverted-dark":
-          "linear-gradient(180deg, rgba(0, 0, 0, 0.00) 0%, rgba(0, 0, 0, 0.12) 100%)",
-        "button-danger":
-          "linear-gradient(180deg, rgba(255, 255, 255, 0.12) 0%, rgba(255, 255, 255, 0.00) 100%)",
-        "button-danger-dark":
-          "linear-gradient(180deg, rgba(255, 255, 255, 0.10) 0%, rgba(255, 255, 255, 0.00) 100%)",
-        "button-danger-hover":
-          "linear-gradient(180deg, rgba(255, 255, 255, 0.16) 0%, rgba(255, 255, 255, 0.00) 100%)",
-        "button-danger-hover-dark":
-          "linear-gradient(180deg, rgba(255, 255, 255, 0.14) 0%, rgba(255, 255, 255, 0.00) 100%)",
-        "button-danger-pressed":
-          "linear-gradient(180deg, rgba(255, 255, 255, 0.00) 0%, rgba(255, 255, 255, 0.16) 100%)",
-        "button-danger-pressed-dark":
-          "linear-gradient(180deg, rgba(255, 255, 255, 0.00) 0%, rgba(255, 255, 255, 0.14) 100%)",
-        "code-fade": `linear-gradient(90deg, ${theme(
-          "colors.medusa.code.bg.base.transparent"
-        )}, ${theme("colors.medusa.code.bg.base.DEFAULT")} 24px)`,
-        fade: "linear-gradient(to top, rgba(255, 255, 255, 1), rgba(255, 255, 255, 0))",
-        "fade-dark":
-          "linear-gradient(to top, rgba(27, 27, 31, 1), rgba(27, 27, 31, 0))",
-        diagrams: "url('/img/diagrams-bg.png')",
-      }),
+      backgroundImage: {
+        "code-fade-top-to-bottom": `linear-gradient(180deg, #27272A 0%, rgba(39, 39, 42, 0.00) 100%)`,
+        "code-fade-bottom-to-top": `linear-gradient(180deg, #27272A 0%, rgba(39, 39, 42, 0.00) 100%)`,
+      },
       screens: {
         xs: "576px",
         lg: "1025px",
@@ -371,7 +368,7 @@ module.exports = {
           },
         ],
         "compact-x-small": [
-          "12px",
+          "13px",
           {
             lineHeight: "20px",
             fontWeight: "400",
@@ -420,21 +417,21 @@ module.exports = {
           },
         ],
         "code-label": [
-          "13px",
+          "12px",
           {
             lineHeight: "20px",
             fontWeight: "400",
           },
         ],
         "code-body": [
-          "13px",
+          "12px",
           {
-            lineHeight: "24px",
+            lineHeight: "22px",
             fontWeight: "400",
           },
         ],
       },
-      keyframes: ({ theme }) => ({
+      keyframes: {
         fadeIn: {
           from: { opacity: 0 },
           to: { opacity: 1 },
@@ -588,7 +585,7 @@ module.exports = {
             backgroundColor: "transparent",
           },
         },
-      }),
+      },
       animation: {
         fadeIn: "fadeIn 500ms",
         fadeOut: "fadeOut 500ms",
@@ -725,7 +722,7 @@ module.exports = {
           },
           ".code-block-highlight-dark": {
             "*::selection": {
-              "background-color": "var(--docs-code-text-highlight)",
+              "background-color": "var(--docs-contrast-bg-highlight)",
             },
           },
           ".code-block-highlight-light": {
@@ -733,6 +730,11 @@ module.exports = {
               "background-color": "var(--docs-bg-highlight)",
             },
           },
+          ".badge": {
+            "&::selection": {
+              "background-color": "var(--docs-bg-highlight)",
+            },
+          },
         })
         addComponents({
           ".btn-secondary-icon": {
diff --git a/www/packages/tailwind/theme-presets.js b/www/packages/tailwind/theme-presets.js
index 712248ae2a..633eb76ffc 100644
--- a/www/packages/tailwind/theme-presets.js
+++ b/www/packages/tailwind/theme-presets.js
@@ -1,189 +1,209 @@
 const light = {
   "--docs-bg-base": "rgba(255, 255, 255, 1)",
-  "--docs-bg-base-hover": "rgba(249, 250, 251, 1)",
-  "--docs-bg-base-pressed": "rgba(243, 244, 246, 1)",
-  "--docs-bg-subtle": "rgba(249, 250, 251, 1)",
-  "--docs-bg-subtle-hover": "rgba(243, 244, 246, 1)",
-  "--docs-bg-subtle-pressed": "rgba(229, 231, 235, 1)",
-  "--docs-bg-component": "rgba(241, 243, 245, 1)",
-  "--docs-bg-switch-off": "rgba(229, 231, 235, 1)",
-  "--docs-bg-switch-off-hover": "rgba(209, 213, 219, 1)",
+  "--docs-bg-base-hover": "rgba(244, 244, 245, 1)",
+  "--docs-bg-base-pressed": "rgba(228, 228, 231, 1)",
+  "--docs-bg-subtle": "rgba(250, 250, 250, 1)",
+  "--docs-bg-subtle-hover": "rgba(244, 244, 245, 1)",
+  "--docs-bg-subtle-pressed": "rgba(228, 228, 231, 1)",
+  "--docs-bg-component": "rgba(250, 250, 250, 1)",
+  "--docs-bg-component-pressed": "rgba(228, 228, 231, 1)",
+  "--docs-bg-component-hover": "rgba(244, 244, 245, 1)",
+  "--docs-bg-switch-off": "rgba(228, 228, 231, 1)",
+  "--docs-bg-switch-off-hover": "rgba(212, 212, 216, 1)",
   "--docs-bg-interactive": "rgba(59, 130, 246, 1)",
-  "--docs-bg-overlay": "rgba(3, 7, 18, 0.4)",
-  "--docs-bg-disabled": "rgba(243, 244, 246, 1)",
+  "--docs-bg-overlay": "rgba(9, 9, 11, 0.4)",
+  "--docs-bg-disabled": "rgba(244, 244, 245, 1)",
   "--docs-bg-highlight": "rgba(239, 246, 255, 1)",
   "--docs-bg-highlight-hover": "rgba(219, 234, 254, 1)",
-  "--docs-bg-field": "rgba(249, 250, 251, 1)",
-  "--docs-bg-field-hover": "rgba(243, 244, 246, 1)",
+  "--docs-bg-field": "rgba(250, 250, 250, 1)",
+  "--docs-bg-field-hover": "rgba(244, 244, 245, 1)",
+  "--docs-bg-field-component": "rgba(255, 255, 255, 1)",
+  "--docs-bg-field-component-hover": "rgba(250, 250, 250, 1)",
 
-  "--docs-fg-base": "rgba(3, 7, 18, 1)",
-  "--docs-fg-subtle": "rgba(75, 85, 99, 1)",
-  "--docs-fg-muted": "rgba(156, 163, 175, 1)",
-  "--docs-fg-disabled": "rgba(209, 213, 219, 1)",
+  "--docs-fg-base": "rgba(9, 9, 11, 1)",
+  "--docs-fg-subtle": "rgba(82, 82, 91, 1)",
+  "--docs-fg-muted": "rgba(161, 161, 170, 1)",
+  "--docs-fg-disabled": "rgba(212, 212, 216, 1)",
   "--docs-fg-on-color": "rgba(255, 255, 255, 1)",
   "--docs-fg-on-inverted": "rgba(255, 255, 255, 1)",
   "--docs-fg-interactive": "rgba(59, 130, 246, 1)",
   "--docs-fg-interactive-hover": "rgba(37, 99, 235, 1)",
   "--docs-fg-error": "rgba(225, 29, 72, 1)",
 
-  "--docs-border-base": "rgba(229, 231, 235, 1)",
-  "--docs-border-strong": "rgba(209, 213, 219, 1)",
-  "--docs-border-loud": "rgba(3, 7, 18, 1)",
+  "--docs-border-base": "rgba(228, 228, 231, 1)",
+  "--docs-border-strong": "rgba(212, 212, 216, 1)",
   "--docs-border-interactive": "rgba(59, 130, 246, 1)",
   "--docs-border-error": "rgba(225, 29, 72, 1)",
   "--docs-border-danger": "rgba(190, 18, 60, 1)",
-  "--docs-border-transparent": "rgba(3, 7, 18, 0)",
+  "--docs-border-transparent": "rgba(255, 255, 255, 0)",
 
-  "--docs-button-inverted": "rgba(3, 7, 18, 1)",
-  "--docs-button-inverted-hover": "rgba(31, 41, 55, 1)",
-  "--docs-button-inverted-pressed": "rgba(55, 65, 81, 1)",
+  "--docs-button-inverted": "rgba(39, 39, 42, 1)",
+  "--docs-button-inverted-hover": "rgba(63, 63, 70, 1)",
+  "--docs-button-inverted-pressed": "rgba(82, 82, 91, 1)",
   "--docs-button-neutral": "rgba(255, 255, 255, 1)",
-  "--docs-button-neutral-hover": "rgba(249, 250, 251, 1)",
-  "--docs-button-neutral-pressed": "rgba(243, 244, 246, 1)",
+  "--docs-button-neutral-hover": "rgba(244, 244, 245, 1)",
+  "--docs-button-neutral-pressed": "rgba(228, 228, 231, 1)",
   "--docs-button-danger": "rgba(225, 29, 72, 1)",
-  "--docs-button-danger-hover": "rgba(225, 29, 72, 1)",
-  "--docs-button-danger-pressed": "rgba(190, 18, 60, 1)",
+  "--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(249, 250, 251, 1)",
-  "--docs-button-transparent-pressed": "rgba(243, 244, 246, 1)",
-  "--docs-button-disabled": "rgba(236, 238, 240, 1)",
+  "--docs-button-transparent-hover": "rgba(244, 244, 245, 1)",
+  "--docs-button-transparent-pressed": "rgba(228, 228, 231, 1)",
 
-  "--docs-tags-neutral-bg": "rgba(243, 244, 246, 1)",
-  "--docs-tags-neutral-bg-hover": "rgba(229, 231, 235, 1)",
-  "--docs-tags-neutral-text": "rgba(75, 85, 99, 1)",
-  "--docs-tags-neutral-icon": "rgba(107, 114, 128, 1)",
-  "--docs-tags-neutral-border": "rgba(229, 231, 235, 1)",
+  "--docs-tags-neutral-bg": "rgba(244, 244, 245, 1)",
+  "--docs-tags-neutral-bg-hover": "rgba(228, 228, 231, 1)",
+  "--docs-tags-neutral-text": "rgba(82, 82, 91, 1)",
+  "--docs-tags-neutral-icon": "rgba(161, 161, 170, 1)",
+  "--docs-tags-neutral-border": "rgba(228, 228, 231, 1)",
   "--docs-tags-purple-bg": "rgba(237, 233, 254, 1)",
   "--docs-tags-purple-bg-hover": "rgba(221, 214, 254, 1)",
-  "--docs-tags-purple-text": "rgba(109, 40, 217, 1)",
-  "--docs-tags-purple-icon": "rgba(124, 58, 237, 1)",
+  "--docs-tags-purple-text": "rgba(91, 33, 182, 1)",
+  "--docs-tags-purple-icon": "rgba(139, 92, 246, 1)",
   "--docs-tags-purple-border": "rgba(221, 214, 254, 1)",
   "--docs-tags-blue-bg": "rgba(219, 234, 254, 1)",
   "--docs-tags-blue-bg-hover": "rgba(191, 219, 254, 1)",
-  "--docs-tags-blue-text": "rgba(29, 78, 216, 1)",
-  "--docs-tags-blue-icon": "rgba(37, 99, 235, 1)",
+  "--docs-tags-blue-text": "rgba(30, 64, 175, 1)",
+  "--docs-tags-blue-icon": "rgba(59, 130, 246, 1)",
   "--docs-tags-blue-border": "rgba(191, 219, 254, 1)",
   "--docs-tags-green-bg": "rgba(209, 250, 229, 1)",
   "--docs-tags-green-bg-hover": "rgba(167, 243, 208, 1)",
-  "--docs-tags-green-text": "rgba(4, 120, 87, 1)",
-  "--docs-tags-green-icon": "rgba(5, 150, 105, 1)",
+  "--docs-tags-green-text": "rgba(6, 95, 70, 1)",
+  "--docs-tags-green-icon": "rgba(16, 185, 129, 1)",
   "--docs-tags-green-border": "rgba(167, 243, 208, 1)",
-  "--docs-tags-orange-bg": "rgba(254, 244, 199, 1)",
+  "--docs-tags-orange-bg": "rgba(255, 237, 213, 1)",
   "--docs-tags-orange-bg-hover": "rgba(253, 230, 138, 1)",
-  "--docs-tags-orange-text": "rgba(180, 83, 9, 1)",
-  "--docs-tags-orange-icon": "rgba(217, 119, 6, 1)",
-  "--docs-tags-orange-border": "rgba(253, 230, 138, 1)",
+  "--docs-tags-orange-text": "rgba(154, 52, 18, 1)",
+  "--docs-tags-orange-icon": "rgba(249, 115, 22, 1)",
+  "--docs-tags-orange-border": "rgba(254, 215, 170, 1)",
   "--docs-tags-red-bg": "rgba(255, 228, 230, 1)",
   "--docs-tags-red-bg-hover": "rgba(254, 205, 211, 1)",
-  "--docs-tags-red-text": "rgba(190, 18, 60, 1)",
-  "--docs-tags-red-icon": "rgba(225, 29, 72, 1)",
+  "--docs-tags-red-text": "rgba(159, 18, 57, 1)",
+  "--docs-tags-red-icon": "rgba(244, 63, 94, 1)",
   "--docs-tags-red-border": "rgba(254, 205, 211, 1)",
 
-  "--docs-code-text-base": "rgba(249, 250, 251, 1)",
-  "--docs-code-text-subtle": "rgba(156, 163, 175, 1)",
-  "--docs-code-text-highlight": "rgba(16, 42, 76, 1)",
-  "--docs-code-icon": "rgba(107, 114, 128, 1)",
-  "--docs-code-bg-base": "rgba(17, 24, 39, 1)",
+  // TODO change code block design to use contrast
+  // we currently need those for the subtle code blocks
+  "--docs-code-bg-base": "rgba(24, 24, 27, 1)",
   "--docs-code-bg-header": "rgba(31, 41, 55, 1)",
-  "--docs-code-bg-transparent": "rgba(17, 24, 39, 0)",
   "--docs-code-border": "rgba(55, 65, 81, 1)",
 
   "--docs-bg": "var(--docs-bg-base)",
   "--docs-bg-surface": "var(--docs-bg-subtle)",
+
+  "--docs-contrast-bg-base": "rgba(24, 24, 27, 1)",
+  "--docs-contrast-bg-base-pressed": "rgba(63, 63, 70, 1)",
+  "--docs-contrast-bg-base-hover": "rgba(39, 39, 42, 1)",
+  "--docs-contrast-bg-subtle": "rgba(39, 39, 42, 1)",
+  "--docs-contrast-bg-highlight": "rgba(63, 63, 70, 1)",
+  "--docs-contrast-bg-alpha": "rgba(9, 9, 11, 0.8)",
+  "--docs-contrast-fg-primary": "rgba(255, 255, 255, 0.88)",
+  "--docs-contrast-fg-secondary": "rgba(255, 255, 255, 0.56)",
+  "--docs-contrast-border-base": "rgba(255, 255, 255, 0.15)",
+  "--docs-contrast-border-top": "rgba(9, 9, 11, 1)",
+  "--docs-contrast-border-bot": "rgba(255, 255, 255, 0.1)",
 }
 
 const dark = {
-  "--docs-bg-base": "rgba(27, 27, 31, 1)",
-  "--docs-bg-base-hover": "rgba(39, 40, 45, 1)",
-  "--docs-bg-base-pressed": "rgba(46, 48, 53, 1)",
-  "--docs-bg-subtle": "rgba(24, 24, 26, 1)",
-  "--docs-bg-subtle-hover": "rgba(27, 27, 31, 1)",
-  "--docs-bg-subtle-pressed": "rgba(39, 40, 45, 1)",
-  "--docs-bg-component": "rgba(39, 40, 45, 1)",
-  "--docs-bg-switch-off": "rgba(53, 55, 60, 1)",
-  "--docs-bg-switch-off-hover": "rgba(70, 75, 80, 1)",
+  "--docs-bg-base": "rgba(24, 24, 27, 1)",
+  "--docs-bg-base-hover": "rgba(39, 39, 42, 1)",
+  "--docs-bg-base-pressed": "rgba(63, 63, 70, 1)",
+  "--docs-bg-subtle": "rgba(9, 9, 11, 1)",
+  "--docs-bg-subtle-hover": "rgba(24, 24, 27, 1)",
+  "--docs-bg-subtle-pressed": "rgba(63, 63, 70, 1)",
+  "--docs-bg-component": "rgba(39, 39, 42, 1)",
+  "--docs-bg-component-pressed": "rgba(255, 255, 255, 0.16)",
+  "--docs-bg-component-hover": "rgba(255, 255, 255, 0.1)",
+  "--docs-bg-switch-off": "rgba(63, 63, 70, 1)",
+  "--docs-bg-switch-off-hover": "rgba(82, 82, 91, 1)",
   "--docs-bg-interactive": "rgba(96, 165, 250, 1)",
-  "--docs-bg-overlay": "rgba(24, 24, 26, 0.7)",
-  "--docs-bg-disabled": "rgba(39, 40, 45, 1)",
+  "--docs-bg-overlay": "rgba(9, 9, 11, 0.72)",
+  "--docs-bg-disabled": "rgba(39, 39, 42, 1)",
   "--docs-bg-highlight": "rgba(23, 37, 84, 1)",
   "--docs-bg-highlight-hover": "rgba(30, 58, 138, 1)",
-  "--docs-bg-field": "rgba(39, 40, 45, 1)",
-  "--docs-bg-field-hover": "rgba(46, 48, 53, 1)",
+  "--docs-bg-field": "rgba(255, 255, 255, 0.04)",
+  "--docs-bg-field-hover": "rgba(255, 255, 255, 0.08)",
 
-  "--docs-fg-base": "rgba(237, 238, 240, 1)",
-  "--docs-fg-subtle": "rgba(173, 177, 184, 1)",
-  "--docs-fg-muted": "rgba(105, 110, 119, 1)",
-  "--docs-fg-disabled": "rgba(60, 63, 68, 1)",
+  "--docs-fg-base": "rgba(244, 244, 245, 1)",
+  "--docs-fg-subtle": "rgba(161, 161, 170, 1)",
+  "--docs-fg-muted": "rgba(161, 161, 170, 1)",
+  "--docs-fg-disabled": "rgba(82, 82, 91, 1)",
   "--docs-fg-on-color": "rgba(255, 255, 255, 1)",
-  "--docs-fg-on-inverted": "rgba(24, 24, 26, 1)",
+  "--docs-fg-on-inverted": "rgba(9, 9, 11, 1)",
   "--docs-fg-interactive": "rgba(96, 165, 250, 1)",
-  "--docs-fg-interactive-hover": "rgba(59, 130, 246, 1)",
+  "--docs-fg-interactive-hover": "rgba(147, 197, 253, 1)",
   "--docs-fg-error": "rgba(251, 113, 133, 1)",
 
-  "--docs-border-base": "rgba(46, 48, 53, 1)",
-  "--docs-border-strong": "rgba(53, 55, 60, 1)",
-  "--docs-border-loud": "rgba(237, 238, 240, 1)",
+  "--docs-border-base": "rgba(255, 255, 255, 0.08)",
+  "--docs-border-strong": "rgba(255, 255, 255, 0.16)",
   "--docs-border-interactive": "rgba(96, 165, 250, 1)",
-  "--docs-border-error": "rgba(244, 63, 94, 1)",
+  "--docs-border-error": "rgba(251, 113, 133, 1)",
   "--docs-border-danger": "rgba(190, 18, 60, 1)",
   "--docs-border-transparent": "rgba(255, 255, 255, 0)",
 
-  "--docs-button-inverted": "rgba(237, 238, 240, 1)",
-  "--docs-button-inverted-hover": "rgba(255, 255, 255, 1)",
-  "--docs-button-inverted-pressed": "rgba(237, 238, 240, 1)",
-  "--docs-button-neutral": "rgba(39, 40, 45, 1)",
-  "--docs-button-neutral-hover": "rgba(53, 55, 60, 1)",
-  "--docs-button-neutral-pressed": "rgba(60, 63, 68, 1)",
+  "--docs-button-inverted": "rgba(82, 82, 91, 1)",
+  "--docs-button-inverted-hover": "rgba(113, 113, 122, 1)",
+  "--docs-button-inverted-pressed": "rgba(161, 161, 170, 1)",
+  "--docs-button-neutral": "rgba(39, 39, 42, 1)",
+  "--docs-button-neutral-hover": "rgba(63, 63, 70, 1)",
+  "--docs-button-neutral-pressed": "rgba(82, 82, 91, 1)",
   "--docs-button-danger": "rgba(159, 18, 57, 1)",
   "--docs-button-danger-hover": "rgba(190, 18, 60, 1)",
   "--docs-button-danger-pressed": "rgba(225, 29, 72, 1)",
   "--docs-button-transparent": "rgba(255, 255, 255, 0)",
-  "--docs-button-transparent-hover": "rgba(39, 40, 45, 1)",
-  "--docs-button-transparent-pressed": "rgba(46, 48, 53, 1)",
-  "--docs-button-disabled": "rgba(40, 40, 44, 1)",
+  "--docs-button-transparent-hover": "rgba(39, 39, 42, 1)",
+  "--docs-button-transparent-pressed": "rgba(63, 63, 70, 1)",
 
-  "--docs-tags-neutral-bg": "rgba(46, 48, 53, 1)",
-  "--docs-tags-neutral-bg-hover": "rgba(53, 55, 60, 1)",
-  "--docs-tags-neutral-text": "rgba(173, 177, 184, 1)",
-  "--docs-tags-neutral-icon": "rgba(125, 130, 138, 1)",
-  "--docs-tags-neutral-border": "rgba(60, 63, 68, 1)",
-  "--docs-tags-purple-bg": "rgba(46, 16, 100, 1)",
+  "--docs-tags-neutral-bg": "rgba(255, 255, 255, 0.08)",
+  "--docs-tags-neutral-bg-hover": "rgba(63, 63, 70, 1)",
+  "--docs-tags-neutral-text": "rgba(212, 212, 216, 1)",
+  "--docs-tags-neutral-icon": "rgba(113, 113, 122, 1)",
+  "--docs-tags-neutral-border": "rgba(63, 63, 70, 1)",
+  "--docs-tags-purple-bg": "rgba(46, 16, 101, 1)",
   "--docs-tags-purple-bg-hover": "rgba(76, 29, 149, 1)",
-  "--docs-tags-purple-text": "rgba(167, 139, 250, 1)",
-  "--docs-tags-purple-icon": "rgba(139, 92, 246, 1)",
-  "--docs-tags-purple-border": "rgba(76, 29, 149, 1)",
+  "--docs-tags-purple-text": "rgba(196, 181, 253, 1)",
+  "--docs-tags-purple-icon": "rgba(167, 139, 250, 1)",
+  "--docs-tags-purple-border": "rgba(91, 33, 182, 1)",
   "--docs-tags-blue-bg": "rgba(23, 37, 84, 1)",
   "--docs-tags-blue-bg-hover": "rgba(30, 42, 138, 1)",
-  "--docs-tags-blue-text": "rgba(96, 165, 250, 1)",
-  "--docs-tags-blue-icon": "rgba(59, 130, 246, 1)",
+  "--docs-tags-blue-text": "rgba(147, 197, 253, 1)",
+  "--docs-tags-blue-icon": "rgba(96, 165, 250, 1)",
   "--docs-tags-blue-border": "rgba(30, 58, 138, 1)",
   "--docs-tags-green-bg": "rgba(2, 44, 34, 1)",
   "--docs-tags-green-bg-hover": "rgba(6, 78, 59, 1)",
   "--docs-tags-green-text": "rgba(52, 211, 153, 1)",
   "--docs-tags-green-icon": "rgba(16, 185, 129, 1)",
   "--docs-tags-green-border": "rgba(6, 78, 59, 1)",
-  "--docs-tags-orange-bg": "rgba(69, 26, 3, 1)",
+  "--docs-tags-orange-bg": "rgba(67, 20, 7, 1)",
   "--docs-tags-orange-bg-hover": "rgba(120, 53, 15, 1)",
-  "--docs-tags-orange-text": "rgba(251, 191, 36, 1)",
-  "--docs-tags-orange-icon": "rgba(245, 158, 11, 1)",
-  "--docs-tags-orange-border": "rgba(120, 53, 15, 1)",
+  "--docs-tags-orange-text": "rgba(253, 186, 116, 1)",
+  "--docs-tags-orange-icon": "rgba(251, 146, 60, 1)",
+  "--docs-tags-orange-border": "rgba(124, 45, 18, 1)",
   "--docs-tags-red-bg": "rgba(76, 5, 25, 1)",
   "--docs-tags-red-bg-hover": "rgba(136, 19, 55, 1)",
-  "--docs-tags-red-text": "rgba(251, 113, 133, 1)",
-  "--docs-tags-red-icon": "rgba(244, 63, 94, 1)",
+  "--docs-tags-red-text": "rgba(253, 164, 175, 1)",
+  "--docs-tags-red-icon": "rgba(251, 113, 133, 1)",
   "--docs-tags-red-border": "rgba(136, 19, 55, 1)",
 
-  "--docs-code-text-base": "rgba(237, 238, 240, 1)",
-  "--docs-code-text-subtle": "rgba(105, 110, 119, 1)",
-  "--docs-code-text-highlight": "rgba(16, 42, 76, 1)",
-  "--docs-code-icon": "rgba(70, 75, 80, 1)",
-  "--docs-code-bg-base": "rgba(27, 27, 31, 1)",
+  // TODO change code block design to use contrast
+  // we currently need those for the subtle code blocks
+  "--docs-code-bg-base": "rgba(9, 9, 11, 1)",
   "--docs-code-bg-header": "rgba(24, 24, 26, 1)",
-  "--docs-code-bg-transparent": "rgba(27, 27, 31, 0)",
   "--docs-code-border": "rgba(46, 48, 53, 1)",
 
   "--docs-bg": "var(--docs-bg-subtle)",
   "--docs-bg-surface": "var(--docs-bg-base)",
+
+  "--docs-contrast-bg-base": "rgba(39, 39, 42, 1)",
+  "--docs-contrast-bg-base-pressed": "rgba(113, 113, 122, 1)",
+  "--docs-contrast-bg-base-hover": "rgba(82, 82, 91, 1)",
+  "--docs-contrast-bg-subtle": "rgba(255, 255, 255, 0.04)",
+  "--docs-contrast-bg-highlight": "rgba(82, 82, 91, 1)",
+  "--docs-contrast-bg-alpha": "rgba(63, 63, 70, 0.9)",
+  "--docs-contrast-fg-primary": "rgba(250, 250, 250, 1)",
+  "--docs-contrast-fg-secondary": "rgba(255, 255, 255, 0.56)",
+  "--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)",
 }
 
 module.exports = {