add button migration guide and update outputs for codemod

packages/components/bin/codemod.sh

@@ -31,6 +31,8 @@ echo ""
 
 if npx tsx@latest $CODEMOD_PATH $TARGET_DIR; then
   echo "Codemod '$codemodFileName' completed successfully in directory '$transformDir'"
+  echo "---"
+  echo "Run linting and prettier to correct issues with re-writes"
 else
   echo "Codemod '$codemodFileName' could not be run in '$TARGET_DIR'"
   exit 1

packages/components/codemods/upgradeV1Buttons/index.ts

@@ -2,6 +2,8 @@ import { transformComponentsInDir } from '../utils'
 import { upgradeV1Buttons } from './upgradeV1Buttons'
 
 const run = (): void => {
+  console.log('It is recommended that the `upgradeIconV1` codemod be run prior to this')
+  console.log('---')
   console.log('~(-_- ~) Running V1 Buttons upgrade (~ -_-)~')
 
   const targetDir = process.argv[2]

packages/components/src/__rc__/Button/_docs/Button--migration-guide.mdx

@@ -0,0 +1,58 @@
+import { Canvas, Meta, Controls, Story } from '@storybook/blocks'
+import { ResourceLinks, KAIOInstallation } from '~storybook/components'
+
+<Meta title="Components/Button/Button (v3)/Migration Guide" />
+
+# Button Migration Guide
+
+This is a short guide to assist in migration from the old to new `Button` and `LinkButton` component.
+
+## Key API differences
+
+Below is a list of notable changes when migrating to the new `Button` and `LinkButton` component:
+
+- `label` is now handled as `Children` and does not have a specific prop.
+- Variants, such as `primary` and `secondary`, are now controlled as by the single `variant` prop.
+- `onClick` and other event handlers now reflect the RAC event ecosystems, ie: `onPress`.
+  - You can see more about the RAC event ecosystem [here](https://react-spectrum.adobe.com/react-aria/Button.html#events).
+- `Button` and `LinkButton` now exist as separate components.
+  - The intent is to more closely align to the semantic roles of an anchor or button and should be used accordingly.
+- `LinkButton` handles native navigation via `href` out of the box but additional config can be used to allow for client side routing - [see here](/docs/components-linkbutton-api-specification--docs#client-side-routing).
+  - `onPress` can still be used in place of `onClick` for pushing to routers.
+- `IconButton` has been superseded by icon props and the [icon-only pattern](/docs/components-button-button-v3-api-specification--docs#icon-only-button-and-hashiddenlabel).
+- `working` props has been updated to `pending` to better reflect the state of the button.
+- `badge` prop has been removed and should be handled within the `Children` where required.
+- `size` props have been adjusted to include `small`, `medium` and `large`.
+- Styles have been consolidate to align with modern designs and variants like `destructive` have been removed.
+  - The codemod will remap these to the relative variants.
+- Reversed styles should be handled by the `ReversedColors` Provider but for ease of migration can use the `isReversed` prop.
+
+## Codemod
+
+To assist in migration we have created the `upgradeV1Buttons` codemod.
+
+This will loop through the given directory and update all instances of Button to the latest implementation. You can refer to this [README](https://github.com/cultureamp/kaizen-design-system/blob/main/packages/components/codemods/README.md#kaizen-codemods) on how to run kaizen codemods using the CLI within your repository, ie:
+
+```bash
+pnpm kaizen-codemod src upgradeV1Buttons
+```
+
+### Pre-requisites
+
+It is also recommended that the `upgradeIconV1` codemod is run before `upgradeV1Buttons` to ensure that all icons are updated to the new `Icon` component that uses the Material icons CDN. Seem more about this [here](/docs/components-icon-icon-future-api-specification--docs#set-up).
+
+### Potential gotchas
+
+If you're facing any issues not captured below, reach out to the [#help_design_system](https://cultureamp.slack.com/archives/C0189KBPM4Y) channel on Slack.
+
+### `icon` props and sizing
+
+While the `icon` prop supports any `JSX` element, only the latest [Icon component](/docs/components-icon-icon-future-api-specification--docs) will be able to handle relative sizing and spacing automatically within the Button. We recommend running the `upgradeIconV1` codemod before this to convert all icons to the latest implementation. See the guidance here on using the [Material Icons CDN](/docs/guides-app-starter--docs#5-link-to-google-material-symbols-cdn).
+
+### `component` render props and intentional type errors
+
+Based off Metabase queries, `component` render props is used in consuming repositories to wrap Button content with a routing solution, such as NextJS's `Link` component. To ensure a safe migration, the codemod will update any usages to a `LinkButton` with the `component` prop still passed in. This will cause an intentional type error to provide feedback and make it easier to find in the codebase for a manual update. This should be able to be converted to use client side routing by following the [LinkButton API docs](https://cultureamp.design/?path=/docs/components-linkbutton-api-specification--docs).
+
+## More information
+
+For more information on the about each of the new API's, we recommend referring the [Button](/docs/components-button-button-v3-api-specification--docs) or [LinkButton](/docs/components-linkbutton-api-specification--docs) API specifications.