From a582035870d11030cc217b014479b94dc928ba92 Mon Sep 17 00:00:00 2001
From: Sebastian Sebald <sebastian.sebald@reservix.de>
Date: Wed, 2 Oct 2024 12:53:58 +0200
Subject: [PATCH] docs: Update the `MarigoldProvider` page (#4180)

* almost

* marigold provider resisted

* Create tidy-needles-sort.md

* Update provider.mdx

* update

* added <>
---
 .changeset/tidy-needles-sort.md               |  7 ++
 .../provider/provider-root-styles.demo.tsx    | 12 ++++
 .../application/provider/provider.mdx         | 65 +++++++++++++------
 3 files changed, 63 insertions(+), 21 deletions(-)
 create mode 100644 .changeset/tidy-needles-sort.md
 create mode 100644 docs/content/components/application/provider/provider-root-styles.demo.tsx

diff --git a/.changeset/tidy-needles-sort.md b/.changeset/tidy-needles-sort.md
new file mode 100644
index 0000000000..5c087a7929
--- /dev/null
+++ b/.changeset/tidy-needles-sort.md
@@ -0,0 +1,7 @@
+---
+"@marigold/docs": patch
+---
+
+docs: Update the `MarigoldProvider` page
+
+Updated the MarigoldProvider page according to our new page layout and information.
diff --git a/docs/content/components/application/provider/provider-root-styles.demo.tsx b/docs/content/components/application/provider/provider-root-styles.demo.tsx
new file mode 100644
index 0000000000..147ec44299
--- /dev/null
+++ b/docs/content/components/application/provider/provider-root-styles.demo.tsx
@@ -0,0 +1,12 @@
+import { Card, Inset, MarigoldProvider } from '@marigold/components';
+import theme from '@marigold/theme-core';
+
+export default () => (
+  <MarigoldProvider theme={theme} className="bg-bg-surface-sunken rounded-lg">
+    <Inset space={6}>
+      <Card p={4}>
+        This card will always be on a sunken surface with rounded corners.
+      </Card>
+    </Inset>
+  </MarigoldProvider>
+);
diff --git a/docs/content/components/application/provider/provider.mdx b/docs/content/components/application/provider/provider.mdx
index 3f222b1bf8..5406a85843 100644
--- a/docs/content/components/application/provider/provider.mdx
+++ b/docs/content/components/application/provider/provider.mdx
@@ -1,42 +1,65 @@
 ---
 title: MarigoldProvider
-caption: Provider which applies the theme.
+caption: Container for apps using Marigold.
 ---
 
-`<MarigoldProvider>` is the container for all Marigold applications. It defines the theme and other application level settings.
-Without the `<MarigoldProvider>` you can't get the theme on your components. So it is necessary to use.
+The `<MarigoldProvider>` component serves as the wrapper for any application that integrates with Marigold. It is responsible for managing and distributing critical application-level settings, including providing theming to all child components.
 
-You just have to wrap your components around the `<MarigoldProvider>` to make it work.
-If you want to get more information about the setup go to [Getting Started](/getting-started/installation/#bootstrapping).
+By wrapping an app in `<MarigoldProvider>`, developers can ensure that a consistent theme and other globally relevant configurations are propagated throughout the app's component tree.
 
-```tsx
-import { Button, MarigoldProvider } from '@marigold/components';
+## Appearance
 
-<MarigoldProvider theme={theme}>
-  <Button variant="primary">Hello World!</Button>
-</MarigoldProvider>;
-```
+The `<MarigoldProvider>` component does not have its own visual appearance. However, it hosts the root styles of a theme, ensuring that global styles and theming are applied across the entire app.
+
+## Usage
+
+### Setup
 
-## Import
+It is recommended to place `<MarigoldProvider>` in its own file, alongside other providers you may use, and wrap your root component with it. This approach keeps your project structure organized and ensures that global settings like theming are applied consistently across your app.
 
 ```tsx
+import { PropsWithChildren } from 'react';
 import { MarigoldProvider } from '@marigold/components';
+import theme from '@marigold/theme-core';
+
+export const App = ({ children }: PropsWithChildren) => (
+  <MarigoldProvider theme={theme}>{children}</MarigoldProvider>
+);
 ```
 
-## Props
+### Overriding root styles
 
-<PropsTable component={title} />
+The `<MarigoldProvider>` supports overriding root styles by passing custom class names to it. This feature is useful when you need to adjust or customize the root styles, depending on the context in which your app is used.
 
-## Examples
+<ComponentDemo file="./provider-root-styles.demo.tsx" />
 
-### Provider with Button
+### Nesting Providers
 
-The example shows how the `<MarigoldProvider>` works. As simple as it is you just have to wrap the component around the provider and import a theme. You can click on the theme select on top of the page to see how the `<Button>` changes its theme.
+The `<MarigoldProvider>` supports nesting themes, allowing you to apply a different theme within a nested provider. This enables sections of your app to have distinct themes, providing flexibility in styling different parts of the application.
+
+Note that in these scenarios, it often makes sense to adjust the root styles using the aforementioned `className` prop.
 
 ```tsx
-import { Button, MarigoldProvider } from '@marigold/components';
+import { Card, MarigoldProvider, Stack } from '@marigold/components';
+import core from '@marigold/theme-core';
+import b2b from '@marigold/theme-core';
 
-<MarigoldProvider theme={theme}>
-  <Button variant="primary">Hello World!</Button>
-</MarigoldProvider>;
+export default () => (
+  <MarigoldProvider theme={core}>
+    <Card p={4}>
+      <Stack space={4}>
+        This area is still using the <strong>core theme</strong>.
+        <MarigoldProvider theme={b2b} className="bg-transparent">
+          This area is still using the <strong>b2b theme</strong>.
+        </MarigoldProvider>
+      </Stack>
+    </Card>
+  </MarigoldProvider>
+);
 ```
+
+## Props
+
+<StorybookHintMessage component={title} />
+
+<PropsTable component={title} />