From ae661604970c8472a8d6cd06ddf63dab1ac41446 Mon Sep 17 00:00:00 2001
From: Charles de Dreuille <charles.dedreuille@gmail.com>
Date: Wed, 18 Jun 2025 12:41:08 +0100
Subject: [PATCH] Improve docs

Signed-off-by: Charles de Dreuille <charles.dedreuille@gmail.com>
---
 .../src/content/components/button.props.ts    |  3 ++
 .../src/content/components/icon-button.mdx    | 13 +++++
 .../content/components/icon-button.props.ts   | 29 +++++++----
 .../IconButton/IconButton.stories.tsx         | 50 ++++++-------------
 4 files changed, 52 insertions(+), 43 deletions(-)

diff --git a/canon-docs/src/content/components/button.props.ts b/canon-docs/src/content/components/button.props.ts
index 02ed9e9134..ef72a70596 100644
--- a/canon-docs/src/content/components/button.props.ts
+++ b/canon-docs/src/content/components/button.props.ts
@@ -14,6 +14,9 @@ export const buttonPropDefs: Record<string, PropDef> = {
     default: 'medium',
     responsive: true,
   },
+  iconStart: { type: 'enum', values: ['ReactNode'], responsive: false },
+  iconEnd: { type: 'enum', values: ['ReactNode'], responsive: false },
+  children: { type: 'enum', values: ['ReactNode'], responsive: false },
   ...classNamePropDefs,
   ...stylePropDefs,
 };
diff --git a/canon-docs/src/content/components/icon-button.mdx b/canon-docs/src/content/components/icon-button.mdx
index 80e7e5a46d..d8eb3beab2 100644
--- a/canon-docs/src/content/components/icon-button.mdx
+++ b/canon-docs/src/content/components/icon-button.mdx
@@ -10,6 +10,7 @@ import {
   iconButtonSizesSnippet,
   iconButtonDisabledSnippet,
   iconButtonResponsiveSnippet,
+  iconButtonAsLinkSnippet,
 } from './icon-button.props';
 import { ComponentInfos } from '@/components/ComponentInfos';
 
@@ -77,3 +78,15 @@ Here's a view when buttons are disabled.
 Here's a view when buttons are responsive.
 
 <CodeBlock code={iconButtonResponsiveSnippet} />
+
+### As Link
+
+You can use the `as` prop to make a button act as a link.
+
+<Snippet
+  align="center"
+  py={4}
+  open
+  preview={<IconButtonSnippet story="AsLink" />}
+  code={iconButtonAsLinkSnippet}
+/>
diff --git a/canon-docs/src/content/components/icon-button.props.ts b/canon-docs/src/content/components/icon-button.props.ts
index 8fdfaba6b9..9e3a2818fe 100644
--- a/canon-docs/src/content/components/icon-button.props.ts
+++ b/canon-docs/src/content/components/icon-button.props.ts
@@ -17,7 +17,7 @@ export const iconButtonPropDefs: Record<string, PropDef> = {
     default: 'medium',
     responsive: true,
   },
-  icon: { type: 'enum', values: 'icon', responsive: false },
+  icon: { type: 'enum', values: ['ReactNode'], responsive: false },
   ...classNamePropDefs,
   ...stylePropDefs,
 };
@@ -27,20 +27,31 @@ export const iconButtonUsageSnippet = `import { IconButton } from '@backstage/ca
 <IconButton />`;
 
 export const iconButtonDefaultSnippet = `<Flex align="center">
-  <IconButton icon="cloud" variant="primary" />
-  <IconButton icon="cloud" variant="secondary" />
+  <IconButton icon={<Icon name="cloud" />} variant="primary" />
+  <IconButton icon={<Icon name="cloud" />} variant="secondary" />
 </Flex>`;
 
 export const iconButtonVariantsSnippet = `<Flex align="center">
-  <IconButton icon="cloud" variant="primary" />
-  <IconButton icon="cloud" variant="secondary" />
+  <IconButton icon={<Icon name="cloud" />} variant="primary" />
+  <IconButton icon={<Icon name="cloud" />} variant="secondary" />
 </Flex>`;
 
 export const iconButtonSizesSnippet = `<Flex align="center">
-  <IconButton icon="cloud" size="small" />
-  <IconButton icon="cloud" size="medium" />
+  <IconButton icon={<Icon name="cloud" />} size="small" />
+  <IconButton icon={<Icon name="cloud" />} size="medium" />
 </Flex>`;
 
-export const iconButtonDisabledSnippet = `<IconButton icon="cloud" disabled />`;
+export const iconButtonDisabledSnippet = `<IconButton icon={<Icon name="cloud" />} disabled />`;
 
-export const iconButtonResponsiveSnippet = `<IconButton icon="cloud" variant={{ initial: 'primary', lg: 'secondary' }} />`;
+export const iconButtonResponsiveSnippet = `<IconButton icon={<Icon name="cloud" />} variant={{ initial: 'primary', lg: 'secondary' }} />`;
+
+export const iconButtonAsLinkSnippet = `// Using the \`as\` prop
+<IconButton
+  as="a"
+  href="https://canon.backstage.io"
+  target="_blank"
+  icon={<Icon name="cloud" />}
+/>
+
+// Using a custom component
+<IconButton as={Link} to="/" icon={<Icon name="cloud" />} />`;
diff --git a/packages/canon/src/components/IconButton/IconButton.stories.tsx b/packages/canon/src/components/IconButton/IconButton.stories.tsx
index d74e7ebf1a..110db0aa89 100644
--- a/packages/canon/src/components/IconButton/IconButton.stories.tsx
+++ b/packages/canon/src/components/IconButton/IconButton.stories.tsx
@@ -40,58 +40,44 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
-  args: {
-    icon: <Icon name="cloud" />,
-  },
+  render: args => <IconButton {...args} icon={<Icon name="cloud" />} />,
 };
 
 export const Variants: Story = {
-  args: {
-    ...Default.args,
-  },
   render: args => (
     <Flex align="center" gap="2">
-      <IconButton {...args} variant="primary" />
-      <IconButton {...args} variant="secondary" />
+      <IconButton {...args} icon={<Icon name="cloud" />} variant="primary" />
+      <IconButton {...args} icon={<Icon name="cloud" />} variant="secondary" />
     </Flex>
   ),
 };
 
 export const Sizes: Story = {
-  args: {
-    icon: <Icon name="cloud" />,
-  },
   render: args => (
     <Flex align="center" gap="2">
-      <IconButton {...args} size="small" />
-      <IconButton {...args} size="medium" />
+      <IconButton {...args} icon={<Icon name="cloud" />} size="small" />
+      <IconButton {...args} icon={<Icon name="cloud" />} size="medium" />
     </Flex>
   ),
 };
 
 export const Disabled: Story = {
-  args: {
-    icon: <Icon name="cloud" />,
-    disabled: true,
-    'aria-label': 'Cloud icon button',
-  },
+  args: { disabled: true },
   render: args => (
     <Flex direction="row" gap="2">
-      <IconButton {...args} variant="primary" />
-      <IconButton {...args} variant="secondary" />
+      <IconButton {...args} icon={<Icon name="cloud" />} variant="primary" />
+      <IconButton {...args} icon={<Icon name="cloud" />} variant="secondary" />
     </Flex>
   ),
 };
 
 export const AsLink: Story = {
-  render: () => (
-    <IconButton
-      as="a"
-      href="https://canon.backstage.io"
-      target="_blank"
-      icon={<Icon name="cloud" />}
-    />
-  ),
+  args: {
+    as: 'a',
+    href: 'https://canon.backstage.io',
+    target: '_blank',
+  },
+  render: args => <IconButton {...args} icon={<Icon name="cloud" />} />,
 };
 
 export const AsComponent: Story = {
@@ -106,8 +92,6 @@ export const AsComponent: Story = {
 
 export const Responsive: Story = {
   args: {
-    icon: <Icon name="cloud" />,
-    'aria-label': 'Cloud icon button',
     variant: {
       initial: 'primary',
       sm: 'secondary',
@@ -117,15 +101,12 @@ export const Responsive: Story = {
       sm: 'medium',
     },
   },
+  render: args => <IconButton {...args} icon={<Icon name="cloud" />} />,
 };
 
 const variants: string[] = ['primary', 'secondary'];
 
 export const Playground: Story = {
-  args: {
-    icon: <Icon name="cloud" />,
-    'aria-label': 'Cloud icon button',
-  },
   render: args => (
     <Flex direction="column">
       {variants.map(variant => (
@@ -137,6 +118,7 @@ export const Playground: Story = {
                 {...args}
                 variant={variant as IconButtonProps<any>['variant']}
                 size={size as IconButtonProps<any>['size']}
+                icon={<Icon name="cloud" />}
               />
               <IconButton
                 {...args}