From 8ac245b1c3abaa9e43bfbefac9bbae8e6652ead9 Mon Sep 17 00:00:00 2001
From: Kyle Gach <kyle.gach@gmail.com>
Date: Fri, 9 Aug 2024 15:51:28 -0600
Subject: [PATCH 1/5] Futher updates to #28716

- Improve feature flag callouts
- Add API details to migration notes and clarify examples
- Restructure guides to use sub-heading structure instead of snippet tabs
    - Offers ability to explain differences between APIs more thoroughly
    - Also a better experience, because users' tab preference will not apply across snippets
- Clarify example snippets
    - Only demonstate one concept per snippet
- Adjust heading levels
- Add globals API reference section
- Improve snippet filenames
    - Remove redundant `storybook-` prefix
- Prose tweaks
---
 MIGRATION.md                                  |  94 ++--
 ...ounds.md => addon-backgrounds-disabled.md} |  24 +-
 ...gure-grid.md => addon-backgrounds-grid.md} |   0
 .../addon-backgrounds-options-in-meta.md      | 243 ++++++++
 .../addon-backgrounds-options-in-preview.md   |  36 ++
 ... => addon-backgrounds-override-globals.md} |  91 +--
 ...ackgrounds-override-parameters-default.md} |  86 +--
 .../addon-backgrounds-values-in-meta.md       | 231 ++++++++
 .../addon-backgrounds-values-in-preview.md    |  40 ++
 ...addon-backgrounds-configure-backgrounds.md | 523 ------------------
 ...n-backgrounds-override-background-color.md | 455 ---------------
 ...ook-preview-configure-background-colors.md |  72 ---
 docs/essentials/backgrounds.mdx               | 155 ++++--
 13 files changed, 829 insertions(+), 1221 deletions(-)
 rename docs/_snippets/{storybook-addon-backgrounds-disable-backgrounds.md => addon-backgrounds-disabled.md} (89%)
 rename docs/_snippets/{storybook-addon-backgrounds-configure-grid.md => addon-backgrounds-grid.md} (100%)
 create mode 100644 docs/_snippets/addon-backgrounds-options-in-meta.md
 create mode 100644 docs/_snippets/addon-backgrounds-options-in-preview.md
 rename docs/_snippets/{storybook-addon-backgrounds-disable-grid.md => addon-backgrounds-override-globals.md} (50%)
 rename docs/_snippets/{storybook-addon-backgrounds-global-api.md => addon-backgrounds-override-parameters-default.md} (55%)
 create mode 100644 docs/_snippets/addon-backgrounds-values-in-meta.md
 create mode 100644 docs/_snippets/addon-backgrounds-values-in-preview.md
 delete mode 100644 docs/_snippets/storybook-addon-backgrounds-configure-backgrounds.md
 delete mode 100644 docs/_snippets/storybook-addon-backgrounds-override-background-color.md

diff --git a/MIGRATION.md b/MIGRATION.md
index 2bf4f00d9077..c8aa7ef35a48 100644
--- a/MIGRATION.md
+++ b/MIGRATION.md
@@ -421,35 +421,41 @@
 
 ### New parameters format for addon backgrounds
 
-The `addon-backgrounds` addon now uses a new format for parameters. The `backgrounds` parameter is now an object with a `values` key that contains the background values.
+> [!NOTE]
+> You need to set the feature flag `backgroundsStoryGlobals` to `true` in your `.storybook/main.ts` to use the new format and set the value with `globals`.
 
-> ! You need to set the feature flag `backgroundsStoryGlobals` to `true` in your `.storybook/main.ts` to use the new format.
+The `addon-backgrounds` addon now uses a new format for parameters. The `backgrounds` parameter is now an object with an `options` property that is assigned to an object of background values, where the key is used when setting the global value.
 
 ```diff
 // .storybook/preview.js
 export const parameters = {
   backgrounds: {
--    values: [
--      { name: 'twitter', value: '#00aced' },
--      { name: 'facebook', value: '#3b5998' },
--    ],
-+    options: {
-+      twitter: { name: 'twitter', value: '#00aced' },
-+      facebook: { name: 'facebook', value: '#3b5998' },
-+    },
+-   values: [
+-     { name: 'twitter', value: '#00aced' },
+-     { name: 'facebook', value: '#3b5998' },
+-   ],
++   options: {
++     twitter: { name: 'Twitter', value: '#00aced' },
++     facebook: { name: 'Facebook', value: '#3b5998' },
++   },
   },
 };
 ```
 
 Setting an override value should now be done via a `globals` property on your component/meta or story itself:
 
-```ts
+```diff
 // Button.stories.ts
 export default {
   component: Button,
-  globals: {
-    backgrounds: { value: 'twitter' },
-  },
+- parameters: {
+-   backgrounds: {
+-     default: "twitter",
+-   },
+- },
++ globals: {
++   backgrounds: { value: "twitter" },
++ },
 };
 ```
 
@@ -457,49 +463,59 @@ This locks that story to the `twitter` background, it cannot be changed by the a
 
 ### New parameters format for addon viewport
 
-> ! You need to set the feature flag `viewportStoryGlobals` to `true` in your `.storybook/main.ts` to use the new format.
+> [!NOTE]
+> You need to set the feature flag `viewportStoryGlobals` to `true` in your `.storybook/main.ts` to use the new format and set the value with `globals`.
 
-The `addon-viewport` addon now uses a new format for parameters. The `viewport` parameter is now an object with a `viewports` key that contains the viewport values.
+The `addon-viewport` addon now uses a new format for parameters. The `viewport` parameter is now an object with an `options` property that is assigned to an object of viewport values, where the key is used when setting the global value.
 
 ```diff
 // .storybook/preview.js
 export const parameters = {
   viewport: {
--    viewports: {
--      iphone5: {
--        name: 'phone',
--        styles: {
--          width: '320px',
--          height: '568px',
--        },
--      },
+-   viewports: {
+-     iphone5: {
+-       name: 'phone',
+-       styles: {
+-         width: '320px',
+-         height: '568px',
+-       },
 -     },
-+    options: {
-+      iphone5: {
-+        name: 'phone',
-+        styles: {
-+          width: '320px',
-+          height: '568px',
-+        },
-+      },
-+    },
+-    },
++   options: {
++     iphone5: {
++       name: 'phone',
++       styles: {
++         width: '320px',
++         height: '568px',
++       },
++     },
++   },
   },
 };
 ```
 
-Setting an override value should now be done via a `globals` property on your component/meta or story itself:
+Setting an override value should now be done via a `globals` property on your component/meta or story itself. Also note the change from `defaultOrientation: "landscape"` to `isRotated: true`.
 
-```ts
+```diff
 // Button.stories.ts
 export default {
   component: Button,
-  globals: {
-    viewport: { value: 'phone' },
-  },
+- parameters: {
+-   viewport: {
+-     defaultViewport: "iphone5",
+-     defaultOrientation: "landscape",
+-   },
+- },
++ globals: {
++   viewport: {
++     value: "iphone5",
++     isRotated: true,
++   },
++ },
 };
 ```
 
-This locks that story to the `phone` viewport, it cannot be changed by the addon UI.
+This locks that story to the `iphone5` viewport in landscape orientation, it cannot be changed by the addon UI.
 
 ## From version 8.1.x to 8.2.x
 
diff --git a/docs/_snippets/storybook-addon-backgrounds-disable-backgrounds.md b/docs/_snippets/addon-backgrounds-disabled.md
similarity index 89%
rename from docs/_snippets/storybook-addon-backgrounds-disable-backgrounds.md
rename to docs/_snippets/addon-backgrounds-disabled.md
index bcfb5d24950b..7cc4d7f8c235 100644
--- a/docs/_snippets/storybook-addon-backgrounds-disable-backgrounds.md
+++ b/docs/_snippets/addon-backgrounds-disabled.md
@@ -1,4 +1,4 @@
-```js filename="Button.stories.js|jsx" renderer="common" language="js" tabTitle="globals-api"
+```js filename="Button.stories.js|jsx" renderer="common" language="js" tabTitle="Without story globals"
 import { Button } from './Button';
 
 export default {
@@ -7,12 +7,12 @@ export default {
 
 export const Large = {
   parameters: {
-    backgrounds: { disabled: true },
+    backgrounds: { disable: true },
   },
 };
 ```
 
-```js filename="Button.stories.js|jsx" renderer="common" language="js" tabTitle="without-globals"
+```js filename="Button.stories.js|jsx" renderer="common" language="js" tabTitle="With story globals enabled"
 import { Button } from './Button';
 
 export default {
@@ -21,12 +21,12 @@ export default {
 
 export const Large = {
   parameters: {
-    backgrounds: { disable: true },
+    backgrounds: { disabled: true },
   },
 };
 ```
 
-```ts filename="Button.stories.ts|tsx" renderer="common" language="ts-4-9" tabTitle="globals-api"
+```ts filename="Button.stories.ts|tsx" renderer="common" language="ts-4-9" tabTitle="Without story globals"
 // Replace your-framework with the name of your framework
 import type { Meta, StoryObj } from '@storybook/your-framework';
 
@@ -41,12 +41,12 @@ type Story = StoryObj<typeof meta>;
 
 export const Large: Story = {
   parameters: {
-    backgrounds: { disabled: true },
+    backgrounds: { disable: true },
   },
 };
 ```
 
-```ts filename="Button.stories.ts|tsx" renderer="common" language="ts-4-9" tabTitle="without-globals"
+```ts filename="Button.stories.ts|tsx" renderer="common" language="ts-4-9" tabTitle="With story globals enabled"
 // Replace your-framework with the name of your framework
 import type { Meta, StoryObj } from '@storybook/your-framework';
 
@@ -61,12 +61,12 @@ type Story = StoryObj<typeof meta>;
 
 export const Large: Story = {
   parameters: {
-    backgrounds: { disable: true },
+    backgrounds: { disabled: true },
   },
 };
 ```
 
-```ts filename="Button.stories.ts|tsx" renderer="common" language="ts" tabTitle="globals-api"
+```ts filename="Button.stories.ts|tsx" renderer="common" language="ts" tabTitle="Without story globals"
 // Replace your-framework with the name of your framework
 import type { Meta, StoryObj } from '@storybook/your-framework';
 
@@ -81,12 +81,12 @@ type Story = StoryObj<typeof Button>;
 
 export const Large: Story = {
   parameters: {
-    backgrounds: { disabled: true },
+    backgrounds: { disable: true },
   },
 };
 ```
 
-```ts filename="Button.stories.ts|tsx" renderer="common" language="ts" tabTitle="without-globals"
+```ts filename="Button.stories.ts|tsx" renderer="common" language="ts" tabTitle="With story globals enabled"
 // Replace your-framework with the name of your framework
 import type { Meta, StoryObj } from '@storybook/your-framework';
 
@@ -101,7 +101,7 @@ type Story = StoryObj<typeof Button>;
 
 export const Large: Story = {
   parameters: {
-    backgrounds: { disable: true },
+    backgrounds: { disabled: true },
   },
 };
 ```
diff --git a/docs/_snippets/storybook-addon-backgrounds-configure-grid.md b/docs/_snippets/addon-backgrounds-grid.md
similarity index 100%
rename from docs/_snippets/storybook-addon-backgrounds-configure-grid.md
rename to docs/_snippets/addon-backgrounds-grid.md
diff --git a/docs/_snippets/addon-backgrounds-options-in-meta.md b/docs/_snippets/addon-backgrounds-options-in-meta.md
new file mode 100644
index 000000000000..6e438c41d153
--- /dev/null
+++ b/docs/_snippets/addon-backgrounds-options-in-meta.md
@@ -0,0 +1,243 @@
+```ts filename="Button.stories.ts" renderer="angular" language="ts"
+import type { Meta } from '@storybook/angular';
+
+import { Button } from './button.component';
+
+const meta: Meta<Button> = {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      options: {
+        // 👇 Override the default `dark` option
+        dark: { name: 'Dark', value: '#000' },
+        // 👇 Add a new option
+        gray: { name: 'Gray', value: '#CCC' },
+      },
+    },
+  },
+};
+
+export default meta;
+```
+
+```js filename="Button.stories.js" renderer="web-components" language="js"
+export default {
+  component: 'demo-button',
+  parameters: {
+    backgrounds: {
+      options: {
+        // 👇 Override the default `dark` option
+        dark: { name: 'Dark', value: '#000' },
+        // 👇 Add a new option
+        gray: { name: 'Gray', value: '#CCC' },
+      },
+    },
+  },
+};
+```
+
+```ts filename="Button.stories.ts" renderer="web-components" language="ts"
+import type { Meta, StoryObj } from '@storybook/web-components';
+
+const meta: Meta = {
+  component: 'demo-button',
+  parameters: {
+    backgrounds: {
+      options: {
+        // 👇 Override the default `dark` option
+        dark: { name: 'Dark', value: '#000' },
+        // 👇 Add a new option
+        gray: { name: 'Gray', value: '#CCC' },
+      },
+    },
+  },
+};
+
+export default meta;
+```
+
+```js filename="Button.stories.js|jsx" renderer="react" language="js"
+import { Button } from './Button';
+
+export default {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      options: {
+        // 👇 Override the default `dark` option
+        dark: { name: 'Dark', value: '#000' },
+        // 👇 Add a new option
+        gray: { name: 'Gray', value: '#CCC' },
+      },
+    },
+  },
+};
+```
+
+```ts filename="Button.stories.tsx" renderer="react" language="ts"
+import type { Meta } from '@storybook/react';
+
+import { Button } from './Button';
+
+const meta: Meta<typeof Button> = {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      options: {
+        // 👇 Override the default `dark` option
+        dark: { name: 'Dark', value: '#000' },
+        // 👇 Add a new option
+        gray: { name: 'Gray', value: '#CCC' },
+      },
+    },
+  },
+};
+
+export default meta;
+```
+
+```ts filename="Button.stories.ts|tsx" renderer="react" language="ts-4-9"
+import type { Meta } from '@storybook/react';
+
+import { Button } from './Button';
+
+const meta = {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      options: {
+        // 👇 Override the default `dark` option
+        dark: { name: 'Dark', value: '#000' },
+        // 👇 Add a new option
+        gray: { name: 'Gray', value: '#CCC' },
+      },
+    },
+  },
+} satisfies Meta<typeof Button>;
+
+export default meta;
+```
+
+```js filename="Button.stories.js" renderer="vue" language="js"
+import Button from './Button.vue';
+
+export default {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      options: {
+        // 👇 Override the default `dark` option
+        dark: { name: 'Dark', value: '#000' },
+        // 👇 Add a new option
+        gray: { name: 'Gray', value: '#CCC' },
+      },
+    },
+  },
+};
+```
+
+```ts filename="Button.stories.ts" renderer="vue" language="ts"
+import type { Meta } from '@storybook/vue3';
+
+import Button from './Button.vue';
+
+const meta: Meta<typeof Button> = {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      options: {
+        // 👇 Override the default `dark` option
+        dark: { name: 'Dark', value: '#000' },
+        // 👇 Add a new option
+        gray: { name: 'Gray', value: '#CCC' },
+      },
+    },
+  },
+};
+
+export default meta;
+```
+
+```ts filename="Button.stories.ts" renderer="vue" language="ts-4-9"
+import type { Meta } from '@storybook/vue3';
+
+import Button from './Button.vue';
+
+const meta = {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      options: {
+        // 👇 Override the default `dark` option
+        dark: { name: 'Dark', value: '#000' },
+        // 👇 Add a new option
+        gray: { name: 'Gray', value: '#CCC' },
+      },
+    },
+  },
+} satisfies Meta<typeof Button>;
+
+export default meta;
+```
+
+```js filename="Button.stories.js" renderer="svelte" language="js"
+import Button from './Button.svelte';
+
+export default {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      options: {
+        // 👇 Override the default `dark` option
+        dark: { name: 'Dark', value: '#000' },
+        // 👇 Add a new option
+        gray: { name: 'Gray', value: '#CCC' },
+      },
+    },
+  },
+};
+```
+
+```ts filename="Button.stories.ts" renderer="svelte" language="ts"
+import type { Meta } from '@storybook/svelte';
+
+import Button from './Button.svelte';
+
+const meta: Meta<typeof Button> = {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      options: {
+        // 👇 Override the default `dark` option
+        dark: { name: 'Dark', value: '#000' },
+        // 👇 Add a new option
+        gray: { name: 'Gray', value: '#CCC' },
+      },
+    },
+  },
+};
+
+export default meta;
+```
+
+```ts filename="Button.stories.ts" renderer="svelte" language="ts-4-9"
+import type { Meta } from '@storybook/svelte';
+
+import Button from './Button.svelte';
+
+const meta = {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      options: {
+        // 👇 Override the default `dark` option
+        dark: { name: 'Dark', value: '#000' },
+        // 👇 Add a new option
+        gray: { name: 'Gray', value: '#CCC' },
+      },
+    },
+  },
+} satisfies Meta<typeof Button>;
+
+export default meta;
+```
diff --git a/docs/_snippets/addon-backgrounds-options-in-preview.md b/docs/_snippets/addon-backgrounds-options-in-preview.md
new file mode 100644
index 000000000000..af9498d8acd4
--- /dev/null
+++ b/docs/_snippets/addon-backgrounds-options-in-preview.md
@@ -0,0 +1,36 @@
+```js filename=".storybook/preview.js" renderer="common" language="js"
+export default {
+  parameters: {
+    backgrounds: {
+      options: {
+        // 👇 Default options
+        dark: { name: 'Dark', value: '#333' },
+        light: { name: 'Light', value: '#F7F9F2' },
+        // 👇 Add your own
+        maroon: { name: 'Maroon', value: '#400' },
+      },
+    },
+  },
+};
+```
+
+```ts filename=".storybook/preview.ts" renderer="common" language="ts"
+// Replace your-framework with the framework you are using (e.g., react, vue3)
+import { Preview } from '@storybook/your-framework';
+
+const preview: Preview = {
+  parameters: {
+    backgrounds: {
+      options: {
+        // 👇 Default options
+        dark: { name: 'Dark', value: '#333' },
+        light: { name: 'Light', value: '#F7F9F2' },
+        // 👇 Add your own
+        maroon: { name: 'Maroon', value: '#400' },
+      },
+    },
+  },
+};
+
+export default preview;
+```
diff --git a/docs/_snippets/storybook-addon-backgrounds-disable-grid.md b/docs/_snippets/addon-backgrounds-override-globals.md
similarity index 50%
rename from docs/_snippets/storybook-addon-backgrounds-disable-grid.md
rename to docs/_snippets/addon-backgrounds-override-globals.md
index f93791b804e0..5097231a356e 100644
--- a/docs/_snippets/storybook-addon-backgrounds-disable-grid.md
+++ b/docs/_snippets/addon-backgrounds-override-globals.md
@@ -5,18 +5,19 @@ import { Button } from './button.component';
 
 const meta: Meta<Button> = {
   component: Button,
+  globals: {
+    // 👇 Set background value for all component stories
+    backgrounds: { value: 'gray', grid: false },
+  },
 };
 
 export default meta;
 type Story = StoryObj<Button>;
 
-export const Large: Story = {
-  parameters: {
-    backgrounds: {
-      grid: {
-        disable: true,
-      },
-    },
+export const OnDark: Story = {
+  globals: {
+    // 👇 Override background value for this story
+    backgrounds: { value: 'dark' },
   },
 };
 ```
@@ -26,15 +27,16 @@ import { Button } from './Button';
 
 export default {
   component: Button,
+  globals: {
+    // 👇 Set background value for all component stories
+    backgrounds: { value: 'gray', grid: false },
+  },
 };
 
-export const Large = {
-  parameters: {
-    backgrounds: {
-      grid: {
-        disable: true,
-      },
-    },
+export const OnDark = {
+  globals: {
+    // 👇 Override background value for this story
+    backgrounds: { value: 'dark' },
   },
 };
 ```
@@ -47,18 +49,19 @@ import { Button } from './Button';
 
 const meta = {
   component: Button,
+  globals: {
+    // 👇 Set background value for all component stories
+    backgrounds: { value: 'gray', grid: false },
+  },
 } satisfies Meta<typeof Button>;
 
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Large: Story = {
-  parameters: {
-    backgrounds: {
-      grid: {
-        disable: true,
-      },
-    },
+export const OnDark: Story = {
+  globals: {
+    // 👇 Override background value for this story
+    backgrounds: { value: 'dark' },
   },
 };
 ```
@@ -71,18 +74,19 @@ import { Button } from './Button';
 
 const meta: Meta<typeof Button> = {
   component: Button,
+  globals: {
+    // 👇 Set background value for all component stories
+    backgrounds: { value: 'gray', grid: false },
+  },
 };
 
 export default meta;
 type Story = StoryObj<typeof Button>;
 
-export const Large: Story = {
-  parameters: {
-    backgrounds: {
-      grid: {
-        disable: true,
-      },
-    },
+export const OnDark: Story = {
+  globals: {
+    // 👇 Override background value for this story
+    backgrounds: { value: 'dark' },
   },
 };
 ```
@@ -90,15 +94,16 @@ export const Large: Story = {
 ```js filename="Button.stories.js" renderer="web-components" language="js"
 export default {
   component: 'demo-button',
+  globals: {
+    // 👇 Set background value for all component stories
+    backgrounds: { value: 'gray', grid: false },
+  },
 };
 
-export const Large = {
-  parameters: {
-    backgrounds: {
-      grid: {
-        disable: true,
-      },
-    },
+export const OnDark = {
+  globals: {
+    // 👇 Override background value for this story
+    backgrounds: { value: 'dark' },
   },
 };
 ```
@@ -108,19 +113,19 @@ import type { Meta, StoryObj } from '@storybook/web-components';
 
 const meta: Meta = {
   component: 'demo-button',
+  globals: {
+    // 👇 Set background value for all component stories
+    backgrounds: { value: 'gray', grid: false },
+  },
 };
 
 export default meta;
 type Story = StoryObj;
 
-export const Large: Story = {
-  parameters: {
-    backgrounds: {
-      grid: {
-        disable: true,
-      },
-    },
+export const OnDark: Story = {
+  globals: {
+    // 👇 Override background value for this story
+    backgrounds: { value: 'dark' },
   },
 };
 ```
-
diff --git a/docs/_snippets/storybook-addon-backgrounds-global-api.md b/docs/_snippets/addon-backgrounds-override-parameters-default.md
similarity index 55%
rename from docs/_snippets/storybook-addon-backgrounds-global-api.md
rename to docs/_snippets/addon-backgrounds-override-parameters-default.md
index bdf01ca550f5..b0b8205499f1 100644
--- a/docs/_snippets/storybook-addon-backgrounds-global-api.md
+++ b/docs/_snippets/addon-backgrounds-override-parameters-default.md
@@ -7,9 +7,8 @@ const meta: Meta<Button> = {
   component: Button,
   parameters: {
     backgrounds: {
-      options: {
-        maroon: { name: 'Maroon', value: '#400' },
-      },
+      // 👇 Set default background value for all component stories
+      default: 'Gray',
     },
   },
 };
@@ -17,9 +16,12 @@ const meta: Meta<Button> = {
 export default meta;
 type Story = StoryObj<Button>;
 
-export const Large: Story = {
-  global: {
-    backgrounds: { value: 'maroon', grid: false },
+export const OnDark: Story = {
+  parameters: {
+    backgrounds: {
+      // 👇 Override default background value for this story
+      default: 'Dark',
+    },
   },
 };
 ```
@@ -31,16 +33,18 @@ export default {
   component: Button,
   parameters: {
     backgrounds: {
-      options: {
-        maroon: { name: 'Maroon', value: '#400' },
-      },
+      // 👇 Set default background value for all component stories
+      default: 'Gray',
     },
   },
 };
 
-export const Large = {
-  global: {
-    backgrounds: { value: 'maroon', grid: false },
+export const OnDark = {
+  parameters: {
+    backgrounds: {
+      // 👇 Override default background value for this story
+      default: 'Dark',
+    },
   },
 };
 ```
@@ -55,9 +59,8 @@ const meta = {
   component: Button,
   parameters: {
     backgrounds: {
-      options: {
-        maroon: { name: 'Maroon', value: '#400' },
-      },
+      // 👇 Set default background value for all component stories
+      default: 'Gray',
     },
   },
 } satisfies Meta<typeof Button>;
@@ -65,9 +68,12 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
-export const Large: Story = {
-  global: {
-    backgrounds: { value: 'maroon', grid: false },
+export const OnDark: Story = {
+  parameters: {
+    backgrounds: {
+      // 👇 Override default background value for this story
+      default: 'Dark',
+    },
   },
 };
 ```
@@ -82,9 +88,8 @@ const meta: Meta<typeof Button> = {
   component: Button,
   parameters: {
     backgrounds: {
-      options: {
-        maroon: { name: 'Maroon', value: '#400' },
-      },
+      // 👇 Set default background value for all component stories
+      default: 'Gray',
     },
   },
 };
@@ -92,9 +97,12 @@ const meta: Meta<typeof Button> = {
 export default meta;
 type Story = StoryObj<typeof Button>;
 
-export const Large: Story = {
-  global: {
-    backgrounds: { value: 'maroon', grid: false },
+export const OnDark: Story = {
+  parameters: {
+    backgrounds: {
+      // 👇 Override default background value for this story
+      default: 'Dark',
+    },
   },
 };
 ```
@@ -104,16 +112,18 @@ export default {
   component: 'demo-button',
   parameters: {
     backgrounds: {
-      options: {
-        maroon: { name: 'Maroon', value: '#400' },
-      },
+      // 👇 Set default background value for all component stories
+      default: 'Gray',
     },
   },
 };
 
-export const Large = {
-  global: {
-    backgrounds: { value: 'maroon', grid: false },
+export const OnDark = {
+  parameters: {
+    backgrounds: {
+      // 👇 Override default background value for this story
+      default: 'Dark',
+    },
   },
 };
 ```
@@ -125,9 +135,8 @@ const meta: Meta = {
   component: 'demo-button',
   parameters: {
     backgrounds: {
-      options: {
-        maroon: { name: 'Maroon', value: '#400' },
-      },
+      // 👇 Set default background value for all component stories
+      default: 'Gray',
     },
   },
 };
@@ -135,9 +144,12 @@ const meta: Meta = {
 export default meta;
 type Story = StoryObj;
 
-export const Large: Story = {
-  global: {
-    backgrounds: { value: 'maroon', grid: false },
+export const OnDark: Story = {
+  parameters: {
+    backgrounds: {
+      // 👇 Override default background value for this story
+      default: 'Dark',
+    },
   },
 };
-```
\ No newline at end of file
+```
diff --git a/docs/_snippets/addon-backgrounds-values-in-meta.md b/docs/_snippets/addon-backgrounds-values-in-meta.md
new file mode 100644
index 000000000000..cdb9f6d9cc31
--- /dev/null
+++ b/docs/_snippets/addon-backgrounds-values-in-meta.md
@@ -0,0 +1,231 @@
+```ts filename="Button.stories.ts" renderer="angular" language="ts"
+import type { Meta } from '@storybook/angular';
+
+import { Button } from './button.component';
+
+const meta: Meta<Button> = {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      default: 'Light',
+      values: [
+        // 👇 Add a new value
+        { name: 'Gray', value: '#CCC' },
+      ],
+    },
+  },
+};
+
+export default meta;
+```
+
+```js filename="Button.stories.js" renderer="web-components" language="js"
+export default {
+  component: 'demo-button',
+  parameters: {
+    backgrounds: {
+      default: 'Light',
+      values: [
+        // 👇 Add a new value
+        { name: 'Gray', value: '#CCC' },
+      ],
+    },
+  },
+};
+```
+
+```ts filename="Button.stories.ts" renderer="web-components" language="ts"
+import type { Meta, StoryObj } from '@storybook/web-components';
+
+const meta: Meta = {
+  component: 'demo-button',
+  parameters: {
+    backgrounds: {
+      default: 'Light',
+      values: [
+        // 👇 Add a new value
+        { name: 'Gray', value: '#CCC' },
+      ],
+    },
+  },
+};
+
+export default meta;
+```
+
+```js filename="Button.stories.js|jsx" renderer="react" language="js"
+import { Button } from './Button';
+
+export default {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      default: 'Light',
+      values: [
+        // 👇 Add a new value
+        { name: 'Gray', value: '#CCC' },
+      ],
+    },
+  },
+};
+```
+
+```ts filename="Button.stories.tsx" renderer="react" language="ts"
+import type { Meta } from '@storybook/react';
+
+import { Button } from './Button';
+
+const meta: Meta<typeof Button> = {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      default: 'Light',
+      values: [
+        // 👇 Add a new value
+        { name: 'Gray', value: '#CCC' },
+      ],
+    },
+  },
+};
+
+export default meta;
+```
+
+```ts filename="Button.stories.ts|tsx" renderer="react" language="ts-4-9"
+import type { Meta } from '@storybook/react';
+
+import { Button } from './Button';
+
+const meta = {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      default: 'Light',
+      values: [
+        // 👇 Add a new value
+        { name: 'Gray', value: '#CCC' },
+      ],
+    },
+  },
+} satisfies Meta<typeof Button>;
+
+export default meta;
+```
+
+```js filename="Button.stories.js" renderer="vue" language="js"
+import Button from './Button.vue';
+
+export default {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      default: 'Light',
+      values: [
+        // 👇 Add a new value
+        { name: 'Gray', value: '#CCC' },
+      ],
+    },
+  },
+};
+```
+
+```ts filename="Button.stories.ts" renderer="vue" language="ts"
+import type { Meta } from '@storybook/vue3';
+
+import Button from './Button.vue';
+
+const meta: Meta<typeof Button> = {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      default: 'Light',
+      values: [
+        // 👇 Add a new value
+        { name: 'Gray', value: '#CCC' },
+      ],
+    },
+  },
+};
+
+export default meta;
+```
+
+```ts filename="Button.stories.ts" renderer="vue" language="ts-4-9"
+import type { Meta } from '@storybook/vue3';
+
+import Button from './Button.vue';
+
+const meta = {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      default: 'Light',
+      values: [
+        // 👇 Add a new value
+        { name: 'Gray', value: '#CCC' },
+      ],
+    },
+  },
+} satisfies Meta<typeof Button>;
+
+export default meta;
+```
+
+```js filename="Button.stories.js" renderer="svelte" language="js"
+import Button from './Button.svelte';
+
+export default {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      default: 'Light',
+      values: [
+        // 👇 Add a new value
+        { name: 'Gray', value: '#CCC' },
+      ],
+    },
+  },
+};
+```
+
+```ts filename="Button.stories.ts" renderer="svelte" language="ts"
+import type { Meta } from '@storybook/svelte';
+
+import Button from './Button.svelte';
+
+const meta: Meta<typeof Button> = {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      default: 'Light',
+      values: [
+        // 👇 Add a new value
+        { name: 'Gray', value: '#CCC' },
+      ],
+    },
+  },
+};
+
+export default meta;
+```
+
+```ts filename="Button.stories.ts" renderer="svelte" language="ts-4-9"
+import type { Meta } from '@storybook/svelte';
+
+import Button from './Button.svelte';
+
+const meta = {
+  component: Button,
+  parameters: {
+    backgrounds: {
+      default: 'Light',
+      values: [
+        // 👇 Add a new value
+        { name: 'Gray', value: '#CCC' },
+      ],
+    },
+  },
+} satisfies Meta<typeof Button>;
+
+export default meta;
+```
diff --git a/docs/_snippets/addon-backgrounds-values-in-preview.md b/docs/_snippets/addon-backgrounds-values-in-preview.md
new file mode 100644
index 000000000000..7fd9834d3142
--- /dev/null
+++ b/docs/_snippets/addon-backgrounds-values-in-preview.md
@@ -0,0 +1,40 @@
+```js filename=".storybook/preview.js" renderer="common" language="js"
+export default {
+  parameters: {
+    backgrounds: {
+      values: [
+        // 👇 Default values
+        { name: 'Dark', value: '#333' },
+        { name: 'Light', value: '#F7F9F2' },
+        // 👇 Add your own
+        { name: 'Maroon', value: '#400' },
+      ],
+      // 👇 Specify which background is shown by default
+      default: 'Light',
+    },
+  },
+};
+```
+
+```ts filename=".storybook/preview.ts" renderer="common" language="ts"
+// Replace your-framework with the framework you are using (e.g., react, vue3)
+import { Preview } from '@storybook/your-framework';
+
+const preview: Preview = {
+  parameters: {
+    backgrounds: {
+      values: [
+        // 👇 Default values
+        { name: 'Dark', value: '#333' },
+        { name: 'Light', value: '#F7F9F2' },
+        // 👇 Add your own
+        { name: 'Maroon', value: '#400' },
+      ],
+      // 👇 Specify which background is shown by default
+      default: 'Light',
+    },
+  },
+};
+
+export default preview;
+```
diff --git a/docs/_snippets/storybook-addon-backgrounds-configure-backgrounds.md b/docs/_snippets/storybook-addon-backgrounds-configure-backgrounds.md
deleted file mode 100644
index d3f67b11a3e1..000000000000
--- a/docs/_snippets/storybook-addon-backgrounds-configure-backgrounds.md
+++ /dev/null
@@ -1,523 +0,0 @@
-```ts filename="Button.stories.ts" renderer="angular" language="ts" tabTitle="globals-api"
-import type { Meta } from '@storybook/angular';
-
-import { Button } from './button.component';
-
-const meta: Meta<Button> = {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#333' },
-        light: { name: 'Light', value: '#F7F9F2' },
-      },
-    },
-  },
-};
-
-export default meta;
-```
-
-```ts filename="Button.stories.ts" renderer="angular" language="ts" tabTitle="without-globals"
-import type { Meta } from '@storybook/angular';
-
-import { Button } from './button.component';
-
-const meta: Meta<Button> = {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      default: 'Light',
-      values: [
-        {
-          name: 'Dark',
-          value: '#333',
-        },
-        {
-          name: 'Light',
-          value: '#F7F9F2',
-        },
-      ],
-    },
-  },
-};
-
-export default meta;
-```
-
-```js filename="Button.stories.js" renderer="web-components" language="js" tabTitle="globals-api"
-export default {
-  component: 'demo-button',
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#333' },
-        light: { name: 'Light', value: '#F7F9F2' },
-      },
-    },
-  },
-};
-```
-
-```ts filename="Button.stories.ts" renderer="web-components" language="ts" tabTitle="globals-api"
-import type { Meta, StoryObj } from '@storybook/web-components';
-
-const meta: Meta = {
-  component: 'demo-button',
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#333' },
-        light: { name: 'Light', value: '#F7F9F2' },
-      },
-    },
-  },
-};
-
-export default meta;
-```
-
-```js filename="Button.stories.js" renderer="web-components" language="js" tabTitle="without-globals"
-export default {
-  component: 'demo-button',
-  parameters: {
-    backgrounds: {
-      default: 'Light',
-      values: [
-        {
-          name: 'Dark',
-          value: '#333',
-        },
-        {
-          name: 'Light',
-          value: '#F7F9F2',
-        },
-      ],
-    },
-  },
-};
-```
-
-```ts filename="Button.stories.ts" renderer="web-components" language="ts" tabTitle="without-globals"
-import type { Meta, StoryObj } from '@storybook/web-components';
-
-const meta: Meta = {
-  component: 'demo-button',
-  parameters: {
-    backgrounds: {
-      default: 'Light',
-      values: [
-        {
-          name: 'Dark',
-          value: '#333',
-        },
-        {
-          name: 'Light',
-          value: '#F7F9F2',
-        },
-      ],
-    },
-  },
-};
-
-export default meta;
-```
-
-```js filename="Button.stories.js|jsx" renderer="react" language="js" tabTitle="globals-api"
-import { Button } from './Button';
-
-export default {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#333' },
-        light: { name: 'Light', value: '#F7F9F2' },
-      },
-    },
-  },
-};
-```
-
-```js filename="Button.stories.js|jsx" renderer="react" language="js" tabTitle="without-globals"
-import { Button } from './Button';
-
-export default {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      default: 'Light',
-      values: [
-        {
-          name: 'Dark',
-          value: '#333',
-        },
-        {
-          name: 'Light',
-          value: '#F7F9F2',
-        },
-      ],
-    },
-  },
-};
-```
-
-```ts filename="Button.stories.tsx" renderer="react" language="ts" tabTitle="globals-api"
-import type { Meta } from '@storybook/react';
-
-import { Button } from './Button';
-
-const meta: Meta<typeof Button> = {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#333' },
-        light: { name: 'Light', value: '#F7F9F2' },
-      },
-    },
-  },
-};
-
-export default meta;
-```
-
-```ts filename="Button.stories.tsx" renderer="react" language="ts" tabTitle="without-globals"
-import type { Meta } from '@storybook/react';
-
-import { Button } from './Button';
-
-const meta: Meta<typeof Button> = {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      default: 'Light',
-      values: [
-        {
-          name: 'Dark',
-          value: '#333',
-        },
-        {
-          name: 'Light',
-          value: '#F7F9F2',
-        },
-      ],
-    },
-  },
-};
-
-export default meta;
-```
-
-```ts filename="Button.stories.ts|tsx" renderer="react" language="ts-4-9" tabTitle="globals-api"
-import type { Meta } from '@storybook/react';
-
-import { Button } from './Button';
-
-const meta = {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#333' },
-        light: { name: 'Light', value: '#F7F9F2' },
-      },
-    },
-  },
-} satisfies Meta<typeof Button>;
-
-export default meta;
-```
-
-```ts filename="Button.stories.ts|tsx" renderer="react" language="ts-4-9" tabTitle="without-globals"
-import type { Meta } from '@storybook/react';
-
-import { Button } from './Button';
-
-const meta = {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      default: 'Light',
-      values: [
-        {
-          name: 'Dark',
-          value: '#333',
-        },
-        {
-          name: 'Light',
-          value: '#F7F9F2',
-        },
-      ],
-    },
-  },
-} satisfies Meta<typeof Button>;
-
-export default meta;
-```
-
-```js filename="Button.stories.js" renderer="vue" language="js" tabTitle="globals-api"
-import Button from './Button.vue';
-
-export default {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#333' },
-        light: { name: 'Light', value: '#F7F9F2' },
-      },
-    },
-  },
-};
-```
-
-```js filename="Button.stories.js" renderer="vue" language="js" tabTitle="without-globals"
-import Button from './Button.vue';
-
-export default {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      default: 'Light',
-      values: [
-        {
-          name: 'Dark',
-          value: '#333',
-        },
-        {
-          name: 'Light',
-          value: '#F7F9F2',
-        },
-      ],
-    },
-  },
-};
-```
-
-```ts filename="Button.stories.ts" renderer="vue" language="ts" tabTitle="globals-api"
-import type { Meta } from '@storybook/vue3';
-
-import Button from './Button.vue';
-
-const meta: Meta<typeof Button> = {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#333' },
-        light: { name: 'Light', value: '#F7F9F2' },
-      },
-    },
-  },
-};
-
-export default meta;
-```
-
-```ts filename="Button.stories.ts" renderer="vue" language="ts" tabTitle="without-globals"
-import type { Meta } from '@storybook/vue3';
-
-import Button from './Button.vue';
-
-const meta: Meta<typeof Button> = {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      default: 'Light',
-      values: [
-        {
-          name: 'Dark',
-          value: '#333',
-        },
-        {
-          name: 'Light',
-          value: '#F7F9F2',
-        },
-      ],
-    },
-  },
-};
-
-export default meta;
-```
-
-```ts filename="Button.stories.ts" renderer="vue" language="ts-4-9" tabTitle="globals-api"
-import type { Meta } from '@storybook/vue3';
-
-import Button from './Button.vue';
-
-const meta = {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#333' },
-        light: { name: 'Light', value: '#F7F9F2' },
-      },
-    },
-  },
-} satisfies Meta<typeof Button>;
-
-export default meta;
-```
-
-```ts filename="Button.stories.ts" renderer="vue" language="ts-4-9" tabTitle="without-globals"
-import type { Meta } from '@storybook/vue3';
-
-import Button from './Button.vue';
-
-const meta = {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      default: 'Light',
-      values: [
-        {
-          name: 'Dark',
-          value: '#333',
-        },
-        {
-          name: 'Light',
-          value: '#F7F9F2',
-        },
-      ],
-    },
-  },
-} satisfies Meta<typeof Button>;
-
-export default meta;
-```
-
-```js filename="Button.stories.js" renderer="svelte" language="js" tabTitle="globals-api"
-import Button from './Button.svelte';
-
-export default {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#333' },
-        light: { name: 'Light', value: '#F7F9F2' },
-      },
-    },
-  },
-};
-```
-
-```js filename="Button.stories.js" renderer="svelte" language="js" tabTitle="without-globals"
-import Button from './Button.svelte';
-
-export default {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      default: 'Light',
-      values: [
-        {
-          name: 'Dark',
-          value: '#333',
-        },
-        {
-          name: 'Light',
-          value: '#F7F9F2',
-        },
-      ],
-    },
-  },
-};
-```
-
-```ts filename="Button.stories.ts" renderer="svelte" language="ts" tabTitle="globals-api"
-import type { Meta } from '@storybook/svelte';
-
-import Button from './Button.svelte';
-
-const meta: Meta<typeof Button> = {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#333' },
-        light: { name: 'Light', value: '#F7F9F2' },
-      },
-    },
-  },
-};
-
-export default meta;
-```
-
-```ts filename="Button.stories.ts" renderer="svelte" language="ts" tabTitle="without-globals"
-import type { Meta } from '@storybook/svelte';
-
-import Button from './Button.svelte';
-
-const meta: Meta<typeof Button> = {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      default: 'Light',
-      values: [
-        {
-          name: 'Dark',
-          value: '#333',
-        },
-        {
-          name: 'Light',
-          value: '#F7F9F2',
-        },
-      ],
-    },
-  },
-};
-
-export default meta;
-```
-
-```ts filename="Button.stories.ts" renderer="svelte" language="ts-4-9" tabTitle="globals-api"
-import type { Meta } from '@storybook/svelte';
-
-import Button from './Button.svelte';
-
-const meta = {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#333' },
-        light: { name: 'Light', value: '#F7F9F2' },
-      },
-    },
-  },
-} satisfies Meta<typeof Button>;
-
-export default meta;
-```
-
-```ts filename="Button.stories.ts" renderer="svelte" language="ts-4-9" tabTitle="without-globals"
-import type { Meta } from '@storybook/svelte';
-
-import Button from './Button.svelte';
-
-const meta = {
-  component: Button,
-  parameters: {
-    backgrounds: {
-      default: 'Light',
-      values: [
-        {
-          name: 'Dark',
-          value: '#333',
-        },
-        {
-          name: 'Light',
-          value: '#F7F9F2',
-        },
-      ],
-    },
-  },
-} satisfies Meta<typeof Button>;
-
-export default meta;
-```
diff --git a/docs/_snippets/storybook-addon-backgrounds-override-background-color.md b/docs/_snippets/storybook-addon-backgrounds-override-background-color.md
deleted file mode 100644
index 87bcb7fb749c..000000000000
--- a/docs/_snippets/storybook-addon-backgrounds-override-background-color.md
+++ /dev/null
@@ -1,455 +0,0 @@
-```ts filename="Button.stories.ts" renderer="angular" language="ts" tabTitle="globals-api"
-import type { Meta, StoryObj } from '@storybook/angular';
-
-import { Button } from './button.component';
-
-const meta: Meta<Button> = {
-  component: Button,
-};
-
-export default meta;
-type Story = StoryObj<Button>;
-
-export const Large: Story = {
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#000' },
-      },
-    },
-  },
-};
-```
-
-```ts filename="Button.stories.ts" renderer="angular" language="ts" tabTitle="without-globals"
-import type { Meta, StoryObj } from '@storybook/angular';
-
-import { Button } from './button.component';
-
-const meta: Meta<Button> = {
-  component: Button,
-};
-
-export default meta;
-type Story = StoryObj<Button>;
-
-export const Large: Story = {
-  parameters: {
-    backgrounds: { default: 'Dark' },
-  },
-};
-```
-
-```js filename="Button.stories.js" renderer="web-components" language="js" tabTitle="globals-api"
-export default {
-  component: 'demo-button',
-};
-
-export const Large = {
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#000' },
-      },
-    },
-  },
-};
-```
-
-```js filename="Button.stories.js" renderer="web-components" language="js" tabTitle="without-globals"
-export default {
-  component: 'demo-button',
-};
-
-export const Large = {
-  parameters: {
-    backgrounds: { default: 'Dark' },
-  },
-};
-```
-
-```ts filename="Button.stories.ts" renderer="web-components" language="ts" tabTitle="globals-api"
-import type { Meta, StoryObj } from '@storybook/web-components';
-
-const meta: Meta = {
-  component: 'demo-button',
-};
-
-export default meta;
-type Story = StoryObj;
-
-export const Large: Story = {
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#000' },
-      },
-    },
-  },
-};
-```
-
-```ts filename="Button.stories.ts" renderer="web-components" language="ts" tabTitle="without-globals"
-import type { Meta, StoryObj } from '@storybook/web-components';
-
-const meta: Meta = {
-  component: 'demo-button',
-};
-
-export default meta;
-type Story = StoryObj;
-
-export const Large: Story = {
-  parameters: {
-    backgrounds: { default: 'Dark' },
-  },
-};
-```
-
-```js filename="Button.stories.js|jsx" renderer="react" language="js" tabTitle="globals-api"
-import { Button } from './Button';
-
-export default {
-  component: Button,
-};
-
-export const Large = {
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#000' },
-      },
-    },
-  },
-};
-```
-
-```js filename="Button.stories.js|jsx" renderer="react" language="js" tabTitle="without-globals"
-import { Button } from './Button';
-
-export default {
-  component: Button,
-};
-
-export const Large = {
-  parameters: {
-    backgrounds: { default: 'Dark' },
-  },
-};
-```
-
-```ts filename="Button.stories.tsx" renderer="react" language="ts" tabTitle="globals-api"
-import type { Meta, StoryObj } from '@storybook/react';
-
-import { Button } from './Button';
-
-const meta: Meta<typeof Button> = {
-  component: Button,
-};
-
-export default meta;
-type Story = StoryObj<typeof Button>;
-
-export const Large: Story = {
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#000' },
-      },
-    },
-  },
-};
-```
-
-```ts filename="Button.stories.tsx" renderer="react" language="ts" tabTitle="without-globals"
-import type { Meta, StoryObj } from '@storybook/react';
-
-import { Button } from './Button';
-
-const meta: Meta<typeof Button> = {
-  component: Button,
-};
-
-export default meta;
-type Story = StoryObj<typeof Button>;
-
-export const Large: Story = {
-  parameters: {
-    backgrounds: { default: 'Dark' },
-  },
-};
-```
-
-```ts filename="Button.stories.ts|tsx" renderer="react" language="ts-4-9" tabTitle="globals-api"
-import type { Meta, StoryObj } from '@storybook/react';
-
-import { Button } from './Button';
-
-const meta = {
-  component: Button,
-} satisfies Meta<typeof Button>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Large: Story = {
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#000' },
-      },
-    },
-  },
-};
-```
-
-```ts filename="Button.stories.ts|tsx" renderer="react" language="ts-4-9" tabTitle="without-globals"
-import type { Meta, StoryObj } from '@storybook/react';
-
-import { Button } from './Button';
-
-const meta = {
-  component: Button,
-} satisfies Meta<typeof Button>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Large: Story = {
-  parameters: {
-    backgrounds: { default: 'Dark' },
-  },
-};
-```
-
-```js filename="Button.stories.js" renderer="vue" language="js" tabTitle="globals-api"
-import Button from './Button.vue';
-
-export default {
-  component: Button,
-};
-
-export const Large = {
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#000' },
-      },
-    },
-  },
-};
-```
-
-```js filename="Button.stories.js" renderer="vue" language="js" tabTitle="without-globals"
-import Button from './Button.vue';
-
-export default {
-  component: Button,
-};
-
-export const Large = {
-  parameters: {
-    backgrounds: { default: 'Dark' },
-  },
-};
-```
-
-```ts filename="Button.stories.ts" renderer="vue" language="ts" tabTitle="globals-api"
-import type { Meta, StoryObj } from '@storybook/vue3';
-
-import Button from './Button.vue';
-
-const meta: Meta<typeof Button> = {
-  component: Button,
-};
-
-export default meta;
-type Story = StoryObj<typeof Button>;
-
-export const Large: Story = {
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#000' },
-      },
-    },
-  },
-};
-```
-
-```ts filename="Button.stories.ts" renderer="vue" language="ts" tabTitle="without-globals"
-import type { Meta, StoryObj } from '@storybook/vue3';
-
-import Button from './Button.vue';
-
-const meta: Meta<typeof Button> = {
-  component: Button,
-};
-
-export default meta;
-type Story = StoryObj<typeof Button>;
-
-export const Large: Story = {
-  parameters: {
-    backgrounds: { default: 'Dark' },
-  },
-};
-```
-
-```ts filename="Button.stories.ts" renderer="vue" language="ts-4-9" tabTitle="globals-api"
-import type { Meta, StoryObj } from '@storybook/vue3';
-
-import Button from './Button.vue';
-
-const meta = {
-  component: Button,
-} satisfies Meta<typeof Button>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Large: Story = {
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#000' },
-      },
-    },
-  },
-};
-```
-
-```ts filename="Button.stories.ts" renderer="vue" language="ts-4-9" tabTitle="without-globals"
-import type { Meta, StoryObj } from '@storybook/vue3';
-
-import Button from './Button.vue';
-
-const meta = {
-  component: Button,
-} satisfies Meta<typeof Button>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Large: Story = {
-  parameters: {
-    backgrounds: { default: 'Dark' },
-  },
-};
-```
-
-```js filename="Button.stories.js" renderer="svelte" language="js" tabTitle="globals-api"
-import Button from './Button.svelte';
-
-export default {
-  component: Button,
-};
-
-export const Large = {
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#000' },
-      },
-    },
-  },
-};
-```
-
-```js filename="Button.stories.js" renderer="svelte" language="js" tabTitle="without-globals"
-import Button from './Button.svelte';
-
-export default {
-  component: Button,
-};
-
-export const Large = {
-  parameters: {
-    backgrounds: { default: 'Dark' },
-  },
-};
-```
-
-```ts filename="Button.stories.ts" renderer="svelte" language="ts" tabTitle="globals-api"
-import type { Meta, StoryObj } from '@storybook/svelte';
-
-import Button from './Button.svelte';
-
-const meta: Meta<typeof Button> = {
-  component: Button,
-};
-
-export default meta;
-type Story = StoryObj<typeof Button>;
-
-export const Large: Story = {
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#000' },
-      },
-    },
-  },
-};
-```
-
-```ts filename="Button.stories.ts" renderer="svelte" language="ts" tabTitle="without-globals"
-import type { Meta, StoryObj } from '@storybook/svelte';
-
-import Button from './Button.svelte';
-
-const meta: Meta<typeof Button> = {
-  component: Button,
-};
-
-export default meta;
-type Story = StoryObj<typeof Button>;
-
-export const Large: Story = {
-  parameters: {
-    backgrounds: { default: 'Dark' },
-  },
-};
-```
-
-```ts filename="Button.stories.ts" renderer="svelte" language="ts-4-9" tabTitle="globals-api"
-import type { Meta, StoryObj } from '@storybook/svelte';
-
-import Button from './Button.svelte';
-
-const meta = {
-  component: Button,
-} satisfies Meta<typeof Button>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Large: Story = {
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#000' },
-      },
-    },
-  },
-};
-```
-
-```ts filename="Button.stories.ts" renderer="svelte" language="ts-4-9" tabTitle="without-globals"
-import type { Meta, StoryObj } from '@storybook/svelte';
-
-import Button from './Button.svelte';
-
-const meta = {
-  component: Button,
-} satisfies Meta<typeof Button>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Large: Story = {
-  parameters: {
-    backgrounds: { default: 'Dark' },
-  },
-};
-```
diff --git a/docs/_snippets/storybook-preview-configure-background-colors.md b/docs/_snippets/storybook-preview-configure-background-colors.md
index 153a7fa54bef..b28b04f64312 100644
--- a/docs/_snippets/storybook-preview-configure-background-colors.md
+++ b/docs/_snippets/storybook-preview-configure-background-colors.md
@@ -1,75 +1,3 @@
-```js filename=".storybook/preview.js" renderer="common" language="js" tabTitle="globals-api"
-export default {
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#333' },
-        light: { name: 'Light', value: '#F7F9F2' },
-      },
-    },
-  },
-};
-```
 
-```ts filename=".storybook/preview.ts" renderer="common" language="ts" tabTitle="globals-api"
-// Replace your-framework with the framework you are using (e.g., react, vue3)
-import { Preview } from '@storybook/your-framework';
 
-const preview: Preview = {
-  parameters: {
-    backgrounds: {
-      options: {
-        dark: { name: 'Dark', value: '#333' },
-        light: { name: 'Light', value: '#F7F9F2' },
-      },
-    },
-  },
-};
 
-export default preview;
-```
-
-```js filename=".storybook/preview.js" renderer="common" language="js" tabTitle="without-globals"
-export default {
-  parameters: {
-    backgrounds: {
-      default: 'Light',
-      values: [
-        {
-          name: 'Dark',
-          value: '#333',
-        },
-        {
-          name: 'Light',
-          value: '#F7F9F2',
-        },
-      ],
-    },
-  },
-};
-```
-
-```ts filename=".storybook/preview.ts" renderer="common" language="ts" tabTitle="without-globals"
-// Replace your-framework with the framework you are using (e.g., react, vue3)
-import { Preview } from '@storybook/your-framework';
-
-const preview: Preview = {
-  parameters: {
-    backgrounds: {
-      default: 'Light',
-      values: [
-        {
-          name: 'Dark',
-          value: '#333',
-        },
-        {
-          name: 'Light',
-          value: '#F7F9F2',
-        },
-      ],
-    },
-  },
-};
-
-export default preview;
-```
diff --git a/docs/essentials/backgrounds.mdx b/docs/essentials/backgrounds.mdx
index 16f0a0064d1a..22cd1f5b3bc5 100644
--- a/docs/essentials/backgrounds.mdx
+++ b/docs/essentials/backgrounds.mdx
@@ -5,7 +5,7 @@ sidebar:
   title: Backgrounds
 ---
 
-The backgrounds toolbar addon allows you to set the background color in which the story renders in the UI:
+The backgrounds toolbar addon allows you to set the background color on which the story renders in the UI:
 
 <Video src="../_assets/essentials/addon-backgrounds-optimized.mp4" />
 
@@ -13,82 +13,111 @@ The backgrounds toolbar addon allows you to set the background color in which th
 
 By default, the backgrounds toolbar includes a light and dark background.
 
-But you're not restricted to these backgrounds, you can configure your own set of colors with the `parameters.backgrounds` [parameter](../writing-stories/parameters.mdx) in your [`.storybook/preview.js`](../configure/index.mdx#configure-story-rendering):
+But you're not restricted to these backgrounds. You can configure your own set of colors with the `backgrounds` [parameter](../writing-stories/parameters.mdx) in your [`.storybook/preview.js`](../configure/index.mdx#configure-story-rendering). There are two ways to configure the backgrounds:
 
-{/* prettier-ignore-start */}
+### Using `options`
 
-<CodeSnippets path="storybook-preview-configure-background-colors.md" />
+<Callout variant="info">
+  This API can only be used when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
+</Callout>
 
-{/* prettier-ignore-end */}
+The available background colors are defined using the `options` property:
 
-If you define the `default` property, the addon will apply it to all stories. Otherwise, it's only listed as an available color.
+{/* prettier-ignore-start */}
 
-### Overriding backgrounds with globals
+<CodeSnippets path="addon-backgrounds-options-in-preview.md" />
 
-The Backgrounds addon enables you to change the background color applied to a story by selecting from the list of predefined background colors in the toolbar. If you need, you can opt into the globals API to configure backgrounds to ensure that a story always uses a specific background color regardless of the existing configuration.
+{/* prettier-ignore-end */}
 
-To enable it, you'll need to take some additional steps to set it up properly. Our recommendation for configuring and using the globals API with the Backgrounds addon is detailed below.
+### Using `values`
 
-Update your [`.storybook/main.js|ts`](../configure/index.mdx#configure-your-storybook-project) to include the [`backgroundsStoryGlobals`](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) option within Storybok's `features` configuration.
+If you're not using the `globals` API, you can define the available background colors using the `values` property:
 
 {/* prettier-ignore-start */}
 
-<CodeSnippets path="main-config-features-backgrounds-story-globals.md" />
+<CodeSnippets path="addon-backgrounds-values-in-preview.md" />
 
 {/* prettier-ignore-end */}
 
-<Callout variant="info">
+With either method, available backgrounds can be defined at the project, component, and story levels.
 
-Enabling this API will turn off the ability to change any options from the toolbar to ensure that the background is always set to the intended value for the story.
+To apply a default background color, assign the `default` property to one of the available colors.
 
-</Callout>
+{/* TK - Snippet? */}
+
+## Overriding the background for a story
 
-Adjust the `backgrounds` parameter in your [`.storybook/preview.js|ts`](../configure/index.mdx#configure-story-rendering) with an `options` object to define the available background colors for your stories.
+The Backgrounds addon enables you to change the background color applied to a story by selecting from the list of predefined background colors in the toolbar. If needed, you can force a story to use a specific background color. There are two ways to do this, which have different behaviors:
 
+### Using `globals`
+
+<Callout variant="info">
+  This feature is available when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
+</Callout>
+
+When you specify a background color for a story (or a component's stories) using `globals`, the background color is applied and cannot be changed using the toolbar. This is useful when you want to ensure that a story is always rendered on a specific background color.
 
 {/* prettier-ignore-start */}
 
-<CodeSnippets path="storybook-preview-migrate-backgrounds-globals.md" />
+<CodeSnippets path="addon-backgrounds-override-globals.md" usesCsf3 />
 
 {/* prettier-ignore-end */}
 
-Update your stories to enable the new story globals API using the `global` configuration option to set the required options for your stories.
+### Using `parameters`
+
+If you're not yet using the `globals` API, you can set the default background color for a story using the `parameters.backgrounds.default` parameter:
 
 {/* prettier-ignore-start */}
 
-<CodeSnippets path="storybook-addon-backgrounds-global-api.md" usesCsf3 />
+<CodeSnippets path="addon-backgrounds-override-parameters-default.md" usesCsf3 />
 
 {/* prettier-ignore-end */}
 
-### Extending the configuration
+As implied by the name, this method only sets the default background color for a story. You can still change the background color using the toolbar when viewing the story.
 
-You can also define backgrounds per-component or per-story basis through [parameter inheritance](../writing-stories/parameters.mdx#component-parameters):
+## Extending the configuration
+
+You can also define backgrounds per-component or per-story basis through [parameter inheritance](../writing-stories/parameters.mdx#component-parameters).
+
+### Using `options`
+
+<Callout variant="info">
+  This API can only be used when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
+</Callout>
+
+The available background colors are defined using the `options` property. In this example, we'll adjust the colors for all of the Button component's stories:
 
 {/* prettier-ignore-start */}
 
-<CodeSnippets path="storybook-addon-backgrounds-configure-backgrounds.md" />
+<CodeSnippets path="addon-backgrounds-options-in-meta.md" />
 
 {/* prettier-ignore-end */}
 
-You can also override a single key on the `backgrounds` parameter:
+### Using `values`
+
+If you're not using the `globals` API, you can define the available background colors using the `values` property. In this example, we'll adjust the colors for all of the Button component's stories:
 
 {/* prettier-ignore-start */}
 
-<CodeSnippets path="storybook-addon-backgrounds-override-background-color.md" usesCsf3 />
+<CodeSnippets path="addon-backgrounds-values-in-meta.md" />
 
 {/* prettier-ignore-end */}
 
-### Disable backgrounds
+## Disable backgrounds
 
 If you want to turn off backgrounds in a story, you can do so by setting the `backgrounds` parameter like so:
 
+<Callout variant="info">
+  Note that the property name changes when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
+</Callout>
+
 {/* prettier-ignore-start */}
 
-<CodeSnippets path="storybook-addon-backgrounds-disable-backgrounds.md" usesCsf3/>
+<CodeSnippets path="addon-backgrounds-disabled.md" usesCsf3/>
 
 {/* prettier-ignore-end */}
 
-### Grid
+## Grid
 
 The Backgrounds toolbar also includes a Grid selector, which allows you to quickly see if your components are aligned.
 
@@ -96,33 +125,49 @@ You don't need additional configuration to get started. But its properties are f
 
 {/* prettier-ignore-start */}
 
-<CodeSnippets path="storybook-addon-backgrounds-configure-grid.md" />
+<CodeSnippets path="addon-backgrounds-grid.md" />
 
 {/* prettier-ignore-end */}
 
 ## API
 
-### Parameters
+### Globals
 
-This addon contributes the following [parameters](../writing-stories/parameters.mdx) to Storybook, under the `backgrounds` namespace:
+This addon contributes the following globals to Storybook, under the `backgrounds` namespace:
 
-#### `default`
+<Callout variant="info">
+  These globals are only available when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
+</Callout>
+
+#### `grid`
+
+Type: Boolean
+
+Whether the [grid](#grid) is displayed.
+
+#### `value`
 
 Type: `string`
 
-Default background color. Must match the `name` property of one of the [available colors](#values). Required if you haven't opted into the [globals API](#overriding-backgrounds-with-globals).
+When set, the background color is applied and cannot be changed using the toolbar. Must match the key of one of the [available colors](#using-options). 
 
-#### `options`
+### Parameters
 
-Requires: [globals API](#overriding-backgrounds-with-globals)
+This addon contributes the following [parameters](../writing-stories/parameters.mdx) to Storybook, under the `backgrounds` namespace:
 
-Type: `Record<string, { name: string; value: string }>`
+#### `default`
 
-Defines the background colors. See above for a [usage example](#configuration).
+Type: `string`
 
-#### `disabled`
+Required: See description
+
+Default background color. Must match the `name` property of one of the [available colors](#values).
 
-Requires: [globals API](#overriding-backgrounds-with-globals)
+#### `disable`
+
+<Callout variant="info">
+  This API is deprecated when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
+</Callout>
 
 Type: `boolean`
 
@@ -130,11 +175,17 @@ Turn off this addon's behavior. If you wish to turn off this addon for the entir
 
 This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to `true` at the project level, it could be re-enabled by setting it to `false` at the meta (component) or story level.
 
+#### `disabled`
+
 <Callout variant="info">
+  This API is only available when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
+</Callout>
 
-The `disabled` parameter is only available with the globals API introduced in Storybook 8.3. If you're using a previous Storybook version, use the `disable` parameter instead.
+Type: `boolean`
 
-</Callout>
+Turn off this addon's behavior. If you wish to turn off this addon for the entire Storybook, you should do so when registering `addon-essentials`. See the [essential addon's docs](../essentials/index.mdx#disabling-addons) for more information.
+
+This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to `true` at the project level, it could be re-enabled by setting it to `false` at the meta (component) or story level.
 
 #### `grid`
 
@@ -151,6 +202,8 @@ Type:
 }
 ```
 
+Configuration for the [background grid](#grid).
+
 ##### `grid.cellAmount`
 
 Type: `number`
@@ -197,8 +250,30 @@ Default: `0.5`
 
 The opacity of the grid lines.
 
+#### `options`
+
+<Callout variant="info">
+  This API is only available when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
+</Callout>
+
+Type: `Record<string, { name: string; value: string }>`
+
+Required: See description
+
+Defines the background colors. See above for a [usage example](#with-options).
+
+Required when defining `backgrounds` parameter at project level.
+
 #### `values`
 
+<Callout variant="info">
+  This API is deprecated when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
+</Callout>
+
 Type: `{ name: string; value: string }[]`
 
-Available background colors. See above for a [usage example](#configuration). Required if you haven't opted into the [globals API](#overriding-backgrounds-with-globals).
+Required: See description
+
+Available background colors. See above for a [usage example](#using-values).
+
+Required when defining `backgrounds` parameter at project level.

From 75add27945799b370a75c8b63785e0e4cde2aed5 Mon Sep 17 00:00:00 2001
From: Kyle Gach <kyle.gach@gmail.com>
Date: Fri, 9 Aug 2024 16:07:47 -0600
Subject: [PATCH 2/5] Remove TK

---
 docs/essentials/backgrounds.mdx | 2 --
 1 file changed, 2 deletions(-)

diff --git a/docs/essentials/backgrounds.mdx b/docs/essentials/backgrounds.mdx
index 22cd1f5b3bc5..d402d9bbca45 100644
--- a/docs/essentials/backgrounds.mdx
+++ b/docs/essentials/backgrounds.mdx
@@ -43,8 +43,6 @@ With either method, available backgrounds can be defined at the project, compone
 
 To apply a default background color, assign the `default` property to one of the available colors.
 
-{/* TK - Snippet? */}
-
 ## Overriding the background for a story
 
 The Backgrounds addon enables you to change the background color applied to a story by selecting from the list of predefined background colors in the toolbar. If needed, you can force a story to use a specific background color. There are two ways to do this, which have different behaviors:

From ba24b9f0650e017c724d9e0097c18a5fb210bb34 Mon Sep 17 00:00:00 2001
From: Kyle Gach <kyle.gach@gmail.com>
Date: Mon, 12 Aug 2024 14:39:45 -0600
Subject: [PATCH 3/5] Address feedback

- Explain globals API and feature flag once, at the top
- Reference that callout in consistent manner throughout page
- Wrap entire docs section in "feature flag callout" to better differentiate
- Remove headings for with/without feature flag sections
    - Headings will be removed in SB 9+, so they're not a stable reference
---
 docs/_snippets/addon-backgrounds-disabled.md |  12 +-
 docs/essentials/backgrounds.mdx              | 152 +++++++++----------
 2 files changed, 80 insertions(+), 84 deletions(-)

diff --git a/docs/_snippets/addon-backgrounds-disabled.md b/docs/_snippets/addon-backgrounds-disabled.md
index 7cc4d7f8c235..140dd63610dd 100644
--- a/docs/_snippets/addon-backgrounds-disabled.md
+++ b/docs/_snippets/addon-backgrounds-disabled.md
@@ -1,4 +1,4 @@
-```js filename="Button.stories.js|jsx" renderer="common" language="js" tabTitle="Without story globals"
+```js filename="Button.stories.js|jsx" renderer="common" language="js" tabTitle="Without globals API"
 import { Button } from './Button';
 
 export default {
@@ -12,7 +12,7 @@ export const Large = {
 };
 ```
 
-```js filename="Button.stories.js|jsx" renderer="common" language="js" tabTitle="With story globals enabled"
+```js filename="Button.stories.js|jsx" renderer="common" language="js" tabTitle="With globals API"
 import { Button } from './Button';
 
 export default {
@@ -26,7 +26,7 @@ export const Large = {
 };
 ```
 
-```ts filename="Button.stories.ts|tsx" renderer="common" language="ts-4-9" tabTitle="Without story globals"
+```ts filename="Button.stories.ts|tsx" renderer="common" language="ts-4-9" tabTitle="Without globals API"
 // Replace your-framework with the name of your framework
 import type { Meta, StoryObj } from '@storybook/your-framework';
 
@@ -46,7 +46,7 @@ export const Large: Story = {
 };
 ```
 
-```ts filename="Button.stories.ts|tsx" renderer="common" language="ts-4-9" tabTitle="With story globals enabled"
+```ts filename="Button.stories.ts|tsx" renderer="common" language="ts-4-9" tabTitle="With globals API"
 // Replace your-framework with the name of your framework
 import type { Meta, StoryObj } from '@storybook/your-framework';
 
@@ -66,7 +66,7 @@ export const Large: Story = {
 };
 ```
 
-```ts filename="Button.stories.ts|tsx" renderer="common" language="ts" tabTitle="Without story globals"
+```ts filename="Button.stories.ts|tsx" renderer="common" language="ts" tabTitle="Without globals API"
 // Replace your-framework with the name of your framework
 import type { Meta, StoryObj } from '@storybook/your-framework';
 
@@ -86,7 +86,7 @@ export const Large: Story = {
 };
 ```
 
-```ts filename="Button.stories.ts|tsx" renderer="common" language="ts" tabTitle="With story globals enabled"
+```ts filename="Button.stories.ts|tsx" renderer="common" language="ts" tabTitle="With globals API"
 // Replace your-framework with the name of your framework
 import type { Meta, StoryObj } from '@storybook/your-framework';
 
diff --git a/docs/essentials/backgrounds.mdx b/docs/essentials/backgrounds.mdx
index d402d9bbca45..1dc228e6b523 100644
--- a/docs/essentials/backgrounds.mdx
+++ b/docs/essentials/backgrounds.mdx
@@ -9,35 +9,39 @@ The backgrounds toolbar addon allows you to set the background color on which th
 
 <Video src="../_assets/essentials/addon-backgrounds-optimized.mp4" />
 
-## Configuration
+<Callout variant="warning" icon="🆕" id="globals-api">
+  **`globals` API**
 
-By default, the backgrounds toolbar includes a light and dark background.
+  This addon has been updated to use the `globals` API when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled. With `globals`, when you specify a background value for a story, it cannot be overridden from the toolbar. This ensures a consistent experience while navigating between stories. This will be the default behavior and API in Storybook 9.
+</Callout>
 
-But you're not restricted to these backgrounds. You can configure your own set of colors with the `backgrounds` [parameter](../writing-stories/parameters.mdx) in your [`.storybook/preview.js`](../configure/index.mdx#configure-story-rendering). There are two ways to configure the backgrounds:
+## Configuration
 
-### Using `options`
+By default, the backgrounds toolbar includes a light and dark background.
 
-<Callout variant="info">
-  This API can only be used when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
-</Callout>
+But you're not restricted to these backgrounds. You can configure your own set of colors with the `backgrounds` [parameter](../writing-stories/parameters.mdx) in your [`.storybook/preview.js`](../configure/index.mdx#configure-story-rendering).
 
-The available background colors are defined using the `options` property:
+You can define the available background colors using the `values` property:
 
 {/* prettier-ignore-start */}
 
-<CodeSnippets path="addon-backgrounds-options-in-preview.md" />
+<CodeSnippets path="addon-backgrounds-values-in-preview.md" />
 
 {/* prettier-ignore-end */}
 
-### Using `values`
+<Callout variant="warning" icon="🆕">
 
-If you're not using the `globals` API, you can define the available background colors using the `values` property:
+  **With the [`globals` API](#globals-api)**
 
-{/* prettier-ignore-start */}
+  When using the `globals` API, you must define the available background colors using the `options` property:
 
-<CodeSnippets path="addon-backgrounds-values-in-preview.md" />
+  {/* prettier-ignore-start */}
 
-{/* prettier-ignore-end */}
+  <CodeSnippets path="addon-backgrounds-options-in-preview.md" />
+
+  {/* prettier-ignore-end */}
+
+</Callout>
 
 With either method, available backgrounds can be defined at the project, component, and story levels.
 
@@ -45,68 +49,68 @@ To apply a default background color, assign the `default` property to one of the
 
 ## Overriding the background for a story
 
-The Backgrounds addon enables you to change the background color applied to a story by selecting from the list of predefined background colors in the toolbar. If needed, you can force a story to use a specific background color. There are two ways to do this, which have different behaviors:
+The Backgrounds addon enables you to change the background color applied to a story by selecting from the list of predefined background colors in the toolbar. If needed, you can force a story to use a specific background color.
 
-### Using `globals`
-
-<Callout variant="info">
-  This feature is available when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
-</Callout>
-
-When you specify a background color for a story (or a component's stories) using `globals`, the background color is applied and cannot be changed using the toolbar. This is useful when you want to ensure that a story is always rendered on a specific background color.
+You can set the default background color for a story using the `parameters.backgrounds.default` parameter:
 
 {/* prettier-ignore-start */}
 
-<CodeSnippets path="addon-backgrounds-override-globals.md" usesCsf3 />
+<CodeSnippets path="addon-backgrounds-override-parameters-default.md" usesCsf3 />
 
 {/* prettier-ignore-end */}
 
-### Using `parameters`
+As implied by the name, this method only sets the default background color for a story. You can still change the background color using the toolbar when viewing the story.
 
-If you're not yet using the `globals` API, you can set the default background color for a story using the `parameters.backgrounds.default` parameter:
+<Callout variant="warning" icon="🆕">
 
-{/* prettier-ignore-start */}
+  **With the [`globals` API](#globals-api)**
 
-<CodeSnippets path="addon-backgrounds-override-parameters-default.md" usesCsf3 />
+  When you specify a background color for a story (or a component's stories) using `globals`, the background color is applied and cannot be changed using the toolbar. This is useful when you want to ensure that a story is always rendered on a specific background color.
 
-{/* prettier-ignore-end */}
+  {/* prettier-ignore-start */}
 
-As implied by the name, this method only sets the default background color for a story. You can still change the background color using the toolbar when viewing the story.
+  <CodeSnippets path="addon-backgrounds-override-globals.md" usesCsf3 />
 
-## Extending the configuration
+  {/* prettier-ignore-end */}
 
-You can also define backgrounds per-component or per-story basis through [parameter inheritance](../writing-stories/parameters.mdx#component-parameters).
+</Callout>
 
-### Using `options`
+## Extending the configuration
 
-<Callout variant="info">
-  This API can only be used when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
-</Callout>
+You can also configure backgrounds per-component or per-story basis through [parameter inheritance](../writing-stories/parameters.mdx#component-parameters).
 
-The available background colors are defined using the `options` property. In this example, we'll adjust the colors for all of the Button component's stories:
+To set the available background colors, use the `values` property. In this example, we'll adjust the colors for all of the Button component's stories:
 
 {/* prettier-ignore-start */}
 
-<CodeSnippets path="addon-backgrounds-options-in-meta.md" />
+<CodeSnippets path="addon-backgrounds-values-in-meta.md" />
 
 {/* prettier-ignore-end */}
 
-### Using `values`
+<Callout variant="warning" icon="🆕">
 
-If you're not using the `globals` API, you can define the available background colors using the `values` property. In this example, we'll adjust the colors for all of the Button component's stories:
+  **With the [`globals` API](#globals-api)**
 
-{/* prettier-ignore-start */}
+  The available background colors are defined using the `options` property. In this example, we'll adjust the colors for all of the Button component's stories:
 
-<CodeSnippets path="addon-backgrounds-values-in-meta.md" />
+  {/* prettier-ignore-start */}
 
-{/* prettier-ignore-end */}
+  <CodeSnippets path="addon-backgrounds-options-in-meta.md" />
+
+  {/* prettier-ignore-end */}
+
+</Callout>
 
 ## Disable backgrounds
 
 If you want to turn off backgrounds in a story, you can do so by setting the `backgrounds` parameter like so:
 
-<Callout variant="info">
-  Note that the property name changes when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
+<Callout variant="warning" icon="🆕">
+
+  **With the [`globals` API](#globals-api)**
+
+  Note that the property has been renamed to `disabled`.
+
 </Callout>
 
 {/* prettier-ignore-start */}
@@ -129,25 +133,27 @@ You don't need additional configuration to get started. But its properties are f
 
 ## API
 
-### Globals
+<Callout variant="warning" icon="🆕">
 
-This addon contributes the following globals to Storybook, under the `backgrounds` namespace:
+  **With the [`globals` API](#globals-api)**
 
-<Callout variant="info">
-  These globals are only available when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
-</Callout>
+  ### Globals
 
-#### `grid`
+  This addon contributes the following globals to Storybook, under the `backgrounds` namespace:
 
-Type: Boolean
+  #### `grid`
 
-Whether the [grid](#grid) is displayed.
+  Type: Boolean
 
-#### `value`
+  Whether the [grid](#grid) is displayed.
 
-Type: `string`
+  #### `value`
+
+  Type: `string`
 
-When set, the background color is applied and cannot be changed using the toolbar. Must match the key of one of the [available colors](#using-options). 
+  When set, the background color is applied and cannot be changed using the toolbar. Must match the key of one of the [available colors](#options).
+
+</Callout>
 
 ### Parameters
 
@@ -163,20 +169,12 @@ Default background color. Must match the `name` property of one of the [availabl
 
 #### `disable`
 
-<Callout variant="info">
-  This API is deprecated when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
-</Callout>
-
-Type: `boolean`
+<Callout variant="warning" icon="🆕">
 
-Turn off this addon's behavior. If you wish to turn off this addon for the entire Storybook, you should do so when registering `addon-essentials`. See the [essential addon's docs](../essentials/index.mdx#disabling-addons) for more information.
-
-This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to `true` at the project level, it could be re-enabled by setting it to `false` at the meta (component) or story level.
+  **With the [`globals` API](#globals-api)**
 
-#### `disabled`
+  Note that the property has been renamed to `disabled`.
 
-<Callout variant="info">
-  This API is only available when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
 </Callout>
 
 Type: `boolean`
@@ -248,30 +246,28 @@ Default: `0.5`
 
 The opacity of the grid lines.
 
-#### `options`
+<Callout variant="warning" icon="🆕">
 
-<Callout variant="info">
-  This API is only available when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
-</Callout>
+  **With the [`globals` API](#globals-api)**
 
-Type: `Record<string, { name: string; value: string }>`
+  #### `options`
 
-Required: See description
+  Type: `Record<string, { name: string; value: string }>`
 
-Defines the background colors. See above for a [usage example](#with-options).
+  Required: See description
 
-Required when defining `backgrounds` parameter at project level.
+  Defines the background colors. Replaces [`values`](#values). See above for a [usage example](#configuration).
 
-#### `values`
+  Required when defining `backgrounds` parameter at project level.
 
-<Callout variant="info">
-  This API is deprecated when the [`backgroundsStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#backgroundsstoryglobals) is enabled.
 </Callout>
 
+#### `values`
+
 Type: `{ name: string; value: string }[]`
 
 Required: See description
 
-Available background colors. See above for a [usage example](#using-values).
+Available background colors. See above for a [usage example](#configuration).
 
 Required when defining `backgrounds` parameter at project level.

From 63c1ce270694f79dd85e81ad195a87c501e568a9 Mon Sep 17 00:00:00 2001
From: Kyle Gach <kyle.gach@gmail.com>
Date: Wed, 14 Aug 2024 17:19:41 -0600
Subject: [PATCH 4/5] Further updates

- Polish and details
- Make Viewport match structure and style of Backgrounds
---
 ...md => addon-backgrounds-define-default.md} |   0
 ...md => addon-backgrounds-define-globals.md} |   0
 .../addon-backgrounds-options-in-preview.md   |   8 +
 ...addon-viewport-add-viewport-in-preview.md} |  36 +-
 ...> addon-viewport-configuration-in-meta.md} | 533 ++++--------------
 .../addon-viewport-define-default.md          | 131 +++++
 .../addon-viewport-define-globals.md          | 131 +++++
 .../addon-viewport-options-in-preview.md      |  32 ++
 .../addon-viewport-viewports-in-preview.md    |  29 +
 .../component-story-theme-override-globals.md | 106 ----
 .../storybook-addon-viewports-global-api.md   | 101 ----
 .../storybook-preview-change-viewports.md     |  53 --
 .../storybook-preview-granular-viewports.md   |  83 ---
 ...ybook-preview-migrate-viewports-globals.md | 165 ------
 .../storybook-preview-viewport-add-devices.md |  19 -
 ...rybook-preview-viewport-use-new-devices.md |  45 --
 docs/essentials/backgrounds.mdx               |  57 +-
 docs/essentials/toolbars-and-globals.mdx      |  23 +-
 docs/essentials/viewport.mdx                  | 278 ++++-----
 19 files changed, 649 insertions(+), 1181 deletions(-)
 rename docs/_snippets/{addon-backgrounds-override-parameters-default.md => addon-backgrounds-define-default.md} (100%)
 rename docs/_snippets/{addon-backgrounds-override-globals.md => addon-backgrounds-define-globals.md} (100%)
 rename docs/_snippets/{storybook-preview-merge-viewports.md => addon-viewport-add-viewport-in-preview.md} (84%)
 rename docs/_snippets/{my-component-story-configure-viewports.md => addon-viewport-configuration-in-meta.md} (54%)
 create mode 100644 docs/_snippets/addon-viewport-define-default.md
 create mode 100644 docs/_snippets/addon-viewport-define-globals.md
 create mode 100644 docs/_snippets/addon-viewport-options-in-preview.md
 create mode 100644 docs/_snippets/addon-viewport-viewports-in-preview.md
 delete mode 100644 docs/_snippets/component-story-theme-override-globals.md
 delete mode 100644 docs/_snippets/storybook-addon-viewports-global-api.md
 delete mode 100644 docs/_snippets/storybook-preview-change-viewports.md
 delete mode 100644 docs/_snippets/storybook-preview-granular-viewports.md
 delete mode 100644 docs/_snippets/storybook-preview-migrate-viewports-globals.md
 delete mode 100644 docs/_snippets/storybook-preview-viewport-add-devices.md
 delete mode 100644 docs/_snippets/storybook-preview-viewport-use-new-devices.md

diff --git a/docs/_snippets/addon-backgrounds-override-parameters-default.md b/docs/_snippets/addon-backgrounds-define-default.md
similarity index 100%
rename from docs/_snippets/addon-backgrounds-override-parameters-default.md
rename to docs/_snippets/addon-backgrounds-define-default.md
diff --git a/docs/_snippets/addon-backgrounds-override-globals.md b/docs/_snippets/addon-backgrounds-define-globals.md
similarity index 100%
rename from docs/_snippets/addon-backgrounds-override-globals.md
rename to docs/_snippets/addon-backgrounds-define-globals.md
diff --git a/docs/_snippets/addon-backgrounds-options-in-preview.md b/docs/_snippets/addon-backgrounds-options-in-preview.md
index af9498d8acd4..80cda975859e 100644
--- a/docs/_snippets/addon-backgrounds-options-in-preview.md
+++ b/docs/_snippets/addon-backgrounds-options-in-preview.md
@@ -11,6 +11,10 @@ export default {
       },
     },
   },
+  initialGlobals: {
+    // 👇 Set the initial background color
+    backgrounds: { value: 'light' },
+  },
 };
 ```
 
@@ -30,6 +34,10 @@ const preview: Preview = {
       },
     },
   },
+  initialGlobals: {
+    // 👇 Set the initial background color
+    backgrounds: { value: 'light' },
+  },
 };
 
 export default preview;
diff --git a/docs/_snippets/storybook-preview-merge-viewports.md b/docs/_snippets/addon-viewport-add-viewport-in-preview.md
similarity index 84%
rename from docs/_snippets/storybook-preview-merge-viewports.md
rename to docs/_snippets/addon-viewport-add-viewport-in-preview.md
index 515e3d90b80e..da27fd16b6bf 100644
--- a/docs/_snippets/storybook-preview-merge-viewports.md
+++ b/docs/_snippets/addon-viewport-add-viewport-in-preview.md
@@ -1,7 +1,7 @@
-```js filename=".storybook/preview.js" renderer="common" language="js" tabTitle="globals-api"
+```js filename=".storybook/preview.js" renderer="common" language="js" tabTitle="Without globals API"
 import { MINIMAL_VIEWPORTS } from '@storybook/addon-viewport';
 
-const customViewports = {
+const kindleViewports = {
   kindleFire2: {
     name: 'Kindle Fire 2',
     styles: {
@@ -21,22 +21,21 @@ const customViewports = {
 export default {
   parameters: {
     viewport: {
-      options: {
+      viewports: {
         ...MINIMAL_VIEWPORTS,
-        ...customViewports,
+        ...kindleViewports,
       },
     },
   },
 };
 ```
 
-```ts filename=".storybook/preview.ts" renderer="common" language="ts" tabTitle="globals-api"
+```ts filename=".storybook/preview.ts" renderer="common" language="ts" tabTitle="Without globals API"
 // Replace your-framework with the framework you are using (e.g., react, vue3)
-import { Preview } from '@storybook/your-framework';
-
+import type { Preview } from '@storybook/your-framework';
 import { MINIMAL_VIEWPORTS } from '@storybook/addon-viewport';
 
-const customViewports = {
+const kindleViewports = {
   kindleFire2: {
     name: 'Kindle Fire 2',
     styles: {
@@ -56,9 +55,9 @@ const customViewports = {
 const preview: Preview = {
   parameters: {
     viewport: {
-      options: {
+      viewports: {
         ...MINIMAL_VIEWPORTS,
-        ...customViewports,
+        ...kindleViewports,
       },
     },
   },
@@ -67,10 +66,10 @@ const preview: Preview = {
 export default preview;
 ```
 
-```js filename=".storybook/preview.js" renderer="common" language="js" tabTitle="without-globals"
+```js filename=".storybook/preview.js" renderer="common" language="js" tabTitle="With globals API"
 import { MINIMAL_VIEWPORTS } from '@storybook/addon-viewport';
 
-const customViewports = {
+const kindleViewports = {
   kindleFire2: {
     name: 'Kindle Fire 2',
     styles: {
@@ -90,22 +89,21 @@ const customViewports = {
 export default {
   parameters: {
     viewport: {
-      viewports: {
+      options: {
         ...MINIMAL_VIEWPORTS,
-        ...customViewports,
+        ...kindleViewports,
       },
     },
   },
 };
 ```
 
-```ts filename=".storybook/preview.ts" renderer="common" language="ts" tabTitle="without-globals"
+```ts filename=".storybook/preview.ts" renderer="common" language="ts" tabTitle="With globals API"
 // Replace your-framework with the framework you are using (e.g., react, vue3)
 import { Preview } from '@storybook/your-framework';
-
 import { MINIMAL_VIEWPORTS } from '@storybook/addon-viewport';
 
-const customViewports = {
+const kindleViewports = {
   kindleFire2: {
     name: 'Kindle Fire 2',
     styles: {
@@ -125,9 +123,9 @@ const customViewports = {
 const preview: Preview = {
   parameters: {
     viewport: {
-      viewports: {
+      options: {
         ...MINIMAL_VIEWPORTS,
-        ...customViewports,
+        ...kindleViewports,
       },
     },
   },
diff --git a/docs/_snippets/my-component-story-configure-viewports.md b/docs/_snippets/addon-viewport-configuration-in-meta.md
similarity index 54%
rename from docs/_snippets/my-component-story-configure-viewports.md
rename to docs/_snippets/addon-viewport-configuration-in-meta.md
index 93b252766329..4eca0f715ef5 100644
--- a/docs/_snippets/my-component-story-configure-viewports.md
+++ b/docs/_snippets/addon-viewport-configuration-in-meta.md
@@ -1,6 +1,5 @@
-```ts filename="MyComponent.stories.ts" renderer="angular" language="ts" tabTitle="globals-api"
+```ts filename="MyComponent.stories.ts" renderer="angular" language="ts" tabTitle="Without globals API"
 import type { Meta, StoryObj } from '@storybook/angular';
-
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
 import { MyComponent } from './MyComponent.component';
@@ -8,27 +7,17 @@ import { MyComponent } from './MyComponent.component';
 const meta: Meta<MyComponent> = {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      options: INITIAL_VIEWPORTS,
+      //👇 Set available viewports for every story in the file
+      viewports: INITIAL_VIEWPORTS,
     },
   },
 };
 
 export default meta;
-type Story = StoryObj<MyComponent>;
-
-export const MyStory: Story = {
-  globals: {
-    viewport: {
-      value: 'iphone6',
-    },
-  },
-};
 ```
 
-```js filename="MyComponent.stories.js|jsx" renderer="react" language="js" tabTitle="globals-api"
+```js filename="MyComponent.stories.js|jsx" renderer="react" language="js" tabTitle="Without globals API"
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
 import { MyComponent } from './MyComponent';
@@ -36,27 +25,16 @@ import { MyComponent } from './MyComponent';
 export default {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
-    viewport: {
-      //👇 The viewports you want to use
-      options: INITIAL_VIEWPORTS,
-    },
-  },
-};
-
-export const MyStory = {
-  globals: {
     viewport: {
-      //👇 Your own default viewport
-      value: 'iphone6',
+      //👇 Set available viewports for every story in the file
+      viewports: INITIAL_VIEWPORTS,
     },
   },
 };
 ```
 
-```ts filename="MyComponent.stories.ts|tsx" renderer="react" language="ts-4-9" tabTitle="globals-api"
+```ts filename="MyComponent.stories.ts|tsx" renderer="react" language="ts-4-9" tabTitle="Without globals API"
 import type { Meta, StoryObj } from '@storybook/react';
-
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
 import { MyComponent } from './MyComponent';
@@ -64,29 +42,18 @@ import { MyComponent } from './MyComponent';
 const meta = {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      options: INITIAL_VIEWPORTS,
+      //👇 Set available viewports for every story in the file
+      viewports: INITIAL_VIEWPORTS,
     },
   },
 } satisfies Meta<typeof MyComponent>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const MyStory: Story = {
-  globals: {
-    viewport: {
-      value: 'iphone6',
-    },
-  },
-};
 ```
 
-```ts filename="MyComponent.stories.ts|tsx" renderer="react" language="ts" tabTitle="globals-api"
+```ts filename="MyComponent.stories.ts|tsx" renderer="react" language="ts" tabTitle="Without globals API"
 import type { Meta, StoryObj } from '@storybook/react';
-
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
 import { MyComponent } from './MyComponent';
@@ -94,401 +61,246 @@ import { MyComponent } from './MyComponent';
 const meta: Meta<typeof MyComponent> = {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      options: INITIAL_VIEWPORTS,
+      //👇 Set available viewports for every story in the file
+      viewports: INITIAL_VIEWPORTS,
     },
   },
 };
 
 export default meta;
-type Story = StoryObj<typeof MyComponent>;
-
-export const MyStory: Story = {
-  globals: {
-    viewport: {
-      value: 'iphone6',
-    },
-  },
-};
 ```
 
-```js filename="MyComponent.stories.js" renderer="svelte" language="js" tabTitle="globals-api"
+```js filename="MyComponent.stories.js|jsx" renderer="solid" language="js" tabTitle="Without globals API"
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
-import MyComponent from './MyComponent.svelte';
+import { MyComponent } from './MyComponent';
 
 export default {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      options: INITIAL_VIEWPORTS,
-    },
-  },
-};
-
-export const MyStory = {
-  globals: {
-    viewport: {
-      value: 'iphone6',
+      //👇 Set available viewports for every story in the file
+      viewports: INITIAL_VIEWPORTS,
     },
   },
 };
 ```
 
-```ts filename="MyComponent.stories.ts" renderer="svelte" language="ts-4-9" tabTitle="globals-api"
-import type { Meta, StoryObj } from '@storybook/svelte';
-
+```tsx filename="MyComponent.stories.ts|tsx" renderer="solid" language="ts-4-9" tabTitle="Without globals API"
+import type { Meta, StoryObj } from 'storybook-solidjs';
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
-import MyComponent from './MyComponent.svelte';
+import { MyComponent } from './MyComponent';
 
 const meta = {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      options: INITIAL_VIEWPORTS,
+      //👇 Set available viewports for every story in the file
+      viewports: INITIAL_VIEWPORTS,
     },
   },
 } satisfies Meta<typeof MyComponent>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const MyStory: Story = {
-  globals: {
-    viewport: {
-      value: 'iphone6',
-    },
-  },
-};
 ```
 
-```ts filename="MyComponent.stories.ts" renderer="svelte" language="ts" tabTitle="globals-api"
-import type { Meta, StoryObj } from '@storybook/svelte';
-
+```tsx filename="MyComponent.stories.ts|tsx" renderer="solid" language="ts" tabTitle="Without globals API"
+import type { Meta, StoryObj } from 'storybook-solidjs';
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
-import MyComponent from './MyComponent.svelte';
+import { MyComponent } from './MyComponent';
 
 const meta: Meta<typeof MyComponent> = {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      options: INITIAL_VIEWPORTS,
+      //👇 Set available viewports for every story in the file
+      viewports: INITIAL_VIEWPORTS,
     },
   },
 };
 
 export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const MyStory: Story = {
-  globals: {
-    viewport: {
-      value: 'iphone6',
-    },
-  },
-};
 ```
 
-```js filename="MyComponent.stories.js" renderer="vue" language="js" tabTitle="globals-api"
+```js filename="MyComponent.stories.js" renderer="svelte" language="js" tabTitle="Without globals API"
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
-import MyComponent from './MyComponent.vue';
+import MyComponent from './MyComponent.svelte';
 
 export default {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
-    viewport: {
-      //👇 The viewports you want to use
-      options: INITIAL_VIEWPORTS,
-    },
-  },
-};
-
-export const MyStory = {
-  globals: {
     viewport: {
-      value: 'iphone6',
+      //👇 Set available viewports for every story in the file
+      viewports: INITIAL_VIEWPORTS,
     },
   },
 };
 ```
 
-```ts filename="MyComponent.stories.ts" renderer="vue" language="ts-4-9" tabTitle="globals-api"
-import type { Meta, StoryObj } from '@storybook/vue3';
-
+```ts filename="MyComponent.stories.ts" renderer="svelte" language="ts-4-9" tabTitle="Without globals API"
+import type { Meta, StoryObj } from '@storybook/svelte';
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
-import MyComponent from './MyComponent.vue';
+import MyComponent from './MyComponent.svelte';
 
 const meta = {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      options: INITIAL_VIEWPORTS,
+      //👇 Set available viewports for every story in the file
+      viewports: INITIAL_VIEWPORTS,
     },
   },
 } satisfies Meta<typeof MyComponent>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const MyStory: Story = {
-  globals: {
-    viewport: {
-      value: 'iphone6',
-    },
-  },
-};
 ```
 
-```ts filename="MyComponent.stories.ts" renderer="vue" language="ts" tabTitle="globals-api"
-import type { Meta, StoryObj } from '@storybook/vue3';
-
+```ts filename="MyComponent.stories.ts" renderer="svelte" language="ts" tabTitle="Without globals API"
+import type { Meta, StoryObj } from '@storybook/svelte';
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
-import MyComponent from './MyComponent.vue';
+import MyComponent from './MyComponent.svelte';
 
 const meta: Meta<typeof MyComponent> = {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      options: INITIAL_VIEWPORTS,
+      //👇 Set available viewports for every story in the file
+      viewports: INITIAL_VIEWPORTS,
     },
   },
 };
 
 export default meta;
-type Story = StoryObj<typeof MyComponent>;
-
-export const MyStory: Story = {
-  globals: {
-    viewport: {
-      value: 'iphone6',
-    },
-  },
-};
 ```
 
-```js filename="MyComponent.stories.js" renderer="web-components" language="js" tabTitle="globals-api"
+```js filename="MyComponent.stories.js" renderer="vue" language="js" tabTitle="Without globals API"
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
+import MyComponent from './MyComponent.vue';
+
 export default {
-  component: 'my-component',
+  component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
-    viewport: {
-      //👇 The viewports you want to use
-      options: INITIAL_VIEWPORTS,
-    },
-  },
-};
-
-export const MyStory = {
-  globals: {
     viewport: {
-      value: 'iphone6',
+      //👇 Set available viewports for every story in the file
+      viewports: INITIAL_VIEWPORTS,
     },
   },
 };
 ```
 
-```ts filename="MyComponent.stories.ts" renderer="web-components" language="ts" tabTitle="globals-api"
-import type { Meta, StoryObj } from '@storybook/web-components';
-
+```ts filename="MyComponent.stories.ts" renderer="vue" language="ts-4-9" tabTitle="Without globals API"
+import type { Meta, StoryObj } from '@storybook/vue3';
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
-const meta: Meta = {
-  component: 'my-component',
+import MyComponent from './MyComponent.vue';
+
+const meta = {
+  component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      options: INITIAL_VIEWPORTS,
+      //👇 Set available viewports for every story in the file
+      viewports: INITIAL_VIEWPORTS,
     },
   },
-};
+} satisfies Meta<typeof MyComponent>;
 
 export default meta;
-type Story = StoryObj;
-
-export const MyStory: Story = {
-  globals: {
-    viewport: {
-      value: 'iphone6',
-    },
-  },
-};
 ```
 
-```ts filename="MyComponent.stories.ts" renderer="angular" language="ts" tabTitle="without-globals"
-import type { Meta, StoryObj } from '@storybook/angular';
-
+```ts filename="MyComponent.stories.ts" renderer="vue" language="ts" tabTitle="Without globals API"
+import type { Meta, StoryObj } from '@storybook/vue3';
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
-import { MyComponent } from './MyComponent.component';
+import MyComponent from './MyComponent.vue';
 
-const meta: Meta<MyComponent> = {
+const meta: Meta<typeof MyComponent> = {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
+      //👇 Set available viewports for every story in the file
       viewports: INITIAL_VIEWPORTS,
-
-      //👇 Your own default viewport
-      defaultViewport: 'iphone6',
     },
   },
 };
 
 export default meta;
-type Story = StoryObj<MyComponent>;
-
-export const MyStory: Story = {
-  parameters: {
-    viewport: {
-      defaultViewport: 'iphonex',
-    },
-  },
-};
 ```
 
-```js filename="MyComponent.stories.js|jsx" renderer="react" language="js" tabTitle="without-globals"
+```js filename="MyComponent.stories.js" renderer="web-components" language="js" tabTitle="Without globals API"
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
-import { MyComponent } from './MyComponent';
-
 export default {
-  component: MyComponent,
+  component: 'my-component',
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
+      //👇 Set available viewports for every story in the file
       viewports: INITIAL_VIEWPORTS,
-      //👇 Your own default viewport
-      defaultViewport: 'iphone6',
-    },
-  },
-};
-
-export const MyStory = {
-  parameters: {
-    viewport: {
-      defaultViewport: 'iphonex',
     },
   },
 };
 ```
 
-```ts filename="MyComponent.stories.ts|tsx" renderer="react" language="ts-4-9" tabTitle="without-globals"
-import type { Meta, StoryObj } from '@storybook/react';
-
+```ts filename="MyComponent.stories.ts" renderer="web-components" language="ts" tabTitle="Without globals API"
+import type { Meta, StoryObj } from '@storybook/web-components';
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
-import { MyComponent } from './MyComponent';
-
-const meta = {
-  component: MyComponent,
+const meta: Meta = {
+  component: 'my-component',
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
+      //👇 Set available viewports for every story in the file
       viewports: INITIAL_VIEWPORTS,
-      //👇 Your own default viewport
-      defaultViewport: 'iphone6',
     },
   },
-} satisfies Meta<typeof MyComponent>;
+};
 
 export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const MyStory: Story = {
-  parameters: {
-    viewport: {
-      defaultViewport: 'iphonex',
-    },
-  },
-};
 ```
 
-```ts filename="MyComponent.stories.ts|tsx" renderer="react" language="ts" tabTitle="without-globals"
-import type { Meta, StoryObj } from '@storybook/react';
-
+```ts filename="MyComponent.stories.ts" renderer="angular" language="ts" tabTitle="With globals API"
+import type { Meta, StoryObj } from '@storybook/angular';
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
-import { MyComponent } from './MyComponent';
+import { MyComponent } from './MyComponent.component';
 
-const meta: Meta<typeof MyComponent> = {
+const meta: Meta<MyComponent> = {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      viewports: INITIAL_VIEWPORTS,
-      //👇 Your own default viewport
-      defaultViewport: 'iphone6',
+      //👇 Set available viewports for every story in the file
+      options: INITIAL_VIEWPORTS,
     },
   },
 };
 
 export default meta;
-type Story = StoryObj<typeof MyComponent>;
-
-export const MyStory: Story = {
-  parameters: {
-    viewport: {
-      defaultViewport: 'iphonex',
-    },
-  },
-};
 ```
 
-```js filename="MyComponent.stories.js|jsx" renderer="solid" language="js" tabTitle="without-globals"
+```js filename="MyComponent.stories.js|jsx" renderer="react" language="js" tabTitle="With globals API"
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
 import { MyComponent } from './MyComponent';
 
 export default {
   component: MyComponent,
-  parameters: {
-    //👇 The viewports object from the Essentials addon
-    viewport: {
-      //👇 The viewports you want to use
-      viewports: INITIAL_VIEWPORTS,
-      //👇 Your own default viewport
-      defaultViewport: 'iphone6',
-    },
-  },
-};
-
-export const MyStory = {
   parameters: {
     viewport: {
-      defaultViewport: 'iphonex',
+      //👇 Set available viewports for every story in the file
+      options: INITIAL_VIEWPORTS,
     },
   },
 };
 ```
 
-```tsx filename="MyComponent.stories.ts|tsx" renderer="solid" language="ts-4-9" tabTitle="without-globals"
-import type { Meta, StoryObj } from 'storybook-solidjs';
-
+```ts filename="MyComponent.stories.ts|tsx" renderer="react" language="ts-4-9" tabTitle="With globals API"
+import type { Meta, StoryObj } from '@storybook/react';
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
 import { MyComponent } from './MyComponent';
@@ -496,31 +308,18 @@ import { MyComponent } from './MyComponent';
 const meta = {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      viewports: INITIAL_VIEWPORTS,
-      //👇 Your own default viewport
-      defaultViewport: 'iphone6',
+      //👇 Set available viewports for every story in the file
+      options: INITIAL_VIEWPORTS,
     },
   },
 } satisfies Meta<typeof MyComponent>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const MyStory: Story = {
-  parameters: {
-    viewport: {
-      defaultViewport: 'iphonex',
-    },
-  },
-};
 ```
 
-```tsx filename="MyComponent.stories.ts|tsx" renderer="solid" language="ts" tabTitle="without-globals"
-import type { Meta, StoryObj } from 'storybook-solidjs';
-
+```ts filename="MyComponent.stories.ts|tsx" renderer="react" language="ts" tabTitle="With globals API"
+import type { Meta, StoryObj } from '@storybook/react';
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
 import { MyComponent } from './MyComponent';
@@ -528,29 +327,17 @@ import { MyComponent } from './MyComponent';
 const meta: Meta<typeof MyComponent> = {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      viewports: INITIAL_VIEWPORTS,
-      //👇 Your own default viewport
-      defaultViewport: 'iphone6',
+      //👇 Set available viewports for every story in the file
+      options: INITIAL_VIEWPORTS,
     },
   },
 };
 
 export default meta;
-type Story = StoryObj<typeof MyComponent>;
-
-export const MyStory: Story = {
-  parameters: {
-    viewport: {
-      defaultViewport: 'iphonex',
-    },
-  },
-};
 ```
 
-```js filename="MyComponent.stories.js" renderer="svelte" language="js" tabTitle="without-globals"
+```js filename="MyComponent.stories.js" renderer="svelte" language="js" tabTitle="With globals API"
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
 import MyComponent from './MyComponent.svelte';
@@ -558,28 +345,16 @@ import MyComponent from './MyComponent.svelte';
 export default {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      viewports: INITIAL_VIEWPORTS,
-      //👇 Your own default viewport
-      defaultViewport: 'iphone6',
-    },
-  },
-};
-
-export const MyStory = {
-  parameters: {
-    viewport: {
-      defaultViewport: 'iphonex',
+      //👇 Set available viewports for every story in the file
+      options: INITIAL_VIEWPORTS,
     },
   },
 };
 ```
 
-```ts filename="MyComponent.stories.ts" renderer="svelte" language="ts-4-9" tabTitle="without-globals"
+```ts filename="MyComponent.stories.ts" renderer="svelte" language="ts-4-9" tabTitle="With globals API"
 import type { Meta, StoryObj } from '@storybook/svelte';
-
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
 import MyComponent from './MyComponent.svelte';
@@ -587,31 +362,18 @@ import MyComponent from './MyComponent.svelte';
 const meta = {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      viewports: INITIAL_VIEWPORTS,
-      //👇 Your own default viewport
-      defaultViewport: 'iphone6',
+      //👇 Set available viewports for every story in the file
+      options: INITIAL_VIEWPORTS,
     },
   },
 } satisfies Meta<typeof MyComponent>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const MyStory: Story = {
-  parameters: {
-    viewport: {
-      defaultViewport: 'iphonex',
-    },
-  },
-};
 ```
 
-```ts filename="MyComponent.stories.ts" renderer="svelte" language="ts" tabTitle="without-globals"
+```ts filename="MyComponent.stories.ts" renderer="svelte" language="ts" tabTitle="With globals API"
 import type { Meta, StoryObj } from '@storybook/svelte';
-
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
 import MyComponent from './MyComponent.svelte';
@@ -619,29 +381,17 @@ import MyComponent from './MyComponent.svelte';
 const meta: Meta<typeof MyComponent> = {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      viewports: INITIAL_VIEWPORTS,
-      //👇 Your own default viewport
-      defaultViewport: 'iphone6',
+      //👇 Set available viewports for every story in the file
+      options: INITIAL_VIEWPORTS,
     },
   },
 };
 
 export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const MyStory: Story = {
-  parameters: {
-    viewport: {
-      defaultViewport: 'iphonex',
-    },
-  },
-};
 ```
 
-```js filename="MyComponent.stories.js" renderer="vue" language="js" tabTitle="without-globals"
+```js filename="MyComponent.stories.js" renderer="vue" language="js" tabTitle="With globals API"
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
 import MyComponent from './MyComponent.vue';
@@ -649,29 +399,16 @@ import MyComponent from './MyComponent.vue';
 export default {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      viewports: INITIAL_VIEWPORTS,
-
-      //👇 Your own default viewport
-      defaultViewport: 'iphone6',
-    },
-  },
-};
-
-export const MyStory = {
-  parameters: {
-    viewport: {
-      defaultViewport: 'iphonex',
+      //👇 Set available viewports for every story in the file
+      options: INITIAL_VIEWPORTS,
     },
   },
 };
 ```
 
-```ts filename="MyComponent.stories.ts" renderer="vue" language="ts-4-9" tabTitle="without-globals"
+```ts filename="MyComponent.stories.ts" renderer="vue" language="ts-4-9" tabTitle="With globals API"
 import type { Meta, StoryObj } from '@storybook/vue3';
-
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
 import MyComponent from './MyComponent.vue';
@@ -679,30 +416,17 @@ import MyComponent from './MyComponent.vue';
 const meta = {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      viewports: INITIAL_VIEWPORTS,
-
-      //👇 Your own default viewport
-      defaultViewport: 'iphone6',
+      //👇 Set available viewports for every story in the file
+      options: INITIAL_VIEWPORTS,
     },
   },
 } satisfies Meta<typeof MyComponent>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const MyStory: Story = {
-  parameters: {
-    viewport: {
-      defaultViewport: 'iphonex',
-    },
-  },
-};
 ```
 
-```ts filename="MyComponent.stories.ts" renderer="vue" language="ts" tabTitle="without-globals"
+```ts filename="MyComponent.stories.ts" renderer="vue" language="ts" tabTitle="With globals API"
 import type { Meta, StoryObj } from '@storybook/vue3';
 
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
@@ -712,80 +436,43 @@ import MyComponent from './MyComponent.vue';
 const meta: Meta<typeof MyComponent> = {
   component: MyComponent,
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      viewports: INITIAL_VIEWPORTS,
-
-      //👇 Your own default viewport
-      defaultViewport: 'iphone6',
+      //👇 Set available viewports for every story in the file
+      options: INITIAL_VIEWPORTS,
     },
   },
 };
 
 export default meta;
-type Story = StoryObj<typeof MyComponent>;
-
-export const MyStory: Story = {
-  parameters: {
-    viewport: {
-      defaultViewport: 'iphonex',
-    },
-  },
-};
 ```
 
-```js filename="MyComponent.stories.js" renderer="web-components" language="js" tabTitle="without-globals"
+```js filename="MyComponent.stories.js" renderer="web-components" language="js" tabTitle="With globals API"
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
 export default {
   component: 'my-component',
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      viewports: INITIAL_VIEWPORTS,
-      //👇 Your own default viewport
-      defaultViewport: 'iphone6',
-    },
-  },
-};
-
-export const MyStory = {
-  parameters: {
-    viewport: {
-      defaultViewport: 'iphonex',
+      //👇 Set available viewports for every story in the file
+      options: INITIAL_VIEWPORTS,
     },
   },
 };
 ```
 
-```ts filename="MyComponent.stories.ts" renderer="web-components" language="ts" tabTitle="without-globals"
+```ts filename="MyComponent.stories.ts" renderer="web-components" language="ts" tabTitle="With globals API"
 import type { Meta, StoryObj } from '@storybook/web-components';
-
 import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
 
 const meta: Meta = {
   component: 'my-component',
   parameters: {
-    //👇 The viewports object from the Essentials addon
     viewport: {
-      //👇 The viewports you want to use
-      viewports: INITIAL_VIEWPORTS,
-      //👇 Your own default viewport
-      defaultViewport: 'iphone6',
+      //👇 Set available viewports for every story in the file
+      options: INITIAL_VIEWPORTS,
     },
   },
 };
 
 export default meta;
-type Story = StoryObj;
-
-export const MyStory: Story = {
-  parameters: {
-    viewport: {
-      defaultViewport: 'iphonex',
-    },
-  },
-};
 ```
diff --git a/docs/_snippets/addon-viewport-define-default.md b/docs/_snippets/addon-viewport-define-default.md
new file mode 100644
index 000000000000..d3de90dd4878
--- /dev/null
+++ b/docs/_snippets/addon-viewport-define-default.md
@@ -0,0 +1,131 @@
+```ts filename="Button.stories.ts" renderer="angular" language="ts"
+import type { Meta, StoryObj } from '@storybook/angular';
+
+import { Button } from './button.component';
+
+const meta: Meta<Button> = {
+  component: Button,
+  parameters: {
+    // 👇 Set default viewport for all component stories
+    viewport: { defaultViewport: 'tablet' },
+  },
+};
+
+export default meta;
+type Story = StoryObj<Button>;
+
+export const OnPhone: Story = {
+  parameters: {
+    // 👇 Override default viewport for this story
+    viewport: { defaultViewport: 'mobile1' },
+  },
+};
+```
+
+```js filename="Button.stories.js|jsx" renderer="common" language="js"
+import { Button } from './Button';
+
+export default {
+  component: Button,
+  parameters: {
+    // 👇 Set default viewport for all component stories
+    viewport: { defaultViewport: 'tablet' },
+  },
+};
+
+export const OnPhone = {
+  parameters: {
+    // 👇 Override default viewport for this story
+    viewport: { defaultViewport: 'mobile1' },
+  },
+};
+```
+
+```ts filename="Button.stories.ts|tsx" renderer="common" language="ts-4-9"
+// Replace your-framework with the name of your framework
+import type { Meta, StoryObj } from '@storybook/your-framework';
+
+import { Button } from './Button';
+
+const meta = {
+  component: Button,
+  parameters: {
+    // 👇 Set default viewport for all component stories
+    viewport: { defaultViewport: 'tablet' },
+  },
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const OnPhone: Story = {
+  parameters: {
+    // 👇 Override default viewport for this story
+    viewport: { defaultViewport: 'mobile1' },
+  },
+};
+```
+
+```ts filename="Button.stories.ts|tsx" renderer="common" language="ts"
+// Replace your-framework with the name of your framework
+import type { Meta, StoryObj } from '@storybook/your-framework';
+
+import { Button } from './Button';
+
+const meta: Meta<typeof Button> = {
+  component: Button,
+  parameters: {
+    // 👇 Set default viewport for all component stories
+    viewport: { defaultViewport: 'tablet' },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Button>;
+
+export const OnPhone: Story = {
+  parameters: {
+    // 👇 Override default viewport for this story
+    viewport: { defaultViewport: 'mobile1' },
+  },
+};
+```
+
+```js filename="Button.stories.js" renderer="web-components" language="js"
+export default {
+  component: 'demo-button',
+  parameters: {
+    // 👇 Set default viewport for all component stories
+    viewport: { defaultViewport: 'tablet' },
+  },
+};
+
+export const OnPhone = {
+  parameters: {
+    // 👇 Override default viewport for this story
+    viewport: { defaultViewport: 'mobile1' },
+  },
+};
+```
+
+```ts filename="Button.stories.ts" renderer="web-components" language="ts"
+import type { Meta, StoryObj } from '@storybook/web-components';
+
+const meta: Meta = {
+  component: 'demo-button',
+  parameters: {
+    // 👇 Set default viewport for all component stories
+    viewport: { defaultViewport: 'tablet' },
+  },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const OnPhone: Story = {
+  parameters: {
+    // 👇 Override default viewport for this story
+    viewport: { defaultViewport: 'mobile1' },
+  },
+};
+```
diff --git a/docs/_snippets/addon-viewport-define-globals.md b/docs/_snippets/addon-viewport-define-globals.md
new file mode 100644
index 000000000000..29dec7e660f9
--- /dev/null
+++ b/docs/_snippets/addon-viewport-define-globals.md
@@ -0,0 +1,131 @@
+```ts filename="Button.stories.ts" renderer="angular" language="ts"
+import type { Meta, StoryObj } from '@storybook/angular';
+
+import { Button } from './button.component';
+
+const meta: Meta<Button> = {
+  component: Button,
+  globals: {
+    // 👇 Set viewport for all component stories
+    viewport: { value: 'tablet', isRotated: false },
+  },
+};
+
+export default meta;
+type Story = StoryObj<Button>;
+
+export const OnPhone: Story = {
+  globals: {
+    // 👇 Override viewport for this story
+    viewport: { value: 'mobile1', isRotated: false },
+  },
+};
+```
+
+```js filename="Button.stories.js|jsx" renderer="common" language="js"
+import { Button } from './Button';
+
+export default {
+  component: Button,
+  globals: {
+    // 👇 Set viewport for all component stories
+    viewport: { value: 'tablet', isRotated: false },
+  },
+};
+
+export const OnPhone = {
+  globals: {
+    // 👇 Override viewport for this story
+    viewport: { value: 'mobile1', isRotated: false },
+  },
+};
+```
+
+```ts filename="Button.stories.ts|tsx" renderer="common" language="ts-4-9"
+// Replace your-framework with the name of your framework
+import type { Meta, StoryObj } from '@storybook/your-framework';
+
+import { Button } from './Button';
+
+const meta = {
+  component: Button,
+  globals: {
+    // 👇 Set viewport for all component stories
+    viewport: { value: 'tablet', isRotated: false },
+  },
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const OnPhone: Story = {
+  globals: {
+    // 👇 Override viewport for this story
+    viewport: { value: 'mobile1', isRotated: false },
+  },
+};
+```
+
+```ts filename="Button.stories.ts|tsx" renderer="common" language="ts"
+// Replace your-framework with the name of your framework
+import type { Meta, StoryObj } from '@storybook/your-framework';
+
+import { Button } from './Button';
+
+const meta: Meta<typeof Button> = {
+  component: Button,
+  globals: {
+    // 👇 Set viewport for all component stories
+    viewport: { value: 'tablet', isRotated: false },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Button>;
+
+export const OnPhone: Story = {
+  globals: {
+    // 👇 Override viewport for this story
+    viewport: { value: 'mobile1', isRotated: false },
+  },
+};
+```
+
+```js filename="Button.stories.js" renderer="web-components" language="js"
+export default {
+  component: 'demo-button',
+  globals: {
+    // 👇 Set viewport for all component stories
+    viewport: { value: 'tablet', isRotated: false },
+  },
+};
+
+export const OnPhone = {
+  globals: {
+    // 👇 Override viewport for this story
+    viewport: { value: 'mobile1', isRotated: false },
+  },
+};
+```
+
+```ts filename="Button.stories.ts" renderer="web-components" language="ts"
+import type { Meta, StoryObj } from '@storybook/web-components';
+
+const meta: Meta = {
+  component: 'demo-button',
+  globals: {
+    // 👇 Set viewport for all component stories
+    viewport: { value: 'tablet', isRotated: false },
+  },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const OnPhone: Story = {
+  globals: {
+    // 👇 Override viewport for this story
+    viewport: { value: 'mobile1', isRotated: false },
+  },
+};
+```
diff --git a/docs/_snippets/addon-viewport-options-in-preview.md b/docs/_snippets/addon-viewport-options-in-preview.md
new file mode 100644
index 000000000000..34b8f25c46f6
--- /dev/null
+++ b/docs/_snippets/addon-viewport-options-in-preview.md
@@ -0,0 +1,32 @@
+```js filename=".storybook/preview.js" renderer="common" language="js"
+import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
+
+export default {
+  parameters: {
+    viewport: {
+      viewports: INITIAL_VIEWPORTS,
+    },
+  },
+  initialGlobals: {
+    viewport: { value: 'ipad', isRotated: false },
+  },
+};
+```
+
+```ts filename=".storybook/preview.ts" renderer="common" language="ts"
+// Replace your-framework with the framework you are using (e.g., react, vue3)
+import { Preview } from '@storybook/your-framework';
+
+const preview: Preview = {
+  parameters: {
+    viewport: {
+      viewports: INITIAL_VIEWPORTS,
+    },
+  },
+  initialGlobals: {
+    viewport: { value: 'ipad', isRotated: false },
+  },
+};
+
+export default preview;
+```
diff --git a/docs/_snippets/addon-viewport-viewports-in-preview.md b/docs/_snippets/addon-viewport-viewports-in-preview.md
new file mode 100644
index 000000000000..f7d71004f8b7
--- /dev/null
+++ b/docs/_snippets/addon-viewport-viewports-in-preview.md
@@ -0,0 +1,29 @@
+```js filename=".storybook/preview.js" renderer="common" language="js"
+import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
+
+export default {
+  parameters: {
+    viewport: {
+      viewports: INITIAL_VIEWPORTS,
+      defaultViewport: 'ipad',
+    },
+  },
+};
+```
+
+```ts filename=".storybook/preview.ts" renderer="common" language="ts"
+// Replace your-framework with the framework you are using (e.g., react, vue3)
+import { Preview } from '@storybook/your-framework';
+import { INITIAL_VIEWPORTS } from '@storybook/addon-viewport';
+
+const preview: Preview = {
+  parameters: {
+    viewport: {
+      viewports: INITIAL_VIEWPORTS,
+      defaultViewport: 'ipad',
+    },
+  },
+};
+
+export default preview;
+```
diff --git a/docs/_snippets/component-story-theme-override-globals.md b/docs/_snippets/component-story-theme-override-globals.md
deleted file mode 100644
index 6d4774da1de2..000000000000
--- a/docs/_snippets/component-story-theme-override-globals.md
+++ /dev/null
@@ -1,106 +0,0 @@
-```ts filename="MyComponent.stories.ts" renderer="angular" language="ts"
-import type { Meta, StoryObj } from '@storybook/angular';
-
-import { MyComponent } from './MyComponent.component';
-
-const meta: Meta<MyComponent> = {
-  component: MyComponent,
-};
-
-export default meta;
-type Story = StoryObj<MyComponent>;
-
-export const Default: Story = {};
-
-export const Dark: Story = {
-  //👇 Overrides the current theme for this story to render it with the dark theme
-  globals: { theme: 'dark' },
-};
-```
-
-```js filename="MyComponent.stories.js|jsx" renderer="common" language="js"
-import { MyComponent } from './MyComponent';
-
-export default {
-  component: MyComponent,
-};
-
-export const Default = {};
-
-export const Dark = {
-  //👇 Overrides the current theme for this story to render it with the dark theme
-  globals: { theme: 'dark' },
-};
-```
-
-```ts filename="MyComponent.stories.ts|tsx" renderer="common" language="ts-4-9"
-// Replace your-framework with the name of your framework
-import type { Meta, StoryObj } from '@storybook/your-framework';
-
-import { MyComponent } from './MyComponent';
-
-const meta = {
-  component: MyComponent,
-} satisfies Meta<typeof MyComponent>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Default: Story = {};
-
-export const Dark: Story = {
-  //👇 Overrides the current theme for this story to render it with the dark theme
-  globals: { theme: 'dark' },
-};
-```
-
-```ts filename="MyComponent.stories.ts|tsx" renderer="common" language="ts"
-// Replace your-framework with the name of your framework
-import type { Meta, StoryObj } from '@storybook/your-framework';
-
-import { MyComponent } from './MyComponent';
-
-const meta: Meta<typeof MyComponent> = {
-  component: MyComponent,
-};
-
-export default meta;
-type Story = StoryObj<typeof MyComponent>;
-
-export const Default: Story = {};
-
-export const Dark: Story = {
-  //👇 Overrides the current theme for this story to render it with the dark theme
-  globals: { theme: 'dark' },
-};
-```
-
-```js filename="MyComponent.stories.js" renderer="web-components" language="js"
-export default {
-  component: 'my-component',
-};
-
-export const Default = {};
-
-export const Dark = {
-  globals: { theme: 'dark' },
-};
-```
-
-```ts filename="MyComponent.stories.ts" renderer="web-components" language="ts"
-import type { Meta, StoryObj } from '@storybook/web-components';
-
-const meta: Meta = {
-  component: 'my-component',
-};
-
-export default meta;
-type Story = StoryObj;
-
-export const Default: Story = {};
-
-export const Dark: Story = {
-  //👇 Overrides the current theme for this story to render it with the dark theme
-  globals: { theme: 'dark' },
-};
-```
diff --git a/docs/_snippets/storybook-addon-viewports-global-api.md b/docs/_snippets/storybook-addon-viewports-global-api.md
deleted file mode 100644
index 7737314236df..000000000000
--- a/docs/_snippets/storybook-addon-viewports-global-api.md
+++ /dev/null
@@ -1,101 +0,0 @@
-```ts filename="Button.stories.ts" renderer="angular" language="ts"
-import type { Meta, StoryObj } from '@storybook/angular';
-
-import { Button } from './button.component';
-
-const meta: Meta<Button> = {
-  component: Button,
-};
-
-export default meta;
-type Story = StoryObj<Button>;
-
-export const Large: Story = {
-  global: {
-    viewport: { value: 'phone', isRotated: false },
-  },
-};
-```
-
-```js filename="Button.stories.js|jsx" renderer="common" language="js"
-import { Button } from './Button';
-
-export default {
-  component: Button,
-};
-
-export const Large = {
-  global: {
-    viewport: { value: 'phone', isRotated: false },
-  },
-};
-```
-
-```ts filename="Button.stories.ts|tsx" renderer="common" language="ts-4-9"
-// Replace your-framework with the name of your framework
-import type { Meta, StoryObj } from '@storybook/your-framework';
-
-import { Button } from './Button';
-
-const meta = {
-  component: Button,
-} satisfies Meta<typeof Button>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-export const Large: Story = {
-  global: {
-    viewport: { value: 'phone', isRotated: false },
-  },
-};
-```
-
-```ts filename="Button.stories.ts|tsx" renderer="common" language="ts"
-// Replace your-framework with the name of your framework
-import type { Meta, StoryObj } from '@storybook/your-framework';
-
-import { Button } from './Button';
-
-const meta: Meta<typeof Button> = {
-  component: Button,
-};
-
-export default meta;
-type Story = StoryObj<typeof Button>;
-
-export const Large: Story = {
-  global: {
-    viewport: { value: 'phone', isRotated: false },
-  },
-};
-```
-
-```js filename="Button.stories.js" renderer="web-components" language="js"
-export default {
-  component: 'demo-button',
-};
-
-export const Large = {
-  global: {
-    viewport: { value: 'phone', isRotated: false },
-  },
-};
-```
-
-```ts filename="Button.stories.ts" renderer="web-components" language="ts"
-import type { Meta, StoryObj } from '@storybook/web-components';
-
-const meta: Meta = {
-  component: 'demo-button',
-};
-
-export default meta;
-type Story = StoryObj;
-
-export const Large: Story = {
-  global: {
-    viewport: { value: 'phone', isRotated: false },
-  },
-};
-```
\ No newline at end of file
diff --git a/docs/_snippets/storybook-preview-change-viewports.md b/docs/_snippets/storybook-preview-change-viewports.md
deleted file mode 100644
index abc009259864..000000000000
--- a/docs/_snippets/storybook-preview-change-viewports.md
+++ /dev/null
@@ -1,53 +0,0 @@
-```js filename=".storybook/preview.js" renderer="common" language="js" tabTitle="globals-api"
-export default {
-  parameters: {
-    viewport: {
-      // newViewports would be an ViewportMap. (see below for examples)
-      options: newViewports,
-    },
-  },
-};
-```
-
-```ts filename=".storybook/preview.ts" renderer="common" language="ts" tabTitle="globals-api"
-// Replace your-framework with the framework you are using (e.g., react, vue3)
-import { Preview } from '@storybook/your-framework';
-
-const preview: Preview = {
-  parameters: {
-    viewport: {
-      // newViewports would be an ViewportMap. (see below for examples)
-      options: newViewports,
-    },
-  },
-};
-
-export default preview;
-```
-
-```js filename=".storybook/preview.js" renderer="common" language="js" tabTitle="without-globals"
-export default {
-  parameters: {
-    viewport: {
-      viewports: newViewports, // newViewports would be an ViewportMap. (see below for examples)
-      defaultViewport: 'someDefault',
-    },
-  },
-};
-```
-
-```ts filename=".storybook/preview.ts" renderer="common" language="ts" tabTitle="without-globals"
-// Replace your-framework with the framework you are using (e.g., react, vue3)
-import { Preview } from '@storybook/your-framework';
-
-const preview: Preview = {
-  parameters: {
-    viewport: {
-      viewports: newViewports, // newViewports would be an ViewportMap. (see below for examples)
-      defaultViewport: 'someDefault',
-    },
-  },
-};
-
-export default preview;
-```
diff --git a/docs/_snippets/storybook-preview-granular-viewports.md b/docs/_snippets/storybook-preview-granular-viewports.md
deleted file mode 100644
index e6d548f1fbc6..000000000000
--- a/docs/_snippets/storybook-preview-granular-viewports.md
+++ /dev/null
@@ -1,83 +0,0 @@
-```js filename=".storybook/preview.js" renderer="common" language="js" tabTitle="globals-api"
-import { INITIAL_VIEWPORTS, MINIMAL_VIEWPORTS } from '@storybook/addon-viewport';
-
-export default {
-  parameters: {
-    viewport: {
-      options: {
-        ...INITIAL_VIEWPORTS,
-        ...MINIMAL_VIEWPORTS,
-      },
-    },
-  },
-  initialGlobals: {
-    viewport: {
-      value: 'iphone14promax',
-      isRotated: false,
-    },
-  },
-};
-```
-
-```ts filename=".storybook/preview.ts" renderer="common" language="ts" tabTitle="globals-api"
-// Replace your-framework with the framework you are using (e.g., react, vue3)
-import { Preview } from '@storybook/your-framework';
-
-import { INITIAL_VIEWPORTS, MINIMAL_VIEWPORTS } from '@storybook/addon-viewport';
-
-const preview: Preview = {
-  parameters: {
-    viewport: {
-      options: {
-        ...INITIAL_VIEWPORTS,
-        ...MINIMAL_VIEWPORTS,
-      },
-    },
-  },
-  initialGlobals: {
-    viewport: {
-      value: 'iphone14promax',
-      isRotated: false,
-    },
-  },
-};
-
-export default preview;
-```
-
-```js filename=".storybook/preview.js" renderer="common" language="js" tabTitle="without-globals"
-import { INITIAL_VIEWPORTS, MINIMAL_VIEWPORTS } from '@storybook/addon-viewport';
-
-export default {
-  parameters: {
-    viewport: {
-      viewports: {
-        ...INITIAL_VIEWPORTS,
-        ...MINIMAL_VIEWPORTS,
-      },
-      defaultViewport: 'iphone14promax',
-    },
-  },
-};
-```
-
-```ts filename=".storybook/preview.ts" renderer="common" language="ts" tabTitle="without-globals"
-// Replace your-framework with the framework you are using (e.g., react, vue3)
-import { Preview } from '@storybook/your-framework';
-
-import { INITIAL_VIEWPORTS, MINIMAL_VIEWPORTS } from '@storybook/addon-viewport';
-
-const preview: Preview = {
-  parameters: {
-    viewport: {
-      viewports: {
-        ...INITIAL_VIEWPORTS,
-        ...MINIMAL_VIEWPORTS,
-      },
-      defaultViewport: 'iphone14promax',
-    },
-  },
-};
-
-export default preview;
-```
diff --git a/docs/_snippets/storybook-preview-migrate-viewports-globals.md b/docs/_snippets/storybook-preview-migrate-viewports-globals.md
deleted file mode 100644
index 7773f3e185da..000000000000
--- a/docs/_snippets/storybook-preview-migrate-viewports-globals.md
+++ /dev/null
@@ -1,165 +0,0 @@
-```js filename=".storybook/preview.js" renderer="common" language="js" tabTitle="without-globals"
-export default {
-  parameters: {
-    viewport: {
-      viewports: {
-        SmallPhone: {
-          name: 'Small phone',
-          styles: {
-            width: '320px',
-            height: '568px',
-          },
-        },
-        LargePhone: {
-          name: 'Large phone',
-          styles: {
-            width: '414px',
-            height: '896px',
-          },
-        },
-        Tablet: {
-          name: 'Tablet',
-          styles: {
-            height: '1024px',
-            width: '768px',
-          },
-        },
-        Desktop: {
-          name: 'Desktop',
-          styles: {
-            width: '1920px',
-            height: '1080px',
-          },
-        },
-      },
-    },
-  },
-};
-```
-
-```js filename=".storybook/preview.js" renderer="common" language="js" tabTitle="globals-api"
-export default {
-  parameters: {
-    viewport: {
-      options: {
-        SmallPhone: {
-          name: 'Small phone',
-          styles: {
-            width: '320px',
-            height: '568px',
-          },
-        },
-        LargePhone: {
-          name: 'Large phone',
-          styles: {
-            width: '414px',
-            height: '896px',
-          },
-        },
-        Tablet: {
-          name: 'Tablet',
-          styles: {
-            height: '1024px',
-            width: '768px',
-          },
-        },
-        Desktop: {
-          name: 'Desktop',
-          styles: {
-            width: '1920px',
-            height: '1080px',
-          },
-        },
-      },
-    },
-  },
-};
-```
-
-```ts filename=".storybook/preview.ts" renderer="common" language="ts" tabTitle="without-globals"
-// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
-import type { Preview } from '@storybook/your-renderer';
-
-const preview: Preview = {
-  parameters: {
-    viewport: {
-      viewports: {
-        SmallPhone: {
-          name: 'Small phone',
-          styles: {
-            width: '320px',
-            height: '568px',
-          },
-        },
-        LargePhone: {
-          name: 'Large phone',
-          styles: {
-            width: '414px',
-            height: '896px',
-          },
-        },
-        Tablet: {
-          name: 'Tablet',
-          styles: {
-            height: '1024px',
-            width: '768px',
-          },
-        },
-        Desktop: {
-          name: 'Desktop',
-          styles: {
-            width: '1920px',
-            height: '1080px',
-          },
-        },
-      },
-    },
-  },
-};
-
-export default preview;
-```
-
-```ts filename=".storybook/preview.ts" renderer="common" language="ts" tabTitle="globals-api"
-// Replace your-renderer with the renderer you are using (e.g., react, vue3, angular, etc.)
-import type { Preview } from '@storybook/your-renderer';
-
-const preview: Preview = {
-  parameters: {
-    viewport: {
-      options: {
-        SmallPhone: {
-          name: 'Small phone',
-          styles: {
-            width: '320px',
-            height: '568px',
-          },
-        },
-        LargePhone: {
-          name: 'Large phone',
-          styles: {
-            width: '414px',
-            height: '896px',
-          },
-        },
-        Tablet: {
-          name: 'Tablet',
-          styles: {
-            height: '1024px',
-            width: '768px',
-          },
-        },
-        Desktop: {
-          name: 'Desktop',
-          styles: {
-            width: '1920px',
-            height: '1080px',
-          },
-        },
-      },
-    },
-  },
-};
-
-export default preview;
-```
diff --git a/docs/_snippets/storybook-preview-viewport-add-devices.md b/docs/_snippets/storybook-preview-viewport-add-devices.md
deleted file mode 100644
index 4978c18f6352..000000000000
--- a/docs/_snippets/storybook-preview-viewport-add-devices.md
+++ /dev/null
@@ -1,19 +0,0 @@
-```js filename=".storybook/preview.js|ts" renderer="common" language="js"
-const customViewports = {
-  kindleFire2: {
-    name: 'Kindle Fire 2',
-    styles: {
-      width: '600px',
-      height: '963px',
-    },
-  },
-  kindleFireHD: {
-    name: 'Kindle Fire HD',
-    styles: {
-      width: '533px',
-      height: '801px',
-    },
-  },
-};
-```
-
diff --git a/docs/_snippets/storybook-preview-viewport-use-new-devices.md b/docs/_snippets/storybook-preview-viewport-use-new-devices.md
deleted file mode 100644
index 0449775db3fb..000000000000
--- a/docs/_snippets/storybook-preview-viewport-use-new-devices.md
+++ /dev/null
@@ -1,45 +0,0 @@
-```js filename=".storybook/preview.js" renderer="common" language="js" tabTitle="globals-api"
-export default {
-  parameters: {
-    viewport: {
-      options: customViewports,
-    },
-  },
-};
-```
-
-```ts filename=".storybook/preview.ts" renderer="common" language="ts" tabTitle="globals-api"
-// Replace your-framework with the framework you are using (e.g., react, vue3)
-import { Preview } from '@storybook/your-framework';
-
-const preview: Preview = {
-  parameters: {
-    viewport: {
-      options: customViewports,
-    },
-  },
-};
-
-export default preview;
-```
-
-```js filename=".storybook/preview.js" renderer="common" language="js" tabTitle="without-globals"
-export default {
-  parameters: {
-    viewport: { viewports: customViewports },
-  },
-};
-```
-
-```ts filename=".storybook/preview.ts" renderer="common" language="ts" tabTitle="without-globals"
-// Replace your-framework with the framework you are using (e.g., react, vue3)
-import { Preview } from '@storybook/your-framework';
-
-const preview: Preview = {
-  parameters: {
-    viewport: { viewports: customViewports },
-  },
-};
-
-export default preview;
-```
diff --git a/docs/essentials/backgrounds.mdx b/docs/essentials/backgrounds.mdx
index 1dc228e6b523..08aa41407eee 100644
--- a/docs/essentials/backgrounds.mdx
+++ b/docs/essentials/backgrounds.mdx
@@ -21,7 +21,7 @@ By default, the backgrounds toolbar includes a light and dark background.
 
 But you're not restricted to these backgrounds. You can configure your own set of colors with the `backgrounds` [parameter](../writing-stories/parameters.mdx) in your [`.storybook/preview.js`](../configure/index.mdx#configure-story-rendering).
 
-You can define the available background colors using the `values` property:
+You can define the available background colors using the [`values` property](#values) and set the initial background color using the [`default` property](#default):
 
 {/* prettier-ignore-start */}
 
@@ -33,7 +33,7 @@ You can define the available background colors using the `values` property:
 
   **With the [`globals` API](#globals-api)**
 
-  When using the `globals` API, you must define the available background colors using the `options` property:
+  When using the `globals` API, you must define the available background colors using the [`options` property](#options). The initial background color can be set using the `initialGlobals` property, which accepts the same object properties as the [`globals`](#globals) for this addon.
 
   {/* prettier-ignore-start */}
 
@@ -43,19 +43,13 @@ You can define the available background colors using the `values` property:
 
 </Callout>
 
-With either method, available backgrounds can be defined at the project, component, and story levels.
+## Defining the background for a story
 
-To apply a default background color, assign the `default` property to one of the available colors.
-
-## Overriding the background for a story
-
-The Backgrounds addon enables you to change the background color applied to a story by selecting from the list of predefined background colors in the toolbar. If needed, you can force a story to use a specific background color.
-
-You can set the default background color for a story using the `parameters.backgrounds.default` parameter:
+The Backgrounds addon enables you to change the background color applied to a story by selecting from the list of predefined background colors in the toolbar. If needed, you can set a story to default to a specific background color, by using the `parameters.backgrounds.default` parameter:
 
 {/* prettier-ignore-start */}
 
-<CodeSnippets path="addon-backgrounds-override-parameters-default.md" usesCsf3 />
+<CodeSnippets path="addon-backgrounds-define-default.md" usesCsf3 />
 
 {/* prettier-ignore-end */}
 
@@ -69,7 +63,7 @@ As implied by the name, this method only sets the default background color for a
 
   {/* prettier-ignore-start */}
 
-  <CodeSnippets path="addon-backgrounds-override-globals.md" usesCsf3 />
+  <CodeSnippets path="addon-backgrounds-define-globals.md" usesCsf3 />
 
   {/* prettier-ignore-end */}
 
@@ -79,7 +73,7 @@ As implied by the name, this method only sets the default background color for a
 
 You can also configure backgrounds per-component or per-story basis through [parameter inheritance](../writing-stories/parameters.mdx#component-parameters).
 
-To set the available background colors, use the `values` property. In this example, we'll adjust the colors for all of the Button component's stories:
+To set the available background colors, use the [`values` property](#values). In this example, we'll adjust the colors for all of the Button component's stories:
 
 {/* prettier-ignore-start */}
 
@@ -91,7 +85,7 @@ To set the available background colors, use the `values` property. In this examp
 
   **With the [`globals` API](#globals-api)**
 
-  The available background colors are defined using the `options` property. In this example, we'll adjust the colors for all of the Button component's stories:
+  The available background colors are defined using the [`options` property](#options). In this example, we'll adjust the colors for all of the Button component's stories:
 
   {/* prettier-ignore-start */}
 
@@ -103,7 +97,7 @@ To set the available background colors, use the `values` property. In this examp
 
 ## Disable backgrounds
 
-If you want to turn off backgrounds in a story, you can do so by setting the `backgrounds` parameter like so:
+If you want to turn off backgrounds in a story, you can do so by configuring the `backgrounds` parameter like so:
 
 <Callout variant="warning" icon="🆕">
 
@@ -143,7 +137,7 @@ You don't need additional configuration to get started. But its properties are f
 
   #### `grid`
 
-  Type: Boolean
+  Type: `boolean`
 
   Whether the [grid](#grid) is displayed.
 
@@ -165,7 +159,7 @@ Type: `string`
 
 Required: See description
 
-Default background color. Must match the `name` property of one of the [available colors](#values).
+Default background color. Must match the `name` property of one of the available colors defined in the [`values`](#values) (or [`options`](#options)) property.
 
 #### `disable`
 
@@ -189,12 +183,12 @@ Type:
 
 ```ts
 {
- cellAmount?: number;
- cellSize?: number;
- disable?: boolean;
- offsetX?: number;
- offsetY?: number;
- opacity?: number;
+  cellAmount?: number;
+  cellSize?: number;
+  disable?: boolean;
+  offsetX?: number;
+  offsetY?: number;
+  opacity?: number;
 }
 ```
 
@@ -252,13 +246,22 @@ The opacity of the grid lines.
 
   #### `options`
 
-  Type: `Record<string, { name: string; value: string }>`
+  Type:
+
+  ```ts
+  {
+    [key: string]: {
+      name: string;
+      value: string;
+    };
+  }
+  ```
 
   Required: See description
 
-  Defines the background colors. Replaces [`values`](#values). See above for a [usage example](#configuration).
+  Defines the background colors. Replaces [`values`](#values). The key is used to reference the color, and the value is an object to define it. See above for a [usage example](#configuration).
 
-  Required when defining `backgrounds` parameter at project level.
+  When defining the `backgrounds` parameter at the project level (in `.storybook/preview.js|ts`), you _must_ define the `options` property.
 
 </Callout>
 
@@ -270,4 +273,4 @@ Required: See description
 
 Available background colors. See above for a [usage example](#configuration).
 
-Required when defining `backgrounds` parameter at project level.
+When defining the `backgrounds` parameter at the project level (in `.storybook/preview.js|ts`), you _must_ define the `values` property.
diff --git a/docs/essentials/toolbars-and-globals.mdx b/docs/essentials/toolbars-and-globals.mdx
index cb5c6a57b6b7..18ab6bdbb721 100644
--- a/docs/essentials/toolbars-and-globals.mdx
+++ b/docs/essentials/toolbars-and-globals.mdx
@@ -7,13 +7,13 @@ sidebar:
 
 <YouTubeCallout id="DuJ_gmSncLM" title="Create custom toolbar items using global types" />
 
-Storybook ships with toolbar addons to control the [viewport](./viewport.mdx) and [background](./backgrounds.mdx) the story renders in. You can also create your toolbar items that control special “globals,” which you can then read to create [decorators](../writing-stories/decorators.mdx) to control story rendering.
+Storybook ships with toolbar addons to control the [viewport](./viewport.mdx) and [background](./backgrounds.mdx) the story renders in. You can also create toolbar items which control special “globals”. You can then read the global values to create [decorators](../writing-stories/decorators.mdx) to control story rendering.
 
 ![Toolbars and globals](../_assets/essentials/toolbars-and-globals.png)
 
 ## Globals
 
-Globals in Storybook represent “global” (as in not story-specific) inputs to the rendering of the story. As they aren’t specific to the story, they aren’t passed in the `args` argument to the story function (although they are accessible as `context.globals`), but typically you use them in decorators, which apply to all stories.
+Globals in Storybook represent “global” (as in not story-specific) inputs to the rendering of the story. As they aren’t specific to the story, they aren’t passed in the `args` argument to the story function (although they are accessible as `context.globals`). Instead, they are typically used in decorators, which apply to all stories.
 
 When the globals change, the story re-renders and the decorators rerun with the new values. The easiest way to change globals is to create a toolbar item for them.
 
@@ -21,13 +21,15 @@ When the globals change, the story re-renders and the decorators rerun with the
 
 Storybook has a simple, declarative syntax for configuring toolbar menus. In your [`.storybook/preview.js|ts`](../configure/index.mdx#configure-story-rendering), you can add your own toolbars by creating `globalTypes` with a `toolbar` annotation:
 
+{/* prettier-ignore-start */}
+
 <CodeSnippets path="storybook-preview-configure-globaltypes.md" />
 
 {/* prettier-ignore-end */}
 
 <Callout variant="info" icon="💡">
 
- As globals are *global* you can *only* set `globalTypes` in [`.storybook/preview.js|ts`](../configure/index.mdx#configure-story-rendering).
+ As globals are *global* you can *only* set `globalTypes` and `initialGlobals` in [`.storybook/preview.js|ts`](../configure/index.mdx#configure-story-rendering).
 
 </Callout>
 
@@ -77,22 +79,27 @@ We have a `global` implemented. Let's wire it up! We can consume our new `theme`
   {/* prettier-ignore-end */}
 </IfRenderer>
 
-
 ## Setting globals on a story
 
-By default, custom toolbars and other globals defined with the `globalTypes` annotation, similar to the one created to set up our custom theme, are consistently applied to every story available. However, if you need to, you can override them at the component or story level to use a custom value for a specific story or subset of stories. This will allow you to test specific scenarios (e.g., custom appearance, behavior) where a particular value should be used. To do this, add a `globals` annotation in your story to enable the selected option.
+<Callout variant="warning" icon="🆕">
+  The ability to set globals on a story or component is available in Storybook 8.3+. Some addons, like [backgrounds](./backgrounds.mdx) and [viewport](./viewport.mdx), have been updated to use the `globals` API when a feature flag is enabled.
+</Callout>
+
+When a global value is changed with a toolbar menu in Storybook, that value continues to be used as you navigate between stories. But sometimes a story requires a specific value to render correctly, e.g., when testing against a particular environment.
+
+To ensure that a story always uses a specific global value, regardless of what has been chosen in the toolbar, you can set the `globals` annotation on a story or component. This overrides the global value for those stories and disables the toolbar menu for that global when viewing the stories.
 
 {/* prettier-ignore-start */}
 
-<CodeSnippets path="component-story-theme-override-globals.md" />
+<CodeSnippets path="addon-backgrounds-define-globals.md" />
 
 {/* prettier-ignore-end */}
 
-When Storybook loads the stories, it applies the selected theme to every story except the `Dark` story, which automatically applies the `dark` theme. It also turns off the toolbar dropdown with the theme options, preventing them from being changed and notifying that this story requires a specific value to be used.
+In the example above, Storybook will force all Button stories to use a gray background color, except the `OnDark` story, which will use the dark background. For all Buttons stories, the toolbar menu will be disabled for the `backgrounds` global, with a tooltip explaining that the global is set at the story level.
 
 <Callout variant="info" icon="💡">
 
-Configuring a story's `globals` annotation to override the project-level global settings is useful but should be used with moderation. Globals that are _not_ defined at the story level can be selected interactively in Storybook's UI, allowing users to explore every existing combination of values (e.g., global values, [`args`](../writing-stories/args.mdx)). Enabling them at the story level will turn them off, preventing users from exploring the available options.
+Configuring a story's `globals` annotation to override the project-level global settings is useful but should be used with moderation. Globals that are _not_ defined at the story level can be selected interactively in Storybook's UI, allowing users to explore every existing combination of values (e.g., global values, [`args`](../writing-stories/args.mdx)). Setting them at the story level will disable that control, preventing users from exploring the available options.
 
 </Callout>
 
diff --git a/docs/essentials/viewport.mdx b/docs/essentials/viewport.mdx
index 78eb965066e4..d685ecf7649a 100644
--- a/docs/essentials/viewport.mdx
+++ b/docs/essentials/viewport.mdx
@@ -11,174 +11,189 @@ The Viewport toolbar item allows you to adjust the dimensions of the iframe your
 
 <Video src="../_assets/essentials/addon-viewports-optimized.mp4" />
 
+<Callout variant="warning" icon="🆕" id="globals-api">
+  **`globals` API**
+
+  This addon has been updated to use the `globals` API when the [`viewportStoryGlobals` feature flag](../api/main-config/main-config-features.mdx#viewportstoryglobals) is enabled. With `globals`, when you specify a viewport for a story, it cannot be overridden from the toolbar. This ensures a consistent experience while navigating between stories. This will be the default behavior and API in Storybook 9.
+</Callout>
+
 ## Configuration
 
-Out of the box, the Viewport addon offers you a standard set of viewports that you can use. If you want to change the default set of viewports, you can set the global `parameters.viewport` [parameter](../writing-stories/parameters.mdx) in your [`.storybook/preview.js`](../configure/index.mdx#configure-story-rendering):
+Out of the box, the Viewport addon offers you a standard set of viewports that you can use. If you want to change the default set of viewports, you can configure your own viewports with the `viewport` [parameter](../writing-stories/parameters.mdx) in your [`.storybook/preview.js`](../configure/index.mdx#configure-story-rendering).
+
+You can define the available viewports using the [`viewports` property](#viewports) and set the initial viewport using the [`defaultViewport` property](#default):
 
 {/* prettier-ignore-start */}
 
-<CodeSnippets path="storybook-preview-change-viewports.md" />
+<CodeSnippets path="addon-viewport-viewports-in-preview.md" />
 
 {/* prettier-ignore-end */}
 
-The viewport parameter can take an object with the following keys:
+<Callout variant="warning" icon="🆕">
 
-| Field                  | Type    | Description                                                                                                                                   | Default Value  |
-| ---------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
-| **defaultViewport**    | String  | Only available without the [globals API](#customizing-viewports-with-globals).<br/>Sets the default viewport                                  | `'responsive'` |
-| **defaultOrientation** | String  | Only available without the [globals API](#customizing-viewports-with-globals).<br/>Sets the default orientation (e.g., portrait or landscape) | `'portrait'`   |
-| **disabled**           | Boolean | Requires the [globals API](#customizing-viewports-with-globals).<br/>Disables the viewport<br/>                                               | N/A            |
-| **options**            | Object  | Requires the [globals API](#customizing-viewports-with-globals).<br/>The available list of viewports                                          | `{}`           |
-| **viewports**          | Object  | Only available without the [globals API](#customizing-viewports-with-globals).<br/> The configuration objects for the viewport                | `{}`           |
+  **With the [`globals` API](#globals-api)**
 
+  When using the `globals` API, you must define the available viewports using the [`options` property](#options). The initial viewport can be set using the `initialGlobals` property, which accepts the same object properties as the [`globals`](#globals) for this addon.
 
-Each viewports object needs the following keys:
+  {/* prettier-ignore-start */}
 
-| Field      | Type   | Description                                           | Example values          |
-| ---------- | ------ | ----------------------------------------------------- | ----------------------- |
-| **name**   | String | Name for the viewport                                 | `'Responsive'`          |
-| **styles** | Object | Sets Inline styles to be applied to the story         | `{ width:0, height:0 }` |
-| **type**   | String | Type of the device (e.g., desktop, mobile, or tablet) | `desktop`               |
+  <CodeSnippets path="addon-viewport-options-in-preview.md" />
 
+  {/* prettier-ignore-end */}
 
-### Customizing viewports with globals
-
-By default, the Viewport addon allows you to customize the viewport enabled for a story by selecting from the list of existing viewports in the toolbar. If you need, you can opt into the globals API to configure viewports to ensure that a story always uses a specific viewport regardless of the existing configuration.
+</Callout>
 
-To enable it, you'll need to take some additional steps to set it up properly. Detailed below is our recommendation for configuring and using the globals API with the Viewports addon.
+### Use a detailed set of devices
 
-Update your [`.storybook/main.js|ts`](../configure/index.mdx#configure-your-storybook-project) to include the [`viewportStoryGlobals`](../api/main-config/main-config-features.mdx#viewportstoryglobals) option within Storybok's `features` configuration.
+By default, the Viewport addon will use a minimal set of viewports, which enables you to test your UI in common responsive scenarios. These are also available in the [`MINIMAL_VIEWPORTS` export](#minimal_viewports) and include the following devices:
+
+| Key       | Description  | Dimensions<br />(<abbr title="width">w</abbr>×<abbr title="height">h</abbr>, px) |
+| ----------|------------- | -------------------------------------------------------------------------------- |
+| `mobile1` | Small mobile | 320 × 568                                                                        |
+| `mobile2` | Large mobile | 414 × 896                                                                        |
+| `tablet`  | Tablet       | 834 × 1112                                                                       |
+
+If you need a more detailed set of devices, you can use the [`INITIAL_VIEWPORTS` export](#initial_viewports), which includes the following devices:
+
+| Key              | Description                                     | Dimensions<br />(<abbr title="width">w</abbr>×<abbr title="height">h</abbr>, px) |
+| -----------------| ----------------------------------------------- | -------------------------------------------------------------------------------- |
+| `iphone5`        | iPhone 5                                        | 320 × 568                                                                        |
+| `iphone6`        | iPhone 6                                        | 375 × 667                                                                        |
+| `iphone6p`       | iPhone 6 Plus                                   | 414 × 736                                                                        |
+| `iphone8p`       | iPhone 8 Plus                                   | 414 × 736                                                                        |
+| `iphonex`        | iPhone X                                        | 375 × 812                                                                        |
+| `iphonexr`       | iPhone XR                                       | 414 × 896                                                                        |
+| `iphonexsmax`    | iPhone XS Max                                   | 414 × 896                                                                        |
+| `iphonese2`      | iPhone SE (2nd generation)                      | 375 × 667                                                                        |
+| `iphone12mini`   | iPhone 12 mini                                  | 375 × 812                                                                        |
+| `iphone12`       | iPhone 12                                       | 390 × 844                                                                        |
+| `iphone12promax` | iPhone 12 Pro Max                               | 428 × 926                                                                        |
+| `iphoneSE3`      | iPhone SE 3rd generation                        | 375 × 667                                                                        |
+| `iphone13`       | iPhone 13                                       | 390 × 844                                                                        |
+| `iphone13pro`    | iPhone 13 Pro                                   | 390 × 844                                                                        |
+| `iphone13promax` | iPhone 13 Pro Max                               | 428 × 926                                                                        |
+| `iphone14`       | iPhone 14                                       | 390 × 844                                                                        |
+| `iphone14pro`    | iPhone 14 Pro                                   | 393 × 852                                                                        |
+| `iphone14promax` | iPhone 14 Pro Max                               | 430 × 932                                                                        |
+| `galaxys5`       | Galaxy S5                                       | 360 × 640                                                                        |
+| `galaxys9`       | Galaxy S9                                       | 360 × 740                                                                        |
+| `nexus5x`        | Nexus 5X                                        | 412 × 668                                                                        |
+| `nexus6p`        | Nexus 6P                                        | 412 × 732                                                                        |
+| `pixel`          | Pixel                                           | 540 × 960                                                                        |
+| `pixelxl`        | Pixel XL                                        | 720 × 1280                                                                       |
+| `mobile1`        | Small mobile<br />(also in `MINIMAL_VIEWPORTS`) | 320 × 568                                                                        |
+| `mobile2`        | Large mobile<br />(also in `MINIMAL_VIEWPORTS`) | 414 × 896                                                                        |
+| `ipad`           | iPad                                            | 768 × 1024                                                                       |
+| `ipad10p`        | iPad Pro 10.5-in                                | 834 × 112                                                                        |
+| `ipad11p`        | iPad Pro 11-in                                  | 834 × 1194                                                                       |
+| `ipad12p`        | iPad Pro 12.9-in                                | 1024 × 1366                                                                      |
+| `tablet`         | Tablet<br />(also in `MINIMAL_VIEWPORTS`)       | 834 × 1112                                                                       |
+
+To use the detailed set of devices, you can replace the `viewports` property in your configuration with the `INITIAL_VIEWPORTS` export:
 
 {/* prettier-ignore-start */}
 
-<CodeSnippets path="main-config-features-viewport-story-globals.md" />
+<CodeSnippets path="addon-viewport-viewports-in-preview.md" />
 
 {/* prettier-ignore-end */}
 
-<Callout variant="info">
+<Callout variant="warning" icon="🆕">
 
-Enabling this API will turn off the ability to change any options from the toolbar to ensure that the viewport is always set to the intended value for the story.
+  **With the [`globals` API](#globals-api)**
+
+  When using the `globals` API, the available viewports are defined using the [`options` property](#options).
+
+  <CodeSnippets path="addon-viewport-options-in-preview.md" />
 
 </Callout>
 
-Replace the `viewports` parameter in your [`.storybook/preview.js|ts`](../configure/index.mdx#configure-story-rendering) with an `options` object to define your configuration.
+### Add new devices
 
-{/* prettier-ignore-start */}
+If the predefined viewports don't meet your needs, you can add new devices to the list of viewports. For example, let's add two Kindle devices to the default set of minimal viewports:
 
-<CodeSnippets path="storybook-preview-migrate-viewports-globals.md" />
+<Callout variant="warning" icon="🆕">
 
-{/* prettier-ignore-end */}
+  **With the [`globals` API](#globals-api)**
+
+  When using the `globals` API, note that available viewports are defined using the [`options` property](#options).
 
-Adjust your stories to opt-in to the new story globals API using the `global` configuration element to set the required viewport.
+</Callout>
 
 {/* prettier-ignore-start */}
 
-<CodeSnippets path="storybook-addon-viewports-global-api.md" usesCsf3 />
+<CodeSnippets path="addon-viewport-add-viewport-in-preview.md" />
 
 {/* prettier-ignore-end */}
 
-### Use a detailed set of devices
+### Configuring per component or story
 
-The Viewport addon includes a selection of devices that you can use to test your components. Listed below are the available devices and examples of how to use them.
-| Device                     | Description                                                                                                                             | Value             | Dimensions<br />(<abbr title="width">w</abbr>×<abbr title="height">h</abbr>, px) |
-| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------- |
-| iPhone 5                   | Configures the iPhone 5 as a device for the Viewport addon.                                                                             | `iphone5`         | 320 × 568                                                                        |
-| iPhone 6                   | Enables the iPhone 6 to be used with the Viewport addon.                                                                                | `iphone6`         | 375 × 667                                                                        |                                                                                  
-| iPhone 6 Plus              | Includes the iPhone 6 Plus as a device for the Viewport addon.                                                                          | `iphone6p`        | 414 × 736                                                                        |
-| iPhone 8 Plus              | Sets the iPhone 8 Plus as a device to be used by the Viewport addon.                                                                    | `iphone8p`        | 414 × 736                                                                        |
-| iPhone X                   | Configures the iPhone X as a device for the Viewport addon.                                                                             | `iphonex`         | 375 × 812                                                                        |
-| iPhone XR                  | Includes the iPhone XR as a device for the Viewport addon.                                                                              | `iphonexr`        | 414 × 896                                                                        |
-| iPhone XS Max              | Sets the iPhone XS Max as a device to be used by the Viewport addon.                                                                    | `iphonexsmax`     | 414 × 896                                                                        |
-| iPhone SE (2nd generation) | Configures the iPhone SE (2nd generation) as a device for the Viewport addon.                                                           | `iphonese2`       | 375 × 667                                                                        |
-| iPhone 12 mini             | Enables the iPhone 12 Mini to be used with the Viewport addon.                                                                          | `iphone12mini`    | 375 × 812                                                                        |
-| iPhone 12                  | Includes the iPhone 12 as a device for the Viewport addon.                                                                              | `iphone12`        | 390 × 844                                                                        |
-| iPhone 12 Pro Max          | Configures the iPhone 12 Pro Max as a device for the Viewport addon.                                                                    | `iphone12promax`  | 428 × 926                                                                        |
-| iPhone SE 3rd generation   | Enables the iPhone SE (3rd generation) to be used with the Viewport addon.                                                              | `iphoneSE3`       | 375 × 667                                                                        |
-| iPhone 13                  | Includes the iPhone 13 as a device for the Viewport addon.                                                                              | `iphone13`        | 390 × 844                                                                        |
-| iPhone 13 Pro              | Enables the iPhone 13 Pro to be used with the Viewport addon.                                                                           | `iphone13pro`     | 390 × 844                                                                        |
-| iPhone 13 Pro Max          | Configures the iPhone 13 Pro Max as a device to be used by the Viewport addon.                                                          | `iphone13promax`  | 428 × 926                                                                        |
-| iPhone 14                  | Enables the iPhone 14 to be used with the Viewport addon.                                                                               | `iphone14`        | 390 × 844                                                                        |
-| iPhone 14 Pro              | Includes the iPhone 14 Pro as a device for the Viewport addon.                                                                          | `iphone14pro`     | 393 × 852                                                                        |
-| iPhone 14 Pro Max          | Sets the iPhone 14 Pro Max as a device to be used by the Viewport addon.                                                                | `iphone14promax`  | 430 × 932                                                                        |
-| Galaxy S5                  | Configures the Galaxy S5 as a device for the Viewport addon.                                                                            | `galaxys5`        | 360 × 640                                                                        |
-| Galaxy S9                  | Enables the Galaxy S9 to be used with the Viewport addon.                                                                               | `galaxys9`        | 360 × 740                                                                        |
-| Nexus 5X                   | Includes the Nexus 5x as a device for the Viewport addon.                                                                               | `nexus5x`         | 412 × 668                                                                        |
-| Nexus 6P                   | Sets the Nexus 6P as a device to be used by the Viewport addon.                                                                         | `nexus6p`         | 412 × 732                                                                        |
-| Pixel                      | Configures the Pixel as a device for the Viewport addon.                                                                                | `pixel`           | 540 × 960                                                                        |
-| Pixel XL                   | Enables the Pixel XL to be used with the Viewport addon.                                                                                | `pixelxl`         | 720 × 1280                                                                       |
-| Small mobile               | Enabled by default.<br />Configures a small form factor generic mobile device to be used by the Viewport addon.                         | `mobile1`         | 320 × 568                                                                        |
-| Large mobile               | Enabled by default.<br />Configures a large form factor mobile device to be used by the Viewport addon.                                 | `mobile2`         | 414 × 896                                                                        |
-| iPad                       | Includes the iPad as a device for the Viewport addon.                                                                                   | `ipad`            | 768 × 1024                                                                       |
-| iPad Pro 10.5-in           | Enables the iPad Pro (10.5-inch) to be used with the Viewport addon.                                                                    | `ipad10p`         | 834 × 112                                                                        |
-| iPad Pro 11-in             | Configures the iPad Pro (11-inch) as a device for the Viewport addon.                                                                   | `ipad11p`         | 834 × 1194                                                                       |
-| iPad Pro 12.9-in           | Sets the iPad Pro (12.9-inch) as a device to be used by the Viewport addon.                                                             | `ipad12p`         | 1024 × 1366                                                                      |
-| Tablet                     | Enabled by default.<br />Configures a standard form factor tablet device to be used by the Viewport addon.                              | `tablet`          | 834 × 1112                                                                       |
+In some cases, it's not practical for you to use a specific visual viewport on a global scale, and you need to adjust it to an individual story or set of stories for a component.
+
+[Parameters](../writing-stories/parameters.mdx) can be applied at the project, component, and story levels, which allows you to specify the configuration where needed. For example, you can set the available viewports for all of the stories for a component like so:
 
 {/* prettier-ignore-start */}
 
-<CodeSnippets path="storybook-preview-granular-viewports.md" />
+<CodeSnippets path="addon-viewport-configuration-in-meta.md" usesCsf3 />
 
 {/* prettier-ignore-end */}
 
-<Callout variant="info">
-
- The generic devices are enabled by default as they are the most common for testing responsive UIs. You don't need to include them in your configuration if you want to use them. For the implementation details, see the [source code](https://github.com/storybookjs/storybook/tree/next/code/addons/viewport) for the Viewport addon.
-
-</Callout>
-
-### Add new devices
+## Defining the viewport for a story
 
-If you have either a specific viewport or a list of viewports that you need to use, you can modify your [`.storybook/preview.js`](../configure/index.mdx#configure-story-rendering) file and include them:
+The Viewport addon enables you to change the viewport applied to a story by selecting from the list of predefined viewports in the toolbar. If needed, you can set a story to default to a specific viewport, by using the `parameters.viewport.default` parameter:
 
 {/* prettier-ignore-start */}
 
-<CodeSnippets path="storybook-preview-viewport-add-devices.md" />
+<CodeSnippets path="addon-viewport-define-default.md" usesCsf3 />
 
 {/* prettier-ignore-end */}
 
-Make the following changes to use them in your Storybook:
+As implied by the name, this method only sets the default viewport for a story. You can still change the viewport using the toolbar when viewing the story.
 
-{/* prettier-ignore-start */}
+<Callout variant="warning" icon="🆕">
 
-<CodeSnippets path="storybook-preview-viewport-use-new-devices.md" />
+  **With the [`globals` API](#globals-api)**
 
-{/* prettier-ignore-end */}
+  When you specify a viewport for a story (or a component's stories) using `globals`, the viewport is applied and cannot be changed using the toolbar. This is useful when you want to ensure that a story is always rendered on a specific viewport.
 
-Once you start Storybook, you'll see your new viewports and devices.
+  {/* prettier-ignore-start */}
 
-You can add these two to another list of viewports if needed.
+  <CodeSnippets path="addon-viewport-define-globals.md" usesCsf3 />
 
-For instance, if you want to use these two with the minimal set of viewports, you can do it like so:
+  {/* prettier-ignore-end */}
 
-{/* prettier-ignore-start */}
+</Callout>
 
-<CodeSnippets path="storybook-preview-merge-viewports.md" />
+## API
 
-{/* prettier-ignore-end */}
+### Keyboard shortcuts
 
-Both viewports (`Kindle Fire 2` and `Kindle Fire HD`) will feature in the list of devices by merging them into the [`MINIMAL_VIEWPORTS`](https://github.com/storybookjs/storybook/blob/next/code/addons/viewport/src/defaults.ts#L231).
+If you need, you can edit these on the shortcuts page.
 
-### Configuring per component or story
+* Next viewport: <kbd>alt</kbd> + <kbd>v</kbd>
+* Previous viewport: <kbd>alt</kbd> + <kbd>shift</kbd> + <kbd>v</kbd>
+* Reset viewport: <kbd>alt</kbd> + <kbd>control</kbd> + <kbd>v</kbd>
 
-In some cases, it's not practical for you to use a specific visual viewport on a global scale, and you need to adjust it to an individual story.
+<Callout variant="warning" icon="🆕">
 
-Update your story through [parameters](../writing-stories/parameters.mdx) to include your viewports at a component level or for a specific story:
+  **With the [`globals` API](#globals-api)**
 
-{/* prettier-ignore-start */}
+  ### Globals
 
-<CodeSnippets path="my-component-story-configure-viewports.md" usesCsf3 />
+  This addon contributes the following globals to Storybook, under the `viewport` namespace:
 
-{/* prettier-ignore-end */}
+  #### `value`
 
-### Keyboard shortcuts
+  Type: `string`
 
-* Previous viewport: <kbd>alt</kbd> + <kbd>shift</kbd> + <kbd>v</kbd>
-* Next viewport: <kbd>alt</kbd> + <kbd>v</kbd>
-* Reset viewport: <kbd>alt</kbd> + <kbd>control</kbd> + <kbd>v</kbd>
+  When set, the viewport is applied and cannot be changed using the toolbar. Must match the key of one of the [available viewports](#options).
 
-If you need, you can edit them on the shortcuts page.
+  #### `isRotated`
 
-## API
+  Type: `boolean`
+
+  When true the viewport applied will be rotated 90°, e.g. it will rotate from portrait to landscape orientation.
+
+</Callout>
 
 ### Parameters
 
@@ -196,11 +211,17 @@ Specifies the default orientation used when viewing a story. Only available if y
 
 Type: `string`
 
-Specifies the default viewport used when viewing a story. Must match a key in the [`viewports`](#viewports) object. Only available if you haven't enabled the [globals API](#customizing-viewports-with-globals).
+Specifies the default viewport used when viewing a story. Must match a key in the [`viewports`](#viewports) (or [`options`](#options)) object.
+
+#### `disable`
 
-#### `disabled`
+<Callout variant="warning" icon="🆕">
 
-Requires: [globals API](#customizing-viewports-with-globals)
+  **With the [`globals` API](#globals-api)**
+
+  Note that the property has been renamed to `disabled`.
+
+</Callout>
 
 Type: `boolean`
 
@@ -208,29 +229,27 @@ Turn off this addon's behavior. If you wish to turn off this addon for the entir
 
 This parameter is most useful to allow overriding at more specific levels. For example, if this parameter is set to `true` at the project level, it could be re-enabled by setting it to `false` at the meta (component) or story level.
 
-<Callout variant="info">
-
-The `disabled` parameter is only available with the globals API introduced in Storybook 8.3. If you're using a previous Storybook version, use the `disable` parameter instead.
+<Callout variant="warning" icon="🆕">
 
-</Callout>
+  **With the [`globals` API](#globals-api)**
 
-#### `options`
+  #### `options`
 
-Requires: [globals API](#customizing-viewports-with-globals)
+  Type:
 
-Type:
+  ```ts
+  {
+    [key: string]: {
+      name: string;
+      styles: { height: string, width: string };
+      type: 'desktop' | 'mobile' | 'tablet' | 'other';
+    };
+  }
+  ```
 
-```ts
-{
- Record<string, {
- name: string,
- styles: { height: string, width: string },
- type: 'desktop' | 'mobile' | 'tablet' | 'other',
- }>,
-};
-```
+  Specify the available viewports. Replaces [`viewports`](#viewports). The key is used to reference the viewport, and the value is an object to define it. See [usage example](#add-new-devices) above. The `width` and `height` values must include the unit, e.g. `'320px'`.
 
-Specify the available viewports. The key is used to reference the viewport, and the value is an object to define it. See [usage example](#add-new-devices) above. The `width` and `height` values must include the unit, e.g. `'320px'`.
+</Callout>
 
 #### `viewports`
 
@@ -238,15 +257,15 @@ Type:
 
 ```ts
 {
- [key: string]: {
- name: string,
- styles: { height: string, width: string },
- type: 'desktop' | 'mobile' | 'tablet',
- },
-};
+  [key: string]: {
+    name: string;
+    styles: { height: string, width: string };
+    type: 'desktop' | 'mobile' | 'tablet';
+  };
+}
 ```
 
-Configures the viewports and options. This configuration element references the viewport, and the value is an object that defines it. See [usage example](#add-new-devices) above. The `width` and `height` values must include the unit, e.g., `'320px'`. Only available if you haven't enabled the [globals API](#customizing-viewports-with-globals).
+Specify the available viewports. The key is used to reference the viewport, and the value is an object to define it. See [usage example](#add-new-devices) above. The `width` and `height` values must include the unit, e.g. `'320px'`.
 
 ### Exports
 
@@ -260,16 +279,11 @@ import { INITIAL_VIEWPORTS, MINIMAL_VIEWPORTS } from '@storybook/addon-viewport'
 
 Type: `object`
 
-The default set of viewports provided by the Viewport addon [listed above](#use-a-detailed-set-of-devices).
+The full set of initial viewports provided by the Viewport addon, [listed above](#use-a-detailed-set-of-devices).
 
 #### `MINIMAL_VIEWPORTS`
 
 Type: `object`
 
-A minimal set of viewports provided by the Viewport addon is listed below:
+A minimal set of viewports provided by the Viewport addon [listed above](#use-a-detailed-set-of-devices). These are used by default.
 
-| Device       | Description                  | Value     | Dimensions<br />(<abbr title="width">w</abbr>×<abbr title="height">h</abbr>, px)  |
-| ------------ | ---------------------------- | --------- | --------------------------------------------------------------------------------- |
-| Small mobile | A small mobile device size   | `mobile1` | 320 × 568                                                                         |
-| Large mobile | A large mobile device size   | `mobile2` | 414 × 896                                                                         |
-| Tablet       | A tablet device size         | `tablet`  | 834 × 1112                                                                        |

From fe71ac0ae83140f96bb177e1a134d55aca6e6295 Mon Sep 17 00:00:00 2001
From: Kyle Gach <kyle.gach@gmail.com>
Date: Wed, 14 Aug 2024 21:14:56 -0600
Subject: [PATCH 5/5] Typo

Co-authored-by: jonniebigodes <joaocontadesenvolvimento@gmail.com>
---
 docs/essentials/backgrounds.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/essentials/backgrounds.mdx b/docs/essentials/backgrounds.mdx
index 08aa41407eee..68151756ecab 100644
--- a/docs/essentials/backgrounds.mdx
+++ b/docs/essentials/backgrounds.mdx
@@ -71,7 +71,7 @@ As implied by the name, this method only sets the default background color for a
 
 ## Extending the configuration
 
-You can also configure backgrounds per-component or per-story basis through [parameter inheritance](../writing-stories/parameters.mdx#component-parameters).
+You can also configure backgrounds on a per-component or per-story basis through [parameter inheritance](../writing-stories/parameters.mdx#component-parameters).
 
 To set the available background colors, use the [`values` property](#values). In this example, we'll adjust the colors for all of the Button component's stories: