@keboola/design 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keboola/design",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Keboola UI platform design system — shadcn-aligned React primitives, Keboola-branded blocks, and the form bindings built on TanStack Form.",
   "license": "MIT",
   "type": "module",
@@ -13,6 +13,7 @@
     "./styles": "./src/styles.css",
     "./mermaid": "./src/blocks/MermaidDiagram/index.ts",
     "./markdown-editor": "./src/components/MarkdownEditor/index.ts",
+    "./icons": "./src/icons/index.ts",
     "./icon-names": "./src/icon-names.ts"
   },
   "files": [
@@ -48,6 +49,7 @@
     "build:js": "tsup",
     "build:css": "tailwindcss --postcss -c tailwind.config.js -i src/styles.css -o dist/styles.css --minify",
     "test": "vitest run --passWithNoTests --reporter=dot",
+    "test:stories": "vitest run --config vitest.storybook.config.ts",
     "lint": "yarn lint:format && yarn lint:oxlint",
     "lint:fix": "oxlint --fix . && oxfmt",
     "knip:check": "yarn --cwd ../.. exec knip --workspace packages/design",
@@ -65,15 +67,19 @@
     "@keboola/tsconfig": "workspace:^",
     "@storybook/addon-docs": "^10.2.19",
     "@storybook/addon-links": "^10.2.19",
+    "@storybook/addon-vitest": "10.2.19",
     "@storybook/react-vite": "^10.2.19",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/react": "^16.3.2",
     "@testing-library/user-event": "^14.6.1",
     "@types/react": "^19.2.15",
     "@vitejs/plugin-react": "^6.0.0",
+    "@vitest/browser": "4.1.2",
+    "@vitest/browser-playwright": "4.1.2",
     "eslint-plugin-storybook": "^10.3.5",
     "oxfmt": "^0.44.0",
     "oxlint": "^1.56.0",
+    "playwright": "1.59.1",
     "storybook": "^10.2.19",
     "tailwindcss": "^3.4.17",
     "tsup": "^8.5.1",
@@ -82,7 +88,7 @@
     "vitest": "^4.1.2"
   },
   "dependencies": {
-    "@awesome.me/kit-be8bcf7e5e": "^1.0.217",
+    "@awesome.me/kit-be8bcf7e5e": "1.0.220",
     "@base-ui/react": "1.5.0",
     "@codemirror/autocomplete": "^6.20.1",
     "@codemirror/commands": "^6.10.3",
@@ -98,7 +104,7 @@
     "@codemirror/view": "^6.41.0",
     "@fortawesome/fontawesome-svg-core": "^6.7.2",
     "@fortawesome/react-fontawesome": "^0.2.2",
-    "@keboola/codemirror-lang-sfsql": "^1.1.0",
+    "@keboola/codemirror-lang-sfsql": "^1.2.0",
     "@keboola/codemirror-lang-sql": "^0.2.0",
     "@keboola/tailwind-config": "^0.1.1",
     "@lexical/code": "^0.42.0",
@@ -138,6 +144,7 @@
     "cmdk": "^1.1.1",
     "diff": "^9.0.0",
     "lexical": "^0.42.0",
+    "lucide-react": "^1.17.0",
     "mermaid": "^11.15.0",
     "node-diff3": "^3.2.0",
     "react": "^19.2.6",

package/src/blocks/AIKit/CollapsibleStepHeader.tsx

@@ -1,6 +1,6 @@
 import type { ReactNode } from 'react';
 
-import { Icon } from '../../components/Icon';
+import { ChevronDown, CircleCheck, Loader2, XCircle } from '../../icons';
 import { cn } from '../../utils';
 
 type Variant = 'success' | 'error' | 'processing' | 'dismissed';
@@ -25,15 +25,15 @@ const variantClasses: Record<Variant, string> = {
 
 const renderVariantIcon = (variant: Variant) => {
   if (variant === 'processing') {
-    return <Icon icon="spinner" spin className="tw-size-4" />;
+    return <Loader2 className="tw-size-4 tw-animate-spin" />;
   }
   if (variant === 'error') {
-    return <Icon icon="circle-xmark" className="tw-size-4" />;
+    return <XCircle className="tw-size-4" />;
   }
   if (variant === 'dismissed') {
-    return <Icon icon="circle-xmark" className="tw-size-4 tw-text-neutral-500" />;
+    return <XCircle className="tw-size-4 tw-text-neutral-500" />;
   }
-  return <Icon icon="circle-check" className="tw-size-4" />;
+  return <CircleCheck className="tw-size-4" />;
 };
 
 export const CollapsibleStepHeader = ({
@@ -56,9 +56,8 @@ export const CollapsibleStepHeader = ({
         {renderVariantIcon(variant)}
         <span>{label}</span>
       </div>
-      <Icon
-        icon="chevron-down"
-        className={cn('tw-size-3 tw-transition-transform', isExpanded && 'tw-rotate-180')}
+      <ChevronDown
+        className={cn('tw-size-4 tw-transition-transform', isExpanded && 'tw-rotate-180')}
       />
     </button>
   );

package/src/blocks/AIKit/InlineStepLabel.tsx

@@ -1,6 +1,6 @@
 import type { ReactNode } from 'react';
 
-import { Icon } from '../../components/Icon';
+import { CircleCheck, Loader2, XCircle } from '../../icons';
 
 type Variant = 'processing' | 'success' | 'error' | 'dismissed';
 
@@ -11,23 +11,23 @@ type Props = {
 
 const renderVariantIcon = (variant: Variant) => {
   if (variant === 'processing') {
-    return <Icon icon="spinner" spin className="tw-size-3 tw-text-neutral-200" />;
+    return <Loader2 className="tw-size-4 tw-animate-spin tw-text-neutral-200" />;
   }
   if (variant === 'error') {
-    return <Icon icon="circle-xmark" className="tw-size-3 tw-text-error-500" />;
+    return <XCircle className="tw-size-4 tw-text-error-500" />;
   }
   if (variant === 'dismissed') {
-    return <Icon icon="circle-xmark" className="tw-size-3 tw-text-neutral-200" />;
+    return <XCircle className="tw-size-4 tw-text-neutral-200" />;
   }
-  return <Icon icon="circle-check" className="tw-size-3 tw-text-neutral-200" />;
+  return <CircleCheck className="tw-size-4 tw-text-neutral-200" />;
 };
 
 export const InlineStepLabel = ({ variant, children }: Props) => (
-  <div className="tw-flex tw-items-center tw-gap-1">
+  <div className="tw-flex tw-min-w-0 tw-items-center tw-gap-1">
     <div className="tw-flex tw-size-5 tw-shrink-0 tw-items-center tw-justify-center">
       {renderVariantIcon(variant)}
     </div>
-    <div className="tw-flex tw-flex-wrap tw-items-center tw-gap-x-1.5 tw-gap-y-1 tw-text-sm tw-font-medium tw-italic tw-text-neutral-800">
+    <div className="tw-flex tw-min-w-0 tw-flex-wrap tw-items-center tw-gap-x-1.5 tw-gap-y-1 tw-text-sm tw-font-medium tw-italic tw-text-neutral-800">
       {children}
     </div>
   </div>

package/src/blocks/AIKit/MessageBubble.stories.tsx

@@ -1,5 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
+import { Copy, ThumbsDown, ThumbsUp } from '@keboola/design/icons';
+
 import { Button } from '../../components/Button';
 
 import { MessageBubble } from './MessageBubble';
@@ -66,9 +68,15 @@ export const AssistantWithActions: Story = {
     ),
     actions: (
       <div className="tw-flex tw-gap-2">
-        <Button size="icon-sm" variant="outline" icon="copy" aria-label="Copy" />
-        <Button size="icon-sm" variant="outline" icon="thumbs-up" aria-label="Helpful" />
-        <Button size="icon-sm" variant="outline" icon="thumbs-down" aria-label="Not helpful" />
+        <Button size="icon-sm" variant="outline" aria-label="Copy">
+          <Copy className="tw-size-4" />
+        </Button>
+        <Button size="icon-sm" variant="outline" aria-label="Helpful">
+          <ThumbsUp className="tw-size-4" />
+        </Button>
+        <Button size="icon-sm" variant="outline" aria-label="Not helpful">
+          <ThumbsDown className="tw-size-4" />
+        </Button>
       </div>
     ),
   },

package/src/blocks/AIKit/MessageBubble.tsx

@@ -28,7 +28,7 @@ const contentClasses = cva(
   {
     variants: {
       variant: {
-        assistant: ['tw-flex-1', 'tw-w-full', 'tw-min-w-0'],
+        assistant: ['tw-flex-1', 'tw-w-full', 'tw-min-w-0', '[&>*]:tw-min-w-0'],
         user: [
           'tw-max-w-screen-sm',
           'tw-w-fit',

package/src/blocks/AIKit/PlanApproval.tsx

@@ -2,7 +2,7 @@ import { type FormEvent, type KeyboardEvent, type ReactNode, useState } from 're
 
 import { Badge } from '../../components/Badge';
 import { Button } from '../../components/Button';
-import { Icon } from '../../components/Icon';
+import { ChevronDown, Send, X } from '../../icons';
 import { cn } from '../../utils';
 import { Textarea } from '../Textarea';
 
@@ -102,9 +102,8 @@ const ExpandToggle = ({
     className="tailwindcss-preflight tw-inline-flex tw-cursor-pointer tw-items-center tw-gap-1 tw-bg-transparent tw-p-0 tw-text-sm tw-font-medium tw-text-secondary-500 hover:tw-text-secondary-600 focus-visible:tw-outline focus-visible:tw-outline-2 focus-visible:tw-outline-offset-2 focus-visible:tw-outline-secondary-500"
   >
     <span>{isExpanded ? showLessLabel : showMoreLabel}</span>
-    <Icon
-      icon="chevron-down"
-      className={cn('tw-size-3 tw-transition-transform', isExpanded && 'tw-rotate-180')}
+    <ChevronDown
+      className={cn('tw-size-5 tw-transition-transform', isExpanded && 'tw-rotate-180')}
     />
   </button>
 );
@@ -221,12 +220,13 @@ export const PlanApproval = ({
             argo
             variant="outline"
             size="icon-sm"
-            icon={['far', 'xmark']}
             aria-label={closeLabel}
             onClick={onClose}
             disabled={isSubmitting}
             data-testid="plan-close-button"
-          />
+          >
+            <X className="tw-size-4" />
+          </Button>
         )}
       </div>
 
@@ -271,12 +271,13 @@ export const PlanApproval = ({
               type="submit"
               variant="invisible"
               size="icon-sm"
-              icon="paper-plane-top"
               aria-label={changeRequestSubmitLabel}
               disabled={!canSubmitChangeRequest}
               className="tw-absolute tw-right-2 tw-top-1/2 tw--translate-y-1/2 [&_svg]:tw-text-secondary-500 not-disabled:hover:[&_svg]:tw-text-secondary-600"
               data-testid="plan-change-request-submit"
-            />
+            >
+              <Send className="tw-size-4" />
+            </Button>
           </div>
         </form>
       )}

package/src/blocks/AIKit/PlanRewritingIndicator.tsx

@@ -1,4 +1,4 @@
-import { Icon } from '../../components/Icon';
+import { Loader2 } from '../../icons';
 
 type PlanRewritingIndicatorProps = {
   label?: string;
@@ -12,7 +12,7 @@ export const PlanRewritingIndicator = ({
     role="status"
     data-testid="plan-rewriting-indicator"
   >
-    <Icon icon="spinner" spin className="tw-size-4 tw-text-secondary-500" />
+    <Loader2 className="tw-size-4 tw-animate-spin tw-text-secondary-500" />
     <span className="tw-text-sm tw-italic tw-text-secondary-500">{label}</span>
   </div>
 );

package/src/blocks/AIKit/PromptInput.stories.tsx

@@ -2,6 +2,8 @@ import { useState } from 'react';
 import type { ComponentProps } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
 
+import { Upload } from '@keboola/design/icons';
+
 import { Button } from '../../components/Button';
 import { DropdownMenu } from '../../components/DropdownMenu';
 
@@ -47,7 +49,9 @@ export default {
     disabled: false,
     suffix: (
       <PromptInput.Action>
-        <Button size="icon-sm" variant="invisible" icon="upload" />
+        <Button size="icon-sm" variant="invisible">
+          <Upload className="tw-size-4" />
+        </Button>
       </PromptInput.Action>
     ),
 
@@ -87,7 +91,11 @@ export const Inline: Story = {
 
 export const Actions: Story = {
   args: {
-    suffix: <Button size="icon-3xs" variant="inline" icon="upload" />,
+    suffix: (
+      <Button size="icon-3xs" variant="inline">
+        <Upload className="tw-size-4" />
+      </Button>
+    ),
   },
 };
 

package/src/blocks/AIKit/PromptInputSubmit.tsx

@@ -1,7 +1,8 @@
-import type { ComponentProps, ElementRef, Ref } from 'react';
+import type { ComponentProps, ElementRef, ReactNode, Ref } from 'react';
 
 import { Button } from '../../components/Button';
 import { Tooltip } from '../../components/Tooltip';
+import { CirclePause, Play, Send } from '../../icons';
 
 import { PromptInputAction } from './PromptInputAction';
 
@@ -16,11 +17,11 @@ export const PromptInputSubmit = ({
   disabled,
   status = 'ready',
 }: Props & { ref?: Ref<ElementRef<'button'>> }) => {
-  const getIcon = () => {
-    if (status === 'streaming') return 'stop-circle';
-    if (status === 'interrupted') return 'play';
-    return 'paper-plane-top';
-  };
+  const icon: ReactNode = (() => {
+    if (status === 'streaming') return <CirclePause className="tw-size-4" />;
+    if (status === 'interrupted') return <Play className="tw-size-4" />;
+    return <Send className="tw-size-4" />;
+  })();
 
   const getTooltipText = () => {
     if (status === 'streaming') return 'Stop';
@@ -39,9 +40,12 @@ export const PromptInputSubmit = ({
             size="icon-sm"
             variant="invisible"
             isLoading={status === 'submitted'}
-            icon={getIcon()}
             className="tw-ml-auto tw-flex tw-items-center tw-rounded-lg [&_svg]:tw-text-secondary-500 not-disabled:hover:[&_svg]:tw-text-secondary-600"
-          />
+          >
+            {/* Suppress the child icon while isLoading — Button already renders
+                the spinner; rendering both would double-stack glyphs. */}
+            {status !== 'submitted' && icon}
+          </Button>
         </PromptInputAction>
       </Tooltip.Trigger>
 

package/src/blocks/AIKit/Question.tsx

@@ -2,9 +2,9 @@ import { type KeyboardEvent, type ReactNode, useState } from 'react';
 
 import { Button } from '../../components/Button';
 import { Checkbox } from '../../components/Checkbox';
-import { Icon } from '../../components/Icon';
 import { TextInput } from '../../components/Input';
 import { Progress } from '../../components/Progress';
+import { ChevronLeft, ChevronRight, X } from '../../icons';
 import { cn } from '../../utils';
 
 type QuestionOption = {
@@ -142,11 +142,12 @@ export const Question = ({
             argo
             variant="outline"
             size="icon-sm"
-            icon={['far', 'xmark']}
             aria-label="Close"
             onClick={onClose}
             data-testid="question-close-button"
-          />
+          >
+            <X className="tw-size-4" />
+          </Button>
         )}
       </div>
 
@@ -264,10 +265,9 @@ export const Question = ({
                 onClick={onPrevious}
                 aria-label="Previous step"
               >
-                <Icon
-                  icon="chevron-left"
+                <ChevronLeft
                   className={cn(
-                    'tw-size-4',
+                    'tw-size-5',
                     isFirstStep ? 'tw-text-primary/25' : 'tw-text-primary',
                   )}
                 />
@@ -282,10 +282,9 @@ export const Question = ({
                 onClick={onNext}
                 aria-label="Next step"
               >
-                <Icon
-                  icon="chevron-right"
+                <ChevronRight
                   className={cn(
-                    'tw-size-4',
+                    'tw-size-5',
                     currentStep === totalSteps ? 'tw-text-primary/25' : 'tw-text-primary',
                   )}
                 />

package/src/blocks/AIKit/SuggestedPrompt.tsx

@@ -1,6 +1,6 @@
 import type { ReactNode } from 'react';
 
-import { Icon } from '../../components/Icon';
+import { FileText } from '../../icons';
 import { cn } from '../../utils';
 
 type Props = {
@@ -23,10 +23,17 @@ export const SuggestedPrompt = ({ label, disabled, onClick, icon, className }: P
       onClick={onClick}
     >
       {icon ?? (
-        <Icon
-          className="group-not-disabled:group-hover:[&_path]:tw-fill-secondary-600 tw-size-4 tw-shrink-0 tw-basis-4 [&_path]:tw-fill-aigradient-600"
-          fixedWidth
-          icon={['far', 'file-lines']}
+        <FileText
+          className={cn(
+            'tw-size-4 tw-shrink-0 tw-basis-4',
+            // Lucide icons are stroke-based — paint the visible line with the
+            // AI gradient (no fill, so the glyph keeps its outline silhouette
+            // instead of becoming a solid block). The `*` selector catches
+            // every shape element (path, circle, polyline, …) so multi-part
+            // icons don't lose sub-shapes the way `path`-only selectors do.
+            '[&_*]:tw-stroke-aigradient-600',
+            'group-not-disabled:group-hover:[&_*]:tw-stroke-secondary-600',
+          )}
         />
       )}
       <div className="tw-whitespace-normal tw-text-left">{label}</div>

package/src/blocks/AIKit/ThinkingIndicator.tsx

@@ -1,4 +1,4 @@
-import { Icon } from '../../components/Icon';
+import { Loader2 } from '../../icons';
 
 type ThinkingIndicatorProps = {
   label?: string;
@@ -7,7 +7,7 @@ type ThinkingIndicatorProps = {
 export const ThinkingIndicator = ({ label = 'Thinking...' }: ThinkingIndicatorProps) => {
   return (
     <div className="tw-flex tw-items-center tw-gap-2" data-testid="chat-thinking-indicator">
-      <Icon icon="spinner" spin className="tw-size-4 tw-text-secondary-500" />
+      <Loader2 className="tw-size-4 tw-animate-spin tw-text-secondary-500" />
       <span className="tw-text-sm tw-italic tw-text-secondary-500">{label}</span>
     </div>
   );

package/src/blocks/AutoSaveTextarea/AutoSaveTextarea.tsx

@@ -1,6 +1,6 @@
 import { type ComponentProps, useState } from 'react';
 
-import { Icon } from '../../components/Icon';
+import { CircleCheck, Loader2 } from '../../icons';
 import { cn } from '../../utils';
 import { Textarea } from '../Textarea';
 
@@ -83,17 +83,17 @@ export const AutoSaveTextarea = ({
             {currentValue.length} / {maxLength}
           </span>
         )}
-        <span className="tw-text-neutral-400">
+        <span className="tw-flex tw-items-center tw-gap-1 tw-text-neutral-400">
           {isOverLimit && 'Character limit exceeded'}
           {!isOverLimit && isChanged && !isSaving && 'Unsaved'}
           {!isOverLimit && isChanged && isSaving && (
             <>
-              <Icon spin icon="spinner" className="tw-mr-1" /> Saving
+              <Loader2 className="tw-size-4 tw-animate-spin" /> Saving
             </>
           )}
           {!isOverLimit && value !== null && !isChanged && !isSaving && (
             <>
-              <Icon icon="check-circle" className="tw-text-primary-500" /> Saved
+              <CircleCheck className="tw-size-4 tw-text-primary-500" /> Saved
             </>
           )}
         </span>

package/src/blocks/ClipboardButton/ClipboardButton.tsx

@@ -1,18 +1,19 @@
-import type { ComponentProps } from 'react';
+import type { ComponentProps, ReactNode } from 'react';
 
 import { Button } from '../../components/Button';
 import { Clipboard } from '../../components/Clipboard';
+import { Copy } from '../../icons';
 
 type ClipboardProps = Pick<
   ComponentProps<typeof Clipboard>,
   'text' | 'tooltip' | 'tooltipPlacement' | 'tooltipVariant'
 >;
 
-type ButtonProps = Omit<ComponentProps<typeof Button>, 'disabled'>;
+type ButtonProps = Omit<ComponentProps<typeof Button>, 'disabled' | 'icon'>;
 
-type Props = ClipboardProps & ButtonProps;
+type Props = ClipboardProps & ButtonProps & { icon?: ReactNode };
 
-const DEFAULT_ICON: Props['icon'] = 'copy';
+const DEFAULT_ICON: ReactNode = <Copy />;
 
 export const ClipboardButton = ({
   // clipboard props
@@ -34,7 +35,8 @@ export const ClipboardButton = ({
     tooltipVariant={tooltipVariant}
     text={text}
   >
-    <Button {...rest} icon={icon} variant={variant} disabled={!text}>
+    <Button {...rest} variant={variant} disabled={!text}>
+      {icon}
       {children}
     </Button>
   </Clipboard>

package/src/blocks/ClipboardButton/ClipboardInline.tsx

@@ -1,9 +1,8 @@
 import type { ComponentProps } from 'react';
 
-import { Icon } from '@keboola/design';
-
 import { ButtonInline } from '../../components/Button';
 import { Clipboard } from '../../components/Clipboard';
+import { Copy } from '../../icons';
 
 type ClipboardProps = Pick<
   ComponentProps<typeof Clipboard>,
@@ -34,7 +33,7 @@ export const ClipboardInline = ({
     tooltipVariant={tooltipVariant}
   >
     <ButtonInline {...rest} disabled={!text}>
-      {!hideIcon && <Icon icon="copy" />}
+      {!hideIcon && <Copy className="tw-size-4" />}
       {children}
     </ButtonInline>
   </Clipboard>

package/src/blocks/ColorInput/ColorInput.tsx

@@ -9,6 +9,7 @@ import type {
 } from 'react';
 
 import { InputGroup } from '../../components/InputGroup';
+import { X } from '../../icons';
 import { cn, createChangeInputEvent, mergeRefs } from '../../utils';
 
 import { ColorPicker } from './ColorPicker';
@@ -150,12 +151,13 @@ export const ColorInput = ({
       <InputGroup.Addon align="inline-end">
         {canClear && (
           <InputGroup.Button
-            icon="xmark"
             // prevents input focus stealing
             onMouseDown={(event) => event.preventDefault()}
             onClick={handleClear}
             aria-label="Clear color"
-          />
+          >
+            <X className="tw-size-4" />
+          </InputGroup.Button>
         )}
         <ColorPicker
           disabled={disabled}

package/src/blocks/ColorInput/ColorPicker.tsx

@@ -1,5 +1,7 @@
 import { type ComponentProps, type ElementRef, useRef } from 'react';
 
+import { Pipette } from '@keboola/design/icons';
+
 import { InputGroup } from '../../components/InputGroup';
 
 import { coerceColorPickerValue, showPicker } from './utils';
@@ -30,10 +32,11 @@ export const ColorPicker = ({ value, disabled, readOnly, ...props }: Props) => {
       <InputGroup.Button
         onMouseDown={(event) => event.preventDefault()}
         disabled={disabled || readOnly}
-        icon="eye-dropper"
         onClick={handleOpenPicker}
         aria-label="Pick color"
-      />
+      >
+        <Pipette className="tw-size-4" />
+      </InputGroup.Button>
     </div>
   );
 };

package/src/blocks/EmptyState/EmptyState.tsx

@@ -67,11 +67,27 @@ const emptyStateActionsClassnames = cva(['tw-flex', 'tw-items-center', 'tw-flex-
 
 type Variant = VariantProps<typeof emptyStateClassnames>['variant'];
 
+/**
+ * Props for `EmptyState`. `variant` chooses spacing — `"default"` for full-page empty states,
+ * `"compact"` for inside cards / small surfaces.
+ */
 type RootProps = ComponentProps<'div'> &
   VariantProps<typeof emptyStateClassnames> & {
     variant?: Variant;
   };
 
+/**
+ * Friendly "nothing here yet" placeholder with icon, title, description, and actions slots.
+ *
+ * **When to use:** the user reached a page or surface that is intentionally empty (no items created
+ * yet, an empty list after filtering, an empty inbox). The goal is to guide the user to the next action.
+ * **When NOT to use:** for an error or failure state use `ErrorState`; for inline loading placeholders
+ * use `Skeleton`; for "no matches found after search" inside a search/combobox use `EmptySearchContent`.
+ * **Composition:** nest `EmptyState.Icon`, `EmptyState.Title`, `EmptyState.Description`, and
+ * `EmptyState.Actions` (with one or two `Button`s). Use `variant="compact"` inside a `Card`.
+ *
+ * @see RECIPES.md#card-with-empty-state — for the empty-card pattern
+ */
 const EmptyStateRoot = ({ className, variant = 'default', children, ...rest }: RootProps) => (
   <div role="status" className={emptyStateClassnames({ className, variant })} {...rest}>
     {children}

package/src/blocks/ErrorState/ErrorState.tsx

@@ -69,11 +69,26 @@ const errorStateActionsClassnames = cva(['tw-flex', 'tw-items-center', 'tw-flex-
 
 type Variant = VariantProps<typeof errorStateClassnames>['variant'];
 
+/**
+ * Props for `ErrorState`. `variant` chooses look — `"default"` for non-blocking errors, `"compact"` for
+ * inside cards, `"destructive"` for blocking failures (red title + icon).
+ */
 type RootProps = ComponentProps<'div'> &
   VariantProps<typeof errorStateClassnames> & {
     variant?: Variant;
   };
 
+/**
+ * Page-level error placeholder with icon, title, description, and recovery-action slots.
+ *
+ * **When to use:** the page can't render its content because a request failed, the user lacks permission,
+ * or the entity doesn't exist. Show a recovery action (retry, go back, request access) in
+ * `ErrorState.Actions`.
+ * **When NOT to use:** for transient operation failures use `toast()`; for inline form validation use
+ * `FormGroup state="error"`; for contextual warning banners use `Alert variant="error"`.
+ * **Composition:** nest `ErrorState.Icon`, `ErrorState.Title`, `ErrorState.Description`, and
+ * `ErrorState.Actions`. Use `variant="destructive"` for full-page critical failures.
+ */
 const ErrorStateRoot = ({ className, variant = 'default', children, ...rest }: RootProps) => (
   <div role="alert" className={errorStateClassnames({ className, variant })} {...rest}>
     {children}

package/src/blocks/Form/formHook.ts

@@ -11,6 +11,21 @@ import { TextAreaField } from './connectors/TextAreaField';
 import { TextField } from './connectors/TextField';
 import { fieldContext, formContext } from './contexts';
 
+/**
+ * Typed form hook + `withForm` binding for the design system.
+ *
+ * **When to use:** any form layout that has validation, server-side errors, or a submit state — pages,
+ * modals, drawers, multi-step wizards. Use `useAppForm({ defaultValues, validators, onSubmit })` at the
+ * top of the form component, then render the typed `field.TextField` / `field.NumberField` /
+ * `field.PasswordField` / `field.TextAreaField` / `field.SelectField` / `field.CheckboxField` /
+ * `field.SwitchField` connectors inside `form.AppForm` → `form.FormBody`. Submit via `form.SubmitButton`.
+ * **When NOT to use:** for a single uncontrolled `<input>` use `TextInput` directly; for a bare label + input
+ * pair without validation use `FormGroup` + `FormGroup.TextInput`.
+ * **Composition:** schema-library agnostic — pass any [Standard Schema](https://standardschema.dev/) validator
+ * (zod, valibot, …) in the consuming app. Server errors come from `setServerFieldErrors` (also re-exported).
+ *
+ * @see RECIPES.md#modal-form — for the canonical form-in-modal composition
+ */
 export const { useAppForm, withForm } = createFormHook({
   fieldContext,
   formContext,