@keboola/design 1.2.0 → 1.3.0

package/src/blocks/SplitButton/SplitButton.tsx

@@ -1,8 +1,11 @@
 import type { ComponentProps, ElementRef, ReactNode, Ref } from 'react';
 
+import { ChevronDown } from '@keboola/design/icons';
+
 import { Button } from '../../components/Button';
 import { ButtonGroup } from '../../components/ButtonGroup';
 import { DropdownMenu } from '../../components/DropdownMenu';
+import { renderLegacyIcon } from '../../utils/legacyIcon';
 
 type Variant = ComponentProps<typeof Button>['variant'];
 type Size = NonNullable<ComponentProps<typeof Button>['size']>;
@@ -15,10 +18,12 @@ type Props = {
   actions?: ReactNode;
   isActionsOpen?: boolean;
   onActionsOpenChange?: (open: boolean) => void;
+  /** Optional leading-icon slot — pass a Lucide icon node. */
+  icon?: ReactNode;
   // inline and invisible aren't supported in SplitButton
   variant?: Exclude<Variant, 'inline' | 'invisible'>;
   size?: SpitButtonSize;
-} & Omit<ComponentProps<typeof Button>, 'variant' | 'size'>;
+} & Omit<ComponentProps<typeof Button>, 'variant' | 'size' | 'icon'>;
 
 const iconSizeMap: Record<SpitButtonSize, Size> = {
   medium: 'icon',
@@ -35,10 +40,17 @@ const SplitButtonBase = ({
   isActionsOpen,
   onActionsOpenChange,
   argo = false,
+  icon,
+  children,
   ...rest
 }: Props & { ref?: Ref<ElementRef<'button'>> }) => (
   <ButtonGroup space="compact">
-    <Button {...rest} ref={ref} disabled={disabled} variant={variant} size={size} argo={argo} />
+    <Button {...rest} ref={ref} disabled={disabled} variant={variant} size={size} argo={argo}>
+      {/* Suppress the leading icon while Button renders its spinner so the two
+          glyphs don't double-stack. */}
+      {!rest.isLoading && renderLegacyIcon(icon)}
+      {children}
+    </Button>
 
     {actions && (
       <DropdownMenu
@@ -52,9 +64,10 @@ const SplitButtonBase = ({
             argo={argo}
             size={iconSizeMap[size]}
             variant={variant}
-            icon="caret-down"
             aria-label="Additional actions"
-          />
+          >
+            <ChevronDown className="tw-size-5" />
+          </Button>
         </DropdownMenu.Trigger>
         <DropdownMenu.Content align="end">{actions}</DropdownMenu.Content>
       </DropdownMenu>

package/src/blocks/Tagger/TagItem.tsx

@@ -1,4 +1,5 @@
 import { Badge } from '../../components/Badge';
+import { X } from '../../icons';
 
 import type { TagOption } from './types';
 
@@ -21,7 +22,9 @@ export const TagItem = ({ tag, onRemove, disabled = false }: Props) => {
 
       {onRemove && !isDisabled && (
         <Badge.Addon variant="floating" align="inline-end">
-          <Badge.Button onClick={handleRemove} icon="xmark" aria-label="Remove Tag" />
+          <Badge.Button onClick={handleRemove} aria-label="Remove Tag">
+            <X className="tw-size-3" />
+          </Badge.Button>
         </Badge.Addon>
       )}
     </Badge.Root>

package/src/blocks/Tagger/TagSelectPopover/TagSelectCreateItem.tsx

@@ -1,6 +1,8 @@
 import type { ComponentProps } from 'react';
 import { useCommandState } from 'cmdk';
 
+import { Plus } from '@keboola/design/icons';
+
 import { Command } from '../../../components/Command';
 import { cn } from '../../../utils';
 
@@ -26,7 +28,7 @@ export const TagSelectCreateItem = ({ onCreate, value }: Props) => {
       className={cn('[&_svg]:tw-text-primary-500', {
         'tw-hidden': !isCreateItemVisible,
       })}
-      icon="plus"
+      icon={<Plus className="tw-size-4" />}
     >
       Create{' '}
       {isSearched ? (

package/src/blocks/Tagger/TagSelectPopover/TagSelectList.tsx

@@ -2,7 +2,7 @@ import { type ComponentProps, useState } from 'react';
 import { defaultFilter } from 'cmdk';
 
 import { Command } from '../../../components/Command';
-import { Icon } from '../../../components/Icon';
+import { Search } from '../../../icons';
 import type { TagOption } from '../types';
 
 import { TagSelectCreateItem } from './TagSelectCreateItem';
@@ -41,7 +41,7 @@ export const TagSelectList = ({ options = defaultOptions, onAdd, onCreate }: Pro
         <div className="tw-border-b tw-border-neutral-100 tw-p-3">
           <Command.Input
             variant="secondary"
-            prefix={<Icon icon="search" className="tw-size-4 tw-text-neutral-400" />}
+            prefix={<Search className="tw-size-4 tw-text-neutral-400" />}
             placeholder="Search tags"
             allowClear
           />

package/src/blocks/Tagger/Tagger.tsx

@@ -2,8 +2,8 @@ import { useMemo } from 'react';
 import type { ComponentProps } from 'react';
 
 import { Badge } from '../../components/Badge';
-import { Icon } from '../../components/Icon';
 import { TooltipProvider } from '../../components/Tooltip';
+import { Plus } from '../../icons';
 import { cn } from '../../utils';
 
 import { TagItem } from './TagItem';
@@ -82,7 +82,7 @@ export const Tagger = ({
             <TagSelectPopover options={tagsToAdd} onAdd={handleAdd} onCreate={handleCreate}>
               <Badge color="gray-inverse" asChild>
                 <button type="button" className="tw-flex tw-items-center tw-gap-1">
-                  <Icon icon="plus" />
+                  <Plus className="tw-size-4" />
                   <span
                     className={cn({
                       'tw-sr-only': isAnySelected,

package/src/components/Alert/Alert.stories.tsx

@@ -1,6 +1,8 @@
 import type { ComponentProps } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
+import { Eye, Info, X } from '@keboola/design/icons';
+
 import { withTooltipProvider } from '../../utils';
 import { Button } from '../Button';
 
@@ -47,9 +49,15 @@ export const WithActions: Story = {
   args: {
     actions: (
       <>
-        <Button variant="inline" icon="info-circle" size="icon-3xs" aria-label="Info" />
-        <Button variant="inline" icon="eye" size="icon-3xs" aria-label="Seen" />
-        <Button variant="inline" icon="xmark" size="icon-3xs" aria-label="Close" />
+        <Button variant="inline" size="icon-3xs" aria-label="Info">
+          <Info className="tw-size-4" />
+        </Button>
+        <Button variant="inline" size="icon-3xs" aria-label="Seen">
+          <Eye className="tw-size-4" />
+        </Button>
+        <Button variant="inline" size="icon-3xs" aria-label="Close">
+          <X className="tw-size-4" />
+        </Button>
       </>
     ),
   },

package/src/components/Alert/Alert.tsx

@@ -13,7 +13,7 @@ import { AlertTitle } from './AlertTitle';
 
 type CommonProps = {
   hideIcon?: boolean;
-  icon?: ComponentProps<typeof AlertIcon>['icon'];
+  icon?: ReactNode;
 } & Pick<ComponentProps<typeof Collapsible>, 'open' | 'onOpenChange' | 'defaultOpen'> &
   Omit<ComponentProps<typeof AlertRoot>, 'children'>;
 
@@ -31,8 +31,26 @@ type DefaultProps = {
   actions?: ReactNode;
 };
 
+/**
+ * Props for `Alert`. Discriminated by `mode` — `"default"` renders `title` / `children` / `actions`,
+ * `"collapsible"` requires `title` + `children` (no `actions`) and renders a collapsible disclosure.
+ * `variant` (`info` | `success` | `warning` | `error`) is a categorical colour contract.
+ */
 type Props = CommonProps & (CollapsibleProps | DefaultProps);
 
+/**
+ * Persistent inline banner for contextual messages tied to the page layout.
+ *
+ * **When to use:** a message that lives in the page (info banner, warning about a misconfiguration,
+ * post-save validation summary). Use `variant` to encode meaning; pass `actions` for inline buttons.
+ * `mode="collapsible"` collapses long error details behind a toggle.
+ * **When NOT to use:** for transient feedback (save succeeded, job started) use `toast()`; for
+ * field-level validation errors use `FormGroup state="error"`; for a confirmation popover use
+ * `Popconfirm`.
+ * **Composition:** typically rendered at the top of `PageLayout.Content` or above a form section.
+ *
+ * @see RECIPES.md#alert-with-action — for action-bearing alert composition
+ */
 export const Alert = ({
   title,
   variant = 'info',

package/src/components/Alert/AlertCollapsibleIcon.tsx

@@ -1,5 +1,5 @@
+import { ChevronDown } from '../../icons';
 import { cn } from '../../utils';
-import { Icon } from '../Icon';
 import { Tooltip } from '../Tooltip';
 
 type Props = {
@@ -8,11 +8,10 @@ type Props = {
 
 export const AlertCollapsibleIcon = ({ open }: Props) => (
   <Tooltip placement="top" tooltip={open ? 'Collapse alert' : 'Expand alert'} triggerAsChild>
-    <Icon
-      icon="chevron-down"
+    <ChevronDown
       className={cn(
         'tw-mt-px',
-        'tw-size-4',
+        'tw-size-5',
         'tw-text-neutral-400',
         'group-data-[state=open]/alert:tw-rotate-180',
 

package/src/components/Alert/AlertIcon.tsx

@@ -1,43 +1,40 @@
-import type { ComponentProps, ElementRef, Ref } from 'react';
+import type { ComponentProps, ReactNode } from 'react';
 
+import { AlertTriangle, CircleCheck, Info } from '../../icons';
 import { cn } from '../../utils';
-import { Icon } from '../Icon';
 
 import type { Variant } from './AlertRoot';
 
-const ICONS: Record<Variant, ComponentProps<typeof Icon>['icon']> = {
-  info: 'circle-info',
-  warning: 'triangle-exclamation',
-  error: 'triangle-exclamation',
-  success: 'circle-check',
+const VARIANT_ICONS: Record<Variant, ReactNode> = {
+  info: <Info />,
+  warning: <AlertTriangle />,
+  error: <AlertTriangle />,
+  success: <CircleCheck />,
 };
 
 type Props = {
   variant: Variant;
-  icon?: ComponentProps<typeof Icon>['icon'];
-} & Omit<ComponentProps<typeof Icon>, 'icon'>;
+  icon?: ReactNode;
+} & Omit<ComponentProps<'span'>, 'children'>;
 
-export const AlertIcon = ({
-  ref,
-  variant,
-  icon,
-  className,
-  ...rest
-}: Props & { ref?: Ref<ElementRef<'svg'>> }) => (
-  <Icon
+export const AlertIcon = ({ variant, icon, className, ...rest }: Props) => (
+  <span
     {...rest}
-    ref={ref}
     data-slot="alert-icon"
-    icon={icon ?? ICONS[variant]}
     className={cn(
+      'tw-inline-flex',
+      'tw-items-center',
+      'tw-justify-center',
       'tw-self-start',
       'tw-p-0.5',
-      'tw-text-base',
+      '[&_svg]:tw-size-4',
       'group-data-[variant=info]/alert:tw-text-secondary-500',
       'group-data-[variant=warning]/alert:tw-text-warning-500',
       'group-data-[variant=error]/alert:tw-text-error-500',
       'group-data-[variant=success]/alert:tw-text-primary-500',
       className,
     )}
-  />
+  >
+    {icon ?? VARIANT_ICONS[variant]}
+  </span>
 );

package/src/components/Badge/Badge.stories.tsx

@@ -1,5 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
+import { Plus, X } from '@keboola/design/icons';
+
 import { Icon } from '../Icon';
 
 import { Badge } from './Badge';
@@ -80,21 +82,37 @@ export const AsButton: Story = {
 
 export const StartAddon: Story = {
   args: {
-    prefix: <Badge.Button icon="plus" onClick={() => alert('Removed')} aria-label="Add" />,
+    prefix: (
+      <Badge.Button onClick={() => alert('Removed')} aria-label="Add">
+        <Plus className="tw-size-4" />
+      </Badge.Button>
+    ),
   },
 };
 
 export const EndAddon: Story = {
   args: {
-    suffix: <Badge.Button icon="xmark" onClick={() => alert('Removed')} aria-label="Remove" />,
+    suffix: (
+      <Badge.Button onClick={() => alert('Removed')} aria-label="Remove">
+        <X className="tw-size-4" />
+      </Badge.Button>
+    ),
     prefixVariant: 'floating',
   },
 };
 
 export const BothAddons: Story = {
   args: {
-    prefix: <Badge.Button icon="plus" onClick={() => alert('Removed')} aria-label="Add" />,
-    suffix: <Badge.Button icon="xmark" onClick={() => alert('Removed')} aria-label="Remove" />,
+    prefix: (
+      <Badge.Button onClick={() => alert('Removed')} aria-label="Add">
+        <Plus className="tw-size-4" />
+      </Badge.Button>
+    ),
+    suffix: (
+      <Badge.Button onClick={() => alert('Removed')} aria-label="Remove">
+        <X className="tw-size-4" />
+      </Badge.Button>
+    ),
   },
 };
 

package/src/components/Badge/Badge.tsx

@@ -9,6 +9,11 @@ type AddonVariant = ComponentProps<typeof BadgeAddon>['variant'];
 type BadgeRootProps = ComponentProps<typeof BadgeRoot>;
 type BadgeLabelProps = ComponentProps<typeof BadgeLabel>;
 
+/**
+ * Props for `Badge`. `color` is a categorical contract (`green` = success, `red` = error, `yellow` = warning,
+ * `purple/cyan/teal/pink/blue/gray` for decorative tags) — colours stay fixed across brand themes.
+ * Pass `prefix` / `suffix` for icon-style addons.
+ */
 type Props = Pick<BadgeRootProps, 'variant' | 'color'> &
   Omit<BadgeLabelProps, 'prefix'> & {
     prefix?: ReactNode;
@@ -18,6 +23,17 @@ type Props = Pick<BadgeRootProps, 'variant' | 'color'> &
     labelClassName?: string;
   };
 
+/**
+ * Compact status / category label rendered as an inline pill.
+ *
+ * **When to use:** encoding status (active, deprecated, beta), counts, or decorative tags next to a title
+ * or in a table cell. The `color` prop is a semantic contract — `green` means success, `red` means error
+ * etc., and colours are intentionally stable across customer brand themes.
+ * **When NOT to use:** for an inline action use `Button` / `ButtonInline`; for a persistent contextual
+ * banner use `Alert`; for a counter-only chip prefer `Badge` with just a numeric label.
+ * **Composition:** drop into `PageHeader.Detail` `badges` slot, `Table.Cell`, or alongside titles in cards.
+ * Use `Badge.Button` for an interactive (clickable) badge variant.
+ */
 const BadgeInner = ({
   ref,
   // root props

package/src/components/Badge/BadgeButton.tsx

@@ -1,17 +1,14 @@
 import type { ComponentProps, ElementRef, Ref } from 'react';
 
 import { cn } from '../../utils';
-import { Icon } from '../Icon';
 
-type Props = ComponentProps<'button'> & {
-  icon: ComponentProps<typeof Icon>['icon'];
-};
+type Props = ComponentProps<'button'>;
 
 export const BadgeButton = ({
   ref,
   className,
-  icon,
   type = 'button',
+  children,
   ...rest
 }: Props & { ref?: Ref<ElementRef<'button'>> }) => (
   <button
@@ -31,9 +28,13 @@ export const BadgeButton = ({
 
       'hover:tw-brightness-95',
       'tw-px-1',
+      // Default sizing for Lucide-icon children (which ship at 24×24); keeps
+      // the visual baseline aligned with the previous FA-icon API and other
+      // icon-wrapper components (ItemIcon, SidebarMenuIcon).
+      '[&_svg]:tw-size-3',
       className,
     )}
   >
-    <Icon icon={icon} />
+    {children}
   </button>
 );

package/src/components/Breadcrumb/BreadcrumbEllipsis.tsx

@@ -1,7 +1,7 @@
 import type { ComponentProps, ElementRef, Ref } from 'react';
 
+import { Ellipsis } from '../../icons';
 import { cn } from '../../utils';
-import { Icon } from '../Icon';
 
 type Props = ComponentProps<'button'>;
 
@@ -37,7 +37,7 @@ export const BreadcrumbEllipsis = ({
     )}
     {...props}
   >
-    <Icon icon={['far', 'ellipsis']} className="tw-size-4" />
+    <Ellipsis className="tw-size-4" />
     <span className="tw-sr-only">More</span>
   </button>
 );

package/src/components/Breadcrumb/BreadcrumbSeparator.tsx

@@ -1,7 +1,7 @@
 import type { ComponentProps } from 'react';
 
+import { ChevronRight } from '../../icons';
 import { cn } from '../../utils';
-import { Icon } from '../Icon';
 
 type Props = ComponentProps<'li'>;
 
@@ -23,6 +23,6 @@ export const BreadcrumbSeparator = ({ children, className, ...props }: Props) =>
     )}
     {...props}
   >
-    {children ?? <Icon icon="chevron-right" />}
+    {children ?? <ChevronRight className="!tw-size-4" />}
   </li>
 );

package/src/components/Button/Button.stories.tsx

@@ -1,6 +1,8 @@
 import type { ComponentProps } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
+import { CircleCheck, X } from '../../icons';
+
 import { Button } from './Button';
 
 type Props = ComponentProps<typeof Button>;
@@ -43,11 +45,21 @@ export const Default: Story = {
 };
 
 export const WithIcon: Story = {
-  args: { children: 'Button', icon: 'circle-check' },
+  args: {
+    children: (
+      <>
+        <CircleCheck className="tw-size-4" /> Button
+      </>
+    ),
+  },
 };
 
 export const IconOnly: Story = {
-  args: { size: 'icon', children: null, icon: 'xmark', 'aria-label': 'Delete' },
+  args: {
+    size: 'icon',
+    children: <X className="tw-size-4" />,
+    'aria-label': 'Delete',
+  },
   argTypes: {
     size: {
       control: 'radio',

package/src/components/Button/Button.tsx

@@ -2,26 +2,57 @@ import type { ComponentProps, ElementRef, Ref } from 'react';
 import { Root, Slottable } from '@radix-ui/react-slot';
 import type { VariantProps } from 'class-variance-authority';
 
+import { Loader2 } from '../../icons';
 import { cn } from '../../utils';
 import { Icon } from '../Icon';
 
 import { argoVariants, variants } from './styles';
 
+/**
+ * Props for the `Button` component.
+ *
+ * Pass `variant` for primary/secondary/danger/outline/invisible looks, `size`
+ * for height (including `icon-*` sizes when rendering icon-only). Icons are
+ * composed as children — `<Button><Trash2 className="tw-size-4" /> Delete</Button>`.
+ * `argo` opts into the Argo redesign styling (PageHeader / sidebar contexts) —
+ * required when nested inside `PageHeader` or `PageLayout.Footer` slots.
+ */
 type Props = {
-  icon?: ComponentProps<typeof Icon>['icon'];
+  /** Replaces the leading content with a spinner and disables the button visually. The caller still controls `disabled`. */
   isLoading?: boolean;
+  /** Render as a Radix `Slot` so the parent JSX (e.g. a `react-router` `<Link>`) becomes the button element. */
   asChild?: boolean;
+  /** Opt into the Argo redesign variant. Required inside `PageHeader` slots and other Argo surfaces. */
   argo?: boolean;
+  /**
+   * @deprecated FA-name icon prop kept as a shim during the kbc-ui consumer
+   * migration sweep (UT-4109 C2). New code should compose icons as children
+   * via direct Lucide imports — `<Button><Trash2 className="tw-size-4" /> Delete</Button>`.
+   * Removed in the final C2 cleanup once every consumer is migrated.
+   */
+  icon?: ComponentProps<typeof Icon>['icon'];
 } & ComponentProps<'button'> &
   VariantProps<typeof variants>;
 
+/**
+ * Primary action surface for the design system — covers all clickable controls except inline text links.
+ *
+ * **When to use:** any user-initiated action (submit, save, open modal, run job). Use `size="icon-*"` with no
+ * children for an icon-only button; there is no separate `IconButton` component.
+ * **When NOT to use:** for inline text-link actions inside body copy use `ButtonInline`; for navigation that
+ * opens a URL use `Link`; for "primary action + dropdown of related actions" use `SplitButton`.
+ * **Composition:** wrap in `Tooltip` when icon-only or when disabled state needs an explanation; pair with
+ * `Popconfirm` for destructive confirmations; pass through `Modal.Trigger` / `DropdownMenu.Trigger` via `asChild`.
+ *
+ * @see RECIPES.md#disabled-button-tooltip — for the disabled-button + tooltip pattern
+ * @see RECIPES.md#confirm-dialog — for destructive-action confirmation
+ */
 export const Button = ({
   ref,
   children,
   disabled = false,
   className,
   type = 'button',
-  icon: iconProp,
   isLoading = false,
   asChild = false,
   onClick,
@@ -29,10 +60,10 @@ export const Button = ({
   variant = 'primary',
   size = 'medium',
   block = false,
+  icon,
   ...buttonProps
 }: Props & { ref?: Ref<ElementRef<'button'>> }) => {
   const Comp = asChild ? Root : 'button';
-  const icon = isLoading ? 'spinner' : iconProp;
   const classNames = argo
     ? argoVariants({ variant: variant, size, block, className })
     : variants({
@@ -61,12 +92,18 @@ export const Button = ({
       disabled={disabled}
       aria-disabled={disabled}
       data-variant={variant}
-      data-icon-only={!children}
+      // `size="icon"` / `size="icon-*"` flags the button as icon-only — needed
+      // by `ButtonGroup space="block"` which stretches non-icon children to
+      // equal width. Detection by `size` works for both the legacy shim path
+      // (no children, FA icon prop) and shadcn composition (icon as the only
+      // child).
+      data-icon-only={String(size).startsWith('icon')}
       type={type}
       onClick={handleClick}
       className={cn(classNames)}
     >
-      {icon && <Icon spin={isLoading} icon={icon} />}
+      {isLoading && <Loader2 className="tw-size-4 tw-shrink-0 tw-animate-spin" />}
+      {!isLoading && icon && <Icon icon={icon} />}
       <Slottable>{children}</Slottable>
     </Comp>
   );

package/src/components/Button/styles.ts

@@ -222,13 +222,11 @@ export const argoVariants = cva(
           'focus-visible:tw-ring-primary/50',
         ],
         secondary: [
-          'tw-bg-secondary',
-          'tw-text-secondary-foreground',
-          'hover:tw-bg-secondary/80',
-          'hover:tw-text-secondary-foreground',
-          'focus:tw-text-secondary-foreground',
+          'tw-bg-primary/10',
+          'tw-text-primary',
+          'hover:not-disabled:tw-bg-primary/20',
 
-          'focus-visible:tw-border-secondary',
+          'focus-visible:tw-border-primary',
           'focus-visible:tw-ring-primary/50',
         ],