Merge pull request #16992 from storybookjs/11697-document-project-arg…

…-argTypes

First cut at documentation of project arg/argTypes for discussion

docs/api/argtypes.md

@@ -89,6 +89,24 @@ In particular, this would render a row with a modified description, a type displ
 💡 As with other Storybook properties (e.g., args, decorators), you can also override ArgTypes per story basis.
 </div>
 
+#### Global `argTypes`
+
+You can also define arg types at the global level; they will apply to every component's stories unless you overwrite them. To do so, export the `argTypes` key in your `preview.js`:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/button-story-project-args-theme.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
+<div class="aside">
+💡 If you define a global arg type for a story that does not have that arg (e.g. if there is no corresponding global arg definition), then the arg type will have no effect.
+</div>
+
 #### Using argTypes in addons
 
 If you want to access the argTypes of the current component inside an addon, you can use the `useArgTypes` hook from the `@storybook/api` package:
@@ -101,4 +119,4 @@ If you want to access the argTypes of the current component inside an addon, you
   ]}
 />
 
-<!-- prettier-ignore-end -->
+<!-- prettier-ignore-end -->

docs/snippets/common/button-story-project-args-theme.js.mdx

@@ -0,0 +1,9 @@
+```js
+// preview.js
+
+// All stories expect a theme arg
+export const argTypes = { theme: { control: { options: ['light', 'dark'] } } };
+
+// The default value of the theme arg to all stories
+export const args = { theme: 'light' };
+```

docs/writing-stories/args.md

@@ -10,7 +10,7 @@ Learn how and why to write stories in [the introduction](./introduction.md#using
 
 ## Args object
 
-The `args` object can be defined at the [story](#story-args) and [component level](#component-args). It is a JSON serializable object composed of string keys with matching valid value types that can be passed into a component for your framework.
+The `args` object can be defined at the [story](#story-args), [component](#component-args) and [global level](#global-args). It is a JSON serializable object composed of string keys with matching valid value types that can be passed into a component for your framework.
 
 ## Story args
 
@@ -76,6 +76,20 @@ You can also define args at the component level; they will apply to all the comp
 
 <!-- prettier-ignore-end -->
 
+## Global args
+
+You can also define args at the global level; they will apply to every component's stories unless you overwrite them. To do so, export the `args` key in your `preview.js`:
+
+<!-- prettier-ignore-start -->
+
+<CodeSnippets
+  paths={[
+    'common/button-story-project-args-theme.js.mdx',
+  ]}
+/>
+
+<!-- prettier-ignore-end -->
+
 ## Args composition
 
 You can separate the arguments to a story to compose in other stories. Here's how you can combine args for multiple stories of the same component.