CSF: Update docs for using globals in viewports and background addons

MIGRATION.md

@@ -1,5 +1,8 @@
 <h1>Migration</h1>
 
+- [From version 8.2.x to 8.3.x](#from-version-82x-to-83x)
+  - [New parameters format for addon backgrounds](#new-parameters-format-for-addon-backgrounds)
+  - [New parameters format for addon viewport](#new-parameters-format-for-addon-viewport)
 - [From version 8.1.x to 8.2.x](#from-version-81x-to-82x)
   - [Failed to resolve import "@storybook/X" error](#failed-to-resolve-import-storybookx-error)
   - [Preview.js globals renamed to initialGlobals](#previewjs-globals-renamed-to-initialglobals)
@@ -414,6 +417,90 @@
   - [Packages renaming](#packages-renaming)
   - [Deprecated embedded addons](#deprecated-embedded-addons)
 
+## From version 8.2.x to 8.3.x
+
+### 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.
+
+> ! You need to set the feature flag `backgroundsStoryGlobals` to `true` in your `.storybook/main.ts` to use the new format.
+
+```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' },
++    },
+  },
+};
+```
+
+Setting an override value should now be done via a `globals` property on your component/meta or story itself:
+
+```ts
+// Button.stories.ts
+export default {
+  component: Button,
+  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.
+
+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.
+
+```diff
+// .storybook/preview.js
+export const parameters = {
+  viewport: {
+-    viewports: {
+-      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:
+
+```ts
+// Button.stories.ts
+export default {
+  component: Button,
+  globals: {
+    viewport: { value: 'phone' },
+  },
+};
+```
+
+This locks that story to the `phone` viewport, it cannot be changed by the addon UI.
+
 ## From version 8.1.x to 8.2.x
 
 ### Failed to resolve import "@storybook/X" error

docs/_snippets/component-story-theme-override-globals.md

@@ -0,0 +1,106 @@
+```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' },
+};
+```

docs/_snippets/main-config-features-backgrounds-story-globals.md

@@ -0,0 +1,25 @@
+```js filename=".storybook/main.js" renderer="common" language="js"
+export default {
+  // Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
+  framework: '@storybook/your-framework',
+  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  features: {
+    backgroundsStoryGlobals: true,
+  },
+};
+```
+
+```ts filename=".storybook/main.ts" renderer="common" language="ts"
+// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
+import type { StorybookConfig } from '@storybook/your-framework';
+
+const config: StorybookConfig = {
+  framework: '@storybook/your-framework',
+  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  features: {
+    backgroundsStoryGlobals: true,
+  },
+};
+
+export default config;
+```

docs/_snippets/main-config-features-viewport-story-globals.md

@@ -0,0 +1,25 @@
+```js filename=".storybook/main.js" renderer="common" language="js"
+export default {
+  // Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
+  framework: '@storybook/your-framework',
+  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  features: {
+    viewportStoryGlobals: true,
+  },
+};
+```
+
+```ts filename=".storybook/main.ts" renderer="common" language="ts"
+// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
+import type { StorybookConfig } from '@storybook/your-framework';
+
+const config: StorybookConfig = {
+  framework: '@storybook/your-framework',
+  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  features: {
+    viewportStoryGlobals: true,
+  },
+};
+
+export default config;
+```