@nexus-cross/design-system 1.0.14 → 1.1.1

package/dist/schemas.mjs

@@ -1,6 +1,6 @@
-import './chunks/chunk-CVYXRSXT.mjs';
 import { z } from 'zod';
 
+// src/schemas/breadcrumb.ts
 z.object({
   children: z.any().describe("Content to render inside the breadcrumb item (ReactNode). Can be plain text, Link, Select, or any ReactElement."),
   className: z.string().optional().describe("Additional CSS class")
@@ -11,7 +11,21 @@ var breadcrumbPropsSchema = z.object({
   maxItems: z.number().optional().describe('Max visible items. When exceeded, middle items collapse with "\u2026"'),
   className: z.string().optional().describe("Style override for the root nav element")
 }).describe(
-  "Breadcrumb navigation (compound component pattern). Use <Breadcrumb.Item> children instead of items array. Each Item can wrap arbitrary ReactNode (Link, Select, plain text, etc.)."
+  `Breadcrumb \u2014 hierarchical location navigation (Home > Settings > Profile).
+
+WHEN TO USE:
+  \u2022 Multi-level information architecture (>=3 levels deep)
+  \u2022 Hierarchical category drill-down (file system, taxonomy)
+  \u2022 Step-based linear flow \u2192 Stepper (not Breadcrumb)
+  \u2022 Tab switching \u2192 Tab
+  \u2022 Single-level navigation \u2192 page title alone
+
+Compound pattern: use <Breadcrumb.Item> children. Each Item wraps any ReactNode (Link, Select, plain text). Use maxItems for long paths (auto-collapse with "\u2026").
+
+ANTI-PATTERNS:
+  \u2717 Breadcrumb with 1 level \u2014 just show page title
+  \u2717 Breadcrumb with > 6 visible items \u2192 set maxItems
+  \u2717 Last item as a link (it's the current page; should be plain text)`
 );
 var buttonPropsSchema = z.object({
   semantic: z.enum(["primary", "secondary", "normal", "danger"]).default("primary").describe(
@@ -31,7 +45,17 @@ var buttonPropsSchema = z.object({
   style: z.any().optional().describe("Inline style (CSSProperties)"),
   className: z.string().optional().describe("Style override")
 }).describe(
-  "Interactive button. semantic(color) x variant(style) 2-axis system. Rendering element changeable via asChild."
+  `Interactive button (always prefer over native <button>).
+
+WHEN TO USE: any clickable action \u2014 submit, navigate (with asChild), open modal, trigger menu.
+2-axis: semantic (color intent) \xD7 variant (visual weight). Use semantic="primary" for the page's main CTA, "danger" for destructive actions, "secondary" for sub actions, "normal" for neutral.
+
+ANTI-PATTERNS:
+  \u2717 <button className="bg-blue-500"> \u2192 <Button semantic="primary">
+  \u2717 <a className="..."> styled as button \u2192 <Button asChild><a href="..."/></Button>
+  \u2717 Mixing variants randomly within one row \u2014 pick one per visual hierarchy level
+  \u2717 Using primary + contained for every button \u2192 only ONE primary CTA per view
+  \u2717 <Button className="!bg-red-500"> \u2192 <Button semantic="danger"> (no !important)`
 );
 var textInputPropsSchema = z.object({
   size: z.enum(["md", "lg", "xl"]).default("md").describe("Size"),
@@ -58,7 +82,20 @@ var textInputPropsSchema = z.object({
   onBlur: z.any().optional().describe("Blur callback"),
   onFocus: z.any().optional().describe("Focus callback"),
   className: z.string().optional().describe("Style override")
-}).describe("Text input field. Supports label, description, prefix/suffix icons, clearable, character counter.");
+}).describe(
+  `Single-line text input (always prefer over native <input type="text">).
+
+WHEN TO USE: any short text \u2014 name, email, search, URL, password.
+Use the built-in label/description props instead of wrapping with your own <label>/<p> tags (auto-binds htmlFor/aria-describedby for accessibility).
+For numeric input use NumberInput; for currency PriceInput; for long text TextArea; for date DatePicker.
+
+ANTI-PATTERNS:
+  \u2717 <TextInput type="number"> \u2192 <NumberInput> (gives unit, step, \u2191\u2193 keys)
+  \u2717 <label>Email <input ...></label> + <p>helper</p> \u2192 <TextInput label="Email" description="helper">
+  \u2717 Custom red border for error \u2192 use error prop (auto aria-invalid + token color)
+  \u2717 Manual character counter \u2192 use showCount + maxLength
+  \u2717 Manual clear X button \u2192 use clearable prop`
+);
 var textAreaPropsSchema = z.object({
   label: z.string().optional().describe("Label text above the textarea"),
   description: z.string().optional().describe("Helper/error description below the textarea"),
@@ -81,7 +118,21 @@ var textAreaPropsSchema = z.object({
   onBlur: z.any().optional().describe("Blur callback"),
   onFocus: z.any().optional().describe("Focus callback"),
   className: z.string().optional().describe("Style override")
-}).describe("Multi-line text input with label, description, character counter, and resize modes.");
+}).describe(
+  `Multi-line text input. Always prefer over native <textarea>.
+
+WHEN TO USE:
+  \u2022 Long-form text \u2014 comments, descriptions, memos, bios
+  \u2022 Single-line input \u2192 TextInput
+  \u2022 Numeric \u2192 NumberInput
+
+resize="auto" auto-grows with content (great for chat input). resize="none" locks size for fixed UI.
+
+ANTI-PATTERNS:
+  \u2717 Native <textarea> + custom counter \u2192 showCount + maxLength
+  \u2717 <TextArea> for short labels \u2014 use TextInput (smaller affordance)
+  \u2717 Wrapping with custom <label>/<p> \u2192 use built-in label/description props (auto a11y binding)`
+);
 var selectPropsSchema = z.object({
   value: z.string().optional().describe("Selected value"),
   placeholder: z.string().optional().describe("Placeholder"),
@@ -93,13 +144,134 @@ var selectPropsSchema = z.object({
   children: z.any().describe("SelectItem list (ReactNode, required)"),
   className: z.string().optional().describe("Wrapper style"),
   triggerClassName: z.string().optional().describe("Trigger style override")
-}).describe("Dropdown select. Based on Radix Select. Used with SelectItem.");
+}).describe(
+  `Dropdown select for short option lists. Based on Radix Select. Used with SelectItem.
+
+WHEN TO USE:
+  \u2022 Options \u2264 7, no search needed \u2192 Select
+  \u2022 Options \u2265 7 OR search needed OR async \u2192 Combobox instead
+  \u2022 Need multi-select \u2192 Combobox (multiple)
+  \u2022 Action menu (save/delete/share) \u2192 DropdownMenu (not Select; values vs actions)
+
+ANTI-PATTERNS:
+  \u2717 Select with 20+ options \u2192 Combobox
+  \u2717 Using Select for menu items that trigger functions \u2192 DropdownMenu
+  \u2717 Manual <select> styling \u2192 Select gives consistent token styling
+  \u2717 Wrapping each SelectItem with Tooltip \u2014 instead put hint in item label`
+);
 var selectItemPropsSchema = z.object({
   value: z.string().describe("Item value"),
   children: z.any().describe("Item content (ReactNode, required)"),
   disabled: z.boolean().optional().describe("Disabled"),
   className: z.string().optional().describe("Style override")
 }).describe("Individual option within Select.");
+var comboboxOptionPropsSchema = z.object({
+  value: z.string().describe(
+    "Unique value (string, required). Duplicate values within one Combobox produce a dev-mode console.error and the duplicate option is dropped."
+  ),
+  disabled: z.boolean().optional().describe(
+    "Disable selection. Skipped by keyboard navigation (Arrow Up/Down, Home/End)."
+  ),
+  textValue: z.string().optional().describe(
+    'Text used for client-side filtering and the input display when this option is selected. If omitted, derived from `children` (string nodes only; OptionDescription / OptionMeta are excluded). Set this when label contains icons or non-text nodes you still want searchable (e.g. textValue="apple \uC0AC\uACFC fruit").'
+  ),
+  className: z.string().optional().describe('Class merged onto the rendered <div role="option">.'),
+  children: z.any().optional().describe(
+    "Label content + optional <Combobox.OptionDescription> / <Combobox.OptionMeta> slots."
+  )
+}).describe(
+  `Single Combobox option. Direct child of <Combobox> only.
+
+WHEN TO USE:
+  \u2022 One per selectable item; \`value\` MUST be unique within the Combobox
+  \u2022 Wrap rich content (icons, badges) directly as children \u2014 no escape hatch needed
+  \u2022 Use textValue when label is non-text (e.g. <Combobox.Option value="apple" textValue="\uC0AC\uACFC apple">\u{1F34E}</Combobox.Option>)
+
+ANTI-PATTERNS:
+  \u2717 <Combobox><div><Combobox.Option/></div></Combobox> \u2014 Option must be a direct child
+  \u2717 Same value on two options \u2192 dev warning + silent drop; pick unique values
+  \u2717 Putting label text inside <Combobox.OptionDescription> \u2014 that slot is the secondary line below the label`
+);
+var comboboxOptionDescriptionPropsSchema = z.object({
+  children: z.any().optional().describe("Secondary text below the label (ReactNode)."),
+  className: z.string().optional().describe("Class for the description node.")
+}).describe(
+  'Secondary text shown below an option label. Use for hints like "Republic of Korea" beneath "\uD55C\uAD6D". Excluded from textValue-based search.'
+);
+var comboboxOptionMetaPropsSchema = z.object({
+  children: z.any().optional().describe("Right-aligned meta content (price, badge, shortcut, etc.)."),
+  className: z.string().optional().describe("Class for the meta slot.")
+}).describe(
+  "Right-aligned slot inside an option. Use for prices, keyboard shortcuts, version tags, status badges. Excluded from textValue-based search."
+);
+var comboboxPropsSchema = z.object({
+  children: z.any().describe(
+    "<Combobox.Option> elements (required). Other children are ignored with a dev-mode warning. Async-search consumers swap this list as `onSearch` results arrive."
+  ),
+  value: z.any().optional().describe("Selected value. string for single, string[] for multiple"),
+  defaultValue: z.any().optional().describe("Initial value (uncontrolled)"),
+  onValueChange: z.any().optional().describe("Value change callback. (value: string | string[]) => void"),
+  multiple: z.boolean().default(false).describe("Multi-select mode. Selected values shown as chips inside input"),
+  onSearch: z.any().optional().describe("Async search callback. (query: string) => void. Triggers external data fetching with debounce. When set, the built-in client filter is disabled \u2014 render whatever <Combobox.Option> children match the latest results."),
+  searchDebounce: z.number().default(250).describe("Debounce delay (ms) before onSearch fires"),
+  loading: z.boolean().default(false).describe("Externally-controlled loading state. Shows spinner in input suffix and a status row inside the popover."),
+  filter: z.any().optional().describe("Custom client-side filter. (option: { value, textValue, disabled }, query: string) => boolean. Default: case-insensitive textValue includes match. Ignored when onSearch is set."),
+  placeholder: z.string().optional().describe("Input placeholder"),
+  emptyMessage: z.any().optional().describe('Message when no options match (string | ReactNode). Default: "\uAC80\uC0C9 \uACB0\uACFC \uC5C6\uC74C"'),
+  loadingMessage: z.any().optional().describe('Message during loading state inside popover (string | ReactNode). Default: "\uAC80\uC0C9 \uC911\u2026"'),
+  size: z.enum(["md", "lg", "xl"]).default("md").describe("Input size (matches TextInput tokens)"),
+  disabled: z.boolean().optional().describe("Disabled"),
+  error: z.boolean().optional().describe("Error state"),
+  clearable: z.boolean().default(true).describe("Show clear button when value(s) exist"),
+  autoOpenOnFocus: z.boolean().default(true).describe("Open popover automatically when input gains focus"),
+  label: z.any().optional().describe("Field label (ReactNode)"),
+  description: z.any().optional().describe("Helper text below input (ReactNode)"),
+  className: z.string().optional().describe("Wrapper className"),
+  popoverClassName: z.string().optional().describe("Popover content className")
+}).describe(
+  `Searchable select with compound option API. Text input + popover listbox. Single/multi-select. Sync (auto-filter) or async (onSearch + loading) modes.
+
+WHEN TO USE:
+  \u2022 Options \u2265 7, OR labels are long, OR search/filter is needed \u2192 Combobox (not Select)
+  \u2022 Multi-select form field \u2192 Combobox with multiple (chips render inside input)
+  \u2022 Async data from server \u2192 set onSearch + loading
+For \u22647 simple options use Select. For free-text tags use TagInput.
+
+COMPOUND API:
+  <Combobox value={v} onValueChange={setV} placeholder="\u2026">
+    <Combobox.Option value="kr">\uD55C\uAD6D</Combobox.Option>
+    <Combobox.Option value="jp" disabled>
+      \uC77C\uBCF8
+      <Combobox.OptionDescription>\uD488\uC808</Combobox.OptionDescription>
+      <Combobox.OptionMeta>JP</Combobox.OptionMeta>
+    </Combobox.Option>
+  </Combobox>
+
+  \u2022 <Combobox.Option> requires unique \`value\` (dev mode warns on duplicates and drops the duplicate)
+  \u2022 <Combobox.OptionDescription> = secondary line under label
+  \u2022 <Combobox.OptionMeta> = right-aligned slot (price, shortcut, badge)
+  \u2022 Both slots are excluded from textValue-based search
+
+ASYNC PATTERN:
+  <Combobox loading={isFetching} onSearch={(q) => mutate(q)}>
+    {results.map((u) => (
+      <Combobox.Option key={u.id} value={u.id}>{u.name}
+        <Combobox.OptionDescription>{u.email}</Combobox.OptionDescription>
+      </Combobox.Option>
+    ))}
+  </Combobox>
+  \u2014 onSearch fires after searchDebounce (default 250ms). Do NOT clear input on result update; component preserves user's typing.
+
+IME (Korean/Japanese/Chinese): Enter during composition is ignored automatically \u2014 do not add custom keydown handlers.
+
+ANTI-PATTERNS:
+  \u2717 <Select> with 20 options \u2192 <Combobox>
+  \u2717 Manual <input> + dropdown div + filter logic \u2192 <Combobox>
+  \u2717 Passing options through a prop array (legacy API removed) \u2192 use <Combobox.Option> children
+  \u2717 Wrapping options in extra elements (<div><Combobox.Option/></div>) \u2192 keep them as direct children
+  \u2717 Same \`value\` on two <Combobox.Option> \u2014 duplicates are warned + dropped in dev mode
+  \u2717 Setting value externally to clear input mid-typing \u2192 use onValueChange instead`
+);
 var dropdownMenuItemSchema = z.object({
   label: z.any().describe("Menu item text (ReactNode)"),
   value: z.string().optional().describe("Item identifier"),
@@ -116,7 +288,24 @@ var dropdownMenuPropsSchema = z.object({
   side: z.enum(["top", "right", "bottom", "left"]).default("bottom").describe("Position"),
   className: z.string().optional().describe("Trigger wrapper style"),
   contentClassName: z.string().optional().describe("Content panel style")
-}).describe("Dropdown menu. Based on Radix DropdownMenu. Action menu for context/more menus.");
+}).describe(
+  `Dropdown menu \u2014 list of actions/commands triggered by a button. Based on Radix DropdownMenu (role="menu" + keyboard nav).
+
+WHEN TO USE:
+  \u2022 "More" / context menu (\u2022\u2022\u2022, \u22EE)
+  \u2022 Action lists where each item triggers a function (save, share, delete)
+  \u2022 Selecting a value (form field) \u2192 Select / Combobox (not DropdownMenu)
+  \u2022 Multi-select toggles \u2192 ToggleGroup or CheckBox group
+  \u2022 Anchored info panel \u2192 Popover
+
+Use danger=true on destructive items (Delete) for visual + semantic emphasis.
+Use separator=true to group related actions.
+
+ANTI-PATTERNS:
+  \u2717 DropdownMenu for value selection submitted later \u2192 Select / Combobox
+  \u2717 Custom <div onClick> with isOpen state \u2192 DropdownMenu
+  \u2717 Long form inputs inside menu items \u2192 Popover instead`
+);
 var toggleGroupItemSchema = z.object({
   value: z.string().describe("Item value"),
   label: z.any().describe("Display label (ReactNode)"),
@@ -130,12 +319,37 @@ var toggleGroupPropsSchema = z.object({
   value: z.any().optional().describe("Controlled value (string | string[])"),
   defaultValue: z.any().optional().describe("Default value"),
   onValueChange: z.any().optional().describe("Value change callback"),
-  variant: z.enum(["default", "primary", "secondary"]).default("default").describe("Style variant (default=slider, primary=accent filled, secondary=accent filled)"),
+  variant: z.enum(["default", "primary", "secondary", "outline"]).default("default").describe(
+    "Style variant (default=slider, primary/secondary=accent filled, outline=bordered buttons with no background)"
+  ),
   size: z.enum(["sm", "md", "lg"]).default("md").describe("Size"),
+  fullWidth: z.boolean().default(false).describe("Stretch the group to parent width and split items equally"),
   disabled: z.boolean().optional().describe("Disable all items"),
   required: z.boolean().default(true).describe("Prevent deselection (at least one must be selected)"),
   className: z.string().optional().describe("Style override")
-}).describe("Toggle group / Segment control. Based on Radix ToggleGroup.");
+}).describe(
+  `Toggle group / Segment control for immediate-effect option selection. Based on Radix ToggleGroup.
+
+WHEN TO USE:
+  \u2022 Sort order, view mode (grid/list), filter chips \u2014 selection takes effect immediately
+  \u2022 Visual comparison important (icons or short labels)
+  \u2022 Form field that submits later \u2192 RadioGroup or CheckBox instead
+  \u2022 Page area switching (settings tabs) \u2192 Tab instead
+
+VARIANTS:
+  \u2022 default \u2014 slider-style background (sleek)
+  \u2022 primary / secondary \u2014 accent-filled selected state
+  \u2022 outline \u2014 bordered buttons with no background (button-style toolbar)
+
+fullWidth=true distributes items equally across parent width (use with outline variant for button-row look).
+
+type="single" requires at least one selection by default (required=true). Set required=false to allow deselection.
+
+ANTI-PATTERNS:
+  \u2717 Using ToggleGroup for content tabs \u2192 Tab
+  \u2717 Using ToggleGroup as form field submitted later \u2192 RadioGroup (semantics + a11y)
+  \u2717 Mixing icons and text labels of different sizes \u2014 keep visual rhythm consistent`
+);
 var sliderPropsSchema = z.object({
   value: z.array(z.number()).optional().describe("Controlled value (number[]). Use [50] for single, [20, 80] for range"),
   defaultValue: z.array(z.number()).optional().describe("Default value"),
@@ -150,7 +364,23 @@ var sliderPropsSchema = z.object({
   onValueChange: z.any().optional().describe("Value change callback (value: number[]) => void"),
   onValueCommit: z.any().optional().describe("Committed value callback (on pointer up)"),
   className: z.string().optional().describe("Style override")
-}).describe("Slider / Range input. Based on Radix Slider. Supports single and range mode.");
+}).describe(
+  `Slider \u2014 numeric range selector. Based on Radix Slider. Single thumb or range (two thumbs).
+
+WHEN TO USE:
+  \u2022 Continuous range with visual feedback: volume, brightness, price filter
+  \u2022 Range filter (min-max) \u2192 defaultValue=[20, 80]
+  \u2022 Precise number entry \u2192 NumberInput
+  \u2022 Discrete few options \u2192 ToggleGroup or RadioGroup
+  \u2022 Boolean \u2192 Switch
+
+step controls increments. onValueCommit fires only after pointer release (good for expensive recomputations).
+
+ANTI-PATTERNS:
+  \u2717 Slider for required precise input (typing 47 is faster than dragging)
+  \u2717 Long step count without showValue / labels (users have no reference)
+  \u2717 Calling expensive API on every onValueChange tick \u2192 use onValueCommit`
+);
 var checkBoxPropsSchema = z.object({
   size: z.enum(["sm", "md"]).default("md").describe("Size"),
   shape: z.enum(["square", "round"]).default("square").describe("Shape"),
@@ -166,12 +396,30 @@ var checkBoxPropsSchema = z.object({
   onCheckedChange: z.any().optional().describe("Checked state change callback (checked: boolean) => void"),
   onChange: z.any().optional().describe("Native change event handler"),
   className: z.string().optional().describe("Style override")
-}).describe("Checkbox. Native input-based, supports square/round shapes.");
+}).describe(
+  `Checkbox for multi-select form fields. Native input-based, supports square/round shapes.
+
+WHEN TO USE:
+  \u2022 Form field with multiple independent options (T&C agreements, multi-select filters submitted later)
+  \u2022 Tri-state (parent-child selection) \u2014 use indeterminate prop
+  \u2022 Single binary that takes effect immediately \u2192 Switch instead
+  \u2022 Many options with search \u2192 Combobox (multiple)
+
+INDETERMINATE: set indeterminate=true when some children are checked, others not. aria-checked becomes "mixed" automatically.
+
+ANTI-PATTERNS:
+  \u2717 <CheckBox> for "Enable dark mode" toggle \u2192 <Switch>
+  \u2717 Native <input type="checkbox"> + manual styling \u2192 <CheckBox>
+  \u2717 Forgetting indeterminate for "select all" parent`
+);
 var radioGroupPropsSchema = z.object({
   name: z.string().describe("Form name (required)"),
   value: z.string().optional().describe("Selected value (controlled)"),
   defaultValue: z.string().optional().describe("Initial value (uncontrolled)"),
   size: z.enum(["sm", "md"]).default("md").describe("Size"),
+  variant: z.enum(["default", "ring"]).default("default").describe(
+    "Visual style. default=outline circle with inner dot, ring=thick border replaces dot when checked"
+  ),
   orientation: z.enum(["horizontal", "vertical"]).default("vertical").describe("Layout direction"),
   disabled: z.boolean().optional().describe("Disabled"),
   children: z.any().describe("RadioItem list (ReactNode, required)"),
@@ -179,11 +427,32 @@ var radioGroupPropsSchema = z.object({
   "aria-labelledby": z.string().optional().describe("Accessibility label reference ID"),
   onValueChange: z.any().optional().describe("Value change callback (value: string) => void"),
   className: z.string().optional().describe("Style override")
-}).describe("Radio group. Used with RadioItem.");
+}).describe(
+  `Radio group for single-choice form fields. Used with RadioItem.
+
+WHEN TO USE:
+  \u2022 Form field where user picks ONE of small set (\u22644-7) and submits later \u2192 RadioGroup
+  \u2022 All options should be visible at once for comparison \u2192 RadioGroup (not Select)
+  \u2022 Immediate effect on selection (no submit) \u2192 ToggleGroup instead
+  \u2022 Page area switching (tabs) \u2192 Tab (not RadioGroup)
+  \u2022 Many options \u2192 Select / Combobox
+
+VARIANTS:
+  \u2022 variant="default" \u2014 outline circle with inner dot when checked (classic)
+  \u2022 variant="ring" \u2014 thick border replaces inner dot when checked (modern, Figma "ring" style)
+
+ANTI-PATTERNS:
+  \u2717 Using RadioGroup for tab-like content switching \u2192 Tab
+  \u2717 Using RadioGroup for immediate filters \u2192 ToggleGroup
+  \u2717 Mixing RadioGroup and ToggleGroup in same form \u2192 pick one pattern
+  \u2717 Native <input type="radio"> \u2192 RadioItem (gets a11y, focus ring, tokens)`
+);
 var radioItemPropsSchema = z.object({
   value: z.string().describe("Item value (required)"),
   size: z.enum(["sm", "md"]).optional().describe("Size (overrides group)"),
+  variant: z.enum(["default", "ring"]).optional().describe("Visual style (overrides group)"),
   label: z.any().optional().describe("Label text (ReactNode)"),
+  description: z.any().optional().describe("Help text shown beneath the label (ReactNode)"),
   children: z.any().optional().describe("Label alternative content (ReactNode)"),
   disabled: z.boolean().optional().describe("Disabled"),
   className: z.string().optional().describe("Style override")
@@ -198,7 +467,20 @@ var switchPropsSchema = z.object({
   onCheckedChange: z.any().optional().describe("Toggle state change callback (checked: boolean) => void"),
   onChange: z.any().optional().describe("Native change event handler (ChangeEvent)"),
   className: z.string().optional().describe("Style override")
-}).describe('Toggle switch. Native checkbox-based, role="switch".');
+}).describe(
+  `Toggle switch for immediate on/off binary state. Native checkbox-based, role="switch".
+
+WHEN TO USE:
+  \u2022 Setting that takes effect immediately (notifications on/off, dark mode)
+  \u2022 Binary state with no submit step
+  \u2022 Form field submitted later \u2192 CheckBox instead (semantics: checkbox is form data)
+  \u2022 Multiple related options \u2192 CheckBox group or ToggleGroup (multiple)
+
+ANTI-PATTERNS:
+  \u2717 <CheckBox> for "Enable notifications" toggle \u2192 <Switch>
+  \u2717 <Switch> inside form requiring submit \u2192 <CheckBox>
+  \u2717 Wrapping Switch in <label onClick> manually \u2192 use label prop or htmlFor pattern`
+);
 var chipPropsSchema = z.object({
   variant: z.enum(["default", "filled", "outline", "accent"]).default("default").describe("Style"),
   size: z.enum(["sm", "md", "lg"]).default("md").describe("Size"),
@@ -208,7 +490,21 @@ var chipPropsSchema = z.object({
   onClose: z.any().optional().describe("Close button click callback (e: MouseEvent) => void. Shows X button when provided"),
   onClick: z.any().optional().describe("Click event handler"),
   className: z.string().optional().describe("Style override")
-}).describe("Chip/tag/badge. Close button displayed via onClose prop.");
+}).describe(
+  `Chip \u2014 small interactive token for filters, tags, removable selections, status labels.
+
+WHEN TO USE:
+  \u2022 Filter token / removable selection (set onClose for X button)
+  \u2022 Tag/category indicator
+  \u2022 Status indicator with color (variant="accent")
+  \u2022 Pure count badge \u2192 Badge instead
+  \u2022 Toggleable filter \u2192 ToggleGroup or Chip with onClick + active state
+
+ANTI-PATTERNS:
+  \u2717 Building dismiss UI manually with custom div + X icon \u2192 use onClose prop
+  \u2717 Using Chip as a primary CTA \u2192 Button
+  \u2717 Using Chip for hover-only labels \u2192 Tooltip`
+);
 var badgePropsSchema = z.object({
   count: z.number().optional().describe("Badge count number"),
   max: z.number().default(99).describe('Max count (shows "99+" when exceeded)'),
@@ -219,7 +515,23 @@ var badgePropsSchema = z.object({
   offset: z.tuple([z.number(), z.number()]).optional().describe("Position offset [x, y] in px"),
   children: z.any().optional().describe("Anchor element to attach badge to (ReactNode)"),
   className: z.string().optional().describe("Style override")
-}).describe("Badge indicator. Dot or count display. Wraps children when provided.");
+}).describe(
+  `Badge \u2014 small status / count indicator overlaid on an anchor (icon, avatar, button).
+
+WHEN TO USE:
+  \u2022 Notification count on bell icon
+  \u2022 Unread message count on inbox tab
+  \u2022 Status dot (online/offline) \u2192 dot=true
+  \u2022 Status label with text (e.g. "PRO", "NEW") \u2192 Chip variant="accent"
+  \u2022 Removable filter token \u2192 Chip with onClose
+
+count={0} hides badge by default; pass showZero=true to keep visible.
+
+ANTI-PATTERNS:
+  \u2717 Using Badge as standalone label without anchor \u2192 Chip
+  \u2717 count > 999 without max \u2192 ugly layout; default max=99 ("99+")
+  \u2717 Multiple badges on same anchor (visual noise)`
+);
 var progressPropsSchema = z.object({
   value: z.number().default(0).describe("Current progress value"),
   max: z.number().default(100).describe("Maximum value"),
@@ -229,7 +541,23 @@ var progressPropsSchema = z.object({
   indeterminate: z.boolean().default(false).describe("Indeterminate loading animation"),
   label: z.string().optional().describe("Label text above the bar"),
   className: z.string().optional().describe("Style override")
-}).describe("Progress bar. Linear progress indicator with percentage display.");
+}).describe(
+  `Progress \u2014 linear progress bar (file upload, multi-step form, loading with known %).
+
+WHEN TO USE:
+  \u2022 Quantifiable progress (% complete, X of Y)
+  \u2022 Unknown duration spinner \u2192 Spinner
+  \u2022 Stable component shape during load \u2192 Skeleton
+  \u2022 Step-based navigation \u2192 Stepper
+  \u2022 Indeterminate (loading without %) \u2192 set indeterminate=true
+
+variant follows semantic colors (success when complete, danger on error).
+
+ANTI-PATTERNS:
+  \u2717 Indeterminate Progress for short loads (<1s) \u2014 Spinner is lighter
+  \u2717 Custom <div style={{ width: x% }}> \u2192 Progress (a11y, tokens)
+  \u2717 Progress without label/showValue when % is critical info`
+);
 var alertPropsSchema = z.object({
   variant: z.enum(["info", "success", "warning", "danger"]).default("info").describe("Alert type / color"),
   title: z.string().optional().describe("Alert title (bold)"),
@@ -239,14 +567,42 @@ var alertPropsSchema = z.object({
   onClose: z.any().optional().describe("Close callback () => void"),
   action: z.any().optional().describe("Action area (ReactNode, e.g. Button)"),
   className: z.string().optional().describe("Style override")
-}).describe("Alert / Banner. Inline notification with icon, title, description.");
+}).describe(
+  `Alert \u2014 persistent inline notification (banner). Auto icon by variant.
+
+WHEN TO USE:
+  \u2022 In-page status: form errors, server warnings, info banners, success confirmation
+  \u2022 Transient toast/snackbar \u2192 use a toast library, NOT Alert
+  \u2022 Modal-blocking error \u2192 Modal with semantic="danger"
+  \u2022 Inline form field error \u2192 use error/description prop on TextInput / Select / etc.
+
+variant maps to semantic colors. closable=true gives users dismiss control. action prop reserved for inline buttons (e.g. "Retry").
+
+ANTI-PATTERNS:
+  \u2717 Stacking 5 alerts at top of page (use one with summary)
+  \u2717 Critical destructive action confirmation in Alert \u2192 Modal
+  \u2717 Wrapping <div className="bg-red-100"> manually \u2192 Alert (a11y role + tokens)`
+);
 var spinnerPropsSchema = z.object({
   size: z.number().default(20).describe("Size in px"),
   color: z.string().optional().describe("Color (CSS color value, default currentColor)"),
   "aria-label": z.string().default("Loading").describe("Accessibility label"),
   style: z.any().optional().describe("Inline style (CSSProperties)"),
   className: z.string().optional().describe("Color override etc.")
-}).describe('Loading indicator. SVG-based. Built-in role="status".');
+}).describe(
+  `Loading indicator (spinner). SVG-based. role="status" + aria-label built-in.
+
+WHEN TO USE:
+  \u2022 Short loads (<1s), inline indicator (button content while submitting)
+  \u2022 Long loads with known structure \u2192 Skeleton (better perceived performance)
+  \u2022 Quantifiable progress \u2192 Progress
+  \u2022 Page-level loading boundary inside DataList/DataGrid \u2192 use their loading prop instead
+
+ANTI-PATTERNS:
+  \u2717 Custom CSS spinning div \u2192 Spinner (a11y + tokens)
+  \u2717 Using Spinner where Skeleton fits (long loads with stable layout)
+  \u2717 Forgetting aria-label override when meaning differs from "Loading"`
+);
 var stepItemSchema = z.object({
   label: z.string().describe("Step title"),
   description: z.string().optional().describe("Step description")
@@ -258,7 +614,23 @@ var stepperPropsSchema = z.object({
   orientation: z.enum(["horizontal", "vertical"]).default("horizontal").describe("Layout direction"),
   size: z.enum(["sm", "md"]).default("md").describe("Size"),
   className: z.string().optional().describe("Style override")
-}).describe("Stepper. Step-by-step progress indicator.");
+}).describe(
+  `Stepper \u2014 multi-step linear flow indicator (checkout, onboarding, wizard).
+
+WHEN TO USE:
+  \u2022 Sequential workflow with finite steps (3-7)
+  \u2022 Show user's current position in flow + completed/upcoming steps
+  \u2022 Independent navigation between unrelated sections \u2192 Tab
+  \u2022 Continuous % progress \u2192 Progress
+  \u2022 Hierarchy / location \u2192 Breadcrumb
+
+status="error" highlights the current step with danger color when validation fails.
+
+ANTI-PATTERNS:
+  \u2717 Stepper with 2 steps (use Progress or just navigation)
+  \u2717 Stepper with 10+ steps (overwhelming) \u2014 chunk into sub-flows
+  \u2717 Letting users skip ahead by clicking future steps (only mark completed \u2192 current is allowed)`
+);
 var skeletonPropsSchema = z.object({
   as: z.enum(["div", "span"]).default("div").describe("Rendered tag"),
   circle: z.boolean().default(false).describe("Circle skeleton (rounded-full)"),
@@ -268,7 +640,21 @@ var skeletonPropsSchema = z.object({
   style: z.any().optional().describe("Inline style (CSSProperties)"),
   className: z.string().optional().describe("Style override")
 }).describe(
-  "Skeleton loading placeholder. Size/shape via className. With children, wraps transparently to maintain actual size."
+  `Skeleton loading placeholder. Size/shape via className. With children, wraps transparently to maintain actual size.
+
+WHEN TO USE:
+  \u2022 Long load with known component shape (cards, lists, profile headers)
+  \u2022 Reduces perceived wait time when layout is predictable
+  \u2022 Short loads (<1s) \u2192 Spinner
+  \u2022 Quantifiable progress \u2192 Progress
+  \u2022 DataList/DataGrid loading \u2192 set list={null} (uses skeletonElement prop automatically)
+
+GOLDEN RULE: Skeleton must match the real component's shape and size. Mismatch causes layout shift.
+
+ANTI-PATTERNS:
+  \u2717 Generic gray rectangle for everything \u2192 match real component shape
+  \u2717 Skeleton for instant loads (causes flash)
+  \u2717 Many skeletons of different shapes when component is uniform \u2192 use a single skeleton in DataList`
 );
 var dividerPropsSchema = z.object({
   orientation: z.enum(["horizontal", "vertical"]).default("horizontal").describe("Direction"),
@@ -276,7 +662,21 @@ var dividerPropsSchema = z.object({
   color: z.string().optional().describe("Custom color (CSS value)"),
   style: z.any().optional().describe("Inline style (CSSProperties)"),
   className: z.string().optional().describe("Style override")
-}).describe("Divider. Supports horizontal/vertical, solid/dashed/dotted.");
+}).describe(
+  `Divider \u2014 visual separator (horizontal/vertical line).
+
+WHEN TO USE:
+  \u2022 Separating sections within a card / list
+  \u2022 Vertical separator between inline items (orientation="vertical")
+  \u2022 Use color prop sparingly \u2014 defaults to border-default token
+  \u2022 For grouping form sections, prefer larger spacing over Divider
+  \u2022 Tab/Accordion already provide visual separation \u2014 don't add Divider
+
+ANTI-PATTERNS:
+  \u2717 Stacking many Dividers \u2014 increase spacing instead
+  \u2717 Using Divider as decorative line with bright color \u2192 use Tailwind border utility on container
+  \u2717 Inline <hr> with custom CSS \u2192 Divider (consistent token)`
+);
 var tooltipPropsSchema = z.object({
   children: z.any().describe("Trigger element (ReactNode, required)"),
   content: z.any().describe("Tooltip content (ReactNode, required)"),
@@ -287,7 +687,22 @@ var tooltipPropsSchema = z.object({
   disabled: z.boolean().default(false).describe("Disabled"),
   className: z.string().optional().describe("Content style"),
   triggerClassName: z.string().optional().describe("Trigger style")
-}).describe("Tooltip. Based on Radix Tooltip. Built-in Provider.");
+}).describe(
+  `Tooltip \u2014 short text hint shown on hover/focus. Based on Radix Tooltip. Provider built-in.
+
+WHEN TO USE:
+  \u2022 Brief explanation of an icon button or truncated label
+  \u2022 Hover-only, non-interactive content (text only)
+  \u2022 Need clickable content inside \u2192 Popover (not Tooltip)
+  \u2022 Action menu \u2192 DropdownMenu
+  \u2022 Force user attention \u2192 Modal
+
+ANTI-PATTERNS:
+  \u2717 Buttons/links inside content \u2192 use Popover (Tooltip not focusable)
+  \u2717 Long paragraphs in tooltip \u2192 consider Popover or Drawer
+  \u2717 Tooltip on disabled buttons (won't show in some browsers) \u2014 wrap in span instead
+  \u2717 Critical info only in tooltip \u2014 duplicate visible elsewhere for mobile/touch`
+);
 var popoverPropsSchema = z.object({
   trigger: z.any().describe("Trigger element (ReactNode, required)"),
   side: z.enum(["top", "right", "bottom", "left"]).default("bottom").describe("Position"),
@@ -300,7 +715,21 @@ var popoverPropsSchema = z.object({
   children: z.any().optional().describe("Popover body (ReactNode)"),
   className: z.string().optional().describe("Content style"),
   arrowClassName: z.string().optional().describe("Arrow style")
-}).describe("Popover. Based on Radix Popover.");
+}).describe(
+  `Popover \u2014 anchor-positioned panel with interactive content. Based on Radix Popover.
+
+WHEN TO USE:
+  \u2022 Trigger-anchored UI with buttons, inputs, or rich content
+  \u2022 Filter/option panel near a button (not a full sidebar)
+  \u2022 Hover-only text hint \u2192 Tooltip (lighter)
+  \u2022 Action menu list \u2192 DropdownMenu (gives role=menu, keyboard nav)
+  \u2022 Decision dialog \u2192 Modal
+
+ANTI-PATTERNS:
+  \u2717 Action lists with onClick handlers \u2192 DropdownMenu (a11y semantics)
+  \u2717 Implementing dropdown manually with Popover + custom buttons \u2192 DropdownMenu
+  \u2717 Long forms inside Popover \u2192 Drawer or Modal`
+);
 var accordionItemData = z.object({
   id: z.string().describe("Unique ID"),
   trigger: z.any().describe("Trigger content (ReactNode)"),
@@ -318,7 +747,23 @@ var accordionPropsSchema = z.object({
   defaultValue: z.union([z.string(), z.array(z.string())]).optional().describe("Uncontrolled initial value"),
   onValueChange: z.any().optional().describe("Open item change callback (value: string | string[]) => void"),
   className: z.string().optional().describe("Root style")
-}).describe("Accordion. Supports both items array and composable patterns.");
+}).describe(
+  `Accordion \u2014 collapsible content sections (FAQ, settings groups).
+
+WHEN TO USE:
+  \u2022 FAQ, help docs, settings groups
+  \u2022 Long page where each section is independently scannable
+  \u2022 Hidden critical info \u2014 DO NOT bury what users always need
+  \u2022 Tab-like content switching \u2192 Tab (Accordion is for stacked, not exclusive)
+
+type="single" + collapsible=true \u2192 all-closed allowed (recommended for FAQ).
+type="multiple" \u2192 multiple sections open at once.
+
+ANTI-PATTERNS:
+  \u2717 Hiding the page's primary content inside collapsed Accordion
+  \u2717 Single-section Accordion (just show the content)
+  \u2717 Custom toggle div + state \u2014 use Accordion (gets a11y, keyboard nav)`
+);
 var drawerDirection = z.enum(["bottom", "top", "left", "right"]).default("bottom");
 var drawerPropsSchema = z.object({
   direction: drawerDirection.describe("Direction"),
@@ -328,7 +773,23 @@ var drawerPropsSchema = z.object({
   modal: z.boolean().optional().describe("Modal mode (default true). If false, background is interactive"),
   shouldScaleBackground: z.boolean().optional().describe("Background scale effect (default false)"),
   children: z.any().describe("Drawer sub-components (ReactNode, required)")
-}).describe("Drawer/bottom sheet. Based on Vaul. Compound component pattern.");
+}).describe(
+  `Drawer / bottom sheet. Based on Vaul. Compound component pattern.
+
+WHEN TO USE:
+  \u2022 Side panel for secondary action while user can still see main content (filter panel, item details)
+  \u2022 Mobile bottom sheet (direction="bottom")
+  \u2022 Force decision blocking main flow \u2192 Modal instead
+  \u2022 Inline anchor-positioned UI \u2192 Popover instead
+
+DIRECTION: bottom (default, mobile-friendly), top, left, right.
+dismissible=true (default) allows swipe/outside-click close. Set false for blocking flows.
+
+ANTI-PATTERNS:
+  \u2717 Drawer for confirmation dialogs \u2192 Modal (decision-forcing)
+  \u2717 Always shouldScaleBackground \u2192 only enable for true mobile bottom-sheets
+  \u2717 Forgetting Drawer.Title \u2192 required for screen readers (a11y)`
+);
 var drawerContentPropsSchema = z.object({
   direction: drawerDirection.optional().describe("Direction (Context takes priority)"),
   blur: z.enum(["none", "sm", "md"]).default("none").describe("Overlay blur"),
@@ -372,7 +833,24 @@ var tabPropsSchema = z.object({
   className: z.string().optional().describe("Root style"),
   tabListClassName: z.string().optional().describe("Tab list style"),
   tabPanelClassName: z.string().optional().describe("Tab panel style")
-}).describe("Tab navigation. line/pill variants.");
+}).describe(
+  `Tab navigation \u2014 switch between content panels (settings sections, profile views).
+
+WHEN TO USE:
+  \u2022 Page area swap where only one panel is visible at a time
+  \u2022 Mutually exclusive content with stable section labels
+  \u2022 Form field selection \u2192 RadioGroup (semantics: not navigation)
+  \u2022 Immediate filter/option toggle \u2192 ToggleGroup
+  \u2022 Stacked collapsible sections \u2192 Accordion
+
+destroyInactive=true unmounts hidden panels (saves memory but loses state).
+
+ANTI-PATTERNS:
+  \u2717 Tab with 1 item \u2014 just render the panel
+  \u2717 Tab with 8+ items \u2014 consider sub-routing or DropdownMenu
+  \u2717 Using Tab for form value selection \u2192 RadioGroup
+  \u2717 Custom <button> + onClick + state \u2192 Tab (a11y, keyboard, focus management)`
+);
 var carouselPropsSchema = z.object({
   opts: z.record(z.any()).optional().describe("Embla options (loop, align, etc.)"),
   plugins: z.array(z.any()).optional().describe("Embla plugins"),
@@ -380,7 +858,20 @@ var carouselPropsSchema = z.object({
   children: z.any().optional().describe("Carousel slides and sub-components (ReactNode)"),
   className: z.string().optional().describe("Style override")
 }).describe(
-  "Carousel. Based on Embla Carousel. Sub-components: CarouselSlide, CarouselPrev, CarouselNext, CarouselDots."
+  `Carousel \u2014 horizontal slide gallery. Based on Embla Carousel. Compound: CarouselSlide, CarouselPrev/Next, CarouselDots.
+
+WHEN TO USE:
+  \u2022 Hero banners, image gallery, product showcase
+  \u2022 Multi-card horizontal scroll with snap behavior
+  \u2022 Vertical scrolling list \u2192 Marquee or VirtualList (not Carousel)
+  \u2022 Critical content that must always be visible \u2014 Carousel hides slides
+
+opts={{ loop: true, align: 'start' }} for endless loop. Add Embla autoplay plugin for auto-advance.
+
+ANTI-PATTERNS:
+  \u2717 Critical CTA inside non-first slide (users might never scroll)
+  \u2717 Auto-advance without pause-on-hover (a11y)
+  \u2717 Manual scroll-snap div \u2192 Carousel (gets keyboard nav, indicators)`
 );
 var carouselSlidePropsSchema = z.object({
   className: z.string().optional().describe("Slide style (use basis-1/3 etc. for multi-slide view)"),
@@ -401,7 +892,21 @@ var paginationPropsSchema = z.object({
   size: z.enum(["sm", "md"]).default("md").describe("Size"),
   onPageChange: z.any().describe("Page change callback (page: number) => void, required"),
   className: z.string().optional().describe("<nav> style")
-}).describe("Pagination. Previous/next + page number buttons.");
+}).describe(
+  `Pagination \u2014 page-by-page navigation for long datasets.
+
+WHEN TO USE:
+  \u2022 User needs to jump to specific pages (search results, blog archives)
+  \u2022 Total count is known and stable
+  \u2022 Continuous browsing \u2192 InfiniteScroll instead
+  \u2022 Real-time stream \u2192 InfiniteScroll
+  \u2022 Both fit \u2192 Pagination is more accessible (keyboard, deep-linkable URL)
+
+ANTI-PATTERNS:
+  \u2717 Pagination with totalPages=1 \u2014 hide it
+  \u2717 Mixing Pagination + InfiniteScroll on same list (confusing)
+  \u2717 Custom page button divs \u2192 Pagination (a11y, edge cases like ellipsis)`
+);
 var avatarPropsSchema = z.object({
   src: z.string().optional().describe("Image URL"),
   alt: z.string().optional().describe("Alt text"),
@@ -411,7 +916,22 @@ var avatarPropsSchema = z.object({
   children: z.any().optional().describe("Custom image element (e.g. Next.js Image)"),
   onImageError: z.any().optional().describe("Image load error callback () => void"),
   className: z.string().optional().describe("Style override")
-}).describe("Avatar. Supports image, fallback text, and children.");
+}).describe(
+  `Avatar \u2014 user/entity profile image with text fallback.
+
+WHEN TO USE:
+  \u2022 User profiles, comment authors, team member lists, message sender icons
+  \u2022 Image fails / not provided \u2192 fallback (initials or icon) shown automatically
+  \u2022 Need optimized image (Next.js) \u2192 pass <Image> via children, omit src
+  \u2022 Larger illustration / logo \u2192 use NxImage instead
+
+shape="square" for organization/team logos; "circle" for people (default).
+
+ANTI-PATTERNS:
+  \u2717 <img> + manual fallback handling \u2192 Avatar (handles error)
+  \u2717 Avatar without alt for screen readers (always set alt or aria-label)
+  \u2717 Mixing avatar sizes inconsistently in a list \u2014 pick one size`
+);
 var counterPropsSchema = z.object({
   endValue: z.number().describe("Target value (required)"),
   startValue: z.number().default(0).describe("Start value"),
@@ -423,7 +943,22 @@ var counterPropsSchema = z.object({
   onEnd: z.any().optional().describe("Count complete callback () => void"),
   style: z.any().optional().describe("Inline style (CSSProperties)"),
   className: z.string().optional().describe("Style override")
-}).describe("Number count animation.");
+}).describe(
+  `Counter \u2014 animated number tick from startValue to endValue.
+
+WHEN TO USE:
+  \u2022 Marketing landing \u2014 "10,000+ users" KPI displays
+  \u2022 Stat dashboards (animate when value changes)
+  \u2022 Live tickers / real-time data \u2014 re-render plain text instead (Counter is one-shot animation)
+  \u2022 Currency input / editable number \u2192 NumberInput / PriceInput
+
+triggerOnView=true delays animation until element scrolls into view (good for landing pages).
+
+ANTI-PATTERNS:
+  \u2717 Counter for values that update frequently \u2014 animation queue conflicts
+  \u2717 Long duration on critical numbers (users wait to read)
+  \u2717 Counter without separator for large numbers (hard to read)`
+);
 var countdownPropsSchema = z.object({
   endTimestamp: z.number().describe("End time (Unix ms, required)"),
   separator: z.any().default(":").describe("Separator (ReactNode)"),
@@ -437,7 +972,22 @@ var countdownPropsSchema = z.object({
   render: z.any().optional().describe("Custom render function"),
   onEnd: z.any().optional().describe("Countdown end callback () => void"),
   className: z.string().optional().describe("Style override")
-}).describe("Countdown timer.");
+}).describe(
+  `Countdown \u2014 live timer counting down to endTimestamp (Unix ms).
+
+WHEN TO USE:
+  \u2022 Sale ends in / event starts in / token claim window
+  \u2022 OTP / verification code expiry
+  \u2022 Counting up (since X) \u2192 not Countdown; use Counter or custom interval
+  \u2022 Persistent server time \u2192 pass server-synced endTimestamp (not Date.now offset)
+
+showDays=false for short timers (<24h) to declutter. Use render prop for fully custom layouts.
+
+ANTI-PATTERNS:
+  \u2717 Countdown without onEnd handler \u2014 UI stuck at 0
+  \u2717 Countdown across SSR without hydration safety \u2014 pass endTimestamp from server
+  \u2717 Updating endTimestamp every render \u2014 causes jitter`
+);
 var marqueePropsSchema = z.object({
   direction: z.enum(["left", "right", "up", "down"]).default("left").describe("Direction"),
   speed: z.number().default(40).describe("Animation speed (seconds)"),
@@ -446,7 +996,22 @@ var marqueePropsSchema = z.object({
   children: z.any().describe("Content to repeat (ReactNode, required)"),
   style: z.any().optional().describe("Inline style (CSSProperties)"),
   className: z.string().optional().describe("Style override")
-}).describe("Marquee (scrolling text/elements).");
+}).describe(
+  `Marquee \u2014 endless scrolling content (logo strip, promo banner, news ticker).
+
+WHEN TO USE:
+  \u2022 Logo cloud, partner brands strip, social proof
+  \u2022 Critical info that must be read \u2192 not Marquee (auto-scroll hurts a11y)
+  \u2022 Long static list \u2192 VirtualList
+  \u2022 User-paced gallery \u2192 Carousel
+
+pauseOnHover=true is recommended whenever content is readable text.
+
+ANTI-PATTERNS:
+  \u2717 Marquee with action buttons inside (hard to click)
+  \u2717 Fast-speed marquee on important text (unreadable, a11y violation)
+  \u2717 Multiple Marquees on same page in different directions (visual chaos)`
+);
 var virtualListPropsSchema = z.object({
   items: z.array(z.any()).describe("Data array (required)"),
   estimateSize: z.union([z.number(), z.any()]).describe("Estimated item height (number or (index) => number, required)"),
@@ -457,7 +1022,23 @@ var virtualListPropsSchema = z.object({
   style: z.any().optional().describe("Inline style (CSSProperties)"),
   endReachedThreshold: z.number().default(200).describe("End detection threshold (px)"),
   onEndReached: z.any().optional().describe("End reached callback () => void")
-}).describe("Virtual scroll list. Based on @tanstack/react-virtual.");
+}).describe(
+  `VirtualList \u2014 performant rendering of huge lists (1000+ items). Based on @tanstack/react-virtual.
+
+WHEN TO USE:
+  \u2022 Large datasets (>200 rows): chat history, transactions, logs, leaderboard
+  \u2022 Stable item height (or measurable per-item via estimateSize fn)
+  \u2022 Small list (<100 items) \u2192 DataList (much simpler API)
+  \u2022 Grid layout \u2192 VirtualGrid
+  \u2022 Server-side pagination \u2192 InfiniteScroll wrapping plain list
+
+estimateSize is critical \u2014 wrong values cause scroll jumps. Pair with onEndReached for server pagination.
+
+ANTI-PATTERNS:
+  \u2717 VirtualList for short lists (DataList is simpler and renders faster)
+  \u2717 Variable estimateSize for uniform items \u2014 use a single number
+  \u2717 Putting interactive overlays inside virtual rows (mounted/unmounted on scroll)`
+);
 var virtualGridPropsSchema = z.object({
   items: z.array(z.any()).describe("Data array (required)"),
   columns: z.number().describe("Column count (required)"),
@@ -469,7 +1050,20 @@ var virtualGridPropsSchema = z.object({
   style: z.any().optional().describe("Inline style (CSSProperties)"),
   endReachedThreshold: z.number().default(200).describe("End detection threshold (px)"),
   onEndReached: z.any().optional().describe("End reached callback () => void")
-}).describe("Virtual scroll grid. Based on @tanstack/react-virtual.");
+}).describe(
+  `VirtualGrid \u2014 performant grid for huge lists. Based on @tanstack/react-virtual.
+
+WHEN TO USE:
+  \u2022 Image gallery / card grid with 200+ items
+  \u2022 Fixed column count (responsive via JS \u2014 recompute columns on breakpoint)
+  \u2022 Small grid \u2192 DataGrid (no virtualization, simpler API)
+  \u2022 Single-column list \u2192 VirtualList
+
+ANTI-PATTERNS:
+  \u2717 VirtualGrid with <50 items \u2014 DataGrid is simpler
+  \u2717 Cards with hover-expanding height (breaks virtualization)
+  \u2717 Forgetting to recompute columns on resize \u2192 visible empty space`
+);
 var infiniteScrollPropsSchema = z.object({
   list: z.array(z.any()).nullable().describe("Current data array (required)"),
   totalCount: z.number().optional().describe("Total count (mutually exclusive with hasMore)"),
@@ -482,7 +1076,23 @@ var infiniteScrollPropsSchema = z.object({
   scrollTarget: z.any().optional().describe("Scroll target element (HTMLElement | Document | MutableRefObject)"),
   children: z.any().describe("List item rendering (ReactNode, required)"),
   className: z.string().optional().describe("Style override")
-}).describe("Infinite scroll. Based on IntersectionObserver.");
+}).describe(
+  `InfiniteScroll \u2014 auto-load more when sentinel enters viewport. Based on IntersectionObserver.
+
+WHEN TO USE:
+  \u2022 Feeds, social timelines, search-as-you-scroll
+  \u2022 Continuous browsing where total isn't critical
+  \u2022 Need jump-to-page \u2192 Pagination (not InfiniteScroll)
+  \u2022 Need to render 1000s of already-loaded items efficiently \u2192 VirtualList
+  \u2022 Combine with VirtualList for huge + paginated data
+
+Pass either totalCount or hasMore (not both). handleLoadMore is required.
+
+ANTI-PATTERNS:
+  \u2717 InfiniteScroll without footer/loading element (looks broken at the bottom)
+  \u2717 InfiniteScroll without debouncing handleLoadMore \u2014 duplicate fetches
+  \u2717 Auto-loading critical actions in footer (links, contact) \u2014 they become unreachable`
+);
 var ellipsisPropsSchema = z.object({
   content: z.any().default("").describe("Body text (ReactNode)"),
   lineClamp: z.number().default(2).describe("Line clamp limit"),
@@ -492,7 +1102,22 @@ var ellipsisPropsSchema = z.object({
   observingEnvs: z.array(z.boolean()).optional().describe("Re-measure on external condition change"),
   onShowMoreLessClick: z.any().optional().describe("Show more/less click callback () => void"),
   className: z.string().optional().describe("Style override")
-}).describe("Text ellipsis. Built-in show more/less toggle.");
+}).describe(
+  `Ellipsis \u2014 clamp long text to N lines with "show more / less" toggle.
+
+WHEN TO USE:
+  \u2022 Long descriptions in cards, comments, post previews
+  \u2022 Single-line truncation only \u2192 CSS line-clamp utility (lighter)
+  \u2022 Tooltip on hover for full text \u2192 Tooltip + truncate utility
+  \u2022 Critical content that must be fully readable \u2014 don't truncate
+
+triggerMore/triggerLess accept ReactNode for icons or styled buttons.
+
+ANTI-PATTERNS:
+  \u2717 Ellipsis on titles / labels \u2014 confusing UX
+  \u2717 Always-collapsed (defaultShortened=true) for short text \u2014 measurement waste
+  \u2717 Overriding triggerMore/Less with HTML that breaks accessibility (use button-like)`
+);
 var emptyStatePropsSchema = z.object({
   icon: z.any().optional().describe("Custom icon (ReactNode). Default inbox icon"),
   title: z.string().optional().describe("Title text"),
@@ -501,7 +1126,22 @@ var emptyStatePropsSchema = z.object({
   size: z.enum(["sm", "md", "lg"]).default("md").describe("Overall size"),
   children: z.any().optional().describe("Additional content (ReactNode)"),
   className: z.string().optional().describe("Style override")
-}).describe("Empty state placeholder. Shown when data is empty or unavailable.");
+}).describe(
+  `EmptyState \u2014 friendly placeholder for empty lists, no search results, first-time setup.
+
+WHEN TO USE:
+  \u2022 Empty inbox / list / search results
+  \u2022 First-time use (onboarding nudge with action button)
+  \u2022 Loading \u2192 Skeleton/Spinner (NOT EmptyState)
+  \u2022 Error \u2192 Alert (or pass icon + title to EmptyState only when conceptually "nothing here")
+
+DataList/DataGrid have built-in noDataMessage that wraps EmptyState \u2014 use that prop instead of conditional rendering.
+
+ANTI-PATTERNS:
+  \u2717 Showing EmptyState during loading (confuses users into thinking data is missing)
+  \u2717 EmptyState without action when user can fix it ("Create your first X" button)
+  \u2717 Cluttered EmptyState (too much text/multiple CTAs) \u2014 keep one primary action`
+);
 var numberInputPropsSchema = z.object({
   variant: z.enum(["basic", "bind"]).default("basic").describe("Variant: basic (right chevron arrows) or bind (left/right +/- buttons)"),
   value: z.union([z.number(), z.string()]).optional().describe("Current value"),
@@ -528,7 +1168,17 @@ var numberInputPropsSchema = z.object({
   onFocus: z.any().optional().describe("Focus callback"),
   className: z.string().optional().describe("Style override")
 }).describe(
-  "Number input with two variants: basic (chevron arrows) and bind (+/- buttons). Supports label, description, max display (click to fill), accelerated increment on long press. numberInputBind(ref, direction) binds acceleration to external buttons."
+  `Number input with two variants: basic (chevron arrows) and bind (+/- buttons). Supports label, description, max display (click to fill), accelerated increment on long press. numberInputBind(ref, direction) binds acceleration to external buttons.
+
+WHEN TO USE:
+  \u2022 Any numeric field \u2014 quantity, score, age, count
+  \u2022 Currency with thousand separators \u2192 PriceInput instead
+  \u2022 Date / time \u2192 DatePicker instead
+
+ANTI-PATTERNS:
+  \u2717 <TextInput type="number"> \u2192 <NumberInput> (loses keyboard \u2191\u2193, step, accelerated long-press, max click)
+  \u2717 Custom +/- buttons + <input> \u2192 variant="bind" (or numberInputBind for external)
+  \u2717 Manual thousand separators for currency \u2192 PriceInput`
 );
 var priceInputPropsSchema = z.object({
   size: z.enum(["md", "lg", "xl"]).default("md").describe("Size"),
@@ -551,7 +1201,20 @@ var priceInputPropsSchema = z.object({
   onBalanceClick: z.any().optional().describe("Balance click callback (balance: string | number) => void"),
   className: z.string().optional().describe("Style override")
 }).describe(
-  "Price/amount input field with prefix, suffix, balance display, and auto-fill on balance click."
+  `PriceInput \u2014 currency / amount input with prefix, suffix, balance display, click-to-fill.
+
+WHEN TO USE:
+  \u2022 Money / token amounts: payment, transfer, swap, withdraw
+  \u2022 Need balance hint with auto-fill UX (set balance + onBalanceClick)
+  \u2022 Pure number (count, age, score) \u2192 NumberInput
+  \u2022 Generic text \u2192 TextInput
+
+separator=true displays commas; onValueChange always returns raw value (no commas). maxBalance auto-applies error styling on overflow.
+
+ANTI-PATTERNS:
+  \u2717 <TextInput type="number"> + manual currency formatting \u2192 PriceInput
+  \u2717 NumberInput for currency (loses prefix/suffix/balance UX)
+  \u2717 Using string input for amounts then parseFloat \u2014 lose precision; use this component`
 );
 var dataListPropsSchema = z.object({
   list: z.array(z.any()).nullable().describe("Data array to render. null = loading state (required)"),
@@ -564,7 +1227,58 @@ var dataListPropsSchema = z.object({
   children: z.any().describe("Item render function: ({ item, index }) => ReactNode (required)"),
   className: z.string().optional().describe("Root element style")
 }).describe(
-  "Data list. Automatically handles loading/skeleton/empty/data states based on list. Built-in ErrorBoundary."
+  `DataList \u2014 render-prop list that handles loading / skeleton / empty / error / data in one component. Built-in ErrorBoundary.
+
+WHEN TO USE:
+  \u2022 Any async list (<200 items) \u2014 feed, comments, dashboard rows
+  \u2022 Pass list={null} during loading (auto-shows skeleton/spinner)
+  \u2022 Pass list=[] for empty state (auto-shows noDataMessage)
+  \u2022 Card grid \u2192 DataGrid (same API + columns prop)
+  \u2022 Huge dataset \u2192 VirtualList
+
+children is render fn: ({ item, index }) => ReactNode.
+
+ANTI-PATTERNS:
+  \u2717 Manual if (loading) {...} else if (!data.length) {...} chains \u2192 DataList handles all
+  \u2717 DataList without skeletonElement when component shape is known (use Skeleton)
+  \u2717 list=undefined (treated as data, not loading) \u2014 use null for loading`
+);
+var responsiveColumnsSchema = z.object({
+  base: z.number().optional().describe("Default column count (mobile-first)"),
+  sm: z.number().optional().describe(">= 640px"),
+  md: z.number().optional().describe(">= 768px"),
+  lg: z.number().optional().describe(">= 1024px"),
+  xl: z.number().optional().describe(">= 1280px"),
+  "2xl": z.number().optional().describe(">= 1536px")
+});
+var dataGridPropsSchema = z.object({
+  list: z.array(z.any()).nullable().describe("Data array to render. null = loading state (required)"),
+  columns: z.union([z.number(), responsiveColumnsSchema]).describe(
+    "Column count. number = fixed | { base, sm, md, lg, xl, 2xl } = responsive (required)"
+  ),
+  gap: z.union([z.number(), z.string()]).optional().describe("Item gap. number = px | string = CSS value"),
+  noDataMessage: z.any().optional().describe("Message for empty array (string | ReactElement)"),
+  errorFallback: z.any().optional().describe("Fallback on error (ReactNode)"),
+  loadingElement: z.any().optional().describe("Custom loading element (default: Spinner)"),
+  skeletonElement: z.any().optional().describe("Skeleton element during loading (ReactElement)"),
+  skeletonCount: z.number().default(3).describe("Skeleton repeat count"),
+  loading: z.boolean().default(false).describe("Force loading state"),
+  children: z.any().describe("Item render function: ({ item, index }) => ReactNode (required)"),
+  className: z.string().optional().describe("Root element style")
+}).describe(
+  `DataGrid \u2014 card grid version of DataList with responsive columns. Built-in ErrorBoundary, loading/skeleton/empty/error states.
+
+WHEN TO USE:
+  \u2022 Card grids: products, gallery, team members, posts
+  \u2022 Need responsive column count \u2192 pass { base: 1, sm: 2, lg: 3, xl: 4 }
+  \u2022 Single column / row layout \u2192 DataList
+  \u2022 Tabular data \u2192 table component (not DataGrid)
+  \u2022 Huge dataset \u2192 VirtualGrid
+
+ANTI-PATTERNS:
+  \u2717 Tabular data forced into card grid (use a table)
+  \u2717 Hardcoded column count for responsive layouts \u2192 use responsive object
+  \u2717 Manual loading/empty handling \u2192 DataGrid does it`
 );
 var animationOptionsSchema = z.object({
   name: z.string().optional().describe("Animation name"),
@@ -603,7 +1317,22 @@ var modalTemplatePropsSchema = z.object({
   dimClassName: z.string().optional().describe("Dim overlay style"),
   headerClassName: z.string().optional().describe("Header area style")
 }).describe(
-  "Modal template. All modal components must be wrapped with ModalTemplate."
+  `Modal template. All modal components must be wrapped with ModalTemplate.
+
+WHEN TO USE:
+  \u2022 Force user decision (delete confirm, submit confirm, blocking dialog)
+  \u2022 Long form/flow that needs full attention
+  \u2022 Side panel that doesn't block main flow \u2192 Drawer instead
+  \u2022 Inline contextual UI \u2192 Popover instead
+  \u2022 Short hint \u2192 Tooltip instead
+
+PREFERRED API: use modal() / useModal() imperative API rather than mounting <ModalTemplate> directly. modal() handles stacking, focus return, ESC, and background scroll automatically.
+
+ANTI-PATTERNS:
+  \u2717 Custom <div className="fixed inset-0"> \u2192 modal() (loses focus trap, a11y)
+  \u2717 Direct <ModalTemplate> mount in render tree \u2192 wrap with modal()
+  \u2717 Modal with no title for screen readers \u2192 always pass title prop
+  \u2717 Multiple modals stacking confusingly \u2192 use isAlone:true to close prior modals`
 );
 var modalCallSchema = z.object({
   component: z.any().describe("Modal component (required). Automatically receives close/resolve as props"),
@@ -634,24 +1363,39 @@ var errorBoundaryPropsSchema = z.object({
   children: z.any().describe("Child elements to wrap (ReactNode, required)"),
   fallback: z.any().optional().describe("Fallback UI on error (ReactNode)"),
   onError: z.any().optional().describe("Error callback (error: Error, errorInfo: ErrorInfo) => void")
-}).describe("Error boundary. Catches child component render errors and displays fallback UI.");
+}).describe(
+  `ErrorBoundary \u2014 catches render-time errors in subtree and shows fallback UI.
+
+WHEN TO USE:
+  \u2022 Wrap risky areas: third-party widgets, dynamic imports, untrusted content rendering
+  \u2022 Async errors / promise rejections \u2192 NOT caught (use try/catch in handlers)
+  \u2022 Per-route error wrapping \u2192 use framework's error.tsx (Next.js) where possible
+
+DataList / DataGrid have ErrorBoundary built-in \u2014 don't double-wrap.
+
+ANTI-PATTERNS:
+  \u2717 ErrorBoundary at app root only \u2014 granular boundaries give better UX (one widget fails, page survives)
+  \u2717 Showing raw Error.message in production (leak risk) \u2014 use friendly fallback
+  \u2717 Forgetting onError logging \u2192 silent failures in production`
+);
 var clientOnlyPropsSchema = z.object({
   children: z.any().describe("Element to render only on client (ReactNode, required)"),
   fallback: z.any().optional().describe("Fallback UI during SSR (ReactNode, default: null)")
-}).describe("Client-only rendering. Prevents hydration mismatch in SSR environments.");
-var themeProviderPropsSchema = z.object({
-  children: z.any().describe("App root element (ReactNode, required)"),
-  defaultTheme: z.string().optional().describe('Default theme (e.g. "dark", "light")'),
-  storageKey: z.string().optional().describe('localStorage storage key (default: "theme")'),
-  themes: z.array(z.string()).optional().describe('Available theme list (default: ["light", "dark"])'),
-  attribute: z.union([z.string(), z.array(z.string())]).optional().describe('Theme HTML attribute (default: "data-theme")'),
-  enableSystem: z.boolean().optional().describe("Enable system theme detection"),
-  disableTransitionOnChange: z.boolean().optional().describe("Disable transitions on theme change"),
-  forcedTheme: z.string().optional().describe("Forced theme (user cannot change)"),
-  enableColorScheme: z.boolean().optional().describe("Auto-set color-scheme CSS property"),
-  nonce: z.string().optional().describe("CSP nonce")
-}).describe(
-  "Theme provider. Based on next-themes. Access theme state via useTheme() hook."
+}).describe(
+  `ClientOnly \u2014 defers children to client-side render, preventing SSR hydration mismatch.
+
+WHEN TO USE:
+  \u2022 Wrap components that read window/document/localStorage at render time
+  \u2022 Components depending on browser-only APIs (IntersectionObserver eager init, geolocation)
+  \u2022 Server-renderable content \u2192 DON'T wrap (loses SEO/SSR perf benefits)
+  \u2022 Conditional based on data \u2192 use proper SSR-safe state instead
+
+Pass fallback to avoid layout shift during hydration.
+
+ANTI-PATTERNS:
+  \u2717 Wrapping the entire page in ClientOnly (defeats SSR)
+  \u2717 ClientOnly without fallback for above-the-fold UI (CLS)
+  \u2717 Using ClientOnly to "fix" any hydration warning \u2014 root-cause the mismatch first`
 );
 var tablePropsSchema = z.object({
   list: z.array(z.any()).nullable().describe("Data array. null/undefined = loading state (required)"),
@@ -668,14 +1412,35 @@ var tablePropsSchema = z.object({
   className: z.string().optional().describe("Table wrapper style"),
   theadClassName: z.string().optional().describe("Header row style")
 }).describe(
-  "Table. Column definitions via TdColumn, row wrapping via TableRow. Built-in sorting/skeleton loading."
+  `Table \u2014 tabular data with sortable columns, skeleton/loading/empty states. Compound: TableRow + TdColumn.
+
+WHEN TO USE:
+  \u2022 Comparable structured data (financial reports, transaction history, leaderboard)
+  \u2022 Sortable per-column \u2192 enableSorting on TdColumn
+  \u2022 Card-style entities \u2192 DataGrid
+  \u2022 Single-column read-only list \u2192 DataList
+  \u2022 Huge dataset (>500 rows) \u2192 wrap with VirtualList logic or paginate
+
+list={null} \u2192 loading state. list=[] \u2192 noDataMsg. children: ({ item, index }) => <TableRow>...</TableRow>.
+
+ANTI-PATTERNS:
+  \u2717 Native <table> + manual loading/empty handling \u2192 Table component
+  \u2717 Forcing card-style data into Table (use DataGrid)
+  \u2717 Sorting in client when server pagination is in use \u2192 server-side sort`
 );
 var tableRowPropsSchema = z.object({
   variant: z.enum(["default", "accent"]).default("default").describe("Row style"),
   className: z.string().optional().describe("Style override"),
   children: z.any().describe("TdColumn list (ReactNode, required)"),
   onClick: z.any().optional().describe("Row click callback (e: MouseEvent) => void")
-}).describe("Table row. Used inside Table.");
+}).describe(
+  `TableRow \u2014 a single row inside Table. Wraps TdColumn cells.
+
+WHEN TO USE:
+  \u2022 variant="accent" highlights selected/current row
+  \u2022 onClick for row-level navigation (e.g. open detail page)
+  \u2022 Per-row checkbox/action \u2192 place inside a TdColumn child`
+);
 var tdColumnPropsSchema = z.object({
   label: z.any().optional().describe("Header label (ReactElement | string)"),
   fieldId: z.string().nullable().describe("Column identifier (sort key, required)"),
@@ -693,7 +1458,20 @@ var tdColumnPropsSchema = z.object({
   handleClickSort: z.any().optional().describe("Sort click callback ({ index, fieldId, order }) => void"),
   children: z.any().describe("Cell content (ReactNode, required)"),
   className: z.string().optional().describe("Style override")
-}).describe("Table cell/column definition. Used inside TableRow.");
+}).describe(
+  `TdColumn \u2014 table cell. Drives both <th> and <td> for the column. Provides sorting, alignment, overflow handling.
+
+WHEN TO USE:
+  \u2022 textOverflow="truncate" (default) for fixed-width columns; "wrap" for narrative
+  \u2022 align="right" for numeric/currency columns (a11y readability)
+  \u2022 enableSorting=true when column is sortable; supply order + handleClickSort for controlled sort
+  \u2022 highlightKey to group columns that highlight together on hover
+
+ANTI-PATTERNS:
+  \u2717 enableSorting without handleClickSort \u2192 sort indicator is dead
+  \u2717 align="left" for currency/number columns
+  \u2717 Mixing text and numeric in one column without consistent align`
+);
 var toastOptionsSchema = z.object({
   description: z.any().optional().describe("Toast subtitle (ReactNode)"),
   duration: z.number().optional().describe("Auto-dismiss duration (ms). Default 4000"),
@@ -719,7 +1497,20 @@ var toastOptionsSchema = z.object({
   unstyled: z.boolean().optional().describe("Remove default styles (for custom styling)"),
   id: z.union([z.string(), z.number()]).optional().describe("Toast ID (for deduplication or updates)")
 }).describe(
-  "toast() call options. Used as toast(message, options). Fully customizable via toast.custom(jsx)."
+  `toast() options. Used as toast(message, options) / toast.success / .error / .warning / .info / .promise / .custom(jsx).
+
+WHEN TO USE TOAST:
+  \u2022 Transient feedback after user action: "Saved", "Copied", "Network error"
+  \u2022 Persistent in-page banner \u2192 Alert
+  \u2022 Critical destructive confirmation \u2192 Modal (toast can be missed)
+  \u2022 Form field error \u2192 use error/description prop on the input
+
+richColors=true gives strong success/error/warning/info colors. Use action for "Undo" patterns.
+
+ANTI-PATTERNS:
+  \u2717 Toast for confirmation that user MUST acknowledge \u2192 Modal
+  \u2717 Stacking many toasts \u2192 set visibleToasts on Toaster
+  \u2717 Long-form content in toast (toast is for short messages)`
 );
 var toasterPropsSchema = z.object({
   position: z.enum([
@@ -741,7 +1532,17 @@ var toasterPropsSchema = z.object({
   offset: z.any().optional().describe("Offset from screen edge. string | number | { top, right, bottom, left }"),
   dir: z.enum(["ltr", "rtl", "auto"]).optional().describe("Text direction")
 }).describe(
-  "Toaster config. Place once at app root. Display notifications via toast(). Based on sonner."
+  `Toaster \u2014 toast container. Mount ONCE at app root. Then call toast() anywhere. Based on sonner.
+
+WHEN TO USE:
+  \u2022 Mount in app shell (layout.tsx / _app.tsx) \u2014 exactly one instance globally
+  \u2022 Set position once here; per-toast position only when needed
+  \u2022 Provide visibleToasts cap to avoid stacking
+
+ANTI-PATTERNS:
+  \u2717 Multiple Toasters across pages \u2014 only one global Toaster
+  \u2717 Mounting Toaster inside conditional render \u2014 toasts vanish on remount
+  \u2717 Forgetting Toaster mount \u2014 toast() calls do nothing`
 );
 var tagInputPropsSchema = z.object({
   value: z.array(z.string()).optional().describe("Controlled tags array"),
@@ -755,7 +1556,22 @@ var tagInputPropsSchema = z.object({
   description: z.string().optional().describe("Helper text below input"),
   size: z.enum(["sm", "md", "lg"]).default("md").describe("Size"),
   className: z.string().optional().describe("Style override")
-}).describe("Tag input. Enter key to add, Backspace to delete last tag.");
+}).describe(
+  `TagInput \u2014 free-form multi-value entry (Enter to add, Backspace to remove last).
+
+WHEN TO USE:
+  \u2022 Free-form labels: skills, hashtags, email recipients, keywords
+  \u2022 Predefined options \u2192 Combobox with multi-select (NOT TagInput)
+  \u2022 Single value \u2192 TextInput
+  \u2022 Limited options \u2192 Select / RadioGroup / Checkbox
+
+allowDuplicates=false (default) prevents repeats. Use max to cap count.
+
+ANTI-PATTERNS:
+  \u2717 TagInput for predefined taxonomy \u2192 Combobox (controlled options)
+  \u2717 TagInput without max for spam-prone fields
+  \u2717 Custom comma-split string field \u2192 TagInput (proper UX + a11y)`
+);
 var nxImagePropsSchema = z.object({
   src: z.string().optional().describe("Image source URL"),
   alt: z.string().optional().describe("Alt text"),
@@ -766,7 +1582,22 @@ var nxImagePropsSchema = z.object({
   lazy: z.boolean().default(true).describe('Enable lazy loading (loading="lazy")'),
   wrapperClassName: z.string().optional().describe("Wrapper div style"),
   className: z.string().optional().describe("Image element style")
-}).describe("Enhanced image. Lazy loading, fallback, aspect-ratio support.");
+}).describe(
+  `NxImage \u2014 lazy-loaded <img> with fallback, fixed aspect-ratio, object-fit. Always prefer over native <img>.
+
+WHEN TO USE:
+  \u2022 Content images: covers, banners, illustrations, hero images
+  \u2022 Profile/user avatar (with text fallback) \u2192 Avatar
+  \u2022 Background image / decorative \u2192 CSS bg-image
+  \u2022 Need Next.js optimization \u2192 use next/image directly (NxImage doesn't optimize)
+
+aspectRatio reserves space, preventing CLS (layout shift).
+
+ANTI-PATTERNS:
+  \u2717 <img> with manual onError handling \u2192 NxImage (built-in fallback)
+  \u2717 NxImage without alt for content images (a11y violation)
+  \u2717 NxImage without aspectRatio in fluid layouts \u2192 CLS jank`
+);
 var datePickerPropsSchema = z.object({
   value: z.any().optional().describe("Controlled date value (Date)"),
   defaultValue: z.any().optional().describe("Default date (Date)"),
@@ -778,7 +1609,22 @@ var datePickerPropsSchema = z.object({
   locale: z.enum(["ko", "en"]).default("ko").describe("Calendar locale"),
   formatStr: z.string().default("yyyy-MM-dd").describe("Date format string (date-fns format)"),
   className: z.string().optional().describe("Style override")
-}).describe("DatePicker. Calendar popup for date selection. Based on react-day-picker.");
+}).describe(
+  `DatePicker \u2014 calendar popup for date selection. Based on react-day-picker.
+
+WHEN TO USE:
+  \u2022 Single date selection: birthday, due date, appointment
+  \u2022 Date range \u2192 use two DatePickers with minDate/maxDate cross-bound
+  \u2022 Time selection \u2192 not yet supported; use TextInput with type="time" + DatePicker combo
+  \u2022 Quick relative ranges (Today/Last 7 days) \u2192 DropdownMenu of preset Buttons + DatePicker for "Custom"
+
+minDate/maxDate disable out-of-range dates. locale="ko" for Korean labels.
+
+ANTI-PATTERNS:
+  \u2717 Native <input type="date"> for branded UI (inconsistent across browsers) \u2192 DatePicker
+  \u2717 Free-text date with parsing \u2192 DatePicker (consistent UX)
+  \u2717 DatePicker without minDate for past-date-invalid fields (e.g. booking)`
+);
 var imageUploadPropsSchema = z.object({
   value: z.string().nullable().optional().describe("Controlled image URL (string | null)"),
   defaultValue: z.string().optional().describe("Default image URL"),
@@ -794,7 +1640,19 @@ var imageUploadPropsSchema = z.object({
   size: z.enum(["sm", "md", "lg"]).default("md").describe("Upload area size"),
   className: z.string().optional().describe("Style override")
 }).describe(
-  "ImageUpload. Drag-and-drop image upload with preview, file validation, and field label/description support."
+  `ImageUpload \u2014 drag-and-drop image upload with preview, file-type/size validation, label/description.
+
+WHEN TO USE:
+  \u2022 Single image upload: avatar, cover, KYC document, post thumbnail
+  \u2022 Multiple files / non-image \u2192 not yet supported; build custom or use a file dropzone
+  \u2022 Inline image picker without preview \u2192 custom <input type="file">
+
+accept whitelist + maxSize together cover validation. onError fires with i18n-ready string.
+
+ANTI-PATTERNS:
+  \u2717 <input type="file"> + manual preview \u2192 ImageUpload (handles drag, validation, preview)
+  \u2717 ImageUpload without onError handler \u2192 silent failure on validation reject
+  \u2717 Storing image as data-URL value (use File via onChange and upload to server)`
 );
 
-export { accordionPropsSchema, alertPropsSchema, avatarPropsSchema, badgePropsSchema, breadcrumbPropsSchema, buttonPropsSchema, carouselButtonPropsSchema, carouselDotsPropsSchema, carouselPropsSchema, carouselSlidePropsSchema, checkBoxPropsSchema, chipPropsSchema, clientOnlyPropsSchema, countdownPropsSchema, counterPropsSchema, dataListPropsSchema, datePickerPropsSchema, dividerPropsSchema, drawerClosePropsSchema, drawerContentPropsSchema, drawerDescriptionPropsSchema, drawerPropsSchema, drawerTitlePropsSchema, drawerTriggerPropsSchema, dropdownMenuPropsSchema, ellipsisPropsSchema, emptyStatePropsSchema, errorBoundaryPropsSchema, imageUploadPropsSchema, infiniteScrollPropsSchema, marqueePropsSchema, modalCallSchema, modalTemplatePropsSchema, numberInputPropsSchema, nxImagePropsSchema, paginationPropsSchema, popoverPropsSchema, priceInputPropsSchema, progressPropsSchema, radioGroupPropsSchema, radioItemPropsSchema, selectItemPropsSchema, selectPropsSchema, skeletonPropsSchema, sliderPropsSchema, spinnerPropsSchema, stepperPropsSchema, switchPropsSchema, tabPropsSchema, tablePropsSchema, tableRowPropsSchema, tagInputPropsSchema, tdColumnPropsSchema, textAreaPropsSchema, textInputPropsSchema, themeProviderPropsSchema, toastOptionsSchema, toasterPropsSchema, toggleGroupPropsSchema, tooltipPropsSchema, virtualGridPropsSchema, virtualListPropsSchema };
+export { accordionPropsSchema, alertPropsSchema, avatarPropsSchema, badgePropsSchema, breadcrumbPropsSchema, buttonPropsSchema, carouselButtonPropsSchema, carouselDotsPropsSchema, carouselPropsSchema, carouselSlidePropsSchema, checkBoxPropsSchema, chipPropsSchema, clientOnlyPropsSchema, comboboxOptionDescriptionPropsSchema, comboboxOptionMetaPropsSchema, comboboxOptionPropsSchema, comboboxPropsSchema, countdownPropsSchema, counterPropsSchema, dataGridPropsSchema, dataListPropsSchema, datePickerPropsSchema, dividerPropsSchema, drawerClosePropsSchema, drawerContentPropsSchema, drawerDescriptionPropsSchema, drawerPropsSchema, drawerTitlePropsSchema, drawerTriggerPropsSchema, dropdownMenuPropsSchema, ellipsisPropsSchema, emptyStatePropsSchema, errorBoundaryPropsSchema, imageUploadPropsSchema, infiniteScrollPropsSchema, marqueePropsSchema, modalCallSchema, modalTemplatePropsSchema, numberInputPropsSchema, nxImagePropsSchema, paginationPropsSchema, popoverPropsSchema, priceInputPropsSchema, progressPropsSchema, radioGroupPropsSchema, radioItemPropsSchema, selectItemPropsSchema, selectPropsSchema, skeletonPropsSchema, sliderPropsSchema, spinnerPropsSchema, stepperPropsSchema, switchPropsSchema, tabPropsSchema, tablePropsSchema, tableRowPropsSchema, tagInputPropsSchema, tdColumnPropsSchema, textAreaPropsSchema, textInputPropsSchema, toastOptionsSchema, toasterPropsSchema, toggleGroupPropsSchema, tooltipPropsSchema, virtualGridPropsSchema, virtualListPropsSchema };