@nexus-cross/design-system 1.0.3-beta.1

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

@@ -0,0 +1,188 @@
+---
+description: "NEXUS Design System 프로젝트 설정 — 이 프로젝트의 기술 스택과 필수 규칙"
+alwaysApply: true
+---
+
+# NEXUS Design System 프로젝트 설정
+
+이 프로젝트는 NEXUS Design System을 사용한다. 코드를 생성할 때 반드시 아래를 따른다.
+
+## 기술 스택
+
+- **디자인 토큰**: `@nexus-cross/tokens` (CSS 변수 기반)
+- **UI 컴포넌트**: `@nexus-cross/design-system` (React, CVA + Tailwind)
+- **스타일링**: Tailwind CSS v4 + NEXUS 시맨틱 토큰
+
+## 절대 규칙
+
+1. **색상은 반드시 NEXUS 토큰을 사용한다.** 하드코딩 금지.
+   - `bg-bg-default`, `text-text-primary`, `border-border-default` 등
+   - `#ffffff`, `#000000`, `rgb()` 등 직접 색상값 사용 금지
+   - 참고: `.cursor/rules/nexus-tokens.mdc`
+
+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`
+
+3. **Figma 디자인 구현 시:**
+   - NEXUS 토큰과 공용 UI를 적극 활용하되, **Figma 디자인에 충실하게** 구현한다
+   - Figma의 색상값을 보고 가장 가까운 NEXUS 토큰으로 매핑한다
+   - Figma의 UI 요소(버튼, 입력필드 등)는 `@nexus-cross/design-system` 컴포넌트로 구현한다
+   - Figma 디자인과 공용 UI의 스타일이 다를 경우, `className`으로 Figma에 맞게 오버라이드한다
+   - Figma에 없는 커스텀 스타일만 Tailwind 유틸리티로 작성한다
+
+## Figma MCP 코드 변환 체크리스트
+
+**Figma MCP에서 받은 코드를 그대로 사용하지 않는다.** 반드시 아래 교체를 수행한다:
+
+| Figma MCP 결과 (네이티브 HTML) | 교체 대상 (`@nexus-cross/design-system`) |
+|-------------------------------|------------------------------|
+| `<button>`, `<a>` 버튼 스타일 | `<Button>` (variant, size 지정) |
+| `<input type="text">` | `<TextInput>` (prefixIcon, suffixIcon 지원) |
+| `<textarea>` | `<TextArea>` (showCount, maxLength 지원) |
+| `<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>` |
+| 흐르는 텍스트 | `<Marquee>` |
+
+**위 교체를 하지 않고 네이티브 HTML을 사용하면 규칙 위반이다.**
+
+```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 />} />
+<Avatar fallback="JD" size="sm" />
+<Divider />
+```
+
+## 전역 설정 (앱 루트에 필수)
+
+아래 컴포넌트를 앱 루트(layout.tsx 또는 App.tsx)에 **반드시** 배치한다.
+
+| 컴포넌트 | import | 필수 조건 | 설명 |
+|----------|--------|----------|------|
+| `<ModalContainer />` | `@nexus-cross/design-system/modal` | `modal()` 또는 `useModal()` 사용 시 | 모달 렌더링 컨테이너 |
+| `<Toaster />` | `@nexus-cross/design-system` | `toast()` 사용 시 | 토스트 알림 렌더링 |
+
+```tsx
+// layout.tsx 또는 App.tsx
+import { ModalContainer } from '@nexus-cross/design-system/modal';
+import { Toaster } from '@nexus-cross/design-system';
+
+export default function RootLayout({ children }) {
+  return (
+    <>
+      {children}
+      <ModalContainer />
+      <Toaster position="top-right" />
+    </>
+  );
+}
+```
+
+**전역 설정이 필요 없는 컴포넌트** (별도 Provider 없이 바로 사용 가능):
+- Tooltip (내부에 Provider 내장)
+- Popover, Drawer, Select, Accordion 등 모든 나머지 컴포넌트
+
+## Import 패턴
+
+```tsx
+// 일반 컴포넌트
+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';
+
+// 토큰 (JS API가 필요한 경우만)
+import { getTheme } from '@nexus-cross/tokens';
+```
+
+## 모달 작성 규칙
+
+모달 컴포넌트는 **반드시 `ModalTemplate`으로 감싸야 한다.** `<div>`만으로 모달을 만들지 않는다.
+
+```tsx
+// ✅ 올바른 모달
+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>
+  );
+}
+
+// 호출
+const result = await modal({ component: MyModal });
+```
+
+```tsx
+// ❌ 잘못된 모달 — ModalTemplate 없이 div만 사용
+function MyModal({ close }: { close: () => void }) {
+  return (
+    <div className="p-6 bg-white rounded-lg">
+      <h2>제목</h2>
+      <p>내용</p>
+    </div>
+  );
+}
+```
+
+## 토스트 사용 규칙
+
+```tsx
+import { toast } from '@nexus-cross/design-system';
+
+toast('기본 메시지');
+toast.success('성공!');
+toast.error('오류가 발생했습니다');
+toast.loading('처리 중...');
+```
+
+루트에 `<Toaster />` 없이 `toast()`를 호출하면 아무것도 표시되지 않는다.
+
+## 토큰 사용 예시
+
+```tsx
+// ✅ 올바른 사용
+<div className="bg-bg-default text-text-primary border border-border-default">
+  <Button variant="primary">확인</Button>
+  <TextInput placeholder="검색..." />
+</div>
+
+// ❌ 잘못된 사용
+<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="검색..." />
+</div>
+```