Design System: Refactor IconButton and update documentation

packages/grafana-ui/src/components/Button/Button.mdx

@@ -1,10 +1,17 @@
 import { Meta, Preview, ArgTypes } from '@storybook/blocks';
 import { Button, LinkButton } from './Button';
+import { Alert } from '../Alert/Alert';
 
 <Meta title="MDX|Button" component={Button} />
 
 # Button
 
+<Alert severity="warning" title={'Please note:'}>
+  After reviewing this component we are asking you to use the IconButton when you require a button with only an icon.
+</Alert>
+
+When using a button please always follow a11y rules (e.g. W3C Recommendation [3.3.2 Labels or instructions](https://www.w3.org/TR/WCAG21/#labels-or-instructions)) and make sure the context in which the button is located is also communicated by screen readers.
+
 ## Primary
 
 Used for "call to action", i.e. triggering the main action. There should never be more than one on a page. If you need multiple buttons for different actions, decide which action is the most important and make that the primary `Button`. All other `Button` components should be secondary.

packages/grafana-ui/src/components/Button/Button.story.tsx

@@ -1,7 +1,7 @@
 import { StoryFn } from '@storybook/react';
 import React from 'react';
 
-import { ComponentSize } from '../../types/size';
+import { ComponentSize } from '../../types';
 import { withCenteredStory } from '../../utils/storybook/withCenteredStory';
 import { Card } from '../Card/Card';
 import { HorizontalGroup, VerticalGroup } from '../Layout/Layout';
@@ -69,12 +69,6 @@ export const Examples: StoryFn<typeof Button> = () => {
         </Button>
       </HorizontalGroup>
       <div />
-      <HorizontalGroup spacing="lg">
-        <div>With icon only</div>
-        <Button icon="cloud" size="sm" />
-        <Button icon="cloud" size="md" />
-        <Button icon="cloud" size="lg" />
-      </HorizontalGroup>
       <div />
       <Button icon="plus" fullWidth>
         Button with fullWidth

packages/grafana-ui/src/components/Button/Button.tsx

@@ -5,8 +5,8 @@ import { colorManipulator, GrafanaTheme2, ThemeRichColor } from '@grafana/data';
 
 import { useTheme2 } from '../../themes';
 import { getFocusStyles, getMouseFocusStyles } from '../../themes/mixins';
+import { ComponentSize } from '../../types';
 import { IconName } from '../../types/icon';
-import { ComponentSize } from '../../types/size';
 import { getPropertiesForButtonSize } from '../Forms/commonStyles';
 import { Icon } from '../Icon/Icon';
 import { PopoverContent, Tooltip, TooltipPlacement } from '../Tooltip';
@@ -60,6 +60,7 @@ export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
       iconOnly: !children,
     });
 
+    // In order to standardise Button please always consider using IconButton when you need a button with an icon only
     const button = (
       <button className={cx(styles.button, className)} type={type} {...otherProps} ref={ref}>
         {icon && <Icon name={icon} size={size} className={styles.icon} />}
@@ -175,7 +176,7 @@ export const getButtonStyles = (props: StyleProps) => {
       lineHeight: `${theme.spacing.gridSize * height - 2}px`,
       verticalAlign: 'middle',
       cursor: 'pointer',
-      borderRadius: theme.shape.borderRadius(1),
+      borderRadius: theme.shape.radius.default,
       '&:focus': focusStyle,
       '&:focus-visible': focusStyle,
       '&:focus:not(:focus-visible)': getMouseFocusStyles(theme),

packages/grafana-ui/src/components/IconButton/IconButton.mdx

@@ -1,12 +1,20 @@
-import { Meta, Story, Preview, ArgTypes } from '@storybook/blocks';
+import { Meta, ArgTypes } from '@storybook/blocks';
 import { IconButton } from './IconButton';
+import { Alert } from '../Alert/Alert';
 
 <Meta title="MDX|IconButton" component={IconButton} />
 
 # IconButton
 
-This component looks like just an icon but behaves like a button. It fulfils an action when you click it and has hover and focus states. You can choose which icon size you would like to use.
+This component looks just like an icon but behaves like a button. It fulfils an action when you click it and has hover and focus states. You can choose which icon size you would like to use.
 
-`IconButton` is best used when an actual button would look out of place, for example when you want to place a solitary clickable icon next to text. An example where an `IconButton` is used in Grafana is the top left back arrow in the panel edit mode.
+`IconButton` is best used when you only want an icon instead of a button with text, for example when you want to place a solitary clickable icon next to text. An example where an `IconButton` is used in Grafana is the hamburger icon at the top left which opens the new navigation.
+
+Always keep in mind to add text for a tooltip and an aria label.
+
+<Alert severity="warning" title={'Please note:'}>
+  After reviewing this component we would like you to know that there are only 5 sizes available (sizes xs to xl). Sizes
+  xxl and xxxl are now shown in size xl as well and will be deprecated in the future.
+</Alert>
 
 <ArgTypes of={IconButton} />

packages/grafana-ui/src/components/IconButton/IconButton.story.tsx

@@ -55,9 +55,9 @@ interface ScenarioProps {
 
 const RenderScenario = ({ background }: ScenarioProps) => {
   const theme = useTheme2();
-  const sizes: IconSize[] = ['sm', 'md', 'lg', 'xl', 'xxl'];
+  const sizes: IconSize[] = ['xs', 'sm', 'md', 'lg', 'xl'];
   const icons: IconName[] = ['search', 'trash-alt', 'arrow-left', 'times'];
-  const variants: IconButtonVariant[] = ['secondary', 'primary', 'destructive'];
+  const variants: IconButtonVariant[] = ['primary', 'secondary', 'destructive'];
 
   return (
     <div
@@ -67,25 +67,61 @@ const RenderScenario = ({ background }: ScenarioProps) => {
         button {
           margin-right: 8px;
           margin-left: 8px;
-          margin-bottom: 8px;
+          margin-bottom: 30px;
         }
       `}
     >
       <VerticalGroup spacing="md">
         <div>{background}</div>
-        {variants.map((variant) => {
-          return (
-            <div key={variant}>
-              {icons.map((icon) => {
-                return sizes.map((size) => (
+        <div
+          className={css`
+            display: flex;
+          `}
+        >
+          {variants.map((variant) => {
+            return (
+              <div key={variant}>
+                {icons.map((icon) => {
+                  return (
+                    <div
+                      className={css`
+                        display: flex;
+                      `}
+                      key={icon}
+                    >
+                      {sizes.map((size) => (
+                        <span key={icon + size}>
+                          <IconButton name={icon} size={size} variant={variant} />
+                        </span>
+                      ))}
+                    </div>
+                  );
+                })}
+              </div>
+            );
+          })}
+          <div
+            className={css`
+              display: flex;
+              flex-direction: column;
+            `}
+          >
+            {icons.map((icon) => (
+              <div
+                className={css`
+                  display: flex;
+                `}
+                key={icon}
+              >
+                {sizes.map((size) => (
                   <span key={icon + size}>
-                    <IconButton name={icon} size={size} variant={variant} />
+                    <IconButton name={icon} size={size} disabled />
                   </span>
-                ));
-              })}
-            </div>
-          );
-        })}
+                ))}
+              </div>
+            ))}
+          </div>
+        </div>
       </VerticalGroup>
     </div>
   );

packages/grafana-ui/src/components/IconButton/IconButton.tsx

@@ -1,22 +1,24 @@
 import { css, cx } from '@emotion/css';
 import React from 'react';
 
-import { GrafanaTheme2, colorManipulator } from '@grafana/data';
+import { GrafanaTheme2, colorManipulator, deprecationWarning } from '@grafana/data';
 
-import { useTheme2 } from '../../themes/ThemeContext';
+import { useTheme2, stylesFactory } from '../../themes';
 import { getFocusStyles, getMouseFocusStyles } from '../../themes/mixins';
-import { stylesFactory } from '../../themes/stylesFactory';
+import { ComponentSize } from '../../types';
 import { IconName, IconSize, IconType } from '../../types/icon';
 import { Icon } from '../Icon/Icon';
 import { getSvgSize } from '../Icon/utils';
 import { TooltipPlacement, PopoverContent, Tooltip } from '../Tooltip';
 
 export type IconButtonVariant = 'primary' | 'secondary' | 'destructive';
 
+type LimitedIconSize = ComponentSize | 'xl';
+
 export interface Props extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   /** Name of the icon **/
   name: IconName;
-  /** Icon size */
+  /** Icon size - sizes xxl and xxxl are deprecated and when used being decreased to xl*/
   size?: IconSize;
   /** Type of the icon - mono or default */
   iconType?: IconType;
@@ -46,12 +48,22 @@ export const IconButton = React.forwardRef<HTMLButtonElement, Props>(
     ref
   ) => {
     const theme = useTheme2();
-    const styles = getStyles(theme, size, variant);
+    let limitedIconSize: LimitedIconSize;
+
+    // very large icons (xl to xxxl) are unified to size xl
+    if (size === 'xxl' || size === 'xxxl') {
+      deprecationWarning('IconButton', 'size="xxl" and size="xxxl"', 'size="xl"');
+      limitedIconSize = 'xl';
+    } else {
+      limitedIconSize = size;
+    }
+
+    const styles = getStyles(theme, limitedIconSize, variant);
     const tooltipString = typeof tooltip === 'string' ? tooltip : '';
 
     const button = (
       <button ref={ref} aria-label={ariaLabel || tooltipString} {...restProps} className={cx(styles.button, className)}>
-        <Icon name={name} size={size} className={styles.icon} type={iconType} />
+        <Icon name={name} size={limitedIconSize} className={styles.icon} type={iconType} />
       </button>
     );
 
@@ -69,9 +81,11 @@ export const IconButton = React.forwardRef<HTMLButtonElement, Props>(
 
 IconButton.displayName = 'IconButton';
 
-const getStyles = stylesFactory((theme: GrafanaTheme2, size: IconSize, variant: IconButtonVariant) => {
-  const pixelSize = getSvgSize(size);
-  const hoverSize = Math.max(pixelSize / 3, 8);
+const getStyles = stylesFactory((theme: GrafanaTheme2, size, variant: IconButtonVariant) => {
+  // overall size of the IconButton on hover
+  // the value 8 originates from 2*4px and letting the IconSize generally decide on the hoverSize
+  const hoverSize = getSvgSize(size) + 8;
+
   let iconColor = theme.colors.text.primary;
 
   if (variant === 'primary') {
@@ -82,47 +96,34 @@ const getStyles = stylesFactory((theme: GrafanaTheme2, size: IconSize, variant:
 
   return {
     button: css`
-      width: ${pixelSize}px;
-      height: ${pixelSize}px;
-      background: transparent;
-      border: none;
-      color: ${iconColor};
-      padding: 0;
-      margin: 0;
-      outline: none;
+      z-index: 0;
+      position: relative;
+      margin: 0 ${theme.spacing(0.5)} 0 0;
       box-shadow: none;
+      border: none;
       display: inline-flex;
-      align-items: center;
+      background: transparent;
       justify-content: center;
-      position: relative;
-      border-radius: ${theme.shape.borderRadius()};
-      z-index: 0;
-      margin-right: ${theme.spacing(0.5)};
+      align-items: center;
+      padding: 0;
+      color: ${iconColor};
 
       &[disabled],
       &:disabled {
         cursor: not-allowed;
         color: ${theme.colors.action.disabledText};
         opacity: 0.65;
-        box-shadow: none;
       }
 
       &:before {
-        content: '';
-        display: block;
-        opacity: 1;
+        z-index: -1;
         position: absolute;
+        width: ${hoverSize}px;
+        height: ${hoverSize}px;
+        border-radius: ${theme.shape.radius.default};
+        content: '';
         transition-duration: 0.2s;
         transition-timing-function: cubic-bezier(0.4, 0, 0.2, 1);
-        z-index: -1;
-        bottom: -${hoverSize}px;
-        left: -${hoverSize}px;
-        right: -${hoverSize}px;
-        top: -${hoverSize}px;
-        background: none;
-        border-radius: 50%;
-        box-sizing: border-box;
-        transform: scale(0);
         transition-property: transform, opacity;
       }
 
@@ -136,22 +137,15 @@ const getStyles = stylesFactory((theme: GrafanaTheme2, size: IconSize, variant:
       }
 
       &:hover {
-        color: ${iconColor};
-
         &:before {
           background-color: ${variant === 'secondary'
             ? theme.colors.action.hover
             : colorManipulator.alpha(iconColor, 0.12)};
-          border: none;
-          box-shadow: none;
-          opacity: 1;
-          transform: scale(0.8);
         }
       }
     `,
     icon: css`
       vertical-align: baseline;
-      display: flex;
     `,
   };
 });

packages/grafana-ui/src/components/PanelChrome/PanelChrome.mdx

@@ -1,13 +1,13 @@
-import { Meta, Preview, ArgTypes } from '@storybook/blocks';
+import { css } from '@emotion/css';
+import { Meta } from '@storybook/addon-docs/blocks';
 import { PanelChrome } from './PanelChrome';
-import { LoadingIndicator } from './LoadingIndicator';
 
 import { action } from '@storybook/addon-actions';
-import { DashboardStoryCanvas } from '../../utils/storybook/DashboardStoryCanvas';
 import { HorizontalGroup } from '../Layout/Layout';
 import { LoadingState } from '@grafana/data';
-import { Button } from '../Button/Button.tsx';
+import { Button } from '../Button';
 import { Menu } from '../Menu/Menu';
+import { IconButton } from '../IconButton/IconButton';
 
 <Meta title="MDX|PanelChrome" component={PanelChrome} />
 
@@ -306,10 +306,17 @@ Component used for rendering content wrapped in the same style as grafana panels
 <PanelChrome
   title="My awesome panel title"
   titleItems={
-    <div>
-      <Button fill="text" icon="github" variant="secondary" tooltip="extra content to render" />
-      <Button fill="text" icon="sliders-v-alt" variant="secondary" tooltip="extra content2 to render" />
-    </div>
+    <>
+      <IconButton
+        className={css`
+          margin-right: 10px;
+        `}
+        name="github"
+        variant="secondary"
+        tooltip="extra content to render"
+      />
+      <IconButton name="sliders-v-alt" variant="secondary" tooltip="extra content2 to render" />
+    </>
   }
   actions={
     <Button size="sm" variant="secondary" key="A">
@@ -342,10 +349,17 @@ Component used for rendering content wrapped in the same style as grafana panels
   <PanelChrome
     title="My awesome panel title"
     titleItems={
-      <div>
-        <Button fill="text" icon="github" variant="secondary" tooltip="extra content to render" />
-        <Button fill="text" icon="sliders-v-alt" variant="secondary" tooltip="extra content2 to render" />
-      </div>
+      <>
+        <IconButton
+          className={css`
+            margin-right: 10px;
+          `}
+          name="github"
+          variant="secondary"
+          tooltip="extra content to render"
+        />
+        <IconButton name="sliders-v-alt" variant="secondary" tooltip="extra content2 to render" />
+      </>
     }
     actions={
       <Button size="sm" variant="secondary" key="A">