@nexus-cross/design-system 1.0.6-beta.2 → 1.0.7

package/DESIGN.md

@@ -0,0 +1,185 @@
+# NEXUS Design System
+
+## Overview
+
+This document defines the visual identity and design principles for projects using `@nexus-cross/design-system`. AI agents should read this file to generate consistent, on-brand UI across the entire project.
+
+## Visual Theme & Atmosphere
+
+The interface prioritizes **clarity, density, and efficiency**. It targets professional data-driven applications — trading platforms, dashboards, and enterprise tools — where information density matters but readability must not be sacrificed.
+
+Design philosophy:
+- **Functional minimalism**: Every visual element serves a purpose. No decorative flourishes.
+- **High contrast hierarchy**: Clear distinction between primary, secondary, and tertiary information.
+- **Calm neutrals with intentional accent**: The UI stays quiet until interaction or status demands attention.
+- **Dark-mode first**: Designed for prolonged screen use. Light mode is equally supported but dark mode is the primary context.
+
+## Color Palette & Roles
+
+### Background layers (depth ordering)
+
+| Token | Role | Light | Dark |
+|---|---|---|---|
+| `bg-default` | Page-level background | `#FFFFFF` | `#1E232E` |
+| `bg-subtle` | Recessed areas, sidebar backgrounds | `#F3F6F8` | `#161A21` |
+| `bg-strong` | Maximum depth contrast | `#ECF0F2` | `#000000` |
+
+### Surface layers (interactive containers)
+
+| Token | Role | Light | Dark |
+|---|---|---|---|
+| `surface-default` | Cards, panels, modals | `#FFFFFF` | `#1E232E` |
+| `surface-subtle` | Secondary panels, nested containers | `#F3F6F8` | `#252B39` |
+| `surface-strong` | Emphasized containers, active sections | `#ECF0F2` | `#363B4C` |
+| `surface-inverted` | High-contrast banners, tooltips | `#161A21` | `#F3F6F8` |
+
+**Rule**: Always layer surfaces in order: `bg` → `surface-default` → `surface-subtle`. Never place `surface-subtle` directly on `bg-default` — use `surface-default` as an intermediate layer.
+
+### Text hierarchy
+
+| Token | Role | When to use |
+|---|---|---|
+| `text-highlight` | Maximum emphasis | Titles, critical numbers, hero stats |
+| `text-primary` | Default readable text | Body text, labels, headings |
+| `text-secondary` | Supporting information | Descriptions, helper text, timestamps |
+| `text-tertiary` | De-emphasized content | Placeholders, disabled labels |
+| `text-muted` | Lowest priority | Watermarks, footnotes |
+
+**Rule**: Never use `text-muted` for any content the user needs to read. It exists only for decorative or supplementary text.
+
+### Accent colors
+
+| Token | Role |
+|---|---|
+| `accent-primary` (teal/green) | Primary CTA, links, active states, brand identity |
+| `accent-secondary` (purple) | Secondary actions, premium features, alternate highlights |
+
+**Rule**: Use `accent-primary` for the single most important action on screen. If there are multiple CTAs, only ONE gets `accent-primary` — the rest use `outline` or `ghost` variants.
+
+### Status colors
+
+| Token | Role | Usage context |
+|---|---|---|
+| `status-success` | Positive outcomes | Completed actions, profit, online status |
+| `status-warning` | Caution needed | Expiring items, approaching limits |
+| `status-danger` | Errors or destructive | Failed actions, losses, delete confirmations |
+| `status-info` | Neutral information | Tips, update notices, general alerts |
+
+**Rule**: Status colors should only appear in context — on alerts, badges, inline messages, or status indicators. Never use status colors for decorative purposes or general theming.
+
+## Typography Rules
+
+- **Font**: System font stack (inherits from the consuming project).
+- **Scale**: 8 levels from `text-xs` (0.75rem) to `text-xl` (1.25rem) for body, plus heading scale `h7`–`h1` and display `sm`–`lg`.
+- **Weight system**: Regular (400) for body, Medium (500) for labels, Semi-bold (600) for headings, Bold (700) for display and h1–h2.
+- **Letter spacing**: `-0.01em` for body text (tighter for readability at small sizes), `0` for headings and labels.
+- **Line height**: Built into each typography token — do not override.
+
+**Rule**: Use typography tokens (`text-text-sm`, `text-heading-h4`, etc.) instead of raw Tailwind sizes. The tokens include coordinated font-size, font-weight, line-height, and letter-spacing.
+
+## Spacing & Layout
+
+### Spacing scale
+
+- **Padding**: `none` (0), `2xs` (4px), `xs` (8px), `sm` (12px), `md` (16px), `lg` (24px), `xl` (32px), `2xl` (40px)
+- **Gap**: `none` (0), `xs` (4px), `sm` (8px), `md` (16px), `lg` (24px), `xl` (32px)
+
+### Control sizes
+
+| Size | Height | Use case |
+|---|---|---|
+| `xs` | 24px | Compact tables, inline actions |
+| `sm` | 32px | Secondary actions, filters |
+| `md` | 40px | Default inputs, buttons |
+| `lg` | 48px | Primary CTAs, prominent inputs |
+
+### Border radius
+
+| Token | Value | Use case |
+|---|---|---|
+| `corner-none` | 0px | Tables, full-width elements |
+| `corner-sm` | 4px | Chips, badges, small elements |
+| `corner-md` | 8px | Buttons, inputs, cards (default) |
+| `corner-lg` | 12px | Modals, large cards |
+| `corner-xl` | 16px | Hero sections, featured cards |
+| `corner-full` | 9999px | Avatars, pills, circular buttons |
+
+**Rule**: Be consistent within a feature. If a card uses `corner-md`, its internal buttons should also use `corner-md` or smaller — never larger than their container.
+
+### Breakpoints
+
+| Token | Value | Context |
+|---|---|---|
+| `screen-xs` | 320px | Small mobile |
+| `screen-sm` | 640px | Mobile |
+| `screen-md` | 768px | Tablet |
+| `screen-lg` | 1024px | Desktop |
+| `screen-xl` | 1280px | Wide desktop |
+| `screen-2xl` | 1440px | Ultra-wide |
+
+## Component Styling Principles
+
+- **Buttons**: `corner-md` (8px) radius by default. Primary actions use `accent-primary` fill with white text. Ghost and outline variants for secondary actions.
+- **Inputs**: `corner-md` radius, `border-default` border, `surface-default` background. Focus state uses `accent-primary` ring.
+- **Cards/Panels**: `surface-default` background, `border-default` border (1px), `corner-md` or `corner-lg` radius. No drop shadows by default — use `shadow-sm` only on hover or elevated contexts.
+- **Modals/Drawers**: `surface-default` background, `corner-lg` radius on visible corners. Overlay uses `opacity-overlay-dim` (0.5).
+- **Chips/Tags**: `corner-sm` (4px) radius, compact padding. Use semantic variants (`accent`, `success`, `danger`) to convey meaning.
+- **Tables**: No border-radius on the table itself. Use `surface-subtle` for alternating rows or header background. `border-default` for cell dividers.
+
+## Elevation & Shadows
+
+| Token | Value | Use case |
+|---|---|---|
+| `shadow-none` | `none` | Default state for most elements |
+| `shadow-sm` | `0 1px 2px 0 rgb(0 0 0 / 0.12)` | Hover states, subtle lift |
+| `shadow-md` | `0 1px 3px 0 rgb(0 0 0 / 0.12)` | Dropdown menus, popovers |
+| `shadow-lg` | `0 2px 8px -1px rgb(0 0 0 / 0.12)` | Modals, drawers |
+| `shadow-xl` | `0 4px 15px -3px rgb(0 0 0 / 0.12)` | Toast notifications |
+
+**Rule**: Prefer borders over shadows for static elements. Shadows should imply interactivity or overlay behavior. A card sitting on a page uses a border, not a shadow.
+
+## Animation & Motion
+
+- **Transitions**: 150ms (fast), 200ms (normal), 300ms (slow). Use `cubic-bezier(0, 0, 0.2, 1)` (ease-out) for most transitions.
+- **Enter animations**: 200ms with ease-out. Elements enter from the direction they were triggered (dropdown from top, drawer from side).
+- **Exit animations**: 150ms with `cubic-bezier(0.4, 0, 1, 1)` (ease-in). Exits are faster than enters.
+
+**Rule**: Only animate properties that benefit the user's understanding of state change (opacity, transform). Never animate color or background-color on large surfaces — it feels sluggish.
+
+## Do's and Don'ts
+
+### Colors
+
+- **Do** use semantic token names (`bg-surface-default`, `text-text-primary`), not raw hex values.
+- **Do** use `accent-primary` sparingly — one primary CTA per visible area.
+- **Don't** use `status-danger` red for non-error purposes (e.g., decorative highlights).
+- **Don't** mix `text-muted` with `bg-subtle` — the contrast ratio is too low for accessibility.
+- **Don't** override dark mode colors manually. The token system handles light/dark switching automatically.
+
+### Typography
+
+- **Do** use the typography token scale. Every text element should map to a token.
+- **Don't** use more than 3 different text sizes in a single card or section.
+- **Don't** use `font-bold` (700) for body text. Bold is reserved for headings and display text.
+
+### Layout
+
+- **Do** use the spacing scale tokens for all padding, margin, and gap values.
+- **Do** maintain consistent spacing within a component: if padding-x is `md`, padding-y should be `sm` or `md`, not `2xs`.
+- **Don't** use arbitrary pixel values (e.g., `p-[13px]`). Snap to the nearest spacing token.
+- **Don't** nest more than 3 surface layers deep. If you need more depth, reconsider the information architecture.
+
+### Components
+
+- **Do** use `@nexus-cross/design-system` components for any matching UI element. Never re-implement buttons, inputs, modals, etc.
+- **Do** use `className` prop for style overrides. The `cn()` utility resolves prefix conflicts automatically.
+- **Don't** use `!important` in className overrides — it's unnecessary and breaks the override system.
+- **Don't** wrap design system components in extra `<div>` elements for styling. Use `className` directly.
+- **Don't** import Radix UI, Headless UI, or similar libraries to build components that already exist in the design system.
+
+### Interaction States
+
+- **Do** provide visual feedback for all interactive elements: hover, focus, active, disabled.
+- **Do** use `focus-visible` outlines (not `focus`) to avoid showing focus rings on click.
+- **Don't** remove focus indicators entirely — they are required for keyboard accessibility.
+- **Don't** use `opacity` below `0.4` for disabled states — it becomes invisible in some contexts.

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

@@ -119,10 +119,14 @@ Text input field. Supports label, description, prefix/suffix icons, clearable, c
 
 ## TextArea
 
-Multi-line text input. Built-in character counter.
+Multi-line text input with label, description, character counter, and resize modes.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
+| `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 |
@@ -941,21 +945,25 @@ Text ellipsis. Built-in show more/less toggle.
 
 ## NumberInput
 
-Number input. Accelerated increment on long press. Exposes increment/decrement methods via ref. numberInputBind(ref, direction) binds same acceleration to external buttons.
+Number input with two variants: basic (chevron arrows) and bind (+/- buttons). Supports label, description, max display (click to fill), accelerated increment on long press. numberInputBind(ref, direction) binds acceleration to external buttons.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
+| `variant` | `'basic'` \| `'bind'` | `"basic"` | Variant: basic (right chevron arrows) or bind (left/right +/- buttons) |
 | `value` | `number` \| `string` | - | Current value |
-| `size` | `'sm'` \| `'md'` \| `'lg'` \| `'xl'` | `"md"` | Size |
+| `size` | `'lg'` \| `'xl'` | `"lg"` | Size |
 | `error` | `boolean` | - | Error state |
 | `min` | `number` | - | Minimum value |
-| `max` | `number` | - | Maximum value |
+| `max` | `number` | - | Maximum value. When set, "Max {value}" is displayed in the header. Clicking it fills the input with the max 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 |
+| `label` | `string` | - | Label text displayed above input |
+| `description` | `string` | - | Description text displayed below input |
+| `showMax` | `boolean` | - | Show "Max {value}" in header (defaults to true when max is set) |
+| `hideButtons` | `boolean` | `false` | Hide built-in buttons. Use with numberInputBind for external button event binding |
 | `disabled` | `boolean` | - | Disabled |
-| `readOnly` | `boolean` | - | Read-only (includes hiding spin buttons) |
-| `placeholder` | `string` | - | Placeholder |
+| `readOnly` | `boolean` | - | Read-only (includes hiding buttons) |
+| `placeholder` | `string` | - | Placeholder (default: "0") |
 | `name` | `string` | - | Form field name |
 | `id` | `string` | - | Element ID |
 | `autoFocus` | `boolean` | - | Auto focus |
@@ -1019,6 +1027,214 @@ Price/amount input field with prefix, suffix, balance display, and auto-fill on
 
 ---
 
+## 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 |
+
+---
+
+## Breadcrumb
+
+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 |
+
+---
+
+## Stepper
+
+Stepper. Step-by-step progress indicator.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `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

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

@@ -43,35 +43,50 @@ Dividers (2)                 → <Divider>
 |---|---|---|
 | Button | `<Button>` | `import { Button } from '@nexus-cross/design-system'` |
 | Text input | `<TextInput>` | `import { TextInput } from '@nexus-cross/design-system'` |
+| Price / currency input | `<PriceInput>` | `import { PriceInput } from '@nexus-cross/design-system'` |
 | Text area | `<TextArea>` | `import { TextArea } from '@nexus-cross/design-system'` |
+| Number input | `<NumberInput>` | `import { NumberInput } from '@nexus-cross/design-system'` |
 | Select / Dropdown | `<Select>` + `<SelectItem>` | `import { Select, SelectItem } from '@nexus-cross/design-system'` |
+| Dropdown menu / Context menu | `<DropdownMenu>` | `import { DropdownMenu } from '@nexus-cross/design-system'` |
 | Checkbox | `<CheckBox>` | `import { CheckBox } from '@nexus-cross/design-system'` |
 | Radio group | `<RadioGroup>` + `<RadioItem>` | `import { RadioGroup, RadioItem } from '@nexus-cross/design-system'` |
 | Toggle / Switch | `<Switch>` | `import { Switch } from '@nexus-cross/design-system'` |
-| Chip / Tag / Badge | `<Chip>` | `import { Chip } from '@nexus-cross/design-system'` |
-| Loading spinner | `<Spinner>` | `import { Spinner } from '@nexus-cross/design-system'` |
-| Divider | `<Divider>` | `import { Divider } from '@nexus-cross/design-system'` |
-| Tooltip | `<Tooltip>` | `import { Tooltip } from '@nexus-cross/design-system'` |
-| Popover | `<Popover>` | `import { Popover } from '@nexus-cross/design-system'` |
-| Accordion / Collapsible | `<Accordion>` | `import { Accordion } from '@nexus-cross/design-system'` |
-| Drawer / Bottom sheet | `<Drawer>` | `import { Drawer } from '@nexus-cross/design-system'` |
-| Modal / Dialog | `openModal()` | `import { openModal } from '@nexus-cross/design-system'` |
-| Toast / Notification | `toast()` | `import { toast } from '@nexus-cross/design-system'` |
+| Toggle group / Segmented control | `<ToggleGroup>` | `import { ToggleGroup } from '@nexus-cross/design-system'` |
+| Slider / Range | `<Slider>` | `import { Slider } from '@nexus-cross/design-system'` |
+| Tag input / Multi-value input | `<TagInput>` | `import { TagInput } from '@nexus-cross/design-system'` |
+| Date picker | `<DatePicker>` | `import { DatePicker } from '@nexus-cross/design-system'` |
+| Chip / Tag | `<Chip>` | `import { Chip } from '@nexus-cross/design-system'` |
+| Badge / Status dot | `<Badge>` | `import { Badge } from '@nexus-cross/design-system'` |
+| Avatar / Profile | `<Avatar>` | `import { Avatar } from '@nexus-cross/design-system'` |
+| Image / Lazy image | `<NxImage>` | `import { NxImage } from '@nexus-cross/design-system'` |
 | Table | `<Table>` | `import { Table, TableRow, TdColumn } from '@nexus-cross/design-system'` |
-| Infinite scroll | `<InfiniteScroll>` | `import { InfiniteScroll } from '@nexus-cross/design-system'` |
+| Accordion / Collapsible | `<Accordion>` | `import { Accordion } from '@nexus-cross/design-system'` |
 | Text ellipsis | `<Ellipsis>` | `import { Ellipsis } from '@nexus-cross/design-system'` |
-| Pagination | `<Pagination>` | `import { Pagination } from '@nexus-cross/design-system'` |
-| Number input | `<NumberInput>` | `import { NumberInput } from '@nexus-cross/design-system'` |
-| Avatar / Profile | `<Avatar>` | `import { Avatar } from '@nexus-cross/design-system'` |
 | Counter | `<Counter>` | `import { Counter } from '@nexus-cross/design-system'` |
 | Countdown | `<Countdown>` | `import { Countdown } from '@nexus-cross/design-system'` |
-| Marquee | `<Marquee>` | `import { Marquee } from '@nexus-cross/design-system'` |
+| Data list | `<DataList>` | `import { DataList } from '@nexus-cross/design-system'` |
+| Empty state / No data | `<EmptyState>` | `import { EmptyState } from '@nexus-cross/design-system'` |
 | Tab | `<Tab>` | `import { Tab } from '@nexus-cross/design-system'` |
+| Breadcrumb | `<Breadcrumb>` | `import { Breadcrumb } from '@nexus-cross/design-system'` |
+| Stepper / Steps | `<Stepper>` | `import { Stepper } from '@nexus-cross/design-system'` |
+| Pagination | `<Pagination>` | `import { Pagination } from '@nexus-cross/design-system'` |
 | Carousel / Slider | `<Carousel>` | `import { Carousel, CarouselSlide } from '@nexus-cross/design-system'` |
+| Modal / Dialog | `openModal()` | `import { openModal } from '@nexus-cross/design-system'` |
+| Toast / Notification | `toast()` | `import { toast } from '@nexus-cross/design-system'` |
+| Drawer / Bottom sheet | `<Drawer>` | `import { Drawer } from '@nexus-cross/design-system'` |
+| Popover | `<Popover>` | `import { Popover } from '@nexus-cross/design-system'` |
+| Tooltip | `<Tooltip>` | `import { Tooltip } from '@nexus-cross/design-system'` |
+| Loading spinner | `<Spinner>` | `import { Spinner } from '@nexus-cross/design-system'` |
+| Progress bar | `<Progress>` | `import { Progress } from '@nexus-cross/design-system'` |
+| Alert / Banner | `<Alert>` | `import { Alert } from '@nexus-cross/design-system'` |
+| Skeleton loader | `<Skeleton>` | `import { Skeleton } from '@nexus-cross/design-system'` |
+| Divider | `<Divider>` | `import { Divider } from '@nexus-cross/design-system'` |
+| Marquee | `<Marquee>` | `import { Marquee } from '@nexus-cross/design-system'` |
+| Infinite scroll | `<InfiniteScroll>` | `import { InfiniteScroll } from '@nexus-cross/design-system'` |
 | Virtual scroll list | `<VirtualList>` | `import { VirtualList } from '@nexus-cross/design-system'` |
 | Virtual scroll grid | `<VirtualGrid>` | `import { VirtualGrid } from '@nexus-cross/design-system'` |
-| Data list | `<DataList>` | `import { DataList } from '@nexus-cross/design-system'` |
-| Skeleton loader | `<Skeleton>` | `import { Skeleton } from '@nexus-cross/design-system'` |
+| Client-only render | `<ClientOnly>` | `import { ClientOnly } from '@nexus-cross/design-system'` |
+| Error boundary | `<ErrorBoundary>` | `import { ErrorBoundary } from '@nexus-cross/design-system'` |
 
 ## Visual Pattern → Component Mapping
 
@@ -83,9 +98,21 @@ The table above maps by Figma element name, which can miss **visual patterns**.
 | Icon-only button (hamburger, X, settings, app launcher, etc.) | `<Button variant="ghost">` or `<Button variant="outlined">` | Using native `<button>` |
 | Horizontal filter/tab group (single selection) | `<Tab>` | Repeating `<button>` manually |
 | Small label / badge / status indicator (Yes/No, Active, New, etc.) | `<Chip>` | Using native `<span>` |
+| Numeric badge / notification count dot | `<Badge>` | Using absolute-positioned `<span>` manually |
 | Number increment/decrement UI (+/- buttons) | `<NumberInput>` + `numberInputBind` | Using `<input type="number">` + custom buttons |
+| Price / currency input with prefix ($, ₩) | `<PriceInput>` | Using `<TextInput>` + manual formatting |
+| Multi-tag / multi-value input field | `<TagInput>` | Building custom chip array + input |
+| Right-click or kebab menu | `<DropdownMenu>` | Using `<Popover>` + manual list |
+| Segmented button group (multi-option toggle) | `<ToggleGroup>` | Using multiple `<Button>` manually |
+| Step indicator / wizard progress | `<Stepper>` | Using numbered divs manually |
+| Breadcrumb navigation trail | `<Breadcrumb>` | Using `<span>` + separator manually |
+| Progress / loading bar | `<Progress>` | Using `<div>` with width percentage |
+| Alert / info / warning / error banner | `<Alert>` | Using styled `<div>` with icon |
+| Empty state / no data placeholder | `<EmptyState>` | Building custom empty UI per component |
 | Data list with loading/empty states | `<DataList>` | Using `{list.map()}` + manual conditional rendering |
 | Overflowing text | `<Ellipsis>` | Applying `truncate` / `line-clamp` directly |
+| Range slider | `<Slider>` | Using native `<input type="range">` |
+| Date selection | `<DatePicker>` | Using native `<input type="date">` |
 
 ## Utilities & Hooks
 
@@ -125,7 +152,7 @@ import { buttonVariants } from '@nexus-cross/design-system';
 </a>
 ```
 
-Available variant functions: `buttonVariants`, `chipVariants`, `switchVariants`, `textInputVariants`, `textAreaVariants`, `checkBoxVariants`, `radioGroupVariants`, `radioItemVariants`, `dividerVariants`, `selectTriggerVariants`, `selectContentVariants`, `tooltipContentVariants`, `popoverContentVariants`, `drawerContentVariants`
+Available variant functions: `buttonVariants`, `chipVariants`, `badgeVariants`, `switchVariants`, `textInputVariants`, `textAreaVariants`, `priceInputVariants`, `numberInputVariants`, `checkBoxVariants`, `radioGroupVariants`, `radioItemVariants`, `dividerVariants`, `selectTriggerVariants`, `selectContentVariants`, `tooltipContentVariants`, `popoverContentVariants`, `drawerContentVariants`, `toggleGroupVariants`, `sliderVariants`, `tagInputVariants`, `progressVariants`, `alertVariants`, `emptyStateVariants`, `stepperVariants`, `tabListVariants`, `tabTriggerVariants`, `paginationVariants`
 
 ## When Customization Is Needed
 

package/dist/alert.js

@@ -0,0 +1,16 @@
+'use strict';
+
+var chunk5PQ3UCKF_js = require('./chunks/chunk-5PQ3UCKF.js');
+require('./chunks/chunk-CZC76ZD5.js');
+require('./chunks/chunk-JNMCYWGY.js');
+
+
+
+Object.defineProperty(exports, "Alert", {
+  enumerable: true,
+  get: function () { return chunk5PQ3UCKF_js.Alert; }
+});
+Object.defineProperty(exports, "alertVariants", {
+  enumerable: true,
+  get: function () { return chunk5PQ3UCKF_js.alertVariants; }
+});

package/dist/alert.mjs

@@ -0,0 +1,3 @@
+export { Alert, alertVariants } from './chunks/chunk-2UPGFY6E.mjs';
+import './chunks/chunk-MCKOWMLS.mjs';
+import './chunks/chunk-CVYXRSXT.mjs';

package/dist/badge.js

@@ -0,0 +1,16 @@
+'use strict';
+
+var chunkS2GMEC43_js = require('./chunks/chunk-S2GMEC43.js');
+require('./chunks/chunk-CZC76ZD5.js');
+require('./chunks/chunk-JNMCYWGY.js');
+
+
+
+Object.defineProperty(exports, "Badge", {
+  enumerable: true,
+  get: function () { return chunkS2GMEC43_js.Badge; }
+});
+Object.defineProperty(exports, "badgeVariants", {
+  enumerable: true,
+  get: function () { return chunkS2GMEC43_js.badgeVariants; }
+});

package/dist/badge.mjs

@@ -0,0 +1,3 @@
+export { Badge, badgeVariants } from './chunks/chunk-CUTMLBC3.mjs';
+import './chunks/chunk-MCKOWMLS.mjs';
+import './chunks/chunk-CVYXRSXT.mjs';

package/dist/breadcrumb.js

@@ -0,0 +1,12 @@
+'use strict';
+
+var chunk3ZWN66YH_js = require('./chunks/chunk-3ZWN66YH.js');
+require('./chunks/chunk-CZC76ZD5.js');
+require('./chunks/chunk-JNMCYWGY.js');
+
+
+
+Object.defineProperty(exports, "Breadcrumb", {
+  enumerable: true,
+  get: function () { return chunk3ZWN66YH_js.Breadcrumb; }
+});

package/dist/breadcrumb.mjs

@@ -0,0 +1,3 @@
+export { Breadcrumb } from './chunks/chunk-EJY7IVSK.mjs';
+import './chunks/chunk-MCKOWMLS.mjs';
+import './chunks/chunk-CVYXRSXT.mjs';