From 4d0902d6af92bee056774a3a5e6e62e6bfc7a3e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Greg=20Berg=C3=A9?= Date: Fri, 11 Sep 2026 21:45:19 +0200 Subject: [PATCH] docs(storybook): document Storybook 9+ parameters and supported versions Companion to argos-ci/argos-javascript#381, which makes @argos-ci/storybook resolve viewports from the Storybook 9+ `viewport.options` parameter and the `{ value, isRotated }` global. - Story modes guide: viewports and backgrounds are built into Storybook 9+ and configured through `options` maps, and a mode selects a background by key. A hint keeps the Storybook 8 format (`viewports`, `values`, color as value) for readers still on 8. - SDK reference: a Compatibility section (Storybook 8 through 11, Vitest 4 or 5, Node.js 22) and a Viewports section describing how a mode's or a story's `viewport` global is resolved. - Storybook Quickstart: the Vitest addon requires Storybook 9 or later. Co-Authored-By: Claude Fable 5.1 --- .../visual-coverage/storybook-story-modes.md | 31 +++++++++++-------- .../quickstart/storybook-quickstart/README.md | 2 +- docs/sdks-reference/storybook.md | 16 ++++++++++ 3 files changed, 35 insertions(+), 14 deletions(-) diff --git a/docs/learn/how-to-guides/visual-coverage/storybook-story-modes.md b/docs/learn/how-to-guides/visual-coverage/storybook-story-modes.md index 124449a8..36604394 100644 --- a/docs/learn/how-to-guides/visual-coverage/storybook-story-modes.md +++ b/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 Do all Storybook addons work with Argos modes? -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. diff --git a/docs/quickstart/storybook-quickstart/README.md b/docs/quickstart/storybook-quickstart/README.md index f38ff597..886fca22 100644 --- a/docs/quickstart/storybook-quickstart/README.md +++ b/docs/quickstart/storybook-quickstart/README.md @@ -19,7 +19,7 @@ If you use a legacy version of Storybook (\