From 34c9bb2dd620fe7f59edbe91a4901b9e7539ca8c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Peter=20Dr=C3=A4xler?= <peter@draxler.ml>
Date: Fri, 6 Aug 2021 10:00:58 +0200
Subject: [PATCH 01/15] Button docs

---
 .storybook/preview.js                         |   8 +-
 packages/react-button/.storybook/preview.js   |   1 +
 packages/react-button/src/Button.stories.tsx  | 118 ------------
 .../src/components/Button/Button.stories.tsx  | 169 ++++++++++++++++++
 .../src/components/Button/Button.tsx          |  33 +++-
 .../react-button/src/tmp-icons.stories.tsx    |  23 +++
 6 files changed, 229 insertions(+), 123 deletions(-)
 delete mode 100644 packages/react-button/src/Button.stories.tsx
 create mode 100644 packages/react-button/src/components/Button/Button.stories.tsx
 create mode 100644 packages/react-button/src/tmp-icons.stories.tsx

diff --git a/.storybook/preview.js b/.storybook/preview.js
index 4305b6bebe269..b8ee72eac2dbe 100644
--- a/.storybook/preview.js
+++ b/.storybook/preview.js
@@ -7,7 +7,13 @@ export const decorators = [withFluentProvider, withStrictMode];
 /** @type {import('@storybook/react').Parameters} */
 export const parameters = {
   controls: {
-    disable: true,
+    hideNoControlsWarning: true,
     expanded: true,
   },
+  viewMode: 'docs',
+  docs: {
+    source: {
+      excludeDecorators: true,
+    },
+  },
 };
diff --git a/packages/react-button/.storybook/preview.js b/packages/react-button/.storybook/preview.js
index b52409294c330..9c28a0e6c1e1b 100644
--- a/packages/react-button/.storybook/preview.js
+++ b/packages/react-button/.storybook/preview.js
@@ -1,3 +1,4 @@
 import * as rootPreview from '../../../.storybook/preview';
 
 export const decorators = [...rootPreview.decorators];
+export const parameters = rootPreview.parameters;
diff --git a/packages/react-button/src/Button.stories.tsx b/packages/react-button/src/Button.stories.tsx
deleted file mode 100644
index d1c6754cf9e7d..0000000000000
--- a/packages/react-button/src/Button.stories.tsx
+++ /dev/null
@@ -1,118 +0,0 @@
-import * as React from 'react';
-import { Button, ButtonProps } from './Button';
-import { Playground } from './Playground.stories';
-import { PlaygroundProps } from './Playground.types.stories';
-import { buttonBaseProps } from './buttonBaseProps.stories';
-
-// TODO: this is here while waiting for react-icons to merge
-const SVGIcon = () => (
-  <span
-    role="presentation"
-    style={{
-      width: '1em',
-      height: '1em',
-    }}
-  >
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      viewBox="0 0 2048 2048"
-      style={{
-        height: '100%',
-        fill: 'currentColor',
-        verticalAlign: 'top',
-      }}
-    >
-      <path d="M768 768h128v128H768V768zm384 768h128v128h-128v-128zm384-768h128v128h-128V768zm-384 0h128v128h-128V768zm-384 256h128v128H768v-128zm-384 0h128v128H384v-128zm1152 0h128v128h-128v-128zm-384 0h128v128h-128v-128zm-384 256h128v128H768v-128zm-384 0h128v128H384v-128zm1152 0h128v128h-128v-128zm-384 0h128v128h-128v-128zm-384 256h128v128H768v-128zm-384 0h128v128H384v-128zM2048 128v1792H0V128h384V0h128v128h1024V0h128v128h384zM128 256v256h1792V256h-256v128h-128V256H512v128H384V256H128zm1792 1536V640H128v1152h1792z" />
-    </svg>
-  </span>
-);
-
-export const Default = () => <AppearanceExample />;
-
-//
-// Anatomy & Layout
-//
-
-export const TextOnly = () => <Button>Text</Button>;
-export const TextOnlyLong = () => <Button>Text truncates after it hits the max width token value</Button>;
-
-export const IconWithText = () => (
-  <>
-    <Button icon={<SVGIcon />}>Text</Button>
-    <Button icon={<SVGIcon />} iconPosition="after">
-      Text
-    </Button>
-  </>
-);
-
-export const IconOnly = () => <Button icon={<SVGIcon />} />;
-
-//
-// Size
-//
-const SizeExample = ({ size }: { size?: ButtonProps['size'] }) => (
-  <>
-    <h4>{size || '(default)'}</h4>
-    <Button size={size}>Text</Button>
-    <Button size={size} icon={<SVGIcon />}>
-      Text
-    </Button>
-    <Button size={size} icon={<SVGIcon />} />
-  </>
-);
-
-export const Size = () => (
-  <>
-    <SizeExample size="small" />
-    <SizeExample />
-    <SizeExample size="large" />
-  </>
-);
-
-//
-// Appearance
-//
-const AppearanceExample = (props: ButtonProps) => (
-  <>
-    <Button {...props} icon={<SVGIcon />} />
-    <br />
-    <Button {...props}>Text</Button>
-    <Button {...props} icon={<SVGIcon />}>
-      Text
-    </Button>
-    <Button {...props} icon={<SVGIcon />} iconPosition="after">
-      Text
-    </Button>
-  </>
-);
-
-export const Primary = () => <AppearanceExample primary />;
-
-//
-// States
-//
-export const Disabled = () => (
-  <>
-    <Button disabled icon={<SVGIcon />}>
-      Default disabled
-    </Button>
-    <Button primary disabled icon={<SVGIcon />}>
-      Primary disabled
-    </Button>
-  </>
-);
-
-const buttonProps: PlaygroundProps<ButtonProps>['sections'] = [
-  { sectionName: 'Button props', propList: buttonBaseProps },
-];
-
-export const ButtonPlayground = () => (
-  <Playground sections={buttonProps}>
-    <Button />
-  </Playground>
-);
-
-export default {
-  title: 'Components/Button',
-  component: Button,
-};
diff --git a/packages/react-button/src/components/Button/Button.stories.tsx b/packages/react-button/src/components/Button/Button.stories.tsx
new file mode 100644
index 0000000000000..d954d67cb3942
--- /dev/null
+++ b/packages/react-button/src/components/Button/Button.stories.tsx
@@ -0,0 +1,169 @@
+import * as React from 'react';
+import { Button, ButtonProps } from '../../Button';
+import { Meta } from '@storybook/react';
+
+// TODO: this is here while waiting for react-icons to merge
+import { CalendarIcon } from '../../tmp-icons.stories';
+
+export const Default = (props: ButtonProps) => <Button {...props}>Button</Button>;
+
+export const Emphasis = () => (
+  <>
+    <Button primary>Primary button</Button>
+    <Button>Default button</Button>
+    <Button outline>Outline button</Button>
+    <Button subtle>Subtle button</Button>
+    <Button transparent>Transparent button</Button>
+  </>
+);
+Emphasis.parameters = {
+  docs: {
+    description: {
+      story:
+        '- `primary` button is used for the most important action on the page or in a view\n' +
+        '- `default` button is used for subordinate actions\n' +
+        '- `outline` has no background styling and is emphasized through the styling of its content and borders\n' +
+        '- `transparent` has no background or border styling and is just emphasized through its content styling\n' +
+        '- `subtle` button blends into its background and becomes less emphasized\n',
+    },
+  },
+};
+
+export const ButtonWithIcon = () => (
+  <>
+    <Button icon={<CalendarIcon />}>Text</Button>
+    <Button icon={<CalendarIcon />} iconPosition="after">
+      Text
+    </Button>
+    <Button icon={<CalendarIcon />} />
+  </>
+);
+ButtonWithIcon.parameters = {
+  docs: {
+    description: {
+      story:
+        'Button has an `icon` slot that, if specified, renders an icon either `before` or `after` the children, ' +
+        'as specified by the `iconPosition` prop.',
+    },
+  },
+};
+
+export const CircularButton = () => (
+  <>
+    <Button circular>Button</Button>
+    <Button circular outline icon={<CalendarIcon />} />
+    <Button circular subtle icon={<CalendarIcon />} />
+    <Button circular transparent icon={<CalendarIcon />} />
+  </>
+);
+CircularButton.parameters = {
+  docs: {
+    description: {
+      story: 'A button can have completely rounded corners.',
+    },
+  },
+};
+
+export const ButtonSize = () => (
+  <>
+    <div>
+      <h4>small</h4>
+      <Button size="small">Text</Button>
+      <Button size="small" icon={<CalendarIcon />}>
+        Text
+      </Button>
+      <Button size="small" icon={<CalendarIcon />} />
+    </div>
+    <div>
+      <h4>medium</h4>
+      <Button>Text</Button>
+      <Button icon={<CalendarIcon />}>Text</Button>
+      <Button icon={<CalendarIcon />} />
+    </div>
+    <div>
+      <h4>large</h4>
+      <Button size="large">Text</Button>
+      <Button size="large" icon={<CalendarIcon />}>
+        Text
+      </Button>
+      <Button size="large" icon={<CalendarIcon />} />
+    </div>
+  </>
+);
+ButtonSize.parameters = {
+  docs: {
+    description: {
+      story: 'A button supports `small`, `medium` and `large` size. Default size is `medium`.',
+    },
+  },
+};
+
+export const BlockButton = () => (
+  <>
+    <Button block>Block button</Button>
+  </>
+);
+BlockButton.parameters = {
+  docs: {
+    description: {
+      story: 'A button can fill the width of its container.',
+    },
+  },
+};
+
+export const DisabledButton = () => (
+  <>
+    <div>
+      <Button>Default</Button>
+      <Button disabled>Disabled</Button>
+      <Button disabledFocusable>Disabled focusable</Button>
+    </div>
+    <div>
+      <Button primary icon={<CalendarIcon />}>
+        Primary
+      </Button>
+      <Button primary disabled icon={<CalendarIcon />}>
+        Primary disabled
+      </Button>
+      <Button primary disabledFocusable>
+        Primary disabled focusable
+      </Button>
+    </div>
+  </>
+);
+DisabledButton.parameters = {
+  docs: {
+    description: {
+      story: `A button can be \`disabled\` or \`disabledFocusable\`.
+              \`disabledFocusable\` is used in scenarios where it is important to keep a consistent tab order
+              for screen reader and keyboard users. The primary example of this pattern is when
+              the disabled button is in a menu or a commandbar and is seldom used for standalone buttons.`,
+    },
+  },
+};
+
+export const ButtonWithLongText = () => (
+  <>
+    <Button>Text</Button>
+    <Button>Text truncates after it hits the max width token value</Button>
+  </>
+);
+ButtonWithLongText.parameters = {
+  docs: {
+    description: {
+      story: 'Text truncates after it hits the max width theme token value.',
+    },
+  },
+};
+
+export default {
+  title: 'Components/Button',
+  component: Button,
+  decorators: [
+    Story => (
+      <div style={{ display: 'flex', justifyContent: 'space-evenly' }}>
+        <Story />
+      </div>
+    ),
+  ],
+} as Meta;
diff --git a/packages/react-button/src/components/Button/Button.tsx b/packages/react-button/src/components/Button/Button.tsx
index d71f9f2921ee3..f095869d7bfb6 100644
--- a/packages/react-button/src/components/Button/Button.tsx
+++ b/packages/react-button/src/components/Button/Button.tsx
@@ -5,8 +5,35 @@ import { renderButton } from './renderButton';
 import { useButtonStyles } from './useButtonStyles';
 
 /**
- * Define a styled Button, using the `useButton` hook.
- * {@docCategory Button}
+ * Buttons give people a way to trigger an action.
+ *
+ * They’re typically found in forms, dialog panels, and dialogs. Some buttons are specialized for particular tasks,
+ * such as navigation, repeated actions, or presenting menus.
+ *
+ * See also:
+ * [MenuButton](/?path=/docs/components-menubutton--menu-button-playground),
+ * [ToggleButton](/?path=/docs/components-togglebutton--toggle-button-playground),
+ * [CompoundButton](/?path=/docs/components-compoundbutton--compound-button-playground)
+ *
+ * ## Best practices
+ * ### Layout
+ * - For dialog boxes and panels, where people are moving through a sequence of screens, right-align buttons with the
+ * container.
+ * - For single-page forms and focused tasks, left-align buttons with the container.
+ * - Always place the primary button on the left, the secondary button just to the right of it.
+ * - Show only one primary button that inherits theme color at rest state. If there are more than two buttons with
+ * equal priority, all buttons should have neutral backgrounds.
+ * - Don't use a button to navigate to another place; use a link instead. The exception is in a wizard where "Back" and
+ * "Next" buttons may be used.
+ * - Don't place the default focus on a button that destroys data. Instead, place the default focus on the button that
+ * performs the "safe act" and retains the content (such as "Save") or cancels the action (such as "Cancel").
+ *
+ * ### Content
+ * - Use sentence-style capitalization—only capitalize the first word. For more info, see
+ * [Capitalization](https://docs.microsoft.com/en-us/style-guide/capitalization) in the Microsoft Writing Style Guide.
+ * - Make sure it's clear what will happen when people interact with the button. Be concise; usually a single verb
+ * is best. Include a noun if there is any room for interpretation about what the verb means.
+ * For example, "Delete folder" or "Create account".
  */
 export const Button: React.FunctionComponent<ButtonProps & React.RefAttributes<HTMLElement>> = React.forwardRef<
   HTMLElement,
@@ -18,5 +45,3 @@ export const Button: React.FunctionComponent<ButtonProps & React.RefAttributes<H
 
   return renderButton(state);
 });
-
-Button.displayName = 'Button';
diff --git a/packages/react-button/src/tmp-icons.stories.tsx b/packages/react-button/src/tmp-icons.stories.tsx
new file mode 100644
index 0000000000000..0ea6cb55450b1
--- /dev/null
+++ b/packages/react-button/src/tmp-icons.stories.tsx
@@ -0,0 +1,23 @@
+import * as React from 'react';
+
+export const CalendarIcon = () => (
+  <span
+    role="presentation"
+    style={{
+      width: '1em',
+      height: '1em',
+    }}
+  >
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 2048 2048"
+      style={{
+        height: '100%',
+        fill: 'currentColor',
+        verticalAlign: 'top',
+      }}
+    >
+      <path d="M768 768h128v128H768V768zm384 768h128v128h-128v-128zm384-768h128v128h-128V768zm-384 0h128v128h-128V768zm-384 256h128v128H768v-128zm-384 0h128v128H384v-128zm1152 0h128v128h-128v-128zm-384 0h128v128h-128v-128zm-384 256h128v128H768v-128zm-384 0h128v128H384v-128zm1152 0h128v128h-128v-128zm-384 0h128v128h-128v-128zm-384 256h128v128H768v-128zm-384 0h128v128H384v-128zM2048 128v1792H0V128h384V0h128v128h1024V0h128v128h384zM128 256v256h1792V256h-256v128h-128V256H512v128H384V256H128zm1792 1536V640H128v1152h1792z" />
+    </svg>
+  </span>
+);

From 080028a6bb25fa54d0a40c84ac5c6c110ccdb612 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Peter=20Dr=C3=A4xler?= <peter@draxler.ml>
Date: Fri, 6 Aug 2021 16:39:57 +0200
Subject: [PATCH 02/15] Change files

---
 ...-react-button-2b550638-96d1-40ea-9b3f-94bd0ecc1d89.json | 7 +++++++
 1 file changed, 7 insertions(+)
 create mode 100644 change/@fluentui-react-button-2b550638-96d1-40ea-9b3f-94bd0ecc1d89.json

diff --git a/change/@fluentui-react-button-2b550638-96d1-40ea-9b3f-94bd0ecc1d89.json b/change/@fluentui-react-button-2b550638-96d1-40ea-9b3f-94bd0ecc1d89.json
new file mode 100644
index 0000000000000..f55f555937b04
--- /dev/null
+++ b/change/@fluentui-react-button-2b550638-96d1-40ea-9b3f-94bd0ecc1d89.json
@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "Button docs",
+  "packageName": "@fluentui/react-button",
+  "email": "peter@draxler.ml",
+  "dependentChangeType": "none"
+}

From eb8d3fcb4f19736be8929f78a9e8f2eb334251e5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Peter=20Dr=C3=A4xler?= <peter@draxler.ml>
Date: Mon, 9 Aug 2021 19:18:04 +0200
Subject: [PATCH 03/15] use @fluentui/react-icons

---
 .../src/components/Button/Button.stories.tsx  | 32 +++++++++----------
 1 file changed, 15 insertions(+), 17 deletions(-)

diff --git a/packages/react-button/src/components/Button/Button.stories.tsx b/packages/react-button/src/components/Button/Button.stories.tsx
index d954d67cb3942..db1e3e2506ab9 100644
--- a/packages/react-button/src/components/Button/Button.stories.tsx
+++ b/packages/react-button/src/components/Button/Button.stories.tsx
@@ -1,9 +1,7 @@
 import * as React from 'react';
 import { Button, ButtonProps } from '../../Button';
 import { Meta } from '@storybook/react';
-
-// TODO: this is here while waiting for react-icons to merge
-import { CalendarIcon } from '../../tmp-icons.stories';
+import { CalendarMonth24Regular } from '@fluentui/react-icons';
 
 export const Default = (props: ButtonProps) => <Button {...props}>Button</Button>;
 
@@ -31,11 +29,11 @@ Emphasis.parameters = {
 
 export const ButtonWithIcon = () => (
   <>
-    <Button icon={<CalendarIcon />}>Text</Button>
-    <Button icon={<CalendarIcon />} iconPosition="after">
+    <Button icon={<CalendarMonth24Regular />}>Text</Button>
+    <Button icon={<CalendarMonth24Regular />} iconPosition="after">
       Text
     </Button>
-    <Button icon={<CalendarIcon />} />
+    <Button icon={<CalendarMonth24Regular />} />
   </>
 );
 ButtonWithIcon.parameters = {
@@ -51,9 +49,9 @@ ButtonWithIcon.parameters = {
 export const CircularButton = () => (
   <>
     <Button circular>Button</Button>
-    <Button circular outline icon={<CalendarIcon />} />
-    <Button circular subtle icon={<CalendarIcon />} />
-    <Button circular transparent icon={<CalendarIcon />} />
+    <Button circular outline icon={<CalendarMonth24Regular />} />
+    <Button circular subtle icon={<CalendarMonth24Regular />} />
+    <Button circular transparent icon={<CalendarMonth24Regular />} />
   </>
 );
 CircularButton.parameters = {
@@ -69,24 +67,24 @@ export const ButtonSize = () => (
     <div>
       <h4>small</h4>
       <Button size="small">Text</Button>
-      <Button size="small" icon={<CalendarIcon />}>
+      <Button size="small" icon={<CalendarMonth24Regular />}>
         Text
       </Button>
-      <Button size="small" icon={<CalendarIcon />} />
+      <Button size="small" icon={<CalendarMonth24Regular />} />
     </div>
     <div>
       <h4>medium</h4>
       <Button>Text</Button>
-      <Button icon={<CalendarIcon />}>Text</Button>
-      <Button icon={<CalendarIcon />} />
+      <Button icon={<CalendarMonth24Regular />}>Text</Button>
+      <Button icon={<CalendarMonth24Regular />} />
     </div>
     <div>
       <h4>large</h4>
       <Button size="large">Text</Button>
-      <Button size="large" icon={<CalendarIcon />}>
+      <Button size="large" icon={<CalendarMonth24Regular />}>
         Text
       </Button>
-      <Button size="large" icon={<CalendarIcon />} />
+      <Button size="large" icon={<CalendarMonth24Regular />} />
     </div>
   </>
 );
@@ -119,10 +117,10 @@ export const DisabledButton = () => (
       <Button disabledFocusable>Disabled focusable</Button>
     </div>
     <div>
-      <Button primary icon={<CalendarIcon />}>
+      <Button primary icon={<CalendarMonth24Regular />}>
         Primary
       </Button>
-      <Button primary disabled icon={<CalendarIcon />}>
+      <Button primary disabled icon={<CalendarMonth24Regular />}>
         Primary disabled
       </Button>
       <Button primary disabledFocusable>

From 490bc7fb202c2e2100eef5c8a70bd519c6716aaf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Peter=20Dr=C3=A4xler?= <peter@draxler.ml>
Date: Tue, 10 Aug 2021 15:24:43 +0200
Subject: [PATCH 04/15] styling of stories

---
 .../src/components/Button/Button.stories.tsx  | 58 ++++++++++---------
 1 file changed, 30 insertions(+), 28 deletions(-)

diff --git a/packages/react-button/src/components/Button/Button.stories.tsx b/packages/react-button/src/components/Button/Button.stories.tsx
index db1e3e2506ab9..121f45f22cc00 100644
--- a/packages/react-button/src/components/Button/Button.stories.tsx
+++ b/packages/react-button/src/components/Button/Button.stories.tsx
@@ -62,32 +62,34 @@ CircularButton.parameters = {
   },
 };
 
-export const ButtonSize = () => (
-  <>
-    <div>
-      <h4>small</h4>
-      <Button size="small">Text</Button>
-      <Button size="small" icon={<CalendarMonth24Regular />}>
-        Text
-      </Button>
-      <Button size="small" icon={<CalendarMonth24Regular />} />
-    </div>
-    <div>
-      <h4>medium</h4>
-      <Button>Text</Button>
-      <Button icon={<CalendarMonth24Regular />}>Text</Button>
-      <Button icon={<CalendarMonth24Regular />} />
-    </div>
-    <div>
-      <h4>large</h4>
-      <Button size="large">Text</Button>
-      <Button size="large" icon={<CalendarMonth24Regular />}>
-        Text
-      </Button>
-      <Button size="large" icon={<CalendarMonth24Regular />} />
-    </div>
-  </>
-);
+export const ButtonSize = () => {
+  return (
+    <>
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: '1em' }}>
+        <h4 style={{ width: '100%', margin: 0 }}>small</h4>
+        <Button size="small">Text</Button>
+        <Button size="small" icon={<CalendarMonth24Regular />}>
+          Text
+        </Button>
+        <Button size="small" icon={<CalendarMonth24Regular />} />
+      </div>
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: '1em' }}>
+        <h4 style={{ width: '100%', margin: 0 }}>medium</h4>
+        <Button>Text</Button>
+        <Button icon={<CalendarMonth24Regular />}>Text</Button>
+        <Button icon={<CalendarMonth24Regular />} />
+      </div>
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: '1em' }}>
+        <h4 style={{ width: '100%', margin: 0 }}>large</h4>
+        <Button size="large">Text</Button>
+        <Button size="large" icon={<CalendarMonth24Regular />}>
+          Text
+        </Button>
+        <Button size="large" icon={<CalendarMonth24Regular />} />
+      </div>
+    </>
+  );
+};
 ButtonSize.parameters = {
   docs: {
     description: {
@@ -111,12 +113,12 @@ BlockButton.parameters = {
 
 export const DisabledButton = () => (
   <>
-    <div>
+    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.5em' }}>
       <Button>Default</Button>
       <Button disabled>Disabled</Button>
       <Button disabledFocusable>Disabled focusable</Button>
     </div>
-    <div>
+    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.5em' }}>
       <Button primary icon={<CalendarMonth24Regular />}>
         Primary
       </Button>

From 87ab8e24d95f080847b523a6e624b3b4038f6167 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Peter=20Dr=C3=A4xler?= <peter@draxler.ml>
Date: Tue, 10 Aug 2021 16:16:00 +0200
Subject: [PATCH 05/15] use variables for repeated styles

---
 .../src/components/Button/Button.stories.tsx  | 58 ++++++++++---------
 1 file changed, 32 insertions(+), 26 deletions(-)

diff --git a/packages/react-button/src/components/Button/Button.stories.tsx b/packages/react-button/src/components/Button/Button.stories.tsx
index 121f45f22cc00..7f898fa5ac2b6 100644
--- a/packages/react-button/src/components/Button/Button.stories.tsx
+++ b/packages/react-button/src/components/Button/Button.stories.tsx
@@ -63,24 +63,26 @@ CircularButton.parameters = {
 };
 
 export const ButtonSize = () => {
+  const groupStyles: React.CSSProperties = { display: 'flex', flexWrap: 'wrap', gap: '0.5em' };
+  const headerStyles: React.CSSProperties = { width: '100%', margin: 0 };
   return (
     <>
-      <div style={{ display: 'flex', flexWrap: 'wrap', gap: '1em' }}>
-        <h4 style={{ width: '100%', margin: 0 }}>small</h4>
+      <div style={groupStyles}>
+        <h4 style={headerStyles}>small</h4>
         <Button size="small">Text</Button>
         <Button size="small" icon={<CalendarMonth24Regular />}>
           Text
         </Button>
         <Button size="small" icon={<CalendarMonth24Regular />} />
       </div>
-      <div style={{ display: 'flex', flexWrap: 'wrap', gap: '1em' }}>
-        <h4 style={{ width: '100%', margin: 0 }}>medium</h4>
+      <div style={groupStyles}>
+        <h4 style={headerStyles}>medium</h4>
         <Button>Text</Button>
         <Button icon={<CalendarMonth24Regular />}>Text</Button>
         <Button icon={<CalendarMonth24Regular />} />
       </div>
-      <div style={{ display: 'flex', flexWrap: 'wrap', gap: '1em' }}>
-        <h4 style={{ width: '100%', margin: 0 }}>large</h4>
+      <div style={groupStyles}>
+        <h4 style={headerStyles}>large</h4>
         <Button size="large">Text</Button>
         <Button size="large" icon={<CalendarMonth24Regular />}>
           Text
@@ -111,26 +113,30 @@ BlockButton.parameters = {
   },
 };
 
-export const DisabledButton = () => (
-  <>
-    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.5em' }}>
-      <Button>Default</Button>
-      <Button disabled>Disabled</Button>
-      <Button disabledFocusable>Disabled focusable</Button>
-    </div>
-    <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.5em' }}>
-      <Button primary icon={<CalendarMonth24Regular />}>
-        Primary
-      </Button>
-      <Button primary disabled icon={<CalendarMonth24Regular />}>
-        Primary disabled
-      </Button>
-      <Button primary disabledFocusable>
-        Primary disabled focusable
-      </Button>
-    </div>
-  </>
-);
+export const DisabledButton = () => {
+  const groupStyles: React.CSSProperties = { display: 'flex', flexWrap: 'wrap', gap: '0.5em' };
+
+  return (
+    <>
+      <div style={groupStyles}>
+        <Button>Default</Button>
+        <Button disabled>Disabled</Button>
+        <Button disabledFocusable>Disabled focusable</Button>
+      </div>
+      <div style={groupStyles}>
+        <Button primary icon={<CalendarMonth24Regular />}>
+          Primary
+        </Button>
+        <Button primary disabled icon={<CalendarMonth24Regular />}>
+          Primary disabled
+        </Button>
+        <Button primary disabledFocusable>
+          Primary disabled focusable
+        </Button>
+      </div>
+    </>
+  );
+};
 DisabledButton.parameters = {
   docs: {
     description: {

From cbc50f42d4e131a7c7c3048fbad6417c1627686f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Peter=20Dr=C3=A4xler?= <peter@draxler.ml>
Date: Sat, 14 Aug 2021 09:21:14 +0200
Subject: [PATCH 06/15] Update packages/react-button/.storybook/preview.js

Co-authored-by: Martin Hochel <hochelmartin@gmail.com>
---
 packages/react-button/.storybook/preview.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react-button/.storybook/preview.js b/packages/react-button/.storybook/preview.js
index 9c28a0e6c1e1b..509dbd0b6d66b 100644
--- a/packages/react-button/.storybook/preview.js
+++ b/packages/react-button/.storybook/preview.js
@@ -1,4 +1,4 @@
 import * as rootPreview from '../../../.storybook/preview';
 
 export const decorators = [...rootPreview.decorators];
-export const parameters = rootPreview.parameters;
+export const parameters = [...rootPreview.parameters];

From 493052618bce8763dc5532168ad2874746a44ffb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Peter=20Dr=C3=A4xler?= <peter@draxler.ml>
Date: Sat, 14 Aug 2021 09:40:36 +0200
Subject: [PATCH 07/15] Update preview.js

---
 .storybook/preview.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.storybook/preview.js b/.storybook/preview.js
index b8ee72eac2dbe..e27f725619b08 100644
--- a/.storybook/preview.js
+++ b/.storybook/preview.js
@@ -7,7 +7,7 @@ export const decorators = [withFluentProvider, withStrictMode];
 /** @type {import('@storybook/react').Parameters} */
 export const parameters = {
   controls: {
-    hideNoControlsWarning: true,
+    disabled: true,
     expanded: true,
   },
   viewMode: 'docs',

From eb35fd773065308864169e1b12ad982c70c55ce4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Peter=20Dr=C3=A4xler?= <peter@draxler.ml>
Date: Sat, 14 Aug 2021 09:40:58 +0200
Subject: [PATCH 08/15] Update preview.js

---
 .storybook/preview.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/.storybook/preview.js b/.storybook/preview.js
index e27f725619b08..2666e4e3debfb 100644
--- a/.storybook/preview.js
+++ b/.storybook/preview.js
@@ -7,7 +7,7 @@ export const decorators = [withFluentProvider, withStrictMode];
 /** @type {import('@storybook/react').Parameters} */
 export const parameters = {
   controls: {
-    disabled: true,
+    disable: true,
     expanded: true,
   },
   viewMode: 'docs',

From f481a4d4bb2f009f2c2ac1956758c6ae30043476 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Peter=20Dr=C3=A4xler?= <peter@draxler.ml>
Date: Sat, 14 Aug 2021 10:48:46 +0200
Subject: [PATCH 09/15] Update preview.js

---
 .storybook/preview.js | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.storybook/preview.js b/.storybook/preview.js
index 2666e4e3debfb..fef17237e88a9 100644
--- a/.storybook/preview.js
+++ b/.storybook/preview.js
@@ -10,7 +10,6 @@ export const parameters = {
     disable: true,
     expanded: true,
   },
-  viewMode: 'docs',
   docs: {
     source: {
       excludeDecorators: true,

From 09bc168996d3080716cc951f8c0714898caa35a9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Peter=20Dr=C3=A4xler?= <peter@draxler.ml>
Date: Wed, 18 Aug 2021 09:35:11 +0200
Subject: [PATCH 10/15] fix object spread

---
 packages/react-button/.storybook/preview.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react-button/.storybook/preview.js b/packages/react-button/.storybook/preview.js
index 509dbd0b6d66b..75f5ad3840b32 100644
--- a/packages/react-button/.storybook/preview.js
+++ b/packages/react-button/.storybook/preview.js
@@ -1,4 +1,4 @@
 import * as rootPreview from '../../../.storybook/preview';
 
 export const decorators = [...rootPreview.decorators];
-export const parameters = [...rootPreview.parameters];
+export const parameters = { ...rootPreview.parameters };

From d5f5ac0494e532bd05b44f1b7a6908da391a8b5f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Peter=20Dr=C3=A4xler?= <peter@draxler.ml>
Date: Thu, 19 Aug 2021 13:16:31 +0200
Subject: [PATCH 11/15] remove unused tmp-icons

---
 .../react-button/src/tmp-icons.stories.tsx    | 23 -------------------
 1 file changed, 23 deletions(-)
 delete mode 100644 packages/react-button/src/tmp-icons.stories.tsx

diff --git a/packages/react-button/src/tmp-icons.stories.tsx b/packages/react-button/src/tmp-icons.stories.tsx
deleted file mode 100644
index 0ea6cb55450b1..0000000000000
--- a/packages/react-button/src/tmp-icons.stories.tsx
+++ /dev/null
@@ -1,23 +0,0 @@
-import * as React from 'react';
-
-export const CalendarIcon = () => (
-  <span
-    role="presentation"
-    style={{
-      width: '1em',
-      height: '1em',
-    }}
-  >
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      viewBox="0 0 2048 2048"
-      style={{
-        height: '100%',
-        fill: 'currentColor',
-        verticalAlign: 'top',
-      }}
-    >
-      <path d="M768 768h128v128H768V768zm384 768h128v128h-128v-128zm384-768h128v128h-128V768zm-384 0h128v128h-128V768zm-384 256h128v128H768v-128zm-384 0h128v128H384v-128zm1152 0h128v128h-128v-128zm-384 0h128v128h-128v-128zm-384 256h128v128H768v-128zm-384 0h128v128H384v-128zm1152 0h128v128h-128v-128zm-384 0h128v128h-128v-128zm-384 256h128v128H768v-128zm-384 0h128v128H384v-128zM2048 128v1792H0V128h384V0h128v128h1024V0h128v128h384zM128 256v256h1792V256h-256v128h-128V256H512v128H384V256H128zm1792 1536V640H128v1152h1792z" />
-    </svg>
-  </span>
-);

From ec9c1daad3cb146d3e746eae6da963f750ec2591 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Peter=20Dr=C3=A4xler?= <peter@draxler.ml>
Date: Fri, 20 Aug 2021 13:57:34 +0200
Subject: [PATCH 12/15] move description to a separate file

---
 .../src/components/Button/Button.stories.tsx  |  9 ++++++
 .../src/components/Button/Button.tsx          | 28 -------------------
 .../components/Button/ButtonBestPractices.md  | 22 +++++++++++++++
 .../components/Button/ButtonDescription.md    |  9 ++++++
 4 files changed, 40 insertions(+), 28 deletions(-)
 create mode 100644 packages/react-button/src/components/Button/ButtonBestPractices.md
 create mode 100644 packages/react-button/src/components/Button/ButtonDescription.md

diff --git a/packages/react-button/src/components/Button/Button.stories.tsx b/packages/react-button/src/components/Button/Button.stories.tsx
index 7f898fa5ac2b6..cd05bce8a5af7 100644
--- a/packages/react-button/src/components/Button/Button.stories.tsx
+++ b/packages/react-button/src/components/Button/Button.stories.tsx
@@ -2,6 +2,8 @@ import * as React from 'react';
 import { Button, ButtonProps } from '../../Button';
 import { Meta } from '@storybook/react';
 import { CalendarMonth24Regular } from '@fluentui/react-icons';
+import descriptionMdx from './ButtonDescription.md';
+import bestPracticesMdx from './ButtonBestPractices.md';
 
 export const Default = (props: ButtonProps) => <Button {...props}>Button</Button>;
 
@@ -165,6 +167,13 @@ ButtonWithLongText.parameters = {
 export default {
   title: 'Components/Button',
   component: Button,
+  parameters: {
+    docs: {
+      description: {
+        component: descriptionMdx + '\n' + bestPracticesMdx,
+      },
+    },
+  },
   decorators: [
     Story => (
       <div style={{ display: 'flex', justifyContent: 'space-evenly' }}>
diff --git a/packages/react-button/src/components/Button/Button.tsx b/packages/react-button/src/components/Button/Button.tsx
index f095869d7bfb6..977aca323c896 100644
--- a/packages/react-button/src/components/Button/Button.tsx
+++ b/packages/react-button/src/components/Button/Button.tsx
@@ -6,34 +6,6 @@ import { useButtonStyles } from './useButtonStyles';
 
 /**
  * Buttons give people a way to trigger an action.
- *
- * They’re typically found in forms, dialog panels, and dialogs. Some buttons are specialized for particular tasks,
- * such as navigation, repeated actions, or presenting menus.
- *
- * See also:
- * [MenuButton](/?path=/docs/components-menubutton--menu-button-playground),
- * [ToggleButton](/?path=/docs/components-togglebutton--toggle-button-playground),
- * [CompoundButton](/?path=/docs/components-compoundbutton--compound-button-playground)
- *
- * ## Best practices
- * ### Layout
- * - For dialog boxes and panels, where people are moving through a sequence of screens, right-align buttons with the
- * container.
- * - For single-page forms and focused tasks, left-align buttons with the container.
- * - Always place the primary button on the left, the secondary button just to the right of it.
- * - Show only one primary button that inherits theme color at rest state. If there are more than two buttons with
- * equal priority, all buttons should have neutral backgrounds.
- * - Don't use a button to navigate to another place; use a link instead. The exception is in a wizard where "Back" and
- * "Next" buttons may be used.
- * - Don't place the default focus on a button that destroys data. Instead, place the default focus on the button that
- * performs the "safe act" and retains the content (such as "Save") or cancels the action (such as "Cancel").
- *
- * ### Content
- * - Use sentence-style capitalization—only capitalize the first word. For more info, see
- * [Capitalization](https://docs.microsoft.com/en-us/style-guide/capitalization) in the Microsoft Writing Style Guide.
- * - Make sure it's clear what will happen when people interact with the button. Be concise; usually a single verb
- * is best. Include a noun if there is any room for interpretation about what the verb means.
- * For example, "Delete folder" or "Create account".
  */
 export const Button: React.FunctionComponent<ButtonProps & React.RefAttributes<HTMLElement>> = React.forwardRef<
   HTMLElement,
diff --git a/packages/react-button/src/components/Button/ButtonBestPractices.md b/packages/react-button/src/components/Button/ButtonBestPractices.md
new file mode 100644
index 0000000000000..9cef31d0fd2a0
--- /dev/null
+++ b/packages/react-button/src/components/Button/ButtonBestPractices.md
@@ -0,0 +1,22 @@
+## Best practices
+
+### Layout
+
+- For dialog boxes and panels, where people are moving through a sequence of screens, right-align buttons with the
+  container.
+- For single-page forms and focused tasks, left-align buttons with the container.
+- Always place the primary button on the left, the secondary button just to the right of it.
+- Show only one primary button that inherits theme color at rest state. If there are more than two buttons with
+  equal priority, all buttons should have neutral backgrounds.
+- Don't use a button to navigate to another place; use a link instead. The exception is in a wizard where "Back" and
+  "Next" buttons may be used.
+- Don't place the default focus on a button that destroys data. Instead, place the default focus on the button that
+  performs the "safe act" and retains the content (such as "Save") or cancels the action (such as "Cancel").
+
+### Content
+
+- Use sentence-style capitalization—only capitalize the first word. For more info, see
+  [Capitalization](https://docs.microsoft.com/en-us/style-guide/capitalization) in the Microsoft Writing Style Guide.
+- Make sure it's clear what will happen when people interact with the button. Be concise; usually a single verb
+  is best. Include a noun if there is any room for interpretation about what the verb means.
+  For example, "Delete folder" or "Create account".
diff --git a/packages/react-button/src/components/Button/ButtonDescription.md b/packages/react-button/src/components/Button/ButtonDescription.md
new file mode 100644
index 0000000000000..87c03848d77df
--- /dev/null
+++ b/packages/react-button/src/components/Button/ButtonDescription.md
@@ -0,0 +1,9 @@
+Buttons give people a way to trigger an action.
+
+They’re typically found in forms, dialog panels, and dialogs. Some buttons are specialized for particular tasks,
+such as navigation, repeated actions, or presenting menus.
+
+See also:
+[MenuButton](/?path=/docs/components-menubutton--menu-button-playground),
+[ToggleButton](/?path=/docs/components-togglebutton--toggle-button-playground),
+[CompoundButton](/?path=/docs/components-compoundbutton--compound-button-playground)

From 3a1bd7c217328c09003429f8e403784f89267cfd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Peter=20Dr=C3=A4xler?= <peter@draxler.ml>
Date: Fri, 20 Aug 2021 15:59:48 +0200
Subject: [PATCH 13/15] code style

---
 packages/react-button/src/components/Button/Button.stories.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/react-button/src/components/Button/Button.stories.tsx b/packages/react-button/src/components/Button/Button.stories.tsx
index cd05bce8a5af7..49281423736de 100644
--- a/packages/react-button/src/components/Button/Button.stories.tsx
+++ b/packages/react-button/src/components/Button/Button.stories.tsx
@@ -170,7 +170,7 @@ export default {
   parameters: {
     docs: {
       description: {
-        component: descriptionMdx + '\n' + bestPracticesMdx,
+        component: [descriptionMdx, bestPracticesMdx].join('\n'),
       },
     },
   },

From baeaed98ac36012637bca700811ea9f2beb061bb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Peter=20Dr=C3=A4xler?= <peter@draxler.ml>
Date: Mon, 23 Aug 2021 14:31:03 +0200
Subject: [PATCH 14/15] add Markdown typing for typescript

---
 .../react-button/src/components/Button/Button.stories.tsx   | 6 +++---
 typings/custom-global/index.d.ts                            | 5 +++++
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/packages/react-button/src/components/Button/Button.stories.tsx b/packages/react-button/src/components/Button/Button.stories.tsx
index 49281423736de..0d6a4f1cf4a4b 100644
--- a/packages/react-button/src/components/Button/Button.stories.tsx
+++ b/packages/react-button/src/components/Button/Button.stories.tsx
@@ -2,8 +2,8 @@ import * as React from 'react';
 import { Button, ButtonProps } from '../../Button';
 import { Meta } from '@storybook/react';
 import { CalendarMonth24Regular } from '@fluentui/react-icons';
-import descriptionMdx from './ButtonDescription.md';
-import bestPracticesMdx from './ButtonBestPractices.md';
+import descriptionMd from './ButtonDescription.md';
+import bestPracticesMd from './ButtonBestPractices.md';
 
 export const Default = (props: ButtonProps) => <Button {...props}>Button</Button>;
 
@@ -170,7 +170,7 @@ export default {
   parameters: {
     docs: {
       description: {
-        component: [descriptionMdx, bestPracticesMdx].join('\n'),
+        component: [descriptionMd, bestPracticesMd].join('\n'),
       },
     },
   },
diff --git a/typings/custom-global/index.d.ts b/typings/custom-global/index.d.ts
index 3d5847fed6b6b..a1042f27e0f30 100644
--- a/typings/custom-global/index.d.ts
+++ b/typings/custom-global/index.d.ts
@@ -6,6 +6,11 @@ declare module '*.scss' {
   export default styles;
 }
 
+/**
+ * Generic typings for Markdown files.
+ */
+declare module '*.md';
+
 // These declarations are meant to represent the parts of Map/WeakMap/Set that exist in IE 11.
 // Therefore, some functionality (such as constructor parameters) is intentionally missing.
 

From 6650fc880ac3f5abd91de7685a62d5e3a286a244 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Peter=20Dr=C3=A4xler?= <peter@draxler.ml>
Date: Mon, 23 Aug 2021 18:04:55 +0200
Subject: [PATCH 15/15] add displayName to satisfy a lint rule

---
 packages/react-button/src/components/Button/Button.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/react-button/src/components/Button/Button.tsx b/packages/react-button/src/components/Button/Button.tsx
index 977aca323c896..157d95f9d99f5 100644
--- a/packages/react-button/src/components/Button/Button.tsx
+++ b/packages/react-button/src/components/Button/Button.tsx
@@ -17,3 +17,4 @@ export const Button: React.FunctionComponent<ButtonProps & React.RefAttributes<H
 
   return renderButton(state);
 });
+Button.displayName = 'Button';