docs: new getting started page! (#3247)

docs/content/introduction/getting-started.mdx

@@ -1,65 +1,194 @@
 ---
 title: Getting Started
-caption: This page describes how to get started building an application with Marigold.
+caption: How to setup and get started with Marigold.
 order: 1
 ---
 
-## Installation
+To integrate Marigold into your React app, follow the steps outlined below. Marigold provides a wide range of pre-designed UI components. However, Marigold's components come with no styling by default. To ensure a perfect fit with your product's appearance, you must also install one of the predefined themes.
 
-To install Marigold you can use any common package managers like [yarn](https://yarnpkg.com/) [pnpm](https://pnpm.io/) or [npm](https://www.npmjs.com/).
+Please bear in mind that certain steps may vary depending on your specific setup. You can find examples for the most common setups down below.
 
-**With npm:**
+<Message messageTitle="Good to know!" variant="info">
+  Experience Marigold right away by trying it out in our [interactive
+  playground](https://play.marigold-ui.io/)!
+</Message>
 
-```bash
-npm install @marigold/components --save
-```
+## 1. Installation
 
-**With yarn:**
+Begin by instaling the core Marigold package (`@marigold/components`) into your app using your preferred package manager. This package is always required, regardless of the theme you choose to apply later.
 
-```bash
-yarn add @marigold/components
-```
+Execute the following command in your project's directory:
+
+<Tabs>
+  <Tabs.Item key="npm" title="npm">
+
+    {/* prettier-ignore */}
+    ```bash
+    npm install @marigold/components --save
+    ```
+
+  </Tabs.Item>
+  <Tabs.Item key="pnpm" title="pnpm">
+
+    {/* prettier-ignore */}
+    ```bash
+    pnpm add @marigold/components
+    ```
+
+  </Tabs.Item>
+  <Tabs.Item key="yarn" title="yarn">
+
+    {/* prettier-ignore */}
+    ```bash
+    yarn add @marigold/components
+    ```
+
+  </Tabs.Item>
+</Tabs>
+
+## 2. Theming
+
+As mentioned earlier, Marigold components come without any styles by default. To customize their appearance, you can choose from the existing themes listed below:
+
+- **b2b:** Ideal for developing new standalone software applications.
+- **core:** Suitable for developing or refactoring components within the Reservix System.
+
+Selecting a theme will enable you to seamlessly apply a consistent look and feel to all components, ensuring they harmonize with the rest of your app. Each theme comes as its own package:
+
+- `@marigold/theme-b2b` will give you the appearance for standalone software.
+- `@marigold/theme-core` will match the look and feel of the Reservix System.
+
+Once you have decided on a theme, proceed to install it using your preferred package manager, similar to the way you installed the `@marigold/components` package earlier.
+
+## 3. Tooling
+
+Marigold effortlessly integrates with popular bundlers such as [webpack](https://webpack.js.org/), [rollup](https://rollupjs.org/), [esbuild](https://esbuild.github.io/), and [vite](https://vitejs.dev/), as well as frameworks like [Next.js](https://nextjs.org/), without requiring any additional configurations.
+
+That being said, we strongly recommend adhering to the guidance provided by the React Team. If you are creating a new app or a site entirely with React, it is advisable to use a framework. You can find more details about this recommendation in the [React
+docs](https://react.dev/learn/start-a-new-react-project).
+
+Furthermore, if you are using TypeScript, ensure that you add `@types/react` and `@react/types-dom` to your project. Marigold's components are fully typed, enabling you to benefit from static type checking and IDE autocomplete features for enhanced development efficiency.
+
+## 4. Bootstrapping
+
+To set up Marigold in your project, you have two options based on the scale and needs of your app. Regardless of the chosen setup, it is essential to add the `MarigoldProvider` to your application's root. This ensures that components can access the theme and apply their corresponding styles.
 
-**With pnpm:**
+### Using the provided CSS file
 
-```bash
-pnpm add @marigold/components
+The easiest way to start is by using the provided CSS file that comes with each theme. While this method allows for a quick start, it does not offer customization options beyond using the provided design tokens. This setup is sufficient for smaller and simpler applications.
+
+```jsx
+/**
+ * 1. Import the CSS file and theme
+ */
+import '@marigold/theme-b2b/index.css';
+import theme from '@marigold/theme-b2b';
+
+/**
+ * 2. Import the MarigoldProvider
+ */
+import { MarigoldProvider } from '@marigold/components';
+
+/**
+ * 3. Wrap your app into the MarigoldProvider
+ *    and pass it the selected theme
+ */
+export const App = () => (
+  <MarigoldProvider theme={theme}>{/* Your App */}}</MarigoldProvider>
+);
 ```
 
-In addition to the components, you usually want to install an existing [theme](/introduction/theming).
+### Using Tailwind CSS
 
-<Message messageTitle="Note" variant="info">
-  Please note that [react](https://www.npmjs.com/package/react) >= 17.0.0 and
-  [react-dom](https://www.npmjs.com/package/react-dom) >= 17.0.0 are peer
-  dependencies for `@marigold/components`.
-</Message>
+However, if you want to maximize the benefits of Marigold, you should install Tailwind CSS alongside Marigold. This combination not only enables customization and extension of the selected theme but also allows you to take full advantage of Tailwind's features while staying true to our design system.
 
-## Tooling
+To set up Tailwind CSS, please refer to the official [installation guide](https://tailwindcss.com/docs/installation). Once you have completed the installation, add the chosen theme as a preset to the Tailwind CSS config, as shown below:
 
-_Marigold_ works with popular build tools, like [webpack](https://webpack.js.org/), [rollup](https://rollupjs.org/) and [esbuild](https://esbuild.github.io/).
+```ts
+import { Config } from 'tailwindcss/types/config';
+// If you are using another theme, change the name accordingly
+import { preset } from '@marigold/theme-b2b/preset';
 
-If you are using [TypeScript](https://www.typescriptlang.org/) to build your app, be sure to add [@types/react](https://www.npmjs.com/package/@types/react) and [@types/react-dom](https://www.npmjs.com/package/@types/react-dom) to your project. _Marigold_ is written in TypeScript and Marigold components are published with their type definitions so that you can take advantage of static type checking and IDE autocomplete.
+const config: Config = {
+  content: [
+    // Dont forget to add the glob for your app here
+    ...preset.content,
+  ],
+  presets: [preset],
+};
 
-## Bootstrapping
+export default config;
+```
+
+After configuring Tailwind CSS and adding the preset, wrap your app with the MarigoldProvider. Unlike before, you no longer have to import the CSS file of the selected theme separately.
 
-For _Marigold_ to work correctly, you need to wrap your app with the `MarigoldProvider`. This way _Marigold_ components will be able to access styles and SSR will work out of the box.
+Tailwind CSS will automatically generate the required CSS for you. However, remember to import the generated CSS file somewhere in your project. Depending on your setup, this is typically done in the root file where you bootstrap React or, in case of Next.js in our root [layout file](https://nextjs.org/docs/app/building-your-application/routing/pages-and-layouts#layouts).
 
 ```jsx
-import React from 'react';
-import { Button, MarigoldProvider } from '@marigold/components';
+/**
+ * 1. Import the CSS file and theme
+ */
 import theme from '@marigold/theme-b2b';
 
-const App = () => (
-  <MarigoldProvider theme={theme}>
-    <Button variant="primary" onClick={() => alert('Hey there!')}>
-      Hello World
-    </Button>
-  </MarigoldProvider>
+/**
+ * 2. Import the MarigoldProvider
+ */
+import { MarigoldProvider } from '@marigold/components';
+
+/**
+ * 3. Wrap your app into the MarigoldProvider
+ *    and pass it the selected theme
+ */
+export const App = () => (
+  <MarigoldProvider theme={theme}>{/* Your App */}}</MarigoldProvider>
 );
 ```
 
-See the [Provider](../components/provider) and [Button](../components/button) docs for more information about the components used in this example.
+### Adding Fonts
+
+Certain themes, such as the B2B theme, are designed to utilize custom web fonts. To incorporate these fonts, you have two options:
+
+1. Use [Font Source](https://fontsource.org/) to add them.
+2. If you are using Next.js, take advantage of `next/font`, which not only takes care of loading the font but also optimizes the used fonts. You can find more information on loading custom web fonts in Next.js [here](https://nextjs.org/docs/pages/building-your-application/optimizing/fonts).
+
+To load the Inter font with Font Source when using with the B2B theme, you can follow the steps below:
+
+First, add the font as a dependency to your project:
+
+<Tabs>
+  <Tabs.Item key="npm" title="npm">
+
+    {/* prettier-ignore */}
+    ```bash
+    npm install @fontsource-variable/inter --save
+    ```
+
+  </Tabs.Item>
+  <Tabs.Item key="pnpm" title="pnpm">
+
+    {/* prettier-ignore */}
+    ```bash
+    pnpm add @fontsource-variable/inter
+    ```
+
+  </Tabs.Item>
+  <Tabs.Item key="yarn" title="yarn">
+
+    {/* prettier-ignore */}
+    ```bash
+    yarn add @fontsource-variable/inter
+    ```
+
+  </Tabs.Item>
+</Tabs>
+
+Afterwards, import the package into your project.
+
+```js
+// Supports weights 100-900
+import '@fontsource-variable/inter';
+```
 
 ## Next Steps
 
-Now that you've bootstrapped your app, you can dive into the documentation for the available components to understand them in detail read about our principles to learn what drove our decision and which contrains come with our approach.
+Now that you've bootstrapped your app, you can dive into the documentation to [explore the available components](/components) in detail. Additionally, you can read about our principles to understand the driving factors behind our decisions and the constraints associated with our approach.

docs/next.config.js

@@ -23,6 +23,11 @@ const nextConfig = {
         destination: '/introduction/getting-started',
         permanent: true,
       },
+      {
+        source: '/components',
+        destination: '/components/provider',
+        permanent: true,
+      },
     ];
   },
 };

docs/ui/mdx.tsx

@@ -5,7 +5,7 @@ import { useMDXComponent } from 'next-contentlayer/hooks';
 
 import { IconList } from '@/ui/IconList';
 
-import { Headline, Message, Link, Text } from './';
+import { Headline, Message, Link, Text, Tabs } from './';
 import { AppearanceTable } from './AppearanceTable';
 import { PropsTable } from './PropsTable';
 import { ComponentDemo } from './ComponentDemo';
@@ -75,6 +75,7 @@ const components = {
   ComponentDemo,
   Headline,
   Message,
+  Tabs,
   Text,
   IconList,
   AppearanceTable,