@nexus-cross/design-system 1.0.0

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

@@ -0,0 +1,292 @@
+---
+description: "NEXUS Design System 프로젝트 설정 — 이 프로젝트의 기술 스택과 필수 규칙"
+alwaysApply: true
+---
+
+# NEXUS Design System 프로젝트 설정
+
+이 프로젝트는 NEXUS Design System을 사용한다. 코드를 생성할 때 반드시 아래를 따른다.
+
+## 기술 스택
+
+- **디자인 토큰**: `@nexus-cross/tokens` (CSS 변수 기반)
+- **UI 컴포넌트**: `@nexus-cross/design-system` (React, CVA + Plain CSS)
+- **스타일링**: Tailwind CSS v4 + NEXUS 시맨틱 토큰
+
+## 디자인 시스템 CSS 설정
+
+UI 컴포넌트 스타일은 사용처 환경에 따라 두 가지 entry point 중 하나를 선택한다.
+
+| 환경 | import | 설명 |
+|---|---|---|
+| Tailwind v3 / Plain CSS / CSS Modules | `@nexus-cross/design-system/styles` | unlayered CSS |
+| Tailwind v4 | `@nexus-cross/design-system/styles/layer` | `@layer nexus`로 래핑 |
+
+```tsx
+// Tailwind v3, Plain CSS, CSS Modules
+import '@nexus-cross/design-system/styles'
+
+// Tailwind v4
+import '@nexus-cross/design-system/styles/layer'
+```
+
+Tailwind v4 프로젝트는 `globals.css`에 layer 순서도 선언한다:
+```css
+@layer base, nexus, components, utilities;
+```
+
+## 절대 규칙
+
+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 → NEXUS 변환 워크플로우
+
+**Figma MCP 도구(get_design_context, get_code 등)의 출력을 절대 그대로 사용하지 않는다.**
+Figma MCP는 바닐라 HTML + Tailwind를 출력하지만, 이 프로젝트는 `@nexus-cross/design-system`을 사용한다.
+**MCP 출력은 "디자인 의도를 파악하는 참고 자료"일 뿐, 최종 코드가 아니다.**
+
+### 필수 3단계 워크플로우
+
+**1단계: 디자인 분석 (MCP 호출)**
+- `get_design_context`로 구조와 레이아웃 파악
+- `get_screenshot`으로 시각적 참조 확인
+- 이 단계에서 MCP가 출력하는 코드는 **읽기만 하고 사용하지 않는다**
+
+**2단계: 컴포넌트 매핑 (코드 작성 전에 반드시 수행)**
+MCP 출력의 각 요소를 NEXUS 컴포넌트로 매핑한다. **코드를 한 줄이라도 쓰기 전에** 이 매핑을 먼저 완료한다.
+
+```
+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)
+```
+
+**3단계: NEXUS 코드 생성**
+매핑을 기반으로 코드를 작성한다. 이 단계에서는 MCP 출력 코드를 참조하지 않는다.
+
+### 컴포넌트 변환 테이블
+
+| MCP 출력 (네이티브 HTML) | → NEXUS 컴포넌트 |
+|---|---|
+| `<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>` |
+| 스켈레톤 로딩 | `<Skeleton>` |
+| 데이터 리스트 | `<DataList>` |
+| 테이블 | `<Table>` + `<TableRow>` + `<TdColumn>` |
+| 숫자 카운트 애니메이션 | `<Counter>` |
+| 카운트다운 타이머 | `<Countdown>` |
+| 텍스트 말줄임 | `<Ellipsis>` |
+| 흐르는 텍스트 | `<Marquee>` |
+| 무한 스크롤 리스트 | `<InfiniteScroll>` |
+| 대량 리스트 (가상 스크롤) | `<VirtualList>` / `<VirtualGrid>` |
+
+**위 교체를 하지 않고 네이티브 HTML을 사용하면 규칙 위반이다.**
+
+### 색상 변환 테이블
+
+MCP가 출력하는 색상값을 NEXUS 토큰으로 변환한다:
+
+| MCP 출력 색상 | → NEXUS 토큰 |
+|---|---|
+| `#FFFFFF`, `bg-white` | `bg-bg-default` |
+| `#F3F6F8`, `bg-gray-50` | `bg-bg-subtle` |
+| `#1E232E`, `text-gray-900` | `text-text-primary` |
+| `#7E8597`, `text-gray-500` | `text-text-secondary` |
+| `#A2AABA`, `text-gray-400` | `text-text-muted` |
+| `#ECF0F2`, `border-gray-200` | `border-border-default` |
+| `#09B498`, `bg-green-*`, `bg-teal-*` | `bg-accent-primary` |
+| `#7346F3`, `bg-purple-*`, `bg-violet-*` | `bg-accent-secondary` |
+| `#DB0A2D`, `bg-red-*` | `bg-status-danger` |
+| `#00B784` | `bg-status-success` |
+| `#FF9D00`, `bg-amber-*` | `bg-status-warning` |
+| `#0095FF`, `bg-blue-*` | `bg-status-info` |
+
+위에 정확히 매칭되지 않는 색상은 가장 가까운 NEXUS 토큰을 선택한다.
+**어떤 경우에도 hex 값이나 Tailwind 기본 색상(bg-blue-500 등)을 사용하지 않는다.**
+
+### Button variant 판단 기준
+
+Figma에서 버튼의 시각적 스타일을 보고 variant를 결정한다:
+
+| Figma 시각적 특징 | → variant |
+|---|---|
+| 채워진 accent 색상 배경 (초록/틸) | `variant="primary"` |
+| 채워진 회색/중립 배경 | `variant="secondary"` |
+| 테두리만 있고 배경 투명 | `variant="outline"` |
+| 배경/테두리 없이 텍스트만 | `variant="ghost"` |
+| 빨간색/위험 표시 | `variant="danger"` |
+
+### 자기 검증 체크리스트
+
+코드를 출력하기 전에 아래를 확인한다:
+
+- [ ] `<button>`, `<input>`, `<select>`, `<textarea>` 등 네이티브 HTML 폼 요소가 없는가?
+- [ ] hex 색상값(`#...`)이 없는가?
+- [ ] Tailwind 기본 색상(`bg-blue-500`, `text-gray-900` 등)이 없는가?
+- [ ] 모든 import가 `@nexus-cross/design-system`에서 오는가?
+- [ ] 모달은 `ModalTemplate`으로 감쌌는가?
+- [ ] 간격/크기에 하드코딩 px이 없는가?
+
+**하나라도 실패하면 코드를 수정한 후 출력한다.**
+
+```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>
+```