feat: Allow Button to display an icon without a label

packages/css/src/components/button/button.scss

@@ -95,3 +95,17 @@
     color: var(--ams-button-tertiary-hover-color);
   }
 }
+
+.ams-button--icon-only {
+  padding-block: var(--ams-button-icon-only-padding-block);
+  padding-inline: var(--ams-button-icon-only-padding-inline);
+}
+
+// TODO: Proposition
+// .ams-button--icon-start {
+//   padding-inline-start: var(--ams-button-icon-start-padding-inline-start);
+// }
+
+// .ams-button--icon-end {
+//   padding-inline-end: var(--ams-button-icon-end-padding-inline-end);
+// }

packages/react/src/Button/Button.test.tsx

@@ -1,3 +1,4 @@
+import { ShareIcon } from '@amsterdam/design-system-react-icons'
 import { render, screen } from '@testing-library/react'
 import '@testing-library/jest-dom'
 import { createRef } from 'react'
@@ -104,10 +105,22 @@ describe('Button', () => {
   it('is able to pass a React ref', () => {
     const ref = createRef<HTMLButtonElement>()
 
-    const { container } = render(<Button ref={ref} />)
+    const { container } = render(<Button ref={ref}>Click me!</Button>)
 
     const button = container.querySelector(':only-child')
 
     expect(ref.current).toBe(button)
   })
+
+  it('renders a button with an icon', () => {
+    render(<Button icon={ShareIcon}>Share</Button>)
+
+    const button = screen.getByRole('button', {
+      name: 'Share',
+    })
+
+    expect(button).toBeInTheDocument()
+    const icon = button.querySelector('.ams-icon')
+    expect(icon).toBeInTheDocument()
+  })
 })

packages/react/src/Button/Button.tsx

@@ -6,26 +6,31 @@
 import clsx from 'clsx'
 import { forwardRef } from 'react'
 import type { ButtonHTMLAttributes, ForwardedRef, PropsWithChildren } from 'react'
+import { Icon } from '../Icon'
 
 export type ButtonProps = {
   /** The level of prominence. Use a primary button only once per page or section. */
   variant?: 'primary' | 'secondary' | 'tertiary'
+  icon?: Function
+  iconPosition?: 'start' | 'only'
 } & PropsWithChildren<ButtonHTMLAttributes<HTMLButtonElement>>
 
 export const Button = forwardRef(
   (
-    { children, className, type, disabled, variant = 'primary', ...restProps }: ButtonProps,
+    { children, className, disabled, icon, iconPosition, type, variant = 'primary', ...restProps }: ButtonProps,
     ref: ForwardedRef<HTMLButtonElement>,
   ) => {
     return (
       <button
         {...restProps}
         ref={ref}
         disabled={disabled}
-        className={clsx('ams-button', `ams-button--${variant}`, className)}
+        className={clsx('ams-button', `ams-button--${variant}`, `ams-button--icon-${iconPosition}`, className)}
         type={type || 'button'}
       >
-        {children}
+        {icon && (iconPosition === 'start' || iconPosition === 'only') && <Icon svg={icon} size="level-5" square />}
+        {icon && iconPosition === 'only' ? <span className="ams-visually-hidden">{children}</span> : children}
+        {icon && !iconPosition && <Icon svg={icon} size="level-5" square />}
       </button>
     )
   },

proprietary/tokens/src/components/ams/button.tokens.json

@@ -56,6 +56,16 @@
           "background-color": { "value": "transparent" },
           "color": { "value": "{ams.color.neutral-grey2}" }
         }
+      },
+      "icon-only": {
+        "padding-block": { "value": "{ams.space.sm}" },
+        "padding-inline": { "value": "{ams.space.sm}" }
+      },
+      "icon-start": {
+        "padding-inline-start": { "value": "{ams.space.sm}" }
+      },
+      "icon-end": {
+        "padding-inline-end": { "value": "{ams.space.sm}" }
       }
     }
   }

storybook/src/components/Button/Button.docs.mdx

@@ -16,28 +16,45 @@ import README from "../../../../packages/css/src/components/button/README.md?raw
 
 ### Primary
 
-The most important call-to-action.
-One primary Button may be used per screen.
+A primary button draws attention to the most important call to action.
+Only one primary Button should be used per screen or, in applications, large section.
 
 <Canvas of={ButtonStories.Primary} />
 
 ### Secondary
 
-Use the secondary Button for less prominent calls to action.
-It is possible to use more than 1 secondary Button.
+The secondary is the default type of Button.
 
 <Canvas of={ButtonStories.Secondary} />
 
 ### Tertiary
 
-Use tertiary Buttons for unimportant calls to action – as many as necessary.
+Tertiary buttons can be used to distinguish their importance from secondary buttons.
+They are also a good choice for buttons with an icon only.
 
 <Canvas of={ButtonStories.Tertiary} />
 
-### With icon
+### With an icon
+
+Add an icon if it makes it easier or faster to understand its purpose.
+The icon will appear after the label.
 
 <Canvas of={ButtonStories.WithIcon} />
 
+### With an icon at the start
+
+The icon can also appear before the label.
+
+<Canvas of={ButtonStories.WithIconAtStart} />
+
+### With an icon only
+
+A button can even consist of an icon only.
+Do this only for icons that are universally recognized.
+You must still provide a label – it will be used to make the button accessible.
+
+<Canvas of={ButtonStories.WithIconOnly} />
+
 ### Text wrapping
 
 Keep in mind that the label may occasionally wrap over multiple lines:

storybook/src/components/Button/Button.stories.tsx

@@ -3,7 +3,6 @@
  * Copyright Gemeente Amsterdam
  */
 
-import { Icon } from '@amsterdam/design-system-react'
 import { Button } from '@amsterdam/design-system-react/src'
 import { ShareIcon } from '@amsterdam/design-system-react-icons'
 import { Meta, StoryObj } from '@storybook/react'
@@ -12,18 +11,17 @@ const meta = {
   title: 'Components/Buttons/Button',
   component: Button,
   args: {
-    children: 'Button label',
-    variant: 'primary',
+    children: 'Versturen',
     disabled: false,
+    variant: 'primary',
   },
   argTypes: {
-    children: {
-      description: 'The text for the label and/or an icon.',
-      table: { disable: false },
-    },
     disabled: {
       description: 'Prevents interaction. Avoid if possible.',
     },
+    icon: {
+      table: { disable: true },
+    },
   },
 } satisfies Meta<typeof Button>
 
@@ -35,24 +33,39 @@ export const Primary: Story = {}
 
 export const Secondary: Story = {
   args: {
+    children: 'Annuleren',
     variant: 'secondary',
   },
 }
 
 export const Tertiary: Story = {
   args: {
+    children: 'Terug',
     variant: 'tertiary',
   },
 }
 
 export const WithIcon: Story = {
   args: {
-    children: ['Button label', <Icon key="icon" svg={ShareIcon} size="level-5" />],
+    children: 'Delen',
+    icon: ShareIcon,
   },
-  argTypes: {
-    children: {
-      table: { disable: true },
-    },
+}
+
+export const WithIconAtStart: Story = {
+  args: {
+    children: 'Delen',
+    icon: ShareIcon,
+    iconPosition: 'start',
+  },
+}
+
+export const WithIconOnly: Story = {
+  args: {
+    children: 'Delen',
+    icon: ShareIcon,
+    iconPosition: 'only',
+    variant: 'tertiary',
   },
 }