@nexus-cross/design-system 1.0.4-beta.1 → 1.0.4

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

@@ -1,41 +1,57 @@
 ---
-description: "@nexus-cross/design-system 컴포넌트 API 레퍼런스 — 모든 공용 컴포넌트의 props와 사용 예시"
+description: "@nexus-cross/design-system component API reference — props and usage examples for all shared components"
 globs: "**/*.tsx,**/*.jsx,**/*.ts"
 alwaysApply: false
 ---
 
 # @nexus-cross/design-system — Component API Reference
 
-모든 컴포넌트는 `@nexus-cross/design-system`에서 import.
+All components are imported from `@nexus-cross/design-system`.
 
 ---
 
 ## Button
 
-인터랙티브 버튼. `asChild`로 렌더링 요소 변경 가능.
+Interactive button. semantic(color) x variant(style) 2-axis system. Rendering element changeable via asChild.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `variant` | `'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'danger'` | `'primary'` | 시각 스타일 |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 크기 |
-| `asChild` | `boolean` | `false` | 자식 요소로 렌더링 |
-| `detectDoubleClick` | `boolean` | `false` | 500ms 더블 클릭 방지 |
-| `disabled` | `boolean` | - | 비활성 (`aria-disabled` 자동) |
-| `className` | `string` | - | 스타일 오버라이드 |
+| `semantic` | `'primary'` \| `'secondary'` \| `'normal'` \| `'danger'` | `"primary"` | Color theme (primary=main, secondary=sub, normal=neutral, danger=danger) |
+| `variant` | `'contained'` \| `'outlined'` \| `'subtle'` \| `'ghost'` | `"contained"` | Visual style (contained=filled, outlined=border, subtle=light bg, ghost=transparent) |
+| `size` | `'xl'` \| `'lg'` \| `'md'` \| `'sm'` | `"md"` | Size |
+| `radius` | `'default'` \| `'circle'` | `"default"` | Corner radius (default=size-based radius, circle=pill shape) |
+| `asChild` | `boolean` | - | If true, renders as child element (Slot pattern) |
+| `detectDoubleClick` | `boolean` | - | Prevent double click within 500ms |
+| `disabled` | `boolean` | - | Disabled (auto aria-disabled) |
+| `children` | `ReactNode` | - | Button content (ReactNode) |
+| `onClick` | `ReactNode` | - | Click event handler |
+| `type` | `'button'` \| `'submit'` \| `'reset'` | - | HTML button type (default: button) |
+| `style` | `ReactNode` | - | Inline style (CSSProperties) |
+| `className` | `string` | - | Style override |
+
+2-axis variant: semantic (color) × variant (style). sizes: xl, lg, md, sm. radius: default, circle.
 
 ```tsx
-<Button variant="primary" size="lg">확인</Button>
+// Default (primary + contained)
+<Button>Confirm</Button>
 
-<Button variant="outline" disabled>비활성</Button>
+// semantic × variant combinations
+<Button semantic="primary" variant="contained" size="lg">Primary Contained</Button>
+<Button semantic="secondary" variant="outlined" size="md">Secondary Outlined</Button>
+<Button semantic="normal" variant="subtle" size="sm">Normal Subtle</Button>
+<Button semantic="danger" variant="ghost">Danger Ghost</Button>
 
-// 로딩 상태 (Spinner를 children에 직접 배치)
+// Pill shape (radius="circle")
+<Button semantic="primary" variant="contained" radius="circle">Pill</Button>
+
+// Loading state
 <Button disabled>
-  <Spinner size={16} /> 처리 중...
+  <Spinner size={16} /> Processing...
 </Button>
 
-// <a> 태그로 렌더링
-<Button asChild variant="ghost">
-  <a href="/settings">설정</a>
+// Render as <a> tag
+<Button asChild semantic="normal" variant="ghost">
+  <a href="/settings">Settings</a>
 </Button>
 ```
 
@@ -43,42 +59,95 @@ alwaysApply: false
 
 ## TextInput
 
-텍스트 입력 필드. prefix/suffix 아이콘 지원.
+Text input field. Supports label, description, prefix/suffix icons, clearable, character counter.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 크기 |
-| `error` | `boolean` | `false` | 에러 상태 (`aria-invalid` 자동) |
-| `prefixIcon` | `ReactNode` | - | 앞쪽 아이콘 |
-| `suffixIcon` | `ReactNode` | - | 뒤쪽 아이콘 |
-| `onValueChange` | `(value: string) => void` | - | 값 변경 콜백 |
+| `size` | `'md'` \| `'lg'` \| `'xl'` | `"md"` | Size |
+| `error` | `boolean` | - | Error state (auto aria-invalid) |
+| `prefixIcon` | `ReactNode` | - | Prefix icon (ReactNode) |
+| `suffixIcon` | `ReactNode` | - | Suffix icon (ReactNode) |
+| `label` | `ReactNode` | - | Label above input field (ReactNode) |
+| `description` | `ReactNode` | - | Description below input field (ReactNode, red on error) |
+| `showCount` | `boolean` | - | Show character count (requires maxLength) |
+| `maxLength` | `number` | - | Maximum character count |
+| `clearable` | `boolean` | - | Clear input via X button |
+| `placeholder` | `string` | - | Placeholder |
+| `disabled` | `boolean` | - | Disabled |
+| `readOnly` | `boolean` | - | Read-only |
+| `value` | `string` | - | Input value (controlled mode) |
+| `defaultValue` | `string` | - | Initial value (uncontrolled mode) |
+| `type` | `string` | - | Input type (text, password, email, url, etc.) |
+| `name` | `string` | - | Form field name |
+| `id` | `string` | - | Element ID (for label htmlFor binding) |
+| `autoFocus` | `boolean` | - | Auto focus |
+| `autoComplete` | `string` | - | Autocomplete hint (on, off, email, etc.) |
+| `onValueChange` | `ReactNode` | - | Value change callback (value: string) => void |
+| `onChange` | `ReactNode` | - | Native change event handler |
+| `onBlur` | `ReactNode` | - | Blur callback |
+| `onFocus` | `ReactNode` | - | Focus callback |
+| `className` | `string` | - | Style override |
 
 ```tsx
-<TextInput placeholder="이메일" size="md" />
+<TextInput placeholder="Email" size="md" />
 
 <TextInput
-  error
+  label="Email"
+  description="Enter your email address"
+  placeholder="example@email.com"
+  clearable
+/>
+
+<TextInput
+  label="Search"
   prefixIcon={<SearchIcon />}
+  clearable
   onValueChange={(v) => setQuery(v)}
 />
+
+<TextInput
+  label="Nickname"
+  description="2-20 characters"
+  showCount
+  maxLength={20}
+  clearable
+  error
+/>
 ```
 
 ---
 
 ## TextArea
 
-여러 줄 텍스트 입력. 글자 수 카운터 내장.
+Multi-line text input with label, description, character counter, and resize modes.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `error` | `boolean` | `false` | 에러 상태 (`aria-invalid` 자동) |
-| `showCount` | `boolean` | `false` | 글자 수 표시 (`maxLength` 필요) |
-| `maxLength` | `number` | - | 최대 글자 수 |
-| `onValueChange` | `(value: string) => void` | - | 값 변경 콜백 |
+| `label` | `string` | - | Label text above the textarea |
+| `description` | `string` | - | Helper/error description below the textarea |
+| `size` | `'lg'` \| `'md'` | - | Font size variant (lg: 16px, md: 14px) |
+| `resize` | `'default'` \| `'auto'` \| `'none'` | - | Resize mode (default: manual, auto: auto-grow, none: fixed) |
+| `error` | `boolean` | - | Error state (auto aria-invalid) |
+| `showCount` | `boolean` | - | Show character count (requires maxLength) |
+| `maxLength` | `number` | - | Maximum character count |
+| `placeholder` | `string` | - | Placeholder |
+| `rows` | `number` | - | Visible row count |
+| `disabled` | `boolean` | - | Disabled |
+| `readOnly` | `boolean` | - | Read-only |
+| `value` | `string` | - | Input value (controlled mode) |
+| `defaultValue` | `string` | - | Initial value (uncontrolled mode) |
+| `name` | `string` | - | Form field name |
+| `id` | `string` | - | Element ID |
+| `autoFocus` | `boolean` | - | Auto focus |
+| `onValueChange` | `ReactNode` | - | Value change callback (value: string) => void |
+| `onChange` | `ReactNode` | - | Native change event handler |
+| `onBlur` | `ReactNode` | - | Blur callback |
+| `onFocus` | `ReactNode` | - | Focus callback |
+| `className` | `string` | - | Style override |
 
 ```tsx
 <TextArea
-  placeholder="내용을 입력하세요"
+  placeholder="Enter your content"
   maxLength={500}
   showCount
   rows={4}
@@ -89,23 +158,37 @@ alwaysApply: false
 
 ## Select
 
-드롭다운 선택. Radix Select 기반.
+Dropdown select. Based on Radix Select. Used with SelectItem.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `value` | `string` | - | 선택된 값 |
-| `onValueChange` | `(value: string) => void` | - | 값 변경 콜백 |
-| `placeholder` | `string` | - | 플레이스홀더 |
-| `variant` | `'default' \| 'outline'` | `'default'` | 트리거 스타일 |
-| `size` | `'sm' \| 'md' \| 'lg' \| 'full'` | `'full'` | 너비 |
-| `disabled` | `boolean` | - | 비활성 |
-| `displayComponent` | `ReactNode` | - | 트리거에 커스텀 표시 |
+| `value` | `string` | - | Selected value |
+| `placeholder` | `string` | - | Placeholder |
+| `variant` | `'default'` \| `'outline'` | `"default"` | Trigger style |
+| `size` | `'sm'` \| `'md'` \| `'lg'` \| `'full'` | `"full"` | Width |
+| `disabled` | `boolean` | - | Disabled |
+| `onValueChange` | `ReactNode` | - | Value change callback (value: string) => void |
+| `displayComponent` | `ReactNode` | - | Custom display in trigger (ReactNode) |
+| `children` | `ReactNode` | - | SelectItem list (ReactNode, required) |
+| `className` | `string` | - | Wrapper style |
+| `triggerClassName` | `string` | - | Trigger style override |
+
+### SelectItem
+
+Individual option within Select.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | - | Item value |
+| `children` | `ReactNode` | - | Item content (ReactNode, required) |
+| `disabled` | `boolean` | - | Disabled |
+| `className` | `string` | - | Style override |
 
 ```tsx
-<Select value={lang} onValueChange={setLang} placeholder="언어 선택">
-  <SelectItem value="ko">한국어</SelectItem>
+<Select value={lang} onValueChange={setLang} placeholder="Select language">
+  <SelectItem value="ko">Korean</SelectItem>
   <SelectItem value="en">English</SelectItem>
-  <SelectItem value="ja">日本語</SelectItem>
+  <SelectItem value="ja">Japanese</SelectItem>
 </Select>
 ```
 
@@ -113,22 +196,30 @@ alwaysApply: false
 
 ## CheckBox
 
-체크박스. 네이티브 `<input>` 기반, square/round 형태 지원.
+Checkbox. Native input-based, supports square/round shapes.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `'sm' \| 'md'` | `'md'` | 크기 |
-| `shape` | `'square' \| 'round'` | `'square'` | 형태 |
-| `checked` | `boolean` | - | 체크 상태 |
-| `indeterminate` | `boolean` | `false` | 불확정 상태 (`aria-checked="mixed"`) |
-| `onCheckedChange` | `(checked: boolean) => void` | - | 체크 변경 콜백 |
-| `label` | `ReactNode` | - | 라벨 텍스트 |
+| `size` | `'sm'` \| `'md'` | `"md"` | Size |
+| `shape` | `'square'` \| `'round'` | `"square"` | Shape |
+| `checked` | `boolean` | - | Checked state |
+| `indeterminate` | `boolean` | - | Indeterminate state (aria-checked="mixed") |
+| `disabled` | `boolean` | - | Disabled |
+| `readOnly` | `boolean` | - | Read-only |
+| `label` | `ReactNode` | - | Label text (ReactNode) |
+| `children` | `ReactNode` | - | Label alternative content (ReactNode) |
+| `name` | `string` | - | Form field name |
+| `id` | `string` | - | Element ID |
+| `value` | `string` | - | Value for form submission |
+| `onCheckedChange` | `ReactNode` | - | Checked state change callback (checked: boolean) => void |
+| `onChange` | `ReactNode` | - | Native change event handler |
+| `className` | `string` | - | Style override |
 
 ```tsx
 <CheckBox
   checked={agreed}
   onCheckedChange={setAgreed}
-  label="이용약관에 동의합니다"
+  label="I agree to the terms of service"
 />
 
 <CheckBox shape="round" size="sm" checked indeterminate />
@@ -136,23 +227,36 @@ alwaysApply: false
 
 ---
 
-## RadioGroup / RadioItem
+## RadioGroup
 
-라디오 그룹. 네이티브 `<input type="radio">` 기반.
+Radio group. Used with RadioItem.
 
-| RadioGroup Prop | Type | Default | Description |
+| Prop | Type | Default | Description |
 |---|---|---|---|
-| `name` | `string` (필수) | - | form name |
-| `value` | `string` | - | 선택된 값 |
-| `onValueChange` | `(value: string) => void` | - | 변경 콜백 |
-| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | 배치 방향 |
-| `size` | `'sm' \| 'md'` | `'md'` | 크기 |
-| `aria-label` | `string` | - | 접근성 라벨 |
+| `name` | `string` | - | Form name (required) |
+| `value` | `string` | - | Selected value (controlled) |
+| `defaultValue` | `string` | - | Initial value (uncontrolled) |
+| `size` | `'sm'` \| `'md'` | `"md"` | Size |
+| `orientation` | `'horizontal'` \| `'vertical'` | `"vertical"` | Layout direction |
+| `disabled` | `boolean` | - | Disabled |
+| `children` | `ReactNode` | - | RadioItem list (ReactNode, required) |
+| `aria-label` | `string` | - | Accessibility label |
+| `aria-labelledby` | `string` | - | Accessibility label reference ID |
+| `onValueChange` | `ReactNode` | - | Value change callback (value: string) => void |
+| `className` | `string` | - | Style override |
+
+### RadioItem
+
+Individual option within RadioGroup.
 
-| RadioItem Prop | Type | Description |
-|---|---|---|
-| `value` | `string` (필수) | 항목 값 |
-| `label` | `ReactNode` | 라벨 텍스트 |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | - | Item value (required) |
+| `size` | `'sm'` \| `'md'` | - | Size (overrides group) |
+| `label` | `ReactNode` | - | Label text (ReactNode) |
+| `children` | `ReactNode` | - | Label alternative content (ReactNode) |
+| `disabled` | `boolean` | - | Disabled |
+| `className` | `string` | - | Style override |
 
 ```tsx
 <RadioGroup
@@ -160,11 +264,11 @@ alwaysApply: false
   value={plan}
   onValueChange={setPlan}
   orientation="horizontal"
-  aria-label="요금제 선택"
+  aria-label="Select plan"
 >
-  <RadioItem value="free" label="무료" />
-  <RadioItem value="pro" label="프로" />
-  <RadioItem value="enterprise" label="엔터프라이즈" />
+  <RadioItem value="free" label="Free" />
+  <RadioItem value="pro" label="Pro" />
+  <RadioItem value="enterprise" label="Enterprise" />
 </RadioGroup>
 ```
 
@@ -172,14 +276,19 @@ alwaysApply: false
 
 ## Switch
 
-토글 스위치. 네이티브 checkbox 기반, `role="switch"`.
+Toggle switch. Native checkbox-based, role="switch".
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `'sm' \| 'md'` | `'md'` | 크기 |
-| `checked` | `boolean` | - | on/off 상태 |
-| `onCheckedChange` | `(checked: boolean) => void` | - | 변경 콜백 |
-| `disabled` | `boolean` | - | 비활성 |
+| `size` | `'sm'` \| `'md'` | `"md"` | Size |
+| `checked` | `boolean` | - | On/off state |
+| `disabled` | `boolean` | - | Disabled |
+| `readOnly` | `boolean` | - | Read-only |
+| `name` | `string` | - | Form field name |
+| `id` | `string` | - | Element ID |
+| `onCheckedChange` | `ReactNode` | - | Toggle state change callback (checked: boolean) => void |
+| `onChange` | `ReactNode` | - | Native change event handler (ChangeEvent) |
+| `className` | `string` | - | Style override |
 
 ```tsx
 <Switch checked={darkMode} onCheckedChange={setDarkMode} />
@@ -189,24 +298,27 @@ alwaysApply: false
 
 ## Chip
 
-칩/태그/뱃지. `asChild`로 렌더링 요소 변경 가능.
+Chip/tag/badge. Close button displayed via onClose prop.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `variant` | `'default' \| 'filled' \| 'outline' \| 'accent'` | `'default'` | 스타일 |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 크기 |
-| `asChild` | `boolean` | `false` | 자식 요소로 렌더링 |
-| `disabled` | `boolean` | - | 비활성 (`aria-disabled` 자동) |
-| `onClose` | `(e: MouseEvent) => void` | - | 닫기 버튼 표시 및 콜백 |
+| `variant` | `'default'` \| `'filled'` \| `'outline'` \| `'accent'` | `"default"` | Style |
+| `size` | `'sm'` \| `'md'` \| `'lg'` | `"md"` | Size |
+| `asChild` | `boolean` | - | If true, renders as child element (Slot pattern) |
+| `disabled` | `boolean` | - | Disabled (auto aria-disabled) |
+| `children` | `ReactNode` | - | Chip content (ReactNode) |
+| `onClose` | `ReactNode` | - | Close button click callback (e: MouseEvent) => void. Shows X button when provided |
+| `onClick` | `ReactNode` | - | Click event handler |
+| `className` | `string` | - | Style override |
 
 ```tsx
 <Chip variant="accent" size="sm">New</Chip>
 
 <Chip onClose={() => removeTag(id)}>React</Chip>
 
-// <li>로 렌더링
+// Render as <li>
 <Chip asChild variant="filled">
-  <li>리스트 칩</li>
+  <li>List chip</li>
 </Chip>
 ```
 
@@ -214,31 +326,73 @@ alwaysApply: false
 
 ## Spinner
 
-로딩 인디케이터. SVG 기반. `role="status"` 내장.
+Loading indicator. SVG-based. Built-in role="status".
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `size` | `number` | `20` | px 크기 |
-| `className` | `string` | - | 색상 등 오버라이드 |
-| `aria-label` | `string` | `'Loading'` | 접근성 라벨 |
+| `size` | `number` | `20` | Size in px |
+| `color` | `string` | - | Color (CSS color value, default currentColor) |
+| `aria-label` | `string` | `"Loading"` | Accessibility label |
+| `style` | `ReactNode` | - | Inline style (CSSProperties) |
+| `className` | `string` | - | Color override etc. |
 
 ```tsx
 <Spinner size={24} />
 
-<Spinner size={14} className="text-white" aria-label="로딩 중" />
+<Spinner size={14} className="text-white" aria-label="Loading" />
+```
+
+---
+
+## Skeleton
+
+Skeleton loading placeholder. Size/shape via className. With children, wraps transparently to maintain actual size.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `as` | `'div'` \| `'span'` | `"div"` | Rendered tag |
+| `circle` | `boolean` | `false` | Circle skeleton (rounded-full) |
+| `width` | `string` \| `number` | - | Width (e.g. '100px', '50%', 200) |
+| `height` | `string` \| `number` | - | Height (e.g. '16px', 40) |
+| `children` | `ReactNode` | - | Inner content (shown when loaded, maintains actual size) |
+| `style` | `ReactNode` | - | Inline style (CSSProperties) |
+| `className` | `string` | - | Style override |
+
+```tsx
+// Basic usage (size via className)
+<Skeleton className="h-4 w-48" />
+<Skeleton className="h-3 w-32" />
+
+// Circular avatar skeleton
+<Skeleton circle width={40} height={40} />
+
+// width/height props
+<Skeleton width="100%" height={120} className="rounded-lg" />
+
+// Match children size
+<Skeleton>
+  <p>Skeleton will match this text size</p>
+</Skeleton>
+
+// With DataList
+<DataList list={data} skeletonElement={<MySkeleton />} skeletonCount={5}>
+  {({ item }) => <Card key={item.id} {...item} />}
+</DataList>
 ```
 
 ---
 
 ## Divider
 
-구분선. 수평/수직 방향, 실선/점선/파선 지원.
+Divider. Supports horizontal/vertical, solid/dashed/dotted.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | 방향 |
-| `variant` | `'solid' \| 'dashed' \| 'dotted'` | `'solid'` | 선 스타일 |
-| `color` | `string` | - | 커스텀 색상 (CSS 값) |
+| `orientation` | `'horizontal'` \| `'vertical'` | `"horizontal"` | Direction |
+| `variant` | `'solid'` \| `'dashed'` \| `'dotted'` | `"solid"` | Line style |
+| `color` | `string` | - | Custom color (CSS value) |
+| `style` | `ReactNode` | - | Inline style (CSSProperties) |
+| `className` | `string` | - | Style override |
 
 ```tsx
 <Divider />
@@ -249,19 +403,22 @@ alwaysApply: false
 
 ## Tooltip
 
-툴팁. Radix Tooltip 기반. 단독 사용 가능 (Provider 내장).
+Tooltip. Based on Radix Tooltip. Built-in Provider.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `content` | `ReactNode` | - | 툴팁 내용 |
-| `variant` | `'dark' \| 'light'` | `'dark'` | 스타일 |
-| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | 위치 |
-| `align` | `'start' \| 'center' \| 'end'` | `'center'` | 정렬 |
-| `delayDuration` | `number` | `200` | 표시 지연 (ms) |
-| `disabled` | `boolean` | `false` | 비활성 |
+| `children` | `ReactNode` | - | Trigger element (ReactNode, required) |
+| `content` | `ReactNode` | - | Tooltip content (ReactNode, required) |
+| `variant` | `'dark'` \| `'light'` | `"dark"` | Style |
+| `side` | `'top'` \| `'right'` \| `'bottom'` \| `'left'` | `"top"` | Position |
+| `align` | `'start'` \| `'center'` \| `'end'` | `"center"` | Alignment |
+| `delayDuration` | `number` | `200` | Show delay (ms) |
+| `disabled` | `boolean` | `false` | Disabled |
+| `className` | `string` | - | Content style |
+| `triggerClassName` | `string` | - | Trigger style |
 
 ```tsx
-<Tooltip content="복사됨!" side="bottom">
+<Tooltip content="Copied!" side="bottom">
   <button>📋</button>
 </Tooltip>
 ```
@@ -270,21 +427,25 @@ alwaysApply: false
 
 ## Popover
 
-팝오버. Radix Popover 기반. 컴포저블 패턴과 단일 패턴 모두 지원.
+Popover. Based on Radix Popover.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `trigger` | `ReactNode` | - | 트리거 요소 |
-| `children` | `ReactNode` | - | 팝오버 내용 |
-| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | 위치 |
-| `align` | `'start' \| 'center' \| 'end'` | `'center'` | 정렬 |
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 너비 |
-| `open` | `boolean` | - | 제어 모드 |
-| `onOpenChange` | `(open: boolean) => void` | - | 열림/닫힘 콜백 |
+| `trigger` | `ReactNode` | - | Trigger element (ReactNode, required) |
+| `side` | `'top'` \| `'right'` \| `'bottom'` \| `'left'` | `"bottom"` | Position |
+| `align` | `'start'` \| `'center'` \| `'end'` | `"center"` | Alignment |
+| `sideOffset` | `number` | `4` | Position offset (px) |
+| `alignOffset` | `number` | - | Alignment offset (px) |
+| `open` | `boolean` | - | Controlled mode |
+| `onOpenChange` | `ReactNode` | - | Open/close state change callback (open: boolean) => void |
+| `onClickTrigger` | `ReactNode` | - | Callback on trigger element click. Passed to PopoverPrimitive.Trigger onClick. |
+| `children` | `ReactNode` | - | Popover body (ReactNode) |
+| `className` | `string` | - | Content style |
+| `arrowClassName` | `string` | - | Arrow style |
 
 ```tsx
-<Popover trigger={<Button variant="outline">메뉴</Button>}>
-  <div className="p-4">팝오버 내용</div>
+<Popover trigger={<Button variant="outline">Menu</Button>}>
+  <div className="p-4">Popover content</div>
 </Popover>
 ```
 
@@ -292,27 +453,29 @@ alwaysApply: false
 
 ## Accordion
 
-아코디언. 단순 `items` 배열 방식과 컴포저블 방식 모두 지원.
+Accordion. Supports both items array and composable patterns.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `items` | `AccordionItemData[]` | - | 항목 배열 |
-| `type` | `'single' \| 'multiple'` | `'single'` | 단일/다중 열기 |
-| `collapsible` | `boolean` | `true` | 전부 접기 가능 |
-| `value` / `defaultValue` | `string \| string[]` | - | 제어/비제어 |
-| `onValueChange` | `(value) => void` | - | 변경 콜백 |
+| `items` | `object`[] | - | Accordion item array (required) |
+| `type` | `'single'` \| `'multiple'` | `"single"` | Single/multiple open mode |
+| `collapsible` | `boolean` | `true` | Allow collapsing all |
+| `value` | `string` \| `string`[] | - | Controlled mode |
+| `defaultValue` | `string` \| `string`[] | - | Uncontrolled initial value |
+| `onValueChange` | `ReactNode` | - | Open item change callback (value: string | string[]) => void |
+| `className` | `string` | - | Root style |
 
 ```tsx
 <Accordion items={[
-  { id: '1', trigger: 'FAQ 1', content: '답변 1' },
-  { id: '2', trigger: 'FAQ 2', content: '답변 2' },
+  { id: '1', trigger: 'FAQ 1', content: 'Answer 1' },
+  { id: '2', trigger: 'FAQ 2', content: 'Answer 2' },
 ]} />
 
-// 컴포저블 방식
+// Composable pattern
 <AccordionRoot type="single" collapsible>
   <AccordionItem value="item-1">
-    <AccordionTrigger>제목</AccordionTrigger>
-    <AccordionContent>내용</AccordionContent>
+    <AccordionTrigger>Title</AccordionTrigger>
+    <AccordionContent>Content</AccordionContent>
   </AccordionItem>
 </AccordionRoot>
 ```
@@ -321,24 +484,41 @@ alwaysApply: false
 
 ## Drawer
 
-드로어/바텀시트. Vaul 기반. 4방향 지원.
+Drawer/bottom sheet. Based on Vaul. Compound component pattern.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `direction` | `'bottom' \| 'top' \| 'left' \| 'right'` | `'bottom'` | 방향 |
-| `showHandle` | `boolean` | `true` | 핸들 바 표시 (top/bottom만) |
-| `blur` | `'none' \| 'sm' \| 'md'` | `'none'` | 오버레이 블러 |
+| `direction` | `'bottom'` \| `'top'` \| `'left'` \| `'right'` | `"bottom"` | Direction |
+| `open` | `boolean` | - | Open state (controlled mode) |
+| `onOpenChange` | `ReactNode` | - | Open state change callback (open: boolean) => void |
+| `dismissible` | `boolean` | - | Allow close via swipe/outside click (default true) |
+| `modal` | `boolean` | - | Modal mode (default true). If false, background is interactive |
+| `shouldScaleBackground` | `boolean` | - | Background scale effect (default false) |
+| `children` | `ReactNode` | - | Drawer sub-components (ReactNode, required) |
+
+### DrawerContent
+
+Drawer.Content area.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `direction` | `'bottom'` \| `'top'` \| `'left'` \| `'right'` | `"bottom"` | Direction (Context takes priority) |
+| `blur` | `'none'` \| `'sm'` \| `'md'` | `"none"` | Overlay blur |
+| `showHandle` | `boolean` | `true` | Show handle bar |
+| `children` | `ReactNode` | - | Content area (ReactNode) |
+| `overlayClassName` | `string` | - | Overlay style |
+| `className` | `string` | - | Panel style |
 
 ```tsx
 <Drawer direction="bottom">
   <Drawer.Trigger asChild>
-    <Button>열기</Button>
+    <Button>Open</Button>
   </Drawer.Trigger>
   <Drawer.Content>
-    <Drawer.Title>제목</Drawer.Title>
-    <Drawer.Description>설명</Drawer.Description>
+    <Drawer.Title>Title</Drawer.Title>
+    <Drawer.Description>Description</Drawer.Description>
     <Drawer.Close asChild>
-      <Button variant="ghost">닫기</Button>
+      <Button variant="ghost">Close</Button>
     </Drawer.Close>
   </Drawer.Content>
 </Drawer>
@@ -346,353 +526,756 @@ alwaysApply: false
 
 ---
 
-## Modal (함수형 API)
+## Modal
 
-명령형 모달. 함수 호출로 열고 닫는다.
+Modal template. All modal components must be wrapped with ModalTemplate.
 
-**중요: 모달 컴포넌트는 반드시 `ModalTemplate`으로 감싸야 한다.**
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `ReactNode` | - | Header title (ReactNode) |
+| `desc` | `ReactNode` | - | Header description (ReactNode) |
+| `layout` | `'default'` \| `'bottom-sheet'` \| `'slide-left'` \| `'slide-right'` \| `'full-page'` \| `'full-page-reverse'` \| `'draggable'` | `"default"` | Layout |
+| `showDim` | `boolean` | `true` | Show dim overlay |
+| `dimClose` | `boolean` | `true` | Close on dim click |
+| `hideHeader` | `boolean` | `false` | Hide header |
+| `hideFooter` | `boolean` | `true` | Hide footer |
+| `footer` | `ReactNode` | - | Custom footer (ReactElement) |
+| `animation` | `object` | - | Modal animation |
+| `enableDrag` | `boolean` | `true` | Enable drag (bottom-sheet/draggable layouts) |
+| `dragPersistKey` | `string` | - | Drag position persistence key |
+| `close` | `ReactNode` | - | Modal close function (isAnimation?: boolean) => void (auto-injected) |
+| `children` | `ReactNode` | - | Modal body (ReactNode, required) |
+| `className` | `string` | - | Root wrapper style |
+| `innerClassName` | `string` | - | Modal body style |
+| `bodyClassName` | `string` | - | Body area style |
+| `footerClassName` | `string` | - | Footer area style |
+| `dimClassName` | `string` | - | Dim overlay style |
+| `headerClassName` | `string` | - | Header area style |
+
+### modal()
+
+modal() function call options. component automatically receives close/resolve as props.
 
-### 모달 컴포넌트 작성법
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `component` | `ReactNode` | - | Modal component (required). Automatically receives close/resolve as props |
+| `props` | `Record<string, any>` | - | Props to pass to component |
+| `id` | `string` | - | Modal ID (used for duplicate check) |
+| `layout` | `'default'` \| `'bottom-sheet'` \| `'slide-left'` \| `'slide-right'` \| `'full-page'` \| `'full-page-reverse'` \| `'draggable'` | - | Layout |
+| `animation` | `object` | - | Modal animation |
+| `scrollEnable` | `boolean` | - | Allow background scroll |
+| `isToggle` | `boolean` | - | Toggle mode (close on re-call of same modal) |
+| `isAlone` | `boolean` | - | Alone mode (close all existing modals before opening) |
+| `duplicateCheck` | `boolean` | - | Prevent duplicate opening of same component |
+| `disableEscapeKeyPress` | `boolean` | - | Disable close via ESC key |
+| `componentName` | `string` | - | Modal identifier name (used for duplicate check, modal search) |
+| `onOpen` | `ReactNode` | - | Callback when modal opens |
+| `onClose` | `ReactNode` | - | Callback when modal closes |
+
+**IMPORTANT: Modal components MUST be wrapped with `ModalTemplate`.**
 
 ```tsx
 import { ModalTemplate } from '@nexus-cross/design-system/modal';
 
-// 모달 컴포넌트는 반드시 close와 resolve를 props로 받는다
 function MyModal({ close, resolve }: { close: () => void; resolve: (value: any) => void }) {
   return (
     <ModalTemplate
-      title="모달 제목"
-      desc="모달 설명 (선택)"
+      title="Modal Title"
+      desc="Modal description (optional)"
       close={close}
-      layout="default"          // 'default' | 'bottom-sheet' | 'slide-left' | 'slide-right' | 'full-page' | 'draggable'
-      hideFooter                // footer 없으면 하단 패딩 자동
+      layout="default"
+      hideFooter
     >
       <div className="space-y-4">
-        <p className="text-text-secondary">모달 내용</p>
-        <Button onClick={() => resolve({ confirmed: true })}>확인</Button>
+        <p className="text-text-secondary">Modal content</p>
+        <Button onClick={() => resolve({ confirmed: true })}>Confirm</Button>
       </div>
     </ModalTemplate>
   );
 }
 ```
 
-### ModalTemplate Props
-
-| Prop | Type | Default | Description |
-|---|---|---|---|
-| `title` | `ReactNode` | - | 헤더 제목 |
-| `desc` | `ReactNode` | - | 헤더 설명 |
-| `close` | `() => void` (필수) | - | 닫기 함수 (props로 자동 주입됨) |
-| `layout` | `'default' \| 'bottom-sheet' \| 'slide-left' \| 'slide-right' \| 'full-page' \| 'full-page-reverse' \| 'draggable'` | `'default'` | 레이아웃 |
-| `showDim` | `boolean` | `true` | 딤 배경 표시 |
-| `dimClose` | `boolean` | `true` | 딤 클릭 시 닫기 |
-| `hideHeader` | `boolean` | `false` | 헤더 숨김 |
-| `hideFooter` | `boolean` | `true` | 푸터 숨김 |
-| `footer` | `ReactElement` | - | 커스텀 푸터 |
-| `enableDrag` | `boolean` | `false` | 드래그 활성화 (draggable 레이아웃) |
-| `dragPersistKey` | `string` | - | 드래그 위치 저장 키 |
-| `innerClassName` | `string` | - | 모달 본체 스타일 오버라이드 |
-| `bodyClassName` | `string` | - | 바디 영역 스타일 오버라이드 |
-
-### 모달 호출
+### Calling a Modal
 
 ```tsx
 import { modal, useModal, ModalContainer } from '@nexus-cross/design-system/modal';
 
-// 앱 루트에 ModalContainer 배치 필수
+// ModalContainer MUST be placed at the app root
 <ModalContainer />
 
-// 방법 1: modal() 함수
+// Method 1: modal() function
 const result = await modal({
   component: MyModal,
-  props: { /* 추가 props */ },
+  props: { /* additional props */ },
 });
 
-// 방법 2: useModal() 훅
+// Method 2: useModal() hook
 const { modal: openModal } = useModal();
 openModal({
   component: MyModal,
-  options: { isAlone: true },  // 단독 모달 (다른 모달 위에 안 쌓임)
+  options: { isAlone: true },
 });
 ```
 
-### 금지 사항
+### Prohibited
 
-- ModalTemplate 없이 `<div>`만으로 모달 컴포넌트를 만들지 않는다
-- `close` prop을 직접 정의하지 않는다 (시스템이 자동 주입)
-- 모달 내에서 별도 dim/overlay를 구현하지 않는다
+- Do NOT create modal components without ModalTemplate (using plain `<div>`)
+- Do NOT define the `close` prop manually (the system injects it automatically)
+- Do NOT implement a separate dim/overlay inside the modal
 
 ---
 
-## Toast (함수형 API)
+## Tab
 
-토스트 알림. Sonner 기반.
+Tab navigation. line/pill variants.
 
-```tsx
-import { toast, Toaster } from '@nexus-cross/design-system';
-
-// 앱 루트에 Toaster 배치
-<Toaster position="top-right" />
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `items` | `object`[] | - | Tab item array (required) |
+| `activeKey` | `string` | - | Controlled mode active key |
+| `defaultActiveKey` | `string` | - | Uncontrolled initial key |
+| `variant` | `'line'` \| `'pill'` | `"line"` | Style |
+| `size` | `'sm'` \| `'md'` | `"md"` | Size |
+| `destroyInactive` | `boolean` | `false` | Unmount inactive panels |
+| `onTabChange` | `ReactNode` | - | Tab change callback (key: string) => void |
+| `className` | `string` | - | Root style |
+| `tabListClassName` | `string` | - | Tab list style |
+| `tabPanelClassName` | `string` | - | Tab panel style |
 
-// 사용
-toast('저장되었습니다');
-toast.success('성공!');
-toast.error('오류가 발생했습니다');
-toast.loading('처리 중...');
+```tsx
+<Tab
+  items={[
+    { key: 'a', label: 'Tab A', children: <p>A</p> },
+    { key: 'b', label: 'Tab B', children: <p>B</p> },
+  ]}
+  defaultActiveKey="a"
+  variant="pill"
+/>
 ```
 
 ---
 
-## InfiniteScroll
+## Carousel
 
-무한 스크롤. IntersectionObserver 기반.
+Carousel. Based on Embla Carousel. Sub-components: CarouselSlide, CarouselPrev, CarouselNext, CarouselDots.
 
-| Prop | Type | Description |
-|---|---|---|
-| `list` | `unknown[]` | 현재 데이터 배열 |
-| `totalCount` | `number` | 전체 개수 (또는 `hasMore` 사용) |
-| `hasMore` | `boolean` | 더 있는지 (또는 `totalCount` 사용) |
-| `handleLoadMore` | `() => void` | 추가 로드 콜백 |
-| `loading` | `boolean` | 로딩 상태 |
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `opts` | `Record<string, any>` | - | Embla options (loop, align, etc.) |
+| `plugins` | `ReactNode`[] | - | Embla plugins |
+| `onApiChange` | `ReactNode` | - | Embla API change callback (api: CarouselApi) => void |
+| `children` | `ReactNode` | - | Carousel slides and sub-components (ReactNode) |
+| `className` | `string` | - | Style override |
+
+Sub-components: `CarouselSlide`, `CarouselPrev`, `CarouselNext`, `CarouselDots`
 
 ```tsx
-<InfiniteScroll
-  list={items}
-  totalCount={100}
-  loading={isLoading}
-  handleLoadMore={fetchMore}
->
-  {items.map(item => <Card key={item.id} {...item} />)}
-</InfiniteScroll>
+<Carousel opts={{ loop: true }}>
+  <CarouselSlide>Slide 1</CarouselSlide>
+  <CarouselSlide>Slide 2</CarouselSlide>
+  <CarouselPrev />
+  <CarouselNext />
+  <CarouselDots />
+</Carousel>
 ```
 
 ---
 
-## Ellipsis
+## Pagination
 
-텍스트 말줄임. 더보기/접기 토글 내장.
+Pagination. Previous/next + page number buttons.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `content` | `ReactNode` | - | 내용 |
-| `lineClamp` | `number` | `2` | 줄 수 제한 |
-| `triggerMore` | `ReactNode` | `'more'` | 더보기 텍스트 |
-| `triggerLess` | `ReactNode` | `'less'` | 접기 텍스트 |
+| `currentPage` | `number` | - | Current page (1-based, required) |
+| `totalPages` | `number` | - | Total page count (required) |
+| `siblingCount` | `number` | `1` | Number of pages shown on each side of current |
+| `showEdges` | `boolean` | - | Always show first/last page |
+| `size` | `'sm'` \| `'md'` | `"md"` | Size |
+| `onPageChange` | `ReactNode` | - | Page change callback (page: number) => void, required |
+| `className` | `string` | - | <nav> style |
 
 ```tsx
-<Ellipsis content={longText} lineClamp={3} triggerMore="더보기" triggerLess="접기" />
+<Pagination currentPage={2} totalPages={10} onPageChange={setPage} />
 ```
 
 ---
 
-## Hooks
+## Avatar
 
-### useModal
+Avatar. Supports image, fallback text, and children.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `src` | `string` | - | Image URL |
+| `alt` | `string` | - | Alt text |
+| `fallback` | `ReactNode` | - | Displayed on image load failure (ReactNode) |
+| `size` | `'xs'` \| `'sm'` \| `'md'` \| `'lg'` \| `'xl'` | `"md"` | Size |
+| `shape` | `'circle'` \| `'square'` | `"circle"` | Shape |
+| `children` | `ReactNode` | - | Custom image element (e.g. Next.js Image) |
+| `onImageError` | `ReactNode` | - | Image load error callback () => void |
+| `className` | `string` | - | Style override |
 
 ```tsx
-const { open, close } = useModal();
-open(MyComponent, { title: '제목' });
+<Avatar src="/user.png" alt="User" size="lg" />
+<Avatar fallback="JD" shape="square" size="sm" />
 ```
 
-### useInView
+---
 
-```tsx
-const { ref, inView } = useInView({ threshold: 0.5 });
-<div ref={ref}>{inView && <LazyContent />}</div>
-```
+## Counter
 
-### useCheckDevice
+Number count animation.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `endValue` | `number` | - | Target value (required) |
+| `startValue` | `number` | `0` | Start value |
+| `duration` | `number` | `1500` | Animation duration (ms) |
+| `delay` | `number` | `0` | Start delay (ms) |
+| `separator` | `boolean` | `true` | Thousands separator |
+| `digits` | `number` | `0` | Decimal places |
+| `triggerOnView` | `boolean` | `false` | Start on viewport entry |
+| `onEnd` | `ReactNode` | - | Count complete callback () => void |
+| `style` | `ReactNode` | - | Inline style (CSSProperties) |
+| `className` | `string` | - | Style override |
 
 ```tsx
-const { isMobile, isTablet, isDesktop } = useCheckDevice();
+<Counter endValue={1234} duration={2000} separator />
 ```
 
-### useClickOutside
+---
+
+## Countdown
+
+Countdown timer.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `endTimestamp` | `number` | - | End time (Unix ms, required) |
+| `separator` | `ReactNode` | `":"` | Separator (ReactNode) |
+| `showDays` | `boolean` | `true` | Show days unit |
+| `labels` | `object` | - | Unit labels |
+| `render` | `ReactNode` | - | Custom render function |
+| `onEnd` | `ReactNode` | - | Countdown end callback () => void |
+| `className` | `string` | - | Style override |
 
 ```tsx
-const ref = useClickOutside<HTMLDivElement>(() => setOpen(false));
-<div ref={ref}>드롭다운 내용</div>
+<Countdown endTimestamp={Date.now() + 60_000} showDays={false} onEnd={handleEnd} />
 ```
 
 ---
 
-## Pagination
+## Marquee
 
-페이지네이션. 이전/다음 + 번호 버튼.
+Marquee (scrolling text/elements).
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `currentPage` | `number` | - | 현재 페이지 (1부터) |
-| `totalPages` | `number` | - | 전체 페이지 수 |
-| `siblingCount` | `number` | `1` | 현재 페이지 양옆 표시 개수 |
-| `onPageChange` | `(page: number) => void` | - | 페이지 변경 콜백 |
-| `size` | `'sm' \| 'md'` | `'md'` | 크기 |
+| `direction` | `'left'` \| `'right'` \| `'up'` \| `'down'` | `"left"` | Direction |
+| `speed` | `number` | `40` | Animation speed (seconds) |
+| `pauseOnHover` | `boolean` | `false` | Pause on hover |
+| `gap` | `number` | `16` | Item gap (px) |
+| `children` | `ReactNode` | - | Content to repeat (ReactNode, required) |
+| `style` | `ReactNode` | - | Inline style (CSSProperties) |
+| `className` | `string` | - | Style override |
 
 ```tsx
-<Pagination currentPage={2} totalPages={10} onPageChange={setPage} />
+<Marquee direction="left" speed={30} pauseOnHover>
+  <span>Scrolling text</span>
+</Marquee>
 ```
 
 ---
 
-## Avatar
+## VirtualList
 
-아바타. 이미지, 폴백 텍스트, children 지원.
+Virtual scroll list. Based on @tanstack/react-virtual.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `src` | `string` | - | 이미지 URL |
-| `alt` | `string` | - | 대체 텍스트 |
-| `fallback` | `ReactNode` | - | 이미지 로드 실패 시 표시 |
-| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | 크기 |
-| `shape` | `'circle' \| 'square'` | `'circle'` | 형태 |
-| `onImageError` | `() => void` | - | 이미지 에러 콜백 |
+| `items` | `ReactNode`[] | - | Data array (required) |
+| `estimateSize` | `number` \| `ReactNode` | - | Estimated item height (number or (index) => number, required) |
+| `renderItem` | `ReactNode` | - | Item renderer (item, index, virtualItem) => ReactNode (required) |
+| `overscan` | `number` | `5` | Overscan count |
+| `gap` | `number` | `0` | Item gap (px) |
+| `className` | `string` | - | Scroll container style |
+| `style` | `ReactNode` | - | Inline style (CSSProperties) |
+| `endReachedThreshold` | `number` | `200` | End detection threshold (px) |
+| `onEndReached` | `ReactNode` | - | End reached callback () => void |
+
+### VirtualGrid
+
+Virtual scroll grid. Based on @tanstack/react-virtual.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `items` | `ReactNode`[] | - | Data array (required) |
+| `columns` | `number` | - | Column count (required) |
+| `estimateSize` | `number` \| `ReactNode` | - | Estimated item height (required) |
+| `renderItem` | `ReactNode` | - | Item renderer (item, index) => ReactNode (required) |
+| `overscan` | `number` | `3` | Overscan count |
+| `gap` | `number` | `0` | Item gap (px) |
+| `className` | `string` | - | Scroll container style |
+| `style` | `ReactNode` | - | Inline style (CSSProperties) |
+| `endReachedThreshold` | `number` | `200` | End detection threshold (px) |
+| `onEndReached` | `ReactNode` | - | End reached callback () => void |
 
 ```tsx
-<Avatar src="/user.png" alt="User" size="lg" />
-<Avatar fallback="JD" shape="square" size="sm" />
+<VirtualList
+  items={data}
+  estimateSize={48}
+  renderItem={(item) => <div>{item.name}</div>}
+  onEndReached={loadMore}
+/>
+```
+
+### VirtualGrid
+
+Same as VirtualList + `columns: number` (required).
+
+```tsx
+<VirtualGrid items={data} estimateSize={120} columns={3} renderItem={(item) => <Card {...item} />} />
 ```
 
 ---
 
-## Counter
+## DataList
 
-숫자 카운트 애니메이션.
+Data list. Automatically handles loading/skeleton/empty/data states based on list. Built-in ErrorBoundary.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `endValue` | `number` (필수) | - | 목표 값 |
-| `startValue` | `number` | `0` | 시작 값 |
-| `duration` | `number` | `1500` | 애니메이션 시간 (ms) |
-| `delay` | `number` | `0` | 시작 지연 (ms) |
-| `separator` | `boolean` | `true` | 천 단위 구분 |
-| `digits` | `number` | `0` | 소수 자릿수 |
-| `triggerOnView` | `boolean` | `false` | 뷰포트 진입 시 시작 |
-| `onEnd` | `() => void` | - | 완료 콜백 |
+| `list` | `ReactNode`[] | - | Data array to render. null = loading state (required) |
+| `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 |
+
+When list is null → **loading**, [] → **empty state**, array → **render**. ErrorBoundary built-in.
+
+- **Default loading**: Without skeletonElement, a Spinner is shown automatically
+- **Skeleton loading**: Pass a custom skeleton component to skeletonElement, rendered skeletonCount times
 
 ```tsx
-<Counter endValue={1234} duration={2000} separator />
+// Basic usage — Spinner shown automatically when list is null
+<DataList list={users} noDataMessage="No users found">
+  {({ item, index }) => <UserCard key={item.id} user={item} />}
+</DataList>
+
+// Skeleton loading — implement and pass a custom skeleton component
+function UserSkeleton() {
+  return (
+    <div className="flex items-center gap-3 px-4 py-3">
+      <Skeleton circle width={32} height={32} />
+      <div className="flex-1 space-y-1.5">
+        <Skeleton className="h-3 w-24" />
+        <Skeleton className="h-2.5 w-16" />
+      </div>
+    </div>
+  );
+}
+
+<DataList
+  list={products}
+  skeletonElement={<UserSkeleton />}
+  skeletonCount={5}
+>
+  {({ item }) => <ProductCard key={item.id} {...item} />}
+</DataList>
 ```
 
 ---
 
-## Countdown
+## InfiniteScroll
 
-카운트다운 타이머.
+Infinite scroll. Based on IntersectionObserver.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `endTimestamp` | `number` (필수) | - | 종료 시각 (Unix ms) |
-| `separator` | `ReactNode` | `':'` | 구분자 |
-| `showDays` | `boolean` | `true` | 일 단위 표시 |
-| `labels` | `{ days?, hours?, minutes?, seconds? }` | - | 단위 라벨 |
-| `onEnd` | `() => void` | - | 완료 콜백 |
-| `render` | `(timeLeft: TimeLeft) => ReactNode` | - | 커스텀 렌더링 |
+| `list` | `ReactNode`[] | - | Current data array (required) |
+| `totalCount` | `number` | - | Total count (mutually exclusive with hasMore) |
+| `hasMore` | `boolean` | - | Has more items (mutually exclusive with totalCount) |
+| `tag` | `string` | `"div"` | Children wrapper tag |
+| `rootMargin` | `number` | `100` | Detection margin (px) |
+| `loading` | `boolean` | - | Loading state |
+| `loadingElement` | `ReactNode` | - | Custom loading element |
+| `handleLoadMore` | `ReactNode` | - | Load more callback () => void, required |
+| `scrollTarget` | `ReactNode` | - | Scroll target element (HTMLElement | Document | MutableRefObject) |
+| `children` | `ReactNode` | - | List item rendering (ReactNode, required) |
+| `className` | `string` | - | Style override |
 
 ```tsx
-<Countdown endTimestamp={Date.now() + 60_000} showDays={false} onEnd={handleEnd} />
+<InfiniteScroll
+  list={items}
+  totalCount={100}
+  loading={isLoading}
+  handleLoadMore={fetchMore}
+>
+  {items.map(item => <Card key={item.id} {...item} />)}
+</InfiniteScroll>
 ```
 
 ---
 
-## Marquee
+## Ellipsis
 
-마퀴(흐르는 텍스트/요소).
+Text ellipsis. Built-in show more/less toggle.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `direction` | `'left' \| 'right' \| 'up' \| 'down'` | `'left'` | 방향 |
-| `speed` | `number` | `40` | 애니메이션 속도 (초) |
-| `pauseOnHover` | `boolean` | `false` | 호버 시 일시정지 |
-| `gap` | `number` | `16` | 아이템 간격 (px) |
+| `content` | `ReactNode` | `""` | Body text (ReactNode) |
+| `lineClamp` | `number` | `2` | Line clamp limit |
+| `triggerMore` | `ReactNode` | `"more"` | Show more text (ReactNode) |
+| `triggerLess` | `ReactNode` | `"less"` | Show less text (ReactNode) |
+| `defaultShortened` | `boolean` | `true` | Initial collapsed state |
+| `observingEnvs` | `boolean`[] | - | Re-measure on external condition change |
+| `onShowMoreLessClick` | `ReactNode` | - | Show more/less click callback () => void |
+| `className` | `string` | - | Style override |
 
 ```tsx
-<Marquee direction="left" speed={30} pauseOnHover>
-  <span>흐르는 텍스트</span>
-</Marquee>
+<Ellipsis content={longText} lineClamp={3} triggerMore="more" triggerLess="less" />
 ```
 
 ---
 
-## Tab
+## NumberInput
 
-탭 네비게이션. line/pill 변형.
+Number input. Accelerated increment on long press. Exposes increment/decrement methods via ref. numberInputBind(ref, direction) binds same acceleration to external buttons.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `items` | `TabItem[]` (필수) | - | 탭 항목 배열 |
-| `activeKey` | `string` | - | 제어 모드 활성 키 |
-| `defaultActiveKey` | `string` | - | 비제어 모드 초기 키 |
-| `variant` | `'line' \| 'pill'` | `'line'` | 스타일 |
-| `size` | `'sm' \| 'md'` | `'md'` | 크기 |
-| `destroyInactive` | `boolean` | `false` | 비활성 패널 언마운트 |
-| `onTabChange` | `(key: string) => void` | - | 탭 변경 콜백 |
+| `value` | `number` \| `string` | - | Current value |
+| `size` | `'sm'` \| `'md'` \| `'lg'` \| `'xl'` | `"md"` | Size |
+| `error` | `boolean` | - | Error state |
+| `min` | `number` | - | Minimum value |
+| `max` | `number` | - | Maximum value |
+| `step` | `number` | `1` | Step increment |
+| `digit` | `number` | `0` | Decimal places |
+| `hideButtons` | `boolean` | `false` | Hide default spin buttons. Use with numberInputBind for external button event binding |
+| `disabled` | `boolean` | - | Disabled |
+| `readOnly` | `boolean` | - | Read-only (includes hiding spin buttons) |
+| `placeholder` | `string` | - | Placeholder |
+| `name` | `string` | - | Form field name |
+| `id` | `string` | - | Element ID |
+| `autoFocus` | `boolean` | - | Auto focus |
+| `onValueChange` | `ReactNode` | - | Value change callback (value: number | undefined) => void |
+| `onBlur` | `ReactNode` | - | Blur callback |
+| `onFocus` | `ReactNode` | - | Focus callback |
+| `className` | `string` | - | Style override |
+
+Press-and-hold accelerates increment/decrement (100ms → 75ms → 50ms → 30ms). Default is right-side vertical spin buttons. Use `numberInputBind(ref, direction)` to bind the same acceleration events to external buttons for free placement.
 
 ```tsx
-<Tab
-  items={[
-    { key: 'a', label: 'Tab A', children: <p>A</p> },
-    { key: 'b', label: 'Tab B', children: <p>B</p> },
-  ]}
-  defaultActiveKey="a"
-  variant="pill"
+// Basic usage — right-side vertical spin buttons
+<NumberInput
+  value={count}
+  onValueChange={setCount}
+  min={0}
+  max={100}
+  step={5}
 />
+
+// External buttons — bind events with numberInputBind
+const ref = useRef<NumberInputRef>(null);
+
+<NumberInput ref={ref} value={count} onValueChange={setCount} hideButtons />
+
+// Buttons can be placed anywhere, completely separate from NumberInput
+<button {...numberInputBind(ref, 'decrement')}><MinusIcon /></button>
+<button {...numberInputBind(ref, 'increment')}><PlusIcon /></button>
+
+// Single invocation (onClick)
+<button onClick={() => ref.current?.increment()}>+1</button>
 ```
 
 ---
 
-## Carousel
+## PriceInput
 
-캐러셀. Embla Carousel 기반. 컴포저블 패턴.
+Price/amount input field with prefix, suffix, balance display, and auto-fill on balance click.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `opts` | `EmblaOptionsType` | `{ loop: false }` | Embla 옵션 |
-| `plugins` | `EmblaPluginType[]` | - | Embla 플러그인 |
-| `onApiChange` | `(api: CarouselApi) => void` | - | API 변경 콜백 |
+| `size` | `'md'` \| `'lg'` \| `'xl'` | `"md"` | Size |
+| `error` | `boolean` | - | Error state (shows danger border) |
+| `prefix` | `boolean` \| `ReactNode` | `true` | Prefix element. true = "$", ReactNode = custom content, false = hidden |
+| `suffix` | `ReactNode` | - | Suffix element after the input (e.g. "CROSSD", icon, ReactNode) |
+| `label` | `ReactNode` | - | Label displayed above the input (ReactNode) |
+| `description` | `ReactNode` | - | Description below the input. Turns red on error (ReactNode) |
+| `balance` | `string` \| `number` | - | Balance value in the header. Clicking fills the input |
+| `balanceLabel` | `string` | `"Balance"` | Label text for balance display |
+| `balanceContent` | `ReactNode` | - | Custom balance display (ReactNode). Replaces default text, keeps click-to-fill |
+| `maxBalance` | `number` | - | Max allowed value. Exceeding auto-applies error state and turns balance red |
+| `separator` | `boolean` | `false` | Display thousands separator (comma). onValueChange receives raw value without commas |
+| `align` | `'left'` \| `'right'` | `"left"` | Text alignment inside the input |
+| `disabled` | `boolean` | - | Disabled |
+| `placeholder` | `string` | - | Placeholder |
+| `value` | `ReactNode` | - | Controlled value |
+| `id` | `string` | - | Element ID |
+| `onValueChange` | `ReactNode` | - | Value change callback (value: string) => void |
+| `onBalanceClick` | `ReactNode` | - | Balance click callback (balance: string | number) => void |
+| `className` | `string` | - | Style override |
 
-서브 컴포넌트: `CarouselSlide`, `CarouselPrev`, `CarouselNext`, `CarouselDots`
+---
 
-```tsx
-<Carousel opts={{ loop: true }}>
-  <CarouselSlide>슬라이드 1</CarouselSlide>
-  <CarouselSlide>슬라이드 2</CarouselSlide>
-  <CarouselPrev />
-  <CarouselNext />
-  <CarouselDots />
-</Carousel>
-```
+## Badge
+
+Badge indicator. Dot or count display. Wraps children when provided.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `count` | `number` | - | Badge count number |
+| `max` | `number` | `99` | Max count (shows "99+" when exceeded) |
+| `dot` | `boolean` | `false` | Show as dot instead of count |
+| `showZero` | `boolean` | `false` | Show badge when count is 0 |
+| `variant` | `'danger'` \| `'primary'` \| `'secondary'` \| `'info'` \| `'success'` \| `'warning'` | `"danger"` | Color variant |
+| `size` | `'sm'` \| `'md'` \| `'lg'` | `"md"` | Size |
+| `offset` | `any` | - | Position offset [x, y] in px |
+| `children` | `ReactNode` | - | Anchor element to attach badge to (ReactNode) |
+| `className` | `string` | - | Style override |
+
+---
+
+## Progress
+
+Progress bar. Linear progress indicator with percentage display.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `number` | `0` | Current progress value |
+| `max` | `number` | `100` | Maximum value |
+| `variant` | `'primary'` \| `'success'` \| `'warning'` \| `'danger'` \| `'info'` | `"primary"` | Color variant |
+| `size` | `'sm'` \| `'md'` \| `'lg'` | `"md"` | Bar height |
+| `showValue` | `boolean` | `false` | Show percentage text |
+| `indeterminate` | `boolean` | `false` | Indeterminate loading animation |
+| `label` | `string` | - | Label text above the bar |
+| `className` | `string` | - | Style override |
+
+---
+
+## Alert
+
+Alert / Banner. Inline notification with icon, title, description.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `variant` | `'info'` \| `'success'` \| `'warning'` \| `'danger'` | `"info"` | Alert type / color |
+| `title` | `string` | - | Alert title (bold) |
+| `children` | `ReactNode` | - | Alert description (ReactNode) |
+| `icon` | `ReactNode` | - | Custom icon (ReactNode). Auto icon by variant if omitted |
+| `closable` | `boolean` | `false` | Show close button |
+| `onClose` | `ReactNode` | - | Close callback () => void |
+| `action` | `ReactNode` | - | Action area (ReactNode, e.g. Button) |
+| `className` | `string` | - | Style override |
+
+---
+
+## EmptyState
+
+Empty state placeholder. Shown when data is empty or unavailable.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `icon` | `ReactNode` | - | Custom icon (ReactNode). Default inbox icon |
+| `title` | `string` | - | Title text |
+| `description` | `string` | - | Description text |
+| `action` | `ReactNode` | - | Action area (ReactNode, e.g. Button) |
+| `size` | `'sm'` \| `'md'` \| `'lg'` | `"md"` | Overall size |
+| `children` | `ReactNode` | - | Additional content (ReactNode) |
+| `className` | `string` | - | Style override |
 
 ---
 
-## VirtualList / VirtualGrid
+## Breadcrumb
 
-가상 스크롤 리스트/그리드. @tanstack/react-virtual 기반.
+Breadcrumb navigation. Shows current location path.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `items` | `object`[] | - | Breadcrumb items array (required) |
+| `separator` | `ReactNode` | - | Custom separator (ReactNode). Default: chevron |
+| `maxItems` | `number` | - | Max visible items (collapses middle with "...") |
+| `className` | `string` | - | Style override |
+
+---
 
-### VirtualList
+## Stepper
+
+Stepper. Step-by-step progress indicator.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `items` | `T[]` (필수) | - | 데이터 배열 |
-| `estimateSize` | `number \| (index: number) => number` (필수) | - | 예상 아이템 높이 |
-| `renderItem` | `(item: T, index: number) => ReactNode` (필수) | - | 렌더러 |
-| `overscan` | `number` | `5` | 오버스캔 |
-| `gap` | `number` | `0` | 아이템 간격 |
-| `onEndReached` | `() => void` | - | 끝 도달 콜백 |
-| `endReachedThreshold` | `number` | `200` | 끝 감지 임계값 (px) |
+| `steps` | `object`[] | - | Step items array (required) |
+| `current` | `number` | `0` | Current step index (0-based) |
+| `status` | `'process'` \| `'error'` | `"process"` | Current step status |
+| `orientation` | `'horizontal'` \| `'vertical'` | `"horizontal"` | Layout direction |
+| `size` | `'sm'` \| `'md'` | `"md"` | Size |
+| `className` | `string` | - | Style override |
+
+---
+
+## DropdownMenu
+
+Dropdown menu. Based on Radix DropdownMenu. Action menu for context/more menus.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | - | Trigger element (ReactNode, required) |
+| `items` | `object`[] | - | Menu items array (required) |
+| `align` | `'start'` \| `'center'` \| `'end'` | `"start"` | Alignment |
+| `side` | `'top'` \| `'right'` \| `'bottom'` \| `'left'` | `"bottom"` | Position |
+| `className` | `string` | - | Trigger wrapper style |
+| `contentClassName` | `string` | - | Content panel style |
+
+---
+
+## ToggleGroup
+
+Toggle group / Segment control. Based on Radix ToggleGroup.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `type` | `'single'` \| `'multiple'` | `"single"` | Selection mode |
+| `items` | `object`[] | - | Toggle items array (required) |
+| `value` | `ReactNode` | - | Controlled value (string | string[]) |
+| `defaultValue` | `ReactNode` | - | Default value |
+| `onValueChange` | `ReactNode` | - | Value change callback |
+| `variant` | `'default'` \| `'outline'` | `"default"` | Style variant |
+| `size` | `'sm'` \| `'md'` \| `'lg'` | `"md"` | Size |
+| `disabled` | `boolean` | - | Disable all items |
+| `className` | `string` | - | Style override |
+
+---
+
+## Slider
+
+Slider / Range input. Based on Radix Slider. Supports single and range mode.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `number`[] | - | Controlled value (number[]). Use [50] for single, [20, 80] for range |
+| `defaultValue` | `number`[] | - | Default value |
+| `min` | `number` | `0` | Minimum |
+| `max` | `number` | `100` | Maximum |
+| `step` | `number` | `1` | Step increment |
+| `size` | `'sm'` \| `'md'` \| `'lg'` | `"md"` | Track height / thumb size |
+| `showValue` | `boolean` | `false` | Show current value text |
+| `formatValue` | `ReactNode` | - | Value format function (value: number) => string |
+| `label` | `string` | - | Label text |
+| `disabled` | `boolean` | - | Disabled |
+| `onValueChange` | `ReactNode` | - | Value change callback (value: number[]) => void |
+| `onValueCommit` | `ReactNode` | - | Committed value callback (on pointer up) |
+| `className` | `string` | - | Style override |
+
+---
+
+## TagInput
+
+Tag input. Enter key to add, Backspace to delete last tag.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string`[] | - | Controlled tags array |
+| `defaultValue` | `string`[] | - | Default tags |
+| `onChange` | `ReactNode` | - | Tags change callback (tags: string[]) => void |
+| `placeholder` | `string` | `"태그 입력 후 Enter"` | Input placeholder |
+| `max` | `number` | - | Maximum number of tags |
+| `disabled` | `boolean` | - | Disabled |
+| `allowDuplicates` | `boolean` | `false` | Allow duplicate tags |
+| `label` | `string` | - | Label text |
+| `description` | `string` | - | Helper text below input |
+| `size` | `'sm'` \| `'md'` \| `'lg'` | `"md"` | Size |
+| `className` | `string` | - | Style override |
+
+---
+
+## NxImage
+
+Enhanced image. Lazy loading, fallback, aspect-ratio support.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `src` | `string` | - | Image source URL |
+| `alt` | `string` | - | Alt text |
+| `fallback` | `ReactNode` | - | Custom fallback element (ReactNode) |
+| `fallbackSrc` | `string` | - | Fallback image URL on error |
+| `aspectRatio` | `string` | - | CSS aspect-ratio (e.g. "16/9", "1/1") |
+| `objectFit` | `'cover'` \| `'contain'` \| `'fill'` \| `'none'` | `"cover"` | Object-fit mode |
+| `lazy` | `boolean` | `true` | Enable lazy loading (loading="lazy") |
+| `wrapperClassName` | `string` | - | Wrapper div style |
+| `className` | `string` | - | Image element style |
+
+---
+
+## DatePicker
+
+DatePicker. Calendar popup for date selection. Based on react-day-picker.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `ReactNode` | - | Controlled date value (Date) |
+| `defaultValue` | `ReactNode` | - | Default date (Date) |
+| `onChange` | `ReactNode` | - | Date change callback (date: Date | undefined) => void |
+| `placeholder` | `string` | `"날짜 선택"` | Placeholder text |
+| `disabled` | `boolean` | `false` | Disabled |
+| `minDate` | `ReactNode` | - | Minimum selectable date (Date) |
+| `maxDate` | `ReactNode` | - | Maximum selectable date (Date) |
+| `locale` | `'ko'` \| `'en'` | `"ko"` | Calendar locale |
+| `formatStr` | `string` | `"yyyy-MM-dd"` | Date format string (date-fns format) |
+| `className` | `string` | - | Style override |
+
+---
+
+## Hooks
+
+### useModal
 
 ```tsx
-<VirtualList
-  items={data}
-  estimateSize={48}
-  renderItem={(item) => <div>{item.name}</div>}
-  onEndReached={loadMore}
-/>
+const { open, close } = useModal();
+open(MyComponent, { title: 'Title' });
 ```
 
-### VirtualGrid
+### useInView
 
-VirtualList와 동일 + `columns: number` (필수).
+```tsx
+const { ref, inView } = useInView({ threshold: 0.5 });
+<div ref={ref}>{inView && <LazyContent />}</div>
+```
+
+### useCheckDevice
 
 ```tsx
-<VirtualGrid items={data} estimateSize={120} columns={3} renderItem={(item) => <Card {...item} />} />
+const { isMobile, isTablet, isDesktop } = useCheckDevice();
 ```
+
+### useClickOutside
+
+```tsx
+const ref = useClickOutside<HTMLDivElement>(() => setOpen(false));
+<div ref={ref}>Dropdown content</div>
+```
+
+---
+
+## Toast (Imperative API)
+
+Toast notifications. Sonner-based.
+
+```tsx
+import { toast, Toaster } from '@nexus-cross/design-system';
+
+// Place Toaster at app root
+<Toaster position="top-right" />
+
+// Usage
+toast('Saved successfully');
+toast.success('Success!');
+toast.error('An error occurred');
+toast.loading('Processing...');
+```
+