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

@@ -421,85 +421,101 @@
 
 ### 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" },
++ },
 };
 ```
 
 This locks that story to the `twitter` background, it cannot be changed by the addon UI.
 
 ### 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
 

docs/_snippets/storybook-addon-backgrounds-disable-backgrounds.md → 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 },
   },
 };
 ```