@nexus-cross/design-system 1.1.0 → 2.0.0-beta.1

package/claude-rules/nexus/CLAUDE.md

@@ -34,7 +34,13 @@
 
 ---
 
-## Quick Component Import
+## Quick Install (단일 패키지)
+
+```bash
+npm install @nexus-cross/design-system   # 토큰/도메인 토큰까지 자동 transitive install
+```
+
+## Quick Component / Token Import
 
 ```tsx
 import {
@@ -47,25 +53,47 @@ import {
 } from '@nexus-cross/design-system';
 
 import { modal, useModal, ModalTemplate, ModalContainer } from '@nexus-cross/design-system/modal';
+
+// 토큰 JS API (sub-path)
+import { getTheme } from '@nexus-cross/design-system/tokens';
+import { getPredictionTheme } from '@nexus-cross/design-system/tokens-domains';
 ```
 
 ---
 
 ## CSS Setup (한 번만)
 
-### Tailwind v4
+### Tailwind v4 (Next + Turbopack / Vite 등 모든 환경) — **2줄 셋업**
+
+**design-system + 토큰을 함께 쓸 때 (대부분의 경우):**
 ```css
+/* globals.css */
 @import 'tailwindcss';
-@import '@nexus-cross/tokens/company.css';
-/* Next.js Turbopack only: */
+@import '@nexus-cross/design-system/tailwind-v4.css';
+/* 도메인 토큰 사용 시 한 줄 추가 */
+/* @import '@nexus-cross/design-system/tokens-domains/prediction.css'; */
+```
+
+`tailwind-v4.css` 안에서 회사 공통 토큰이 sub-path를 통해 자동 로드되므로 **토큰 import를 따로 쓸 필요 없습니다.** 컴포넌트 CSS는 Tailwind의 `components` 레이어에 주입되어 `className="bg-red-500"` 오버라이드가 항상 utility에 우선합니다.
+
+**디자인 토큰만 쓸 때 (design-system 없이):** `@nexus-cross/tokens`를 별도 설치하고 `@import '@nexus-cross/tokens/company.css';` 사용.
+
+**`@layer base, nexus, components, utilities;` statement를 직접 쓰지 마세요.** Tailwind v4 프로세서가 자동 정리/제거하기 때문에 의도와 다르게 동작합니다.
+
+### Tailwind v3 / 순수 CSS
+```css
+/* globals.css */
+@import '@nexus-cross/design-system/tokens/css';
 @import '@nexus-cross/design-system/styles.css';
+@tailwind base; @tailwind components; @tailwind utilities;
 ```
+또는 entry에서 `import '@nexus-cross/design-system/styles'`.
 
-### Next.js Turbopack
+### Next.js (모든 버전)
 ```js
 // next.config.mjs
 const nextConfig = {
-  transpilePackages: ['@nexus-cross/design-system', '@nexus-cross/tokens'],
+  transpilePackages: ['@nexus-cross/design-system'],
 }
 ```
 

package/cursor-rules/CLAUDE.md

@@ -25,33 +25,62 @@
 
 4. **`className` 오버라이드 시 `!important` 금지.** `cn()` 유틸이 프리픽스 충돌 자동 해소.
 
-## Component Import
+## 설치 (단일 패키지)
+
+v2.0부터 `@nexus-cross/design-system` 1개 install로 토큰까지 모두 사용 가능합니다.
+
+```bash
+npm install @nexus-cross/design-system
+```
+
+## Component / Token Import
 
 ```tsx
+// UI 컴포넌트
 import { Button, TextInput, TextArea, Select, Switch, Chip, Spinner, Divider } from '@nexus-cross/design-system';
 import { Tooltip, Popover, Drawer, Accordion } from '@nexus-cross/design-system';
 import { toast, Toaster } from '@nexus-cross/design-system';
 import { modal, useModal, ModalTemplate, ModalContainer } from '@nexus-cross/design-system/modal';
-import { NumberInput, numberInputBind } from '@nexus-cross/design-system';
-import { Avatar, Tab, ToggleGroup } from '@nexus-cross/design-system';
-import { cn } from '@nexus-cross/design-system';
+import { NumberInput, numberInputBind, Avatar, Tab, ToggleGroup, cn } from '@nexus-cross/design-system';
+
+// 토큰 JS API (sub-path)
+import { getTheme } from '@nexus-cross/design-system/tokens';
+import { getPredictionTheme } from '@nexus-cross/design-system/tokens-domains';
 ```
 
 ## CSS Setup
 
-### Tailwind v4
+### Tailwind v4 (Next + Turbopack / Vite 등 모든 환경) — **2줄 셋업**
+
+**design-system + 토큰을 함께 쓸 때 (대부분의 경우):**
 ```css
+/* globals.css */
 @import 'tailwindcss';
-@import '@nexus-cross/tokens/company.css';
-/* Next.js Turbopack only: */
+@import '@nexus-cross/design-system/tailwind-v4.css';
+/* 도메인 토큰 사용 시 한 줄 추가 */
+/* @import '@nexus-cross/design-system/tokens-domains/prediction.css'; */
+```
+
+`tailwind-v4.css` 안에서 회사 공통 토큰이 자동 로드되므로 **토큰 import를 따로 쓸 필요 없습니다.** 컴포넌트 CSS는 Tailwind의 `components` 레이어에 주입되어 `className="bg-red-500"` 오버라이드가 항상 utility에 우선합니다.
+
+**디자인 토큰만 쓸 때 (design-system 없이):** `@nexus-cross/tokens`를 별도 설치하고 `@import '@nexus-cross/tokens/company.css';` 사용.
+
+**절대 직접 `@layer base, nexus, components, utilities;` 같은 statement를 globals.css에 쓰지 말 것.** Tailwind v4 프로세서가 자동 정리해버려 의도와 다르게 동작합니다.
+
+### Tailwind v3 / 순수 CSS
+```css
+/* globals.css */
+@import '@nexus-cross/design-system/tokens/css';
 @import '@nexus-cross/design-system/styles.css';
+@tailwind base; @tailwind components; @tailwind utilities;
 ```
+또는 entry에서 `import '@nexus-cross/design-system/styles'`.
 
-### Next.js Turbopack
+### Next.js (모든 버전)
 ```js
 // next.config.mjs
 const nextConfig = {
-  transpilePackages: ['@nexus-cross/design-system', '@nexus-cross/tokens'],
+  transpilePackages: ['@nexus-cross/design-system'],
 }
 ```
 

package/cursor-rules/nexus-project-setup.mdc

@@ -13,28 +13,41 @@ This project uses NEXUS Design System. All generated code MUST follow the rules
 - **UI Components**: `@nexus-cross/design-system` (React, CVA + Plain CSS)
 - **Styling**: Tailwind CSS v4 + NEXUS semantic tokens
 
-## Design System CSS Setup
+## Install (단일 패키지)
 
-Choose one of two CSS entry points depending on the project environment:
+v2.0부터 design-system 1개 install로 토큰까지 모두 가능합니다.
 
-| Environment | import | Description |
-|---|---|---|
-| Tailwind v3 / Plain CSS / CSS Modules | `@nexus-cross/design-system/styles` | unlayered CSS |
-| Tailwind v4 | `@nexus-cross/design-system/styles/layer` | wrapped in `@layer nexus` |
+```bash
+npm install @nexus-cross/design-system   # @nexus-cross/tokens, tokens-domains 자동 transitive install
+```
 
-```tsx
-// Tailwind v3, Plain CSS, CSS Modules
-import '@nexus-cross/design-system/styles'
+토큰만 단독으로 쓰는 경우엔 `npm install @nexus-cross/tokens` (또는 `tokens-domains`) 가능.
 
-// Tailwind v4
-import '@nexus-cross/design-system/styles/layer'
-```
+## Design System CSS Setup
 
-For Tailwind v4 projects, also declare layer order in `globals.css`:
+| Environment | Setup |
+|---|---|
+| **Tailwind v4** (Next + Turbopack / Vite 등) | `globals.css`에서 2줄: `@import 'tailwindcss';` + `@import '@nexus-cross/design-system/tailwind-v4.css';` |
+| Tailwind v3 | `globals.css`에 `@import '@nexus-cross/design-system/tokens/css';` + `@import '@nexus-cross/design-system/styles.css';` |
+| Plain CSS / CSS Modules | `@import '@nexus-cross/design-system/tokens/css';` + entry에서 `import '@nexus-cross/design-system/styles'` |
+
+### Tailwind v4 — **2줄 셋업** (권장)
+
+**design-system + 토큰을 함께 쓸 때 (대부분의 경우):**
 ```css
-@layer base, nexus, components, utilities;
+/* globals.css */
+@import 'tailwindcss';
+@import '@nexus-cross/design-system/tailwind-v4.css';
+/* 도메인 토큰 사용 시 */
+/* @import '@nexus-cross/design-system/tokens-domains/prediction.css'; */
 ```
 
+`tailwind-v4.css` 안에서 회사 공통 토큰이 sub-path를 통해 자동 로드되므로 **토큰 import를 따로 쓸 필요 없습니다.** 컴포넌트 CSS는 Tailwind의 `components` 레이어에 주입되어 `className="bg-red-500"` 오버라이드가 항상 utility에 우선합니다.
+
+**디자인 토큰만 쓸 때 (design-system 없이):** `@nexus-cross/tokens`를 별도 설치하고 `@import '@nexus-cross/tokens/company.css';` 사용.
+
+**`@layer base, nexus, components, utilities;` 같은 statement를 직접 쓰지 마세요.** Tailwind v4 프로세서가 자동으로 정리/제거하기 때문에 의도와 다르게 동작합니다.
+
 ## Absolute Rules
 
 1. **Always use NEXUS tokens for colors.** Hardcoding is prohibited.
@@ -225,8 +238,9 @@ import { toast, Toaster } from '@nexus-cross/design-system';
 // Modal system (separate subpath)
 import { modal, useModal, ModalTemplate, ModalContainer } from '@nexus-cross/design-system/modal';
 
-// Tokens (only when JS API is needed)
-import { getTheme } from '@nexus-cross/tokens';
+// Tokens (sub-path — design-system 1개 install로 사용 가능)
+import { getTheme } from '@nexus-cross/design-system/tokens';
+import { getPredictionTheme } from '@nexus-cross/design-system/tokens-domains';
 ```
 
 ## Modal Writing Rules

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

@@ -241,7 +241,7 @@ Individual option within Select.
 
 ## Combobox
 
-Searchable select. Text input + popover listbox. Single/multi-select. Sync (auto-filter) or async (onSearch + loading) modes.
+Searchable select with compound option API. Text input + popover listbox. Single/multi-select. Sync (auto-filter) or async (onSearch + loading) modes.
 
 WHEN TO USE:
   • Options ≥ 7, OR labels are long, OR search/filter is needed → Combobox (not Select)
@@ -249,8 +249,29 @@ WHEN TO USE:
   • Async data from server → set onSearch + loading
 For ≤7 simple options use Select. For free-text tags use TagInput.
 
+COMPOUND API:
+  <Combobox value={v} onValueChange={setV} placeholder="…">
+    <Combobox.Option value="kr">한국</Combobox.Option>
+    <Combobox.Option value="jp" disabled>
+      일본
+      <Combobox.OptionDescription>품절</Combobox.OptionDescription>
+      <Combobox.OptionMeta>JP</Combobox.OptionMeta>
+    </Combobox.Option>
+  </Combobox>
+
+  • <Combobox.Option> requires unique `value` (dev mode warns on duplicates and drops the duplicate)
+  • <Combobox.OptionDescription> = secondary line under label
+  • <Combobox.OptionMeta> = right-aligned slot (price, shortcut, badge)
+  • Both slots are excluded from textValue-based search
+
 ASYNC PATTERN:
-  <Combobox options={results} loading={isFetching} onSearch={(q) => mutate(q)} />
+  <Combobox loading={isFetching} onSearch={(q) => mutate(q)}>
+    {results.map((u) => (
+      <Combobox.Option key={u.id} value={u.id}>{u.name}
+        <Combobox.OptionDescription>{u.email}</Combobox.OptionDescription>
+      </Combobox.Option>
+    ))}
+  </Combobox>
   — onSearch fires after searchDebounce (default 250ms). Do NOT clear input on result update; component preserves user's typing.
 
 IME (Korean/Japanese/Chinese): Enter during composition is ignored automatically — do not add custom keydown handlers.
@@ -258,19 +279,22 @@ IME (Korean/Japanese/Chinese): Enter during composition is ignored automatically
 ANTI-PATTERNS:
   ✗ <Select> with 20 options → <Combobox>
   ✗ Manual <input> + dropdown div + filter logic → <Combobox>
+  ✗ Passing options through a prop array (legacy API removed) → use <Combobox.Option> children
+  ✗ Wrapping options in extra elements (<div><Combobox.Option/></div>) → keep them as direct children
+  ✗ Same `value` on two <Combobox.Option> — duplicates are warned + dropped in dev mode
   ✗ Setting value externally to clear input mid-typing → use onValueChange instead
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `options` | `ReactNode` | - | Available options array (ComboboxOption[], required) |
+| `children` | `ReactNode` | - | <Combobox.Option> elements (required). Other children are ignored with a dev-mode warning. Async-search consumers swap this list as `onSearch` results arrive. |
 | `value` | `ReactNode` | - | Selected value. string for single, string[] for multiple |
 | `defaultValue` | `ReactNode` | - | Initial value (uncontrolled) |
 | `onValueChange` | `ReactNode` | - | Value change callback. (value: string | string[]) => void |
 | `multiple` | `boolean` | `false` | Multi-select mode. Selected values shown as chips inside input |
-| `onSearch` | `ReactNode` | - | Async search callback. (query: string) => void. Triggers external data fetching with debounce |
+| `onSearch` | `ReactNode` | - | Async search callback. (query: string) => void. Triggers external data fetching with debounce. When set, the built-in client filter is disabled — render whatever <Combobox.Option> children match the latest results. |
 | `searchDebounce` | `number` | `250` | Debounce delay (ms) before onSearch fires |
-| `loading` | `boolean` | `false` | Externally-controlled loading state. Shows spinner in input suffix |
-| `filter` | `ReactNode` | - | Custom client-side filter. (option, query) => boolean. Default: case-insensitive label includes match |
+| `loading` | `boolean` | `false` | Externally-controlled loading state. Shows spinner in input suffix and a status row inside the popover. |
+| `filter` | `ReactNode` | - | Custom client-side filter. (option: { value, textValue, disabled }, query: string) => boolean. Default: case-insensitive textValue includes match. Ignored when onSearch is set. |
 | `placeholder` | `string` | - | Input placeholder |
 | `emptyMessage` | `ReactNode` | - | Message when no options match (string | ReactNode). Default: "검색 결과 없음" |
 | `loadingMessage` | `ReactNode` | - | Message during loading state inside popover (string | ReactNode). Default: "검색 중…" |
@@ -284,83 +308,140 @@ ANTI-PATTERNS:
 | `className` | `string` | - | Wrapper className |
 | `popoverClassName` | `string` | - | Popover content className |
 
-### ComboboxOption
+### Combobox.Option
+
+Single Combobox option. Direct child of <Combobox> only.
+
+WHEN TO USE:
+  • One per selectable item; `value` MUST be unique within the Combobox
+  • Wrap rich content (icons, badges) directly as children — no escape hatch needed
+  • Use textValue when label is non-text (e.g. <Combobox.Option value="apple" textValue="사과 apple">🍎</Combobox.Option>)
+
+ANTI-PATTERNS:
+  ✗ <Combobox><div><Combobox.Option/></div></Combobox> — Option must be a direct child
+  ✗ Same value on two options → dev warning + silent drop; pick unique values
+  ✗ Putting label text inside <Combobox.OptionDescription> — that slot is the secondary line below the label
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `value` | `string` | - | Unique value (string, required). Duplicate values within one Combobox produce a dev-mode console.error and the duplicate option is dropped. |
+| `disabled` | `boolean` | - | Disable selection. Skipped by keyboard navigation (Arrow Up/Down, Home/End). |
+| `textValue` | `string` | - | Text used for client-side filtering and the input display when this option is selected. If omitted, derived from `children` (string nodes only; OptionDescription / OptionMeta are excluded). Set this when label contains icons or non-text nodes you still want searchable (e.g. textValue="apple 사과 fruit"). |
+| `className` | `string` | - | Class merged onto the rendered <div role="option">. |
+| `children` | `ReactNode` | - | Label content + optional <Combobox.OptionDescription> / <Combobox.OptionMeta> slots. |
+
+### Combobox.OptionDescription
+
+Secondary text shown below an option label. Use for hints like "Republic of Korea" beneath "한국". Excluded from textValue-based search.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | - | Secondary text below the label (ReactNode). |
+| `className` | `string` | - | Class for the description node. |
+
+### Combobox.OptionMeta
 
-Single Combobox option.
+Right-aligned slot inside an option. Use for prices, keyboard shortcuts, version tags, status badges. Excluded from textValue-based search.
 
 | Prop | Type | Default | Description |
 |---|---|---|---|
-| `value` | `string` | - | Option value (unique key) |
-| `label` | `ReactNode` | - | Display label (string | ReactNode) |
-| `description` | `ReactNode` | - | Secondary text below label (ReactNode) |
-| `disabled` | `boolean` | - | Disabled option |
+| `children` | `ReactNode` | - | Right-aligned meta content (price, badge, shortcut, etc.). |
+| `className` | `string` | - | Class for the meta slot. |
 
-Searchable select with popover listbox. Supports single/multi-select and sync (auto-filter) / async (onSearch + loading) modes. **WAI-ARIA Combobox pattern** (Radix Popover under the hood — NOT Radix Select).
+Searchable select with popover listbox. **Compound API** — options are declared as <Combobox.Option> children. Supports single/multi-select and sync (auto-filter) / async (onSearch + loading) modes. **WAI-ARIA Combobox pattern** (Radix Popover under the hood — NOT Radix Select).
 
-- **Sync mode** (no `onSearch` prop): client-side filters `options` by typed query (case-insensitive label includes match by default; override via `filter`).
-- **Async mode** (provide `onSearch`): debounced (`searchDebounce`, default 250ms) callback fires for external data fetch. Set `loading` to show spinner in the input suffix.
-- **Multi-select** (`multiple`): selected values render as removable chips inside the input. Backspace on empty input removes the last chip.
+- **Subcomponents**: `Combobox.Option` (required `value`), `Combobox.OptionDescription` (secondary line), `Combobox.OptionMeta` (right-aligned slot).
+- **Duplicate `value`**: dev mode logs `console.error` and silently drops the duplicate.
+- **textValue**: derived from option children (text nodes only; OptionDescription/OptionMeta excluded). Override per-option when label is non-text.
+- **Sync mode** (no `onSearch`): client-side filters by `textValue` (case-insensitive includes; override with `filter`).
+- **Async mode** (provide `onSearch`): debounced (`searchDebounce`, default 250ms) callback fires for external data fetch. Set `loading` for spinner.
+- **Multi-select** (`multiple`): chips inside input; Backspace on empty input removes the last chip.
 - Keyboard: Arrow Up/Down, Home/End, Enter to select, Escape to close.
 
 ```tsx
-// 1) Sync — auto-filter local options
-const COUNTRIES = [
-  { value: 'kr', label: '한국' },
-  { value: 'jp', label: '일본' },
-  { value: 'us', label: '미국' },
-];
-
-<Combobox
-  options={COUNTRIES}
-  value={value}
-  onValueChange={setValue}
-  placeholder="국가 선택"
-/>
+// 1) Sync — declarative options
+<Combobox value={value} onValueChange={setValue} placeholder="국가 선택">
+  <Combobox.Option value="kr">한국</Combobox.Option>
+  <Combobox.Option value="jp">일본</Combobox.Option>
+  <Combobox.Option value="us" disabled>
+    미국
+    <Combobox.OptionDescription>일시 품절</Combobox.OptionDescription>
+  </Combobox.Option>
+</Combobox>
 
 // 2) Async — external search w/ loading spinner
-const [results, setResults] = useState<ComboboxOption[]>([]);
+const [results, setResults] = useState<{ id: string; name: string; email: string }[]>([]);
 const [loading, setLoading] = useState(false);
 
 const handleSearch = async (q: string) => {
-  if (!q) return setResults([]);
   setLoading(true);
-  const users = await fetchUsers(q);
-  setResults(users.map((u) => ({ value: u.id, label: u.name, description: u.email })));
+  setResults(await fetchUsers(q));
   setLoading(false);
 };
 
 <Combobox
-  options={results}
   loading={loading}
   onSearch={handleSearch}
   value={selectedId}
   onValueChange={setSelectedId}
   placeholder="유저 검색…"
   emptyMessage="검색 결과 없음"
-/>
+>
+  {results.map((u) => (
+    <Combobox.Option key={u.id} value={u.id}>
+      {u.name}
+      <Combobox.OptionDescription>{u.email}</Combobox.OptionDescription>
+    </Combobox.Option>
+  ))}
+</Combobox>
 
 // 3) Multi-select with chips
 <Combobox
   multiple
-  options={results}
   value={selectedIds}
   onValueChange={setSelectedIds}
   loading={loading}
   onSearch={handleSearch}
-/>
-
-// 4) With label / description / error
+>
+  {results.map((u) => (
+    <Combobox.Option key={u.id} value={u.id}>{u.name}</Combobox.Option>
+  ))}
+</Combobox>
+
+// 4) Rich option — meta slot for prices / shortcuts / badges
+<Combobox placeholder="플랜 선택">
+  <Combobox.Option value="free">
+    Free
+    <Combobox.OptionDescription>개인용</Combobox.OptionDescription>
+    <Combobox.OptionMeta>$0/mo</Combobox.OptionMeta>
+  </Combobox.Option>
+  <Combobox.Option value="pro">
+    Pro
+    <Combobox.OptionDescription>소규모 팀</Combobox.OptionDescription>
+    <Combobox.OptionMeta>$12/mo</Combobox.OptionMeta>
+  </Combobox.Option>
+</Combobox>
+
+// 5) Non-text label — explicit textValue for searching
+<Combobox.Option value="apple" textValue="apple 사과 fruit">
+  🍎 사과
+</Combobox.Option>
+
+// 6) With label / description / error
 <Combobox
   label="담당자"
   description="검색 후 선택하세요"
-  options={results}
   loading={loading}
   onSearch={handleSearch}
   value={value}
   onValueChange={setValue}
   error={!value}
   size="lg"
-/>
+>
+  {results.map((u) => (
+    <Combobox.Option key={u.id} value={u.id}>{u.name}</Combobox.Option>
+  ))}
+</Combobox>
 ```
 
 **When to use `Select` vs `Combobox`**:
@@ -368,6 +449,11 @@ const handleSearch = async (q: string) => {
 - Long list / async search / typed input → `Combobox`
 - Free-form tag input (any string) → `TagInput`
 
+**ANTI-PATTERNS**:
+- ✗ `<Combobox options={[...]}>` — legacy prop API removed; use `<Combobox.Option>` children
+- ✗ Wrapping options: `<Combobox><div><Combobox.Option/></div></Combobox>` — Option must be a direct child
+- ✗ Duplicate `value` across options — dev warning + duplicate dropped
+
 ---
 
 ## CheckBox

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

@@ -40,8 +40,12 @@ UI 작업 시 어떤 컴포넌트를 골라야 할지 결정하는 가이드. **
 // ❌ 옵션 20개에 Select
 <Select><SelectItem>...</SelectItem>...</Select>
 
-// ✅ 옵션 20개에 Combobox
-<Combobox options={options} placeholder="검색하여 선택" />
+// ✅ 옵션 20개에 Combobox (compound API)
+<Combobox placeholder="검색하여 선택">
+  {options.map((o) => (
+    <Combobox.Option key={o.value} value={o.value}>{o.label}</Combobox.Option>
+  ))}
+</Combobox>
 
 // ❌ 옵션 3개에 Select
 <Select><SelectItem>S</SelectItem><SelectItem>M</SelectItem><SelectItem>L</SelectItem></Select>