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

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

@@ -1,108 +1,130 @@
 ---
-description: "NEXUS Design System 프로젝트 설정 — 이 프로젝트의 기술 스택과 필수 규칙"
+description: "NEXUS Design System project setup — tech stack and mandatory rules for this project"
 alwaysApply: true
 ---
 
-# NEXUS Design System 프로젝트 설정
+# NEXUS Design System Project Setup
 
-이 프로젝트는 NEXUS Design System을 사용한다. 코드를 생성할 때 반드시 아래를 따른다.
+This project uses NEXUS Design System. All generated code MUST follow the rules below.
 
-## 기술 스택
+## Tech Stack
 
-- **디자인 토큰**: `@nexus-cross/tokens` (CSS 변수 기반)
-- **UI 컴포넌트**: `@nexus-cross/design-system` (React, CVA + Tailwind)
-- **스타일링**: Tailwind CSS v4 + NEXUS 시맨틱 토큰
+- **Design Tokens**: `@nexus-cross/tokens` (CSS variable based)
+- **UI Components**: `@nexus-cross/design-system` (React, CVA + Plain CSS)
+- **Styling**: Tailwind CSS v4 + NEXUS semantic tokens
 
-## 절대 규칙
+## Design System CSS Setup
 
-1. **색상은 반드시 NEXUS 토큰을 사용한다.** 하드코딩 금지.
-   - `bg-bg-default`, `text-text-primary`, `border-border-default` 등
-   - `#ffffff`, `#000000`, `rgb()` 등 직접 색상값 사용 금지
-   - 참고: `.cursor/rules/nexus-tokens.mdc`
+Choose one of two CSS entry points depending on the project environment:
 
-2. **UI 컴포넌트는 반드시 `@nexus-cross/design-system`에서 import한다.** 직접 구현 금지.
-   - `<Button>`, `<TextInput>`, `<Modal>`, `<Toast>` 등
-   - Radix UI, Headless UI 등을 직접 import하여 동일 기능 컴포넌트를 만들지 않는다
-   - 참고: `.cursor/rules/nexus-ui-components.mdc`, `.cursor/rules/nexus-ui-api.mdc`
+| 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` |
 
-3. **Figma 디자인 구현 시:**
-   - NEXUS 토큰과 공용 UI를 적극 활용하되, **Figma 디자인에 충실하게** 구현한다
-   - Figma의 색상값을 보고 가장 가까운 NEXUS 토큰으로 매핑한다
-   - Figma의 UI 요소(버튼, 입력필드 등)는 `@nexus-cross/design-system` 컴포넌트로 구현한다
-   - Figma 디자인과 공용 UI의 스타일이 다를 경우, `className`으로 Figma에 맞게 오버라이드한다
-   - Figma에 없는 커스텀 스타일만 Tailwind 유틸리티로 작성한다
+```tsx
+// Tailwind v3, Plain CSS, CSS Modules
+import '@nexus-cross/design-system/styles'
+
+// Tailwind v4
+import '@nexus-cross/design-system/styles/layer'
+```
+
+For Tailwind v4 projects, also declare layer order in `globals.css`:
+```css
+@layer base, nexus, components, utilities;
+```
+
+## Absolute Rules
+
+1. **Always use NEXUS tokens for colors.** Hardcoding is prohibited.
+   - `bg-bg-default`, `text-text-primary`, `border-border-default`, etc.
+   - Direct color values like `#ffffff`, `#000000`, `rgb()` are prohibited
+   - Reference: `.cursor/rules/nexus-tokens.mdc`
+
+2. **Always import UI components from `@nexus-cross/design-system`.** Direct implementation is prohibited.
+   - `<Button>`, `<TextInput>`, `<Modal>`, `<Toast>`, etc.
+   - Do NOT import Radix UI, Headless UI, etc. to build equivalent components
+   - Reference: `.cursor/rules/nexus-ui-components.mdc`, `.cursor/rules/nexus-ui-api.mdc`
+
+3. **When implementing Figma designs:**
+   - Actively use NEXUS tokens and shared UI, while **faithfully** implementing the Figma design
+   - Map Figma color values to the closest NEXUS token
+   - Implement Figma UI elements (buttons, inputs, etc.) using `@nexus-cross/design-system` components
+   - If shared UI style differs from Figma, override with `className` to match Figma
+   - Only use Tailwind utilities for custom styles not present in Figma
 
-## Figma MCP → NEXUS 변환 워크플로우
+## Figma MCP → NEXUS Conversion Workflow
 
-**Figma MCP 도구(get_design_context, get_code 등)의 출력을 절대 그대로 사용하지 않는다.**
-Figma MCP는 바닐라 HTML + Tailwind를 출력하지만, 이 프로젝트는 `@nexus-cross/design-system`을 사용한다.
-**MCP 출력은 "디자인 의도를 파악하는 참고 자료"일 뿐, 최종 코드가 아니다.**
+**NEVER use Figma MCP tool output (get_design_context, get_code, etc.) as-is.**
+Figma MCP outputs vanilla HTML + Tailwind, but this project uses `@nexus-cross/design-system`.
+**MCP output is only a "reference for understanding design intent", not final code.**
 
-### 필수 3단계 워크플로우
+### Mandatory 3-Step Workflow
 
-**1단계: 디자인 분석 (MCP 호출)**
-- `get_design_context`로 구조와 레이아웃 파악
-- `get_screenshot`으로 시각적 참조 확인
-- 이 단계에서 MCP가 출력하는 코드는 **읽기만 하고 사용하지 않는다**
+**Step 1: Design Analysis (MCP call)**
+- Use `get_design_context` to understand structure and layout
+- Use `get_screenshot` for visual reference
+- Code output from MCP at this stage is **read-only — do not use it**
 
-**2단계: 컴포넌트 매핑 (코드 작성 전에 반드시 수행)**
-MCP 출력의 각 요소를 NEXUS 컴포넌트로 매핑한다. **코드를 한 줄이라도 쓰기 전에** 이 매핑을 먼저 완료한다.
+**Step 2: Component Mapping (MUST be done before writing code)**
+Map each element from MCP output to a NEXUS component. **Complete this mapping before writing a single line of code.**
 
 ```
-MCP 출력 분석:
-- <button> 2개 발견 → Button (primary, ghost)
-- <input type="text"> 1개 → TextInput
-- <select> 1개 → Select + SelectItem
-- 색상 #09B498 → bg-accent-primary (NEXUS 토큰)
-- 색상 #1E232E → text-text-primary (NEXUS 토큰)
-- 간격 16px → var(--spacing-padding-md)
+MCP Output Analysis:
+- 2 <button> found → Button (primary, ghost)
+- 1 <input type="text"> → TextInput
+- 1 <select> → Select + SelectItem
+- Color #09B498 → bg-accent-primary (NEXUS token)
+- Color #1E232E → text-text-primary (NEXUS token)
+- Spacing 16px → var(--spacing-padding-md)
 ```
 
-**3단계: NEXUS 코드 생성**
-매핑을 기반으로 코드를 작성한다. 이 단계에서는 MCP 출력 코드를 참조하지 않는다.
+**Step 3: NEXUS Code Generation**
+Write code based on the mapping. Do NOT reference MCP output code at this stage.
 
-### 컴포넌트 변환 테이블
+### Component Conversion Table
 
-| MCP 출력 (네이티브 HTML) | → NEXUS 컴포넌트 |
+| MCP Output (Native HTML) | → NEXUS Component |
 |---|---|
-| `<button>`, `<a>` 버튼 스타일 | `<Button>` (variant, size 지정) |
-| `<input type="text">` | `<TextInput>` (prefixIcon, suffixIcon 지원) |
-| `<textarea>` | `<TextArea>` (showCount, maxLength 지원) |
+| `<button>`, `<a>` button style | `<Button>` (specify variant, size) |
+| `<input type="text">` | `<TextInput>` (prefixIcon, suffixIcon supported) |
+| `<textarea>` | `<TextArea>` (showCount, maxLength supported) |
 | `<input type="number">` | `<NumberInput>` |
 | `<select>` | `<Select>` + `<SelectItem>` |
 | `<input type="checkbox">` | `<CheckBox>` |
 | `<input type="radio">` | `<RadioGroup>` + `<RadioItem>` |
-| 토글/스위치 UI | `<Switch>` |
-| 탭 UI | `<Tab>` (items 배열로 구성) |
-| 칩/태그/필터/뱃지 | `<Chip>` (variant, onClose 지원) |
-| 아바타/프로필 이미지 | `<Avatar>` (fallback, shape 지원) |
-| 구분선/`<hr>` | `<Divider>` (orientation, variant 지정) |
-| 드롭다운 메뉴 | `<Select>` 또는 `<Popover>` |
-| 툴팁 | `<Tooltip>` |
-| 아코디언/접기 | `<Accordion>` |
-| 캐러셀/슬라이더 | `<Carousel>` + `<CarouselSlide>` |
-| 페이지네이션 | `<Pagination>` |
-| 모달/다이얼로그 | `modal()` + `<ModalTemplate>` |
-| 토스트/알림 | `toast()` |
-| 드로어/바텀시트 | `<Drawer>` |
-| 로딩 스피너 | `<Spinner>` |
-| 스켈레톤 로딩 | `<Skeleton>` |
-| 데이터 리스트 | `<DataList>` |
-| 테이블 | `<Table>` + `<TableRow>` + `<TdColumn>` |
-| 숫자 카운트 애니메이션 | `<Counter>` |
-| 카운트다운 타이머 | `<Countdown>` |
-| 텍스트 말줄임 | `<Ellipsis>` |
-| 흐르는 텍스트 | `<Marquee>` |
-| 무한 스크롤 리스트 | `<InfiniteScroll>` |
-| 대량 리스트 (가상 스크롤) | `<VirtualList>` / `<VirtualGrid>` |
-
-**위 교체를 하지 않고 네이티브 HTML을 사용하면 규칙 위반이다.**
-
-### 색상 변환 테이블
-
-MCP가 출력하는 색상값을 NEXUS 토큰으로 변환한다:
-
-| MCP 출력 색상 | → NEXUS 토큰 |
+| Toggle/Switch UI | `<Switch>` |
+| Tab UI | `<Tab>` (configured via items array) |
+| Chip/Tag/Filter/Badge | `<Chip>` (variant, onClose supported) |
+| Avatar/Profile image | `<Avatar>` (fallback, shape supported) |
+| Divider/`<hr>` | `<Divider>` (specify orientation, variant) |
+| Dropdown menu | `<Select>` or `<Popover>` |
+| Tooltip | `<Tooltip>` |
+| Accordion/Collapsible | `<Accordion>` |
+| Carousel/Slider | `<Carousel>` + `<CarouselSlide>` |
+| Pagination | `<Pagination>` |
+| Modal/Dialog | `modal()` + `<ModalTemplate>` |
+| Toast/Notification | `toast()` |
+| Drawer/Bottom sheet | `<Drawer>` |
+| Loading spinner | `<Spinner>` |
+| Skeleton loader | `<Skeleton>` |
+| Data list | `<DataList>` |
+| Table | `<Table>` + `<TableRow>` + `<TdColumn>` |
+| Number count animation | `<Counter>` |
+| Countdown timer | `<Countdown>` |
+| Text ellipsis | `<Ellipsis>` |
+| Scrolling text | `<Marquee>` |
+| Infinite scroll list | `<InfiniteScroll>` |
+| Large list (virtual scroll) | `<VirtualList>` / `<VirtualGrid>` |
+
+**Using native HTML instead of the replacements above is a rule violation.**
+
+### Color Conversion Table
+
+Convert MCP output colors to NEXUS tokens:
+
+| MCP Output Color | → NEXUS Token |
 |---|---|
 | `#FFFFFF`, `bg-white` | `bg-bg-default` |
 | `#F3F6F8`, `bg-gray-50` | `bg-bg-subtle` |
@@ -117,59 +139,59 @@ MCP가 출력하는 색상값을 NEXUS 토큰으로 변환한다:
 | `#FF9D00`, `bg-amber-*` | `bg-status-warning` |
 | `#0095FF`, `bg-blue-*` | `bg-status-info` |
 
-위에 정확히 매칭되지 않는 색상은 가장 가까운 NEXUS 토큰을 선택한다.
-**어떤 경우에도 hex 값이나 Tailwind 기본 색상(bg-blue-500 등)을 사용하지 않는다.**
+For colors not exactly matching above, choose the closest NEXUS token.
+**Under no circumstances use hex values or default Tailwind colors (bg-blue-500, etc.).**
 
-### Button variant 판단 기준
+### Button Variant Decision Criteria
 
-Figma에서 버튼의 시각적 스타일을 보고 variant를 결정한다:
+Determine the variant based on visual style in Figma:
 
-| Figma 시각적 특징 | → variant |
+| Figma Visual Characteristic | → variant |
 |---|---|
-| 채워진 accent 색상 배경 (초록/틸) | `variant="primary"` |
-| 채워진 회색/중립 배경 | `variant="secondary"` |
-| 테두리만 있고 배경 투명 | `variant="outline"` |
-| 배경/테두리 없이 텍스트만 | `variant="ghost"` |
-| 빨간색/위험 표시 | `variant="danger"` |
+| Filled accent color background (green/teal) | `variant="primary"` |
+| Filled gray/neutral background | `variant="secondary"` |
+| Border only, transparent background | `variant="outline"` |
+| No background/border, text only | `variant="ghost"` |
+| Red/danger indicator | `variant="danger"` |
 
-### 자기 검증 체크리스트
+### Self-Verification Checklist
 
-코드를 출력하기 전에 아래를 확인한다:
+Verify the following before outputting code:
 
-- [ ] `<button>`, `<input>`, `<select>`, `<textarea>` 등 네이티브 HTML 폼 요소가 없는가?
-- [ ] hex 색상값(`#...`)이 없는가?
-- [ ] Tailwind 기본 색상(`bg-blue-500`, `text-gray-900` 등)이 없는가?
-- [ ] 모든 import가 `@nexus-cross/design-system`에서 오는가?
-- [ ] 모달은 `ModalTemplate`으로 감쌌는가?
-- [ ] 간격/크기에 하드코딩 px이 없는가?
+- [ ] No native HTML form elements (`<button>`, `<input>`, `<select>`, `<textarea>`, etc.)?
+- [ ] No hex color values (`#...`)?
+- [ ] No default Tailwind colors (`bg-blue-500`, `text-gray-900`, etc.)?
+- [ ] All imports from `@nexus-cross/design-system`?
+- [ ] Modals wrapped with `ModalTemplate`?
+- [ ] No hardcoded px values for spacing/sizing?
 
-**하나라도 실패하면 코드를 수정한 후 출력한다.**
+**If any check fails, fix the code before outputting.**
 
 ```tsx
-// ❌ Figma MCP 코드 그대로 사용 (금지)
-<button className="bg-[#09B498] text-white px-4 py-2 rounded-lg">확인</button>
-<input className="border border-[#C6D0DA] px-3 py-2 rounded" placeholder="검색" />
-<div className="w-8 h-8 rounded-full bg-gray-200" /> {/* 아바타 */}
-<hr className="border-[#ECF0F2]" /> {/* 구분선 */}
-
-// ✅ NEXUS 컴포넌트로 교체 (필수)
-<Button variant="primary">확인</Button>
-<TextInput placeholder="검색" prefixIcon={<SearchIcon />} />
+// WRONG — Using Figma MCP code as-is (prohibited)
+<button className="bg-[#09B498] text-white px-4 py-2 rounded-lg">Confirm</button>
+<input className="border border-[#C6D0DA] px-3 py-2 rounded" placeholder="Search" />
+<div className="w-8 h-8 rounded-full bg-gray-200" /> {/* avatar */}
+<hr className="border-[#ECF0F2]" /> {/* divider */}
+
+// CORRECT — Replace with NEXUS components (required)
+<Button variant="primary">Confirm</Button>
+<TextInput placeholder="Search" prefixIcon={<SearchIcon />} />
 <Avatar fallback="JD" size="sm" />
 <Divider />
 ```
 
-## 전역 설정 (앱 루트에 필수)
+## Global Setup (Required at App Root)
 
-아래 컴포넌트를 앱 루트(layout.tsx 또는 App.tsx)에 **반드시** 배치한다.
+The following components MUST be placed at the app root (layout.tsx or App.tsx).
 
-| 컴포넌트 | import | 필수 조건 | 설명 |
-|----------|--------|----------|------|
-| `<ModalContainer />` | `@nexus-cross/design-system/modal` | `modal()` 또는 `useModal()` 사용 시 | 모달 렌더링 컨테이너 |
-| `<Toaster />` | `@nexus-cross/design-system` | `toast()` 사용 시 | 토스트 알림 렌더링 |
+| Component | import | Required When | Description |
+|---|---|---|---|
+| `<ModalContainer />` | `@nexus-cross/design-system/modal` | Using `modal()` or `useModal()` | Modal rendering container |
+| `<Toaster />` | `@nexus-cross/design-system` | Using `toast()` | Toast notification renderer |
 
 ```tsx
-// layout.tsx 또는 App.tsx
+// layout.tsx or App.tsx
 import { ModalContainer } from '@nexus-cross/design-system/modal';
 import { Toaster } from '@nexus-cross/design-system';
 
@@ -184,87 +206,87 @@ export default function RootLayout({ children }) {
 }
 ```
 
-**전역 설정이 필요 없는 컴포넌트** (별도 Provider 없이 바로 사용 가능):
-- Tooltip (내부에 Provider 내장)
-- Popover, Drawer, Select, Accordion 등 모든 나머지 컴포넌트
+**Components that do NOT need global setup** (usable directly without Provider):
+- Tooltip (Provider built-in)
+- Popover, Drawer, Select, Accordion, and all other components
 
-## Import 패턴
+## Import Patterns
 
 ```tsx
-// 일반 컴포넌트
+// General components
 import { Button, TextInput, TextArea, Select, Switch, Chip, Spinner, Divider } from '@nexus-cross/design-system';
 
-// 오버레이 컴포넌트
+// Overlay components
 import { Tooltip, Popover, Drawer, Accordion } from '@nexus-cross/design-system';
 
-// 토스트
+// Toast
 import { toast, Toaster } from '@nexus-cross/design-system';
 
-// 모달 시스템 (별도 서브패스)
+// Modal system (separate subpath)
 import { modal, useModal, ModalTemplate, ModalContainer } from '@nexus-cross/design-system/modal';
 
-// 토큰 (JS API가 필요한 경우만)
+// Tokens (only when JS API is needed)
 import { getTheme } from '@nexus-cross/tokens';
 ```
 
-## 모달 작성 규칙
+## Modal Writing Rules
 
-모달 컴포넌트는 **반드시 `ModalTemplate`으로 감싸야 한다.** `<div>`만으로 모달을 만들지 않는다.
+Modal components **MUST be wrapped with `ModalTemplate`.** Do NOT create modals with plain `<div>`.
 
 ```tsx
-// ✅ 올바른 모달
+// CORRECT modal
 import { ModalTemplate } from '@nexus-cross/design-system/modal';
 
 function MyModal({ close, resolve }: { close: () => void; resolve: (value: any) => void }) {
   return (
-    <ModalTemplate title="제목" close={close}>
-      <p className="text-text-secondary">내용</p>
-      <Button onClick={() => resolve({ confirmed: true })}>확인</Button>
+    <ModalTemplate title="Title" close={close}>
+      <p className="text-text-secondary">Content</p>
+      <Button onClick={() => resolve({ confirmed: true })}>Confirm</Button>
     </ModalTemplate>
   );
 }
 
-// 호출
+// Call
 const result = await modal({ component: MyModal });
 ```
 
 ```tsx
-// ❌ 잘못된 모달 — ModalTemplate 없이 div만 사용
+// WRONG modal — using div without ModalTemplate
 function MyModal({ close }: { close: () => void }) {
   return (
     <div className="p-6 bg-white rounded-lg">
-      <h2>제목</h2>
-      <p>내용</p>
+      <h2>Title</h2>
+      <p>Content</p>
     </div>
   );
 }
 ```
 
-## 토스트 사용 규칙
+## Toast Usage Rules
 
 ```tsx
 import { toast } from '@nexus-cross/design-system';
 
-toast('기본 메시지');
-toast.success('성공!');
-toast.error('오류가 발생했습니다');
-toast.loading('처리 중...');
+toast('Default message');
+toast.success('Success!');
+toast.error('An error occurred');
+toast.loading('Processing...');
 ```
 
-루트에 `<Toaster />` 없이 `toast()`를 호출하면 아무것도 표시되지 않는다.
+Calling `toast()` without `<Toaster />` at the root will display nothing.
 
-## 토큰 사용 예시
+## Token Usage Examples
 
 ```tsx
-// ✅ 올바른 사용
+// CORRECT usage
 <div className="bg-bg-default text-text-primary border border-border-default">
-  <Button variant="primary">확인</Button>
-  <TextInput placeholder="검색..." />
+  <Button variant="primary">Confirm</Button>
+  <TextInput placeholder="Search..." />
 </div>
 
-// ❌ 잘못된 사용
+// WRONG usage
 <div className="bg-white text-gray-900 border border-gray-200">
-  <button className="bg-green-500 text-white px-4 py-2 rounded">확인</button>
-  <input className="border border-gray-300 px-3 py-2" placeholder="검색..." />
+  <button className="bg-green-500 text-white px-4 py-2 rounded">Confirm</button>
+  <input className="border border-gray-300 px-3 py-2" placeholder="Search..." />
 </div>
 ```