@nexus-cross/design-system 1.0.13 → 1.1.0

package/cursor-rules/nexus-ui-api.mdc

@@ -12,7 +12,17 @@ All components are imported from `@nexus-cross/design-system`.
 
 ## Button
 
-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 — submit, navigate (with asChild), open modal, trigger menu.
+2-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.
+
+ANTI-PATTERNS:
+  ✗ <button className="bg-blue-500"> → <Button semantic="primary">
+  ✗ <a className="..."> styled as button → <Button asChild><a href="..."/></Button>
+  ✗ Mixing variants randomly within one row — pick one per visual hierarchy level
+  ✗ Using primary + contained for every button → only ONE primary CTA per view
+  ✗ <Button className="!bg-red-500"> → <Button semantic="danger"> (no !important)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -59,7 +69,18 @@ Interactive button. semantic(color) x variant(style) 2-axis system. Rendering el
 
 ## TextInput
 
-Text input field. Supports label, description, prefix/suffix icons, clearable, character counter.
+Single-line text input (always prefer over native <input type="text">).
+
+WHEN TO USE: any short text — 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:
+  ✗ <TextInput type="number"> → <NumberInput> (gives unit, step, ↑↓ keys)
+  ✗ <label>Email <input ...></label> + <p>helper</p> → <TextInput label="Email" description="helper">
+  ✗ Custom red border for error → use error prop (auto aria-invalid + token color)
+  ✗ Manual character counter → use showCount + maxLength
+  ✗ Manual clear X button → use clearable prop
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -119,7 +140,19 @@ Text input field. Supports label, description, prefix/suffix icons, clearable, c
 
 ## TextArea
 
-Multi-line text input with label, description, character counter, and resize modes.
+Multi-line text input. Always prefer over native <textarea>.
+
+WHEN TO USE:
+  • Long-form text — comments, descriptions, memos, bios
+  • Single-line input → TextInput
+  • Numeric → NumberInput
+
+resize="auto" auto-grows with content (great for chat input). resize="none" locks size for fixed UI.
+
+ANTI-PATTERNS:
+  ✗ Native <textarea> + custom counter → showCount + maxLength
+  ✗ <TextArea> for short labels — use TextInput (smaller affordance)
+  ✗ Wrapping with custom <label>/<p> → use built-in label/description props (auto a11y binding)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -158,7 +191,19 @@ Multi-line text input with label, description, character counter, and resize mod
 
 ## Select
 
-Dropdown select. Based on Radix Select. Used with SelectItem.
+Dropdown select for short option lists. Based on Radix Select. Used with SelectItem.
+
+WHEN TO USE:
+  • Options ≤ 7, no search needed → Select
+  • Options ≥ 7 OR search needed OR async → Combobox instead
+  • Need multi-select → Combobox (multiple)
+  • Action menu (save/delete/share) → DropdownMenu (not Select; values vs actions)
+
+ANTI-PATTERNS:
+  ✗ Select with 20+ options → Combobox
+  ✗ Using Select for menu items that trigger functions → DropdownMenu
+  ✗ Manual <select> styling → Select gives consistent token styling
+  ✗ Wrapping each SelectItem with Tooltip — instead put hint in item label
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -194,9 +239,153 @@ Individual option within Select.
 
 ---
 
+## Combobox
+
+Searchable select. Text input + popover listbox. Single/multi-select. Sync (auto-filter) or async (onSearch + loading) modes.
+
+WHEN TO USE:
+  • Options ≥ 7, OR labels are long, OR search/filter is needed → Combobox (not Select)
+  • Multi-select form field → Combobox with multiple (chips render inside input)
+  • Async data from server → set onSearch + loading
+For ≤7 simple options use Select. For free-text tags use TagInput.
+
+ASYNC PATTERN:
+  <Combobox options={results} loading={isFetching} onSearch={(q) => mutate(q)} />
+  — 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 — do not add custom keydown handlers.
+
+ANTI-PATTERNS:
+  ✗ <Select> with 20 options → <Combobox>
+  ✗ Manual <input> + dropdown div + filter logic → <Combobox>
+  ✗ Setting value externally to clear input mid-typing → use onValueChange instead
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `options` | `ReactNode` | - | Available options array (ComboboxOption[], required) |
+| `value` | `ReactNode` | - | Selected value. string for single, string[] for multiple |
+| `defaultValue` | `ReactNode` | - | Initial value (uncontrolled) |
+| `onValueChange` | `ReactNode` | - | Value change callback. (value: string | string[]) => void |
+| `multiple` | `boolean` | `false` | Multi-select mode. Selected values shown as chips inside input |
+| `onSearch` | `ReactNode` | - | Async search callback. (query: string) => void. Triggers external data fetching with debounce |
+| `searchDebounce` | `number` | `250` | Debounce delay (ms) before onSearch fires |
+| `loading` | `boolean` | `false` | Externally-controlled loading state. Shows spinner in input suffix |
+| `filter` | `ReactNode` | - | Custom client-side filter. (option, query) => boolean. Default: case-insensitive label includes match |
+| `placeholder` | `string` | - | Input placeholder |
+| `emptyMessage` | `ReactNode` | - | Message when no options match (string | ReactNode). Default: "검색 결과 없음" |
+| `loadingMessage` | `ReactNode` | - | Message during loading state inside popover (string | ReactNode). Default: "검색 중…" |
+| `size` | `'md'` \| `'lg'` \| `'xl'` | `"md"` | Input size (matches TextInput tokens) |
+| `disabled` | `boolean` | - | Disabled |
+| `error` | `boolean` | - | Error state |
+| `clearable` | `boolean` | `true` | Show clear button when value(s) exist |
+| `autoOpenOnFocus` | `boolean` | `true` | Open popover automatically when input gains focus |
+| `label` | `ReactNode` | - | Field label (ReactNode) |
+| `description` | `ReactNode` | - | Helper text below input (ReactNode) |
+| `className` | `string` | - | Wrapper className |
+| `popoverClassName` | `string` | - | Popover content className |
+
+### ComboboxOption
+
+Single Combobox option.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | - | Option value (unique key) |
+| `label` | `ReactNode` | - | Display label (string | ReactNode) |
+| `description` | `ReactNode` | - | Secondary text below label (ReactNode) |
+| `disabled` | `boolean` | - | Disabled option |
+
+Searchable select with popover listbox. Supports single/multi-select and sync (auto-filter) / async (onSearch + loading) modes. **WAI-ARIA Combobox pattern** (Radix Popover under the hood — NOT Radix Select).
+
+- **Sync mode** (no `onSearch` prop): client-side filters `options` by typed query (case-insensitive label includes match by default; override via `filter`).
+- **Async mode** (provide `onSearch`): debounced (`searchDebounce`, default 250ms) callback fires for external data fetch. Set `loading` to show spinner in the input suffix.
+- **Multi-select** (`multiple`): selected values render as removable chips inside the input. Backspace on empty input removes the last chip.
+- Keyboard: Arrow Up/Down, Home/End, Enter to select, Escape to close.
+
+```tsx
+// 1) Sync — auto-filter local options
+const COUNTRIES = [
+  { value: 'kr', label: '한국' },
+  { value: 'jp', label: '일본' },
+  { value: 'us', label: '미국' },
+];
+
+<Combobox
+  options={COUNTRIES}
+  value={value}
+  onValueChange={setValue}
+  placeholder="국가 선택"
+/>
+
+// 2) Async — external search w/ loading spinner
+const [results, setResults] = useState<ComboboxOption[]>([]);
+const [loading, setLoading] = useState(false);
+
+const handleSearch = async (q: string) => {
+  if (!q) return setResults([]);
+  setLoading(true);
+  const users = await fetchUsers(q);
+  setResults(users.map((u) => ({ value: u.id, label: u.name, description: u.email })));
+  setLoading(false);
+};
+
+<Combobox
+  options={results}
+  loading={loading}
+  onSearch={handleSearch}
+  value={selectedId}
+  onValueChange={setSelectedId}
+  placeholder="유저 검색…"
+  emptyMessage="검색 결과 없음"
+/>
+
+// 3) Multi-select with chips
+<Combobox
+  multiple
+  options={results}
+  value={selectedIds}
+  onValueChange={setSelectedIds}
+  loading={loading}
+  onSearch={handleSearch}
+/>
+
+// 4) With label / description / error
+<Combobox
+  label="담당자"
+  description="검색 후 선택하세요"
+  options={results}
+  loading={loading}
+  onSearch={handleSearch}
+  value={value}
+  onValueChange={setValue}
+  error={!value}
+  size="lg"
+/>
+```
+
+**When to use `Select` vs `Combobox`**:
+- Fixed short list, no search needed → `Select`
+- Long list / async search / typed input → `Combobox`
+- Free-form tag input (any string) → `TagInput`
+
+---
+
 ## CheckBox
 
-Checkbox. Native input-based, supports square/round shapes.
+Checkbox for multi-select form fields. Native input-based, supports square/round shapes.
+
+WHEN TO USE:
+  • Form field with multiple independent options (T&C agreements, multi-select filters submitted later)
+  • Tri-state (parent-child selection) — use indeterminate prop
+  • Single binary that takes effect immediately → Switch instead
+  • Many options with search → Combobox (multiple)
+
+INDETERMINATE: set indeterminate=true when some children are checked, others not. aria-checked becomes "mixed" automatically.
+
+ANTI-PATTERNS:
+  ✗ <CheckBox> for "Enable dark mode" toggle → <Switch>
+  ✗ Native <input type="checkbox"> + manual styling → <CheckBox>
+  ✗ Forgetting indeterminate for "select all" parent
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -229,7 +418,24 @@ Checkbox. Native input-based, supports square/round shapes.
 
 ## RadioGroup
 
-Radio group. Used with RadioItem.
+Radio group for single-choice form fields. Used with RadioItem.
+
+WHEN TO USE:
+  • Form field where user picks ONE of small set (≤4-7) and submits later → RadioGroup
+  • All options should be visible at once for comparison → RadioGroup (not Select)
+  • Immediate effect on selection (no submit) → ToggleGroup instead
+  • Page area switching (tabs) → Tab (not RadioGroup)
+  • Many options → Select / Combobox
+
+VARIANTS:
+  • variant="default" — outline circle with inner dot when checked (classic)
+  • variant="ring" — thick border replaces inner dot when checked (modern, Figma "ring" style)
+
+ANTI-PATTERNS:
+  ✗ Using RadioGroup for tab-like content switching → Tab
+  ✗ Using RadioGroup for immediate filters → ToggleGroup
+  ✗ Mixing RadioGroup and ToggleGroup in same form → pick one pattern
+  ✗ Native <input type="radio"> → RadioItem (gets a11y, focus ring, tokens)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -237,6 +443,7 @@ Radio group. Used with RadioItem.
 | `value` | `string` | - | Selected value (controlled) |
 | `defaultValue` | `string` | - | Initial value (uncontrolled) |
 | `size` | `'sm'` \| `'md'` | `"md"` | Size |
+| `variant` | `'default'` \| `'ring'` | `"default"` | Visual style. default=outline circle with inner dot, ring=thick border replaces dot when checked |
 | `orientation` | `'horizontal'` \| `'vertical'` | `"vertical"` | Layout direction |
 | `disabled` | `boolean` | - | Disabled |
 | `children` | `ReactNode` | - | RadioItem list (ReactNode, required) |
@@ -253,7 +460,9 @@ Individual option within RadioGroup.
 |---|---|---|---|
 | `value` | `string` | - | Item value (required) |
 | `size` | `'sm'` \| `'md'` | - | Size (overrides group) |
+| `variant` | `'default'` \| `'ring'` | - | Visual style (overrides group) |
 | `label` | `ReactNode` | - | Label text (ReactNode) |
+| `description` | `ReactNode` | - | Help text shown beneath the label (ReactNode) |
 | `children` | `ReactNode` | - | Label alternative content (ReactNode) |
 | `disabled` | `boolean` | - | Disabled |
 | `className` | `string` | - | Style override |
@@ -276,7 +485,18 @@ Individual option within RadioGroup.
 
 ## Switch
 
-Toggle switch. Native checkbox-based, role="switch".
+Toggle switch for immediate on/off binary state. Native checkbox-based, role="switch".
+
+WHEN TO USE:
+  • Setting that takes effect immediately (notifications on/off, dark mode)
+  • Binary state with no submit step
+  • Form field submitted later → CheckBox instead (semantics: checkbox is form data)
+  • Multiple related options → CheckBox group or ToggleGroup (multiple)
+
+ANTI-PATTERNS:
+  ✗ <CheckBox> for "Enable notifications" toggle → <Switch>
+  ✗ <Switch> inside form requiring submit → <CheckBox>
+  ✗ Wrapping Switch in <label onClick> manually → use label prop or htmlFor pattern
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -298,7 +518,19 @@ Toggle switch. Native checkbox-based, role="switch".
 
 ## Chip
 
-Chip/tag/badge. Close button displayed via onClose prop.
+Chip — small interactive token for filters, tags, removable selections, status labels.
+
+WHEN TO USE:
+  • Filter token / removable selection (set onClose for X button)
+  • Tag/category indicator
+  • Status indicator with color (variant="accent")
+  • Pure count badge → Badge instead
+  • Toggleable filter → ToggleGroup or Chip with onClick + active state
+
+ANTI-PATTERNS:
+  ✗ Building dismiss UI manually with custom div + X icon → use onClose prop
+  ✗ Using Chip as a primary CTA → Button
+  ✗ Using Chip for hover-only labels → Tooltip
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -326,7 +558,18 @@ Chip/tag/badge. Close button displayed via onClose prop.
 
 ## Spinner
 
-Loading indicator. SVG-based. Built-in role="status".
+Loading indicator (spinner). SVG-based. role="status" + aria-label built-in.
+
+WHEN TO USE:
+  • Short loads (<1s), inline indicator (button content while submitting)
+  • Long loads with known structure → Skeleton (better perceived performance)
+  • Quantifiable progress → Progress
+  • Page-level loading boundary inside DataList/DataGrid → use their loading prop instead
+
+ANTI-PATTERNS:
+  ✗ Custom CSS spinning div → Spinner (a11y + tokens)
+  ✗ Using Spinner where Skeleton fits (long loads with stable layout)
+  ✗ Forgetting aria-label override when meaning differs from "Loading"
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -348,6 +591,20 @@ Loading indicator. SVG-based. Built-in role="status".
 
 Skeleton loading placeholder. Size/shape via className. With children, wraps transparently to maintain actual size.
 
+WHEN TO USE:
+  • Long load with known component shape (cards, lists, profile headers)
+  • Reduces perceived wait time when layout is predictable
+  • Short loads (<1s) → Spinner
+  • Quantifiable progress → Progress
+  • DataList/DataGrid loading → 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:
+  ✗ Generic gray rectangle for everything → match real component shape
+  ✗ Skeleton for instant loads (causes flash)
+  ✗ Many skeletons of different shapes when component is uniform → use a single skeleton in DataList
+
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `as` | `'div'` \| `'span'` | `"div"` | Rendered tag |
@@ -384,7 +641,19 @@ Skeleton loading placeholder. Size/shape via className. With children, wraps tra
 
 ## Divider
 
-Divider. Supports horizontal/vertical, solid/dashed/dotted.
+Divider — visual separator (horizontal/vertical line).
+
+WHEN TO USE:
+  • Separating sections within a card / list
+  • Vertical separator between inline items (orientation="vertical")
+  • Use color prop sparingly — defaults to border-default token
+  • For grouping form sections, prefer larger spacing over Divider
+  • Tab/Accordion already provide visual separation — don't add Divider
+
+ANTI-PATTERNS:
+  ✗ Stacking many Dividers — increase spacing instead
+  ✗ Using Divider as decorative line with bright color → use Tailwind border utility on container
+  ✗ Inline <hr> with custom CSS → Divider (consistent token)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -403,7 +672,20 @@ Divider. Supports horizontal/vertical, solid/dashed/dotted.
 
 ## Tooltip
 
-Tooltip. Based on Radix Tooltip. Built-in Provider.
+Tooltip — short text hint shown on hover/focus. Based on Radix Tooltip. Provider built-in.
+
+WHEN TO USE:
+  • Brief explanation of an icon button or truncated label
+  • Hover-only, non-interactive content (text only)
+  • Need clickable content inside → Popover (not Tooltip)
+  • Action menu → DropdownMenu
+  • Force user attention → Modal
+
+ANTI-PATTERNS:
+  ✗ Buttons/links inside content → use Popover (Tooltip not focusable)
+  ✗ Long paragraphs in tooltip → consider Popover or Drawer
+  ✗ Tooltip on disabled buttons (won't show in some browsers) — wrap in span instead
+  ✗ Critical info only in tooltip — duplicate visible elsewhere for mobile/touch
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -427,7 +709,19 @@ Tooltip. Based on Radix Tooltip. Built-in Provider.
 
 ## Popover
 
-Popover. Based on Radix Popover.
+Popover — anchor-positioned panel with interactive content. Based on Radix Popover.
+
+WHEN TO USE:
+  • Trigger-anchored UI with buttons, inputs, or rich content
+  • Filter/option panel near a button (not a full sidebar)
+  • Hover-only text hint → Tooltip (lighter)
+  • Action menu list → DropdownMenu (gives role=menu, keyboard nav)
+  • Decision dialog → Modal
+
+ANTI-PATTERNS:
+  ✗ Action lists with onClick handlers → DropdownMenu (a11y semantics)
+  ✗ Implementing dropdown manually with Popover + custom buttons → DropdownMenu
+  ✗ Long forms inside Popover → Drawer or Modal
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -453,7 +747,21 @@ Popover. Based on Radix Popover.
 
 ## Accordion
 
-Accordion. Supports both items array and composable patterns.
+Accordion — collapsible content sections (FAQ, settings groups).
+
+WHEN TO USE:
+  • FAQ, help docs, settings groups
+  • Long page where each section is independently scannable
+  • Hidden critical info — DO NOT bury what users always need
+  • Tab-like content switching → Tab (Accordion is for stacked, not exclusive)
+
+type="single" + collapsible=true → all-closed allowed (recommended for FAQ).
+type="multiple" → multiple sections open at once.
+
+ANTI-PATTERNS:
+  ✗ Hiding the page's primary content inside collapsed Accordion
+  ✗ Single-section Accordion (just show the content)
+  ✗ Custom toggle div + state — use Accordion (gets a11y, keyboard nav)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -484,7 +792,21 @@ Accordion. Supports both items array and composable patterns.
 
 ## Drawer
 
-Drawer/bottom sheet. Based on Vaul. Compound component pattern.
+Drawer / bottom sheet. Based on Vaul. Compound component pattern.
+
+WHEN TO USE:
+  • Side panel for secondary action while user can still see main content (filter panel, item details)
+  • Mobile bottom sheet (direction="bottom")
+  • Force decision blocking main flow → Modal instead
+  • Inline anchor-positioned UI → 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:
+  ✗ Drawer for confirmation dialogs → Modal (decision-forcing)
+  ✗ Always shouldScaleBackground → only enable for true mobile bottom-sheets
+  ✗ Forgetting Drawer.Title → required for screen readers (a11y)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -530,6 +852,21 @@ Drawer.Content area.
 
 Modal template. All modal components must be wrapped with ModalTemplate.
 
+WHEN TO USE:
+  • Force user decision (delete confirm, submit confirm, blocking dialog)
+  • Long form/flow that needs full attention
+  • Side panel that doesn't block main flow → Drawer instead
+  • Inline contextual UI → Popover instead
+  • Short hint → 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:
+  ✗ Custom <div className="fixed inset-0"> → modal() (loses focus trap, a11y)
+  ✗ Direct <ModalTemplate> mount in render tree → wrap with modal()
+  ✗ Modal with no title for screen readers → always pass title prop
+  ✗ Multiple modals stacking confusingly → use isAlone:true to close prior modals
+
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `title` | `ReactNode` | - | Header title (ReactNode) |
@@ -627,7 +964,22 @@ openModal({
 
 ## Tab
 
-Tab navigation. line/pill variants.
+Tab navigation — switch between content panels (settings sections, profile views).
+
+WHEN TO USE:
+  • Page area swap where only one panel is visible at a time
+  • Mutually exclusive content with stable section labels
+  • Form field selection → RadioGroup (semantics: not navigation)
+  • Immediate filter/option toggle → ToggleGroup
+  • Stacked collapsible sections → Accordion
+
+destroyInactive=true unmounts hidden panels (saves memory but loses state).
+
+ANTI-PATTERNS:
+  ✗ Tab with 1 item — just render the panel
+  ✗ Tab with 8+ items — consider sub-routing or DropdownMenu
+  ✗ Using Tab for form value selection → RadioGroup
+  ✗ Custom <button> + onClick + state → Tab (a11y, keyboard, focus management)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -657,7 +1009,20 @@ Tab navigation. line/pill variants.
 
 ## Carousel
 
-Carousel. Based on Embla Carousel. Sub-components: CarouselSlide, CarouselPrev, CarouselNext, CarouselDots.
+Carousel — horizontal slide gallery. Based on Embla Carousel. Compound: CarouselSlide, CarouselPrev/Next, CarouselDots.
+
+WHEN TO USE:
+  • Hero banners, image gallery, product showcase
+  • Multi-card horizontal scroll with snap behavior
+  • Vertical scrolling list → Marquee or VirtualList (not Carousel)
+  • Critical content that must always be visible — Carousel hides slides
+
+opts={{ loop: true, align: 'start' }} for endless loop. Add Embla autoplay plugin for auto-advance.
+
+ANTI-PATTERNS:
+  ✗ Critical CTA inside non-first slide (users might never scroll)
+  ✗ Auto-advance without pause-on-hover (a11y)
+  ✗ Manual scroll-snap div → Carousel (gets keyboard nav, indicators)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -683,7 +1048,19 @@ Sub-components: `CarouselSlide`, `CarouselPrev`, `CarouselNext`, `CarouselDots`
 
 ## Pagination
 
-Pagination. Previous/next + page number buttons.
+Pagination — page-by-page navigation for long datasets.
+
+WHEN TO USE:
+  • User needs to jump to specific pages (search results, blog archives)
+  • Total count is known and stable
+  • Continuous browsing → InfiniteScroll instead
+  • Real-time stream → InfiniteScroll
+  • Both fit → Pagination is more accessible (keyboard, deep-linkable URL)
+
+ANTI-PATTERNS:
+  ✗ Pagination with totalPages=1 — hide it
+  ✗ Mixing Pagination + InfiniteScroll on same list (confusing)
+  ✗ Custom page button divs → Pagination (a11y, edge cases like ellipsis)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -703,7 +1080,20 @@ Pagination. Previous/next + page number buttons.
 
 ## Avatar
 
-Avatar. Supports image, fallback text, and children.
+Avatar — user/entity profile image with text fallback.
+
+WHEN TO USE:
+  • User profiles, comment authors, team member lists, message sender icons
+  • Image fails / not provided → fallback (initials or icon) shown automatically
+  • Need optimized image (Next.js) → pass <Image> via children, omit src
+  • Larger illustration / logo → use NxImage instead
+
+shape="square" for organization/team logos; "circle" for people (default).
+
+ANTI-PATTERNS:
+  ✗ <img> + manual fallback handling → Avatar (handles error)
+  ✗ Avatar without alt for screen readers (always set alt or aria-label)
+  ✗ Mixing avatar sizes inconsistently in a list — pick one size
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -725,7 +1115,20 @@ Avatar. Supports image, fallback text, and children.
 
 ## Counter
 
-Number count animation.
+Counter — animated number tick from startValue to endValue.
+
+WHEN TO USE:
+  • Marketing landing — "10,000+ users" KPI displays
+  • Stat dashboards (animate when value changes)
+  • Live tickers / real-time data — re-render plain text instead (Counter is one-shot animation)
+  • Currency input / editable number → NumberInput / PriceInput
+
+triggerOnView=true delays animation until element scrolls into view (good for landing pages).
+
+ANTI-PATTERNS:
+  ✗ Counter for values that update frequently — animation queue conflicts
+  ✗ Long duration on critical numbers (users wait to read)
+  ✗ Counter without separator for large numbers (hard to read)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -748,7 +1151,20 @@ Number count animation.
 
 ## Countdown
 
-Countdown timer.
+Countdown — live timer counting down to endTimestamp (Unix ms).
+
+WHEN TO USE:
+  • Sale ends in / event starts in / token claim window
+  • OTP / verification code expiry
+  • Counting up (since X) → not Countdown; use Counter or custom interval
+  • Persistent server time → 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:
+  ✗ Countdown without onEnd handler — UI stuck at 0
+  ✗ Countdown across SSR without hydration safety — pass endTimestamp from server
+  ✗ Updating endTimestamp every render — causes jitter
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -768,7 +1184,20 @@ Countdown timer.
 
 ## Marquee
 
-Marquee (scrolling text/elements).
+Marquee — endless scrolling content (logo strip, promo banner, news ticker).
+
+WHEN TO USE:
+  • Logo cloud, partner brands strip, social proof
+  • Critical info that must be read → not Marquee (auto-scroll hurts a11y)
+  • Long static list → VirtualList
+  • User-paced gallery → Carousel
+
+pauseOnHover=true is recommended whenever content is readable text.
+
+ANTI-PATTERNS:
+  ✗ Marquee with action buttons inside (hard to click)
+  ✗ Fast-speed marquee on important text (unreadable, a11y violation)
+  ✗ Multiple Marquees on same page in different directions (visual chaos)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -790,7 +1219,21 @@ Marquee (scrolling text/elements).
 
 ## VirtualList
 
-Virtual scroll list. Based on @tanstack/react-virtual.
+VirtualList — performant rendering of huge lists (1000+ items). Based on @tanstack/react-virtual.
+
+WHEN TO USE:
+  • Large datasets (>200 rows): chat history, transactions, logs, leaderboard
+  • Stable item height (or measurable per-item via estimateSize fn)
+  • Small list (<100 items) → DataList (much simpler API)
+  • Grid layout → VirtualGrid
+  • Server-side pagination → InfiniteScroll wrapping plain list
+
+estimateSize is critical — wrong values cause scroll jumps. Pair with onEndReached for server pagination.
+
+ANTI-PATTERNS:
+  ✗ VirtualList for short lists (DataList is simpler and renders faster)
+  ✗ Variable estimateSize for uniform items — use a single number
+  ✗ Putting interactive overlays inside virtual rows (mounted/unmounted on scroll)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -806,7 +1249,18 @@ Virtual scroll list. Based on @tanstack/react-virtual.
 
 ### VirtualGrid
 
-Virtual scroll grid. Based on @tanstack/react-virtual.
+VirtualGrid — performant grid for huge lists. Based on @tanstack/react-virtual.
+
+WHEN TO USE:
+  • Image gallery / card grid with 200+ items
+  • Fixed column count (responsive via JS — recompute columns on breakpoint)
+  • Small grid → DataGrid (no virtualization, simpler API)
+  • Single-column list → VirtualList
+
+ANTI-PATTERNS:
+  ✗ VirtualGrid with <50 items — DataGrid is simpler
+  ✗ Cards with hover-expanding height (breaks virtualization)
+  ✗ Forgetting to recompute columns on resize → visible empty space
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -842,7 +1296,21 @@ Same as VirtualList + `columns: number` (required).
 
 ## DataList
 
-Data list. Automatically handles loading/skeleton/empty/data states based on list. Built-in ErrorBoundary.
+DataList — render-prop list that handles loading / skeleton / empty / error / data in one component. Built-in ErrorBoundary.
+
+WHEN TO USE:
+  • Any async list (<200 items) — feed, comments, dashboard rows
+  • Pass list={null} during loading (auto-shows skeleton/spinner)
+  • Pass list=[] for empty state (auto-shows noDataMessage)
+  • Card grid → DataGrid (same API + columns prop)
+  • Huge dataset → VirtualList
+
+children is render fn: ({ item, index }) => ReactNode.
+
+ANTI-PATTERNS:
+  ✗ Manual if (loading) {...} else if (!data.length) {...} chains → DataList handles all
+  ✗ DataList without skeletonElement when component shape is known (use Skeleton)
+  ✗ list=undefined (treated as data, not loading) — use null for loading
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -891,9 +1359,104 @@ function UserSkeleton() {
 
 ---
 
+## DataGrid
+
+DataGrid — card grid version of DataList with responsive columns. Built-in ErrorBoundary, loading/skeleton/empty/error states.
+
+WHEN TO USE:
+  • Card grids: products, gallery, team members, posts
+  • Need responsive column count → pass { base: 1, sm: 2, lg: 3, xl: 4 }
+  • Single column / row layout → DataList
+  • Tabular data → table component (not DataGrid)
+  • Huge dataset → VirtualGrid
+
+ANTI-PATTERNS:
+  ✗ Tabular data forced into card grid (use a table)
+  ✗ Hardcoded column count for responsive layouts → use responsive object
+  ✗ Manual loading/empty handling → DataGrid does it
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `list` | `ReactNode`[] | - | Data array to render. null = loading state (required) |
+| `columns` | `number` \| `object` | - | Column count. number = fixed | { base, sm, md, lg, xl, 2xl } = responsive (required) |
+| `gap` | `number` \| `string` | - | Item gap. number = px | string = CSS value |
+| `noDataMessage` | `ReactNode` | - | Message for empty array (string | ReactElement) |
+| `errorFallback` | `ReactNode` | - | Fallback on error (ReactNode) |
+| `loadingElement` | `ReactNode` | - | Custom loading element (default: Spinner) |
+| `skeletonElement` | `ReactNode` | - | Skeleton element during loading (ReactElement) |
+| `skeletonCount` | `number` | `3` | Skeleton repeat count |
+| `loading` | `boolean` | `false` | Force loading state |
+| `children` | `ReactNode` | - | Item render function: ({ item, index }) => ReactNode (required) |
+| `className` | `string` | - | Root element style |
+
+Card grid counterpart of `Table`. Inherits all DataList semantics (loading / skeleton / empty / error) and adds responsive `columns` + `gap`. Use this whenever you need a card grid view of data.
+
+- **`columns`**: `number` for fixed, or `{ base, sm, md, lg, xl, 2xl }` for responsive (mobile-first; missing breakpoints inherit from the previous one).
+- **`gap`**: `number` (px) or any CSS gap value (e.g. `'1rem'`).
+- All other props (`list`, `skeletonElement`, `noDataMessage`, `errorFallback`, `loading`) behave exactly like `DataList`.
+
+```tsx
+// 1) Fixed columns
+<DataGrid list={projects} columns={3} gap={12}>
+  {({ item }) => <ProjectCard key={item.id} project={item} />}
+</DataGrid>
+
+// 2) Responsive columns (mobile-first)
+<DataGrid
+  list={projects}
+  columns={{ base: 1, sm: 2, lg: 3, xl: 4 }}
+  gap={12}
+>
+  {({ item }) => <ProjectCard key={item.id} project={item} />}
+</DataGrid>
+
+// 3) Skeleton loading (auto-shown when list is null)
+<DataGrid
+  list={projects}
+  columns={{ base: 1, md: 2, lg: 3 }}
+  gap={12}
+  skeletonElement={<ProjectCardSkeleton />}
+  skeletonCount={6}
+>
+  {({ item }) => <ProjectCard key={item.id} project={item} />}
+</DataGrid>
+
+// 4) Empty / error states
+<DataGrid
+  list={projects}
+  columns={3}
+  gap={12}
+  noDataMessage="No projects"
+  errorFallback={<div>Failed to load</div>}
+>
+  {({ item }) => <ProjectCard key={item.id} project={item} />}
+</DataGrid>
+```
+
+**When to use `Table` vs `DataGrid`**:
+- Tabular data with rows/columns → `Table` + `TableRow` + `TdColumn`
+- Card-style items in a responsive grid → `DataGrid`
+- Either view of the same data (toggle pattern) → both, switched by a state-driven `ToggleGroup`
+
+---
+
 ## InfiniteScroll
 
-Infinite scroll. Based on IntersectionObserver.
+InfiniteScroll — auto-load more when sentinel enters viewport. Based on IntersectionObserver.
+
+WHEN TO USE:
+  • Feeds, social timelines, search-as-you-scroll
+  • Continuous browsing where total isn't critical
+  • Need jump-to-page → Pagination (not InfiniteScroll)
+  • Need to render 1000s of already-loaded items efficiently → VirtualList
+  • Combine with VirtualList for huge + paginated data
+
+Pass either totalCount or hasMore (not both). handleLoadMore is required.
+
+ANTI-PATTERNS:
+  ✗ InfiniteScroll without footer/loading element (looks broken at the bottom)
+  ✗ InfiniteScroll without debouncing handleLoadMore — duplicate fetches
+  ✗ Auto-loading critical actions in footer (links, contact) — they become unreachable
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -924,7 +1487,20 @@ Infinite scroll. Based on IntersectionObserver.
 
 ## Ellipsis
 
-Text ellipsis. Built-in show more/less toggle.
+Ellipsis — clamp long text to N lines with "show more / less" toggle.
+
+WHEN TO USE:
+  • Long descriptions in cards, comments, post previews
+  • Single-line truncation only → CSS line-clamp utility (lighter)
+  • Tooltip on hover for full text → Tooltip + truncate utility
+  • Critical content that must be fully readable — don't truncate
+
+triggerMore/triggerLess accept ReactNode for icons or styled buttons.
+
+ANTI-PATTERNS:
+  ✗ Ellipsis on titles / labels — confusing UX
+  ✗ Always-collapsed (defaultShortened=true) for short text — measurement waste
+  ✗ Overriding triggerMore/Less with HTML that breaks accessibility (use button-like)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -947,6 +1523,16 @@ Text ellipsis. Built-in show more/less toggle.
 
 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:
+  • Any numeric field — quantity, score, age, count
+  • Currency with thousand separators → PriceInput instead
+  • Date / time → DatePicker instead
+
+ANTI-PATTERNS:
+  ✗ <TextInput type="number"> → <NumberInput> (loses keyboard ↑↓, step, accelerated long-press, max click)
+  ✗ Custom +/- buttons + <input> → variant="bind" (or numberInputBind for external)
+  ✗ Manual thousand separators for currency → PriceInput
+
 | Prop | Type | Default | Description |
 |---|---|---|---|
 | `variant` | `'basic'` \| `'bind'` | `"basic"` | Variant: basic (right chevron arrows) or bind (left/right +/- buttons) |
@@ -1001,7 +1587,20 @@ const ref = useRef<NumberInputRef>(null);
 
 ## PriceInput
 
-Price/amount input field with prefix, suffix, balance display, and auto-fill on balance click.
+PriceInput — currency / amount input with prefix, suffix, balance display, click-to-fill.
+
+WHEN TO USE:
+  • Money / token amounts: payment, transfer, swap, withdraw
+  • Need balance hint with auto-fill UX (set balance + onBalanceClick)
+  • Pure number (count, age, score) → NumberInput
+  • Generic text → TextInput
+
+separator=true displays commas; onValueChange always returns raw value (no commas). maxBalance auto-applies error styling on overflow.
+
+ANTI-PATTERNS:
+  ✗ <TextInput type="number"> + manual currency formatting → PriceInput
+  ✗ NumberInput for currency (loses prefix/suffix/balance UX)
+  ✗ Using string input for amounts then parseFloat — lose precision; use this component
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1029,7 +1628,21 @@ Price/amount input field with prefix, suffix, balance display, and auto-fill on
 
 ## Badge
 
-Badge indicator. Dot or count display. Wraps children when provided.
+Badge — small status / count indicator overlaid on an anchor (icon, avatar, button).
+
+WHEN TO USE:
+  • Notification count on bell icon
+  • Unread message count on inbox tab
+  • Status dot (online/offline) → dot=true
+  • Status label with text (e.g. "PRO", "NEW") → Chip variant="accent"
+  • Removable filter token → Chip with onClose
+
+count={0} hides badge by default; pass showZero=true to keep visible.
+
+ANTI-PATTERNS:
+  ✗ Using Badge as standalone label without anchor → Chip
+  ✗ count > 999 without max → ugly layout; default max=99 ("99+")
+  ✗ Multiple badges on same anchor (visual noise)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1047,7 +1660,21 @@ Badge indicator. Dot or count display. Wraps children when provided.
 
 ## Progress
 
-Progress bar. Linear progress indicator with percentage display.
+Progress — linear progress bar (file upload, multi-step form, loading with known %).
+
+WHEN TO USE:
+  • Quantifiable progress (% complete, X of Y)
+  • Unknown duration spinner → Spinner
+  • Stable component shape during load → Skeleton
+  • Step-based navigation → Stepper
+  • Indeterminate (loading without %) → set indeterminate=true
+
+variant follows semantic colors (success when complete, danger on error).
+
+ANTI-PATTERNS:
+  ✗ Indeterminate Progress for short loads (<1s) — Spinner is lighter
+  ✗ Custom <div style={{ width: x% }}> → Progress (a11y, tokens)
+  ✗ Progress without label/showValue when % is critical info
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1064,7 +1691,20 @@ Progress bar. Linear progress indicator with percentage display.
 
 ## Alert
 
-Alert / Banner. Inline notification with icon, title, description.
+Alert — persistent inline notification (banner). Auto icon by variant.
+
+WHEN TO USE:
+  • In-page status: form errors, server warnings, info banners, success confirmation
+  • Transient toast/snackbar → use a toast library, NOT Alert
+  • Modal-blocking error → Modal with semantic="danger"
+  • Inline form field error → 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:
+  ✗ Stacking 5 alerts at top of page (use one with summary)
+  ✗ Critical destructive action confirmation in Alert → Modal
+  ✗ Wrapping <div className="bg-red-100"> manually → Alert (a11y role + tokens)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1081,7 +1721,20 @@ Alert / Banner. Inline notification with icon, title, description.
 
 ## EmptyState
 
-Empty state placeholder. Shown when data is empty or unavailable.
+EmptyState — friendly placeholder for empty lists, no search results, first-time setup.
+
+WHEN TO USE:
+  • Empty inbox / list / search results
+  • First-time use (onboarding nudge with action button)
+  • Loading → Skeleton/Spinner (NOT EmptyState)
+  • Error → Alert (or pass icon + title to EmptyState only when conceptually "nothing here")
+
+DataList/DataGrid have built-in noDataMessage that wraps EmptyState — use that prop instead of conditional rendering.
+
+ANTI-PATTERNS:
+  ✗ Showing EmptyState during loading (confuses users into thinking data is missing)
+  ✗ EmptyState without action when user can fix it ("Create your first X" button)
+  ✗ Cluttered EmptyState (too much text/multiple CTAs) — keep one primary action
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1097,7 +1750,21 @@ Empty state placeholder. Shown when data is empty or unavailable.
 
 ## Breadcrumb
 
-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 — hierarchical location navigation (Home > Settings > Profile).
+
+WHEN TO USE:
+  • Multi-level information architecture (>=3 levels deep)
+  • Hierarchical category drill-down (file system, taxonomy)
+  • Step-based linear flow → Stepper (not Breadcrumb)
+  • Tab switching → Tab
+  • Single-level navigation → 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 "…").
+
+ANTI-PATTERNS:
+  ✗ Breadcrumb with 1 level — just show page title
+  ✗ Breadcrumb with > 6 visible items → set maxItems
+  ✗ Last item as a link (it's the current page; should be plain text)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1110,7 +1777,21 @@ Breadcrumb navigation (compound component pattern). Use <Breadcrumb.Item> childr
 
 ## Stepper
 
-Stepper. Step-by-step progress indicator.
+Stepper — multi-step linear flow indicator (checkout, onboarding, wizard).
+
+WHEN TO USE:
+  • Sequential workflow with finite steps (3-7)
+  • Show user's current position in flow + completed/upcoming steps
+  • Independent navigation between unrelated sections → Tab
+  • Continuous % progress → Progress
+  • Hierarchy / location → Breadcrumb
+
+status="error" highlights the current step with danger color when validation fails.
+
+ANTI-PATTERNS:
+  ✗ Stepper with 2 steps (use Progress or just navigation)
+  ✗ Stepper with 10+ steps (overwhelming) — chunk into sub-flows
+  ✗ Letting users skip ahead by clicking future steps (only mark completed → current is allowed)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1125,7 +1806,22 @@ Stepper. Step-by-step progress indicator.
 
 ## DropdownMenu
 
-Dropdown menu. Based on Radix DropdownMenu. Action menu for context/more menus.
+Dropdown menu — list of actions/commands triggered by a button. Based on Radix DropdownMenu (role="menu" + keyboard nav).
+
+WHEN TO USE:
+  • "More" / context menu (•••, ⋮)
+  • Action lists where each item triggers a function (save, share, delete)
+  • Selecting a value (form field) → Select / Combobox (not DropdownMenu)
+  • Multi-select toggles → ToggleGroup or CheckBox group
+  • Anchored info panel → Popover
+
+Use danger=true on destructive items (Delete) for visual + semantic emphasis.
+Use separator=true to group related actions.
+
+ANTI-PATTERNS:
+  ✗ DropdownMenu for value selection submitted later → Select / Combobox
+  ✗ Custom <div onClick> with isOpen state → DropdownMenu
+  ✗ Long form inputs inside menu items → Popover instead
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1140,7 +1836,27 @@ Dropdown menu. Based on Radix DropdownMenu. Action menu for context/more menus.
 
 ## ToggleGroup
 
-Toggle group / Segment control. Based on Radix ToggleGroup.
+Toggle group / Segment control for immediate-effect option selection. Based on Radix ToggleGroup.
+
+WHEN TO USE:
+  • Sort order, view mode (grid/list), filter chips — selection takes effect immediately
+  • Visual comparison important (icons or short labels)
+  • Form field that submits later → RadioGroup or CheckBox instead
+  • Page area switching (settings tabs) → Tab instead
+
+VARIANTS:
+  • default — slider-style background (sleek)
+  • primary / secondary — accent-filled selected state
+  • outline — 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:
+  ✗ Using ToggleGroup for content tabs → Tab
+  ✗ Using ToggleGroup as form field submitted later → RadioGroup (semantics + a11y)
+  ✗ Mixing icons and text labels of different sizes — keep visual rhythm consistent
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1149,16 +1865,32 @@ Toggle group / Segment control. Based on Radix ToggleGroup.
 | `value` | `ReactNode` | - | Controlled value (string | string[]) |
 | `defaultValue` | `ReactNode` | - | Default value |
 | `onValueChange` | `ReactNode` | - | Value change callback |
-| `variant` | `'default'` \| `'outline'` | `"default"` | Style variant |
+| `variant` | `'default'` \| `'primary'` \| `'secondary'` \| `'outline'` | `"default"` | Style variant (default=slider, primary/secondary=accent filled, outline=bordered buttons with no background) |
 | `size` | `'sm'` \| `'md'` \| `'lg'` | `"md"` | Size |
+| `fullWidth` | `boolean` | `false` | Stretch the group to parent width and split items equally |
 | `disabled` | `boolean` | - | Disable all items |
+| `required` | `boolean` | `true` | Prevent deselection (at least one must be selected) |
 | `className` | `string` | - | Style override |
 
 ---
 
 ## Slider
 
-Slider / Range input. Based on Radix Slider. Supports single and range mode.
+Slider — numeric range selector. Based on Radix Slider. Single thumb or range (two thumbs).
+
+WHEN TO USE:
+  • Continuous range with visual feedback: volume, brightness, price filter
+  • Range filter (min-max) → defaultValue=[20, 80]
+  • Precise number entry → NumberInput
+  • Discrete few options → ToggleGroup or RadioGroup
+  • Boolean → Switch
+
+step controls increments. onValueCommit fires only after pointer release (good for expensive recomputations).
+
+ANTI-PATTERNS:
+  ✗ Slider for required precise input (typing 47 is faster than dragging)
+  ✗ Long step count without showValue / labels (users have no reference)
+  ✗ Calling expensive API on every onValueChange tick → use onValueCommit
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1180,7 +1912,20 @@ Slider / Range input. Based on Radix Slider. Supports single and range mode.
 
 ## TagInput
 
-Tag input. Enter key to add, Backspace to delete last tag.
+TagInput — free-form multi-value entry (Enter to add, Backspace to remove last).
+
+WHEN TO USE:
+  • Free-form labels: skills, hashtags, email recipients, keywords
+  • Predefined options → Combobox with multi-select (NOT TagInput)
+  • Single value → TextInput
+  • Limited options → Select / RadioGroup / Checkbox
+
+allowDuplicates=false (default) prevents repeats. Use max to cap count.
+
+ANTI-PATTERNS:
+  ✗ TagInput for predefined taxonomy → Combobox (controlled options)
+  ✗ TagInput without max for spam-prone fields
+  ✗ Custom comma-split string field → TagInput (proper UX + a11y)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1200,7 +1945,20 @@ Tag input. Enter key to add, Backspace to delete last tag.
 
 ## NxImage
 
-Enhanced image. Lazy loading, fallback, aspect-ratio support.
+NxImage — lazy-loaded <img> with fallback, fixed aspect-ratio, object-fit. Always prefer over native <img>.
+
+WHEN TO USE:
+  • Content images: covers, banners, illustrations, hero images
+  • Profile/user avatar (with text fallback) → Avatar
+  • Background image / decorative → CSS bg-image
+  • Need Next.js optimization → use next/image directly (NxImage doesn't optimize)
+
+aspectRatio reserves space, preventing CLS (layout shift).
+
+ANTI-PATTERNS:
+  ✗ <img> with manual onError handling → NxImage (built-in fallback)
+  ✗ NxImage without alt for content images (a11y violation)
+  ✗ NxImage without aspectRatio in fluid layouts → CLS jank
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1218,7 +1976,20 @@ Enhanced image. Lazy loading, fallback, aspect-ratio support.
 
 ## DatePicker
 
-DatePicker. Calendar popup for date selection. Based on react-day-picker.
+DatePicker — calendar popup for date selection. Based on react-day-picker.
+
+WHEN TO USE:
+  • Single date selection: birthday, due date, appointment
+  • Date range → use two DatePickers with minDate/maxDate cross-bound
+  • Time selection → not yet supported; use TextInput with type="time" + DatePicker combo
+  • Quick relative ranges (Today/Last 7 days) → DropdownMenu of preset Buttons + DatePicker for "Custom"
+
+minDate/maxDate disable out-of-range dates. locale="ko" for Korean labels.
+
+ANTI-PATTERNS:
+  ✗ Native <input type="date"> for branded UI (inconsistent across browsers) → DatePicker
+  ✗ Free-text date with parsing → DatePicker (consistent UX)
+  ✗ DatePicker without minDate for past-date-invalid fields (e.g. booking)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
@@ -1237,7 +2008,19 @@ DatePicker. Calendar popup for date selection. Based on react-day-picker.
 
 ## ImageUpload
 
-ImageUpload. Drag-and-drop image upload with preview, file validation, and field label/description support.
+ImageUpload — drag-and-drop image upload with preview, file-type/size validation, label/description.
+
+WHEN TO USE:
+  • Single image upload: avatar, cover, KYC document, post thumbnail
+  • Multiple files / non-image → not yet supported; build custom or use a file dropzone
+  • Inline image picker without preview → custom <input type="file">
+
+accept whitelist + maxSize together cover validation. onError fires with i18n-ready string.
+
+ANTI-PATTERNS:
+  ✗ <input type="file"> + manual preview → ImageUpload (handles drag, validation, preview)
+  ✗ ImageUpload without onError handler → silent failure on validation reject
+  ✗ Storing image as data-URL value (use File via onChange and upload to server)
 
 | Prop | Type | Default | Description |
 |---|---|---|---|