docs(storybook): document Storybook 9+ parameters and supported versions

docs/learn/how-to-guides/visual-coverage/storybook-story-modes.md

@@ -22,14 +22,13 @@ A mode is a preset that configures various Storybook globals. For instance, you
 
 ### Setting up globals & addons
 
-Before you define any modes, make sure you’ve configured the relevant Storybook addons in your `.storybook/preview.ts` (or `.js`) file. Examples include:
+Before you define any modes, make sure you’ve configured the relevant Storybook features and addons in your `.storybook/preview.ts` (or `.js`) file. Examples include:
 
-* [`@storybook/addon-viewport`](https://www.npmjs.com/package/@storybook/addon-viewport) for screen sizes
+* [Viewports](https://storybook.js.org/docs/essentials/viewport) and [backgrounds](https://storybook.js.org/docs/essentials/backgrounds), built into Storybook 9 and later (on Storybook 8, install [`@storybook/addon-viewport`](https://www.npmjs.com/package/@storybook/addon-viewport) and [`@storybook/addon-backgrounds`](https://www.npmjs.com/package/@storybook/addon-backgrounds))
 * [`@storybook/addon-themes`](https://www.npmjs.com/package/@storybook/addon-themes) for light/dark themes
-* [`@storybook/addon-backgrounds`](https://www.npmjs.com/package/@storybook/addon-backgrounds) for backgrounds
 * [`storybook-i18n`](https://www.npmjs.com/package/storybook-i18n) for locales
 
-These addons utilize Storybook “globals” and “decorators” under the hood. Argos modes simply manipulate those globals at test time to generate multiple snapshots of the same story.
+These features rely on Storybook “globals” and “decorators” under the hood. Argos modes simply set those globals at test time to generate multiple snapshots of the same story.
 
 {% code title=".storybook/preview.ts" %}
 ```ts
@@ -39,7 +38,7 @@ import "../src/styles.css";
 const preview = {
   parameters: {
     viewport: {
-      viewports: {
+      options: {
         compact: {
           name: "Compact",
           styles: { width: "600px", height: "900px" },
@@ -51,10 +50,10 @@ const preview = {
       },
     },
     backgrounds: {
-      values: [
-        { name: "Light", value: "#ffffff" },
-        { name: "Dark", value: "#1A1A1A" },
-      ],
+      options: {
+        light: { name: "Light", value: "#ffffff" },
+        dark: { name: "Dark", value: "#1A1A1A" },
+      },
     },
   },
   decorators: [
@@ -72,6 +71,10 @@ export default preview;
 ```
 {% endcode %}
 
+{% hint style="info" %}
+On Storybook 8, viewports are defined under `viewport.viewports` and backgrounds under `backgrounds.values` (an array of `{ name, value }`), and a mode selects a background by its color, for example `backgrounds: { value: "#1A1A1A" }`. Argos resolves a mode’s `viewport` against either format.
+{% endhint %}
+
 ### Defining modes
 
 Create a `.storybook/modes.ts` (or `.js`) file that exports an object where each key is a mode name and each value is a set of overrides for the Storybook globals. For example:
@@ -80,19 +83,19 @@ Create a `.storybook/modes.ts` (or `.js`) file that exports an object where each
 ```ts
 export const allModes = {
   dark: {
-    backgrounds: { value: "#1A1A1A" },
+    backgrounds: { value: "dark" },
     theme: "dark",
   },
   mobile: {
     viewport: "compact",
   },
   "dark widescreen": {
-    backgrounds: { value: "#1A1A1A" },
+    backgrounds: { value: "dark" },
     theme: "dark",
     viewport: "widescreen",
   },
   "light mobile": {
-    backgrounds: { value: "#ffffff" },
+    backgrounds: { value: "light" },
     theme: "light",
     viewport: "compact",
   },
@@ -102,6 +105,8 @@ export const allModes = {
 
 Each object can include as many or as few globals as you need. If a mode doesn’t specify a particular global, that global simply won’t be changed in that mode.
 
+A mode’s `viewport` is a key of your `viewport.options` map: Argos resizes the browser to that viewport before capturing the story. Storybook’s own global format works too, so `viewport: { value: "compact", isRotated: true }` captures the viewport in landscape orientation. Likewise, `backgrounds.value` is a key of `backgrounds.options`, and `theme` is the global read by `withThemeByClassName`.
+
 ### Applying modes
 
 Attach modes to any level of your Storybook: globally in `.storybook/preview.ts` (or `.js`), at the component (default export) level, or in an individual story’s parameters. Argos merges all modes defined up the chain.
@@ -257,7 +262,7 @@ Yes. Argos reads your `chromatic.modes` settings if present. However, for new us
 
 <summary>Do all Storybook addons work with Argos modes?</summary>
 
-Any addon that leverages Storybook globals should work, including [@storybook/addon-themes](https://storybook.js.org/addons/@storybook/addon-themes), [@storybook/addon-viewport](https://storybook.js.org/addons/@storybook/addon-viewport), [@storybook/addon-backgrounds](https://storybook.js.org/addons/@storybook/addon-backgrounds), or [storybook-i18n](https://storybook.js.org/addons/storybook-i18n). Modes just provide different values for those globals.
+Any feature or addon that leverages Storybook globals should work, including Storybook’s built-in viewports and backgrounds, [@storybook/addon-themes](https://storybook.js.org/addons/@storybook/addon-themes), or [storybook-i18n](https://storybook.js.org/addons/storybook-i18n). Modes just provide different values for those globals.
 
 </details>
 

docs/quickstart/storybook-quickstart/README.md

@@ -19,7 +19,7 @@ If you use a legacy version of Storybook (\<v8), follow the [legacy Storybook Qu
 
 ### Prerequisites
 
-* [Storybook v8+](https://storybook.js.org/docs/get-started/install) set up in your project
+* [Storybook v9+](https://storybook.js.org/docs/get-started/install) set up in your project
 * [The Storybook Vitest addon](https://storybook.js.org/docs/writing-tests/integrations/vitest-addon) installed
 * [A project created in Argos](https://app.argos-ci.com/new)
 

docs/sdks-reference/storybook.md

@@ -15,6 +15,12 @@ To get started with Argos and Storybook, check out our Quickstart guides:
 * [Storybook + Test Runner](../quickstart/storybook-quickstart/storybook-test-runner-quickstart.md)
 * [Storybook Legacy (\<v8)](../quickstart/storybook-quickstart/storybook-legacy-less-than-v8-quickstart.md)
 
+### Compatibility
+
+* **Storybook** 8 through 11, including the 11 pre-releases. The Vitest addon needs Storybook 9 or later; the Test Runner works from Storybook 8.
+* **Vitest** 4 or 5, with `@vitest/browser` and `@vitest/browser-playwright`, when using the Vitest addon.
+* **Node.js** 22 or later.
+
 ### Comparing Argos and Chromatic
 
 While both Argos and Chromatic provide visual testing for Storybook, they take different approaches:
@@ -68,6 +74,16 @@ export const FormStory: Story = {
 
 Argos supports Story modes to capture different states of your components. Read our [Story modes guide](../learn/how-to-guides/visual-coverage/storybook-story-modes.md) for more details.
 
+### Viewports
+
+Argos captures a story at the viewport selected by its `viewport` global, whether the global comes from a [story mode](../learn/how-to-guides/visual-coverage/storybook-story-modes.md) or from the story’s own `globals`. The value is resolved against `parameters.viewport.options` (`parameters.viewport.viewports` on Storybook 8):
+
+* `"compact"`: a key of the viewport options.
+* `{ value: "compact", isRotated: true }`: Storybook’s global format, where `isRotated` swaps the width and height.
+* `800`: a number is used as the width.
+
+When no viewport matches, the story is captured at the test browser’s default size.
+
 ### Fit to Content vs Page
 
 By default, Argos screenshots are cropped to fit the rendered component (`fitToContent: true`). You can capture the entire page instead by setting `argos.parameters.fitToContent` to `false`.