WIP

docs/api/doc-block-canvas.md

@@ -124,14 +124,14 @@ Provides HTML class(es) to the preview element, for custom styling.
 
 ### `layout`
 
-Type: `'padded' | 'centered' | 'fullscreen'`
+Type: `'centered' | 'fullscreen' | 'padded'`
 
 Default: `parameters.layout` or `parameters.docs.canvas.layout` or `'padded'`
 
 Specifies how the canvas should layout the story.
 
-- **padded**: Add padding to the story
 - **centered**: Center the story within the canvas
+- **padded**: (default) Add padding to the story
 - **fullscreen**: Show the story as-is, without padding
 
 In addition to the `parameters.docs.canvas.layout` property or the `layout` prop, the `Canvas` block will respect the `parameters.layout` value that defines [how a story is laid out](../configure/story-layout.md) in the regular story view.

docs/api/parameters.md

@@ -0,0 +1,225 @@
+---
+title: 'Parameters'
+---
+
+Parameters are static metadata used to configure your [stories](../get-started/whats-a-story.md) and [addons](../addons/introduction.md) in Storybook. They are specified at the story, meta (component), project (global) levels.
+
+## Story parameters
+
+<div class="aside">
+
+ℹ️ Parameters specified at the story level will [override](#parameter-inheritance) those specified at the project level and meta (component) level.
+
+</div>
+
+Parameters specified at the story level apply to that story only. They are defined in the `parameters` property of the story (named export):
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'angular/parameters-in-story.ts.mdx',
+    'web-components/parameters-in-story.js.mdx',
+    'web-components/parameters-in-story.ts.mdx',
+    'common/parameters-in-story.js.mdx',
+    'common/parameters-in-story.ts.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+## Meta parameters
+
+<div class="aside">
+
+ℹ️ Parameters specified at the meta (component) level will [override](#parameter-inheritance) those specified at the project level.
+
+</div>
+
+Parameter's specified in a [CSF](../writing-stories/introduction.md#component-story-format-csf) file's meta configuration apply to all stories in that file. They are defined in the `parameters` property of the `meta` (default export):
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'angular/parameters-in-meta.ts.mdx',
+    'web-components/parameters-in-meta.js.mdx',
+    'web-components/parameters-in-meta.ts.mdx',
+    'common/parameters-in-meta.js.mdx',
+    'common/parameters-in-meta.ts.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+## Project parameters
+
+Parameters specified at the project (global) level apply to **all stories** in your Storybook. They are defined in the `parameters` property of the default export in your `.storybook/preview.js|ts` file:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+   'common/parameters-in-preview.js.mdx',
+   'common/parameters-in-preview.ts.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+## Available parameters
+
+Storybook only accepts a few parameters directly.
+
+### `layout`
+
+Type: `'centered' | 'fullscreen' | 'padded'`
+
+Default: `'padded'`
+
+Specifies how the canvas should layout the story.
+
+- **centered**: Center the story within the canvas
+- **padded**: (default) Add padding to the story
+- **fullscreen**: Show the story as-is, without padding
+
+### `options`
+
+Type:
+
+```ts
+{
+  storySort?: StorySortConfig | StorySortFn;
+  // TK - necessary?
+  theme?: {
+    base: string;
+    brandTitle?: string;
+  };
+  [key: string]: any;
+}
+```
+
+TK
+
+#### `options.storySort`
+
+Type: `StorySortConfig | StorySortFn`
+
+```ts
+type StorySortConfig = {
+  includeNames?: boolean;
+  locales?: string;
+  method?: 'alphabetical' | 'alphabetical-by-kind' | 'custom';
+  order?: string[];
+};
+
+type Story = {
+  id: string;
+  importPath: string;
+  name: string;
+  title: string;
+};
+
+type StorySortFn = (a: Story, b: Story) => number;
+```
+
+TK
+
+---
+
+All other parameters are contributed by addons. The [essential addon's](../addons/essentials.md) parameters are documented on their individual pages:
+
+- [Actions](../essentials/actions.md)
+- [Backgrounds](../essentials/backgrounds.md)
+- [Controls](../essentials/controls.md)
+- [Highlight](../essentials/highlight.md)
+- [Interactions](../essentials/interactions.md)
+- [Measure & Outline](../essentials/measure-and-outline.md)
+- [Toolbars & globals](../essentials/toolbars-and-globals.md)
+- [Viewport](../essentials/viewport.md)
+
+## Parameter inheritance
+
+No matter where they're specified, parameters are ultimately applied to a single story. Parameters specified at the project (global) level are applied to every story in that project. Those specified at the meta (component) level are applied to every story associated with that meta. And parameters specified for a story only apply to that story.
+
+When specifying parameters, they are merged together in order of increasing specificity:
+
+1. Project (global) parameters
+2. Meta (component) parameters
+3. Story parameters
+
+<div class="aside">
+
+ℹ️ Parameters are **merged**, so individual keys are always overwritten, never dropped.
+
+</div>
+
+In other words, the following specifications of parameters:
+
+```js
+// .storybook/preview.js|ts
+
+const preview = {
+  // 👇 Project-level parameters
+  parameters: {
+    layout: 'centered',
+    viewport: {
+      viewports: defaultViewports,
+    },
+  },
+  // ...
+};
+export default preview;
+```
+
+```js
+// Dialog.stories.js|ts
+
+const meta = {
+  component: Dialog,
+  // 👇 Meta-level parameters
+  parameters: {
+    layout: 'fullscreen',
+    viewport: {
+      defaultViewport: 'medium',
+      viewports: viewportsForDialog,
+    },
+  },
+};
+export default meta;
+
+// (no additional parameters specified)
+export const Basic = {};
+
+export const LargeScreen = {
+  // 👇 Story-level parameters
+  parameters: {
+    layout: 'padded',
+    viewport: {
+      defaultViewport: 'large',
+    },
+  },
+};
+```
+
+Will result in the following parameter values applied to each story:
+
+```js
+// For the Basic story:
+{
+  layout: 'fullscreen',
+  viewport: {
+    defaultViewport: 'medium',
+    viewports: viewportsForDialog,
+  },
+}
+
+// For the LargeScreen story:
+{
+  layout: 'padded',
+  viewport: {
+    defaultViewport: 'large',
+    viewports: viewportsForDialog,
+  },
+}
+```

docs/snippets/common/parameters-in-meta.js.mdx

@@ -0,0 +1,17 @@
+```js
+// Button.stories.js|jsx
+
+import { Button } from './Button';
+
+export default {
+  component: Button,
+  // 👇 Meta-level parameters
+  parameters: {
+    backgrounds: {
+      default: 'dark',
+    },
+  },
+};
+
+export const Basic = {};
+```

docs/snippets/common/parameters-in-meta.ts.mdx

@@ -0,0 +1,23 @@
+```ts
+// Button.stories.ts|tsx
+
+// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
+import type { Meta, StoryObj } from '@storybook/your-framework';
+
+import { Button } from './Button';
+
+const meta: Meta<typeof Button> = {
+  component: Button,
+  // 👇 Meta-level parameters
+  parameters: {
+    backgrounds: {
+      default: 'dark',
+    },
+  },
+};
+export default meta;
+
+type Story = StoryObj<typeof Button>;
+
+export const Basic: Story = {};
+```

docs/snippets/common/parameters-in-preview.js.mdx

@@ -0,0 +1,14 @@
+```ts
+// .storybook/preview.ts
+
+export default {
+  parameters: {
+    backgrounds: {
+      values: [
+        { name: 'light', value: '#fff' },
+        { name: 'dark', value: '#333' },
+      ],
+    },
+  },
+};
+```

docs/snippets/common/parameters-in-preview.ts.mdx

@@ -0,0 +1,19 @@
+```ts
+// .storybook/preview.ts
+
+// Replace your-renderer with the renderer you are using (e.g., react, vue3)
+import { Preview } from '@storybook/your-renderer';
+
+const preview: Preview = {
+  parameters: {
+    backgrounds: {
+      values: [
+        { name: 'light', value: '#fff' },
+        { name: 'dark', value: '#333' },
+      ],
+    },
+  },
+};
+
+export default preview;
+```

docs/snippets/common/parameters-in-story.js.mdx

@@ -0,0 +1,18 @@
+```js
+// Button.stories.js|jsx
+
+import { Button } from './Button';
+
+export default {
+  component: Button,
+};
+
+export const OnDark = {
+  // 👇 Story-level parameters
+  parameters: {
+    backgrounds: {
+      default: 'dark',
+    },
+  },
+};
+```

docs/snippets/common/parameters-in-story.ts.mdx

@@ -0,0 +1,24 @@
+```ts
+// Button.stories.ts|tsx
+
+// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
+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 OnDark: Story = {
+  // 👇 Story-level parameters
+  parameters: {
+    backgrounds: {
+      default: 'dark',
+    },
+  },
+};
+```

docs/toc.js

@@ -589,14 +589,19 @@ module.exports = {
             },
           ],
         },
+        {
+          pathSegment: 'csf',
+          title: 'Component Story Format (CSF)',
+          type: 'link',
+        },
         {
           pathSegment: 'arg-types',
           title: 'ArgTypes',
           type: 'link',
         },
         {
-          pathSegment: 'csf',
-          title: 'Component Story Format (CSF)',
+          pathSegment: 'parameters',
+          title: 'Parameters',
           type: 'link',
         },
         {