docs: documentation changes for release (#4300)

* docs: added manage reservations user guide (#4290)

* docs: added manage reservations user guide

* removed feature flag details

* docs: added how-to for custom reservations (#4292)

* docs: added how-to for custom reservations

* eslint fixes

* docs: added product module documentation (#4287)

* docs: added product module documentation

* added details about optional environment variables

* small fixes

* Remove reference link

* added example usages

* added link to sample project

* address PR feedback

* docs: moved product module guide + added product module tabs (#4307)

* added product module tab

* adjust design of badge

* docs: added onboarding features (#4168)

* added marketplace page

* added subscription roadmap

* added rating for onboarding

* added learning path components

* small fixes

* fix build error

* fix eslint errors

* change roadmaps to recipes

* small change in text

* optimize learning path and notifications

* fix tracking usage

* fix eslint errors

* added enter/exit animation

* allow starting a path using a query parameter

* fix gap between notifications

* address vercel comments

* fixed links issue

* changed create-medusa-app docs steps

* move troubleshooting section

* improved tracking across docs

* fix build errors

* remove console

* added a note about `boilerplate` option

* added troubleshooting section for eagain

* added invite option in cli reference

* added track event for finished onboarding

* update boilerplate option name

* redesigned learning path component

* docs: added how to create widget docs (#4318)

* docs: added how to create widget docs

* remove development guide

* added types

* docs: added details about createCustomAdminHooks (#4288)

* docs: added details about createCustomAdminHooks

* small improvement

* added missing import

* small changes

* docs: added onboarding guide (#4320)

* docs: added how to create widget docs

* remove development guide

* docs: added onboarding guide

* added types

* added recipes link

* small adjustments

* fixed eslint errors

* styling fixes

* change to singular product module

* updated the what's new section

* shorten down medusa react card

* updated tailwind configurations

* fix build error

* fix newspaper icon

* style fixes

* change modal shadow

* fix color of line numbers

* fix code fade color

* docs: updated admin documentations

* eslint fixes

* text changes

* added a note about beta version

* remove empty object argument

* remove demo repo url

* fix selection color for code headers

* general fixes

* fix eslint error

* changed code theme

* added preparation step

* changes regarding beta version

* Update docs/content/modules/products/serverless-module.md

Co-authored-by: Riqwan Thamir <rmthamir@gmail.com>

* Update docs/content/modules/products/serverless-module.md

Co-authored-by: Riqwan Thamir <rmthamir@gmail.com>

---------

Co-authored-by: Riqwan Thamir <rmthamir@gmail.com>
Co-authored-by: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com>

docs/content/admin/development.md

@@ -1,111 +0,0 @@
----
-description: 'Learn how to set up the Medusa Admin repository for local development and customization. This includes cloning the GitHub repository and adding an upstream repository.'
-addHowToData: true
----
-
-# Customize Medusa Admin
-
-In this document, you’ll learn how to customize the Medusa admin by forking it, and how to keep it updated with changes from the main repository.
-
-:::warning
-
-This guide explains how to customize the Medusa Admin repository, which is now deprecated. This guide doesn't work with the [admin plugin](./quickstart.mdx).
-
-:::
-
-## Overview
-
-Although Medusa provides an intuitive admin that should cover all your ecommerce needs, you are free to customize the Medusa admin as you see fit.
-
-For customization and development, it’s recommended that you fork the main Medusa admin repository. That way, you can configure your forked repository to pull changes from the main Medusa admin repository for any latest updates.
-
-In this document, you’ll learn how to:
-
-- Fork the Medusa admin repository.
-- Configure the Medusa admin repository as an upstream repository.
-- Pull changes from the upstream repository to keep your fork synced with the Medusa admin repository.
-
----
-
-## Prerequisites
-
-### Required Tools
-
-[Git CLI tool](../development/backend/prepare-environment.mdx#git)
-
-### Required Accounts
-
-[GitHub](https://github.com/)
-
----
-
-## Fork the Medusa Admin Repository
-
-To fork the Medusa admin:
-
-1. Go to the [Medusa admin repository](https://github.com/medusajs/admin).
-2. Click on the Fork button at the top right.
-3. You can optionally change the name of the repository and description.
-4. Once done, click on the Create fork button.
-5. After your fork is created, you can clone it using the following command:
-
-```bash
-git clone <REPOSITORY_URL>
-```
-
-Where `<REPOSITORY_URL>` is the HTTPS URL of your repository. You can obtain it from your forked repository’s GitHub page by clicking on the Code button and copying the URL.
-
----
-
-## Configure Upstream Repository
-
-To configure the Medusa admin as the upstream repository:
-
-1. Change to the directory of your cloned forked repository. 
-2. Run the following command to add the Medusa admin repository as an upstream repository:
-
-```bash
-git remote add upstream https://github.com/medusajs/admin
-```
-
-1. You can verify that it has been added by running the following command:
-
-```bash
-git remote -v
-```
-
-You should see an `origin` repository which is your forked repository, and an `upstream` repository which is the Medusa admin repository.
-
----
-
-## Update your Fork with Latest Changes
-
-To update your fork with the latest changes from the Medusa admin repository:
-
-1. Change to the directory of your cloned forked repository.
-2. Run the following command to fetch the latest changes from the Medusa admin repository:
-
-```bash
-git fetch upstream
-```
-
-1. Make sure you’re on your `main` or `master` branch of the forked repository:
-
-```bash
-git checkout main
-```
-
-1. Merge the changes from the `main` branch of the Medusa admin repository:
-
-```bash
-git merge upstream/main
-```
-
-If your forked repository doesn’t have any conflicts with the changes from the Medusa admin repository, the merge will be done successfully. Otherwise, you’ll need to [resolve these conflicts](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-using-the-command-line).
-
----
-
-## See Also
-
-- [Admin API reference](/api/admin).
-- [Local development with Medusa](../development/fundamentals/local-development.md).

docs/content/admin/quickstart.mdx

@@ -6,30 +6,18 @@ addHowToData: true
 import Feedback from '@site/src/components/Feedback';
 import Troubleshooting from '@site/src/components/Troubleshooting'
 import AdminLoginSection from '../troubleshooting/signing-in-to-admin.md'
+import CorsSection from '../troubleshooting/cors-issues.md'
 
 # Admin Dashboard Quickstart
 
 This document will guide you through setting up the admin dashboard in the Medusa backend.
 
-:::note
-
-The admin dashboard is now shipped as an NPM package, and the previous GitHub repository has been deprecated.
-
-:::
-
 ## Overview
 
 The admin dashboard is installed on the Medusa backend. The admin dashboard starts when you start the Medusa backend. This also means you can later deploy the Medusa backend along with the admin dashboard on the same hosting.
 
 This guide will explain the steps and configurations required to set up the admin dashboard.
 
-<!-- The admin dashboard is installed on the Medusa backend. Setting it up depends on how you intend to use it:
-
-1. [Served alongside the Medusa backend](#option-1-install-and-serve-admin-with-the-backend): with this approach, the admin dashboard starts when you start the Medusa backend. This also means you can later deploy the Medusa backend along with the admin dashboard on the same hosting.
-2. [Served separately from the Medusa backend](#option-2-install-and-serve-admin-separately): with this approach, the admin dashboard starts separately from the Medusa backend. You still need the Medusa backend to be running as the admin uses its APIs. This is useful if you intend to later deploy the admin dashboard on a different hosting than the Medusa Backend, such as using Vercel.
-
-This guide will explain the steps and configurations required for both approaches. -->
-
 ---
 
 ## Prerequisites
@@ -52,20 +40,10 @@ You can install Node from the [official website](https://nodejs.org/en/).
 
 ---
 
-<!-- ## Option 1: Install and Serve Admin with the Backend -->
-
 ## Install and Serve Admin with the Backend
 
 This section explains how to install the admin to be served with the Medusa Backend and later deployed together.
 
-<!-- :::note
-
-If you decide later to serve the admin for development separately or deploy it on a different hosting, you can go back and follow the steps in [Option 2](#option-2-install-and-serve-admin-serparately).
-
-:::
-
--->
-
 ### Step 1: Install the Package
 
 In the directory of your Medusa backend, run the following command to install admin dashboard:
@@ -74,6 +52,16 @@ In the directory of your Medusa backend, run the following command to install ad
 npm install @medusajs/admin
 ```
 
+:::note
+
+Installing the `@beta` version of the admin and Medusa core allows you to perform customizations such as creating [Admin Widgets](./widgets.md) or [Admin Dashboard Routes](./routes.md). You can install the `beta` version with the following command:
+
+```bash npm2yarn
+npm install @medusajs/admin@beta @medusajs/medusa@beta
+```
+
+:::
+
 ### Step 2: Add Admin to Medusa Configurations
 
 In `medusa-config.js`, add the admin plugin into the array of `plugins`:
@@ -94,7 +82,7 @@ const plugins = [
 The plugin accepts the following options:
 
 1. `serve`: (default: `true`) a boolean indicating whether to serve the admin dashboard when the Medusa backend starts. If set to `false`, you can serve the admin dashboard using the [dev command](#dev-command-options).
-2. `path`: (default: `app`) a string indicating the path the admin server should run on. It shouldn't be prefixed or suffixed with a slash `/`, and it can't be one of the reserved paths: "admin" and "store".
+2. `path`: (default: `app`) a string indicating the path the admin server should run on when [running the Medusa backend in production](#note-on-admin-path). It shouldn't be prefixed or suffixed with a slash `/`, and it can't be one of the reserved paths: "admin" and "store".
 3. `outDir`: Optional path for where to output the admin build files.
 4. `autoRebuild`: (default: `false`) a boolean indicating whether the admin UI should be rebuilt if there are any changes or if a missing build is detected when the backend starts. If not set, you must [manually build the admin dashboard](#build-command-options).
 
@@ -116,66 +104,14 @@ You can test the admin dashboard by running the following command in the directo
 npx @medusajs/medusa-cli develop
 ```
 
-This starts the Medusa Backend and the admin dashboard. By default, the admin will be available on the URL `localhost:9000/app`. If you set the `path` option, then the admin will be available on `localhost:9000/<PATH>` with `<PATH>` being the value of the `path` option.
+This starts the Medusa Backend and the admin dashboard. By default, the admin will be available on the URL `localhost:9000/app`. If you set the path option, then the admin will be available on `localhost:9000/<PATH>` with `<PATH>` being the value of the path option.
-
-<Feedback 
-   event="survey_admin_quickstart"
-   question="Did you set up the admin successfully?"
-   positiveQuestion="Is there anything that should improved?"
-   negativeQuestion="Please describe the issue you faced."
-/>
-
----
-
-<!-- 
-
-## Option 2: Install and Serve Admin Separately
-
-This section explains how to install the admin dashboard using approach 2, which allows you to serve and later deploy the admin separately.
 
 :::note
 
-If you decide later to serve and deploy the admin alongside the server, you can go back and follow the steps in [Option 1](#option-1-install-and-serve-admin-with-the-backend).
+If you're using the `@beta` version of the admin plugin, the admin dashboard will run on `localhost:7001` when you run the `develop` command.
 
 :::
 
-### Step 1: Install the Package
-
-In the directory of your Medusa backend, run the following command to install admin dashboard:
-
-```bash npm2yarn
-npm install @medusajs/admin --save-dev
-```
-
-### Step 2: Add Scripts to Package.json
-
-Add the following scripts to `package.json` in the directory of the Medusa backend:
-
-```json title=package.json
-{
-  "scripts": {
-    // other scripts...
-    "build:admin": "medusa-admin build",
-    "dev:admin": "medusa-admin dev"
-  }
-}
-```
-
-Where:
-
-- `build:admin`: Used to manually create a build of the admin. In this approach, it's useful with the `--deployment` option to build the admin for deployment. You can learn more about all available options in [this section](#build-command-options).
-- `dev:admin`: Used to run the development server of the admin. You can learn about other available options for this command in [this section](#dev-command-options).
-
-### Step 3: Start Admin in Development
-
-Make sure to run the Medusa backend first. Then, in the root directory of the backend, run the following command to start the admin development server:
-
-```bash npm2yarn
-npm run dev:admin
-```
-
-This runs the admin dashboard on `localhost:7001`.
-
 <Feedback 
    event="survey_admin_quickstart"
    question="Did you set up the admin successfully?"
@@ -185,8 +121,6 @@ This runs the admin dashboard on `localhost:7001`.
 
 ---
 
--->
-
 ## Demo Credentials
 
 If you installed the demo data when you installed the Medusa backend by running:
@@ -276,5 +210,16 @@ You can learn more about the admin dashboard and its features in the [User Guide
       title: 'Signing into Admin',
       content: <AdminLoginSection />
     },
+    {
+      title: 'CORS Errors',
+      content: <CorsSection />
+    }
   ]}
 />
+
+---
+
+## See Also
+
+- [Admin widgets](./widgets.md)
+- [Admin UI routes](./routes.md)

docs/content/admin/routes.md

@@ -0,0 +1,326 @@
+---
+title: 'How to Create an Admin UI Route'
+description: 'Learn how to create a new route in the admin dashboard.'
+addHowToData: true
+badge:
+  variant: orange
+  text: beta
+---
+
+In this document, you’ll learn how to create a new route in the admin dashboard.
+
+## Overview
+
+You can customize the admin dashboard that Medusa provides to add new routes. This is useful if you want to add new subpages to the admin dashboard, or you want to add new pages that appear in the sidebar as well.
+
+An admin UI route is essentially a React Component created under the `src/admin/routes` directory.
+
+This guide explains how to create a new route in the admin dashboard with some examples.
+
+---
+
+## Prerequisites
+
+It’s assumed you already have a Medusa backend with the admin plugin installed before you move forward with this guide. If not, you can follow [this documentation page](../create-medusa-app.mdx) to install a Medusa project.
+
+Furthermore, Admin UI Routes are currently available as a beta feature. So, you must install the `beta` version of the `@medusajs/admin` and `@medusajs/medusa` packages:
+
+```bash npm2yarn
+npm install @medusajs/admin@beta @medusajs/medusa@beta
+```
+
+### (Optional) TypeScript Preparations
+
+Since routes are React components, they should be written in `.tsx` or `.jsx` files. If you’re using Typescript, you need to make some adjustments to avoid Typescript errors in your Admin files.
+
+This section provides recommended configurations to avoid any TypeScript errors.
+
+:::note
+
+These changes may already be available in your Medusa project. They're included here for reference purposes.
+
+:::
+
+First, update your `tsconfig.json` with the following configurations:
+
+```json title=tsconfig.json
+{
+  "compilerOptions": {
+    "target": "es2019",
+    "module": "commonjs",
+    "allowJs": true, 
+    "checkJs": false, 
+    "jsx": "react-jsx", 
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "noEmit": false,
+    "strict": false,
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/"],
+  "exclude": [
+    "dist",
+    "build",
+    ".cache",
+    "tests",
+    "**/*.spec.js",
+    "**/*.spec.ts",
+    "node_modules",
+    ".eslintrc.js"
+  ]
+}
+```
+
+The important changes to note here are the inclusion of the field `"jsx": "react-jsx"` and the addition of `"build"` and `“.cache”` to `exclude`.
+
+The addition of `"jsx": "react-jsx"` specified how should TypeScript transform JSX, and excluding `build` and `.cache` ensures that TypeScript ignores build and development files.
+
+Next, create the file `tsconfig.server.json` with the following content:
+
+```json title=tsconfig.server.json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    /* Emit a single file with source maps instead of having a separate file. */
+    "inlineSourceMap": true
+  },
+  "exclude": ["src/admin", "**/*.spec.js"]
+}
+```
+
+This is the configuration that will be used to transpile your custom backend code, such as services or entities. The important part is that it excludes `src/admin` as that is where your Admin code will live.
+
+Finally, create the file `tsconfig.admin.json` with the following content:
+
+```json title=tsconfig.admin.json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "esnext"
+  },
+  "include": ["src/admin"],
+  "exclude": ["**/*.spec.js"]
+}
+```
+
+This is the configuration that will be used when transpiling your admin code.
+
+---
+
+## Create the Admin UI Route
+
+In this section, you’ll learn the basics of creating an admin UI route.
+
+### Step 1: Create File
+
+Custom admin UI routes are added under the `src/admin/routes` directory of your Medusa project. The path of the file depends on the path you want the route to be available under. It is based on [Next.js 13’s App Router](https://nextjs.org/docs/app/building-your-application/routing/defining-routes).
+
+For example, if you want the route to be available in the admin dashboard under the path `/a/custom` you should create your admin route under the path `src/admin/routes/custom/page.tsx`.
+
+:::tip
+
+All admin routes are prefixed with `/a` by default.
+
+:::
+
+You can also create [dynamic routes](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes). For example, you can create the route `/a/custom/[id]` by creating an admin router under the path `src/admin/routes/custom/[id]/page.tsx`.
+
+### Step 2: Create React Component in File
+
+For an admin route to be valid, it must default export a React component. There are no restrictions on the content of the React component.
+
+For example, you can create the file `src/admin/routes/custom/page.tsx` with the following content:
+
+```tsx title=src/admin/routes/custom/page.tsx
+const CustomPage = () => {
+  return (
+    <div>
+      This is my custom route
+    </div>
+  )
+}
+
+export default CustomPage
+```
+
+### Step 3: Test it Out
+
+To test your admin UI route, run the following command in the root directory of the Medusa backend project:
+
+```bash npm2yarn
+npx @medusajs/medusa-cli develop
+```
+
+This will build your admin and opens a window in your default browser to `localhost:7001`. After you log in, if you go to `localhost:7001/a/custom`, you’ll find the page you just created.
+
+:::note
+
+When using the `develop` command, the admin dashboard will run in development mode and will restart whenever you make changes to your admin customizations. This allows you to see changes in the dashboard instantly during your development.
+
+:::
+
+---
+
+## Show Route in Sidebar
+
+You can add your routes into the admin dashboard sidebar by exporting an object of type `RouteConfig` import from `@medusajs/admin` in the same route file.
+
+The object has one property `link`, which is an object having the following properties:
+
+- `label`: a string indicating the sidebar item’s label of your custom route.
+- `icon`: an optional React component that acts as an icon in the sidebar. If none provided, a default icon is used.
+
+For example, you can change the content of the previous route you created to export a config object:
+
+```tsx title=src/admin/routes/custom/page.tsx
+import { RouteConfig } from "@medusajs/admin"
+import { CustomIcon } from "../../icons/custom"
+
+const CustomPage = () => {
+  return (
+    <div>
+      This is my custom route
+    </div>
+  )
+}
+
+export const config: RouteConfig = {
+  link: {
+    label: "Custom Route",
+    icon: CustomIcon,
+  },
+}
+
+export default CustomPage
+```
+
+---
+
+## Retrieve Path Parameters
+
+As mentioned earlier, you can create dynamic routes like `/a/custom/[id]` by creating a route file at the path `src/admin/routes/custom/[id]/page.tsx`.
+
+To retrieve the path parameter, you can use the [useParams hook](https://reactrouter.com/en/main/hooks/use-params) retrieved from the [react-router-dom](https://reactrouter.com/en/main) package.
+
+:::note
+
+`react-router-dom` is available as one of the `@medusajs/admin` dependencies. You can also install it within your project using the following command:
+
+```bash npm2yarn
+npm install react-router-dom
+```
+
+If you're installing it in a plugin with admin customizations, make sure to include it in `peerDependencies`.
+
+:::
+
+For example:
+
+```tsx title=src/admin/routes/custom/[id]/page.tsx
+import { useParams } from "react-router-dom"
+
+const CustomPage = () => {
+  const { id } = useParams()
+
+  return (
+    <div>
+      Passed ID: {id}
+    </div>
+  )
+}
+
+export default CustomPage
+```
+
+### Routing Functionalities
+
+If you want to use routing functionalities such as linking to another page or navigating between pages, you can use `react-router-dom`'s utility hooks and functions.
+
+For example, to add a link to another page:
+
+```tsx title=src/admin/routes/custom/page.tsx
+import { Link } from "react-router-dom"
+
+const CustomPage = () => {
+
+  return (
+    <div>
+      <Link to={"/a/products"}>
+        View Products
+      </Link>
+    </div>
+  )
+}
+
+export default CustomPage
+```
+
+View [react-router-dom’s documentation](https://reactrouter.com/en/main) for other available components and hooks.
+
+---
+
+## Styling Route
+
+Admin UI routes support [Tailwind CSS](https://tailwindcss.com/) by default.
+
+For example, to customize your custom route:
+
+<!-- eslint-disable max-len -->
+
+```tsx title=src/admin/routes/custom/page.tsx
+const CustomPage = () => {
+  return (
+    <div 
+      className="bg-white p-8 border border-gray-200 rounded-lg">
+      This is my custom route
+    </div>
+  )
+}
+
+export default CustomPage
+```
+
+---
+
+## Querying and Mutating Data
+
+You might need to interact with the Medusa backend from your admin route. To do so, you can utilize the [Medusa React package](../medusa-react/overview.md). It contains a collection of queries and mutation built on `@tanstack/react-query` that lets you interact with the Medusa backend.
+
+:::note
+
+Make sure to also install the Medusa React package first if you’re intending to use it, as explained in the [Medusa React guide](../medusa-react/overview.md).
+
+:::
+
+For example, you can retrieve available products and display them in your route:
+
+```tsx title=src/admin/routes/custom/page.tsx
+import { useAdminProducts } from "medusa-react"
+
+const CustomPage = () => {
+  const { products } = useAdminProducts()
+  return (
+    <div className="bg-white">
+      {products?.map((product) => product.title)}
+    </div>
+  )
+}
+
+export default CustomPage
+```
+
+You can also use `medusa-react` to interact with custom endpoints using the [createCustomAdminHooks utility function](../medusa-react/overview.md#custom-hooks).
+
+---
+
+## See Also
+
+- [Admin widgets](./widgets.md)
+- [Create a plugin for your admin customizations](../development/plugins/create.mdx)

docs/content/cli/reference.mdx

@@ -204,9 +204,10 @@ medusa user --email <email> [--password <password>]
 
 | Name | Description |
 | --- | --- |
-| `-e`, `--email` | The email to create a user with. (required) |
+| `-e <email>`, `--email <email>` | The email to create a user with. (required) |
-| `-p`, `--password` | The password to use with the user. If not included, the user will not have a password. |
+| `-p <passowrd>`, `--password <password>` | The password to use with the user. If not included, the user will not have a password. |
-| `-i`, `--id` | The user’s ID. By default it is automatically generated. |
+| `-i <id>`, `--id <id>` | The user’s ID. By default it is automatically generated. |
+| `--invite` | Whether to create an invite instead of a user. When using this option, you don't need to specify a password. If ran successfully, you'll receive the invite token in the output. |
 
 ### telemetry
 

docs/content/create-medusa-app.mdx

@@ -6,7 +6,7 @@ addHowToData: true
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import Feedback from '@site/src/components/Feedback';
-import DocCardList from '@theme/DocCardList';
+import DocCard from '@theme/DocCard';
 import Icons from '@theme/Icon';
 import Troubleshooting from '@site/src/components/Troubleshooting'
 import TypeErrorSection from "./troubleshooting/create-medusa-app-errors/_typeerror.md"
@@ -17,13 +17,22 @@ import FreshInstallationSection from './troubleshooting/awilix-resolution-error/
 
 # Install Medusa with create-medusa-app
 
-In this document, you’ll learn how to use create-medusa-app to set up a Medusa backend.
+In this document, you’ll learn how to use create-medusa-app to set up a Medusa backend and an admin dashboard.
 
 ## Overview
 
 Medusa is a toolkit for developers to create digital commerce applications. In its simplest form, Medusa is a Node.js backend with the core API, plugins, and modules installed through npm.
 
-`create-medusa-app` is a command that facilitates creating a Medusa ecosystem. It installs the Medusa backend, along with the necessary configurations to run the backend.
+`create-medusa-app` is a command that facilitates creating a Medusa ecosystem. It installs the Medusa backend and admin dashboard, along with the necessary configurations to run the backend.
+
+:::note
+
+`create-medusa-app` uses a beta version of the admin dashboard. If you want to use a stable Medusa setup, you can install the stable backend and the admin using the following guides:
+
+1. [Install Medusa backend](./development/backend/install.mdx)
+2. [Install admin package](./admin/quickstart.mdx)
+
+:::
 
 ---
 
@@ -75,7 +84,8 @@ In your terminal, run the following command:
   <summary>Available Options</summary>
 
   - `--repo-url <url>`: The repository URL to create the project from. By default it will be `https://github.com/medusajs/medusa-starter-default`.
-  - `--no-boilerplate`: A flag that removes all files added for an enhanced onboarding experience (files under `src/api`, etc...). This is helpful if you want to create a clean project, and is only recommended if you're familiar with Medusa.
+  - `--seed`: A flag indicating whether the database should be seeded with demo data. By default, seeding is disabled.
+  - `--no-boilerplate`: A flag that removes all files added for an enhanced onboarding experience (files under `src/admin`, `src/api`, etc...). This is helpful if you want to create a clean project, and is only recommended if you're familiar with Medusa.
 
 </details>
 
@@ -89,7 +99,11 @@ By default, this command will try to use the default PostgreSQL credentials to c
 
 These credentials will be used to create a database during this setup and configure your Medusa backend to connect to that database.
 
-### Step 3: Wait for Project Setup
+### Step 3: Enter an admin email
+
+You'll then be prompted to enter an admin email for your admin user. You'll be using this admin email later to login to your admin dashboard. You can use the default `admin@medusa-test.com` or enter any other email.
+
+### Step 4: Wait for Project Setup
 
 After the above steps, the project setup will start which includes:
 
@@ -97,17 +111,14 @@ After the above steps, the project setup will start which includes:
 2. Creating the project database.
 3. Installing dependencies in your project directory.
 4. Building project and running migrations to migrate the Medusa schema into your project database.
-5. Seed the database
+5. Create the admin user.
+6. Seeding the database with demo data.
 
-### Step 4: Test it Out
+### Step 5: Log into admin dashboard
 
-Once the installation is finished, the Medusa backend will be started automatically. You can test it out by either opening the URL `localhost:9000/store/products` in your browser or using cURL:
+Once the project is prepared, the Medusa backend will start and the admin dashboard will be opened in your default browser. You'll then be asked to enter a password for the admin email you entered earlier, as well as other account information.
 
-```bash
+Once you're logged in, you can start using Medusa! Try following the setup guide to create your first product and order.
-cURL localhost:9000/store/products
-```
-
-This endpoint returns an array of available products in your Medusa backend.
 
 <Feedback 
    event="survey_create-medusa-app"
@@ -122,26 +133,15 @@ This endpoint returns an array of available products in your Medusa backend.
 
 Based on what you're building, you can find a development path for you in the Recipes page.
 
-<DocCardList colSize={6} items={[
+<DocCard item={{
-  {
   type: 'link',
-    href: '/modules/overview',
+  href: '/recipes',
-    label: 'Commerce Modules',
+  label: 'Recipes',
   customProps: {
-      icon: Icons['puzzle-solid'],
+    icon: Icons['map'],
-      description: "Learn about available commerce modules and features in Medusa."
+    description: "Find learning paths based on what you're building"
   }
-  },
+}} />
-  {
-    type: 'link',
-    href: '/development/overview',
-    label: 'Medusa Development',
-    customProps: {
-      icon: Icons['server-stack-solid'],
-      description: "Learn how to develop customized digital commerce applications with Medusa."
-    }
-  }
-]} />
 
 ---
 

docs/content/deployments/storefront/deploying-gatsby-on-netlify.md

@@ -1,334 +0,0 @@
----
-description: 'Learn step-by-step.'
-addHowToData: true
----
-
-# Deploy Gatsby Storefront on Netlify
-
-:::note
-
-The Gatsby storefront has been deprecated and it's not recommended to use it moving forward. You can use the [Next.js storefront](../../starters/nextjs-medusa-starter.mdx) instead or build your own.
-
-:::
-
-In this document, you’ll learn how to deploy the Gatsby Storefront on [Netlify](https://www.netlify.com/).
-
-Alternatively, you can use this button to deploy the Gatsby Storefront to Netlify directly:
-
-<a href="https://app.netlify.com/start/deploy?repository=https://github.com/medusajs/gatsby-starter-medusa" class="img-url no-zoom-img">
-  <img src="https://www.netlify.com/img/deploy/button.svg" alt="Deploy to Netlify" class="no-zoom-img" />
-</a>
-
----
-
-## Prerequisites
-
-### Medusa Components
-
-Before proceeding with this documentation, it is assumed you already have the Gatsby storefront installed locally.
-
-Additionally, this documentation does not cover how to deploy the Medusa backend. If you want to deploy the Medusa backend, [check out one of the deployment documentation related to the Medusa backend](../server/index.mdx).
-
-### Needed Accounts
-
-- A [Netlify](https://app.netlify.com/signup) account to deploy the Gatsby storefront.
-- A [GitHub](https://github.com/signup) account where you will host the repository for the Gatsby storefront.
-
-:::tip
-
-If you want to use another Git Provider, it’s possible to follow along with this guide but you’ll have to perform the equivalent steps in your Git Provider.
-
-:::
-
-### Required Tools
-
-- Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](../../development/backend/prepare-environment.mdx#git).
-
----
-
-## Create GitHub Repository
-
-Before you can deploy your Gatsby storefront you need to create a GitHub repository and push the code base to it.
-
-On GitHub, click the plus icon at the top right, then click New Repository.
-
-![Create Repository](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001782/Medusa%20Docs/Netlify/0YlxBRi_aiywpo.png)
-
-You’ll then be redirected to a new page with a form. In the form, enter the Repository Name then scroll down and click Create repository.
-
-![Repository Form](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001800/Medusa%20Docs/Netlify/YPYXAF2_lypjne.png)
-
-### Push Code to GitHub Repository
-
-The next step is to push the code to the GitHub repository you just created.
-
-After creating the repository, you’ll be redirected to the repository’s page. On that page, you should see a URL that you can copy to connect your repository to a local directory.
-
-![GitHub Repository URL](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001818/Medusa%20Docs/Netlify/pHfSTuT_w544lr.png)
-
-Copy the link. Then, open your terminal in the directory that holds your Gatsby storefront codebase and run the following commands:
-
-```bash
-git init
-git remote add origin <GITHUB_URL>
-```
-
-Where `<GITHUB_URL>` is the URL you just copied.
-
-Then, add, commit, and push the changes into the repository:
-
-```bash
-git add .
-git commit -m "initial commit"
-git push origin master
-```
-
-After pushing the changes, you can find the files in your GitHub repository.
-
----
-
-## Deploy to Netlify
-
-This section covers how to deploy Netlify either through the Netlify website or using Netlify’s CLI tool.
-
-### Option 1: Using Netlify’s Website
-
-After logging in with Netlify, go to the [dashboard](https://app.netlify.com/). Then, at the top right of the “Sites” section, click on “Add new site”, then click on “Import an existing project” from the dropdown.
-
-:::note
-
-Alternatively, if you don’t have any other websites, you’ll see a big button that says “Import an existing project”.
-
-:::
-
-![Create a new website](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001840/Medusa%20Docs/Netlify/IUUOzoW_mw9u5w.png)
-
-You’ll then be asked to connect to a Git provider.
-
-![Connect Git Provider](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001855/Medusa%20Docs/Netlify/T6lZPDi_rvcuyf.png)
-
-Choose GitHub. You’ll then be redirected to GitHub’s website to give Netlify permissions if you haven’t done that before.
-
-After you authorize Netlify to use GitHub, you’ll be asked to pick the repository you want to deploy. Pick the repository you just created.
-
-![Choose Repository](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003038/Medusa%20Docs/Netlify/SRI3r1Y_hqwy8r.png)
-
-In the form that shows, keep all fields the same and click on the “Show advanced” button before the “Deploy site” button.
-
-![Show advanced Button](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001884/Medusa%20Docs/Netlify/nUdwRbq_d2kmo6.png)
-
-Under the “Advanced build settings” section click on the “New variable” button. This will show two inputs for the key and value of the environment variable.
-
-For the first field enter the key `GATSBY_MEDUSA_BACKEND_URL` and for the value enter the URL of your Medusa backend.
-
-:::caution
-
-If you haven’t deployed your Medusa backend yet, you can leave the value blank for now and add it later. However, the build process for the Gatsby storefront will fail.
-
-:::
-
-![Environment Variable](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001898/Medusa%20Docs/Netlify/DnutZfT_rv8iel.png)
-
-:::note
-
-If you use more environment variables in your storefront be sure to add them here.
-
-:::
-
-Once you’re done, scroll down and click on Deploy site.
-
-You’ll be then redirected to the dashboard of the new website. Netlify will build your website in the background. You should see “Site deploy in progress” on the top card.
-
-![Site Deployment Progress](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003051/Medusa%20Docs/Netlify/PUDjjnL_hwuywi.png)
-
-The deployment can take a few minutes.
-
-Once the deployment is done, you’ll find the URL in the place of the “Site deploy in progress” message you saw earlier.
-
-:::tip
-
-If you haven’t added any products to your Medusa backend, the build process might fail. It’s recommended to add some products to the backend first in that case.
-
-Alternatively, you can seed the backend with demo data by running this command in the root directory of the backend:
-
-```bash noReport
-npx @medusajs/medusa-cli seed -f data/seed.json
-```
-
-:::
-
-![Deployment Complete](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003068/Medusa%20Docs/Netlify/dPF9HvF_ibnoo1.png)
-
-If you click on it, you’ll be redirected to the deployed storefront website.
-
-![Gatsby Storefront](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003076/Medusa%20Docs/Netlify/l08cBSA_eanbne.png)
-
-:::caution
-
-At this point, you will face errors related to Cross-Origin Resource Sharing (CORS) while using the storefront. Before you start using the storefront, follow along the [Configure CORS on the Medusa Backend section](#configure-cors-variable-on-the-medusa-backend).
-
-:::
-
-### Option 2: Using Netlify’s CLI Tool
-
-In this section, you’ll deploy the Gatsby storefront using Netlify’s CLI tool.
-
-#### Install the Netlify CLI tool
-
-If you don’t have the tool installed, run the following command to install it:
-
-```bash
-npm install netlify-cli -g
-```
-
-#### Login to Netlify
-
-Then, run the following command to log in to Netlify in your terminal:
-
-```bash
-netlify login
-```
-
-This opens a page to log in on your browser. You’ll be asked to authorize the Netlify CLI tool.
-
-![Authorize Application](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001985/Medusa%20Docs/Netlify/JDUdqSE_dzveww.png)
-
-Click on Authorize. Then, you can go back to your terminal and see that you’ve successfully logged in.
-
-![Authorized Message](https://res.cloudinary.com/dza7lstvk/image/upload/v1668001998/Medusa%20Docs/Netlify/L13Yqhp_e2ejpx.png)
-
-#### Initialize Netlify Website
-
-In your terminal, run the following command:
-
-```bash
-netlify init
-```
-
-You’ll have to follow five steps for the initialization:
-
-##### Step 1: Create Netlify Website
-
-You’ll be asked to either connect to an existing Netlify website or create a new one. Choose the second option to create a new site:
-
-```bash noReport
-? What would you like to do? 
-  ⇄  Connect this directory to an existing Netlify site 
-❯ +  Create & configure a new site
-```
-
-##### Step 2: Choose Netlify Team
-
-Choose the team you want to create the website in if you have multiple teams.
-
-##### Step 3: Enter Site Name
-
-You’ll be asked to optionally enter a site name.
-
-##### Step 4: Configure Webhooks and Deployment Keys
-
-At this point, the website is created on Netlify. However, Netlify needs to configure Webhooks and deployment keys. You’ll be asked to either authorize GitHub through Netlify’s website or through a personal access token. You’re free to choose either:
-
-```bash noReport
-? Netlify CLI needs access to your GitHub account to configure Webhooks and Depl
-oy Keys. What would you like to do? (Use arrow keys)
-❯ Authorize with GitHub through app.netlify.com 
-  Authorize with a GitHub personal access token
-```
-
-If you pick the first option, a page in your browser will open where you have to grant authorization to your Git provider.
-
-If you pick the second option, you’ll need to create a personal access token on GitHub. You can follow [this guide in GitHub’s documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) to learn how to do it.
-
-##### Last Step: Steps with Default Values
-
-For the rest of the steps, you can keep the default values provided by Netlify and press the “Enter” key on your keyboard for each.
-
-#### Set Environment Variables
-
-After the previous command has finished running, your Netlify website will be created. The next step is to add an environment variable that points to your Medusa backend.
-
-:::caution
-
-If you haven’t deployed your Medusa backend yet, you can leave the value blank for now and add it later. However, the build process for the Gatsby storefront will fail.
-
-:::
-
-Run the following command to add the environment variable:
-
-```bash
-netlify env:set GATSBY_MEDUSA_BACKEND_URL "<YOUR_BACKKEND_URL>"
-```
-
-Where `<YOUR_BACKKEND_URL>` is the URL of your Medusa backend.
-
-:::note
-
-If you use more environment variables in your storefront be sure to add them here.
-
-:::
-
-#### Check deployment status
-
-You can check the deployment status of your website by running the following command:
-
-```bash
-netlify watch
-```
-
-After the deployment has been completed, you should see a message saying “Deploy complete” with URLs to your website.
-
-:::tip
-
-If you haven’t added any products to your Medusa backend, the build process might fail. It’s recommended to add some products to the backend first in that case.
-
-Alternatively, you can seed the backend with demo data by running this command in the root directory of the backend:
-
-```bash noReport
-npx @medusajs/medusa-cli seed -f data/seed.json
-```
-
-:::
-
-#### Open the Gatsby storefront Website
-
-To open the Gatsby storefront website, either use the URL shown to you or run the following command:
-
-```bash
-netlify open:site
-```
-
-The Gatsby storefront will then open in your browser.
-
-![Gatsby Storefront](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003089/Medusa%20Docs/Netlify/l08cBSA_yfj2rz.png)
-
-Before you can use the Gatsby storefront, you must add the URL as an environment variable on your deployed Medusa backend.
-
----
-
-## Configure CORS Variable on the Medusa Backend
-
-To send requests to the Medusa backend from the Gatsby storefront, you must set the `STORE_CORS` environment variable on your backend to the Gatsby storefront’s URL.
-
-:::caution
-
-If you want to set a custom domain to your Gatsby storefront website on Netlify, make sure to do it before this step. You can refer to this guide on [Netlify’s documentation to learn how to add a custom domain](https://docs.netlify.com/domains-https/custom-domains/#assign-a-domain-to-a-site).
-
-:::
-
-On your Medusa backend, add the following environment variable:
-
-```bash
-STORE_CORS=<STOREFRONT_URL>
-```
-
-Where `<STOREFRONT_URL>` is the URL of your Gatsby storefront that you just deployed.
-
-Then, restart your Medusa backend. Once the backend is running again, you can use your Gatsby storefront.
-
----
-
-## See Also
-
-- [Deploy the Medusa Admin](../admin/index.mdx)
-- [Configure your Medusa backend](../../development/backend/configurations.md)

docs/content/development/file-service/create-file-service.md

@@ -431,4 +431,4 @@ export default () => {
 ## See Also
 
 - [How to create a plugin](../plugins/create.mdx)
-- [How to publish a plugin](../plugins/publish.md)
+- [How to publish a plugin](../plugins/publish.mdx)

docs/content/development/plugins/create.mdx

@@ -124,11 +124,123 @@ The `watch` command outputs the files in the destination specified in the value
 
 :::
 
+### Changes for Admin Plugins
+
+:::note
+
+Admin customizations are currently in beta and require you to use the `beta` version of `@medusajs/admin` and `@medusajs/medusa`. You can install it with the following command:
+
+```bash npm2yarn
+npm install @medusajs/admin@beta @medusajs/medusa@beta
+```
+
+:::
+
+If your plugin contains customizations to the admin dashboard, it's recommended to create different `tsconfig` files for backend and admin customizations, then modify the scripts in `package.json` to handle building backend and admin customizations separately.
+
+:::note
+
+These changes may already be available in your Medusa project. They're included here for reference purposes.
+
+:::
+
+Start by updating your `tsconfig.json` with the following configurations:
+
+```json title=tsconfig.json
+{
+  "compilerOptions": {
+    "target": "es2019",
+    "module": "commonjs",
+    "allowJs": true, 
+    "checkJs": false, 
+    "jsx": "react-jsx", 
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "noEmit": false,
+    "strict": false,
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/"],
+  "exclude": [
+    "dist",
+    "build",
+    ".cache",
+    "tests",
+    "**/*.spec.js",
+    "**/*.spec.ts",
+    "node_modules",
+    ".eslintrc.js"
+  ]
+}
+```
+
+The important changes to note here are the inclusion of the field `"jsx": "react-jsx"` and the addition of `"build"` and `“.cache”` to `exclude`.
+
+The addition of `"jsx": "react-jsx"` specified how should TypeScript transform JSX, and excluding `build` and `.cache` ensures that TypeScript ignores build and development files.
+
+Next, create the file `tsconfig.server.json` with the following content:
+
+```json title=tsconfig.server.json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    /* Emit a single file with source maps instead of having a separate file. */
+    "inlineSourceMap": true
+  },
+  "exclude": ["src/admin", "**/*.spec.js"]
+}
+```
+
+This is the configuration that will be used to transpile your custom backend code, such as services or entities. The important part is that it excludes `src/admin` as that is where your Admin code will live.
+
+Then, create the file `tsconfig.admin.json` with the following content:
+
+```json title=tsconfig.admin.json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "esnext"
+  },
+  "include": ["src/admin"],
+  "exclude": ["**/*.spec.js"]
+}
+```
+
+This is the configuration that will be used when transpiling your admin code.
+
+Finally, update the `build` script in your project:
+
+```json title=package.json
+"scripts": {
+  // other scripts...
+  "build": "tsc -p ./tsconfig.server.json && medusa-admin bundle"
+}
+```
+
+This `build` script builds the backend customizations, then bundles the admin plugin using `medusa-admin bundle`.
+
+Furthermore, make sure to add `react` to `peerDependencies` along with `react-router-dom` if you're using it:
+
+```json title=package.json
+"peerDependencies": {
+  // other dependencies...
+  "react": "^18.2.0",
+  "react-router-dom": "^6.13.0"
+}
+```
+
 ---
 
 ## Develop your Plugin
 
-Now, You can start developing your plugin. This can include adding services, endpoints, entities, or anything that's relevant to your plugin.
+Now, You can start developing your plugin. This can include adding services, endpoints, entities, admin customizations, or anything that's relevant to your plugin.
 
 ### Plugin Structure
 
@@ -185,6 +297,32 @@ This guide doesn't cover how to create different files and components. If you’
       description: 'Learn how to create a subscriber.'
     }
   },
+  {
+    type: 'link',
+    href: '/admin/widgets',
+    label: 'Create an Admin Widget',
+    customProps: {
+      icon: Icons['academic-cap-solid'],
+      description: 'Learn how to create an admin widget.',
+      badge: {
+        variant: 'orange',
+        children: 'Beta'
+      }
+    }
+  },
+  {
+    type: 'link',
+    href: '/admin/routes',
+    label: 'Create an Admin UI Route',
+    customProps: {
+      icon: Icons['academic-cap-solid'],
+      description: 'Learn how to create an admin UI route.',
+      badge: {
+        variant: 'orange',
+        children: 'Beta'
+      }
+    }
+  },
 ]} />
 
 If you're developing something specific, such as a payment processor plugin, you can follow one of the following guides to learn how to create different services within your plugin.
@@ -299,6 +437,49 @@ Make sure to include in the README of your plugin the configurations that can be
 
 :::
 
+### enableUI Plugin Option
+
+All plugins accept an option named `enableUI`. This option is useful mainly if your plugin contains admin customizations. It allows users to enable or disable admin customizations in the admin dashboard.
+
+You can pass the `enableUI` option to plugins as follows:
+
+```js title=medusa-config.js
+const plugins = [
+  // ...
+  {
+    resolve: `medusa-plugin-custom`,
+    options: {
+      // other options
+      enableUI: true,
+    },
+  },
+]
+```
+
+If you're passing your plugin options to third-party services, make sure to omit it from the plugin options you receive in your resources, such as services. The `enableUI` option will always be passed as part of your plugin options.
+
+For example:
+
+```js title=src/service/test.ts
+  // In a service in your plugin
+class MyService extends TransactionBaseService {
+  constructor(container, options) {
+    super(container)
+    // options contains plugin configurations
+    const { enableUI, ...otherOptions } = options
+    // pass otherOptions to a third-party service
+    const client = new Client(otherOptions)
+  }
+  // ...
+}
+```
+
+:::note
+
+Since admin customizations are still in `beta` mode, `enableUI`'s default value is `false` if not provided by the plugin users. This means that it must be enabled manually in a plugin's configuration for the customizations to appear in the admin dashboard. Once the admin customizations are out of beta, this behavior will be reversed.
+
+:::
+
 ---
 
 ## Test Your Plugin
@@ -413,4 +594,4 @@ It is safe to ignore any `cross-env: command not found` error you may receive.
 
 Once you're done with the development of the plugin, you can publish it to NPM so that other Medusa developers and users can use it.
 
-Please refer to [this guide on required steps to publish a plugin](./publish.md).
+Please refer to [this guide on required steps to publish a plugin](./publish.mdx).

docs/content/development/plugins/overview.mdx

@@ -21,6 +21,8 @@ An alternative approach is developing a custom way of handling payment on your e
 
 Plugins run within the same process as the core Medusa backend eliminating the need for extra backend capacity, infrastructure, and maintenance. As a result, plugins can use all other services as dependencies and access the database.
 
+Plugins can contain customizations to the Medusa backend or the admin dashboard.
+
 ---
 
 ## Using Existing Plugins
@@ -41,6 +43,8 @@ You can find community plugins by [searching NPM for the `medusa` or `medusa-plu
 
 You can also check the [Awesome Medusa repository](https://github.com/adrien2p/awesome-medusajs#plugins) for a list of community plugins among other resources.
 
+---
+
 ## How to Install a Plugin
 
 To install an existing plugin, in your Medusa backend run the following command:
@@ -57,6 +61,31 @@ If you’re installing an official plugin from the Medusa repository, you can fi
 
 For community plugins, please refer to the installation instructions of that plugin to learn about any required configurations.
 
+### enableUI Plugin Option
+
+All plugins accept an option named `enableUI`. This option allows you to disable admin customizations from appearing in the admin dashboard.
+
+:::note
+
+Since admin customizations are still in `beta` mode, `enableUI`'s default value is `false` if not provided by the plugin users. This means that it must be enabled manually in a plugin's configuration for the customizations to appear in the admin dashboard. Once the admin customizations are out of beta, this behavior will be reversed.
+
+:::
+
+You can set the `enableUI` value by passing it as part of the plugin's configurations:
+
+```js title=medusa-config.js
+const plugins = [
+  // ...
+  {
+    resolve: `medusa-plugin-custom`,
+    options: {
+      // other options
+      enableUI: true,
+    },
+  },
+]
+```
+
 ---
 
 ## Custom Development

docs/content/development/plugins/publish.mdx

@@ -3,6 +3,9 @@ description: 'Learn how to publish a Medusa plugin to NPM. This guide lists some
 addHowToData: true
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 # How to Publish a Plugin
 
 In this document, you'll learn how to publish a Medusa plugin to NPM and what are some requirements to keep in mind before publishing. Afterwards, your plugin will be published on the [Medusa Plugins page](https://medusajs.com/plugins/).
@@ -35,26 +38,63 @@ Before publishing your plugin, make sure you've set the following fields in your
   - `medusa-plugin-storage`: For plugins that add a file service or storage integration.
   - `medusa-plugin-source`: For plugins that help migrate or import data into Medusa from another platform.
   - `medusa-plugin-storefront`: For storefronts that can be integrated with a Medusa backend.
+  - `medusa-plugin-admin`: For plugins that include only admin customizations.
   - `medusa-plugin-other`: For any other type of plugin.
 
 ### Scripts in package.json
 
-Make sure you add the `publish` command to your `scripts` field and make the following change to the `build` command:
+<Tabs groupId="plugin-preference">
+  <TabItem value="without-admin" label="Without Admin Customizations" default>
 
-```json title=package.json
+  Make sure you add the `publish` command to your `scripts` field and make the following change to the `build` command:
-"build": "babel src --out-dir . --ignore **/__tests__ --extensions \".ts,.js\"",
-"prepare": "cross-env NODE_ENV=production npm run build"
-```
 
-The `build` command ensures that the plugin's built files are placed as explained in the [plugin structure](./create.mdx#plugin-structure) section of the Create Plugin documentation.
+  ```json title=package.json
+  "scripts": {
+    // other scripts...
+    "build": "cross-env npm run clean && tsc",
+    "prepare": "cross-env NODE_ENV=production npm run build"
+  }
+  ```
 
-The `prepare` command facilitates your publishing process. You would typically run this script before publishing your plugin.
+  The `build` command ensures that the plugin's built files are placed as explained in the [plugin structure](./create.mdx#plugin-structure) section of the Create Plugin documentation.
 
-This new script requires installing the package `cross-env` as a development dependency:
+  The `prepare` command facilitates your publishing process. You would typically run this script before publishing your plugin.
 
-```bash npm2yarn
+  This new script requires installing the package `cross-env` as a development dependency:
-npm install --save-dev cross-env
+
-```
+  ```bash npm2yarn
+  npm install --save-dev cross-env
+  ```
+
+  </TabItem>
+  <TabItem value="with-admin" label="With Admin Customizations">
+
+  First, make sure to change `tsconfig` files as recommended in the [create guide](./create.mdx#changes-for-admin-plugins).
+
+  Then, add the `publish` command to your `scripts` field and make the following change to the `build` command:
+
+  ```json title=package.json
+  "scripts": {
+    // other scripts...
+    "build": "tsc -p ./tsconfig.server.json && medusa-admin bundle",
+    "prepare": "cross-env NODE_ENV=production npm run build"
+  }
+  ```
+
+  The `build` command ensures that the plugin's built files are placed as explained in the [plugin structure](./create.mdx#plugin-structure) section of the Create Plugin documentation, and bundles the admin customizations.
+
+  The `prepare` command facilitates your publishing process. You would typically run this script before publishing your plugin.
+
+  This new script requires installing the package `cross-env` as a development dependency:
+
+  ```bash npm2yarn
+  npm install --save-dev cross-env
+  ```
+
+  </TabItem>
+</Tabs>
+
+### 
 
 ### Plugin Structure
 
@@ -83,6 +123,8 @@ src
 .eslintrc
 .babelrc
 .prettierrc
+build
+.cache
 
 # These are files that are included in a
 # Medusa project and can be removed from a

docs/content/development/search/create.md

@@ -413,4 +413,4 @@ You can then send a request to the [Search Products endpoint](/api/store#tag/Pro
 ## See Also
 
 - [How to create a plugin](../plugins/create.mdx)
-- [How to publish a plugin](../plugins/publish.md)
+- [How to publish a plugin](../plugins/publish.mdx)

docs/content/homepage.mdx

@@ -162,40 +162,40 @@ Learn about all the new features and enhancements in Medusa.
 <DocCardList colSize={4} items={[
   {
     type: 'link',
-    href: '/modules/multiwarehouse/overview',
+    href: '/modules/products/serverless-module',
-    label: 'Multi-Warehouse',
+    label: 'Product Module',
     customProps: {
-      icon: Icons['building-solid'],
+      icon: Icons['tag-solid'],
-      description: 'Allows merchants to store a product in multiple locations with accurate and consistent inventory data.',
+      description: 'Learn about the new product module and how to use it in a serverless setup.',
       badge: {
-        variant: 'blue',
+        variant: 'orange',
-        children: 'New'
+        children: 'Beta'
       }
     }
   },
   {
     type: 'link',
-    href: '/modules/products/categories',
+    href: '/admin/widgets',
-    label: 'Product Categories',
+    label: 'Admin Widgets',
     customProps: {
-      icon: Icons['swatch-solid'],
+      icon: Icons['component-solid'],
-      description: 'Clearer organization of your products under categories that can be nested and ranked.',
+      description: 'Learn how you can customize the admin dashboard with admin widgets.',
       badge: {
-        variant: 'blue',
+        variant: 'orange',
-        children: 'New'
+        children: 'Beta'
       }
     }
   },
   {
     type: 'link',
-    href: '/development/modules/overview',
+    href: '/admin/routes',
-    label: 'Modules',
+    label: 'Admin UI Routes',
     customProps: {
-      icon: Icons['puzzle-solid'],
+      icon: Icons['computer-desktop-solid'],
-      description: 'Modules are self-contained packaged functionalities that are isolated from the Medusa core.',
+      description: 'Learn how you can customize the admin dashboard with admin UI routes.',
       badge: {
-        variant: 'blue',
+        variant: 'orange',
-        children: 'New'
+        children: 'Beta'
       }
     }
   },

docs/content/medusa-react/overview.md

@@ -188,6 +188,95 @@ Instead of using `mutate`, you can use `mutateAsync` to receive a Promise that r
 
 Learn more about how you can use mutations in [Tanstack Query’s documentation](https://tanstack.com/query/v4/docs/react/guides/mutations).
 
+### Custom Hooks
+
+Medusa React provides a utility function `createCustomAdminHooks` that allows developers to consume their admin custom endpoints using the same Medusa React methods and conventions. It returns custom mutation and query hooks that you can use to retrieve and manipulate data using your custom endpoints. This utility function is useful when customizing the admin with widgets.
+
+```ts
+import { createCustomAdminHooks } from "medusa-react"
+
+const {
+  useAdminEntity,
+  useAdminEntities,
+  useAdminCreateMutation,
+  useAdminUpdateMutation,
+  useAdminDeleteMutation,
+} = createCustomAdminHooks(
+  `/vendors`, 
+  "vendors",
+  { product: true }
+)
+```
+
+It accepts the following parameters:
+
+1. `path`: (required) the first parameter is a string that indicates the base path to the custom endpoint. For example, if you have custom endpoints that begin with `/admin/vendors`, the value of this parameter would be `vendors`. The `/admin` prefix will be added automatically.
+2. `queryKey`: (required) the second parameter is a string used to generate query keys for all `GET` hooks, which is used by Tanstack Query for caching. When a mutation related to this same key succeeds, the key will be automatically invalidated.
+3. `relatedDomains`: (optional) the third parameter is an object that can be used to specify domains related to this custom hook. This will ensure that Tanstack Query invalides the keys for those domains when your custom mutations succeed. For example, if your custom endpoint is related to products, you can pass `{ product: true }` as the value of this parameter. Then, when you use your custom mutation and it succeeds, the product's key `adminProductKeys.all` will be invalidated automatically, and all products will be re-fetched.
+
+:::note
+
+While the mechanism implemented using the `relatedDomains` parameter may seem a bit excessive, Tanstack Query is smart enough to only re-fetch the queries that are currently active. So, it won't result in all queries being re-fetched simultaneously.
+
+:::
+
+The function returns an object containing the following hooks:
+
+- `useAdminEntity`: is a query hook that allows retrieving a single entry using your custom endpoint. For example, if you have the `GET` endpoint `/admin/vendors/:id`, where `:id` is the ID of a vendor, you can use this hook to call that endpoint and retrieve a vendor by its ID.
+- `useAdminEntities`: is a query hook that allows retrieving a list of entries using your custom endpoint. For example, if you have the `GET` endpoint `/admin/vendors`, you can use this hook to call that endpoint and retrieve the list of vendors.
+- `useAdminCreateMutation`: is a mutation hook that allows creating an entry using your custom endpoint. For example, if you have the `POST` endpoint `/admin/vendors`, you can use this hook to call that endpoint and create a vendor.
+- `useAdminUpdateMutation`: is a mutation hook that allows updating an entry using your custom endpoint. For example, if you have the `POST` endpoint `/admin/vendors/:id`, you can use this hook to call that endpoint and update a vendor.
+- `useAdminDeleteMutation`: is a mutation hook that allows deleting an entry using your custom endpoint. For example, if you have the `DELETE` endpoint `/admin/vendors/:id`, you can use this hook to call that endpoint and delete a vendor.
+
+Each of these hooks are generic, allowing you to set the types for the functions and receive IntelliSense for the query parameters, the payload, and return data. The first generic type accepted would be the type of the request, and the second type accepted would be the type of the response.
+
+An example of using `createCustomAdminHooks`:
+
+```ts
+import { createCustomAdminHooks } from "medusa-react"
+
+type PostVendorsReq = {
+  name: string
+}
+
+type PostVendorRes = {
+  vendor: Vendor // assuming there's a type vendor
+}
+
+const MyWidget = () => {
+  const { 
+    useAdminCreateMutation: useCreateVendor,
+  } = createCustomAdminHooks(
+    `/vendors`, 
+    "vendors",
+    { product: true }
+  )
+
+  const { mutate } = useCreateVendor<
+    PostVendorsReq, 
+    PostVendorRes
+  >()
+
+  // ...
+
+  const handleCreate = () => {
+    mutate({
+      name: "Vendor 1",
+    }, {
+      onSuccess({ vendor }) {
+        console.log(vendor)
+      },
+    })
+  }
+
+  // ...
+}
+```
+
+In the example above, you use `createCustomAdminHooks` to create the custom hook `useAdminCreateMutation`, renamed to `useCreateVendor`. You then use `useCreateVendor` to initialize the `mutate` function. You set the generic types of useCreateVendor to the types `PostVendorsReq` and `PostVendorRes`, which are assumed to be  the types of the create endpoint's request and response respectively.
+
+Later in your code, you can use the `mutate` function to send a request to your endpoint and create a new vendor. The `mutate` function accepts the request's body parameters as an object. You can use the `onSuccess` function, which can be defined in the second parameter object of the `mutate` function, to get access to the response received.
+
 ---
 
 ## Utilities

docs/content/modules/multiwarehouse/admin/manage-item-allocations-in-orders.mdx

@@ -134,11 +134,11 @@ fetch(`<BACKEND_URL>/admin/reservations`, {
     inventory_item_id,
     quantity,
   }),
-  })
+})
-  .then((response) => response.json())
+.then((response) => response.json())
-  .then(({ reservation }) => {
+.then(({ reservation }) => {
   console.log(reservation.id)
-  })
+})
 ```
 
 </TabItem>

docs/content/modules/multiwarehouse/admin/manage-reservations.mdx

@@ -0,0 +1,401 @@
+---
+description: 'Learn how to manage custom reservations of a product variant using the admin APIs. This includes how to list, create, update, and delete reservations.'
+addHowToData: true
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# How to Manage Custom Reservations
+
+In this document, you’ll learn how to manage custom reservations of a product variant using the admin APIs.
+
+:::tip
+
+Although this guide covers how to manage custom reservations of product variants, you can create custom reservations for any entity that is associated with an Inventory Item.
+
+:::
+
+## Overview
+
+When an order is created, reservations are created for the items in that order automatically. However, Medusa also provides the capability to create custom reservations that aren’t related to any order. Custom reservations allow you to allocate quantities of a product variant manually. You can do that using the Reservations admin APIs.
+
+The functionalities in this guide apply to all types of reservations, including those associated with an order and those that aren’t.
+
+### Scenario
+
+You want to add or use the following admin functionalities:
+
+- List reservations, including custom reservations or those associated with orders.
+- Manage a reservation, including creating, updating, and deleting a reservation.
+
+:::note
+
+You can check the [API reference](/api/admin) for all available Reservations endpoints.
+
+:::
+
+---
+
+## Prerequisites
+
+### Medusa Components
+
+It is assumed that you already have a Medusa backend installed and set up. If not, you can follow the [quickstart guide](../../../development/backend/install.mdx) to get started.
+
+### Required Module
+
+This guide assumes you have a stock location and inventory modules installed. You can use Medusa’s [Stock Location and Inventory modules](../install-modules.md) or create your own modules.
+
+### JS Client
+
+This guide includes code snippets to send requests to your Medusa backend using Medusa’s JS Client, among other methods.
+
+If you follow the JS Client code blocks, it’s assumed you already have [Medusa’s JS Client](../../../js-client/overview.md) installed and have [created an instance of the client](../../../js-client/overview.md#configuration).
+
+### Medusa React
+
+This guide also includes code snippets to send requests to your Medusa backend using Medusa React, among other methods.
+
+If you follow the Medusa React code blocks, it's assumed you already have [Medusa React installed](../../../medusa-react/overview.md) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.md#usage).
+
+### Authenticated Admin User
+
+You must be an authenticated admin user before following along with the steps in the tutorial.
+
+You can learn more about [authenticating as an admin user in the API reference](/api/admin/#section/Authentication).
+
+---
+
+## List Reservations
+
+You can list all reservations in your store by sending a request to the [List Reservations endpoint](https://docs.medusajs.com/api/admin#tag/Reservations/operation/GetReservations):
+
+<Tabs groupId="request-type" isCodeTabs={true}>
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.reservations.list()
+.then(({ reservations, limit, count, offset }) => {
+  console.log(reservations.length)
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { useAdminReservations } from "medusa-react"
+
+const Reservations = () => {
+  const { reservations, isLoading } = useAdminReservations()
+
+  return (
+    <div>
+      {isLoading && <span>Loading...</span>}
+      {reservations && !reservations.length && (
+        <span>No Reservations</span>
+      )}
+      {reservations && reservations.length > 0 && (
+        <ul>
+          {reservations.map((reservation) => (
+            <li key={reservation.id}>{reservation.quantity}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  )
+}
+
+export default Reservations
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/reservations`, {
+  credentials: "include",
+})
+.then((response) => response.json())
+.then(({ reservations, limit, count, offset }) => {
+  console.log(reservations.length)
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X GET '<BACKEND_URL>/admin/reservations' \
+-H 'Authorization: Bearer <API_TOKEN>'
+```
+
+</TabItem>
+</Tabs>
+
+This endpoint does not require any query or path parameters. You can pass it query parameters for filtering or pagination purposes. Check out the [API reference](/api/admin#tag/Reservations/operation/GetReservations) for a list of accepted query parameters.
+
+This endpoint returns an array of reservations along with [pagination parameters](/api/admin#section/Pagination).
+
+---
+
+## Create a Reservation
+
+:::note
+
+Before you create a reservation for a product variant, make sure you’ve created an inventory item for that variant. You can learn how to do that in [this guide](./manage-inventory-items.mdx#create-an-inventory-item).
+
+:::
+
+You can create a reservation by sending a request to the [Create Reservation endpoint](/api/admin#tag/Reservations/operation/PostReservations):
+
+<Tabs groupId="request-type" isCodeTabs={true}>
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.reservations.create({
+  location_id,
+  inventory_item_id,
+  quantity,
+})
+.then(({ reservation }) => {
+  console.log(reservation.id)
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { useAdminCreateReservation } from "medusa-react"
+
+const CreateReservation = () => {
+  const createReservation = useAdminCreateReservation()
+  // ...
+
+  const handleCreate = () => {
+    createReservation.mutate({
+      location_id,
+      inventory_item_id,
+      quantity,
+    })
+  }
+
+  // ...
+}
+
+export default CreateReservation
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/reservations`, {
+  credentials: "include",
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    location_id,
+    inventory_item_id,
+    quantity,
+  }),
+})
+.then((response) => response.json())
+.then(({ reservation }) => {
+  console.log(reservation.id)
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X POST '<BACKEND_URL>/admin/reservations' \
+     -H 'Authorization: Bearer <API_TOKEN>' \
+     -H 'Content-Type: application/json' \
+     --data-raw '{
+        "location_id": "<LOC_ID>",
+        "inventory_item_id": "<INV_ITEM_ID>",
+        "quantity": 1
+     }'
+```
+
+</TabItem>
+</Tabs>
+
+This endpoint requires the following body parameters:
+
+- `location_id`: The ID of the location the reservation is created in.
+- `inventory_item_id`: The ID of the inventory item the product variant is associated with.
+- `quantity`: The quantity to allocate.
+
+The request returns the created reservation as an object.
+
+---
+
+## Update a Reservation
+
+You can update a reservation by sending a request to the [Update Reservation endpoint](/api/admin#tag/Reservations/operation/PostReservationsReservation):
+
+<Tabs groupId="request-type" isCodeTabs={true}>
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.reservations.update(reservationId, {
+  quantity,
+})
+.then(({ reservation }) => {
+  console.log(reservation.id)
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { useAdminUpdateReservation } from "medusa-react"
+
+const UpdateReservation = () => {
+  const updateReservation = useAdminUpdateReservation(
+    reservationId
+  )
+  // ...
+
+  const handleCreate = () => {
+    updateReservation.mutate({
+      quantity,
+    })
+  }
+
+  // ...
+}
+
+export default UpdateReservation
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/reservations/${reservationId}`, {
+  credentials: "include",
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+  },
+  body: JSON.stringify({
+    quantity,
+  }),
+})
+.then((response) => response.json())
+.then(({ reservation }) => {
+  console.log(reservation.id)
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X POST '<BACKEND_URL>/admin/reservations/<RESERVATION_ID>' \
+     -H 'Authorization: Bearer <API_TOKEN>' \
+     -H 'Content-Type: application/json' \
+     --data-raw '{
+        "quantity": 3
+     }'
+```
+
+</TabItem>
+</Tabs>
+
+This endpoint requires the ID of the reservation as a path parameter.
+
+In the request body parameters, you can optionally pass any of the following parameters to make updates to the reservation:
+
+- `quantity`: The quantity that should be reserved.
+- `location_id`: The ID of the location that the product variant should be allocated from.
+- `metadata`: set or change the reservation’s metadata.
+
+The request returns the updated reservation as an object.
+
+---
+
+## Delete a Reservation
+
+You can delete a reservation by sending a request to the [Delete Reservation endpoint](/api/admin#tag/Reservations/operation/DeleteReservationsReservation):
+
+<Tabs groupId="request-type" isCodeTabs={true}>
+<TabItem value="client" label="Medusa JS Client" default>
+
+```ts
+medusa.admin.reservations.delete(reservationId)
+.then(({ id, object, deleted }) => {
+  console.log(id)
+})
+```
+
+</TabItem>
+<TabItem value="medusa-react" label="Medusa React">
+
+```tsx
+import { useAdminDeleteReservation } from "medusa-react"
+
+const DeleteReservation = () => {
+  const deleteReservation = useAdminDeleteReservation(
+    reservationId
+  )
+  // ...
+
+  const handleDelete = () => {
+    deleteReservation.mutate()
+  }
+
+  // ...
+}
+
+export default DeleteReservation
+```
+
+</TabItem>
+<TabItem value="fetch" label="Fetch API">
+
+```ts
+fetch(`<BACKEND_URL>/admin/reservations/${reservationId}`, {
+  credentials: "include",
+  method: "DELETE",
+})
+.then((response) => response.json())
+.then(({ id, object, deleted }) => {
+  console.log(id)
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -L -X DELETE '<BACKEND_URL>/admin/reservations/<RESERVATION_ID>' \
+     -H 'Authorization: Bearer <API_TOKEN>'
+```
+
+</TabItem>
+</Tabs>
+
+This endpoint requires the reservation ID to be passed as a path parameter.
+
+The request returns the following fields:
+
+- `id`: The ID of the reservation.
+- `object`: The type of object that was removed. In this case, the value will be `reservation`.
+- `deleted`: A boolean value indicating whether the reservation was successfully deleted.
+
+---
+
+## See Also
+
+- [How to manage inventory items](./manage-inventory-items.mdx)
+- [How to manage stock locations](./manage-stock-locations.mdx)

docs/content/modules/products/serverless-module.md

@@ -0,0 +1,386 @@
+---
+title: 'How to Use Serverless Product Module'
+description: 'Learn how to use the product module in a serverless setup by installing it in a Next.js application.'
+addHowToData: true
+badge:
+  variant: orange
+  text: beta
+---
+
+In this document, you’ll learn how to use the Product module in a serverless setup.
+
+## Overview
+
+Medusa’s modules increase extensibility and customization capabilities. Instead of having to manage a fully-fledged ecommerce system, you can use these modules in serverless applications, such as a Next.js project.
+
+The module only needs to connect to a PostgreSQL database. You can also connect it to an existing Medusa database. Then, you can use the Product module to connect directly to the PostgreSQL database and retrieve or manipulate data.
+
+This guide explains how to use the Product Module in a Next.js application as an example. You can use it with other frameworks, such as Remix, as well.
+
+### Benefits of Serverless Modules
+
+- Keep packages small enough to be deployed to serverless Infrastructure easily
+- Bring Medusa closer to Edge runtime compatibility.
+- Make it easier to integrate modules into an ecosystem of existing commerce services.
+- Make it easier to customize or extend core logic in Medusa.
+
+:::info
+
+The product module is currently in beta, and it provides only functionalities related to browsing products. In later versions, the product module would include more powerful ecommerce features.
+
+:::
+
+---
+
+## Prerequisites
+
+- The Product Module requires a project using Node v16+.
+- The Product Module must connect to a PostgreSQL database. You can refer to [this guide](../../development/backend/prepare-environment.mdx#postgresql) to learn how to install PostgreSQL locally. Alternatively, you can use free PostgreSQL database hosting, such as [Vercel Postgres](https://vercel.com/docs/storage/vercel-postgres). If you have an existing Medusa database, you can use it as well.
+
+---
+
+## Installation in Next.js Project
+
+This section explains how to install the Product module in a Next.js project.
+
+If you don’t have a Next.js project, you can create one with the following command:
+
+```bash
+npx create-next-app@latest
+```
+
+Refer to the [Next.js documentation](https://nextjs.org/docs/getting-started/installation) for other available installation options.
+
+### Step 1: Install Product Module
+
+In the root directory of your Next.js project, run the following command to install the product module:
+
+```bash npm2yarn
+npm install @medusajs/product
+```
+
+### Step 2: Add Database Configurations
+
+Create a `.env` file and add the following environment variable:
+
+```bash
+POSTGRES_URL=<DATABASE_URL>
+```
+
+Where `<DATABASE_URL>` is your database connection URL of the format `postgres://[user][:password]@[host][:port]/[dbname]`. You can learn more about the connection URL format in [this guide](../../development/backend/configurations.md#postgresql-configurations).
+
+You can also set the following optional environment variables:
+
+- `POSTGRES_SCHEMA`: a string indicating the PostgreSQL schema to use. By default, it's `public`.
+- `POSTGRES_DRIVER_OPTIONS`: a stringified JSON object indicating the PostgreSQL options to use. The JSON object is then parsed to be used as a JavaScript object. By default, it's `{"connection":{"ssl":false}}` for local PostgreSQL databases, and `{"connection":{"ssl":{"rejectUnauthorized":false}}}` for remote databases.
+
+:::note
+
+If `POSTGRES_DRIVER_OPTIONS` is not specified, the PostgreSQL database is considered local if `POSTGRES_URL` includes `localhost`. Otherwise, it's considered remote.
+
+:::
+
+### Step 3: Run Database Migrations
+
+:::note
+
+If you are using an existing Medusa database, you can skip this step.
+
+:::
+
+Migrations are used to create your database schema. Before you can run migrations, add in your `package.json` the following scripts:
+
+```json title=package.json
+"scripts": {
+  //...other scripts
+  "product:migrations:run": "medusa-product-migrations-up",
+  "product:seed": "medusa-product-seed ./seed-data.js"
+},
+```
+
+The first command runs the migrations, and the second command allows you to optionally seed your database with demo products. However, you’d need the following seed file added in the root of your Next.js directory:
+
+<details>
+  <summary>Seed file</summary>
+
+  ```js title=seed-data.js
+  const productCategoriesData = [
+    {
+      id: "category-0",
+      name: "category 0",
+      parent_category_id: null,
+    },
+    {
+      id: "category-1",
+      name: "category 1",
+      parent_category_id: "category-0",
+    },
+    {
+      id: "category-1-a",
+      name: "category 1 a",
+      parent_category_id: "category-1",
+    },
+    {
+      id: "category-1-b",
+      name: "category 1 b",
+      parent_category_id: "category-1",
+      is_internal: true,
+    },
+    {
+      id: "category-1-b-1",
+      name: "category 1 b 1",
+      parent_category_id: "category-1-b",
+    },
+  ]
+  
+  const productsData = [
+    {
+      id: "test-1",
+      title: "product 1",
+      status: "published",
+      descriptions: "Lorem ipsum dolor sit amet, consectetur.",
+      tags: [
+        {
+          id: "tag-1",
+          value: "France",
+        },
+      ],
+      categories: [
+        {
+          id: "category-0",
+        },
+      ],
+    },
+    {
+      id: "test-2",
+      title: "product",
+      status: "published",
+      descriptions: "Lorem ipsum dolor sit amet, consectetur.",
+      tags: [
+        {
+          id: "tag-2",
+          value: "Germany",
+        },
+      ],
+      categories: [
+        {
+          id: "category-1",
+        },
+      ],
+    },
+  ]
+  
+  const variantsData = [
+    {
+      id: "test-1",
+      title: "variant title",
+      sku: "sku 1",
+      product: { id: productsData[0].id },
+      inventory_quantity: 10,
+    },
+    {
+      id: "test-2",
+      title: "variant title",
+      sku: "sku 2",
+      product: { id: productsData[1].id },
+      inventory_quantity: 10,
+    },
+  ]
+  
+  module.exports = {
+    productCategoriesData,
+    productsData,
+    variantsData,
+  }
+  ```
+
+</details>
+
+Then run the first and optionally second commands to migrate the database schema:
+
+```bash npm2yarn
+npm run product:migrations:run
+# optionally
+npm run product:seed
+```
+
+### Step 4: Adjust Next.js Configurations
+
+Next.js uses Webpack for compilation. Since quite a few of the dependencies used by the product module are not Webpack optimized, you have to add the product module as an external dependency.
+
+To do that, add the `serverComponentsExternalPackages` option in `next.config.js`:
+
+```js title=next.config.js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  experimental: {
+    serverComponentsExternalPackages: [
+      "@medusajs/product",
+    ],
+  },
+}
+
+module.exports = nextConfig
+```
+
+### Step 5: Create API Route
+
+The product module is ready for use now! You can now use it to create API endpoints within your Next.js application.
+
+:::note
+
+This guide uses Next.js's App Router.
+
+:::
+
+For example, create the file `app/api/products/route.ts` with the following content:
+
+```ts title=app/api/products/route.ts
+import { NextResponse } from "next/server"
+
+import { 
+  initialize as initializeProductModule,
+} from "@medusajs/product"
+
+export async function GET(request: Request) {
+  const productService = await initializeProductModule()
+
+  const data = await productService.list()
+
+  return NextResponse.json({ products: data })
+}
+```
+
+This creates a `GET` endpoint at the route `/api/products`. You import the `initialize` function, aliased as `initializeProductModule`, from `@medusajs/product`. Then, in the endpoint, you invoke the `initializeProductModule` function, which returns an instance of the `ProductModuleService`. Using the product module service’s `list` method, you retrieve all available products and return them in the response of the endpoint.
+
+### Step 6: Test Next.js Application
+
+To test the endpoint you added, start your Next.js application with the following command:
+
+```bash npm2yarn
+npm run dev
+```
+
+Then, open in your browser the URL `http://localhost:3000/api/products`. If you seeded your database with demo products, or you’re using a Medusa database schema, you’ll receive the products in your database. Otherwise, the request will return an empty array.
+
+---
+
+## Example Usages
+
+This section includes some examples of the different functionalities or ways you can use the product module. The code snippets are shown in the context of endpoints.
+
+### List Products
+
+```ts title=app/api/products/route.ts
+import { NextResponse } from "next/server"
+
+import { 
+  initialize as initializeProductModule,
+} from "@medusajs/product"
+
+export async function GET(request: Request) {
+  const productService = await initializeProductModule()
+
+  const data = await productService.list()
+
+  return NextResponse.json({ products: data })
+}
+```
+
+### Retrieve Product by Id
+
+```ts title=app/api/product/[id]/route.ts
+import { NextResponse } from "next/server"
+
+import { 
+  initialize as initializeProductModule,
+} from "@medusajs/product"
+
+export async function GET(
+  request: Request, 
+  { params }: { params: Record<string, any> }) {
+  
+  const { id } = params
+  const productService = await initializeProductModule()
+
+  const data = await productService.list({
+    id,
+  })
+
+  return NextResponse.json({ product: data[0] })
+}
+```
+
+### Retrieve Product by Handle
+
+```ts title=app/api/product/[handle]/route.ts
+import { NextResponse } from "next/server"
+
+import { 
+  initialize as initializeProductModule,
+} from "@medusajs/product"
+
+export async function GET(
+  request: Request, 
+  { params }: { params: Record<string, any> }) {
+  
+  const { handle } = params
+  const productService = await initializeProductModule()
+
+  const data = await productService.list({
+    handle,
+  })
+
+  return NextResponse.json({ product: data[0] })
+}
+```
+
+### Retrieve Categories
+
+```ts title=app/api/categories/route.ts
+import { NextResponse } from "next/server"
+
+import { 
+  initialize as initializeProductModule,
+} from "@medusajs/product"
+
+export async function GET(request: Request) {
+  const productService = await initializeProductModule()
+
+  const data = await productService.listCategories()
+
+  return NextResponse.json({ categories: data })
+}
+```
+
+### Retrieve Category by Handle
+
+```ts title=app/api/category/[handle]/route.ts
+import { NextResponse } from "next/server"
+
+import { 
+  initialize as initializeProductModule,
+} from "@medusajs/product"
+
+export async function GET(
+  request: Request, 
+  { params }: { params: Record<string, any> }) {
+  
+  const { handle } = params
+  const productService = await initializeProductModule()
+
+  const data = await productService.listCategories({
+    handle,
+  })
+
+  return NextResponse.json({ category: data[0] })
+}
+```
+
+---
+
+## See Also
+
+- [Products Commerce Module Overview](./overview.mdx)
+- [How to show products in a storefront](./storefront/show-products.mdx)
+- [How to show categories in a storefront](./storefront/use-categories.mdx)

docs/content/modules/products/storefront/show-products.mdx

@@ -5,6 +5,7 @@ addHowToData: true
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
+import Badge from '@site/src/components/Badge';
 
 # How to Show Products on the Storefront
 
@@ -45,6 +46,12 @@ This guide also includes code snippets to send requests to your Medusa backend u
 
 If you follow the Medusa React code blocks, it's assumed you already have [Medusa React installed](../../../medusa-react/overview.md) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.md#usage).
 
+### @medusajs/product Module
+
+This guide also includes code snippets to utilize the `@medusajs/product` module in your storefront, among other methods.
+
+If you follow the `@medusajs/product` code blocks, it's assumed you already have the [@medusajs/product](../serverless-module.md) installed.
+
 ---
 
 ## List Products
@@ -89,6 +96,31 @@ const Products = () => {
 export default Products
 ```
 
+</TabItem>
+<TabItem value="module" label={(
+  <>
+    @medusajs/product
+    <Badge variant="orange-dark">beta</Badge>
+  </>
+)} attributes={{
+  badge: true
+}}>
+
+```ts
+import {
+  initialize as initializeProductModule,
+} from "@medusajs/product"
+
+// in an async function, or you can use promises
+async () => {
+  // ...
+  const productService = await initializeProductModule()
+  const products = await productService.list()
+
+  console.log(products.length)
+}
+```
+
 </TabItem>
 <TabItem value="fetch" label="Fetch API">
 
@@ -164,6 +196,33 @@ const Products = () => {
 export default Products
 ```
 
+</TabItem>
+<TabItem value="module" label={(
+  <>
+    @medusajs/product
+    <Badge variant="orange-dark">beta</Badge>
+  </>
+)} attributes={{
+  badge: true
+}}>
+
+```ts
+import {
+  initialize as initializeProductModule,
+} from "@medusajs/product"
+
+// in an async function, or you can use promises
+async () => {
+  // ...
+  const productService = await initializeProductModule()
+  const products = await productService.list({
+    category_ids: ["cat_123"],
+  })
+
+  console.log(products)
+}
+```
+
 </TabItem>
 <TabItem value="fetch" label="Fetch API">
 
@@ -235,6 +294,33 @@ const Products = () => {
 export default Products
 ```
 
+</TabItem>
+<TabItem value="module" label={(
+  <>
+    @medusajs/product
+    <Badge variant="orange-dark">beta</Badge>
+  </>
+)} attributes={{
+  badge: true
+}}>
+
+```ts
+import {
+  initialize as initializeProductModule,
+} from "@medusajs/product"
+
+// in an async function, or you can use promises
+async () => {
+  // ...
+  const productService = await initializeProductModule()
+  const products = await productService.list({}, {
+    relations: ["categories"],
+  })
+
+  console.log(products)
+}
+```
+
 </TabItem>
 <TabItem value="fetch" label="Fetch API">
 
@@ -581,6 +667,33 @@ const Products = () => {
 export default Products
 ```
 
+</TabItem>
+<TabItem value="module" label={(
+  <>
+    @medusajs/product
+    <Badge variant="orange-dark">beta</Badge>
+  </>
+)} attributes={{
+  badge: true
+}}>
+
+```ts
+import {
+  initialize as initializeProductModule,
+} from "@medusajs/product"
+
+// in an async function, or you can use promises
+async () => {
+  // ...
+  const productService = await initializeProductModule()
+  const products = await productService.list({
+    id: productId,
+  })
+
+  console.log(products[0])
+}
+```
+
 </TabItem>
 <TabItem value="fetch" label="Fetch API">
 
@@ -658,6 +771,33 @@ const Products = () => {
 export default Products
 ```
 
+</TabItem>
+<TabItem value="module" label={(
+  <>
+    @medusajs/product
+    <Badge variant="orange-dark">beta</Badge>
+  </>
+)} attributes={{
+  badge: true
+}}>
+
+```ts
+import {
+  initialize as initializeProductModule,
+} from "@medusajs/product"
+
+// in an async function, or you can use promises
+async () => {
+  // ...
+  const productService = await initializeProductModule()
+  const products = await productService.list({
+    handle,
+  })
+
+  console.log(products[0])
+}
+```
+
 </TabItem>
 <TabItem value="fetch" label="Fetch API">
 

docs/content/modules/products/storefront/use-categories.mdx

@@ -43,6 +43,12 @@ This guide also includes code snippets to send requests to your Medusa backend u
 
 If you follow the Medusa React code blocks, it's assumed you already have [Medusa React installed](../../../medusa-react/overview.md) and have [used MedusaProvider higher in your component tree](../../../medusa-react/overview.md#usage).
 
+### @medusajs/product Module
+
+This guide also includes code snippets to utilize the `@medusajs/product` module in your storefront, among other methods.
+
+If you follow the `@medusajs/product` code blocks, it's assumed you already have the [@medusajs/product](../serverless-module.md) installed.
+
 ---
 
 ## List Categories
@@ -94,6 +100,29 @@ function Categories() {
 export default Categories
 ```
 
+</TabItem>
+<TabItem value="module" label={(
+  <>
+    @medusajs/product
+    <Badge variant="orange-dark">beta</Badge>
+  </>
+)}>
+
+```ts
+import {
+  initialize as initializeProductModule,
+} from "@medusajs/product"
+
+// in an async function, or you can use promises
+async () => {
+  // ...
+  const productService = await initializeProductModule()
+  const categories = await productService.listCategories()
+
+  console.log(categories)
+}
+```
+
 </TabItem>
 <TabItem value="fetch" label="Fetch API">
 
@@ -162,6 +191,31 @@ function Category() {
 export default Category
 ```
 
+</TabItem>
+<TabItem value="module" label={(
+  <>
+    @medusajs/product
+    <Badge variant="orange-dark">beta</Badge>
+  </>
+)}>
+
+```ts
+import {
+  initialize as initializeProductModule,
+} from "@medusajs/product"
+
+// in an async function, or you can use promises
+async () => {
+  // ...
+  const productService = await initializeProductModule()
+  const categories = await productService.listCategories({
+    id: productCategoryId,
+  })
+
+  console.log(categories[0])
+}
+```
+
 </TabItem>
 <TabItem value="fetch" label="Fetch API">
 
@@ -252,6 +306,31 @@ function Categories() {
 export default Categories
 ```
 
+</TabItem>
+<TabItem value="module" label={(
+  <>
+    @medusajs/product
+    <Badge variant="orange-dark">beta</Badge>
+  </>
+)}>
+
+```ts
+import {
+  initialize as initializeProductModule,
+} from "@medusajs/product"
+
+// in an async function, or you can use promises
+async () => {
+  // ...
+  const productService = await initializeProductModule()
+  const categories = await productService.listCategories({
+    handle,
+  })
+
+  console.log(categories[0])
+}
+```
+
 </TabItem>
 <TabItem value="fetch" label="Fetch API">
 

docs/content/plugins/cms/contentful/customize-contentful.md

@@ -332,5 +332,4 @@ Restart the Gatsby storefront then open a product that you added Rich Text conte
 
 ## See Also
 
-- Deploy your Medusa backend to [Heroku](../../../deployments/server/deploying-on-heroku.mdx), [Qovery](../../../deployments/server/deploying-on-qovery.md), or [DigitalOcean](../../../deployments/server/deploying-on-digital-ocean.md).
+- How to deploy your Medusa backend to [Heroku](../../../deployments/server/deploying-on-heroku.mdx), or [DigitalOcean](../../../deployments/server/deploying-on-digital-ocean.md), or [other providers](../../../deployments/server/index.mdx)
-- [How to deploy your Gatsby storefront to Netlify](../../../deployments/storefront/deploying-gatsby-on-netlify.md).

docs/content/plugins/cms/contentful/index.md

@@ -294,5 +294,4 @@ Learn [How to customize your Contentful backend and storefront](./customize-cont
 
 ## See Also
 
-- How to deploy your Medusa backend to [Heroku](../../../deployments/server/deploying-on-heroku.mdx), [Qovery](../../../deployments/server/deploying-on-qovery.md), or [DigitalOcean](../../../deployments/server/deploying-on-digital-ocean.md).
+- How to deploy your Medusa backend to [Heroku](../../../deployments/server/deploying-on-heroku.mdx), or [DigitalOcean](../../../deployments/server/deploying-on-digital-ocean.md), or [other providers](../../../deployments/server/index.mdx)
-- [How to deploy your Gatsby storefront to Netlify](../../../deployments/storefront/deploying-gatsby-on-netlify.md).

docs/content/plugins/payment/stripe.mdx

@@ -79,7 +79,7 @@ Other optional options include:
 
 - `payment_description`: a string that is used as the default description of a payment if none is provided.
 - `capture`: a boolean value that indicates whether payment should be captured manually or automatically. By default, it will be `false`, leading admins to capture the payment manually.
-- `automatic_payment_methods`: enables Stripe's automatic payment methods. This is useful if you're integrating services like Apple pay or Google pay.
+- `automatic_payment_methods`: a boolean value that enables Stripe's automatic payment methods. This is useful if you're integrating services like Apple pay or Google pay.
 
 ### Retrieve Stripe's Keys
 

docs/content/recipes/index.mdx

@@ -0,0 +1,99 @@
+import DocCardList from '@theme/DocCardList';
+import DocCard from '@theme/DocCard';
+import Icons from '@theme/Icon';
+import Feedback from '@site/src/components/Feedback';
+import LearningPath from '@site/src/components/LearningPath';
+import LargeCard from '@site/src/components/LargeCard';
+import Button from '@site/src/components/Button';
+
+# Medusa Recipes
+
+This document provides you resources for different paths based on what you're building with Medusa.
+
+:::note
+
+These recipes assume you already have a Medusa backend setup. If not, you can create a Medusa project with the following command:
+
+```bash
+npx create-medusa-app
+```
+
+[Learn more in this guide](../create-medusa-app.mdx).
+
+:::
+
+## Recipe: Setup Ecommerce Store
+
+Follow this recipe if you want to use Medusa for an ecommerce store. This recipe includes three steps that will get you a storefront deployed to Vercel and a backend deployed to Railway.
+
+<LearningPath pathName="simple-quickstart" />
+
+---
+
+## Recipe: Build a Marketplace
+
+Follow this guide if you want to build a Marketplace with Medusa.
+
+<DocCard item={{
+  type: 'link',
+  href: '/recipes/marketplace',
+  label: 'Build a Marketplace',
+  customProps: {
+    icon: Icons['building-storefront'],
+    description: 'Learn how you can build a marketplace with Medusa.'
+  }
+}} />
+
+---
+
+## Recipe: Build Subscription Purchases
+
+Follow this guide if you want to implement subscription-based purhcases with Medusa.
+
+<DocCard item={{
+  type: 'link',
+  href: '/recipes/subscriptions',
+  label: 'Build Subscription Purchases',
+  customProps: {
+    icon: Icons['credit-card-solid'],
+    description: 'Learn how you can implement subscription-based purchase in Medusa.'
+  }
+}} />
+
+<Feedback 
+   event="survey_use_cases"
+   question="Did your find your use case?"
+   positiveQuestion="Is there anything that should improved?"
+   negativeQuestion="What was your use case?"
+/>
+
+---
+
+<!-- vale docs.HeadingPunctuation = NO -->
+
+## Can't find your path?
+
+<!-- vale docs.HeadingPunctuation = YES -->
+
+Medusa is a customizable commerce solution that can be used to build any custom use case. If you can't find your use case mentioned above, the following guides give you a general understanding of how Medusa can be used and how you can customize it.
+
+<DocCardList colSize={6} items={[
+  {
+    type: 'link',
+    href: '/modules/overview',
+    label: 'Commerce Modules',
+    customProps: {
+      icon: Icons['puzzle-solid'],
+      description: "Learn about Medusa's commerce features and how to customize them."
+    }
+  },
+  {
+    type: 'link',
+    href: '#',
+    label: 'Medusa Development',
+    customProps: {
+      icon: Icons['server-stack-solid'],
+      description: "Learn how about Medusa's architecture and how to customize it."
+    }
+  },
+]} />

docs/content/recipes/marketplace.mdx

@@ -0,0 +1,400 @@
+import DocCardList from '@theme/DocCardList';
+import DocCard from '@theme/DocCard';
+import Icons from '@theme/Icon';
+import LearningPath from '@site/src/components/LearningPath';
+
+# Build a Marketplace
+
+This document guides you through the different documentation resources that will help you build a marketplace with Medusa.
+
+## Overview
+
+A marketplace is an online commerce store that allows different vendors to sell their products within the same commerce system. Customers can purchase products from any of these vendors, and vendors can manage their orders separately.
+
+<LearningPath pathName="marketplace" />
+
+---
+
+## Associate Entities with Stores
+
+:::tip
+
+Entities represent tables in the database.
+
+:::
+
+By default, entities like users, products, or orders aren't associated with a store, as it's assumed there's one store in Medusa. For a marketplace, each of these entities should be associated with their respective stores.
+
+To associate these entities with the `Store` entity, you need to extend and customize entities created in the Medusa core package `@medusajs/medusa`, such as the `User` entity, to add a relation to the `Store` entity.
+
+<DocCard item={{
+  type: 'link',
+  href: '/development/entities/extend-entity',
+  label: 'Extend an Entity',
+  customProps: {
+    icon: Icons['academic-cap-solid'],
+    description: 'Learn how to extend an entity in Medusa.',
+  }
+}} />
+
+<details>
+  <summary>Example: Associate User with Store</summary>
+
+  For example, to associate the `User` entity with the `Store` entity, create the file `src/models/user.ts` with the following content:
+
+  ```ts title=src/models/user.ts
+  import { 
+    Column,
+    Entity,
+    Index,
+    JoinColumn,
+    ManyToOne,
+  } from "typeorm"
+  import {
+    User as MedusaUser,
+  } from "@medusajs/medusa"
+  import { Store } from "./store"
+  
+  @Entity()
+  export class User extends MedusaUser {
+    @Index("UserStoreId")
+    @Column({ nullable: true })
+    store_id?: string
+  
+    @ManyToOne(() => Store, (store) => store.members)
+    @JoinColumn({ name: "store_id", referencedColumnName: "id" })
+    store?: Store
+  }
+  ```
+
+  Then, you need to extend the `UserRepository` to point to your extended entity. To do that, create the file `src/repositories/user.ts` with the following content:
+
+  ```ts title=src/repositories/user.ts
+  import { User } from "../models/user"
+  import { 
+    dataSource,
+  } from "@medusajs/medusa/dist/loaders/database"
+  import {
+    UserRepository as MedusaUserRepository,
+  } from "@medusajs/medusa/dist/repositories/user"
+
+  export const UserRepository = dataSource
+    .getRepository(User)
+    .extend({
+      ...Object.assign(
+        MedusaUserRepository, 
+        { target: User }
+      ),
+    })
+
+  export default UserRepository
+  ```
+
+  Next, you need to create a migration that reflects the changes on the `User` entity in your database. To do that, run the following command to create a migration file:
+
+  ```bash
+  npx typeorm migration:create src/migrations/add-user-store-id
+  ```
+
+  This creates a file in the `src/migrations` directory of the format `<TIMESTAMP>_add-user-store-id.ts`. Replace the `up` and `down` methods in that file with the methods here:
+
+  ```ts title=src/migrations/<TIMESTAMP>_add-user-store-id.ts
+  // ...
+
+  export class AddUserStoreId1681287255173 
+    implements MigrationInterface {
+      // ...
+
+      public async up(queryRunner: QueryRunner): Promise<void> {
+          await queryRunner.query(
+            `ALTER TABLE "user" ADD "store_id" character varying`
+          )
+          await queryRunner.query(
+            `CREATE INDEX "UserStoreId" ON "user" ("store_id")`
+          )
+      }
+
+      public async down(queryRunner: QueryRunner): Promise<void> {
+          await queryRunner.query(
+            `DROP INDEX "public"."UserStoreId"`
+          )
+          await queryRunner.query(
+            `ALTER TABLE "user" DROP COLUMN "store_id"`
+          )
+      }
+
+  }
+  ```
+
+  Finally, to reflect these changes and start using them, `build` your changes and run migrations with the following commands:
+
+  ```bash npm2yarn
+  npm run build
+  npx @medusajs/medusa migrations run
+  ```
+
+  You can extend other entities in a similar manner to associate them with a store.
+
+</details>
+
+---
+
+## Accessing Logged-in User
+
+Throughout your development, you'll likely need access to the logged-in user. For example, you'll need to know which user is logged in to know which store to associate a new product with.
+
+<DocCard item={{
+  type: 'link',
+  href: '/development/endpoints/example-logged-in-user',
+  label: 'Access Logged-in User',
+  customProps: {
+    icon: Icons['academic-cap-solid'],
+    description: 'Learn how to access the logged-in user throughout your project using a Middleware.',
+  }
+}} />
+
+---
+
+## Customize Data Management Functionalities
+
+After associating entities with stores, you'll need to customize how certain data management functionalities are implemented in the Medusa core package.
+
+For example, when a new user is created, you need to ensure that it's associated either with a new store or with the store of the logged-in user. Another example is associating a new product with the logged-in user's store.
+
+You can customize these functionalities by extending services. Services are classes that contain helper methods specific to an entity. For example, the `UserService` is used to manage functionalities related to the `User` entity, such as creating a user.
+
+You can also extend services if you need to customize a functionality implemented in a service for other reasons.
+
+<DocCard item={{
+  type: 'link',
+  href: '/development/services/extend-service',
+  label: 'Extend a Service',
+  customProps: {
+    icon: Icons['academic-cap-solid'],
+    description: 'Learn how to extend a service in Medusa',
+  }
+}} />
+
+<details>
+  <summary>Example: Extend User Service</summary>
+
+  You can extend the user service to change how the `create` method is implemented.
+
+  To extend the user service, create the file `src/services/user.ts` with the following content:
+
+<!-- eslint-disable prefer-rest-params -->
+
+  ```ts
+  import { Lifetime } from "awilix"
+  import { 
+    UserService as MedusaUserService,
+  } from "@medusajs/medusa"
+  import { User } from "../models/user"
+  import { 
+    CreateUserInput as MedusaCreateUserInput,
+  } from "@medusajs/medusa/dist/types/user"
+  import StoreRepository from "../repositories/store"
+
+  type CreateUserInput = {
+    store_id?: string
+  } & MedusaCreateUserInput
+
+  class UserService extends MedusaUserService {
+    static LIFE_TIME = Lifetime.SCOPED
+    protected readonly loggedInUser_: User | null
+    protected readonly storeRepository_: typeof StoreRepository
+  
+    constructor(container, options) {
+      super(...arguments)
+      this.storeRepository_ = container.storeRepository
+
+      try {
+        this.loggedInUser_ = container.loggedInUser
+      } catch (e) {
+        // avoid errors when backend first runs
+      }
+    }
+
+    async create(
+      user: CreateUserInput,
+      password: string
+    ): Promise<User> {
+      if (!user.store_id) {
+        const storeRepo = this.manager_.withRepository(
+          this.storeRepository_
+        )
+        let newStore = storeRepo.create()
+        newStore = await storeRepo.save(newStore)
+        user.store_id = newStore.id
+      }
+
+      return await super.create(user, password)
+    }
+  }
+
+  export default UserService
+  ```
+
+  In the `create` method of this extended service, you create a new store if the user being created doesn't have a store associated with it.
+
+  You can then test out your customization by running the `build` command and starting the backend:
+
+  ```bash
+  npm run build
+  npx @medusajs/medusa develop
+  ```
+</details>
+
+---
+
+## Listening to Events
+
+While implementing your marketplace, you'll typically need to listen to certain events then perform actions asynchronously. For example, you can listen to the `order.placed` event and, when triggered, create child orders of the order, separating ordered items by their associated store.
+
+To listen to events, you need to create Subscribers that subscribe a handler method to an event. In that handler method, you can implement the desired functionality.
+
+<DocCard item={{
+  type: 'link',
+  href: '/development/events/create-subscriber',
+  label: 'Create a Subscriber',
+  customProps: {
+    icon: Icons['academic-cap-solid'],
+    description: 'Learn how to create a subscriber in Medusa.',
+  }
+}} />
+
+<details>
+  <summary>Example: Listen to Order Created Event</summary>
+
+  To listen to the `order.placed` event, create the file `src/subscribers/orderNotifier.ts` with the following content:
+
+  ```ts
+  class OrderNotifierSubscriber {
+    constructor({ eventBusService }) {
+      eventBusService.subscribe("order.placed", this.handleOrder)
+    }
+
+    handleOrder = async (data) => {
+      // TODO perform functionality
+    }
+  }
+
+  export default OrderNotifierSubscriber
+  ```
+
+  This subscribes the `handleOrder` method to be executed whenever the `order.placed` event is emitted.
+
+  You can then test out your subscriber by running the `build` command and starting the backend:
+
+  ```bash
+  npm run build
+  npx @medusajs/medusa develop
+  ```
+</details>
+
+---
+
+## Add Payment and Fulfillment Providers
+
+Payment and fulfillment providers can be added through plugins or directly in your project. You can either create your own provider, use one of Medusa's official plugins, or use community plugins.
+
+:::note
+
+Payment and fulfillment providers are associated with regions, which are not associated with a store, by default. If you want to allow each store to specify its own payment and fulfillment providers, you'll need to [associate the region with a store](#associate-entities-with-stores).
+
+:::
+
+### Option 1: Create your own providers
+
+<DocCardList colSize={6} items={[
+  {
+    type: 'link',
+    href: '/modules/carts-and-checkout/backend/add-payment-provider',
+    label: 'Create a Payment Processor',
+    customProps: {
+      icon: Icons['academic-cap-solid'],
+      description: 'Learn how to create a payment processor.',
+    }
+  },
+  {
+    type: 'link',
+    href: '/modules/carts-and-checkout/backend/add-fulfillment-provider',
+    label: 'Create a Fulfillment Provider',
+    customProps: {
+      icon: Icons['academic-cap-solid'],
+      description: 'Learn how to create a fulfillment provider.',
+    }
+  },
+]} />
+
+### Option 2: Install a Plugin
+
+<DocCardList colSize={6} items={[
+  {
+    type: 'link',
+    href: '/plugins/overview',
+    label: 'Install an Official Medusa Plugin',
+    customProps: {
+      icon: Icons['academic-cap-solid'],
+      description: 'Check out available Medusa plugins to install.',
+    }
+  },
+  {
+    type: 'link',
+    href: 'https://medusajs.com/plugins/',
+    label: 'Install a Community Plugin',
+    customProps: {
+      icon: Icons['academic-cap-solid'],
+      description: 'Check out available community plugins to install.',
+    }
+  },
+]} />
+
+---
+
+## Build a Storefront
+
+Medusa provides a Next.js starter storefront that you can use with Medusa. Since you've customized your Medusa project, you'll need to either customize the existing Next.js storefront, or create a custom storefront.
+
+<DocCardList colSize={6} items={[
+  {
+    type: 'link',
+    href: '/starters/nextjs-medusa-starter',
+    label: 'Option 1: Use Next.js Storefront',
+    customProps: {
+      icon: Icons['academic-cap-solid'],
+      description: 'Install the Next.js Storefront to customize it.',
+    }
+  },
+  {
+    type: 'link',
+    href: '/storefront/roadmap',
+    label: 'Option 2: Build Custom Storefront',
+    customProps: {
+      icon: Icons['academic-cap-solid'],
+      description: 'Find useful resources to build your own storefront.',
+    }
+  },
+]} />
+
+---
+
+## Deploy Marketplace
+
+Our documentation includes deployment guides for a basic Medusa backend. You should be able to follow it to deploy your customized marketplace, as well.
+
+<DocCard item={{
+  type: 'link',
+  href: '/deployments/server',
+  label: 'Deploy Backend',
+  customProps: {
+    icon: Icons['academic-cap-solid'],
+    description: 'Learn how to deploy your marketplace backend to different hosting providers.',
+  }
+}} />
+
+---
+
+## Additional Development
+
+You can find other resources for your marketplace development in the [Medusa Development section](../development/overview.mdx) of this documentation.

docs/content/recipes/subscriptions.mdx

@@ -0,0 +1,161 @@
+import DocCardList from '@theme/DocCardList';
+import DocCard from '@theme/DocCard';
+import Icons from '@theme/Icon';
+import LearningPath from '@site/src/components/LearningPath';
+
+# Build Subscription-based Purchases
+
+This document guides you through the different documentation resources that will help you build subscription-based purchasing in Medusa.
+
+## Overview
+
+Subscription-based purchase allows customers to purchase products for a specified period, and the payment and fulfillment is processed within a regular interval in that period.
+
+For example, a customer can purchase a book subscription box for a period of three months. Each month, the payment will be captured for that order and, if the payment is successful, the fulfillment will be processed.
+
+<LearningPath pathName="subscriptions" />
+
+---
+
+## Save Subscription Details in the Database
+
+Subscriptions have details related to the subscription interval, subscription period, and more.
+
+Based on the approach you choose to implement the subscription logic (which is discussed in the next section), you might need to store different data in your backend.
+
+If you want to store the subscription details in a new table in the database, you can do that by creating an entity. If you want to extend an existing entity in Medusa's core, such as the `Order` entity, to add details related to the subscription, you can extend an entity.
+
+<DocCardList colSize={6} items={[
+  {
+    type: 'link',
+    href: '/development/entities/create',
+    label: "Create an Entity",
+    customProps: {
+      icon: Icons['academic-cap-solid'],
+      description: 'Learn how to create an entity in Medusa.',
+    }
+  },
+  {
+    type: 'link',
+    href: '/development/entities/extend-entity',
+    label: 'Extend an Entity',
+    customProps: {
+      icon: Icons['academic-cap-solid'],
+      description: 'Learn how to extend an entity in Medusa.',
+    }
+  },
+]} />
+
+---
+
+## Decide on Subscription Approach
+
+There are different ways to implement subscriptions in your Medusa backend. This document discusses two options: using Stripe subscriptions, or implementing subscriptions logic within the backend, independent of a specific payment provider.
+
+### Option 1: Using Stripe Subscriptions
+
+Stripe provides a [subscription payments](https://stripe.com/docs/billing/subscriptions/overview) that allows you to authorize payment on a subscription basis within Stripe. Stripe then handles checking for recurring payments and capturing payment at the specified interval.
+
+This approach allows you to deligate the complications of implementing the subscription logic to Stripe, but does not support using other payment providers.
+
+Medusa provides a Stripe plugin, however, it doesn't handle subscriptions. You can either use that plugin to add the subscription feature on top of it, or create a custom Stripe Subscription payment provider.
+
+<DocCardList colSize={6} items={[
+  {
+    type: 'link',
+    href: 'https://github.com/medusajs/medusa/tree/develop/packages/medusa-payment-stripe',
+    label: "Use Medusa's Stripe Plugin",
+    customProps: {
+      icon: Icons['github'],
+      description: "Check out Medusa's stripe plugin to build subscription on top of it.",
+    }
+  },
+  {
+    type: 'link',
+    href: '/modules/carts-and-checkout/backend/add-payment-provider',
+    label: 'Create Payment Processor',
+    customProps: {
+      icon: Icons['academic-cap-solid'],
+      description: 'Create a Stripe Subscription payment processor from scratch.',
+    }
+  },
+]} />
+
+### Option 2: Implement Subscription Logic
+
+By implementing the subscription logic within your backend, you can have full control over the subscription logic. You'll also be independent of payment providers, allowing you to provide customers with more than payment provider option.
+
+Implementing the logic depends on your use case, but you'll mainly need to do two things:
+
+1. Perform an action when an order is placed, such as saving subscription details. This can be done using subscribers, which register handler methods to be triggered when an event is emitted. When an order is placed, the `order.placed` event is emitted.
+2. Check daily for subscriptions that need renewal. This can be done using a scheduled job, which is a cron job that can be executed on a defined interval. Within that job, you can define your renewal logic.
+
+<DocCardList colSize={6} items={[
+  {
+    type: 'link',
+    href: '/development/events/create-subscriber',
+    label: 'Create a Subscriber',
+    customProps: {
+      icon: Icons['academic-cap-solid'],
+      description: 'Learn how to create a subscriber in Medusa.',
+    }
+  },
+  {
+    type: 'link',
+    href: '/development/scheduled-jobs/create',
+    label: 'Create a Scheduled Job',
+    customProps: {
+      icon: Icons['academic-cap-solid'],
+      description: 'Learn how to create a scheduled job in Medusa.',
+    }
+  },
+]} />
+
+---
+
+## Build a Storefront
+
+Medusa provides a Next.js starter storefront that you can use with Medusa. Since you've customized your Medusa project, you'll need to either customize the existing Next.js storefront, or create a custom storefront.
+
+<DocCardList colSize={6} items={[
+  {
+    type: 'link',
+    href: '/starters/nextjs-medusa-starter',
+    label: 'Option 1: Use Next.js Storefront',
+    customProps: {
+      icon: Icons['academic-cap-solid'],
+      description: 'Install the Next.js Storefront to customize it.',
+    }
+  },
+  {
+    type: 'link',
+    href: '/storefront/roadmap',
+    label: 'Option 2: Build Custom Storefront',
+    customProps: {
+      icon: Icons['academic-cap-solid'],
+      description: 'Find useful resources to build your own storefront.',
+    }
+  },
+]} />
+
+---
+
+## Deploy Backend
+
+Our documentation includes deployment guides for a basic Medusa backend. You should be able to follow it to deploy your customized backend, as well.
+
+<DocCard item={{
+  type: 'link',
+  href: '/deployments/server',
+  label: 'Deploy Backend',
+  customProps: {
+    icon: Icons['academic-cap-solid'],
+    description: 'Learn how to deploy your subscription-based backend to different hosting providers.',
+  }
+}} />
+
+---
+
+## Additional Development
+
+You can find other resources for your development in the [Medusa Development section](../development/overview.mdx) of this documentation.

docs/content/starters/nextjs-medusa-starter.mdx

@@ -30,12 +30,13 @@ This document guides you to install and set up the Next.js Starter Storefront.
 
 ![Next.js Storefront Demo](https://res.cloudinary.com/dza7lstvk/image/upload/v1668003177/Medusa%20Docs/Screenshots/koJl8uR_n3gvii.gif)
 
-## Instant Deployment to Netlify
+## Instant Deployment to Vercel
 
-Instead of manually following this guide to install then later deploy the Next.js Storefront, you can deploy the Next.js Storefront to Netlify with this button:
+Instead of manually following this guide to install then later deploy the Next.js Storefront, you can deploy the Next.js Storefront to Vercel with this button:
 
-<a href="https://app.netlify.com/start/deploy?repository=https://github.com/medusajs/nextjs-starter-medusa" className="img-url">
+<a 
-  <img src="https://www.netlify.com/img/deploy/button.svg" alt="Deploy to Netlify" className="no-zoom-img" />
+  href="https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fmedusajs%2Fnextjs-starter-medusa.git&env=NEXT_PUBLIC_MEDUSA_BACKEND_URL&envDescription=URL%20of%20your%20Medusa%20Backend" class="img-url no-zoom-img">
+  <img src="https://vercel.com/button" alt="Deploy with Vercel" class="no-zoom-img"/>
 </a>
 
 ---

docs/content/troubleshooting/create-medusa-app-errors/_eagain-error.md

@@ -20,13 +20,19 @@ npm run build
 npx @medusajs/medusa-cli migrations run
 ```
 
-4\. Optionally seed the database:
+4\. Create an admin user:
+
+```bash
+npx @medusajs/medusa-cli user -e user@test.com -p supersecret
+```
+
+5\. Optionally seed the database:
 
 ```bash
 npx @medusajs/medusa-cli seed -f ./data/seed.json
 ```
 
-5\. Start project:
+6\. Start project:
 
 ```bash
 npx @medusajs/medusa-cli develop

docs/content/upgrade-guides/index.mdx

@@ -4,7 +4,7 @@ description: 'Upgrade guides on how to update the Medusa backend along with othe
 ---
 
 import DocCard from '@theme/DocCard';
-import getFirstCategoryItem from '@site/src/utils/getFirstCategoryItem';
+import getFirstCategoryItem from '@site/src/utils/get-first-category-item';
 
 # Upgrade Guides
 

docs/content/user-guide/multiwarehouse/index.md

@@ -30,3 +30,4 @@ It should be noted that the following are not explained within this section of t
 
 - [Manage Inventory](./inventory.mdx)
 - [Manage Locations](./locations.mdx)
+- [Manage Reservations](./reservations.mdx)

docs/content/user-guide/multiwarehouse/reservations.mdx

@@ -0,0 +1,99 @@
+---
+sidebar_position: 4
+description: "This user guide explains how to manage reservations in your store. Learn how to view, create, edit, and delete reservations."
+addHowToData: true
+---
+
+import UiIcon from '@site/src/components/UiIcon';
+
+# Manage Reservations
+
+In this document, you’ll learn how to manage reservations in your store.
+
+## View Reservations
+
+To view reservations, go to Inventory from the sidebar, and click on the Reservations header.
+
+In the reservations page, you can view all reservations, either created by an order or created manually.
+
+### Filter by Location
+
+To filter reservations by location:
+
+1. Click on the “All locations” button.
+2. Choose the location you want to filter reservations by.
+
+### Other Filters
+
+You can also filter by description, creation date, reserved quantity, and more.
+
+To do that:
+
+1. Click on the “View” button.
+2. Apply any filters relevant for you.
+3. Click on the “Apply” button.
+
+To reset applied filters:
+
+1. Click on the “View” button.
+2. Toggle off applied filters.
+3. Click on the “Apply” button.
+
+---
+
+## Create a Reservation
+
+Reservations are created manually when an order is created, and you can also manage them from the order’s page.
+
+You can also manually create a reservation from the Reservations page. To create a reservation:
+
+1. Go to Inventory → Reservations.
+2. Click on the “Create reservation” button.
+3. In the form that opens:
+    1. For the “Location” field, select the location the reservation is created in.
+    2. For the “Item to reserve” field, enter the SKU of the item you want to create a reservation for.
+    3. Select the item from the results that appear. Once you do that, a table shows. In the table:
+        1. Next to the “Reserve” row, specify the reservation quantity.
+        2. If you want to remove the selected item and choose a different one, click on the “Remove item” button.
+    4. You can optionally enter a Description of the reservation.
+    5. You can optionally enter key-value metadata fields if you have any custom data you want to attach to the reservation. To add or manage the metadata fields:
+        1. Hover over the available row in the table.
+        2. Click on the <UiIcon lightIcon="https://res.cloudinary.com/dza7lstvk/image/upload/v1667999308/Medusa%20Docs/UI%20Icons/1ordBC6_ssysel.png" darkIcon="https://res.cloudinary.com/dza7lstvk/image/upload/v1667999326/Medusa%20Docs/UI%20Icons/dSwWYBH_stzgoi.png" alt="three dots" /> icon.
+        3. Choose the actions in the dropdown to manage the metadata fields.
+4. Once you’re done, click the “Save reservation” button.
+
+---
+
+## Edit Reservation
+
+To edit a reservation:
+
+1. Go to Inventory → Reservations
+2. Find the reservation you want to edit, and click on the <UiIcon lightIcon="https://res.cloudinary.com/dza7lstvk/image/upload/v1667999308/Medusa%20Docs/UI%20Icons/1ordBC6_ssysel.png" darkIcon="https://res.cloudinary.com/dza7lstvk/image/upload/v1667999326/Medusa%20Docs/UI%20Icons/dSwWYBH_stzgoi.png" alt="three dots" /> icon on its right.
+3. Click on “Edit” from the dropdown.
+4. In the side window that opens:
+    1. You can change the location of the reservation using the Location field.
+    2. In the table, you can change the reserved quantity by changing the value of the Allocate row.
+    3. You can change the description of the reservation using the Description field.
+    4. You can manage the metadata of the reservation:
+        1. If there aren’t any metadata fields, you can add a metadata field using the “Add metadata” button.
+        2. You can add more metadata fields or manage available ones by hovering over a row, clicking the <UiIcon lightIcon="https://res.cloudinary.com/dza7lstvk/image/upload/v1667999308/Medusa%20Docs/UI%20Icons/1ordBC6_ssysel.png" darkIcon="https://res.cloudinary.com/dza7lstvk/image/upload/v1667999326/Medusa%20Docs/UI%20Icons/dSwWYBH_stzgoi.png" alt="three dots" /> icon, and choosing an action from the dropdown.
+        3. You can remove metadata fields by clicking the “Remove metadata” button.
+5. Once you’re done, click the “Save and close” button.
+
+---
+
+## Delete Reservation
+
+:::warning
+
+Deleting a reservation can’t be undone, and the reservation data can’t be restored.
+
+:::
+
+To delete a reservation:
+
+1. Go to Inventory → Reservations
+2. Find the reservation you want to edit, and click on the <UiIcon lightIcon="https://res.cloudinary.com/dza7lstvk/image/upload/v1667999308/Medusa%20Docs/UI%20Icons/1ordBC6_ssysel.png" darkIcon="https://res.cloudinary.com/dza7lstvk/image/upload/v1667999326/Medusa%20Docs/UI%20Icons/dSwWYBH_stzgoi.png" alt="three dots" /> icon on its right.
+3. Click on “Delete” from the dropdown.
+4. Confirm deleting the reservation by clicking the “Yes, remove" button in the pop-up.

www/docs/.eslintrc.js

@@ -86,7 +86,7 @@ module.exports = {
       {
         allow: [
           "error",
-          "warn"
+          "warn",
         ]
       }
     ]

www/docs/package.json

@@ -44,7 +44,8 @@
     "react-uuid": "^2.0.0",
     "redocusaurus": "^1.4.0",
     "tailwindcss": "^3.3.2",
-    "url-loader": "^4.1.1"
+    "url-loader": "^4.1.1",
+    "uuid": "^9.0.0"
   },
   "browserslist": {
     "production": [
@@ -63,6 +64,8 @@
     "@docusaurus/eslint-plugin": "latest",
     "@docusaurus/module-type-aliases": "latest",
     "@tsconfig/docusaurus": "^1.0.7",
+    "@types/react-transition-group": "^4.4.6",
+    "@types/uuid": "^9.0.1",
     "@typescript-eslint/eslint-plugin": "^5.55.0",
     "@typescript-eslint/parser": "^5.55.0",
     "eslint": "^8.36.0",

www/docs/sidebars.js

@@ -35,6 +35,30 @@ module.exports = {
       },
       className: "homepage-sidebar-item",
     },
+    {
+      type: "category",
+      label: "Recipes",
+      link: {
+        type: "doc",
+        id: "recipes/index",
+      },
+      customProps: {
+        sidebar_icon: "newspaper",
+      },
+      className: "homepage-sidebar-item",
+      items: [
+        {
+          type: "doc",
+          id: "recipes/marketplace",
+          label: "Marketplace",
+        },
+        {
+          type: "doc",
+          id: "recipes/subscriptions",
+          label: "Subscriptions",
+        },
+      ],
+    },
     {
       type: "html",
       value: "Browse Docs",
@@ -62,13 +86,33 @@ module.exports = {
       className: "homepage-sidebar-item",
     },
     {
+      type: "category",
+      label: "Admin Dashboard",
+      link: {
         type: "doc",
         id: "admin/quickstart",
-      label: "Admin Dashboard",
+      },
       customProps: {
         sidebar_icon: "computer-desktop",
       },
       className: "homepage-sidebar-item",
+      items: [
+        {
+          type: "doc",
+          label: "Admin Widgets",
+          id: "admin/widgets",
+        },
+        {
+          type: "doc",
+          label: "Admin UI Routes",
+          id: "admin/routes",
+        },
+        {
+          type: "doc",
+          label: "Example: Create Onboarding",
+          id: "admin/onboarding",
+        },
+      ],
     },
     {
       type: "ref",
@@ -222,19 +266,6 @@ module.exports = {
                 },
               },
             },
-            {
-              type: "doc",
-              id: "deployments/server/deploying-on-qovery",
-              label: "Deploy on Qovery",
-              customProps: {
-                image:
-                  "https://res.cloudinary.com/dza7lstvk/image/upload/v1669739955/Medusa%20Docs/Other/qOvY2dN_vogsxy.png",
-                badge: {
-                  variant: "orange",
-                  children: "Deprecated",
-                },
-              },
-            },
           ],
         },
         {
@@ -279,19 +310,6 @@ module.exports = {
                 },
               },
             },
-            {
-              type: "doc",
-              id: "deployments/storefront/deploying-gatsby-on-netlify",
-              label: "Deploy Gatsby on Netlify",
-              customProps: {
-                image:
-                  "https://res.cloudinary.com/dza7lstvk/image/upload/v1679574027/Medusa%20Docs/Other/gCbsCvX_h7nijn.png",
-                badge: {
-                  variant: "orange",
-                  children: "Deprecated",
-                },
-              },
-            },
           ],
         },
       ],
@@ -615,6 +633,11 @@ module.exports = {
           id: "modules/products/admin/import-products",
           label: "Admin: Import Products",
         },
+        {
+          type: "doc",
+          id: "modules/products/serverless-module",
+          label: "Storefront: Serverless Module",
+        },
         {
           type: "doc",
           id: "modules/products/storefront/show-products",
@@ -882,6 +905,11 @@ module.exports = {
           id: "modules/multiwarehouse/admin/manage-inventory-items",
           label: "Admin: Manage Inventory Items",
         },
+        {
+          type: "doc",
+          id: "modules/multiwarehouse/admin/manage-reservations",
+          label: "Admin: Manage Custom Reservations",
+        },
         {
           type: "doc",
           id: "modules/multiwarehouse/admin/manage-item-allocations-in-orders",

www/docs/src/components/Badge/index.tsx

@@ -13,12 +13,21 @@ const Badge: React.FC<BadgeProps> = ({ className, variant, children }) => {
         "tw-text-label-x-small-plus tw-py-px tw-px-0.4 tw-rounded tw-border tw-border-solid tw-text-center",
         variant === "purple" &&
           "tw-bg-medusa-tag-purple-bg dark:tw-bg-medusa-tag-purple-bg-dark tw-text-medusa-tag-purple-text dark:tw-text-medusa-tag-purple-text-dark tw-border-medusa-tag-purple-border dark:tw-border-medusa-tag-purple-border-dark",
+        variant === "purple-dark" &&
+          "tw-bg-medusa-tag-purple-bg-dark tw-text-medusa-tag-purple-text-dark tw-border-medusa-tag-purple-border-dark",
         variant === "orange" &&
           "tw-bg-medusa-tag-orange-bg dark:tw-bg-medusa-tag-orange-bg-dark tw-text-medusa-tag-orange-text dark:tw-text-medusa-tag-orange-text-dark tw-border-medusa-tag-orange-border dark:tw-border-medusa-tag-orange-border-dark",
+        variant === "orange-dark" &&
+          "tw-bg-medusa-tag-orange-bg-dark tw-text-medusa-tag-orange-text-dark tw-border-medusa-tag-orange-border-dark",
         variant === "green" &&
           "tw-bg-medusa-tag-green-bg dark:tw-bg-medusa-tag-green-bg-dark tw-text-medusa-tag-green-text dark:tw-text-medusa-tag-green-text-dark tw-border-medusa-tag-green-border dark:tw-border-medusa-tag-green-border-dark",
+        variant === "green-dark" &&
+          "tw-bg-medusa-tag-green-bg-dark tw-text-medusa-tag-green-text-dark tw-border-medusa-tag-green-border-dark",
         variant === "blue" &&
           "tw-bg-medusa-tag-blue-bg dark:tw-bg-medusa-tag-blue-bg-dark tw-text-medusa-tag-blue-text dark:tw-text-medusa-tag-blue-text-dark tw-border-medusa-tag-blue-border dark:tw-border-medusa-tag-blue-border-dark",
+        variant === "blue-dark" &&
+          "tw-bg-medusa-tag-blue-bg-dark tw-text-medusa-tag-blue-text-dark tw-border-medusa-tag-blue-border-dark",
+        "badge",
         className
       )}
     >

www/docs/src/components/Button/index.tsx

@@ -2,6 +2,7 @@ import React from "react"
 import clsx from "clsx"
 
 type ButtonProps = {
+  btnTypeClassName?: string
   className?: string
   onClick?: React.MouseEventHandler<HTMLButtonElement>
   disabled?: boolean
@@ -9,13 +10,18 @@ type ButtonProps = {
 
 const Button: React.FC<ButtonProps> = ({
   className = "",
+  btnTypeClassName,
   onClick,
   children,
   ...props
 }) => {
   return (
     <button
-      className={clsx("btn-primary", className)}
+      className={clsx(
+        !btnTypeClassName?.length && "btn-primary",
+        btnTypeClassName,
+        className
+      )}
       onClick={onClick}
       {...props}
     >

www/docs/src/components/Feedback/index.tsx

@@ -1,12 +1,12 @@
 import React, { useRef, useState, useEffect } from "react"
 import { CSSTransition, SwitchTransition } from "react-transition-group"
-// import "./index.css"
 
 import useIsBrowser from "@docusaurus/useIsBrowser"
 import { useLocation } from "@docusaurus/router"
 import uuid from "react-uuid"
 import Solutions from "./Solutions/index"
 import Button from "../Button"
+import { useUser } from "@site/src/providers/User"
 
 type FeedbackProps = {
   event?: string
@@ -50,6 +50,7 @@ const Feedback: React.FC<FeedbackProps> = ({
 
   const isBrowser = useIsBrowser()
   const location = useLocation()
+  const { track } = useUser()
 
   function handleFeedback(e) {
     const feedback = e.target.classList.contains("positive")
@@ -60,11 +61,10 @@ const Feedback: React.FC<FeedbackProps> = ({
 
   function submitFeedback(e, feedback = null) {
     if (isBrowser) {
-      if (window.analytics) {
       if (showForm) {
         setLoading(true)
       }
-        window.analytics.track(
+      track(
         event,
         {
           url: location.pathname,
@@ -75,7 +75,6 @@ const Feedback: React.FC<FeedbackProps> = ({
               ? "yes"
               : "no",
           message: message?.length ? message : null,
-            uuid: id,
         },
         function () {
           if (showForm) {
@@ -84,11 +83,6 @@ const Feedback: React.FC<FeedbackProps> = ({
           }
         }
       )
-      } else {
-        if (showForm) {
-          resetForm()
-        }
-      }
     }
   }
 
@@ -110,7 +104,13 @@ const Feedback: React.FC<FeedbackProps> = ({
     <div className={`tw-py-2 ${className}`}>
       <SwitchTransition mode="out-in">
         <CSSTransition
-          key={showForm}
+          key={
+            showForm
+              ? "show_form"
+              : !submittedFeedback
+              ? "feedback"
+              : "submitted_feedback"
+          }
           nodeRef={nodeRef}
           timeout={300}
           addEndListener={(done) => {

www/docs/src/components/Footer/SocialLinks/index.tsx

@@ -12,16 +12,16 @@ type SocialLinksProps = {
 const SocialLinks: React.FC<SocialLinksProps> = ({ links = [] }) => {
   const socialIcons = {
     twitter: (
-      <IconTwitter iconColorClassName="tw-fill-medusa-icon-placeholder dark:tw-fill-medusa-icon-placeholder-dark group-hover:tw-fill-medusa-icon-secondary dark:group-hover:tw-fill-medusa-icon-secondary-dark" />
+      <IconTwitter iconColorClassName="tw-fill-medusa-icon-muted dark:tw-fill-medusa-icon-muted-dark group-hover:tw-fill-medusa-icon-subtle dark:group-hover:tw-fill-medusa-icon-subtle-dark" />
     ),
     github: (
-      <IconGitHub iconColorClassName="tw-fill-medusa-icon-placeholder dark:tw-fill-medusa-icon-placeholder-dark group-hover:tw-fill-medusa-icon-secondary dark:group-hover:tw-fill-medusa-icon-secondary-dark" />
+      <IconGitHub iconColorClassName="tw-fill-medusa-icon-muted dark:tw-fill-medusa-icon-muted-dark group-hover:tw-fill-medusa-icon-subtle dark:group-hover:tw-fill-medusa-icon-subtle-dark" />
     ),
     discord: (
-      <IconDiscord iconColorClassName="tw-fill-medusa-icon-placeholder dark:tw-fill-medusa-icon-placeholder-dark group-hover:tw-fill-medusa-icon-secondary dark:group-hover:tw-fill-medusa-icon-secondary-dark" />
+      <IconDiscord iconColorClassName="tw-fill-medusa-icon-muted dark:tw-fill-medusa-icon-muted-dark group-hover:tw-fill-medusa-icon-subtle dark:group-hover:tw-fill-medusa-icon-subtle-dark" />
     ),
     linkedin: (
-      <IconLinkedIn iconColorClassName="tw-fill-medusa-icon-placeholder dark:tw-fill-medusa-icon-placeholder-dark group-hover:tw-fill-medusa-icon-secondary dark:group-hover:tw-fill-medusa-icon-secondary-dark" />
+      <IconLinkedIn iconColorClassName="tw-fill-medusa-icon-muted dark:tw-fill-medusa-icon-muted-dark group-hover:tw-fill-medusa-icon-subtle dark:group-hover:tw-fill-medusa-icon-subtle-dark" />
     ),
   }
 

www/docs/src/components/LargeCard/index.tsx

@@ -12,8 +12,8 @@ type LargeCardProps = {
     dark?: string
   }
   title: string
-  action: {
+  action?: {
-    href: string
+    href?: string
   }
   isSoon?: boolean
   className?: string
@@ -23,7 +23,9 @@ const LargeCard: React.FC<LargeCardProps> = ({
   Icon,
   image,
   title,
-  action: { href },
+  action: { href } = {
+    href: "",
+  },
   isSoon = false,
   className = "",
   children,
@@ -38,6 +40,9 @@ const LargeCard: React.FC<LargeCardProps> = ({
         "[&:nth-child(3n+1):before]:tw-bg-[2%_52%] [&:nth-child(3n+2):before]:tw-bg-[19%_16%] [&:nth-child(3n+3):before]:tw-bg-[17%_50%]",
         !isSoon &&
           "hover:tw-bg-medusa-bg-subtle-hover dark:hover:tw-bg-medusa-bg-base-hover-dark hover:tw-shadow-card-hover dark:hover:tw-shadow-card-hover-dark",
+        !isSoon &&
+          "group-hover:tw-bg-medusa-bg-subtle-hover dark:group-hover:tw-bg-medusa-bg-base-hover-dark group-hover:tw-shadow-card-hover dark:group-hover:tw-shadow-card-hover-dark",
+        "tw-transition-all tw-duration-200 tw-ease-ease",
         "large-card",
         className
       )}
@@ -79,6 +84,7 @@ const LargeCard: React.FC<LargeCardProps> = ({
           {children}
         </div>
       </div>
+      {href && (
         <Link
           href={href}
           className={clsx(
@@ -86,6 +92,7 @@ const LargeCard: React.FC<LargeCardProps> = ({
             isSoon && "group-hover:tw-pointer-events-none"
           )}
         ></Link>
+      )}
     </article>
   )
 }

www/docs/src/components/LearningPath/Finish/index.tsx

@@ -0,0 +1,42 @@
+import { LearningPathStepType } from "@site/src/providers/LearningPath"
+import React from "react"
+import Rating from "../../Rating"
+
+export type LearningPathFinishType =
+  | {
+      type: "rating"
+      step: Omit<LearningPathStepType, "descriptionJSX"> & {
+        eventName?: string
+      }
+    }
+  | {
+      type: "custom"
+      step: LearningPathStepType & {
+        descriptionJSX: JSX.Element
+      }
+    }
+
+type LearningPathFinishProps = LearningPathFinishType & {
+  onRating?: () => void
+}
+
+const LearningPathFinish: React.FC<LearningPathFinishProps> = ({
+  type,
+  step,
+  onRating,
+}) => {
+  return (
+    <>
+      {type === "rating" && (
+        <Rating event={step.eventName} onRating={onRating} />
+      )}
+      {type === "custom" && (
+        <span className="tw-text-label-small tw-text-medusa-text-subtle dark:tw-text-medusa-text-subtle-dark">
+          {step.descriptionJSX}
+        </span>
+      )}
+    </>
+  )
+}
+
+export default LearningPathFinish

www/docs/src/components/LearningPath/Icon/index.tsx

@@ -0,0 +1,33 @@
+import useBaseUrl from "@docusaurus/useBaseUrl"
+import clsx from "clsx"
+import React from "react"
+
+type LearningPathIconProps = {
+  className?: string
+  imgClassName?: string
+} & React.AllHTMLAttributes<HTMLDivElement>
+
+const LearningPathIcon: React.FC<LearningPathIconProps> = ({
+  className = "",
+  imgClassName = "",
+}) => {
+  return (
+    <div
+      className={clsx(
+        "tw-rounded-full tw-shadow-card-rest dark:tw-shadow-card-rest-dark tw-w-3 tw-h-3 tw-bg-button-neutral dark:tw-bg-button-neutral-dark",
+        "tw-flex tw-justify-center tw-items-center tw-flex-none",
+        className
+      )}
+    >
+      <img
+        src={useBaseUrl("/img/learning-path-img.png")}
+        className={clsx(
+          "tw-rounded-full tw-w-[40px] tw-h-[40px] no-zoom-img",
+          imgClassName
+        )}
+      />
+    </div>
+  )
+}
+
+export default LearningPathIcon

www/docs/src/components/LearningPath/Steps/Actions/index.tsx

@@ -0,0 +1,41 @@
+import Button from "@site/src/components/Button"
+import { useLearningPath } from "@site/src/providers/LearningPath"
+import React from "react"
+
+type LearningPathStepActionsType = {
+  onFinish?: () => void
+  onClose?: () => void
+} & React.AllHTMLAttributes<HTMLDivElement>
+
+const LearningPathStepActions: React.FC<LearningPathStepActionsType> = ({
+  onFinish,
+  onClose,
+}) => {
+  const { hasNextStep, nextStep, endPath } = useLearningPath()
+
+  const handleFinish = () => {
+    if (onFinish) {
+      onFinish()
+    } else {
+      endPath()
+    }
+  }
+
+  return (
+    <div className="tw-flex tw-gap-0.5 tw-p-1 tw-justify-end tw-items-center">
+      <Button onClick={onClose}>Close</Button>
+      {hasNextStep() && (
+        <Button onClick={nextStep} btnTypeClassName="btn-inverted">
+          Next
+        </Button>
+      )}
+      {!hasNextStep() && (
+        <Button onClick={handleFinish} btnTypeClassName="btn-inverted">
+          Finish
+        </Button>
+      )}
+    </div>
+  )
+}
+
+export default LearningPathStepActions

www/docs/src/components/LearningPath/Steps/index.tsx

@@ -0,0 +1,84 @@
+import { useLearningPath } from "@site/src/providers/LearningPath"
+import React from "react"
+import LearningPathStepActions from "./Actions"
+import clsx from "clsx"
+import IconCircleDottedLine from "@site/src/theme/Icon/CircleDottedLine"
+import IconCheckCircleSolid from "@site/src/theme/Icon/CheckCircleSolid"
+import IconCircleMiniSolid from "@site/src/theme/Icon/CircleMiniSolid"
+import Link from "@docusaurus/Link"
+
+type LearningPathStepsProps = {
+  onFinish?: () => void
+  onClose?: () => void
+}
+
+const LearningPathSteps: React.FC<LearningPathStepsProps> = ({ ...rest }) => {
+  const { path, currentStep, goToStep } = useLearningPath()
+
+  if (!path) {
+    return <></>
+  }
+
+  return (
+    <div>
+      {path.steps.map((step, index) => (
+        <div
+          className={clsx(
+            "tw-border-0 tw-border-b tw-border-solid tw-border-medusa-border-base dark:tw-border-medusa-border-base-dark",
+            "tw-relative tw-p-1"
+          )}
+          key={index}
+        >
+          <div className={clsx("tw-flex tw-items-center tw-gap-1")}>
+            <div className="tw-w-2 tw-flex-none tw-flex tw-items-center tw-justify-center">
+              {index === currentStep && (
+                <IconCircleDottedLine
+                  className="tw-shadow-active dark:tw-shadow-active-dark tw-rounded-full"
+                  iconColorClassName="tw-stroke-medusa-icon-interactive dark:tw-stroke-medusa-icon-interactive-dark"
+                />
+              )}
+              {index < currentStep && (
+                <IconCheckCircleSolid iconColorClassName="tw-fill-medusa-icon-interactive dark:tw-fill-medusa-icon-interactive-dark" />
+              )}
+              {index > currentStep && <IconCircleMiniSolid />}
+            </div>
+            <span
+              className={clsx(
+                "tw-text-label-regular-plus tw-text-medusa-text-base dark:tw-text-medusa-text-base-dark"
+              )}
+            >
+              {step.title}
+            </span>
+          </div>
+          {index === currentStep && (
+            <div className={clsx("tw-flex tw-items-center tw-gap-1")}>
+              <div className="tw-w-2 tw-flex-none"></div>
+              <div
+                className={clsx(
+                  "tw-text-body-regular tw-text-medusa-text-subtle dark:tw-text-medusa-text-subtle-dark tw-mt-1"
+                )}
+              >
+                {step.descriptionJSX ?? step.description}
+              </div>
+            </div>
+          )}
+          {index < currentStep && (
+            <Link
+              href={step.path}
+              className={clsx(
+                "tw-absolute tw-top-0 tw-left-0 tw-w-full tw-h-full"
+              )}
+              onClick={(e) => {
+                e.preventDefault()
+                goToStep(index)
+              }}
+            />
+          )}
+        </div>
+      ))}
+      <LearningPathStepActions {...rest} />
+    </div>
+  )
+}
+
+export default LearningPathSteps

www/docs/src/components/LearningPath/index.tsx

@@ -0,0 +1,96 @@
+import { useLearningPath } from "@site/src/providers/LearningPath"
+import { useNotifications } from "@site/src/providers/NotificationProvider"
+import { getLearningPath } from "@site/src/utils/learning-paths"
+import clsx from "clsx"
+import React from "react"
+import useBaseUrl from "@docusaurus/useBaseUrl"
+import Button from "../Button"
+import IconCircleMiniSolid from "@site/src/theme/Icon/CircleMiniSolid"
+import LearningPathIcon from "./Icon"
+
+type LearningPathProps = {
+  pathName: string
+  className?: string
+} & React.AllHTMLAttributes<HTMLDivElement>
+
+const LearningPath: React.FC<LearningPathProps> = ({
+  pathName,
+  className = "",
+}) => {
+  const path = getLearningPath(pathName)
+  if (!path) {
+    throw new Error("Learning path does not exist.")
+  }
+  const { startPath, path: currentPath } = useLearningPath()
+  const notificationContext = useNotifications()
+
+  const handleClick = () => {
+    if (notificationContext && currentPath?.notificationId) {
+      notificationContext.removeNotification(currentPath.notificationId)
+    }
+    startPath(path)
+  }
+
+  return (
+    <div
+      className={clsx(
+        "tw-rounded tw-shadow-card-rest dark:tw-shadow-card-rest-dark tw-bg-docs-bg-surface dark:tw-bg-docs-bg-surface-dark tw-mt-1.5 tw-mb-4",
+        className
+      )}
+    >
+      <div
+        className={clsx(
+          "tw-flex tw-items-center tw-gap-1 tw-p-1 tw-border-0 tw-border-b tw-border-solid tw-border-medusa-border-base dark:tw-border-medusa-border-base-dark"
+        )}
+      >
+        <LearningPathIcon />
+        <div className={clsx("tw-flex-auto")}>
+          <span
+            className={clsx(
+              "tw-text-medusa-text-base dark:tw-text-medusa-text-base-dark tw-text-label-large-plus tw-block"
+            )}
+          >
+            {path.label}
+          </span>
+          {path.description && (
+            <span
+              className={clsx(
+                "tw-text-medusa-text-subtle dark:tw-text-medusa-text-subtle-dark tw-text-label-regular tw-mt-[4px] tw-inline-block"
+              )}
+            >
+              {path.description}
+            </span>
+          )}
+        </div>
+        <Button onClick={handleClick} className={clsx("tw-flex-initial")}>
+          Start Path
+        </Button>
+      </div>
+      {path.steps.map((step, index) => (
+        <div
+          className={clsx(
+            "tw-flex tw-items-center tw-p-1 tw-gap-1",
+            index !== path.steps.length - 1 &&
+              "tw-border-0 tw-border-b tw-border-solid tw-border-medusa-border-base dark:tw-border-medusa-border-base-dark"
+          )}
+          key={index}
+        >
+          <div
+            className={clsx("tw-w-3 tw-flex tw-items-center tw-justify-center")}
+          >
+            <IconCircleMiniSolid iconColorClassName="tw-stroke-medusa-icon-muted dark:tw-stroke-medusa-icon-muted-dark" />
+          </div>
+          <span
+            className={clsx(
+              "tw-text-medusa-text-base dark:tw-text-medusa-text-base-dark tw-text-label-regular-plus"
+            )}
+          >
+            {step.title}
+          </span>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+export default LearningPath

www/docs/src/components/Notification/Container/index.tsx

@@ -0,0 +1,61 @@
+import {
+  NotificationItemType,
+  useNotifications,
+} from "@site/src/providers/NotificationProvider"
+import React from "react"
+import NotificationItem from "../Item"
+import { CSSTransition, TransitionGroup } from "react-transition-group"
+import clsx from "clsx"
+
+const NotificationContainer = () => {
+  const { notifications, removeNotification } = useNotifications()
+
+  const handleClose = (notification: NotificationItemType) => {
+    notification.onClose?.()
+    removeNotification(notification.id)
+  }
+
+  const renderFilteredNotifications = (
+    condition: (notificaiton: NotificationItemType) => boolean,
+    className?: string
+  ) => {
+    return (
+      <TransitionGroup className={className}>
+        {notifications.filter(condition).map((notification) => (
+          <CSSTransition
+            key={notification.id}
+            timeout={200}
+            classNames={{
+              enter: "animate__animated animate__slideInRight animate__fastest",
+              exit: "animate__animated animate__slideOutRight animate__fastest",
+            }}
+          >
+            <NotificationItem
+              {...notification}
+              onClose={() => handleClose(notification)}
+              className={clsx(
+                notification.className,
+                "!tw-relative !tw-top-0 !tw-bottom-0 !tw-right-0"
+              )}
+            />
+          </CSSTransition>
+        ))}
+      </TransitionGroup>
+    )
+  }
+
+  return (
+    <>
+      {renderFilteredNotifications(
+        (notification) => notification.placement === "top",
+        "tw-flex tw-fixed tw-flex-col tw-gap-0.5 md:tw-right-1 tw-right-0 md:tw-top-1 tw-top-0 tw-z-[400] md:tw-w-auto tw-w-full"
+      )}
+      {renderFilteredNotifications(
+        (notification) => notification.placement !== "top",
+        "tw-flex tw-flex-col tw-gap-0.5 tw-fixed md:tw-right-1 tw-right-0 md:tw-bottom-1 tw-bottom-0 tw-z-[400] md:tw-w-auto tw-w-full"
+      )}
+    </>
+  )
+}
+
+export default NotificationContainer

www/docs/src/components/Notification/Item/Layout/Default/index.tsx

@@ -0,0 +1,90 @@
+import React from "react"
+import { NotificationItemProps } from "../.."
+import clsx from "clsx"
+import IconInformationCircleSolid from "@site/src/theme/Icon/InformationCircleSolid"
+import IconXCircleSolid from "@site/src/theme/Icon/XCircleSolid"
+import IconExclamationCircleSolid from "@site/src/theme/Icon/ExclamationCircleSolid"
+import IconCheckCircleSolid from "@site/src/theme/Icon/CheckCircleSolid"
+import Button from "@site/src/components/Button"
+
+type NotificationItemLayoutDefaultProps = NotificationItemProps & {
+  handleClose: () => void
+}
+
+const NotificationItemLayoutDefault: React.FC<
+  NotificationItemLayoutDefaultProps
+> = ({
+  type = "info",
+  title = "",
+  text = "",
+  children,
+  isClosable = true,
+  handleClose,
+  CustomIcon,
+}) => {
+  return (
+    <>
+      <div className={clsx("tw-flex tw-gap-1 tw-p-1")}>
+        {type !== "none" && (
+          <div
+            className={clsx(
+              type !== "custom" &&
+                "tw-w-2 tw-flex tw-justify-center tw-items-center"
+            )}
+          >
+            {type === "info" && (
+              <IconInformationCircleSolid iconColorClassName="tw-fill-medusa-support-info dark:tw-fill-medusa-support-info-dark" />
+            )}
+            {type === "error" && (
+              <IconXCircleSolid iconColorClassName="tw-fill-medusa-tag-red-icon dark:tw-fill-medusa-tag-red-icon-dark" />
+            )}
+            {type === "warning" && (
+              <IconExclamationCircleSolid iconColorClassName="tw-fill-medusa-tag-orange-icon dark:tw-fill-medusa-tag-orange-icon-dark" />
+            )}
+            {type === "success" && (
+              <IconCheckCircleSolid iconColorClassName="tw-fill-medusa-tag-green-icon dark:tw-fill-medusa-tag-green-icon-dark" />
+            )}
+            {type === "custom" && CustomIcon}
+          </div>
+        )}
+        <span
+          className={clsx(
+            "tw-text-label-regular-plus",
+            "tw-text-medusa-text-base dark:tw-text-medusa-text-base-dark"
+          )}
+        >
+          {title}
+        </span>
+      </div>
+      {(text || children) && (
+        <div
+          className={clsx(
+            "tw-flex tw-pt-0 tw-pr-1 tw-pb-1.5 tw-pl-1 tw-gap-1",
+            "tw-border-0 tw-border-b tw-border-solid tw-border-medusa-border-base dark:tw-border-medusa-border-base-dark"
+          )}
+        >
+          <div className="tw-w-2 tw-flex-none"></div>
+          <div className={clsx("tw-flex tw-flex-col", children && "tw-gap-1")}>
+            {text && (
+              <span
+                className={clsx(
+                  "tw-text-body-regular tw-text-medusa-text-subtle dark:tw-text-medusa-text-subtle-dark"
+                )}
+              >
+                {text}
+              </span>
+            )}
+            {children}
+          </div>
+        </div>
+      )}
+      {isClosable && (
+        <div className={clsx("tw-p-1 tw-flex tw-justify-end tw-items-center")}>
+          <Button onClick={handleClose}>Close</Button>
+        </div>
+      )}
+    </>
+  )
+}
+
+export default NotificationItemLayoutDefault

www/docs/src/components/Notification/Item/index.tsx

@@ -0,0 +1,63 @@
+import clsx from "clsx"
+import React, { Children, ReactElement, useEffect, useRef } from "react"
+import NotificationItemLayoutDefault from "./Layout/Default"
+
+export type NotificationItemProps = {
+  layout?: "default" | "empty"
+  type?: "info" | "error" | "warning" | "success" | "custom" | "none"
+  CustomIcon?: React.ReactNode
+  title?: string
+  text?: string
+  className?: string
+  children?: ReactElement
+  isClosable?: boolean
+  placement?: "top" | "bottom"
+  show?: boolean
+  setShow?: (value: boolean) => void
+  onClose?: () => void
+} & React.HTMLAttributes<HTMLDivElement>
+
+const Notification = ({
+  className = "",
+  placement = "bottom",
+  show = true,
+  layout = "default",
+  setShow,
+  onClose,
+  children,
+  ...rest
+}: NotificationItemProps) => {
+  const handleClose = () => {
+    setShow?.(false)
+    onClose?.()
+  }
+
+  return (
+    <div
+      className={clsx(
+        "md:tw-max-w-[320px] md:tw-w-[320px] tw-w-full tw-bg-medusa-bg-base dark:tw-bg-medusa-bg-base-dark tw-rounded",
+        "tw-shadow-flyout dark:tw-shadow-flyout-dark",
+        "tw-fixed md:tw-right-1 tw-left-0 tw-block tw-z-[400]",
+        placement === "bottom" && "md:tw-bottom-1 tw-bottom-0",
+        placement === "top" && "md:tw-top-1 tw-top-0",
+        "tw-opacity-100 tw-transition-opacity tw-duration-200 tw-ease-ease",
+        !show && "!tw-opacity-0",
+        className
+      )}
+    >
+      {layout === "default" && (
+        <NotificationItemLayoutDefault {...rest} handleClose={handleClose}>
+          {children}
+        </NotificationItemLayoutDefault>
+      )}
+      {layout === "empty" &&
+        Children.map(children, (child) =>
+          React.cloneElement(child, {
+            onClose: handleClose,
+          })
+        )}
+    </div>
+  )
+}
+
+export default Notification

www/docs/src/components/Rating/index.tsx

@@ -0,0 +1,80 @@
+import { useUser } from "@site/src/providers/User"
+import IconStar from "@site/src/theme/Icon/Star"
+import IconStarSolid from "@site/src/theme/Icon/StarSolid"
+import clsx from "clsx"
+import React, { useRef, useState } from "react"
+
+type RatingProps = {
+  event?: string
+  className?: string
+  onRating?: () => void
+} & React.HTMLAttributes<HTMLDivElement>
+
+const Rating: React.FC<RatingProps> = ({
+  event = "rating",
+  className = "",
+  onRating,
+}) => {
+  const [rating, setRating] = useState(0)
+  const [hoverRating, setHoverRating] = useState(0)
+  const starElms = useRef<HTMLElement[]>([])
+  const starArr = Array.from(Array(5).keys())
+  const { track } = useUser()
+
+  const handleRating = (selectedRating: number) => {
+    if (rating) {
+      return
+    }
+    setHoverRating(0)
+    setRating(selectedRating)
+    for (let i = 0; i < selectedRating; i++) {
+      starElms.current[i].classList.add("animate__animated", "animate__tada")
+    }
+    track(
+      event,
+      {
+        rating: selectedRating,
+      },
+      () => onRating?.()
+    )
+  }
+
+  return (
+    <div className={clsx("tw-flex tw-gap-0.5", className)}>
+      {starArr.map((i) => {
+        const isSelected =
+          (rating !== 0 && rating - 1 >= i) ||
+          (hoverRating !== 0 && hoverRating - 1 >= i)
+        return (
+          <button
+            className="transparent-button"
+            ref={(element) => {
+              if (starElms.current.length - 1 < i) {
+                starElms.current.push(element)
+              }
+            }}
+            key={i}
+            onMouseOver={() => {
+              if (!rating) {
+                setHoverRating(i + 1)
+              }
+            }}
+            onMouseLeave={() => {
+              if (!rating) {
+                setHoverRating(0)
+              }
+            }}
+            onClick={() => handleRating(i + 1)}
+          >
+            {!isSelected && <IconStar />}
+            {isSelected && (
+              <IconStarSolid iconColorClassName="tw-fill-medusa-tag-orange-icon dark:tw-fill-medusa-tag-orange-icon-dark" />
+            )}
+          </button>
+        )
+      })}
+    </div>
+  )
+}
+
+export default Rating

www/docs/src/context/sidebar.ts

@@ -1,14 +0,0 @@
-import { createContext } from "react"
-
-type SidebarContextType = {
-  hasSidebar: boolean
-  hiddenSidebar: boolean
-  setHiddenSidebar: (value: boolean) => void
-  hiddenSidebarContainer: boolean
-  setHiddenSidebarContainer: (value: boolean) => void
-  floatingSidebar: boolean
-  setFloatingSidebar: (value: boolean) => void
-  onCollapse: () => void
-}
-
-export const SidebarContext = createContext<SidebarContextType | null>(null)

www/docs/src/css/_docusaurus.css

@@ -79,7 +79,7 @@ video {
 }
 
 [class*=codeLineNumber] {
-  @apply tw-text-medusa-text-placeholder !tw-pl-0;
+  @apply tw-text-medusa-code-text-muted !tw-pl-0;
 }
 
 .prism-code {
@@ -279,6 +279,6 @@ h1, h2, h3, h4, h5, h6 {
   @apply tw-bg-medusa-bg-highlight dark:tw-bg-medusa-bg-highlight-dark;
 }
 
-.prism-code *::selection {
+.prism-code *::selection, .code-header::selection {
   @apply tw-bg-medusa-code-text-highlight;
 }

www/docs/src/css/_variables.css

@@ -88,7 +88,7 @@
   --rt-color-white: var(--ifm-color-content) !important;
 
   /* Footer */
-  --ifm-footer-color: theme(colors.medusa.text.placeholder.DEFAULT);
+  --ifm-footer-color: theme(colors.medusa.text.muted.DEFAULT);
   --ifm-footer-background-color: transparent;
   --ifm-footer-padding-horizontal: 0;
   --ifm-footer-link-color: var(--ifm-color-content);
@@ -99,12 +99,12 @@
   --docsearch-searchbox-shadow: none !important;
   --docsearch-modal-height: 472px !important;
   --docsearch-modal-background: theme(colors.medusa.bg.base.DEFAULT) !important;
-  --docsearch-modal-shadow: theme(boxShadow.overlay) !important;
+  --docsearch-modal-shadow: theme(boxShadow.modal) !important;
   --docsearch-container-background: theme(colors.medusa.bg.overlay.DEFAULT) !important;
   --docsearch-key-gradient: theme(colors.medusa.bg.component.DEFAULT) !important;
   --docsearch-muted-color: theme(colors.medusa.text.subtle.DEFAULT) !important;
   --docsearch-spacing: 12px theme(spacing[1.5]) !important;
-  --docsearch-highlight-color: theme(colors.medusa.text.placeholder.DEFAULT) !important;
+  --docsearch-highlight-color: theme(colors.medusa.text.muted.DEFAULT) !important;
   --docsearch-text-color: var(--ifm-color-primary) !important;
   --docsearch-hit-background: var(--docsearch-modal-background) !important;
   --docsearch-hit-height: auto !important;
@@ -154,17 +154,17 @@ html[data-theme="dark"] {
   --rt-color-dark: theme(colors.medusa.bg.base.dark) !important;
 
   /* Footer */
-  --ifm-footer-color: theme(colors.medusa.text.placeholder.dark);
+  --ifm-footer-color: theme(colors.medusa.text.muted.dark);
 
   /* Search */
   --docsearch-searchbox-background: theme(colors.medusa.bg.field.dark) !important;
   --docsearch-searchbox-focus-background: theme(colors.medusa.bg.field.hover.dark) !important;
   --docsearch-modal-background: theme(colors.medusa.bg.base.dark) !important;
-  --docsearch-modal-shadow: theme(boxShadow.overlay-dark) !important;
+  --docsearch-modal-shadow: theme(boxShadow.modal-dark) !important;
   --docsearch-container-background: theme(colors.medusa.bg.overlay.dark) !important;
   --docsearch-key-gradient: theme(colors.medusa.bg.component.dark) !important;
   --docsearch-muted-color: theme(colors.medusa.text.subtle.dark) !important;
-  --docsearch-highlight-color: theme(colors.medusa.text.placeholder.dark) !important;
+  --docsearch-highlight-color: theme(colors.medusa.text.muted.dark) !important;
 
   /* Tables */
   --ifm-table-border-color: theme(colors.medusa.border.base.dark);
@@ -189,3 +189,11 @@ html[data-theme="dark"] {
     --docusaurus-announcement-bar-height: 30px;
   }
 }
+
+.alert {
+  --ifm-code-background: theme(colors.medusa.bg.subtle.DEFAULT) !important;
+}
+
+html[data-theme="dark"] .alert {
+  --ifm-code-background: theme(colors.medusa.bg.base.dark) !important;
+}

www/docs/src/css/components/docsearch.css

@@ -22,7 +22,7 @@
 
 .DocSearch-Input {
   @apply !tw-text-body-regular !tw-pl-1;
-  @apply placeholder:tw-text-medusa-text-placeholder dark:placeholder:tw-text-medusa-text-placeholder-dark;
+  @apply placeholder:tw-text-medusa-text-muted dark:placeholder:tw-text-medusa-text-muted-dark;
 }
 
 .DocSearch-Dropdown {
@@ -31,7 +31,7 @@
 }
 
 .DocSearch-Hit-source {
-  @apply !tw-m-0 !tw-text-label-small-plus tw-uppercase tw-text-medusa-text-placeholder dark:tw-text-medusa-text-placeholder-dark;
+  @apply !tw-m-0 !tw-text-label-small-plus tw-uppercase tw-text-medusa-text-muted dark:tw-text-medusa-text-muted-dark;
   @apply tw-border-0 tw-border-b tw-border-solid tw-border-medusa-border-base dark:tw-border-medusa-border-base-dark;
   @apply !tw-py-[10px] !tw-px-1.5;
 }
@@ -178,7 +178,7 @@ html[data-theme="dark"] .DocSearch-Hit[aria-selected=true] .DocSearch-Hit-path {
 }
 
 .DocSearch-Button-Placeholder {
-  @apply tw-text-medusa-text-placeholder dark:tw-text-medusa-text-placeholder-dark;
+  @apply tw-text-medusa-text-muted dark:tw-text-medusa-text-muted-dark;
   @apply !tw-pl-0.5 !tw-text-label-small lg:!tw-block !tw-hidden;
 }
 

www/docs/src/css/components/redocly.css

@@ -45,7 +45,7 @@
 
 
 .redocusaurus h5 + svg {
-  @apply tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark;
+  @apply tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark;
 }
 
 .redocusaurus h2 + div + div > div + div {
@@ -86,14 +86,14 @@
 }
 
 .redocusaurus .react-tabs__tab:not(.react-tabs__tab--selected) {
-  @apply !tw-bg-medusa-button-secondary dark:!tw-bg-medusa-button-secondary-dark;
+  @apply !tw-bg-medusa-button-neutral dark:!tw-bg-medusa-button-neutral-dark;
   @apply !tw-border-medusa-border-base dark:!tw-border-medusa-border-base-dark;
   @apply !tw-text-medusa-text-base dark:!tw-text-medusa-text-base-dark;
 }
 
 .redocusaurus ul > li.react-tabs__tab--selected[aria-selected="true"]:not(.tab-error):not(.tab-success) {
-  @apply !tw-bg-medusa-button-primary dark:!tw-bg-medusa-button-primary-dark;
+  @apply !tw-bg-medusa-button-brand dark:!tw-bg-medusa-button-brand-dark;
-  @apply !tw-border-medusa-button-primary dark:!tw-border-medusa-button-primary-dark;
+  @apply !tw-border-medusa-button-brand dark:!tw-border-medusa-button-brand-dark;
   @apply !tw-text-medusa-text-on-color dark:!tw-text-medusa-text-on-color-dark;
 }
 
@@ -112,13 +112,13 @@
 }
 
 .redocusaurus .tab-error:not(.react-tabs__tab--selected) {
-  @apply !tw-bg-medusa-button-secondary dark:!tw-bg-medusa-button-secondary-dark;
+  @apply !tw-bg-medusa-button-neutral dark:!tw-bg-medusa-button-neutral-dark;
   @apply !tw-border-medusa-border-base dark:!tw-border-medusa-border-base-dark;
   @apply !tw-text-medusa-support-error dark:!tw-text-medusa-support-error-dark;
 }
 
 .redocusaurus .tab-success:not(.react-tabs__tab--selected) {
-  @apply !tw-bg-medusa-button-secondary dark:!tw-bg-medusa-button-secondary-dark;
+  @apply !tw-bg-medusa-button-neutral dark:!tw-bg-medusa-button-neutral-dark;
   @apply !tw-border-medusa-border-base dark:!tw-border-medusa-border-base-dark;
   @apply !tw-text-medusa-support-success dark:!tw-text-medusa-support-success-dark;
 }
@@ -139,12 +139,12 @@
 .redocusaurus [download] {
   @apply !tw-inline-flex tw-flex-row tw-justify-center tw-items-center;
   @apply !tw-py-[6px] !tw-px-[12px] !tw-rounded !tw-cursor-pointer;
-  @apply !tw-bg-medusa-button-secondary dark:!tw-bg-medusa-button-secondary-dark;
+  @apply !tw-bg-medusa-button-neutral dark:!tw-bg-medusa-button-neutral-dark;
-  @apply hover:!tw-bg-medusa-button-secondary-hover dark:hover:!tw-bg-medusa-button-secondary-hover-dark hover:tw-no-underline;
+  @apply hover:!tw-bg-medusa-button-neutral-hover dark:hover:!tw-bg-medusa-button-neutral-hover-dark hover:tw-no-underline;
   @apply !tw-border !tw-border-solid !tw-border-medusa-border-base dark:!tw-border-medusa-border-base-dark;
   @apply !tw-text-label-small-plus !tw-text-medusa-text-base dark:!tw-text-medusa-text-base-dark;
   @apply hover:!tw-text-medusa-text-base dark:hover:!tw-text-medusa-text-base-dark;
-  @apply focus:!tw-shadow-button-focused dark:focus:!tw-shadow-button-focused-dark;
+  @apply focus:!tw-shadow-focus dark:focus:!tw-shadow-focus-dark;
 }
 
 .redocusaurus [role=menuitem] {

www/docs/src/css/components/tooltip.css

@@ -1,6 +1,6 @@
 .react-tooltip {
   @apply !tw-border !tw-border-solid !tw-border-medusa-border-base dark:!tw-border-medusa-border-base-dark;
-  @apply !tw-rounded !tw-text-label-x-small-plus !tw-shadow-overlay dark:!tw-shadow-overlay-dark;
+  @apply !tw-rounded !tw-text-label-x-small-plus !tw-shadow-tooltip dark:!tw-shadow-tooltip-dark;
   @apply !tw-py-0.4 !tw-px-1 lg:tw-block tw-hidden;
 }
 

www/docs/src/css/custom.css

@@ -49,7 +49,7 @@
   }
 
   .sidebar-group-divider {
-    @apply tw-pb-[6px] tw-uppercase tw-text-medusa-text-placeholder dark:tw-text-medusa-text-placeholder-dark tw-text-label-x-small-plus;
+    @apply tw-pb-[6px] tw-uppercase tw-text-medusa-text-muted dark:tw-text-medusa-text-muted-dark tw-text-label-x-small-plus;
     @apply first:tw-pt-[6px] [&:not(:first-child)]:!tw-pt-1;
   }
   
@@ -98,7 +98,7 @@
   }
 
   .code-header {
-    @apply tw-py-[12px] tw-px-1 tw-bg-medusa-code-tabs-bg;
+    @apply tw-py-[12px] tw-px-1 tw-bg-medusa-code-tabs-bg tw-text-medusa-code-text-subtle;
     @apply tw-flex tw-justify-between tw-items-center;
     @apply tw-rounded-tl tw-rounded-tr tw-rounded-br-none tw-rounded-bl-none tw-border-b-0;
     @apply tw-border tw-border-solid tw-border-medusa-code-block-border tw-border-b-0;
@@ -117,21 +117,37 @@
     @apply tw-py-[6px] tw-px-[12px] tw-rounded tw-cursor-pointer;
     @apply tw-bg-button-neutral dark:tw-bg-button-neutral-dark;
     @apply hover:!tw-bg-no-image hover:tw-bg-medusa-button-neutral-hover dark:hover:tw-bg-medusa-button-neutral-hover-dark hover:tw-no-underline;
-    @apply active:!tw-bg-no-image active:tw-bg-medusa-button-neutral-pressed dark:active:tw-bg-medusa-button-neutral-pressed;
+    @apply active:!tw-bg-no-image active:tw-bg-medusa-button-neutral-pressed dark:active:tw-bg-medusa-button-neutral-pressed-dark;
-    @apply focus:tw-shadow-neutral-button-focused dark:focus:tw-shadow-neutral-button-focused-dark;
+    @apply focus:tw-shadow-focus dark:focus:tw-shadow-focus-dark;
     @apply disabled:!tw-bg-no-image disabled:tw-bg-medusa-button-disabled dark:disabled:tw-bg-medusa-button-disabled-dark;
     @apply tw-border tw-border-solid tw-border-medusa-border-neutral-buttons dark:tw-border-medusa-border-neutral-buttons-dark;
     @apply tw-text-label-small-plus tw-text-medusa-text-base dark:tw-text-medusa-text-base-dark;
     @apply hover:tw-text-medusa-text-base dark:hover:tw-text-medusa-text-base-dark;
   }
 
+  .btn-inverted {
+    @apply tw-inline-flex tw-flex-row tw-justify-center tw-items-center;
+    @apply tw-py-[6px] tw-px-[12px] tw-rounded tw-cursor-pointer;
+    @apply tw-bg-button-inverted dark:tw-bg-button-inverted-dark;
+    @apply hover:!tw-bg-no-image hover:tw-bg-medusa-button-inverted-hover dark:hover:tw-bg-medusa-button-inverted-hover-dark hover:tw-no-underline;
+    @apply active:!tw-bg-no-image active:tw-bg-medusa-button-inverted-pressed dark:active:tw-bg-medusa-button-inverted-pressed-dark;
+    @apply focus:tw-shadow-focus dark:focus:tw-shadow-focus-dark;
+    @apply disabled:!tw-bg-no-image disabled:tw-bg-medusa-button-disabled dark:disabled:tw-bg-medusa-button-disabled-dark;
+    @apply tw-text-label-small-plus tw-text-medusa-text-on-color dark:tw-text-medusa-text-on-inverted-dark;
+    @apply tw-border-transparent tw-border;
+  }
+
   .navbar-action-icon-item {
     @apply tw-bg-button-neutral dark:tw-bg-button-neutral-dark hover:!tw-bg-no-image active:!tw-bg-no-image hover:tw-bg-medusa-button-neutral-hover dark:hover:tw-bg-medusa-button-neutral-hover-dark;
     @apply active:tw-bg-medusa-button-neutral-pressed dark:active:tw-bg-medusa-button-neutral-pressed-dark;
-    @apply focus:tw-shadow-neutral-button-focused dark:focus:tw-shadow-neutral-button-focused-dark;
+    @apply focus:tw-shadow-focus dark:focus:tw-shadow-focus-dark;
     @apply tw-border tw-border-solid tw-border-medusa-border-neutral-buttons dark:tw-border-medusa-border-neutral-buttons-dark tw-rounded;
     @apply tw-w-2 tw-h-2 tw-flex tw-justify-center tw-items-center tw-cursor-pointer;
   }
+
+  .transparent-button {
+    @apply tw-bg-transparent tw-border-0 tw-text-inherit tw-cursor-pointer tw-p-0;
+  }
 }
 
 @layer utilities {

www/docs/src/hooks/use-current-learning-path.tsx

@@ -0,0 +1,94 @@
+import React, { useEffect } from "react"
+import { useLearningPath } from "../providers/LearningPath"
+import { useNotifications } from "../providers/NotificationProvider"
+import LearningPathSteps from "../components/LearningPath/Steps"
+import LearningPathFinish from "../components/LearningPath/Finish"
+import LearningPathIcon from "../components/LearningPath/Icon"
+
+const useCurrentLearningPath = () => {
+  const { path, currentStep, updatePath, endPath } = useLearningPath()
+  const step = path?.steps[currentStep]
+  const {
+    addNotification,
+    generateId,
+    removeNotification,
+    updateNotification,
+  } = useNotifications()
+
+  // used when a notification closed (finished or not)
+  const handleClose = (notificationId: string, shouldEndPath = true) => {
+    if (shouldEndPath) {
+      setTimeout(() => {
+        endPath()
+      }, 500)
+    }
+    removeNotification(notificationId)
+  }
+
+  // used when the learning path is completely finished
+  // shows the finish step, if the path has any
+  const handleFinish = (notificationId: string) => {
+    if (path.finish) {
+      updateNotification(notificationId, {
+        title: path.finish.step.title,
+        text: path.finish.step.description,
+        type: "custom",
+        layout: "default",
+        CustomIcon: (
+          <LearningPathIcon
+            className="!tw-w-2 !tw-h-2"
+            imgClassName="!tw-w-1.5 !tw-h-1.5"
+          />
+        ),
+        children: (
+          <LearningPathFinish
+            {...path.finish}
+            onRating={() =>
+              setTimeout(() => {
+                handleClose(notificationId, false)
+              }, 1500)
+            }
+          />
+        ),
+      })
+      endPath()
+    } else {
+      handleClose(notificationId)
+    }
+  }
+
+  const LearningStep = (notificationId: string) => {
+    return <LearningPathSteps onFinish={() => handleFinish(notificationId)} />
+  }
+
+  // create a notification when a path is initialized
+  useEffect(() => {
+    if (path && !path.notificationId) {
+      const id = generateId()
+
+      addNotification({
+        title: path.label,
+        text: step?.description,
+        onClose: () => handleClose(id),
+        layout: "empty",
+        id,
+        children: LearningStep(id),
+      })
+      updatePath({
+        notificationId: id,
+      })
+    }
+  }, [path])
+
+  // update an existing notification when the step changes
+  useEffect(() => {
+    if (path && path.notificationId && step) {
+      updateNotification(path.notificationId, {
+        text: step?.description,
+        children: LearningStep(path.notificationId),
+      })
+    }
+  }, [step])
+}
+
+export default useCurrentLearningPath

www/docs/src/hooks/use-onboarding.tsx

@@ -0,0 +1,37 @@
+import React, { useEffect, useState } from "react"
+import { useQueryStringValue } from "@docusaurus/theme-common/internal"
+import { useNotifications } from "../providers/NotificationProvider"
+import Rating from "../components/Rating"
+import { useUser } from "../providers/User"
+
+const useOnboarding = () => {
+  const isOnboarding = useQueryStringValue("ref") === "onboarding"
+  const [showNotification, setShowNotification] = useState(isOnboarding)
+  const { addNotification, removeNotification, generateId } = useNotifications()
+  const { track } = useUser()
+
+  useEffect(() => {
+    if (isOnboarding) {
+      track("finished_onboarding")
+      const id = generateId()
+      addNotification({
+        title: "Thank you for installing Medusa!",
+        text: "Please rate your onboarding experience",
+        type: "success",
+        show: showNotification,
+        setShow: setShowNotification,
+        id,
+        children: (
+          <Rating
+            event="rating_onboarding"
+            onRating={() => {
+              setTimeout(() => removeNotification(id), 1500)
+            }}
+          />
+        ),
+      })
+    }
+  }, [])
+}
+
+export default useOnboarding

www/docs/src/providers/LearningPath/index.tsx

@@ -0,0 +1,256 @@
+import useIsBrowser from "@docusaurus/useIsBrowser"
+import { getLearningPath } from "@site/src/utils/learning-paths"
+import React, { createContext, useContext, useEffect, useState } from "react"
+import { useHistory } from "@docusaurus/router"
+import { LearningPathFinishType } from "@site/src/components/LearningPath/Finish"
+import { useUser } from "../User"
+
+export type LearningPathType = {
+  name: string
+  label: string
+  description?: string
+  steps: LearningPathStepType[]
+  finish?: LearningPathFinishType
+  notificationId?: string
+}
+
+export type LearningPathStepType = {
+  title?: string
+  description?: string
+  descriptionJSX?: JSX.Element
+  path?: string
+}
+
+export type LearningPathContextType = {
+  path?: LearningPathType
+  setPath: (value: LearningPathType) => void
+  currentStep: number
+  setCurrentStep: (value: number) => void
+  startPath: (path: LearningPathType) => void
+  updatePath: (data: Pick<LearningPathType, "notificationId">) => void
+  endPath: () => void
+  nextStep: () => void
+  hasNextStep: () => boolean
+  previousStep: () => void
+  hasPreviousStep: () => boolean
+  goToStep: (stepIndex: number) => void
+  isCurrentPath: () => boolean
+  goToCurrentPath: () => void
+}
+
+type LearningPathProviderProps = {
+  children?: React.ReactNode
+}
+
+const LearningPathContext = createContext<LearningPathContextType | null>(null)
+
+const LearningPathProvider: React.FC<LearningPathProviderProps> = ({
+  children,
+}) => {
+  const [path, setPath] = useState<LearningPathType | null>(null)
+  const [currentStep, setCurrentStep] = useState(-1)
+  const isBrowser = useIsBrowser()
+  const history = useHistory()
+  const { track } = useUser()
+
+  const startPath = (path: LearningPathType) => {
+    setPath(path)
+    setCurrentStep(-1)
+    if (isBrowser) {
+      localStorage.setItem(
+        "learning-path",
+        JSON.stringify({
+          pathName: path.name,
+          currentStep: -1,
+        })
+      )
+    }
+
+    track(`learning_path_${path.name}`, {
+      url: history.location.pathname,
+      state: `start`,
+    })
+  }
+
+  useEffect(() => {
+    if (path && currentStep === -1) {
+      nextStep()
+    }
+  }, [path])
+
+  const endPath = () => {
+    const didFinish = currentStep === path.steps.length - 1
+    const reachedIndex = currentStep === -1 ? 0 : currentStep
+    track(`learning_path_${path.name}`, {
+      url: history.location.pathname,
+      state: !didFinish ? `closed` : `end`,
+      reachedStep:
+        path.steps[reachedIndex]?.title ||
+        path.steps[reachedIndex]?.description ||
+        path.steps[reachedIndex]?.descriptionJSX ||
+        reachedIndex,
+    })
+    setPath(null)
+    setCurrentStep(-1)
+    if (isBrowser) {
+      localStorage.removeItem("learning-path")
+    }
+  }
+
+  const hasNextStep = () => currentStep !== path?.steps.length - 1
+
+  const nextStep = () => {
+    if (!path || !hasNextStep()) {
+      return
+    }
+    const nextStepIndex = currentStep + 1
+    setCurrentStep(nextStepIndex)
+    const newPath = path.steps[nextStepIndex].path
+    if (isBrowser) {
+      localStorage.setItem(
+        "learning-path",
+        JSON.stringify({
+          pathName: path.name,
+          currentStep: nextStepIndex,
+        })
+      )
+    }
+    if (history.location.pathname !== newPath) {
+      history.push(newPath)
+    }
+  }
+
+  const hasPreviousStep = () => currentStep > 0
+
+  const previousStep = () => {
+    if (!path || !hasPreviousStep()) {
+      return
+    }
+
+    const previousStepIndex = currentStep - 1
+    setCurrentStep(previousStepIndex)
+    const newPath = path.steps[previousStepIndex].path
+    if (isBrowser) {
+      localStorage.setItem(
+        "learning-path",
+        JSON.stringify({
+          pathName: path.name,
+          currentStep: previousStepIndex,
+        })
+      )
+    }
+    if (history.location.pathname !== newPath) {
+      history.push(newPath)
+    }
+  }
+
+  const goToStep = (stepIndex: number) => {
+    if (!path || stepIndex >= path.steps.length) {
+      return
+    }
+
+    setCurrentStep(stepIndex)
+    const newPath = path.steps[stepIndex].path
+    if (isBrowser) {
+      localStorage.setItem(
+        "learning-path",
+        JSON.stringify({
+          pathName: path.name,
+          currentStep: stepIndex,
+        })
+      )
+    }
+    if (history.location.pathname !== newPath) {
+      history.push(newPath)
+    }
+  }
+
+  const isCurrentPath = () => {
+    if (!path || currentStep === -1) {
+      return false
+    }
+
+    return history.location.pathname === path.steps[currentStep].path
+  }
+
+  const goToCurrentPath = () => {
+    if (!path || currentStep === -1) {
+      return
+    }
+
+    history.push(path.steps[currentStep].path)
+  }
+
+  const updatePath = (data: Pick<LearningPathType, "notificationId">) => {
+    setPath({
+      ...path,
+      ...data,
+    })
+  }
+
+  const initPath = () => {
+    if (isBrowser) {
+      // give query parameters higher precedence over local storage
+      const queryPathName = new URLSearchParams(history.location.search).get(
+        "path"
+      )
+      const queryPath = getLearningPath(queryPathName)
+      if (queryPath) {
+        startPath(queryPath)
+      } else {
+        const storedPath = localStorage.getItem("learning-path")
+        if (storedPath) {
+          const storedPathParsed = JSON.parse(storedPath)
+          const currentPath = getLearningPath(storedPathParsed?.pathName)
+          if (currentPath) {
+            setPath(currentPath)
+            setCurrentStep(storedPathParsed?.currentStep || 0)
+          }
+        }
+      }
+    }
+  }
+
+  useEffect(() => {
+    if (isBrowser && !path) {
+      initPath()
+    }
+  }, [isBrowser])
+
+  return (
+    <LearningPathContext.Provider
+      value={{
+        path,
+        setPath,
+        currentStep,
+        setCurrentStep,
+        startPath,
+        updatePath,
+        endPath,
+        nextStep,
+        hasNextStep,
+        previousStep,
+        hasPreviousStep,
+        goToStep,
+        isCurrentPath,
+        goToCurrentPath,
+      }}
+    >
+      {children}
+    </LearningPathContext.Provider>
+  )
+}
+
+export default LearningPathProvider
+
+export const useLearningPath = () => {
+  const context = useContext(LearningPathContext)
+
+  if (!context) {
+    throw new Error(
+      "useLearningPath must be used within a LearningPathProvider"
+    )
+  }
+
+  return context
+}

www/docs/src/providers/NotificationProvider/index.tsx

@@ -0,0 +1,134 @@
+import React, { createContext, useContext, useReducer } from "react"
+import { NotificationItemProps } from "@site/src/components/Notification/Item"
+import { v4 as uuid4 } from "uuid"
+import NotificationContainer from "@site/src/components/Notification/Container"
+
+export type NotificationItemType = {
+  id?: string
+} & NotificationItemProps
+
+type NotificationContextType = {
+  notifications: NotificationItemType[]
+  addNotification: (value: NotificationItemType) => void
+  generateId: () => string
+  removeNotification: (id: string) => void
+  updateNotification: (
+    id: string,
+    updatedData: Partial<Omit<NotificationItemType, "id">>
+  ) => void
+}
+
+type NotificationProviderProps = {
+  children?: React.ReactNode
+}
+
+enum NotificationReducerActionTypes {
+  ADD = "add",
+  REMOVE = "remove",
+  UPDATE = "update",
+}
+
+type NotificationReducerAction =
+  | {
+      type: NotificationReducerActionTypes.ADD
+      notification: NotificationItemType
+    }
+  | {
+      type: NotificationReducerActionTypes.REMOVE
+      id: string
+    }
+  | {
+      type: NotificationReducerActionTypes.UPDATE
+      id: string
+      updatedData: Partial<Omit<NotificationItemType, "id">>
+    }
+
+const notificationReducer = (
+  state: NotificationItemType[],
+  action: NotificationReducerAction
+) => {
+  switch (action.type) {
+    case NotificationReducerActionTypes.ADD:
+      return [...state, action.notification]
+    case NotificationReducerActionTypes.REMOVE:
+      return state.filter((notification) => notification.id !== action.id)
+    case NotificationReducerActionTypes.UPDATE:
+      return state.map((notification) => {
+        if (notification.id === action.id) {
+          return {
+            ...notification,
+            ...action.updatedData,
+          }
+        }
+
+        return notification
+      })
+    default:
+      return state
+  }
+}
+
+const NotificationContext = createContext<NotificationContextType | null>(null)
+
+const NotificationProvider: React.FC<NotificationProviderProps> = ({
+  children,
+}) => {
+  const [notifications, dispatch] = useReducer(notificationReducer, [])
+
+  const generateId = () => uuid4()
+
+  const addNotification = (notification: NotificationItemType) => {
+    if (!notification.id) {
+      notification.id = generateId()
+    }
+    dispatch({
+      type: NotificationReducerActionTypes.ADD,
+      notification,
+    })
+  }
+
+  const updateNotification = (
+    id: string,
+    updatedData: Partial<Omit<NotificationItemType, "id">>
+  ) => {
+    dispatch({
+      type: NotificationReducerActionTypes.UPDATE,
+      id,
+      updatedData,
+    })
+  }
+
+  const removeNotification = (id: string) => {
+    dispatch({
+      type: NotificationReducerActionTypes.REMOVE,
+      id,
+    })
+  }
+
+  return (
+    <NotificationContext.Provider
+      value={{
+        notifications,
+        addNotification,
+        generateId,
+        removeNotification,
+        updateNotification,
+      }}
+    >
+      {children}
+      <NotificationContainer />
+    </NotificationContext.Provider>
+  )
+}
+
+export default NotificationProvider
+
+export const useNotifications = () => {
+  const context = useContext(NotificationContext)
+
+  if (!context) {
+    console.warn("useNotifications must be used within a NotificationProvider")
+  }
+
+  return context
+}

www/docs/src/providers/User/index.tsx

@@ -0,0 +1,90 @@
+import useIsBrowser from "@docusaurus/useIsBrowser"
+import React, { createContext, useContext, useEffect, useState } from "react"
+import uuid from "react-uuid"
+
+type UserContextType = {
+  id: string
+  track: (
+    event: string,
+    options?: Record<string, any>,
+    callback?: () => void
+  ) => void
+}
+
+const UserContext = createContext<UserContextType | null>(null)
+
+type UserProviderProps = {
+  children?: React.ReactNode
+}
+
+const UserProvider: React.FC<UserProviderProps> = ({ children }) => {
+  const [id, setId] = useState<string>("")
+  const isBrowser = useIsBrowser()
+
+  const initId = () => {
+    if (!id.length) {
+      if (isBrowser) {
+        const storedId = localStorage.getItem("ajs_anonymous_id")
+        if (storedId) {
+          setId(storedId)
+        } else {
+          const generatedId = uuid()
+          localStorage.setItem("ajs_anonymous_id", generatedId)
+          setId(generatedId)
+        }
+      }
+    }
+  }
+
+  const track = (
+    event: string,
+    options?: Record<string, any>,
+    callback?: () => void
+  ) => {
+    if (isBrowser) {
+      if (window.analytics) {
+        window.analytics.track(
+          event,
+          {
+            ...options,
+            uuid: id,
+            anonymousId: id,
+          },
+          callback
+        )
+      } else if (callback) {
+        console.warn(
+          "Segment is either not installed or not configured. Simulating success..."
+        )
+        callback()
+      }
+    }
+  }
+
+  useEffect(() => {
+    initId()
+  }, [isBrowser])
+
+  return (
+    <UserContext.Provider
+      value={{
+        id,
+        track,
+      }}
+    >
+      {children}
+    </UserContext.Provider>
+  )
+}
+
+export default UserProvider
+
+export const useUser = () => {
+  const context = useContext(UserContext)
+
+  if (!context) {
+    throw new Error("useUser must be used within a UserProvider")
+  }
+
+  return context
+}

www/docs/src/theme/Admonition/index.tsx

@@ -2,68 +2,34 @@ import React, { type ReactNode } from "react"
 import clsx from "clsx"
 import Translate from "@docusaurus/Translate"
 import type { Props } from "@theme/Admonition"
+import IconInformationCircleSolid from "../Icon/InformationCircleSolid"
+import IconLightBulbSolid from "../Icon/LightBulbSolid"
+import IconExclamationCircleSolid from "../Icon/ExclamationCircleSolid"
 
 function NoteIcon() {
   return (
-    <svg
+    <IconInformationCircleSolid
-      width={20}
-      height={20}
-      viewBox="0 0 20 20"
-      fill="none"
-      xmlns="http://www.w3.org/2000/svg"
       className="tw-inline-block tw-mr-[2px]"
-    >
+      iconColorClassName="tw-fill-medusa-support-info dark:tw-fill-medusa-support-info-dark"
-      <path
-        fillRule="evenodd"
-        clipRule="evenodd"
-        d="M18 10C18 12.1217 17.1571 14.1566 15.6569 15.6569C14.1566 17.1571 12.1217 18 10 18C7.87827 18 5.84344 17.1571 4.34315 15.6569C2.84285 14.1566 2 12.1217 2 10C2 7.87827 2.84285 5.84344 4.34315 4.34315C5.84344 2.84285 7.87827 2 10 2C12.1217 2 14.1566 2.84285 15.6569 4.34315C17.1571 5.84344 18 7.87827 18 10ZM11 6C11 6.26522 10.8946 6.51957 10.7071 6.70711C10.5196 6.89464 10.2652 7 10 7C9.73478 7 9.48043 6.89464 9.29289 6.70711C9.10536 6.51957 9 6.26522 9 6C9 5.73478 9.10536 5.48043 9.29289 5.29289C9.48043 5.10536 9.73478 5 10 5C10.2652 5 10.5196 5.10536 10.7071 5.29289C10.8946 5.48043 11 5.73478 11 6ZM9 9C8.80109 9 8.61032 9.07902 8.46967 9.21967C8.32902 9.36032 8.25 9.55109 8.25 9.75C8.25 9.94891 8.32902 10.1397 8.46967 10.2803C8.61032 10.421 8.80109 10.5 9 10.5H9.253C9.29041 10.5 9.32734 10.5084 9.36106 10.5246C9.39479 10.5408 9.42445 10.5643 9.44787 10.5935C9.47128 10.6227 9.48785 10.6567 9.49636 10.6932C9.50486 10.7296 9.50508 10.7675 9.497 10.804L9.038 12.87C8.98108 13.1259 8.98237 13.3913 9.04179 13.6466C9.10121 13.902 9.21723 14.1407 9.38129 14.3452C9.54535 14.5496 9.75325 14.7146 9.98963 14.828C10.226 14.9413 10.4848 15.0001 10.747 15H11C11.1989 15 11.3897 14.921 11.5303 14.7803C11.671 14.6397 11.75 14.4489 11.75 14.25C11.75 14.0511 11.671 13.8603 11.5303 13.7197C11.3897 13.579 11.1989 13.5 11 13.5H10.747C10.7096 13.5 10.6727 13.4916 10.6389 13.4754C10.6052 13.4592 10.5755 13.4357 10.5521 13.4065C10.5287 13.3773 10.5121 13.3433 10.5036 13.3068C10.4951 13.2704 10.4949 13.2325 10.503 13.196L10.962 11.13C11.0189 10.8741 11.0176 10.6087 10.9582 10.3534C10.8988 10.098 10.7828 9.8593 10.6187 9.65483C10.4547 9.45036 10.2468 9.28536 10.0104 9.17201C9.77398 9.05867 9.51515 8.99989 9.253 9H9Z"
-        className="tw-fill-medusa-support-info dark:tw-fill-medusa-support-info-dark"
     />
-    </svg>
   )
 }
 
 function TipIcon() {
   return (
-    <svg
+    <IconLightBulbSolid
-      width={20}
-      height={20}
-      viewBox="0 0 20 20"
-      fill="none"
-      xmlns="http://www.w3.org/2000/svg"
       className="tw-inline-block tw-mr-[2px]"
-    >
+      iconColorClassName="tw-fill-medusa-support-warning dark:tw-fill-medusa-support-warning-dark"
-      <path
-        d="M10.0002 1.81238C8.6789 1.81208 7.39444 2.24761 6.34586 3.05146C5.29727 3.85532 4.54312 4.9826 4.20028 6.2586C3.85744 7.5346 3.94507 8.88806 4.44958 10.1092C4.95409 11.3303 5.84731 12.351 6.99079 13.0129C7.49005 13.3026 7.80226 13.7465 7.81609 14.1941C7.81991 14.314 7.86311 14.4293 7.93901 14.5221C8.01492 14.615 8.1193 14.6803 8.23602 14.7079C8.4922 14.7683 8.75274 14.8156 9.01766 14.8498C9.25273 14.8797 9.45432 14.6912 9.45432 14.4539V11.0617C9.22435 11.0364 8.99647 10.9948 8.77239 10.9373C8.70296 10.9194 8.63773 10.888 8.58042 10.8449C8.52311 10.8019 8.47485 10.7479 8.43839 10.6862C8.40193 10.6244 8.37798 10.5561 8.36792 10.4851C8.35786 10.4142 8.36189 10.3419 8.37976 10.2724C8.39763 10.203 8.429 10.1378 8.47209 10.0805C8.51517 10.0232 8.56912 9.9749 8.63085 9.93844C8.69259 9.90198 8.7609 9.87804 8.83189 9.86798C8.90288 9.85792 8.97515 9.86194 9.04458 9.87981C9.67139 10.0414 10.3289 10.0414 10.9557 9.87981C11.0259 9.8596 11.0993 9.85366 11.1718 9.86235C11.2443 9.87103 11.3143 9.89416 11.3776 9.93037C11.441 9.96658 11.4965 10.0151 11.5408 10.0731C11.585 10.1312 11.6172 10.1975 11.6354 10.2682C11.6536 10.3388 11.6575 10.4124 11.6468 10.4846C11.636 10.5568 11.6109 10.6261 11.5729 10.6885C11.5349 10.7508 11.4848 10.8048 11.4255 10.8474C11.3663 10.8901 11.2991 10.9204 11.2279 10.9365C11.0039 10.9944 10.776 11.0362 10.546 11.0617V14.4532C10.546 14.6912 10.7476 14.8797 10.9827 14.8498C11.2476 14.8156 11.5081 14.7683 11.7643 14.7079C11.881 14.6803 11.9854 14.615 12.0613 14.5221C12.1372 14.4293 12.1804 14.314 12.1842 14.1941C12.1988 13.7465 12.5103 13.3026 13.0095 13.0129C14.153 12.351 15.0462 11.3303 15.5507 10.1092C16.0552 8.88806 16.1429 7.5346 15.8 6.2586C15.4572 4.9826 14.703 3.85532 13.6545 3.05146C12.6059 2.24761 11.3214 1.81208 10.0002 1.81238Z"
-        className="tw-fill-medusa-support-warning dark:tw-fill-medusa-support-warning-dark"
     />
-      <path
-        fillRule="evenodd"
-        clipRule="evenodd"
-        d="M7.82589 15.7493C7.83925 15.6788 7.86637 15.6117 7.90568 15.5517C7.94499 15.4918 7.99573 15.4401 8.05501 15.3998C8.11428 15.3594 8.18092 15.3312 8.25112 15.3166C8.32132 15.302 8.39371 15.3014 8.46415 15.3148C9.47884 15.5073 10.5207 15.5073 11.5354 15.3148C11.6067 15.2991 11.6804 15.2978 11.7522 15.3111C11.824 15.3244 11.8923 15.352 11.9533 15.3922C12.0142 15.4324 12.0665 15.4844 12.107 15.5452C12.1474 15.6059 12.1753 15.6742 12.189 15.7459C12.2026 15.8176 12.2017 15.8914 12.1863 15.9627C12.171 16.0341 12.1414 16.1017 12.0995 16.1614C12.0576 16.2212 12.0041 16.2719 11.9422 16.3106C11.8803 16.3493 11.8112 16.3752 11.7392 16.3868C10.5898 16.6049 9.40971 16.6049 8.26037 16.3868C8.11825 16.3598 7.99266 16.2775 7.91119 16.1579C7.82973 16.0384 7.79904 15.8914 7.82589 15.7493ZM8.36517 17.5279C8.37262 17.4566 8.39404 17.3875 8.42821 17.3245C8.46238 17.2615 8.50863 17.2058 8.56432 17.1606C8.62001 17.1155 8.68404 17.0818 8.75277 17.0614C8.82149 17.041 8.89357 17.0343 8.96486 17.0418C9.65293 17.1137 10.3466 17.1137 11.0347 17.0418C11.1787 17.0267 11.3227 17.0695 11.4352 17.1607C11.5477 17.2518 11.6193 17.384 11.6344 17.5279C11.6494 17.6719 11.6067 17.816 11.5155 17.9285C11.4243 18.0409 11.2922 18.1126 11.1482 18.1276C10.3847 18.2076 9.61487 18.2076 8.85133 18.1276C8.78003 18.1202 8.7109 18.0988 8.64787 18.0646C8.58485 18.0304 8.52918 17.9842 8.48404 17.9285C8.43889 17.8728 8.40516 17.8088 8.38476 17.74C8.36437 17.6713 8.35771 17.5992 8.36517 17.5279Z"
-        className="tw-fill-medusa-support-warning dark:tw-fill-medusa-support-warning-dark"
-      />
-    </svg>
   )
 }
 
 function DangerIcon() {
   return (
-    <svg
+    <IconExclamationCircleSolid
-      width={20}
-      height={20}
-      viewBox="0 0 20 20"
-      fill="none"
-      xmlns="http://www.w3.org/2000/svg"
       className="tw-inline-block tw-mr-[2px]"
-    >
+      iconColorClassName="tw-fill-medusa-support-error dark:tw-fill-medusa-support-error-dark"
-      <path
-        fillRule="evenodd"
-        clipRule="evenodd"
-        d="M18 10C18 12.1217 17.1571 14.1566 15.6569 15.6569C14.1566 17.1571 12.1217 18 10 18C7.87827 18 5.84344 17.1571 4.34315 15.6569C2.84285 14.1566 2 12.1217 2 10C2 7.87827 2.84285 5.84344 4.34315 4.34315C5.84344 2.84285 7.87827 2 10 2C12.1217 2 14.1566 2.84285 15.6569 4.34315C17.1571 5.84344 18 7.87827 18 10ZM10 5C10.1989 5 10.3897 5.07902 10.5303 5.21967C10.671 5.36032 10.75 5.55109 10.75 5.75V10.25C10.75 10.4489 10.671 10.6397 10.5303 10.7803C10.3897 10.921 10.1989 11 10 11C9.80109 11 9.61032 10.921 9.46967 10.7803C9.32902 10.6397 9.25 10.4489 9.25 10.25V5.75C9.25 5.55109 9.32902 5.36032 9.46967 5.21967C9.61032 5.07902 9.80109 5 10 5ZM10 15C10.2652 15 10.5196 14.8946 10.7071 14.7071C10.8946 14.5196 11 14.2652 11 14C11 13.7348 10.8946 13.4804 10.7071 13.2929C10.5196 13.1054 10.2652 13 10 13C9.73478 13 9.48043 13.1054 9.29289 13.2929C9.10536 13.4804 9 13.7348 9 14C9 14.2652 9.10536 14.5196 9.29289 14.7071C9.48043 14.8946 9.73478 15 10 15Z"
-        className="tw-fill-medusa-support-error dark:tw-fill-medusa-support-error-dark"
     />
-    </svg>
   )
 }
 

www/docs/src/theme/AnnouncementBar/CloseButton/index.tsx

@@ -26,7 +26,7 @@ export default function AnnouncementBarCloseButton(
         width={20}
         height={20}
         strokeWidth={1.5}
-        iconColorClassName="tw-stroke-medusa-icon-placeholder dark:tw-stroke-medusa-icon-placeholder-dark"
+        iconColorClassName="tw-stroke-medusa-icon-muted dark:tw-stroke-medusa-icon-muted-dark"
       />
     </button>
   )

www/docs/src/theme/ApiDoc/index.tsx

@@ -0,0 +1,17 @@
+import React from "react"
+import ApiDoc from "@theme-original/ApiDoc"
+import type { ApiDocProps } from "@theme-original/ApiDoc"
+import type { WrapperProps } from "@docusaurus/types"
+import UserProvider from "@site/src/providers/User"
+
+type Props = WrapperProps<typeof ApiDocProps>
+
+export default function ApiDocWrapper(props: Props): JSX.Element {
+  return (
+    <>
+      <UserProvider>
+        <ApiDoc {...props} />
+      </UserProvider>
+    </>
+  )
+}

www/docs/src/theme/DocItem/Content/index.tsx

@@ -0,0 +1,69 @@
+import React from "react"
+import clsx from "clsx"
+import { ThemeClassNames } from "@docusaurus/theme-common"
+import { useDoc } from "@docusaurus/theme-common/internal"
+import Heading from "@theme/Heading"
+import MDXContent from "@theme/MDXContent"
+import type { Props } from "@theme/DocItem/Content"
+import { DocContextValue } from "@medusajs/docs"
+import Badge from "@site/src/components/Badge"
+
+/**
+ Title can be declared inside md content or declared through
+ front matter and added manually. To make both cases consistent,
+ the added title is added under the same div.markdown block
+ See https://github.com/facebook/docusaurus/pull/4882#issuecomment-853021120
+
+ We render a "synthetic title" if:
+ - user doesn't ask to hide it with front matter
+ - the markdown content does not already contain a top-level h1 heading
+*/
+function useSyntheticTitle(): string | null {
+  const { metadata, frontMatter, contentTitle } = useDoc()
+  const shouldRender =
+    !frontMatter.hide_title && typeof contentTitle === "undefined"
+  if (!shouldRender) {
+    return null
+  }
+  return metadata.title
+}
+
+export default function DocItemContent({ children }: Props): JSX.Element {
+  const {
+    frontMatter: { badge },
+  } = useDoc() as DocContextValue
+  const syntheticTitle = useSyntheticTitle()
+
+  return (
+    <div className={clsx(ThemeClassNames.docs.docMarkdown, "markdown")}>
+      {syntheticTitle && (
+        <header
+          className={clsx(
+            badge && "md:tw-flex md:tw-items-center md:tw-gap-0.5 tw-mb-2"
+          )}
+        >
+          <Heading as="h1" className="!tw-mb-0">
+            {syntheticTitle}
+            {badge && (
+              <Badge
+                variant={badge.variant}
+                className="md:tw-hidden tw-ml-1 tw-align-middle"
+              >
+                {badge.text}
+              </Badge>
+            )}
+          </Heading>
+          {badge && (
+            <Badge
+              variant={badge.variant}
+              className={clsx("md:tw-block tw-hidden")}
+            >
+              {badge.text}
+            </Badge>
+          )}
+        </header>
+      )}
+      <MDXContent>{children}</MDXContent>
+    </div>
+  )
+}

www/docs/src/theme/DocPage/Layout/index.tsx

@@ -7,10 +7,15 @@ import DocPageLayoutMain from "@theme/DocPage/Layout/Main"
 import type { Props } from "@theme/DocPage/Layout"
 import clsx from "clsx"
 import { useSidebar } from "@site/src/providers/Sidebar"
+import useOnboarding from "@site/src/hooks/use-onboarding"
+import useCurrentLearningPath from "@site/src/hooks/use-current-learning-path"
 
 export default function DocPageLayout({ children }: Props): JSX.Element {
   const sidebar = useDocsSidebar()
   const sidebarContext = useSidebar()
+  useOnboarding()
+  useCurrentLearningPath()
+
   return (
     <Layout wrapperClassName={clsx("tw-flex tw-flex-[1_0_auto]")}>
       <BackToTopButton />

www/docs/src/theme/DocPage/index.tsx

@@ -15,7 +15,10 @@ import DocPageLayout from "@theme/DocPage/Layout"
 import NotFound from "@theme/NotFound"
 import SearchMetadata from "@theme/SearchMetadata"
 import type { Props } from "@theme/DocPage"
+import LearningPathProvider from "@site/src/providers/LearningPath"
 import SidebarProvider from "@site/src/providers/Sidebar"
+import NotificationProvider from "@site/src/providers/NotificationProvider"
+import UserProvider from "@site/src/providers/User"
 
 function DocPageMetadata(props: Props): JSX.Element {
   const { versionMetadata } = props
@@ -58,11 +61,17 @@ export default function DocPage(props: Props): JSX.Element {
         )}
       >
         <DocsVersionProvider version={versionMetadata}>
+          <UserProvider>
             <DocsSidebarProvider name={sidebarName} items={sidebarItems}>
+              <LearningPathProvider>
                 <SidebarProvider sidebarName={sidebarName}>
+                  <NotificationProvider>
                     <DocPageLayout>{docElement}</DocPageLayout>
+                  </NotificationProvider>
                 </SidebarProvider>
+              </LearningPathProvider>
             </DocsSidebarProvider>
+          </UserProvider>
         </DocsVersionProvider>
       </HtmlClassNameProvider>
     </>

www/docs/src/theme/Icon/AcademicCapSolid/index.tsx

@@ -20,7 +20,7 @@ const IconAcademicCapSolid: React.FC<IconProps> = ({
         d="M9.67899 1.93018C9.77863 1.88025 9.88855 1.85425 10 1.85425C10.1115 1.85425 10.2214 1.88025 10.321 1.93018C13.1299 3.33766 15.7595 5.07749 18.1534 7.11227C18.2506 7.19485 18.324 7.30188 18.3661 7.42232C18.4081 7.54275 18.4172 7.67222 18.3925 7.79736C18.3677 7.9225 18.31 8.03876 18.2254 8.13415C18.1407 8.22954 18.0321 8.30059 17.9107 8.33996C15.249 9.20318 12.7213 10.4349 10.4013 11.9991C10.2828 12.0792 10.143 12.122 10 12.122C9.85698 12.122 9.71723 12.0792 9.59873 11.9991C8.95249 11.5637 8.28958 11.1535 7.6115 10.7695V9.64504C7.6115 9.41192 7.72233 9.20269 7.90003 9.07944C8.91637 8.37493 9.97048 7.72651 11.0576 7.13711C11.222 7.04516 11.3435 6.89222 11.3959 6.71137C11.4484 6.53052 11.4275 6.3363 11.3379 6.1707C11.2482 6.00511 11.097 5.88145 10.9169 5.82648C10.7368 5.77151 10.5423 5.78963 10.3755 5.87694C9.24192 6.49154 8.14284 7.1677 7.08316 7.90239C6.80297 8.09811 6.57432 8.35876 6.41677 8.66206C6.25921 8.96536 6.17742 9.3023 6.1784 9.64409V10.0071C4.85835 9.35105 3.49158 8.79348 2.08928 8.33901C1.96795 8.29963 1.85934 8.22858 1.77465 8.13319C1.68996 8.03781 1.63227 7.92154 1.60753 7.7964C1.5828 7.67127 1.59192 7.5418 1.63394 7.42136C1.67597 7.30093 1.74939 7.19389 1.84661 7.11132C4.24046 5.07653 6.8701 3.3367 9.67899 1.92922V1.93018ZM6.1784 11.6179C5.41374 11.2138 4.6311 10.8446 3.83289 10.5116C3.67079 11.4982 3.5465 12.4906 3.46028 13.4867C3.4476 13.6312 3.47907 13.7762 3.55055 13.9024C3.62203 14.0287 3.73014 14.1302 3.8606 14.1937C4.36505 14.4383 4.85994 14.7001 5.34529 14.9771C5.14465 15.2867 4.91058 15.579 4.63925 15.8504C4.56885 15.916 4.51238 15.9951 4.47322 16.083C4.43405 16.1709 4.41299 16.2658 4.4113 16.362C4.4096 16.4582 4.4273 16.5537 4.46334 16.643C4.49937 16.7322 4.55302 16.8132 4.62106 16.8813C4.6891 16.9493 4.77015 17.003 4.85937 17.039C4.9486 17.075 5.04417 17.0927 5.14038 17.091C5.23659 17.0893 5.33147 17.0683 5.41937 17.0291C5.50727 16.99 5.58637 16.9335 5.65197 16.8631C6.00547 16.5106 6.3112 16.1274 6.56916 15.7233C7.60815 16.398 8.59644 17.1478 9.52612 17.9666C9.65701 18.082 9.82551 18.1457 10 18.1457C10.1745 18.1457 10.343 18.082 10.4739 17.9666C12.1842 16.4598 14.0899 15.1904 16.1394 14.1928C16.2699 14.1295 16.3781 14.0281 16.4497 13.9021C16.5214 13.776 16.5531 13.6312 16.5407 13.4867C16.4544 12.4906 16.3301 11.4982 16.1681 10.5116C14.4282 11.2377 12.7644 12.1341 11.2009 13.1877C10.8461 13.4267 10.4279 13.5544 10 13.5544C9.57211 13.5544 9.15395 13.4267 8.79906 13.1877C8.40735 12.9249 8.0099 12.6708 7.60481 12.4262C7.55492 13.5968 7.19773 14.7346 6.56916 15.7233C6.16831 15.4634 5.76019 15.2139 5.34529 14.9771C5.89043 14.1295 6.17969 13.1426 6.1784 12.1348V11.6189V11.6179Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
     </svg>

www/docs/src/theme/Icon/Adjustments/index.tsx

@@ -18,7 +18,7 @@ const IconAdjustments: React.FC<IconProps> = ({
         d="M8.75 5H16.875M8.75 5C8.75 5.33152 8.6183 5.64946 8.38388 5.88388C8.14946 6.1183 7.83152 6.25 7.5 6.25C7.16848 6.25 6.85054 6.1183 6.61612 5.88388C6.3817 5.64946 6.25 5.33152 6.25 5M8.75 5C8.75 4.66848 8.6183 4.35054 8.38388 4.11612C8.14946 3.8817 7.83152 3.75 7.5 3.75C7.16848 3.75 6.85054 3.8817 6.61612 4.11612C6.3817 4.35054 6.25 4.66848 6.25 5M3.125 5H6.25M8.75 15H16.875M8.75 15C8.75 15.3315 8.6183 15.6495 8.38388 15.8839C8.14946 16.1183 7.83152 16.25 7.5 16.25C7.16848 16.25 6.85054 16.1183 6.61612 15.8839C6.3817 15.6495 6.25 15.3315 6.25 15M8.75 15C8.75 14.6685 8.6183 14.3505 8.38388 14.1161C8.14946 13.8817 7.83152 13.75 7.5 13.75C7.16848 13.75 6.85054 13.8817 6.61612 14.1161C6.3817 14.3505 6.25 14.6685 6.25 15M3.125 15H6.25M13.75 10H16.875M13.75 10C13.75 10.3315 13.6183 10.6495 13.3839 10.8839C13.1495 11.1183 12.8315 11.25 12.5 11.25C12.1685 11.25 11.8505 11.1183 11.6161 10.8839C11.3817 10.6495 11.25 10.3315 11.25 10M13.75 10C13.75 9.66848 13.6183 9.35054 13.3839 9.11612C13.1495 8.8817 12.8315 8.75 12.5 8.75C12.1685 8.75 11.8505 8.8817 11.6161 9.11612C11.3817 9.35054 11.25 9.66848 11.25 10M3.125 10H11.25"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1.25"
         strokeLinecap="round"

www/docs/src/theme/Icon/Alert/index.tsx

@@ -17,7 +17,7 @@ const IconAlert: React.FC<IconProps> = ({ iconColorClassName, ...props }) => {
         d="M18 10C18 12.1217 17.1571 14.1566 15.6569 15.6569C14.1566 17.1571 12.1217 18 10 18C7.87827 18 5.84344 17.1571 4.34315 15.6569C2.84285 14.1566 2 12.1217 2 10C2 7.87827 2.84285 5.84344 4.34315 4.34315C5.84344 2.84285 7.87827 2 10 2C12.1217 2 14.1566 2.84285 15.6569 4.34315C17.1571 5.84344 18 7.87827 18 10ZM10 5C10.1989 5 10.3897 5.07902 10.5303 5.21967C10.671 5.36032 10.75 5.55109 10.75 5.75V10.25C10.75 10.4489 10.671 10.6397 10.5303 10.7803C10.3897 10.921 10.1989 11 10 11C9.80109 11 9.61032 10.921 9.46967 10.7803C9.32902 10.6397 9.25 10.4489 9.25 10.25V5.75C9.25 5.55109 9.32902 5.36032 9.46967 5.21967C9.61032 5.07902 9.80109 5 10 5ZM10 15C10.2652 15 10.5196 14.8946 10.7071 14.7071C10.8946 14.5196 11 14.2652 11 14C11 13.7348 10.8946 13.4804 10.7071 13.2929C10.5196 13.1054 10.2652 13 10 13C9.73478 13 9.48043 13.1054 9.29289 13.2929C9.10536 13.4804 9 13.7348 9 14C9 14.2652 9.10536 14.5196 9.29289 14.7071C9.48043 14.8946 9.73478 15 10 15Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
     </svg>

www/docs/src/theme/Icon/ArrowDownTray/index.tsx

@@ -18,7 +18,7 @@ const IconArrowDownTray: React.FC<IconProps> = ({
         d="M2.5 13.75V15.625C2.5 16.1223 2.69754 16.5992 3.04917 16.9508C3.40081 17.3025 3.87772 17.5 4.375 17.5H15.625C16.1223 17.5 16.5992 17.3025 16.9508 16.9508C17.3025 16.5992 17.5 16.1223 17.5 15.625V13.75M13.75 10L10 13.75M10 13.75L6.25 10M10 13.75V2.5"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1.5"
         strokeLinecap="round"

www/docs/src/theme/Icon/BackArrow/index.tsx

@@ -18,7 +18,7 @@ const IconBackArow: React.FC<IconProps> = ({
         d="M7.66703 12.3331L3.00098 7.66703M3.00098 7.66703L7.66703 3.00098M3.00098 7.66703H12.3331C13.5706 7.66703 14.7574 8.15863 15.6325 9.03368C16.5075 9.90874 16.9991 11.0956 16.9991 12.3331C16.9991 13.5706 16.5075 14.7574 15.6325 15.6325C14.7574 16.5075 13.5706 16.9991 12.3331 16.9991H10.0001"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1.5"
         strokeLinecap="round"

www/docs/src/theme/Icon/BarsThree/index.tsx

@@ -18,7 +18,7 @@ const IconBarsThree: React.FC<IconProps> = ({
         d="M3.125 5.00006H16.875M3.125 10H16.875M3.125 15.0001H16.875"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1.5"
         strokeLinecap="round"

www/docs/src/theme/Icon/Bell/index.tsx

@@ -15,7 +15,7 @@ const IconBell: React.FC<IconProps> = ({ iconColorClassName, ...props }) => {
         d="M4.87497 2.91669C4.97929 2.79237 5.03116 2.63234 5.01961 2.47046C5.00806 2.30858 4.93399 2.15754 4.81307 2.04929C4.69216 1.94104 4.53388 1.88407 4.37171 1.89043C4.20954 1.89678 4.05621 1.96597 3.94414 2.08336C2.92036 3.22523 2.24183 4.63431 1.98747 6.14669C1.96394 6.3084 2.00469 6.4729 2.10098 6.60494C2.19726 6.73697 2.34144 6.82604 2.5026 6.85307C2.66377 6.88009 2.82911 6.84292 2.9632 6.74951C3.09729 6.65611 3.18946 6.5139 3.21997 6.35335C3.43508 5.0742 4.00901 3.88242 4.87497 2.91669ZM16.0558 2.08336C16.0012 2.02163 15.935 1.97131 15.8609 1.93527C15.7868 1.89924 15.7064 1.87821 15.6241 1.87339C15.5419 1.86856 15.4595 1.88005 15.3817 1.90718C15.3039 1.93431 15.2323 1.97655 15.1709 2.03147C15.1095 2.0864 15.0595 2.15291 15.0239 2.22721C14.9883 2.3015 14.9678 2.38209 14.9634 2.46436C14.9591 2.54663 14.971 2.62894 14.9986 2.70657C15.0262 2.7842 15.0689 2.85561 15.1241 2.91669C15.9904 3.88234 16.5646 5.07412 16.78 6.35335C16.8074 6.51691 16.8986 6.66287 17.0337 6.75914C17.1005 6.80681 17.1761 6.84084 17.2561 6.85929C17.3361 6.87775 17.419 6.88026 17.5 6.86669C17.581 6.85312 17.6585 6.82373 17.7281 6.7802C17.7977 6.73668 17.8581 6.67986 17.9058 6.613C17.9534 6.54614 17.9875 6.47055 18.0059 6.39054C18.0244 6.31053 18.0269 6.22767 18.0133 6.14669C17.7584 4.63414 17.0801 3.22506 16.0558 2.08336Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
       <path
@@ -24,7 +24,7 @@ const IconBell: React.FC<IconProps> = ({ iconColorClassName, ...props }) => {
         d="M9.99985 1.875C8.50801 1.875 7.07727 2.46763 6.02237 3.52252C4.96748 4.57742 4.37485 6.00816 4.37485 7.5V8.125C4.37741 9.82433 3.74802 11.4639 2.60902 12.725C2.54061 12.8009 2.49186 12.8924 2.46701 12.9915C2.44216 13.0906 2.44198 13.1942 2.46649 13.2934C2.491 13.3926 2.53944 13.4842 2.60758 13.5603C2.67572 13.6365 2.76148 13.6947 2.85735 13.73C4.14402 14.205 5.49068 14.555 6.88318 14.7658C6.85183 15.1943 6.90915 15.6246 7.05157 16.0299C7.19399 16.4352 7.41845 16.8068 7.71093 17.1214C8.0034 17.4361 8.35762 17.6871 8.75144 17.8587C9.14527 18.0303 9.57025 18.1189 9.99985 18.1189C10.4294 18.1189 10.8544 18.0303 11.2483 17.8587C11.6421 17.6871 11.9963 17.4361 12.2888 17.1214C12.5812 16.8068 12.8057 16.4352 12.9481 16.0299C13.0905 15.6246 13.1479 15.1943 13.1165 14.7658C14.4899 14.5576 15.8385 14.2103 17.1415 13.7292C17.2372 13.6938 17.3229 13.6356 17.3909 13.5595C17.4589 13.4835 17.5073 13.3919 17.5318 13.2929C17.5563 13.1938 17.5561 13.0903 17.5314 12.9913C17.5067 12.8923 17.4581 12.8009 17.3898 12.725C16.2511 11.4638 15.6221 9.82422 15.6248 8.125V7.5C15.6248 6.00816 15.0322 4.57742 13.9773 3.52252C12.9224 2.46763 11.4917 1.875 9.99985 1.875ZM8.12485 15C8.12485 14.9717 8.12485 14.9442 8.12652 14.9167C9.37288 15.029 10.6268 15.029 11.8732 14.9167L11.8748 15C11.8748 15.4973 11.6773 15.9742 11.3257 16.3258C10.974 16.6775 10.4971 16.875 9.99985 16.875C9.50257 16.875 9.02566 16.6775 8.67402 16.3258C8.32239 15.9742 8.12485 15.4973 8.12485 15Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
     </svg>

www/docs/src/theme/Icon/BellAlertSolid/index.tsx

@@ -18,7 +18,7 @@ const IconBellAlertSolid: React.FC<IconProps> = ({
         d="M4.875 2.91669C4.97932 2.79237 5.03119 2.63234 5.01964 2.47046C5.00809 2.30858 4.93402 2.15754 4.81311 2.04929C4.69219 1.94104 4.53391 1.88407 4.37174 1.89043C4.20957 1.89678 4.05624 1.96597 3.94417 2.08336C2.92039 3.22523 2.24186 4.63431 1.9875 6.14669C1.96397 6.3084 2.00472 6.4729 2.10101 6.60494C2.19729 6.73697 2.34147 6.82604 2.50263 6.85307C2.6638 6.88009 2.82914 6.84292 2.96323 6.74951C3.09732 6.65611 3.18949 6.5139 3.22 6.35335C3.43511 5.0742 4.00904 3.88242 4.875 2.91669ZM16.0558 2.08336C16.0013 2.02163 15.935 1.97131 15.861 1.93527C15.7869 1.89924 15.7064 1.87821 15.6242 1.87339C15.5419 1.86856 15.4595 1.88005 15.3818 1.90718C15.304 1.93431 15.2323 1.97655 15.1709 2.03147C15.1095 2.0864 15.0596 2.15291 15.024 2.22721C14.9884 2.3015 14.9678 2.38209 14.9634 2.46436C14.9591 2.54663 14.9711 2.62894 14.9987 2.70657C15.0262 2.7842 15.0689 2.85561 15.1242 2.91669C15.9904 3.88234 16.5646 5.07412 16.78 6.35335C16.8074 6.51691 16.8987 6.66287 17.0337 6.75914C17.1005 6.80681 17.1761 6.84084 17.2561 6.85929C17.3362 6.87775 17.419 6.88026 17.5 6.86669C17.581 6.85312 17.6585 6.82373 17.7281 6.7802C17.7977 6.73668 17.8581 6.67986 17.9058 6.613C17.9535 6.54614 17.9875 6.47055 18.0059 6.39054C18.0244 6.31053 18.0269 6.22767 18.0133 6.14669C17.7585 4.63414 17.0802 3.22506 16.0558 2.08336Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
       <path
@@ -27,7 +27,7 @@ const IconBellAlertSolid: React.FC<IconProps> = ({
         d="M10 1.875C8.50816 1.875 7.07742 2.46763 6.02253 3.52252C4.96763 4.57742 4.375 6.00816 4.375 7.5V8.125C4.37757 9.82433 3.74817 11.4639 2.60917 12.725C2.54077 12.8009 2.49201 12.8924 2.46716 12.9915C2.44232 13.0906 2.44214 13.1942 2.46664 13.2934C2.49115 13.3926 2.53959 13.4842 2.60773 13.5603C2.67587 13.6365 2.76163 13.6947 2.8575 13.73C4.14417 14.205 5.49084 14.555 6.88334 14.7658C6.85198 15.1943 6.90931 15.6246 7.05173 16.0299C7.19415 16.4352 7.4186 16.8068 7.71108 17.1214C8.00356 17.4361 8.35777 17.6871 8.7516 17.8587C9.14542 18.0303 9.57041 18.1189 10 18.1189C10.4296 18.1189 10.8546 18.0303 11.2484 17.8587C11.6422 17.6871 11.9964 17.4361 12.2889 17.1214C12.5814 16.8068 12.8059 16.4352 12.9483 16.0299C13.0907 15.6246 13.148 15.1943 13.1167 14.7658C14.49 14.5576 15.8386 14.2103 17.1417 13.7292C17.2374 13.6938 17.323 13.6356 17.391 13.5595C17.4591 13.4835 17.5074 13.3919 17.5319 13.2929C17.5564 13.1938 17.5563 13.0903 17.5316 12.9913C17.5068 12.8923 17.4582 12.8009 17.39 12.725C16.2513 11.4638 15.6222 9.82422 15.625 8.125V7.5C15.625 6.00816 15.0324 4.57742 13.9775 3.52252C12.9226 2.46763 11.4918 1.875 10 1.875ZM8.125 15C8.125 14.9717 8.125 14.9442 8.12667 14.9167C9.37303 15.029 10.627 15.029 11.8733 14.9167L11.875 15C11.875 15.4973 11.6775 15.9742 11.3258 16.3258C10.9742 16.6775 10.4973 16.875 10 16.875C9.50272 16.875 9.02581 16.6775 8.67418 16.3258C8.32255 15.9742 8.125 15.4973 8.125 15Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
     </svg>

www/docs/src/theme/Icon/Bolt/index.tsx

@@ -15,7 +15,7 @@ const IconBolt: React.FC<IconProps> = ({ iconColorClassName, ...props }) => {
         d="M3.125 11.25L11.875 1.875L10 8.75H16.875L8.125 18.125L10 11.25H3.125Z"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1.5"
         strokeLinecap="round"

www/docs/src/theme/Icon/BoltSolid/index.tsx

@@ -20,7 +20,7 @@ const IconBoltSolid: React.FC<IconProps> = ({
         d="M12.0339 1.57679C12.1478 1.64276 12.2372 1.74652 12.2878 1.87153C12.3384 1.99653 12.3473 2.13558 12.3131 2.26648L10.7638 8.17823H16.4167C16.5304 8.17824 16.6416 8.21282 16.7366 8.27772C16.8317 8.34262 16.9065 8.43501 16.9517 8.54354C16.997 8.65206 17.0108 8.772 16.9915 8.88859C16.9722 9.00518 16.9205 9.11336 16.8429 9.19982L8.67622 18.3067C8.58727 18.4061 8.46885 18.4715 8.33992 18.4926C8.21099 18.5137 8.07899 18.4892 7.96502 18.423C7.85106 18.3568 7.76172 18.2527 7.7113 18.1274C7.66087 18.0022 7.65227 17.8629 7.68688 17.7319L9.23622 11.821H3.5833C3.46962 11.821 3.35842 11.7864 3.26336 11.7215C3.16831 11.6566 3.09355 11.5642 3.04827 11.4557C3.00299 11.3471 2.98916 11.2272 3.0085 11.1106C3.02783 10.994 3.07947 10.8858 3.15708 10.7994L11.3238 1.69255C11.4127 1.5935 11.531 1.52829 11.6597 1.50731C11.7884 1.48633 11.9201 1.51079 12.0339 1.57679Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
     </svg>

www/docs/src/theme/Icon/BookOpen/index.tsx

@@ -18,7 +18,7 @@ const IconBookOpen: React.FC<IconProps> = ({
         d="M10 5.03501C8.62634 3.80281 6.84533 3.12246 5 3.12501C4.12333 3.12501 3.28167 3.27501 2.5 3.55167V15.4267C3.30302 15.1434 4.14847 14.9991 5 15C6.92083 15 8.67333 15.7225 10 16.91M10 5.03501C11.3736 3.80274 13.1547 3.12238 15 3.12501C15.8767 3.12501 16.7183 3.27501 17.5 3.55167V15.4267C16.697 15.1434 15.8515 14.9991 15 15C13.1547 14.9975 11.3737 15.6778 10 16.91M10 5.03501V16.91"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1.5"
         strokeLinecap="round"

www/docs/src/theme/Icon/Bug/index.tsx

@@ -15,7 +15,7 @@ const IconBug: React.FC<IconProps> = ({ iconColorClassName, ...props }) => {
         d="M10.0003 10.6153C10.9415 10.6153 11.8679 10.6809 12.7739 10.8097C13.6241 10.9294 14.3037 11.6016 14.3037 12.46C14.3037 15.5164 12.3771 17.994 9.99951 17.994C7.62194 17.994 5.69611 15.5164 5.69611 12.46C5.69611 11.6024 6.37659 10.9294 7.22595 10.8097C8.14506 10.6801 9.07213 10.6152 10.0003 10.6153ZM10.0003 10.6153C12.364 10.6153 14.63 11.0318 16.7288 11.7959C16.6299 13.4859 16.3124 15.1559 15.7844 16.7642M10.0003 10.6153C7.6367 10.6153 5.37063 11.0318 3.271 11.7959C3.37348 13.5209 3.69732 15.1868 4.21628 16.7642M10.0003 10.6153C10.2498 10.6154 10.4966 10.5648 10.726 10.4668C10.9554 10.3687 11.1624 10.2251 11.3347 10.0447C11.507 9.86427 11.6409 9.6508 11.7283 9.41717C11.8157 9.18354 11.8549 8.93461 11.8433 8.68542M10.0003 10.6153C9.75087 10.6154 9.50401 10.5648 9.27465 10.4668C9.04529 10.3687 8.83821 10.2251 8.66593 10.0447C8.49365 9.86427 8.35975 9.6508 8.27233 9.41717C8.1849 9.18354 8.14577 8.93461 8.1573 8.68542M11.8433 8.68542C11.8214 8.2114 11.6176 7.76406 11.2744 7.43639C10.9312 7.10873 10.4749 6.92594 10.0003 6.92602M11.8433 8.68542C13.2994 8.55055 14.7365 8.25301 16.1262 7.79834C16.0812 6.87437 15.9729 5.9668 15.8049 5.08136M8.1573 8.68542C8.17924 8.2114 8.383 7.76406 8.72624 7.43639C9.06948 7.10873 9.52579 6.92594 10.0003 6.92602M8.1573 8.68542C6.67583 8.54769 5.24274 8.24598 3.87523 7.79834C3.91931 6.88633 4.02669 5.97849 4.19661 5.08136M10.0003 6.92602C10.8161 6.92602 11.6163 6.86044 12.3959 6.73254C12.7263 6.67843 13.0026 6.43903 13.0477 6.10781C13.1317 5.4739 13.0174 4.82953 12.7206 4.26315M10.0003 6.92602C9.18457 6.92602 8.38522 6.86044 7.60472 6.73254C7.27514 6.67843 6.99803 6.43903 6.95294 6.10781C6.86626 5.47296 6.98096 4.82691 7.28088 4.26069M7.28088 4.26069C6.93167 4.02814 6.61347 3.75291 6.33396 3.44002C6.39135 2.92352 6.55532 2.43816 6.80455 2.00774M7.28088 4.26069C7.54188 3.76545 7.93313 3.35169 8.41244 3.06249C8.89176 2.77329 9.44093 2.62045 10.0007 2.62045C10.5605 2.62045 11.1097 2.77329 11.589 3.06249C12.0683 3.35169 12.4596 3.76627 12.7206 4.26151C13.0707 4.02949 13.3888 3.7532 13.6675 3.44248C13.6119 2.93613 13.4513 2.44694 13.1961 2.0061"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1.5"
         strokeLinecap="round"

www/docs/src/theme/Icon/BugAntSolid/index.tsx

@@ -20,7 +20,7 @@ const IconBugAntSolid: React.FC<IconProps> = ({
         d="M6.7881 1.72723C6.93928 1.83478 7.0416 1.99794 7.07259 2.18088C7.10357 2.36381 7.06069 2.55156 6.95335 2.7029C6.77659 2.95179 6.63109 3.22146 6.52014 3.50585C6.69286 3.66457 6.87679 3.81302 7.071 3.94747C7.42032 3.50522 7.86536 3.14792 8.37266 2.90243C8.87996 2.65695 9.43631 2.52967 9.99988 2.53018C11.1875 2.53018 12.2453 3.08477 12.9288 3.94747C13.123 3.81302 13.3069 3.66551 13.4796 3.50585C13.3687 3.22146 13.2232 2.95179 13.0464 2.7029C12.9446 2.55142 12.9059 2.36617 12.9387 2.1866C12.9714 2.00703 13.073 1.84735 13.2217 1.74157C13.3705 1.63579 13.5547 1.59227 13.735 1.62028C13.9154 1.6483 14.0777 1.74564 14.1873 1.89155C14.5319 2.37612 14.7942 2.92325 14.9548 3.51239C14.986 3.62715 14.9875 3.74798 14.9591 3.86347C14.9306 3.97896 14.8733 4.08531 14.7924 4.17248C14.4311 4.56203 14.0238 4.90627 13.5795 5.19764C13.6825 5.54399 13.7348 5.90346 13.7345 6.26481C13.7345 6.75032 13.4535 7.16393 13.0595 7.37307C12.7135 7.55658 12.3516 7.70846 11.9783 7.82682C12.0997 8.02102 12.194 8.2339 12.2547 8.46078C13.5739 8.29832 14.8493 7.99395 16.0649 7.56447C16.0796 6.84172 16.0515 6.11874 15.9809 5.39931C15.972 5.30778 15.9811 5.21539 16.0079 5.1274C16.0346 5.03942 16.0785 4.95756 16.1368 4.88651C16.1952 4.81546 16.2671 4.75661 16.3482 4.71331C16.4293 4.67002 16.5182 4.64313 16.6097 4.63418C16.7012 4.62523 16.7936 4.63439 16.8816 4.66115C16.9696 4.68791 17.0515 4.73173 17.1225 4.79012C17.1936 4.84851 17.2524 4.92033 17.2957 5.00146C17.339 5.0826 17.3659 5.17147 17.3749 5.263C17.467 6.20239 17.492 7.14717 17.4495 8.09012C17.4434 8.22648 17.3975 8.35808 17.3176 8.46872C17.2376 8.57937 17.1271 8.66423 16.9995 8.71287C15.4519 9.30451 13.8351 9.69638 12.1884 9.87901C12.1592 9.95761 12.1259 10.0346 12.0885 10.1096C13.7673 10.2866 15.4159 10.6811 16.993 11.2832C17.1311 11.3363 17.2489 11.4317 17.3294 11.5558C17.4099 11.68 17.449 11.8264 17.4411 11.9741C17.3575 13.5925 17.0731 15.1942 16.5943 16.7423C16.5671 16.8302 16.5228 16.9118 16.4641 16.9826C16.4053 17.0533 16.3332 17.1118 16.2518 17.1547C16.1705 17.1975 16.0814 17.224 15.9899 17.2324C15.8983 17.2409 15.8059 17.2312 15.7181 17.204C15.6302 17.1768 15.5486 17.1325 15.4779 17.0738C15.4071 17.015 15.3486 16.9429 15.3058 16.8615C15.2629 16.7802 15.2365 16.6911 15.228 16.5996C15.2195 16.508 15.2292 16.4156 15.2564 16.3278C15.6439 15.0767 15.9006 13.7668 16.0089 12.4158C15.5468 12.2533 15.0753 12.1095 14.5972 11.9853C14.6439 12.2505 14.6682 12.5222 14.6682 12.8004C14.6682 14.4941 14.1855 15.8927 13.3368 16.8805C12.9258 17.3628 12.4139 17.7491 11.8374 18.0121C11.2608 18.275 10.6336 18.4083 9.99988 18.4024C9.36622 18.4082 8.739 18.2749 8.16244 18.012C7.58589 17.749 7.07404 17.3628 6.66299 16.8805C5.81336 15.8918 5.33159 14.4931 5.33159 12.8004C5.33159 12.5222 5.35586 12.2496 5.40255 11.9853C4.92358 12.1095 4.45302 12.2533 3.99086 12.4148C4.09916 13.7668 4.35498 15.0757 4.74338 16.3278C4.79836 16.5052 4.7806 16.6972 4.69401 16.8615C4.60743 17.0259 4.45911 17.1491 4.28169 17.204C4.10427 17.259 3.91228 17.2412 3.74795 17.1547C3.58362 17.0681 3.46042 16.9198 3.40545 16.7423C2.92634 15.1942 2.64157 13.5925 2.55769 11.9741C2.54996 11.8262 2.58936 11.6796 2.67023 11.5554C2.75109 11.4313 2.86925 11.336 3.00771 11.2832C4.58447 10.6812 6.23281 10.2867 7.91129 10.1096C7.87384 10.0346 7.84049 9.95763 7.81139 9.87901C6.16462 9.69638 4.54787 9.30451 3.00024 8.71287C2.8727 8.66423 2.76215 8.57937 2.68219 8.46872C2.60224 8.35808 2.55637 8.22648 2.55022 8.09012C2.50813 7.14716 2.53309 6.20241 2.62491 5.263C2.63386 5.17147 2.66075 5.0826 2.70405 5.00146C2.74734 4.92033 2.8062 4.84851 2.87725 4.79012C2.9483 4.73173 3.03015 4.68791 3.11814 4.66115C3.20612 4.63439 3.29852 4.62523 3.39005 4.63418C3.48157 4.64313 3.57044 4.67002 3.65158 4.71331C3.73271 4.75661 3.80453 4.81546 3.86292 4.88651C3.92131 4.95756 3.96514 5.03942 3.99189 5.1274C4.01865 5.21539 4.02782 5.30778 4.01887 5.39931C3.94839 6.11907 3.92033 6.84235 3.93484 7.5654C5.15046 7.99395 6.42584 8.29832 7.74416 8.46078C7.80579 8.2339 7.89915 8.02102 8.02146 7.82682C7.64813 7.70845 7.28627 7.55658 6.94028 7.37307C6.73772 7.26707 6.56785 7.1079 6.44892 6.91264C6.32999 6.71739 6.2665 6.49343 6.26525 6.26481C6.26501 5.90346 6.31722 5.54399 6.42024 5.19764C5.97564 4.90631 5.56807 4.56207 5.20648 4.17248C5.12573 4.08522 5.06853 3.97883 5.04027 3.86334C5.01202 3.74786 5.01363 3.62708 5.04496 3.51239C5.20336 2.93114 5.46317 2.38243 5.81242 1.89155C5.86576 1.81664 5.93332 1.75296 6.01127 1.70415C6.08921 1.65535 6.17601 1.62238 6.26669 1.60712C6.35738 1.59186 6.45018 1.59461 6.53981 1.61522C6.62943 1.63583 6.71318 1.67389 6.7881 1.72723Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
     </svg>

www/docs/src/theme/Icon/BuildingSolid/index.tsx

@@ -20,7 +20,7 @@ const IconBuildingSolid: React.FC<IconProps> = ({
         d="M13.8927 4.15414V7.27547H16.2399C16.6442 7.27547 17.0319 7.43606 17.3177 7.72192C17.6036 8.00777 17.7642 8.39547 17.7642 8.79973V15.7922H17.7885C18.2027 15.7922 18.5385 16.128 18.5385 16.5422C18.5385 16.9564 18.2027 17.2922 17.7885 17.2922H17.0218L17.0142 17.2923L17.0065 17.2922H2.30347C1.88925 17.2922 1.55347 16.9564 1.55347 16.5422C1.55347 16.128 1.88925 15.7922 2.30347 15.7922H2.32739V4.15414C2.32739 3.74988 2.48798 3.36218 2.77384 3.07633C3.05969 2.79047 3.44739 2.62988 3.85165 2.62988H12.3684C12.7727 2.62988 13.1604 2.79047 13.4462 3.07633C13.7321 3.36218 13.8927 3.74988 13.8927 4.15414ZM10.2392 15.8862C9.88026 15.8862 9.58924 15.5952 9.58924 15.2362V13.859H6.63086V15.2362C6.63086 15.5952 6.33984 15.8862 5.98085 15.8862C5.62187 15.8862 5.33085 15.5952 5.33085 15.2362V13.209C5.33085 12.85 5.62187 12.559 5.98085 12.559H10.2392C10.5982 12.559 10.8892 12.85 10.8892 13.209V15.2362C10.8892 15.5952 10.5982 15.8862 10.2392 15.8862ZM5.98065 9.21094C5.56644 9.21094 5.23065 9.54672 5.23065 9.96094C5.23065 10.3752 5.56644 10.7109 5.98065 10.7109H10.2391C10.6533 10.7109 10.9891 10.3752 10.9891 9.96094C10.9891 9.54672 10.6533 9.21094 10.2391 9.21094H5.98065ZM15.4614 15.884C15.0472 15.884 14.7114 15.5482 14.7114 15.134V9.96098C14.7114 9.54677 15.0472 9.21098 15.4614 9.21098C15.8756 9.21098 16.2114 9.54677 16.2114 9.96098V15.134C16.2114 15.5482 15.8756 15.884 15.4614 15.884ZM5.98065 5.9021C5.56644 5.9021 5.23065 6.23789 5.23065 6.6521C5.23065 7.06631 5.56644 7.4021 5.98065 7.4021H10.2391C10.6533 7.4021 10.9891 7.06631 10.9891 6.6521C10.9891 6.23789 10.6533 5.9021 10.2391 5.9021H5.98065Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
     </svg>

www/docs/src/theme/Icon/BuildingStorefront/index.tsx

@@ -18,7 +18,7 @@ const IconBuildingStorefront: React.FC<IconProps> = ({
         d="M11.25 17.5V11.25C11.25 11.0842 11.3159 10.9253 11.4331 10.8081C11.5503 10.6908 11.7093 10.625 11.875 10.625H14.375C14.5408 10.625 14.6997 10.6908 14.817 10.8081C14.9342 10.9253 15 11.0842 15 11.25V17.5M11.25 17.5H1.96668M11.25 17.5H15M15 17.5H18.0333M16.875 17.5V7.79083C17.2072 7.59909 17.4908 7.33349 17.7038 7.01459C17.9169 6.6957 18.0538 6.33205 18.1038 5.95179C18.1538 5.57154 18.1157 5.18487 17.9924 4.82171C17.869 4.45855 17.6638 4.12864 17.3925 3.8575L16.4008 2.86667C16.1667 2.63218 15.8489 2.50029 15.5175 2.5H4.48168C4.15027 2.50029 3.83254 2.63218 3.59835 2.86667L2.60751 3.85667C2.33688 4.12811 2.13219 4.45809 2.00924 4.82114C1.88628 5.1842 1.84834 5.57064 1.89834 5.95068C1.94834 6.33072 2.08495 6.6942 2.29763 7.01309C2.5103 7.33199 2.79337 7.59779 3.12501 7.79M3.12501 17.4992V7.79167C3.62503 8.07999 4.20939 8.18647 4.77897 8.09306C5.34855 7.99965 5.86828 7.71209 6.25001 7.27917C6.48443 7.54537 6.77293 7.75852 7.09626 7.90437C7.41959 8.05023 7.77031 8.12545 8.12501 8.125C8.87168 8.125 9.54168 7.7975 10 7.27833C10.2344 7.54469 10.5228 7.75799 10.8462 7.90399C11.1695 8.05 11.5202 8.12534 11.875 8.125C12.6217 8.125 13.2917 7.7975 13.75 7.27833C14.1319 7.71112 14.6516 7.99852 15.2212 8.09178C15.7908 8.18504 16.3751 8.07842 16.875 7.79M5.62501 14.9992H8.75001C8.91577 14.9992 9.07474 14.9333 9.19195 14.8161C9.30916 14.6989 9.37501 14.5399 9.37501 14.3742V11.25C9.37501 11.0842 9.30916 10.9253 9.19195 10.8081C9.07474 10.6908 8.91577 10.625 8.75001 10.625H5.62501C5.45925 10.625 5.30028 10.6908 5.18307 10.8081C5.06586 10.9253 5.00001 11.0842 5.00001 11.25V14.375C5.00001 14.7208 5.28001 14.9992 5.62501 14.9992Z"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1.5"
         strokeLinecap="round"

www/docs/src/theme/Icon/BuildingTax/index.tsx

@@ -18,7 +18,7 @@ const IconBuildingTax: React.FC<IconProps> = ({
         d="M17.5 7.5H2.5V5.83333L10 2.5L17.5 5.83333V7.5Z"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1"
         strokeLinejoin="round"
@@ -27,7 +27,7 @@ const IconBuildingTax: React.FC<IconProps> = ({
         d="M8.33333 16.6666H2.5L3.22917 14.1666H8.33333"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1"
         strokeLinecap="round"
@@ -37,7 +37,7 @@ const IconBuildingTax: React.FC<IconProps> = ({
         d="M4.16667 7.5V14.1667M7.50001 14.1667V7.5"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1"
       />
@@ -45,7 +45,7 @@ const IconBuildingTax: React.FC<IconProps> = ({
         d="M17.1354 11.1979L12.0312 16.302"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1"
         strokeLinecap="round"
@@ -55,7 +55,7 @@ const IconBuildingTax: React.FC<IconProps> = ({
         d="M12.2917 12.0834C12.6368 12.0834 12.9167 11.8036 12.9167 11.4584C12.9167 11.1132 12.6368 10.8334 12.2917 10.8334C11.9465 10.8334 11.6667 11.1132 11.6667 11.4584C11.6667 11.8036 11.9465 12.0834 12.2917 12.0834Z"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1"
         strokeLinecap="round"
@@ -65,7 +65,7 @@ const IconBuildingTax: React.FC<IconProps> = ({
         d="M16.875 16.6666C17.2202 16.6666 17.5 16.3868 17.5 16.0416C17.5 15.6964 17.2202 15.4166 16.875 15.4166C16.5298 15.4166 16.25 15.6964 16.25 16.0416C16.25 16.3868 16.5298 16.6666 16.875 16.6666Z"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1"
         strokeLinecap="round"

www/docs/src/theme/Icon/Calendar/index.tsx

@@ -18,7 +18,7 @@ const IconCalendar: React.FC<IconProps> = ({
         d="M5.625 2.5V4.375M14.375 2.5V4.375M2.5 15.625V6.25C2.5 5.75272 2.69754 5.27581 3.04917 4.92417C3.40081 4.57254 3.87772 4.375 4.375 4.375H15.625C16.1223 4.375 16.5992 4.57254 16.9508 4.92417C17.3025 5.27581 17.5 5.75272 17.5 6.25V15.625M2.5 15.625C2.5 16.1223 2.69754 16.5992 3.04917 16.9508C3.40081 17.3025 3.87772 17.5 4.375 17.5H15.625C16.1223 17.5 16.5992 17.3025 16.9508 16.9508C17.3025 16.5992 17.5 16.1223 17.5 15.625M2.5 15.625V9.375C2.5 8.87772 2.69754 8.40081 3.04917 8.04917C3.40081 7.69754 3.87772 7.5 4.375 7.5H15.625C16.1223 7.5 16.5992 7.69754 16.9508 8.04917C17.3025 8.40081 17.5 8.87772 17.5 9.375V15.625"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1.5"
         strokeLinecap="round"

www/docs/src/theme/Icon/CashSolid/index.tsx

@@ -20,7 +20,7 @@ const IconCashSolid: React.FC<IconProps> = ({
         d="M1 4C1 3.73478 1.10536 3.48043 1.29289 3.29289C1.48043 3.10536 1.73478 3 2 3H18C18.2652 3 18.5196 3.10536 18.7071 3.29289C18.8946 3.48043 19 3.73478 19 4V12C19 12.2652 18.8946 12.5196 18.7071 12.7071C18.5196 12.8946 18.2652 13 18 13H2C1.73478 13 1.48043 12.8946 1.29289 12.7071C1.10536 12.5196 1 12.2652 1 12V4ZM13 8C13 8.79565 12.6839 9.55871 12.1213 10.1213C11.5587 10.6839 10.7956 11 10 11C9.20435 11 8.44129 10.6839 7.87868 10.1213C7.31607 9.55871 7 8.79565 7 8C7 7.20435 7.31607 6.44129 7.87868 5.87868C8.44129 5.31607 9.20435 5 10 5C10.7956 5 11.5587 5.31607 12.1213 5.87868C12.6839 6.44129 13 7.20435 13 8ZM4 9C4.26522 9 4.51957 8.89464 4.70711 8.70711C4.89464 8.51957 5 8.26522 5 8C5 7.73478 4.89464 7.48043 4.70711 7.29289C4.51957 7.10536 4.26522 7 4 7C3.73478 7 3.48043 7.10536 3.29289 7.29289C3.10536 7.48043 3 7.73478 3 8C3 8.26522 3.10536 8.51957 3.29289 8.70711C3.48043 8.89464 3.73478 9 4 9ZM17 8C17 8.26522 16.8946 8.51957 16.7071 8.70711C16.5196 8.89464 16.2652 9 16 9C15.7348 9 15.4804 8.89464 15.2929 8.70711C15.1054 8.51957 15 8.26522 15 8C15 7.73478 15.1054 7.48043 15.2929 7.29289C15.4804 7.10536 15.7348 7 16 7C16.2652 7 16.5196 7.10536 16.7071 7.29289C16.8946 7.48043 17 7.73478 17 8ZM1.75 14.5C1.55109 14.5 1.36032 14.579 1.21967 14.7197C1.07902 14.8603 1 15.0511 1 15.25C1 15.4489 1.07902 15.6397 1.21967 15.7803C1.36032 15.921 1.55109 16 1.75 16C6.167 16 10.443 16.603 14.499 17.73C15.61 18.039 16.75 17.218 16.75 16.034V15.25C16.75 15.0511 16.671 14.8603 16.5303 14.7197C16.3897 14.579 16.1989 14.5 16 14.5C15.8011 14.5 15.6103 14.579 15.4697 14.7197C15.329 14.8603 15.25 15.0511 15.25 15.25V16.034C15.2484 16.0755 15.2373 16.1161 15.2176 16.1526C15.1979 16.1891 15.1701 16.2207 15.1363 16.2448C15.1025 16.269 15.0637 16.285 15.0227 16.2918C14.9817 16.2986 14.9398 16.2959 14.9 16.284C10.6177 15.0963 6.19392 14.4961 1.75 14.5Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
     </svg>

www/docs/src/theme/Icon/Channels/index.tsx

@@ -18,7 +18,7 @@ const IconChannels: React.FC<IconProps> = ({
         d="M14.7189 5.875C15.6509 5.875 16.4064 5.11948 16.4064 4.1875C16.4064 3.25552 15.6509 2.5 14.7189 2.5C13.7869 2.5 13.0314 3.25552 13.0314 4.1875C13.0314 5.11948 13.7869 5.875 14.7189 5.875Z"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1"
         strokeLinecap="round"
@@ -28,7 +28,7 @@ const IconChannels: React.FC<IconProps> = ({
         d="M14.7189 11.6875C15.6509 11.6875 16.4064 10.932 16.4064 10C16.4064 9.06802 15.6509 8.3125 14.7189 8.3125C13.7869 8.3125 13.0314 9.06802 13.0314 10C13.0314 10.932 13.7869 11.6875 14.7189 11.6875Z"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1"
         strokeLinecap="round"
@@ -38,7 +38,7 @@ const IconChannels: React.FC<IconProps> = ({
         d="M4.5936 11.6875C5.52558 11.6875 6.2811 10.932 6.2811 10C6.2811 9.06802 5.52558 8.3125 4.5936 8.3125C3.66162 8.3125 2.9061 9.06802 2.9061 10C2.9061 10.932 3.66162 11.6875 4.5936 11.6875Z"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1"
         strokeLinecap="round"
@@ -48,7 +48,7 @@ const IconChannels: React.FC<IconProps> = ({
         d="M14.7189 17.5C15.6509 17.5 16.4064 16.7445 16.4064 15.8125C16.4064 14.8805 15.6509 14.125 14.7189 14.125C13.7869 14.125 13.0314 14.8805 13.0314 15.8125C13.0314 16.7445 13.7869 17.5 14.7189 17.5Z"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1"
         strokeLinecap="round"
@@ -58,7 +58,7 @@ const IconChannels: React.FC<IconProps> = ({
         d="M13.0308 4.1875H11.1558C10.327 4.1875 9.65576 4.85875 9.65576 5.6875V14.3125C9.65576 15.1413 10.327 15.8125 11.1558 15.8125H13.0308"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1"
         strokeLinecap="round"
@@ -68,7 +68,7 @@ const IconChannels: React.FC<IconProps> = ({
         d="M13.0301 10H6.28012"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1"
         strokeLinecap="round"

www/docs/src/theme/Icon/ChannelsSolid/index.tsx

@@ -20,7 +20,7 @@ const IconChannelsSolid: React.FC<IconProps> = ({
         d="M12.3989 3.43751C12.7152 2.45828 13.6343 1.75 14.7188 1.75C16.065 1.75 17.1563 2.84131 17.1563 4.1875C17.1563 5.53369 16.065 6.625 14.7188 6.625C13.6343 6.625 12.7152 5.91673 12.3989 4.93751L11.1557 4.93752C10.7411 4.93752 10.4057 5.27298 10.4057 5.68752V9.24999L12.3989 9.25C12.7152 8.27076 13.6343 7.56248 14.7188 7.56248C16.065 7.56248 17.1563 8.65379 17.1563 9.99998C17.1563 11.3462 16.065 12.4375 14.7188 12.4375C13.6343 12.4375 12.7152 11.7292 12.3989 10.75L10.4057 10.75V14.3125C10.4057 14.727 10.7411 15.0625 11.1557 15.0625L12.3989 15.0625C12.7152 14.0832 13.6343 13.375 14.7188 13.375C16.065 13.375 17.1563 14.4663 17.1563 15.8125C17.1563 17.1587 16.065 18.25 14.7188 18.25C13.6343 18.25 12.7152 17.5417 12.3989 16.5625L11.1557 16.5625C9.91274 16.5625 8.90568 15.5555 8.90568 14.3125V10.75L6.91344 10.75C6.59711 11.7292 5.67802 12.4375 4.59351 12.4375C3.24731 12.4375 2.15601 11.3462 2.15601 9.99998C2.15601 8.65379 3.24731 7.56248 4.59351 7.56248C5.67802 7.56248 6.59711 8.27076 6.91344 9.24998L8.90568 9.24999V5.68752C8.90568 4.44456 9.91272 3.43752 11.1557 3.43752L12.3989 3.43751Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
     </svg>

www/docs/src/theme/Icon/CheckCircleSolid/index.tsx

@@ -20,7 +20,7 @@ const IconCheckCircleSolid: React.FC<IconProps> = ({
         d="M10 18C12.1217 18 14.1566 17.1571 15.6569 15.6569C17.1571 14.1566 18 12.1217 18 10C18 7.87827 17.1571 5.84344 15.6569 4.34315C14.1566 2.84285 12.1217 2 10 2C7.87827 2 5.84344 2.84285 4.34315 4.34315C2.84285 5.84344 2 7.87827 2 10C2 12.1217 2.84285 14.1566 4.34315 15.6569C5.84344 17.1571 7.87827 18 10 18ZM13.857 8.191C13.9149 8.11129 13.9566 8.02095 13.9796 7.92514C14.0026 7.82933 14.0065 7.72994 13.991 7.63262C13.9756 7.5353 13.9412 7.44198 13.8897 7.35797C13.8382 7.27396 13.7707 7.20091 13.691 7.143C13.6113 7.08509 13.5209 7.04344 13.4251 7.02044C13.3293 6.99744 13.2299 6.99354 13.1326 7.00895C13.0353 7.02437 12.942 7.0588 12.858 7.11028C12.774 7.16176 12.7009 7.22929 12.643 7.309L9.16 12.099L7.28 10.219C7.21078 10.1474 7.128 10.0903 7.03647 10.051C6.94495 10.0118 6.84653 9.99114 6.74694 9.99032C6.64736 9.9895 6.54861 10.0085 6.45646 10.0463C6.3643 10.084 6.28059 10.1398 6.2102 10.2102C6.13982 10.2807 6.08417 10.3644 6.0465 10.4566C6.00883 10.5488 5.9899 10.6476 5.99081 10.7472C5.99173 10.8467 6.01246 10.9451 6.05181 11.0366C6.09116 11.1281 6.14834 11.2108 6.22 11.28L8.72 13.78C8.79663 13.8567 8.88896 13.9158 8.99065 13.9534C9.09233 13.9909 9.20094 14.006 9.30901 13.9975C9.41708 13.9891 9.52203 13.9573 9.61663 13.9044C9.71123 13.8515 9.79324 13.7787 9.857 13.691L13.857 8.191Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
     </svg>

www/docs/src/theme/Icon/ChevronDoubleLeftMiniSolid/index.tsx

@@ -20,7 +20,7 @@ const IconChevronDoubleLeftMiniSolid: React.FC<IconProps> = ({
         d="M15.79 14.77C15.6521 14.9131 15.4629 14.9957 15.2641 14.9994C15.0654 15.0032 14.8733 14.9278 14.73 14.79L10.23 10.54C10.1574 10.47 10.0997 10.3862 10.0602 10.2934C10.0208 10.2006 10.0005 10.1008 10.0005 10C10.0005 9.89919 10.0208 9.79941 10.0602 9.70663C10.0997 9.61385 10.1574 9.52997 10.23 9.46001L14.73 5.21001C14.8002 5.13826 14.8841 5.08133 14.9767 5.0426C15.0693 5.00386 15.1687 4.98411 15.2691 4.9845C15.3695 4.9849 15.4687 5.00544 15.561 5.04491C15.6533 5.08437 15.7367 5.14196 15.8064 5.21427C15.876 5.28657 15.9304 5.37211 15.9663 5.46582C16.0023 5.55953 16.0191 5.65951 16.0157 5.75982C16.0123 5.86014 15.9888 5.95875 15.9466 6.04983C15.9044 6.1409 15.8444 6.22257 15.77 6.29001L11.832 10L15.77 13.71C15.9131 13.848 15.9957 14.0371 15.9994 14.2359C16.0032 14.4346 15.9278 14.6267 15.79 14.77ZM9.79001 14.77C9.65205 14.9131 9.46291 14.9957 9.26415 14.9994C9.06539 15.0032 8.87327 14.9278 8.73001 14.79L4.23001 10.54C4.15742 10.47 4.09968 10.3862 4.06025 10.2934C4.02081 10.2006 4.00049 10.1008 4.00049 10C4.00049 9.89919 4.02081 9.79941 4.06025 9.70663C4.09968 9.61385 4.15742 9.52997 4.23001 9.46001L8.73001 5.21001C8.8002 5.13826 8.88408 5.08133 8.97668 5.0426C9.06928 5.00386 9.16871 4.98411 9.26908 4.9845C9.36945 4.9849 9.46873 5.00544 9.56102 5.04491C9.6533 5.08437 9.73673 5.14196 9.80635 5.21427C9.87598 5.28657 9.93038 5.37211 9.96634 5.46582C10.0023 5.55953 10.0191 5.65951 10.0157 5.75982C10.0123 5.86014 9.98881 5.95875 9.9466 6.04983C9.9044 6.1409 9.84435 6.22257 9.77001 6.29001L5.83201 10L9.77001 13.71C9.91314 13.848 9.99565 14.0371 9.9994 14.2359C10.0032 14.4346 9.92784 14.6267 9.79001 14.77Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
     </svg>

www/docs/src/theme/Icon/CircleDottedLine/index.tsx

@@ -0,0 +1,81 @@
+import React from "react"
+import { IconProps } from ".."
+
+const IconCircleDottedLine: React.FC<IconProps> = ({
+  iconColorClassName,
+  ...props
+}) => {
+  return (
+    <svg
+      width={props.width || 20}
+      height={props.height || 20}
+      viewBox="0 0 20 20"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <path
+        d="M12.5 2.93589C10.884 2.3547 9.116 2.3547 7.5 2.93589"
+        className={
+          iconColorClassName ||
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
+        }
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M2.63049 8.63198C2.94295 6.94471 3.82573 5.41606 5.13094 4.30209"
+        className={
+          iconColorClassName ||
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
+        }
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M5.13094 15.6979C3.82575 14.5839 2.94298 13.0552 2.63049 11.368"
+        className={
+          iconColorClassName ||
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
+        }
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M7.5 17.0641C9.116 17.6453 10.884 17.6453 12.5 17.0641"
+        className={
+          iconColorClassName ||
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
+        }
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M17.3695 8.63198C17.057 6.94471 16.1742 5.41606 14.869 4.30209"
+        className={
+          iconColorClassName ||
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
+        }
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M14.869 15.6979C16.1742 14.5839 17.057 13.0552 17.3695 11.368"
+        className={
+          iconColorClassName ||
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
+        }
+        strokeWidth="1.5"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </svg>
+  )
+}
+
+export default IconCircleDottedLine

www/docs/src/theme/Icon/CircleMiniSolid/index.tsx

@@ -0,0 +1,31 @@
+import React from "react"
+import { IconProps } from ".."
+
+const IconCircleMiniSolid: React.FC<IconProps> = ({
+  iconColorClassName,
+  ...props
+}) => {
+  return (
+    <svg
+      width={props.width || 20}
+      height={props.height || 20}
+      viewBox="0 0 20 20"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <circle
+        cx="10"
+        cy="10"
+        r="5.25"
+        strokeWidth="1.5"
+        className={
+          iconColorClassName ||
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
+        }
+      />
+    </svg>
+  )
+}
+
+export default IconCircleMiniSolid

www/docs/src/theme/Icon/CircleStack/index.tsx

@@ -18,7 +18,7 @@ const IconCircleStack: React.FC<IconProps> = ({
         d="M16.875 5.3125C16.875 7.21083 13.7967 8.75 10 8.75C6.20333 8.75 3.125 7.21083 3.125 5.3125M16.875 5.3125C16.875 3.41417 13.7967 1.875 10 1.875C6.20333 1.875 3.125 3.41417 3.125 5.3125M16.875 5.3125V14.6875C16.875 16.5858 13.7967 18.125 10 18.125C6.20333 18.125 3.125 16.5858 3.125 14.6875V5.3125M16.875 5.3125V8.4375M3.125 5.3125V8.4375M16.875 8.4375V11.5625C16.875 13.4608 13.7967 15 10 15C6.20333 15 3.125 13.4608 3.125 11.5625V8.4375M16.875 8.4375C16.875 10.3358 13.7967 11.875 10 11.875C6.20333 11.875 3.125 10.3358 3.125 8.4375"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1.25"
         strokeLinecap="round"

www/docs/src/theme/Icon/CircleStackSolid/index.tsx

@@ -18,28 +18,28 @@ const IconCircleStackSolid: React.FC<IconProps> = ({
         d="M17.5 5.3125C17.5 7.55583 14.1417 9.375 10 9.375C5.85833 9.375 2.5 7.55583 2.5 5.3125C2.5 3.06917 5.85833 1.25 10 1.25C14.1417 1.25 17.5 3.06917 17.5 5.3125Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
       <path
         d="M10 10.625C12.2375 10.625 14.325 10.1367 15.8983 9.28419C16.4774 8.97677 17.0097 8.58843 17.4792 8.13086C17.4925 8.23169 17.5 8.33419 17.5 8.43753C17.5 10.6809 14.1417 12.5 10 12.5C5.85833 12.5 2.5 10.6809 2.5 8.43753C2.5 8.33419 2.5075 8.23169 2.52083 8.13086C2.99035 8.58841 3.52264 8.97675 4.10167 9.28419C5.67417 10.1367 7.7625 10.625 10 10.625Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
       <path
         d="M10 13.75C12.2375 13.75 14.325 13.2617 15.8983 12.4092C16.4774 12.1018 17.0097 11.7134 17.4792 11.2559C17.4925 11.3567 17.5 11.4592 17.5 11.5625C17.5 13.8059 14.1417 15.625 10 15.625C5.85833 15.625 2.5 13.8059 2.5 11.5625C2.5 11.4592 2.5075 11.3567 2.52083 11.2559C2.99034 11.7134 3.52263 12.1018 4.10167 12.4092C5.67417 13.2617 7.7625 13.75 10 13.75Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
       <path
         d="M10 16.875C12.2375 16.875 14.325 16.3867 15.8983 15.5342C16.4774 15.2268 17.0097 14.8384 17.4792 14.3809C17.4925 14.4817 17.5 14.5842 17.5 14.6875C17.5 16.9309 14.1417 18.75 10 18.75C5.85833 18.75 2.5 16.9309 2.5 14.6875C2.5 14.5842 2.5075 14.4817 2.52083 14.3809C2.99034 14.8384 3.52263 15.2268 4.10167 15.5342C5.67417 16.3867 7.7625 16.875 10 16.875Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
     </svg>

www/docs/src/theme/Icon/ClockSolidMini/index.tsx

@@ -20,7 +20,7 @@ const IconClockSolidMini: React.FC<IconProps> = ({
         d="M4 10C4 6.68629 6.68629 4 10 4C13.3137 4 16 6.68629 16 10C16 13.3137 13.3137 16 10 16C6.68629 16 4 13.3137 4 10ZM10 5.75C10.4142 5.75 10.75 6.08579 10.75 6.5V9.63051L13.1914 10.2748C13.5919 10.3805 13.8309 10.7909 13.7252 11.1914C13.6195 11.5919 13.2091 11.8309 12.8086 11.7252L9.80862 10.9334C9.47938 10.8465 9.25 10.5488 9.25 10.2083V6.5C9.25 6.08579 9.58579 5.75 10 5.75Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
     </svg>

www/docs/src/theme/Icon/Close/index.tsx

@@ -15,7 +15,7 @@ const IconClose: React.FC<IconProps> = ({ iconColorClassName, ...props }) => {
         d="M6 14L14 6M6 6L14 14"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth={props.strokeWidth}
         strokeLinecap="round"

www/docs/src/theme/Icon/CloudArrowUp/index.tsx

@@ -18,7 +18,7 @@ const IconCloudArrowUp: React.FC<IconProps> = ({
         d="M10.0002 13.7499V8.12494M10.0002 8.12494L12.5002 10.6249M10.0002 8.12494L7.50017 10.6249M5.62517 16.2499C4.73303 16.2509 3.86977 15.9338 3.19042 15.3555C2.51107 14.7772 2.06013 13.9757 1.9186 13.0949C1.77706 12.214 1.95419 11.3116 2.41819 10.5496C2.88218 9.78761 3.60264 9.21601 4.45017 8.93744C4.23242 7.82174 4.45747 6.6651 5.07766 5.71245C5.69785 4.75979 6.66448 4.08593 7.77285 3.83356C8.88122 3.58119 10.0443 3.77013 11.0158 4.36036C11.9873 4.9506 12.6909 5.89579 12.9777 6.99577C13.421 6.85158 13.8958 6.83423 14.3485 6.94568C14.8012 7.05713 15.2137 7.29294 15.5394 7.62647C15.8652 7.96 16.0911 8.37796 16.1918 8.83315C16.2926 9.28835 16.264 9.76263 16.1093 10.2024C16.7915 10.463 17.361 10.9542 17.719 11.5907C18.0769 12.2273 18.2008 12.969 18.069 13.6873C17.9373 14.4056 17.5583 15.0552 16.9977 15.5232C16.4372 15.9913 15.7305 16.2484 15.0002 16.2499H5.62517Z"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1.5"
         strokeLinecap="round"

www/docs/src/theme/Icon/CogSixTooth/index.tsx

@@ -18,7 +18,7 @@ const IconCogSixTooth: React.FC<IconProps> = ({
         d="M7.99509 3.28333C8.07009 2.83167 8.46176 2.5 8.92009 2.5H11.0809C11.5393 2.5 11.9309 2.83167 12.0059 3.28333L12.1834 4.35083C12.2359 4.6625 12.4443 4.9225 12.7209 5.07583C12.7826 5.10917 12.8434 5.145 12.9043 5.18167C13.1743 5.345 13.5043 5.39583 13.8001 5.285L14.8143 4.905C15.0221 4.82684 15.2509 4.82498 15.46 4.89976C15.6691 4.97454 15.8448 5.1211 15.9559 5.31333L17.0359 7.18583C17.1468 7.37809 17.1859 7.60344 17.1462 7.8218C17.1065 8.04017 16.9907 8.23737 16.8193 8.37833L15.9834 9.0675C15.7393 9.2675 15.6184 9.57833 15.6243 9.89417C15.6256 9.96499 15.6256 10.0358 15.6243 10.1067C15.6184 10.4217 15.7393 10.7317 15.9826 10.9317L16.8201 11.6217C17.1734 11.9133 17.2651 12.4167 17.0368 12.8133L15.9551 14.6858C15.8441 14.878 15.6686 15.0246 15.4597 15.0996C15.2508 15.1745 15.0221 15.1729 14.8143 15.095L13.8001 14.715C13.5043 14.6042 13.1751 14.655 12.9034 14.8183C12.843 14.8551 12.7819 14.8906 12.7201 14.925C12.4443 15.0775 12.2359 15.3375 12.1834 15.6492L12.0059 16.7158C11.9309 17.1683 11.5393 17.5 11.0809 17.5H8.91926C8.46092 17.5 8.06926 17.1683 7.99426 16.7167L7.81676 15.6492C7.76509 15.3375 7.55676 15.0775 7.28009 14.9242C7.2183 14.8901 7.15717 14.8548 7.09676 14.8183C6.82592 14.655 6.49676 14.6042 6.20009 14.715L5.18592 15.095C4.9782 15.1729 4.74956 15.1747 4.54067 15.0999C4.33178 15.0251 4.15618 14.8787 4.04509 14.6867L2.96426 12.8142C2.85338 12.6219 2.8143 12.3966 2.85397 12.1782C2.89364 11.9598 3.0095 11.7626 3.18092 11.6217L4.01759 10.9325C4.26092 10.7325 4.38176 10.4217 4.37592 10.1058C4.37462 10.035 4.37462 9.96416 4.37592 9.89333C4.38176 9.57833 4.26092 9.26833 4.01759 9.06833L3.18092 8.37833C3.00971 8.23741 2.89399 8.04036 2.85432 7.82219C2.81465 7.60401 2.8536 7.37884 2.96426 7.18667L4.04509 5.31417C4.15608 5.12178 4.33177 4.97505 4.54085 4.90011C4.74993 4.82518 4.97883 4.82691 5.18676 4.905L6.20009 5.285C6.49676 5.39583 6.82592 5.345 7.09676 5.18167C7.15676 5.145 7.21842 5.10917 7.28009 5.075C7.55676 4.9225 7.76509 4.6625 7.81676 4.35083L7.99509 3.28333V3.28333Z"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1.5"
         strokeLinecap="round"
@@ -28,7 +28,7 @@ const IconCogSixTooth: React.FC<IconProps> = ({
         d="M12.5 10C12.5 10.663 12.2366 11.2989 11.7678 11.7678C11.2989 12.2366 10.663 12.5 10 12.5C9.33696 12.5 8.70107 12.2366 8.23223 11.7678C7.76339 11.2989 7.5 10.663 7.5 10C7.5 9.33696 7.76339 8.70107 8.23223 8.23223C8.70107 7.76339 9.33696 7.5 10 7.5C10.663 7.5 11.2989 7.76339 11.7678 8.23223C12.2366 8.70107 12.5 9.33696 12.5 10V10Z"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1.5"
         strokeLinecap="round"

www/docs/src/theme/Icon/CogSixToothSolid/index.tsx

@@ -20,7 +20,7 @@ const IconCogSixToothSolid: React.FC<IconProps> = ({
         d="M9.23166 1.875C8.46749 1.875 7.81582 2.4275 7.68999 3.18083L7.54166 4.07417C7.52499 4.17417 7.44582 4.29083 7.29416 4.36417C7.00862 4.50143 6.73393 4.66022 6.47249 4.83917C6.33416 4.935 6.19416 4.94417 6.09749 4.90833L5.24999 4.59C4.90353 4.4602 4.52224 4.45755 4.174 4.58253C3.82577 4.70751 3.53318 4.95201 3.34832 5.2725L2.57999 6.60333C2.39507 6.92363 2.32975 7.29915 2.39567 7.66307C2.46159 8.027 2.65447 8.35575 2.93999 8.59083L3.63999 9.1675C3.71916 9.2325 3.78166 9.35833 3.76832 9.52583C3.74458 9.84178 3.74458 10.1591 3.76832 10.475C3.78082 10.6417 3.71916 10.7683 3.64082 10.8333L2.93999 11.41C2.65447 11.6451 2.46159 11.9738 2.39567 12.3378C2.32975 12.7017 2.39507 13.0772 2.57999 13.3975L3.34832 14.7283C3.53331 15.0487 3.82596 15.293 4.17418 15.4178C4.5224 15.5426 4.90362 15.5399 5.24999 15.41L6.09916 15.0917C6.19499 15.0558 6.33499 15.0658 6.47416 15.16C6.73416 15.3383 7.00832 15.4975 7.29499 15.635C7.44666 15.7083 7.52582 15.825 7.54249 15.9267L7.69082 16.8192C7.81666 17.5725 8.46832 18.125 9.23249 18.125H10.7692C11.5325 18.125 12.185 17.5725 12.3108 16.8192L12.4592 15.9258C12.4758 15.8258 12.5542 15.7092 12.7067 15.635C12.9933 15.4975 13.2675 15.3383 13.5275 15.16C13.6667 15.065 13.8067 15.0558 13.9025 15.0917L14.7525 15.41C15.0987 15.5394 15.4797 15.5418 15.8275 15.4168C16.1754 15.2919 16.4677 15.0476 16.6525 14.7275L17.4217 13.3967C17.6066 13.0764 17.6719 12.7009 17.606 12.3369C17.5401 11.973 17.3472 11.6443 17.0617 11.4092L16.3617 10.8325C16.2825 10.7675 16.22 10.6417 16.2333 10.4742C16.257 10.1582 16.257 9.84095 16.2333 9.525C16.22 9.35833 16.2825 9.23167 16.3608 9.16667L17.0608 8.59C17.6508 8.105 17.8033 7.265 17.4217 6.6025L16.6533 5.27167C16.4683 4.95132 16.1757 4.707 15.8275 4.58218C15.4792 4.45735 15.098 4.46013 14.7517 4.59L13.9017 4.90833C13.8067 4.94417 13.6667 4.93417 13.5275 4.83917C13.2663 4.66025 12.9919 4.50145 12.7067 4.36417C12.5542 4.29167 12.4758 4.175 12.4592 4.07417L12.31 3.18083C12.2492 2.81589 12.0609 2.48435 11.7786 2.24522C11.4963 2.0061 11.1383 1.87491 10.7683 1.875H9.23249H9.23166ZM9.99999 13.125C10.8288 13.125 11.6236 12.7958 12.2097 12.2097C12.7958 11.6237 13.125 10.8288 13.125 10C13.125 9.1712 12.7958 8.37634 12.2097 7.79029C11.6236 7.20424 10.8288 6.875 9.99999 6.875C9.17119 6.875 8.37633 7.20424 7.79028 7.79029C7.20423 8.37634 6.87499 9.1712 6.87499 10C6.87499 10.8288 7.20423 11.6237 7.79028 12.2097C8.37633 12.7958 9.17119 13.125 9.99999 13.125Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
     </svg>

www/docs/src/theme/Icon/CommandLine/index.tsx

@@ -18,7 +18,7 @@ const IconCommandLine: React.FC<IconProps> = ({
         d="M5.625 6.25L8.125 8.125L5.625 10M9.375 10H11.875M4.375 16.875H15.625C16.1223 16.875 16.5992 16.6775 16.9508 16.3258C17.3025 15.9742 17.5 15.4973 17.5 15V5C17.5 4.50272 17.3025 4.02581 16.9508 3.67417C16.5992 3.32254 16.1223 3.125 15.625 3.125H4.375C3.87772 3.125 3.40081 3.32254 3.04917 3.67417C2.69754 4.02581 2.5 4.50272 2.5 5V15C2.5 15.4973 2.69754 15.9742 3.04917 16.3258C3.40081 16.6775 3.87772 16.875 4.375 16.875Z"
         className={
           iconColorClassName ||
-          "tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1.5"
         strokeLinecap="round"

www/docs/src/theme/Icon/CommandLineSolid/index.tsx

@@ -20,7 +20,7 @@ const IconCommandLineSolid: React.FC<IconProps> = ({
         d="M3.63622 3.40051C3.07362 3.40051 2.53407 3.624 2.13626 4.02182C1.73844 4.41963 1.51495 4.95918 1.51495 5.52178V14.4782C1.51495 15.0408 1.73844 15.5804 2.13626 15.9782C2.53407 16.376 3.07362 16.5995 3.63622 16.5995H16.3638C16.6424 16.5995 16.9182 16.5446 17.1756 16.438C17.4329 16.3314 17.6668 16.1752 17.8638 15.9782C18.0607 15.7812 18.217 15.5474 18.3236 15.29C18.4302 15.0326 18.4851 14.7568 18.4851 14.4782V5.52178C18.4851 5.24321 18.4302 4.96737 18.3236 4.71C18.217 4.45264 18.0607 4.21879 17.8638 4.02182C17.6668 3.82484 17.4329 3.66859 17.1756 3.56198C16.9182 3.45538 16.6424 3.40051 16.3638 3.40051H3.63622ZM4.52526 11.6518C4.46299 11.5828 4.41492 11.5022 4.38382 11.4146C4.35272 11.327 4.33919 11.2341 4.34401 11.1413C4.34882 11.0485 4.37189 10.9576 4.41189 10.8737C4.45189 10.7898 4.50803 10.7146 4.57712 10.6524L6.34955 9.05722L4.57712 7.46108C4.50591 7.39956 4.4477 7.32445 4.40589 7.24014C4.36409 7.15583 4.33954 7.06402 4.33367 6.9701C4.32781 6.87618 4.34075 6.78204 4.37174 6.69318C4.40273 6.60433 4.45114 6.52255 4.51414 6.45265C4.57714 6.38275 4.65346 6.32612 4.73863 6.2861C4.82379 6.24607 4.91609 6.22345 5.01011 6.21955C5.10414 6.21566 5.19799 6.23057 5.28618 6.26341C5.37436 6.29625 5.4551 6.34637 5.52367 6.41082L7.88063 8.53209C7.95416 8.59839 8.01294 8.67939 8.05318 8.76985C8.09342 8.86031 8.11421 8.95821 8.11421 9.05722C8.11421 9.15622 8.09342 9.25412 8.05318 9.34458C8.01294 9.43504 7.95416 9.51605 7.88063 9.58235L5.52367 11.7036C5.45468 11.7659 5.37409 11.814 5.2865 11.8451C5.19892 11.8762 5.10606 11.8897 5.01325 11.8849C4.92043 11.8801 4.82947 11.857 4.74558 11.817C4.66168 11.777 4.58744 11.7208 4.52526 11.6518ZM9.76431 10.2357C9.57678 10.2357 9.39693 10.3102 9.26433 10.4428C9.13172 10.5754 9.05722 10.7553 9.05722 10.9428C9.05722 11.1303 9.13172 11.3102 9.26433 11.4428C9.39693 11.5754 9.57678 11.6499 9.76431 11.6499H12.1213C12.3088 11.6499 12.4887 11.5754 12.6213 11.4428C12.7539 11.3102 12.8284 11.1303 12.8284 10.9428C12.8284 10.7553 12.7539 10.5754 12.6213 10.4428C12.4887 10.3102 12.3088 10.2357 12.1213 10.2357H9.76431Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark"
         }
       />
     </svg>

www/docs/src/theme/Icon/ComponentSolid/index.tsx

@@ -18,7 +18,7 @@ const IconComponentSolid: React.FC<IconProps> = ({
         d="M5.125 7.37509L7.75 10.0001L5.125 12.6251L2.5 10.0001L5.125 7.37509Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1.5"
         strokeLinecap="round"
@@ -28,7 +28,7 @@ const IconComponentSolid: React.FC<IconProps> = ({
         d="M9.99969 2.5L12.6247 5.125L9.99969 7.75L7.37469 5.125L9.99969 2.5Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1.5"
         strokeLinecap="round"
@@ -38,7 +38,7 @@ const IconComponentSolid: React.FC<IconProps> = ({
         d="M14.8752 7.37509L17.5002 10.0001L14.8752 12.6251L12.2502 10.0001L14.8752 7.37509Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1.5"
         strokeLinecap="round"
@@ -48,7 +48,7 @@ const IconComponentSolid: React.FC<IconProps> = ({
         d="M9.99969 12.25L12.6247 14.875L9.99969 17.5L7.37469 14.875L9.99969 12.25Z"
         className={
           iconColorClassName ||
-          "tw-fill-medusa-icon-secondary dark:tw-fill-medusa-icon-secondary-dark tw-stroke-medusa-icon-secondary dark:tw-stroke-medusa-icon-secondary"
+          "tw-fill-medusa-icon-subtle dark:tw-fill-medusa-icon-subtle-dark tw-stroke-medusa-icon-subtle dark:tw-stroke-medusa-icon-subtle"
         }
         strokeWidth="1.5"
         strokeLinecap="round"