docs(IconButton): update public documentation + prop API [F36-1540] (#…

…2940)

* docs(IconButton): update public documentation + prop API

* chore: add changelog

* docs: adjust path to prevent broken link-check

* docs(IconButton): adjust the tooltip section

* chore: update changelog

.changeset/witty-chefs-itch.md

@@ -0,0 +1,6 @@
+---
+"@contentful/f36-website": patch
+"@contentful/f36-button": patch
+---
+
+docs(IconButton): update public documentation + prop API

packages/components/button/examples/IconButtonSizesExample.tsx

@@ -0,0 +1,30 @@
+import React from 'react';
+import { IconButton, Stack } from '@contentful/f36-components';
+import { CalendarIcon } from '@contentful/f36-icons';
+
+export default function IconButtonExample() {
+  return (
+    <Stack flexDirection="column">
+      <Stack>
+        <IconButton
+          size="small"
+          variant="secondary"
+          aria-label="Select the date"
+          icon={<CalendarIcon size="tiny" />}
+        />
+        <IconButton
+          size="medium"
+          variant="secondary"
+          aria-label="Select the date"
+          icon={<CalendarIcon size="tiny" />}
+        />
+        <IconButton
+          size="large"
+          variant="secondary"
+          aria-label="Select the date"
+          icon={<CalendarIcon size="tiny" />}
+        />
+      </Stack>
+    </Stack>
+  );
+}

packages/components/button/examples/IconButtonTooltipExample.tsx

@@ -0,0 +1,41 @@
+import React from 'react';
+import { IconButton, Flex, Stack } from '@contentful/f36-components';
+import { css } from 'emotion';
+import tokens from '@contentful/f36-tokens';
+import { FormatBoldIcon, FormatItalicIcon } from '@contentful/f36-icons';
+
+export default function IconButtonTooltipExample() {
+  const styles = {
+    editorToolbarContainer: css({
+      backgroundColor: tokens.gray200,
+      borderRadius: tokens.borderRadiusMedium,
+    }),
+  };
+  return (
+    <Flex
+      justifyContent="space-between"
+      className={styles.editorToolbarContainer}
+      padding="spacingXs"
+    >
+      <Stack spacing="spacingXs">
+        <IconButton
+          aria-label="Toggle bold"
+          icon={<FormatBoldIcon />}
+          variant="transparent"
+          size="small"
+          withTooltip
+          tooltipProps={{ content: 'Bold' }}
+        />
+
+        <IconButton
+          aria-label="Toggle italic"
+          icon={<FormatItalicIcon />}
+          variant="transparent"
+          size="small"
+          withTooltip
+          tooltipProps={{ content: 'Italic' }}
+        />
+      </Stack>
+    </Flex>
+  );
+}

packages/components/button/examples/IconButtonExample.tsx → packages/components/button/examples/IconButtonVariationsExample.tsx

@@ -7,45 +7,29 @@ export default function IconButtonExample() {
     <Stack flexDirection="column">
       <Stack>
         <IconButton
-          variant="secondary"
+          variant="primary"
           aria-label="Select the date"
           icon={<CalendarIcon />}
         />
         <IconButton
-          variant="transparent"
+          variant="secondary"
           aria-label="Select the date"
           icon={<CalendarIcon />}
         />
         <IconButton
-          variant="primary"
+          variant="positive"
           aria-label="Select the date"
           icon={<CalendarIcon />}
         />
         <IconButton
-          variant="primary"
+          variant="negative"
           aria-label="Select the date"
           icon={<CalendarIcon />}
-          tooltipProps={{ content: 'Select the date' }}
         />
-      </Stack>
-      <Stack>
         <IconButton
-          size="small"
-          variant="secondary"
-          aria-label="Select the date"
-          icon={<CalendarIcon size="tiny" />}
-        />
-        <IconButton
-          size="small"
           variant="transparent"
           aria-label="Select the date"
-          icon={<CalendarIcon size="tiny" />}
-        />
-        <IconButton
-          size="small"
-          variant="primary"
-          aria-label="Select the date"
-          icon={<CalendarIcon size="tiny" />}
+          icon={<CalendarIcon />}
         />
       </Stack>
     </Stack>

packages/components/button/src/IconButton/IconButton.tsx

@@ -19,12 +19,12 @@ import {
 type WithTooltipOrNot =
   | {
       /**
-       * Triggers, wheter or not to render the tooltip
+       * Wrap the IconButton with a Tooltip to provide users with additional context about its purpose when they hover over it
        */
       withTooltip?: boolean;
 
       /**
-       * A tooltipProps attribute used to conditionally render the tooltip around root element
+       * The tooltip properties to be passed to the Tooltip component wrapping the IconButton
        */
       tooltipProps?: CommonProps &
         WithEnhancedContent &
@@ -86,7 +86,7 @@ function _IconButton<
 
   const styles = getStyles({ size, density });
 
-  const iconButtton = (
+  const iconButton = (
     <Button
       testId={testId}
       ref={ref}
@@ -109,12 +109,12 @@ function _IconButton<
 
     return (
       <Tooltip content={content} showDelay={showDelay} {...otherTooltipProps}>
-        {iconButtton}
+        {iconButton}
       </Tooltip>
     );
   }
 
-  return iconButtton;
+  return iconButton;
 }
 
 _IconButton.displayName = 'IconButton';

packages/components/button/src/IconButton/README.mdx

@@ -9,9 +9,9 @@ typescript: ./IconButton.tsx
 storybook: 'https://f36-storybook.contentful.com/?path=/story/components-button-iconbutton--basic'
 ---
 
-Start actions, such as "Lock" or "Delete".
+It represents a simple, familiar action that uses only an icon.
 
-The button meaning is only represented with an icon. Use it only with icons users are familiar with from previous experience in other products.
+Only use icon buttons with universally recognized icons that users are likely familiar with from other products or contexts. Icon buttons are best suited for simple, frequently used, or contextually clear actions, such as closing a window or deleting an item. Use them when screen space is limited or complementing a more prominent interface action.
 
 ## Import
 
@@ -23,23 +23,33 @@ import { IconButton } from '@contentful/f36-button';
 
 ## Examples
 
-### Sizes and Variations
+Variants, sizes, and states match those of the [Button](./button) component.
 
-You need to pass an [Icon component](../components/icon) you want to render to the `icon` prop, you may also provide `variant` and `size` to the icon.
+### Variations
 
-```jsx file=../../examples/IconButtonExample.tsx
+- **Primary** - For the most important actions in a scenario. While icon buttons can technically be styled as primary, they’re not recommended for primary actions due to their limited clarity compared to labeled buttons.
+- **Secondary** - For secondary actions, the most commonly used button type.
+- **Positive** - When the action has a positive connotation.
+- **Negative** - For destructive actions - when something can't be undone. For example, deleting entities.
+- **Transparent** - For having an unstyled button. Use this only on light backgrounds.
+
+```jsx file=../../examples/IconButtonVariationsExample.tsx
 
 ```
 
-With tooltip for enhanced user experience.
+### Sizes
+
+The button has 3 different sizes:
 
-### As toolbar actions
+```jsx file=../../examples/IconButtonSizesExample.tsx
+
+```
 
-In toolbars, action bars, and in all other space restricted containers we suggest using `IconButton` instead of `Button` component.
+### Tooltip
 
-For these cases, it would be also beneficial to use [Tooltip](../components/tooltip) as a wrapper of `IconButton` to help users with understanding the button's purpose.
+A built-in [Tooltip](./tooltip) is available to provide users with additional context about the purpose when they hover over the button.
 
-```jsx file=../../examples/IconButtonToolbarExample.tsx
+```jsx file=../../examples/IconButtonTooltipExample.tsx
 
 ```
 
@@ -49,6 +59,6 @@ For these cases, it would be also beneficial to use [Tooltip](../components/tool
 
 ## Accessibility
 
-We enforce `aria-label` property for `IconButton` component to ensure that these buttons are fully accessible for screen readers.
+The IconButton component requires an `aria-label` to ensure full accessibility for screen readers.
 
-For easier understanding we also encourage the use of the tooltipProps and giving it the same `content` as the `aria-label`
+For easier understanding, use tooltipProps and set its content to match the `aria-label`. It’s recommended to ensure tooltipProps and `aria-label` have the same content.

packages/website/components/PageContent/PageContentHeader.tsx

@@ -43,7 +43,7 @@ interface PageContentHeaderProps {
 const getGithubIssueLink = (title) => {
   const queryParams = {
     title: `💬  Feedback - ${title}`,
-    assignees: 'burakukula,mshaaban0,denkristoffer,Lelith',
+    assignees: 'Lelith, veu, cf-remylenoir, damann',
     template: 'component-feedback.md',
   };
   const queryString = Object.keys(queryParams)