move doc to separate migration guide and add more context and notes

packages/components/src/__rc__/Icon/_docs/Icon--api-specification.mdx

@@ -103,9 +103,3 @@ Whilst you have access to all Material Symbols, the following icons match the de
 Tip: Click on the icon you want for a quick copy!
 
 <Story of={IconStories.DefaultIconSet} />
-
-## Migrating from Icon v1
-
-To migrate from the previous implementation of the `Icon` component, either run the [upgradeiconv1 codemod](https://github.com/cultureamp/kaizen-design-system/blob/main/packages/components/codemods/README.md#upgradeiconv1) within your repo or use the comparison table below to replace the components manually.
-
-<Story of={IconStories.IconTableComparison} />

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

@@ -1,7 +1,6 @@
 import React, { useState } from 'react'
 import { type Meta, type StoryObj } from '@storybook/react'
 import classnames from 'classnames'
-import { Collapsible } from '~components/Collapsible'
 import { InlineNotification } from '~components/Notification'
 import {
   TableCard,
@@ -482,38 +481,36 @@ export const TooltipDont: Story = {
 export const IconTableComparison: Story = {
   render: () => {
     return (
-      <Collapsible title="Icon name comparison table">
-        <TableContainer>
-          <TableHeader>
+      <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>
-              <TableHeaderRowCell width={4 / 12} labelText="Old name" />
-              <TableHeaderRowCell width={4 / 12} labelText="New name" />
-              <TableHeaderRowCell width={4 / 12} labelText="isFilled" />
+              <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>
-          </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' : 'false'}
-                  </Text>
-                </TableRowCell>
-              </TableRow>
-            </TableCard>
-          ))}
-        </TableContainer>
-      </Collapsible>
+          </TableCard>
+        ))}
+      </TableContainer>
     )
   },
 }