@nexus-cross/design-system 1.0.13 → 1.1.0

package/dist/schemas/_all.json

@@ -98,7 +98,7 @@
             "items"
           ],
           "additionalProperties": false,
-          "description": "Accordion. Supports both items array and composable patterns."
+          "description": "Accordion — collapsible content sections (FAQ, settings groups).\n\nWHEN TO USE:\n  • FAQ, help docs, settings groups\n  • Long page where each section is independently scannable\n  • Hidden critical info — DO NOT bury what users always need\n  • Tab-like content switching → Tab (Accordion is for stacked, not exclusive)\n\ntype=\"single\" + collapsible=true → all-closed allowed (recommended for FAQ).\ntype=\"multiple\" → multiple sections open at once.\n\nANTI-PATTERNS:\n  ✗ Hiding the page's primary content inside collapsed Accordion\n  ✗ Single-section Accordion (just show the content)\n  ✗ Custom toggle div + state — use Accordion (gets a11y, keyboard nav)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -147,7 +147,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Alert / Banner. Inline notification with icon, title, description."
+          "description": "Alert — persistent inline notification (banner). Auto icon by variant.\n\nWHEN TO USE:\n  • In-page status: form errors, server warnings, info banners, success confirmation\n  • Transient toast/snackbar → use a toast library, NOT Alert\n  • Modal-blocking error → Modal with semantic=\"danger\"\n  • Inline form field error → use error/description prop on TextInput / Select / etc.\n\nvariant maps to semantic colors. closable=true gives users dismiss control. action prop reserved for inline buttons (e.g. \"Retry\").\n\nANTI-PATTERNS:\n  ✗ Stacking 5 alerts at top of page (use one with summary)\n  ✗ Critical destructive action confirmation in Alert → Modal\n  ✗ Wrapping <div className=\"bg-red-100\"> manually → Alert (a11y role + tokens)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -202,7 +202,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Avatar. Supports image, fallback text, and children."
+          "description": "Avatar — user/entity profile image with text fallback.\n\nWHEN TO USE:\n  • User profiles, comment authors, team member lists, message sender icons\n  • Image fails / not provided → fallback (initials or icon) shown automatically\n  • Need optimized image (Next.js) → pass <Image> via children, omit src\n  • Larger illustration / logo → use NxImage instead\n\nshape=\"square\" for organization/team logos; \"circle\" for people (default).\n\nANTI-PATTERNS:\n  ✗ <img> + manual fallback handling → Avatar (handles error)\n  ✗ Avatar without alt for screen readers (always set alt or aria-label)\n  ✗ Mixing avatar sizes inconsistently in a list — pick one size"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -278,7 +278,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Badge indicator. Dot or count display. Wraps children when provided."
+          "description": "Badge — small status / count indicator overlaid on an anchor (icon, avatar, button).\n\nWHEN TO USE:\n  • Notification count on bell icon\n  • Unread message count on inbox tab\n  • Status dot (online/offline) → dot=true\n  • Status label with text (e.g. \"PRO\", \"NEW\") → Chip variant=\"accent\"\n  • Removable filter token → Chip with onClose\n\ncount={0} hides badge by default; pass showZero=true to keep visible.\n\nANTI-PATTERNS:\n  ✗ Using Badge as standalone label without anchor → Chip\n  ✗ count > 999 without max → ugly layout; default max=99 (\"99+\")\n  ✗ Multiple badges on same anchor (visual noise)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -305,7 +305,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Breadcrumb navigation (compound component pattern). Use <Breadcrumb.Item> children instead of items array. Each Item can wrap arbitrary ReactNode (Link, Select, plain text, etc.)."
+          "description": "Breadcrumb — hierarchical location navigation (Home > Settings > Profile).\n\nWHEN TO USE:\n  • Multi-level information architecture (>=3 levels deep)\n  • Hierarchical category drill-down (file system, taxonomy)\n  • Step-based linear flow → Stepper (not Breadcrumb)\n  • Tab switching → Tab\n  • Single-level navigation → page title alone\n\nCompound pattern: use <Breadcrumb.Item> children. Each Item wraps any ReactNode (Link, Select, plain text). Use maxItems for long paths (auto-collapse with \"…\").\n\nANTI-PATTERNS:\n  ✗ Breadcrumb with 1 level — just show page title\n  ✗ Breadcrumb with > 6 visible items → set maxItems\n  ✗ Last item as a link (it's the current page; should be plain text)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -394,7 +394,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Interactive button. semantic(color) x variant(style) 2-axis system. Rendering element changeable via asChild."
+          "description": "Interactive button (always prefer over native <button>).\n\nWHEN TO USE: any clickable action — submit, navigate (with asChild), open modal, trigger menu.\n2-axis: semantic (color intent) × variant (visual weight). Use semantic=\"primary\" for the page's main CTA, \"danger\" for destructive actions, \"secondary\" for sub actions, \"normal\" for neutral.\n\nANTI-PATTERNS:\n  ✗ <button className=\"bg-blue-500\"> → <Button semantic=\"primary\">\n  ✗ <a className=\"...\"> styled as button → <Button asChild><a href=\"...\"/></Button>\n  ✗ Mixing variants randomly within one row — pick one per visual hierarchy level\n  ✗ Using primary + contained for every button → only ONE primary CTA per view\n  ✗ <Button className=\"!bg-red-500\"> → <Button semantic=\"danger\"> (no !important)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -426,7 +426,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Carousel. Based on Embla Carousel. Sub-components: CarouselSlide, CarouselPrev, CarouselNext, CarouselDots."
+          "description": "Carousel — horizontal slide gallery. Based on Embla Carousel. Compound: CarouselSlide, CarouselPrev/Next, CarouselDots.\n\nWHEN TO USE:\n  • Hero banners, image gallery, product showcase\n  • Multi-card horizontal scroll with snap behavior\n  • Vertical scrolling list → Marquee or VirtualList (not Carousel)\n  • Critical content that must always be visible — Carousel hides slides\n\nopts={{ loop: true, align: 'start' }} for endless loop. Add Embla autoplay plugin for auto-advance.\n\nANTI-PATTERNS:\n  ✗ Critical CTA inside non-first slide (users might never scroll)\n  ✗ Auto-advance without pause-on-hover (a11y)\n  ✗ Manual scroll-snap div → Carousel (gets keyboard nav, indicators)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -558,7 +558,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Checkbox. Native input-based, supports square/round shapes."
+          "description": "Checkbox for multi-select form fields. Native input-based, supports square/round shapes.\n\nWHEN TO USE:\n  • Form field with multiple independent options (T&C agreements, multi-select filters submitted later)\n  • Tri-state (parent-child selection) — use indeterminate prop\n  • Single binary that takes effect immediately → Switch instead\n  • Many options with search → Combobox (multiple)\n\nINDETERMINATE: set indeterminate=true when some children are checked, others not. aria-checked becomes \"mixed\" automatically.\n\nANTI-PATTERNS:\n  ✗ <CheckBox> for \"Enable dark mode\" toggle → <Switch>\n  ✗ Native <input type=\"checkbox\"> + manual styling → <CheckBox>\n  ✗ Forgetting indeterminate for \"select all\" parent"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -613,7 +613,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Chip/tag/badge. Close button displayed via onClose prop."
+          "description": "Chip — small interactive token for filters, tags, removable selections, status labels.\n\nWHEN TO USE:\n  • Filter token / removable selection (set onClose for X button)\n  • Tag/category indicator\n  • Status indicator with color (variant=\"accent\")\n  • Pure count badge → Badge instead\n  • Toggleable filter → ToggleGroup or Chip with onClick + active state\n\nANTI-PATTERNS:\n  ✗ Building dismiss UI manually with custom div + X icon → use onClose prop\n  ✗ Using Chip as a primary CTA → Button\n  ✗ Using Chip for hover-only labels → Tooltip"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -632,7 +632,135 @@
             }
           },
           "additionalProperties": false,
-          "description": "Client-only rendering. Prevents hydration mismatch in SSR environments."
+          "description": "ClientOnly — defers children to client-side render, preventing SSR hydration mismatch.\n\nWHEN TO USE:\n  • Wrap components that read window/document/localStorage at render time\n  • Components depending on browser-only APIs (IntersectionObserver eager init, geolocation)\n  • Server-renderable content → DON'T wrap (loses SEO/SSR perf benefits)\n  • Conditional based on data → use proper SSR-safe state instead\n\nPass fallback to avoid layout shift during hydration.\n\nANTI-PATTERNS:\n  ✗ Wrapping the entire page in ClientOnly (defeats SSR)\n  ✗ ClientOnly without fallback for above-the-fold UI (CLS)\n  ✗ Using ClientOnly to \"fix\" any hydration warning — root-cause the mismatch first"
+        }
+      },
+      "$schema": "http://json-schema.org/draft-07/schema#"
+    },
+    "comboboxOption": {
+      "$ref": "#/definitions/comboboxOptionSchema",
+      "definitions": {
+        "comboboxOptionSchema": {
+          "type": "object",
+          "properties": {
+            "value": {
+              "type": "string",
+              "description": "Option value (unique key)"
+            },
+            "label": {
+              "description": "Display label (string | ReactNode)"
+            },
+            "description": {
+              "description": "Secondary text below label (ReactNode)"
+            },
+            "disabled": {
+              "type": "boolean",
+              "description": "Disabled option"
+            }
+          },
+          "required": [
+            "value"
+          ],
+          "additionalProperties": false,
+          "description": "Single Combobox option."
+        }
+      },
+      "$schema": "http://json-schema.org/draft-07/schema#"
+    },
+    "combobox": {
+      "$ref": "#/definitions/comboboxPropsSchema",
+      "definitions": {
+        "comboboxPropsSchema": {
+          "type": "object",
+          "properties": {
+            "options": {
+              "description": "Available options array (ComboboxOption[], required)"
+            },
+            "value": {
+              "description": "Selected value. string for single, string[] for multiple"
+            },
+            "defaultValue": {
+              "description": "Initial value (uncontrolled)"
+            },
+            "onValueChange": {
+              "description": "Value change callback. (value: string | string[]) => void"
+            },
+            "multiple": {
+              "type": "boolean",
+              "default": false,
+              "description": "Multi-select mode. Selected values shown as chips inside input"
+            },
+            "onSearch": {
+              "description": "Async search callback. (query: string) => void. Triggers external data fetching with debounce"
+            },
+            "searchDebounce": {
+              "type": "number",
+              "default": 250,
+              "description": "Debounce delay (ms) before onSearch fires"
+            },
+            "loading": {
+              "type": "boolean",
+              "default": false,
+              "description": "Externally-controlled loading state. Shows spinner in input suffix"
+            },
+            "filter": {
+              "description": "Custom client-side filter. (option, query) => boolean. Default: case-insensitive label includes match"
+            },
+            "placeholder": {
+              "type": "string",
+              "description": "Input placeholder"
+            },
+            "emptyMessage": {
+              "description": "Message when no options match (string | ReactNode). Default: \"검색 결과 없음\""
+            },
+            "loadingMessage": {
+              "description": "Message during loading state inside popover (string | ReactNode). Default: \"검색 중…\""
+            },
+            "size": {
+              "type": "string",
+              "enum": [
+                "md",
+                "lg",
+                "xl"
+              ],
+              "default": "md",
+              "description": "Input size (matches TextInput tokens)"
+            },
+            "disabled": {
+              "type": "boolean",
+              "description": "Disabled"
+            },
+            "error": {
+              "type": "boolean",
+              "description": "Error state"
+            },
+            "clearable": {
+              "type": "boolean",
+              "default": true,
+              "description": "Show clear button when value(s) exist"
+            },
+            "autoOpenOnFocus": {
+              "type": "boolean",
+              "default": true,
+              "description": "Open popover automatically when input gains focus"
+            },
+            "label": {
+              "description": "Field label (ReactNode)"
+            },
+            "description": {
+              "description": "Helper text below input (ReactNode)"
+            },
+            "className": {
+              "type": "string",
+              "description": "Wrapper className"
+            },
+            "popoverClassName": {
+              "type": "string",
+              "description": "Popover content className"
+            }
+          },
+          "additionalProperties": false,
+          "description": "Searchable select. Text input + popover listbox. Single/multi-select. Sync (auto-filter) or async (onSearch + loading) modes.\n\nWHEN TO USE:\n  • Options ≥ 7, OR labels are long, OR search/filter is needed → Combobox (not Select)\n  • Multi-select form field → Combobox with multiple (chips render inside input)\n  • Async data from server → set onSearch + loading\nFor ≤7 simple options use Select. For free-text tags use TagInput.\n\nASYNC PATTERN:\n  <Combobox options={results} loading={isFetching} onSearch={(q) => mutate(q)} />\n  — onSearch fires after searchDebounce (default 250ms). Do NOT clear input on result update; component preserves user's typing.\n\nIME (Korean/Japanese/Chinese): Enter during composition is ignored automatically — do not add custom keydown handlers.\n\nANTI-PATTERNS:\n  ✗ <Select> with 20 options → <Combobox>\n  ✗ Manual <input> + dropdown div + filter logic → <Combobox>\n  ✗ Setting value externally to clear input mid-typing → use onValueChange instead"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -690,7 +818,7 @@
             "endTimestamp"
           ],
           "additionalProperties": false,
-          "description": "Countdown timer."
+          "description": "Countdown — live timer counting down to endTimestamp (Unix ms).\n\nWHEN TO USE:\n  • Sale ends in / event starts in / token claim window\n  • OTP / verification code expiry\n  • Counting up (since X) → not Countdown; use Counter or custom interval\n  • Persistent server time → pass server-synced endTimestamp (not Date.now offset)\n\nshowDays=false for short timers (<24h) to declutter. Use render prop for fully custom layouts.\n\nANTI-PATTERNS:\n  ✗ Countdown without onEnd handler — UI stuck at 0\n  ✗ Countdown across SSR without hydration safety — pass endTimestamp from server\n  ✗ Updating endTimestamp every render — causes jitter"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -750,7 +878,109 @@
             "endValue"
           ],
           "additionalProperties": false,
-          "description": "Number count animation."
+          "description": "Counter — animated number tick from startValue to endValue.\n\nWHEN TO USE:\n  • Marketing landing — \"10,000+ users\" KPI displays\n  • Stat dashboards (animate when value changes)\n  • Live tickers / real-time data — re-render plain text instead (Counter is one-shot animation)\n  • Currency input / editable number → NumberInput / PriceInput\n\ntriggerOnView=true delays animation until element scrolls into view (good for landing pages).\n\nANTI-PATTERNS:\n  ✗ Counter for values that update frequently — animation queue conflicts\n  ✗ Long duration on critical numbers (users wait to read)\n  ✗ Counter without separator for large numbers (hard to read)"
+        }
+      },
+      "$schema": "http://json-schema.org/draft-07/schema#"
+    },
+    "dataGrid": {
+      "$ref": "#/definitions/dataGridPropsSchema",
+      "definitions": {
+        "dataGridPropsSchema": {
+          "type": "object",
+          "properties": {
+            "list": {
+              "anyOf": [
+                {
+                  "type": "array"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "description": "Data array to render. null = loading state (required)"
+            },
+            "columns": {
+              "anyOf": [
+                {
+                  "type": "number"
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "base": {
+                      "type": "number",
+                      "description": "Default column count (mobile-first)"
+                    },
+                    "sm": {
+                      "type": "number",
+                      "description": ">= 640px"
+                    },
+                    "md": {
+                      "type": "number",
+                      "description": ">= 768px"
+                    },
+                    "lg": {
+                      "type": "number",
+                      "description": ">= 1024px"
+                    },
+                    "xl": {
+                      "type": "number",
+                      "description": ">= 1280px"
+                    },
+                    "2xl": {
+                      "type": "number",
+                      "description": ">= 1536px"
+                    }
+                  },
+                  "additionalProperties": false
+                }
+              ],
+              "description": "Column count. number = fixed | { base, sm, md, lg, xl, 2xl } = responsive (required)"
+            },
+            "gap": {
+              "type": [
+                "number",
+                "string"
+              ],
+              "description": "Item gap. number = px | string = CSS value"
+            },
+            "noDataMessage": {
+              "description": "Message for empty array (string | ReactElement)"
+            },
+            "errorFallback": {
+              "description": "Fallback on error (ReactNode)"
+            },
+            "loadingElement": {
+              "description": "Custom loading element (default: Spinner)"
+            },
+            "skeletonElement": {
+              "description": "Skeleton element during loading (ReactElement)"
+            },
+            "skeletonCount": {
+              "type": "number",
+              "default": 3,
+              "description": "Skeleton repeat count"
+            },
+            "loading": {
+              "type": "boolean",
+              "default": false,
+              "description": "Force loading state"
+            },
+            "children": {
+              "description": "Item render function: ({ item, index }) => ReactNode (required)"
+            },
+            "className": {
+              "type": "string",
+              "description": "Root element style"
+            }
+          },
+          "required": [
+            "list",
+            "columns"
+          ],
+          "additionalProperties": false,
+          "description": "DataGrid — card grid version of DataList with responsive columns. Built-in ErrorBoundary, loading/skeleton/empty/error states.\n\nWHEN TO USE:\n  • Card grids: products, gallery, team members, posts\n  • Need responsive column count → pass { base: 1, sm: 2, lg: 3, xl: 4 }\n  • Single column / row layout → DataList\n  • Tabular data → table component (not DataGrid)\n  • Huge dataset → VirtualGrid\n\nANTI-PATTERNS:\n  ✗ Tabular data forced into card grid (use a table)\n  ✗ Hardcoded column count for responsive layouts → use responsive object\n  ✗ Manual loading/empty handling → DataGrid does it"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -806,7 +1036,7 @@
             "list"
           ],
           "additionalProperties": false,
-          "description": "Data list. Automatically handles loading/skeleton/empty/data states based on list. Built-in ErrorBoundary."
+          "description": "DataList — render-prop list that handles loading / skeleton / empty / error / data in one component. Built-in ErrorBoundary.\n\nWHEN TO USE:\n  • Any async list (<200 items) — feed, comments, dashboard rows\n  • Pass list={null} during loading (auto-shows skeleton/spinner)\n  • Pass list=[] for empty state (auto-shows noDataMessage)\n  • Card grid → DataGrid (same API + columns prop)\n  • Huge dataset → VirtualList\n\nchildren is render fn: ({ item, index }) => ReactNode.\n\nANTI-PATTERNS:\n  ✗ Manual if (loading) {...} else if (!data.length) {...} chains → DataList handles all\n  ✗ DataList without skeletonElement when component shape is known (use Skeleton)\n  ✗ list=undefined (treated as data, not loading) — use null for loading"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -862,7 +1092,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "DatePicker. Calendar popup for date selection. Based on react-day-picker."
+          "description": "DatePicker — calendar popup for date selection. Based on react-day-picker.\n\nWHEN TO USE:\n  • Single date selection: birthday, due date, appointment\n  • Date range → use two DatePickers with minDate/maxDate cross-bound\n  • Time selection → not yet supported; use TextInput with type=\"time\" + DatePicker combo\n  • Quick relative ranges (Today/Last 7 days) → DropdownMenu of preset Buttons + DatePicker for \"Custom\"\n\nminDate/maxDate disable out-of-range dates. locale=\"ko\" for Korean labels.\n\nANTI-PATTERNS:\n  ✗ Native <input type=\"date\"> for branded UI (inconsistent across browsers) → DatePicker\n  ✗ Free-text date with parsing → DatePicker (consistent UX)\n  ✗ DatePicker without minDate for past-date-invalid fields (e.g. booking)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -905,7 +1135,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Divider. Supports horizontal/vertical, solid/dashed/dotted."
+          "description": "Divider — visual separator (horizontal/vertical line).\n\nWHEN TO USE:\n  • Separating sections within a card / list\n  • Vertical separator between inline items (orientation=\"vertical\")\n  • Use color prop sparingly — defaults to border-default token\n  • For grouping form sections, prefer larger spacing over Divider\n  • Tab/Accordion already provide visual separation — don't add Divider\n\nANTI-PATTERNS:\n  ✗ Stacking many Dividers — increase spacing instead\n  ✗ Using Divider as decorative line with bright color → use Tailwind border utility on container\n  ✗ Inline <hr> with custom CSS → Divider (consistent token)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -951,7 +1181,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Drawer/bottom sheet. Based on Vaul. Compound component pattern."
+          "description": "Drawer / bottom sheet. Based on Vaul. Compound component pattern.\n\nWHEN TO USE:\n  • Side panel for secondary action while user can still see main content (filter panel, item details)\n  • Mobile bottom sheet (direction=\"bottom\")\n  • Force decision blocking main flow → Modal instead\n  • Inline anchor-positioned UI → Popover instead\n\nDIRECTION: bottom (default, mobile-friendly), top, left, right.\ndismissible=true (default) allows swipe/outside-click close. Set false for blocking flows.\n\nANTI-PATTERNS:\n  ✗ Drawer for confirmation dialogs → Modal (decision-forcing)\n  ✗ Always shouldScaleBackground → only enable for true mobile bottom-sheets\n  ✗ Forgetting Drawer.Title → required for screen readers (a11y)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -1172,7 +1402,7 @@
             "items"
           ],
           "additionalProperties": false,
-          "description": "Dropdown menu. Based on Radix DropdownMenu. Action menu for context/more menus."
+          "description": "Dropdown menu — list of actions/commands triggered by a button. Based on Radix DropdownMenu (role=\"menu\" + keyboard nav).\n\nWHEN TO USE:\n  • \"More\" / context menu (•••, ⋮)\n  • Action lists where each item triggers a function (save, share, delete)\n  • Selecting a value (form field) → Select / Combobox (not DropdownMenu)\n  • Multi-select toggles → ToggleGroup or CheckBox group\n  • Anchored info panel → Popover\n\nUse danger=true on destructive items (Delete) for visual + semantic emphasis.\nUse separator=true to group related actions.\n\nANTI-PATTERNS:\n  ✗ DropdownMenu for value selection submitted later → Select / Combobox\n  ✗ Custom <div onClick> with isOpen state → DropdownMenu\n  ✗ Long form inputs inside menu items → Popover instead"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -1221,7 +1451,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Text ellipsis. Built-in show more/less toggle."
+          "description": "Ellipsis — clamp long text to N lines with \"show more / less\" toggle.\n\nWHEN TO USE:\n  • Long descriptions in cards, comments, post previews\n  • Single-line truncation only → CSS line-clamp utility (lighter)\n  • Tooltip on hover for full text → Tooltip + truncate utility\n  • Critical content that must be fully readable — don't truncate\n\ntriggerMore/triggerLess accept ReactNode for icons or styled buttons.\n\nANTI-PATTERNS:\n  ✗ Ellipsis on titles / labels — confusing UX\n  ✗ Always-collapsed (defaultShortened=true) for short text — measurement waste\n  ✗ Overriding triggerMore/Less with HTML that breaks accessibility (use button-like)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -1265,7 +1495,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Empty state placeholder. Shown when data is empty or unavailable."
+          "description": "EmptyState — friendly placeholder for empty lists, no search results, first-time setup.\n\nWHEN TO USE:\n  • Empty inbox / list / search results\n  • First-time use (onboarding nudge with action button)\n  • Loading → Skeleton/Spinner (NOT EmptyState)\n  • Error → Alert (or pass icon + title to EmptyState only when conceptually \"nothing here\")\n\nDataList/DataGrid have built-in noDataMessage that wraps EmptyState — use that prop instead of conditional rendering.\n\nANTI-PATTERNS:\n  ✗ Showing EmptyState during loading (confuses users into thinking data is missing)\n  ✗ EmptyState without action when user can fix it (\"Create your first X\" button)\n  ✗ Cluttered EmptyState (too much text/multiple CTAs) — keep one primary action"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -1287,7 +1517,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Error boundary. Catches child component render errors and displays fallback UI."
+          "description": "ErrorBoundary — catches render-time errors in subtree and shows fallback UI.\n\nWHEN TO USE:\n  • Wrap risky areas: third-party widgets, dynamic imports, untrusted content rendering\n  • Async errors / promise rejections → NOT caught (use try/catch in handlers)\n  • Per-route error wrapping → use framework's error.tsx (Next.js) where possible\n\nDataList / DataGrid have ErrorBoundary built-in — don't double-wrap.\n\nANTI-PATTERNS:\n  ✗ ErrorBoundary at app root only — granular boundaries give better UX (one widget fails, page survives)\n  ✗ Showing raw Error.message in production (leak risk) — use friendly fallback\n  ✗ Forgetting onError logging → silent failures in production"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -1370,7 +1600,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "ImageUpload. Drag-and-drop image upload with preview, file validation, and field label/description support."
+          "description": "ImageUpload — drag-and-drop image upload with preview, file-type/size validation, label/description.\n\nWHEN TO USE:\n  • Single image upload: avatar, cover, KYC document, post thumbnail\n  • Multiple files / non-image → not yet supported; build custom or use a file dropzone\n  • Inline image picker without preview → custom <input type=\"file\">\n\naccept whitelist + maxSize together cover validation. onError fires with i18n-ready string.\n\nANTI-PATTERNS:\n  ✗ <input type=\"file\"> + manual preview → ImageUpload (handles drag, validation, preview)\n  ✗ ImageUpload without onError handler → silent failure on validation reject\n  ✗ Storing image as data-URL value (use File via onChange and upload to server)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -1435,7 +1665,7 @@
             "list"
           ],
           "additionalProperties": false,
-          "description": "Infinite scroll. Based on IntersectionObserver."
+          "description": "InfiniteScroll — auto-load more when sentinel enters viewport. Based on IntersectionObserver.\n\nWHEN TO USE:\n  • Feeds, social timelines, search-as-you-scroll\n  • Continuous browsing where total isn't critical\n  • Need jump-to-page → Pagination (not InfiniteScroll)\n  • Need to render 1000s of already-loaded items efficiently → VirtualList\n  • Combine with VirtualList for huge + paginated data\n\nPass either totalCount or hasMore (not both). handleLoadMore is required.\n\nANTI-PATTERNS:\n  ✗ InfiniteScroll without footer/loading element (looks broken at the bottom)\n  ✗ InfiniteScroll without debouncing handleLoadMore — duplicate fetches\n  ✗ Auto-loading critical actions in footer (links, contact) — they become unreachable"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -1484,7 +1714,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Marquee (scrolling text/elements)."
+          "description": "Marquee — endless scrolling content (logo strip, promo banner, news ticker).\n\nWHEN TO USE:\n  • Logo cloud, partner brands strip, social proof\n  • Critical info that must be read → not Marquee (auto-scroll hurts a11y)\n  • Long static list → VirtualList\n  • User-paced gallery → Carousel\n\npauseOnHover=true is recommended whenever content is readable text.\n\nANTI-PATTERNS:\n  ✗ Marquee with action buttons inside (hard to click)\n  ✗ Fast-speed marquee on important text (unreadable, a11y violation)\n  ✗ Multiple Marquees on same page in different directions (visual chaos)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -1610,7 +1840,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Modal template. All modal components must be wrapped with ModalTemplate."
+          "description": "Modal template. All modal components must be wrapped with ModalTemplate.\n\nWHEN TO USE:\n  • Force user decision (delete confirm, submit confirm, blocking dialog)\n  • Long form/flow that needs full attention\n  • Side panel that doesn't block main flow → Drawer instead\n  • Inline contextual UI → Popover instead\n  • Short hint → Tooltip instead\n\nPREFERRED API: use modal() / useModal() imperative API rather than mounting <ModalTemplate> directly. modal() handles stacking, focus return, ESC, and background scroll automatically.\n\nANTI-PATTERNS:\n  ✗ Custom <div className=\"fixed inset-0\"> → modal() (loses focus trap, a11y)\n  ✗ Direct <ModalTemplate> mount in render tree → wrap with modal()\n  ✗ Modal with no title for screen readers → always pass title prop\n  ✗ Multiple modals stacking confusingly → use isAlone:true to close prior modals"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -1823,7 +2053,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "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."
+          "description": "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.\n\nWHEN TO USE:\n  • Any numeric field — quantity, score, age, count\n  • Currency with thousand separators → PriceInput instead\n  • Date / time → DatePicker instead\n\nANTI-PATTERNS:\n  ✗ <TextInput type=\"number\"> → <NumberInput> (loses keyboard ↑↓, step, accelerated long-press, max click)\n  ✗ Custom +/- buttons + <input> → variant=\"bind\" (or numberInputBind for external)\n  ✗ Manual thousand separators for currency → PriceInput"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -1879,7 +2109,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Enhanced image. Lazy loading, fallback, aspect-ratio support."
+          "description": "NxImage — lazy-loaded <img> with fallback, fixed aspect-ratio, object-fit. Always prefer over native <img>.\n\nWHEN TO USE:\n  • Content images: covers, banners, illustrations, hero images\n  • Profile/user avatar (with text fallback) → Avatar\n  • Background image / decorative → CSS bg-image\n  • Need Next.js optimization → use next/image directly (NxImage doesn't optimize)\n\naspectRatio reserves space, preventing CLS (layout shift).\n\nANTI-PATTERNS:\n  ✗ <img> with manual onError handling → NxImage (built-in fallback)\n  ✗ NxImage without alt for content images (a11y violation)\n  ✗ NxImage without aspectRatio in fluid layouts → CLS jank"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -1929,7 +2159,7 @@
             "totalPages"
           ],
           "additionalProperties": false,
-          "description": "Pagination. Previous/next + page number buttons."
+          "description": "Pagination — page-by-page navigation for long datasets.\n\nWHEN TO USE:\n  • User needs to jump to specific pages (search results, blog archives)\n  • Total count is known and stable\n  • Continuous browsing → InfiniteScroll instead\n  • Real-time stream → InfiniteScroll\n  • Both fit → Pagination is more accessible (keyboard, deep-linkable URL)\n\nANTI-PATTERNS:\n  ✗ Pagination with totalPages=1 — hide it\n  ✗ Mixing Pagination + InfiniteScroll on same list (confusing)\n  ✗ Custom page button divs → Pagination (a11y, edge cases like ellipsis)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -1996,7 +2226,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Popover. Based on Radix Popover."
+          "description": "Popover — anchor-positioned panel with interactive content. Based on Radix Popover.\n\nWHEN TO USE:\n  • Trigger-anchored UI with buttons, inputs, or rich content\n  • Filter/option panel near a button (not a full sidebar)\n  • Hover-only text hint → Tooltip (lighter)\n  • Action menu list → DropdownMenu (gives role=menu, keyboard nav)\n  • Decision dialog → Modal\n\nANTI-PATTERNS:\n  ✗ Action lists with onClick handlers → DropdownMenu (a11y semantics)\n  ✗ Implementing dropdown manually with Popover + custom buttons → DropdownMenu\n  ✗ Long forms inside Popover → Drawer or Modal"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -2100,7 +2330,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Price/amount input field with prefix, suffix, balance display, and auto-fill on balance click."
+          "description": "PriceInput — currency / amount input with prefix, suffix, balance display, click-to-fill.\n\nWHEN TO USE:\n  • Money / token amounts: payment, transfer, swap, withdraw\n  • Need balance hint with auto-fill UX (set balance + onBalanceClick)\n  • Pure number (count, age, score) → NumberInput\n  • Generic text → TextInput\n\nseparator=true displays commas; onValueChange always returns raw value (no commas). maxBalance auto-applies error styling on overflow.\n\nANTI-PATTERNS:\n  ✗ <TextInput type=\"number\"> + manual currency formatting → PriceInput\n  ✗ NumberInput for currency (loses prefix/suffix/balance UX)\n  ✗ Using string input for amounts then parseFloat — lose precision; use this component"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -2163,7 +2393,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Progress bar. Linear progress indicator with percentage display."
+          "description": "Progress — linear progress bar (file upload, multi-step form, loading with known %).\n\nWHEN TO USE:\n  • Quantifiable progress (% complete, X of Y)\n  • Unknown duration spinner → Spinner\n  • Stable component shape during load → Skeleton\n  • Step-based navigation → Stepper\n  • Indeterminate (loading without %) → set indeterminate=true\n\nvariant follows semantic colors (success when complete, danger on error).\n\nANTI-PATTERNS:\n  ✗ Indeterminate Progress for short loads (<1s) — Spinner is lighter\n  ✗ Custom <div style={{ width: x% }}> → Progress (a11y, tokens)\n  ✗ Progress without label/showValue when % is critical info"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -2195,6 +2425,15 @@
               "default": "md",
               "description": "Size"
             },
+            "variant": {
+              "type": "string",
+              "enum": [
+                "default",
+                "ring"
+              ],
+              "default": "default",
+              "description": "Visual style. default=outline circle with inner dot, ring=thick border replaces dot when checked"
+            },
             "orientation": {
               "type": "string",
               "enum": [
@@ -2231,7 +2470,7 @@
             "name"
           ],
           "additionalProperties": false,
-          "description": "Radio group. Used with RadioItem."
+          "description": "Radio group for single-choice form fields. Used with RadioItem.\n\nWHEN TO USE:\n  • Form field where user picks ONE of small set (≤4-7) and submits later → RadioGroup\n  • All options should be visible at once for comparison → RadioGroup (not Select)\n  • Immediate effect on selection (no submit) → ToggleGroup instead\n  • Page area switching (tabs) → Tab (not RadioGroup)\n  • Many options → Select / Combobox\n\nVARIANTS:\n  • variant=\"default\" — outline circle with inner dot when checked (classic)\n  • variant=\"ring\" — thick border replaces inner dot when checked (modern, Figma \"ring\" style)\n\nANTI-PATTERNS:\n  ✗ Using RadioGroup for tab-like content switching → Tab\n  ✗ Using RadioGroup for immediate filters → ToggleGroup\n  ✗ Mixing RadioGroup and ToggleGroup in same form → pick one pattern\n  ✗ Native <input type=\"radio\"> → RadioItem (gets a11y, focus ring, tokens)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -2254,9 +2493,20 @@
               ],
               "description": "Size (overrides group)"
             },
+            "variant": {
+              "type": "string",
+              "enum": [
+                "default",
+                "ring"
+              ],
+              "description": "Visual style (overrides group)"
+            },
             "label": {
               "description": "Label text (ReactNode)"
             },
+            "description": {
+              "description": "Help text shown beneath the label (ReactNode)"
+            },
             "children": {
               "description": "Label alternative content (ReactNode)"
             },
@@ -2335,7 +2585,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Dropdown select. Based on Radix Select. Used with SelectItem."
+          "description": "Dropdown select for short option lists. Based on Radix Select. Used with SelectItem.\n\nWHEN TO USE:\n  • Options ≤ 7, no search needed → Select\n  • Options ≥ 7 OR search needed OR async → Combobox instead\n  • Need multi-select → Combobox (multiple)\n  • Action menu (save/delete/share) → DropdownMenu (not Select; values vs actions)\n\nANTI-PATTERNS:\n  ✗ Select with 20+ options → Combobox\n  ✗ Using Select for menu items that trigger functions → DropdownMenu\n  ✗ Manual <select> styling → Select gives consistent token styling\n  ✗ Wrapping each SelectItem with Tooltip — instead put hint in item label"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -2417,7 +2667,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Skeleton loading placeholder. Size/shape via className. With children, wraps transparently to maintain actual size."
+          "description": "Skeleton loading placeholder. Size/shape via className. With children, wraps transparently to maintain actual size.\n\nWHEN TO USE:\n  • Long load with known component shape (cards, lists, profile headers)\n  • Reduces perceived wait time when layout is predictable\n  • Short loads (<1s) → Spinner\n  • Quantifiable progress → Progress\n  • DataList/DataGrid loading → set list={null} (uses skeletonElement prop automatically)\n\nGOLDEN RULE: Skeleton must match the real component's shape and size. Mismatch causes layout shift.\n\nANTI-PATTERNS:\n  ✗ Generic gray rectangle for everything → match real component shape\n  ✗ Skeleton for instant loads (causes flash)\n  ✗ Many skeletons of different shapes when component is uniform → use a single skeleton in DataList"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -2495,7 +2745,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Slider / Range input. Based on Radix Slider. Supports single and range mode."
+          "description": "Slider — numeric range selector. Based on Radix Slider. Single thumb or range (two thumbs).\n\nWHEN TO USE:\n  • Continuous range with visual feedback: volume, brightness, price filter\n  • Range filter (min-max) → defaultValue=[20, 80]\n  • Precise number entry → NumberInput\n  • Discrete few options → ToggleGroup or RadioGroup\n  • Boolean → Switch\n\nstep controls increments. onValueCommit fires only after pointer release (good for expensive recomputations).\n\nANTI-PATTERNS:\n  ✗ Slider for required precise input (typing 47 is faster than dragging)\n  ✗ Long step count without showValue / labels (users have no reference)\n  ✗ Calling expensive API on every onValueChange tick → use onValueCommit"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -2529,7 +2779,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Loading indicator. SVG-based. Built-in role=\"status\"."
+          "description": "Loading indicator (spinner). SVG-based. role=\"status\" + aria-label built-in.\n\nWHEN TO USE:\n  • Short loads (<1s), inline indicator (button content while submitting)\n  • Long loads with known structure → Skeleton (better perceived performance)\n  • Quantifiable progress → Progress\n  • Page-level loading boundary inside DataList/DataGrid → use their loading prop instead\n\nANTI-PATTERNS:\n  ✗ Custom CSS spinning div → Spinner (a11y + tokens)\n  ✗ Using Spinner where Skeleton fits (long loads with stable layout)\n  ✗ Forgetting aria-label override when meaning differs from \"Loading\""
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -2602,7 +2852,7 @@
             "steps"
           ],
           "additionalProperties": false,
-          "description": "Stepper. Step-by-step progress indicator."
+          "description": "Stepper — multi-step linear flow indicator (checkout, onboarding, wizard).\n\nWHEN TO USE:\n  • Sequential workflow with finite steps (3-7)\n  • Show user's current position in flow + completed/upcoming steps\n  • Independent navigation between unrelated sections → Tab\n  • Continuous % progress → Progress\n  • Hierarchy / location → Breadcrumb\n\nstatus=\"error\" highlights the current step with danger color when validation fails.\n\nANTI-PATTERNS:\n  ✗ Stepper with 2 steps (use Progress or just navigation)\n  ✗ Stepper with 10+ steps (overwhelming) — chunk into sub-flows\n  ✗ Letting users skip ahead by clicking future steps (only mark completed → current is allowed)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -2654,7 +2904,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Toggle switch. Native checkbox-based, role=\"switch\"."
+          "description": "Toggle switch for immediate on/off binary state. Native checkbox-based, role=\"switch\".\n\nWHEN TO USE:\n  • Setting that takes effect immediately (notifications on/off, dark mode)\n  • Binary state with no submit step\n  • Form field submitted later → CheckBox instead (semantics: checkbox is form data)\n  • Multiple related options → CheckBox group or ToggleGroup (multiple)\n\nANTI-PATTERNS:\n  ✗ <CheckBox> for \"Enable notifications\" toggle → <Switch>\n  ✗ <Switch> inside form requiring submit → <CheckBox>\n  ✗ Wrapping Switch in <label onClick> manually → use label prop or htmlFor pattern"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -2743,7 +2993,7 @@
             "items"
           ],
           "additionalProperties": false,
-          "description": "Tab navigation. line/pill variants."
+          "description": "Tab navigation — switch between content panels (settings sections, profile views).\n\nWHEN TO USE:\n  • Page area swap where only one panel is visible at a time\n  • Mutually exclusive content with stable section labels\n  • Form field selection → RadioGroup (semantics: not navigation)\n  • Immediate filter/option toggle → ToggleGroup\n  • Stacked collapsible sections → Accordion\n\ndestroyInactive=true unmounts hidden panels (saves memory but loses state).\n\nANTI-PATTERNS:\n  ✗ Tab with 1 item — just render the panel\n  ✗ Tab with 8+ items — consider sub-routing or DropdownMenu\n  ✗ Using Tab for form value selection → RadioGroup\n  ✗ Custom <button> + onClick + state → Tab (a11y, keyboard, focus management)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -2818,7 +3068,7 @@
             "list"
           ],
           "additionalProperties": false,
-          "description": "Table. Column definitions via TdColumn, row wrapping via TableRow. Built-in sorting/skeleton loading."
+          "description": "Table — tabular data with sortable columns, skeleton/loading/empty states. Compound: TableRow + TdColumn.\n\nWHEN TO USE:\n  • Comparable structured data (financial reports, transaction history, leaderboard)\n  • Sortable per-column → enableSorting on TdColumn\n  • Card-style entities → DataGrid\n  • Single-column read-only list → DataList\n  • Huge dataset (>500 rows) → wrap with VirtualList logic or paginate\n\nlist={null} → loading state. list=[] → noDataMsg. children: ({ item, index }) => <TableRow>...</TableRow>.\n\nANTI-PATTERNS:\n  ✗ Native <table> + manual loading/empty handling → Table component\n  ✗ Forcing card-style data into Table (use DataGrid)\n  ✗ Sorting in client when server pagination is in use → server-side sort"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -2850,7 +3100,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Table row. Used inside Table."
+          "description": "TableRow — a single row inside Table. Wraps TdColumn cells.\n\nWHEN TO USE:\n  • variant=\"accent\" highlights selected/current row\n  • onClick for row-level navigation (e.g. open detail page)\n  • Per-row checkbox/action → place inside a TdColumn child"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -2957,7 +3207,7 @@
             "fieldId"
           ],
           "additionalProperties": false,
-          "description": "Table cell/column definition. Used inside TableRow."
+          "description": "TdColumn — table cell. Drives both <th> and <td> for the column. Provides sorting, alignment, overflow handling.\n\nWHEN TO USE:\n  • textOverflow=\"truncate\" (default) for fixed-width columns; \"wrap\" for narrative\n  • align=\"right\" for numeric/currency columns (a11y readability)\n  • enableSorting=true when column is sortable; supply order + handleClickSort for controlled sort\n  • highlightKey to group columns that highlight together on hover\n\nANTI-PATTERNS:\n  ✗ enableSorting without handleClickSort → sort indicator is dead\n  ✗ align=\"left\" for currency/number columns\n  ✗ Mixing text and numeric in one column without consistent align"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -3027,7 +3277,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Tag input. Enter key to add, Backspace to delete last tag."
+          "description": "TagInput — free-form multi-value entry (Enter to add, Backspace to remove last).\n\nWHEN TO USE:\n  • Free-form labels: skills, hashtags, email recipients, keywords\n  • Predefined options → Combobox with multi-select (NOT TagInput)\n  • Single value → TextInput\n  • Limited options → Select / RadioGroup / Checkbox\n\nallowDuplicates=false (default) prevents repeats. Use max to cap count.\n\nANTI-PATTERNS:\n  ✗ TagInput for predefined taxonomy → Combobox (controlled options)\n  ✗ TagInput without max for spam-prone fields\n  ✗ Custom comma-split string field → TagInput (proper UX + a11y)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -3129,7 +3379,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Multi-line text input with label, description, character counter, and resize modes."
+          "description": "Multi-line text input. Always prefer over native <textarea>.\n\nWHEN TO USE:\n  • Long-form text — comments, descriptions, memos, bios\n  • Single-line input → TextInput\n  • Numeric → NumberInput\n\nresize=\"auto\" auto-grows with content (great for chat input). resize=\"none\" locks size for fixed UI.\n\nANTI-PATTERNS:\n  ✗ Native <textarea> + custom counter → showCount + maxLength\n  ✗ <TextArea> for short labels — use TextInput (smaller affordance)\n  ✗ Wrapping with custom <label>/<p> → use built-in label/description props (auto a11y binding)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -3236,72 +3486,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Text input field. Supports label, description, prefix/suffix icons, clearable, character counter."
-        }
-      },
-      "$schema": "http://json-schema.org/draft-07/schema#"
-    },
-    "themeProvider": {
-      "$ref": "#/definitions/themeProviderPropsSchema",
-      "definitions": {
-        "themeProviderPropsSchema": {
-          "type": "object",
-          "properties": {
-            "children": {
-              "description": "App root element (ReactNode, required)"
-            },
-            "defaultTheme": {
-              "type": "string",
-              "description": "Default theme (e.g. \"dark\", \"light\")"
-            },
-            "storageKey": {
-              "type": "string",
-              "description": "localStorage storage key (default: \"theme\")"
-            },
-            "themes": {
-              "type": "array",
-              "items": {
-                "type": "string"
-              },
-              "description": "Available theme list (default: [\"light\", \"dark\"])"
-            },
-            "attribute": {
-              "anyOf": [
-                {
-                  "type": "string"
-                },
-                {
-                  "type": "array",
-                  "items": {
-                    "type": "string"
-                  }
-                }
-              ],
-              "description": "Theme HTML attribute (default: \"data-theme\")"
-            },
-            "enableSystem": {
-              "type": "boolean",
-              "description": "Enable system theme detection"
-            },
-            "disableTransitionOnChange": {
-              "type": "boolean",
-              "description": "Disable transitions on theme change"
-            },
-            "forcedTheme": {
-              "type": "string",
-              "description": "Forced theme (user cannot change)"
-            },
-            "enableColorScheme": {
-              "type": "boolean",
-              "description": "Auto-set color-scheme CSS property"
-            },
-            "nonce": {
-              "type": "string",
-              "description": "CSP nonce"
-            }
-          },
-          "additionalProperties": false,
-          "description": "Theme provider. Based on next-themes. Access theme state via useTheme() hook."
+          "description": "Single-line text input (always prefer over native <input type=\"text\">).\n\nWHEN TO USE: any short text — name, email, search, URL, password.\nUse the built-in label/description props instead of wrapping with your own <label>/<p> tags (auto-binds htmlFor/aria-describedby for accessibility).\nFor numeric input use NumberInput; for currency PriceInput; for long text TextArea; for date DatePicker.\n\nANTI-PATTERNS:\n  ✗ <TextInput type=\"number\"> → <NumberInput> (gives unit, step, ↑↓ keys)\n  ✗ <label>Email <input ...></label> + <p>helper</p> → <TextInput label=\"Email\" description=\"helper\">\n  ✗ Custom red border for error → use error prop (auto aria-invalid + token color)\n  ✗ Manual character counter → use showCount + maxLength\n  ✗ Manual clear X button → use clearable prop"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -3382,7 +3567,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "toast() call options. Used as toast(message, options). Fully customizable via toast.custom(jsx)."
+          "description": "toast() options. Used as toast(message, options) / toast.success / .error / .warning / .info / .promise / .custom(jsx).\n\nWHEN TO USE TOAST:\n  • Transient feedback after user action: \"Saved\", \"Copied\", \"Network error\"\n  • Persistent in-page banner → Alert\n  • Critical destructive confirmation → Modal (toast can be missed)\n  • Form field error → use error/description prop on the input\n\nrichColors=true gives strong success/error/warning/info colors. Use action for \"Undo\" patterns.\n\nANTI-PATTERNS:\n  ✗ Toast for confirmation that user MUST acknowledge → Modal\n  ✗ Stacking many toasts → set visibleToasts on Toaster\n  ✗ Long-form content in toast (toast is for short messages)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -3458,7 +3643,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Toaster config. Place once at app root. Display notifications via toast(). Based on sonner."
+          "description": "Toaster — toast container. Mount ONCE at app root. Then call toast() anywhere. Based on sonner.\n\nWHEN TO USE:\n  • Mount in app shell (layout.tsx / _app.tsx) — exactly one instance globally\n  • Set position once here; per-toast position only when needed\n  • Provide visibleToasts cap to avoid stacking\n\nANTI-PATTERNS:\n  ✗ Multiple Toasters across pages — only one global Toaster\n  ✗ Mounting Toaster inside conditional render — toasts vanish on remount\n  ✗ Forgetting Toaster mount — toast() calls do nothing"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -3523,10 +3708,11 @@
               "enum": [
                 "default",
                 "primary",
-                "secondary"
+                "secondary",
+                "outline"
               ],
               "default": "default",
-              "description": "Style variant (default=slider, primary=accent filled, secondary=accent filled)"
+              "description": "Style variant (default=slider, primary/secondary=accent filled, outline=bordered buttons with no background)"
             },
             "size": {
               "type": "string",
@@ -3538,6 +3724,11 @@
               "default": "md",
               "description": "Size"
             },
+            "fullWidth": {
+              "type": "boolean",
+              "default": false,
+              "description": "Stretch the group to parent width and split items equally"
+            },
             "disabled": {
               "type": "boolean",
               "description": "Disable all items"
@@ -3556,7 +3747,7 @@
             "items"
           ],
           "additionalProperties": false,
-          "description": "Toggle group / Segment control. Based on Radix ToggleGroup."
+          "description": "Toggle group / Segment control for immediate-effect option selection. Based on Radix ToggleGroup.\n\nWHEN TO USE:\n  • Sort order, view mode (grid/list), filter chips — selection takes effect immediately\n  • Visual comparison important (icons or short labels)\n  • Form field that submits later → RadioGroup or CheckBox instead\n  • Page area switching (settings tabs) → Tab instead\n\nVARIANTS:\n  • default — slider-style background (sleek)\n  • primary / secondary — accent-filled selected state\n  • outline — bordered buttons with no background (button-style toolbar)\n\nfullWidth=true distributes items equally across parent width (use with outline variant for button-row look).\n\ntype=\"single\" requires at least one selection by default (required=true). Set required=false to allow deselection.\n\nANTI-PATTERNS:\n  ✗ Using ToggleGroup for content tabs → Tab\n  ✗ Using ToggleGroup as form field submitted later → RadioGroup (semantics + a11y)\n  ✗ Mixing icons and text labels of different sizes — keep visual rhythm consistent"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -3623,7 +3814,7 @@
             }
           },
           "additionalProperties": false,
-          "description": "Tooltip. Based on Radix Tooltip. Built-in Provider."
+          "description": "Tooltip — short text hint shown on hover/focus. Based on Radix Tooltip. Provider built-in.\n\nWHEN TO USE:\n  • Brief explanation of an icon button or truncated label\n  • Hover-only, non-interactive content (text only)\n  • Need clickable content inside → Popover (not Tooltip)\n  • Action menu → DropdownMenu\n  • Force user attention → Modal\n\nANTI-PATTERNS:\n  ✗ Buttons/links inside content → use Popover (Tooltip not focusable)\n  ✗ Long paragraphs in tooltip → consider Popover or Drawer\n  ✗ Tooltip on disabled buttons (won't show in some browsers) — wrap in span instead\n  ✗ Critical info only in tooltip — duplicate visible elsewhere for mobile/touch"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -3680,7 +3871,7 @@
             "items"
           ],
           "additionalProperties": false,
-          "description": "Virtual scroll list. Based on @tanstack/react-virtual."
+          "description": "VirtualList — performant rendering of huge lists (1000+ items). Based on @tanstack/react-virtual.\n\nWHEN TO USE:\n  • Large datasets (>200 rows): chat history, transactions, logs, leaderboard\n  • Stable item height (or measurable per-item via estimateSize fn)\n  • Small list (<100 items) → DataList (much simpler API)\n  • Grid layout → VirtualGrid\n  • Server-side pagination → InfiniteScroll wrapping plain list\n\nestimateSize is critical — wrong values cause scroll jumps. Pair with onEndReached for server pagination.\n\nANTI-PATTERNS:\n  ✗ VirtualList for short lists (DataList is simpler and renders faster)\n  ✗ Variable estimateSize for uniform items — use a single number\n  ✗ Putting interactive overlays inside virtual rows (mounted/unmounted on scroll)"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"
@@ -3742,7 +3933,7 @@
             "columns"
           ],
           "additionalProperties": false,
-          "description": "Virtual scroll grid. Based on @tanstack/react-virtual."
+          "description": "VirtualGrid — performant grid for huge lists. Based on @tanstack/react-virtual.\n\nWHEN TO USE:\n  • Image gallery / card grid with 200+ items\n  • Fixed column count (responsive via JS — recompute columns on breakpoint)\n  • Small grid → DataGrid (no virtualization, simpler API)\n  • Single-column list → VirtualList\n\nANTI-PATTERNS:\n  ✗ VirtualGrid with <50 items — DataGrid is simpler\n  ✗ Cards with hover-expanding height (breaks virtualization)\n  ✗ Forgetting to recompute columns on resize → visible empty space"
         }
       },
       "$schema": "http://json-schema.org/draft-07/schema#"