Docs: Add migration guidance for icons

.changeset/little-radios-sparkle.md

@@ -0,0 +1,2 @@
+---
+---

packages/components/codemods/upgradeIconV1/getNewIconPropsFromOldIconName.ts

@@ -5,7 +5,7 @@ import { type StringSuggestions } from '~components/types/StringSuggestions'
 // `undefined` means the icon has no usage, thus is not available in the new icon set
 type NewIconProps = { name: IconNames; isFilled?: boolean } | undefined
 
-const iconMap = new Map<keyof typeof OLD_ICONS, NewIconProps>([
+export const iconMap = new Map<keyof typeof OLD_ICONS, NewIconProps>([
   ['AcademyIcon', { name: 'school' }],
   ['ActionOffIcon', undefined],
   ['ActionOffWhiteIcon', undefined],

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

@@ -0,0 +1,28 @@
+import { Canvas, Meta, Controls, Story } from '@storybook/blocks'
+import { ResourceLinks, KAIOInstallation, LinkTo } from '~storybook/components'
+import * as IconStories from './Icon.docs.stories'
+
+<Meta title="Components/Icon/Icon (Future)/Migration Guide" />
+
+# Icon Migration Guide
+
+This is a short guide to assist in migration from the old to new Icon component.
+
+## Codemod
+
+To assist in migration we have created the `upgradeiconv1` codemod. This will loop through the given directory and update all instances of Icon to the latest implementation. You can refer to this [README](https://github.com/cultureamp/kaizen-design-system/blob/main/packages/components/codemods/README.md#upgradeiconv1) on how to run this within your repository.
+
+For more information on the changes to the API, we recommend referring the <LinkTo pageId="components-icon-icon-future-api-specification--docs">API Specification</LinkTo>.
+
+## Changes to Icon exportNames
+
+The following table outlines the changes to the Icons names and whether the new `isFilled` prop is required. This can be used if you are manually migrating components.
+
+Where `N/A` is shown, this indicates that an equivalent icon does not exist or has been made redundant by the new API, ie:
+
+- `ActionOffIcon` is not needed as the new `ActionOnIcon` (`flash_on`) can be used with the `isFilled` to handle the toggled states.
+- `ActionOffIconActionOffWhiteIcon` is not needed as the API allows for color to be set via `className` or inherited via it's parent element.
+
+You will need to discuss alternative with your design team or reach out in the #help_design_system channel if an equivalent icon does not exist.
+
+<Story of={IconStories.IconTableComparison} />

packages/components/src/__rc__/Icon/_docs/Icon.docs.stories.tsx

@@ -15,6 +15,7 @@ import { ToggleSwitchField } from '~components/ToggleSwitch'
 import { Button } from '~components/__rc__/Button'
 import { Tag } from '~components/__rc__/Tag'
 import { StickerSheet } from '~storybook/components/StickerSheet'
+import { iconMap } from '../../../../codemods/upgradeIconV1/getNewIconPropsFromOldIconName'
 import { iconDefaultSet } from '../constants'
 import { Icon } from '../index'
 import imgInterfaceDont from './assets/interface-dont.png'
@@ -476,3 +477,40 @@ export const TooltipDont: Story = {
     />
   ),
 }
+
+export const IconTableComparison: Story = {
+  render: () => {
+    return (
+      <TableContainer>
+        <TableHeader>
+          <TableRow>
+            <TableHeaderRowCell width={4 / 12} labelText="Old name" />
+            <TableHeaderRowCell width={4 / 12} labelText="New name" />
+            <TableHeaderRowCell width={4 / 12} labelText="isFilled" />
+          </TableRow>
+        </TableHeader>
+        {Array.from(iconMap).map(([key, value]) => (
+          <TableCard key={key}>
+            <TableRow>
+              <TableRowCell width={4 / 12}>
+                <Text tag="div" variant="body">
+                  {key}
+                </Text>
+              </TableRowCell>
+              <TableRowCell width={4 / 12}>
+                <Text tag="div" variant="body">
+                  {value?.name ?? 'N/A'}
+                </Text>
+              </TableRowCell>
+              <TableRowCell width={4 / 12}>
+                <Text tag="div" variant="body">
+                  {value?.isFilled ? 'true' : value?.name ? 'false' : 'N/A'}
+                </Text>
+              </TableRowCell>
+            </TableRow>
+          </TableCard>
+        ))}
+      </TableContainer>
+    )
+  },
+}