Add migration docs

Author: pksjce

docs/content/drafts/Button2.mdx renamed to docs/content/Button.mdx

@@ -7,8 +7,6 @@ storybook: '/react/storybook?path=/story/composite-components-button2'
 description: Use button for the main actions on a page or form.
 ---
 
-import {Props} from '../../src/props'
-import {ComponentChecklist} from '../../src/component-checklist'
 import {Button, IconButton, LinkButton} from '@primer/react/drafts'
 
 ## Usage

docs/content/Buttons.mdx renamed to docs/content/deprecated/Buttons.mdx

@@ -6,6 +6,13 @@ source: https://github.com/primer/react/blob/main/src/Button
 storybook: '/react/storybook?path=/story/composite-components-button--default-button'
 ---
 
+## Deprecation
+
+Use [Button](/Button) instead.
+
+For more info on the changes, have a look at the migration guide.
+[Button migration guide](/migration-guide/Button)
+
 `Button` is used for actions, like in forms, while `Link` is used for destinations, or moving from one page to another.
 
 In special cases where you'd like to use a `<a>` styled like a Button, use `<Button as='a'>` and provide an `href`.

docs/content/migration-guide/Button.mdx

@@ -0,0 +1,99 @@
+---
+title: Button migration guide
+---
+
+## Summary
+
+The new set of Button components brings a much needed update.
+The older version was a set of seven different components. Each variant of the component had a separate component.
+The guidelines to put in icons inside the buttons was also vague. With the new components, we now have a great guidance for common button usage.
+
+## Change list
+
+### Button variants
+
+We now support a variant property which takes values `primary`, `invisible`, `outline` and `danger`
+
+#### Before
+
+```jsx
+import {ButtonPrimary, ButtonInvisible, ButtonOutline, ButtonDanger} from '@primer/react'
+
+  <ButtonPrimary>Primary Button</ButtonPrimary>
+
+  <ButtonInvisible>Invisible Button</ButtonInvisible>
+
+  <ButtonOutline>Outline Button</ButtonOutline>
+
+  <ButtonDanger>Danger Button</ButtonDanger>
+
+```
+
+#### After
+
+```jsx
+import {Button} from '@primer/react'
+
+  <Button variant="primary">Primary Button</Button>
+
+  <Button variant="invisible">Invisible Button</Button>
+
+  <Button variant="outline">Outline Button</Button>
+
+  <Button variant="danger">Danger Button</Button>
+
+```
+
+### Leading and Trailing icons
+
+In the previous component, we allowed icon components to be direct children. This results in a lot of custom styling for the icon components.
+In the new one, we now have `leadinIcon` and `trailingIcon` properties.
+
+#### Before
+
+```jsx
+<Button>
+  <SearchIcon />
+  Search
+</Button>
+```
+
+#### After
+
+```jsx
+<Button leadingIcon={SearchIcon}>Search</Button>
+```
+
+### Icon buttons
+
+Icon only buttons are common usages in products. So we now have a component for the specific usecase
+
+#### Before
+
+```jsx
+<Button>
+  <XIcon />
+</Button>
+```
+
+#### After
+
+```jsx
+<IconButton aria-label="Close button" icon={XIcon} />
+```
+
+### Size property
+
+Earlier we used `variant` to mean size property. Now we have a new property called `size` which is more semantically correct.
+
+#### Before
+
+```jsx
+<Button variant="small">Small button</Button>
+```
+
+#### After
+
+```jsx
+<Button size="small">Small button</Button>
+```