@nexus-cross/design-system 1.0.14 → 1.1.1

package/claude-rules/nexus/CLAUDE.md

@@ -0,0 +1,85 @@
+# NEXUS Design System — AI Agent Rules
+
+> 이 파일은 `@nexus-cross/design-system` 패키지가 자동 관리합니다.
+> 사용자 커스텀 규칙은 프로젝트 루트의 `CLAUDE.md`에 직접 작성하세요.
+
+@./ui-components.md
+@./ui-decisions.md
+@./ui-api.md
+@./tokens.md
+@./domains.md
+
+---
+
+## Absolute Rules (최우선)
+
+1. **색상은 반드시 NEXUS 토큰 사용.** hex, rgb, 기본 Tailwind 색상 (`bg-blue-500` 등) 금지.
+   - 배경: `bg-bg-*`, `bg-surface-*`
+   - 텍스트: `text-text-*`
+   - 아이콘: `text-icon-*`
+   - 테두리: `border-border-*`
+   - 액센트: `bg-accent-*`
+   - 상태: `bg-status-*`
+
+2. **UI 컴포넌트는 `@nexus-cross/design-system`에서 import.** 직접 구현 금지.
+   - `<button>` → `<Button>`, `<input>` → `<TextInput>`, `<select>` → `<Select>` 등
+   - Radix UI, Headless UI 등 직접 import 금지 (design-system이 내부적으로 사용)
+
+3. **Figma MCP 코드 그대로 사용 금지.** MCP 출력은 "디자인 의도 파악용"으로만 참고.
+   - Step 1: MCP로 구조 파악 → Step 2: NEXUS 컴포넌트 매핑 → Step 3: NEXUS 코드 작성
+
+4. **`className` 오버라이드 시 `!important` 금지.** `cn()` 유틸이 프리픽스 충돌 자동 해소.
+
+5. **새 UI 작업 전, 항상 컴포넌트 매핑부터.** native HTML이나 Tailwind 프리미티브로 구현하기 전, `ui-components.md`에 동일 기능이 있는지 먼저 확인.
+
+---
+
+## Quick Component Import
+
+```tsx
+import {
+  Button, TextInput, TextArea, Select, Combobox,
+  Switch, CheckBox, RadioGroup, Chip, Spinner,
+  Divider, Tooltip, Popover, Drawer, Accordion,
+  toast, Toaster,
+  NumberInput, PriceInput, Avatar, Tab, ToggleGroup,
+  cn,
+} from '@nexus-cross/design-system';
+
+import { modal, useModal, ModalTemplate, ModalContainer } from '@nexus-cross/design-system/modal';
+```
+
+---
+
+## CSS Setup (한 번만)
+
+### Tailwind v4
+```css
+@import 'tailwindcss';
+@import '@nexus-cross/tokens/company.css';
+/* Next.js Turbopack only: */
+@import '@nexus-cross/design-system/styles.css';
+```
+
+### Next.js Turbopack
+```js
+// next.config.mjs
+const nextConfig = {
+  transpilePackages: ['@nexus-cross/design-system', '@nexus-cross/tokens'],
+}
+```
+
+---
+
+## Token Path Convention
+
+모든 디자인 토큰은 5-segment 형식: `color.semantic.{namespace}.{slot}.{state}`
+
+```
+# CORRECT
+color.semantic.domain-market.bullish.base
+color.semantic.domain-market.bullish-bg.hover
+
+# WRONG (6+ segments)
+color.semantic.domain-market.trend.bullish.base
+```

package/claude-rules/nexus/commands/nexus-audit.md

@@ -0,0 +1,79 @@
+---
+description: NEXUS Design System 컴플라이언스 감사. 코드베이스에서 NEXUS 룰 위반을 검출하고 수정안을 제시합니다.
+---
+
+# /nexus-audit
+
+이 프로젝트의 NEXUS Design System 컴플라이언스를 감사합니다.
+
+## 검사 항목
+
+다음 위반 사항을 검출하고 각각 수정안을 제시하세요.
+
+### 1. Raw HTML 사용 (NEXUS 컴포넌트로 교체 필요)
+
+`src/`, `app/`, `pages/`, `components/` 하위에서 다음 패턴 검색:
+
+- `<button` (단, `<Button` 제외) → `<Button>` 권고
+- `<input` (단, `type="hidden"` 제외) → `<TextInput>` / `<NumberInput>` / `<CheckBox>` / `<RadioGroup>` 등
+- `<textarea` → `<TextArea>`
+- `<select` → `<Select>` 또는 `<Combobox>`
+- 직접 만든 dropdown div (`onClick + isOpen state`) → `<DropdownMenu>` / `<Popover>`
+- 직접 만든 modal (`fixed inset-0` 등) → `<Modal>` / `modal()` API
+
+### 2. 토큰 위반 (NEXUS 토큰으로 교체 필요)
+
+- hex/rgb/hsl 직접 사용: `#[0-9a-fA-F]{3,8}`, `rgb\(`, `hsl\(`
+- 기본 Tailwind 색상: `bg-(red|blue|green|yellow|gray|slate|zinc|neutral|stone)-\d+` 등
+- 인라인 style 색상: `style={{ color: ..., background: ..., border: ... }}`
+
+수정안: NEXUS 토큰 매핑 (`@.claude/nexus/tokens.md` 참조).
+
+### 3. `!important` 사용
+
+`className`에서 `!`로 시작하는 Tailwind 유틸 (예: `!bg-red-500`, `!text-white`)
+- semantic prop으로 해결 가능한지 확인 (`semantic="danger"` 등)
+- 정말 필요하면 `cn()` 우선순위로 해결
+
+### 4. 직접 import 위반
+
+- `from '@radix-ui/...'` 직접 import (NEXUS가 wrap하고 있음)
+- `from '@headlessui/...'` 직접 import
+- `import { Button } from 'somewhere-else'` (다른 디자인 시스템)
+
+### 5. 자주 발견되는 anti-pattern
+
+- `TextInput type="number"` → `<NumberInput>`
+- `<Tooltip>` 안에 클릭 가능한 콘텐츠 → `<Popover>` 또는 `<DropdownMenu>`
+- 옵션 7개 이상의 `<Select>` → `<Combobox>` 권고
+- 즉시 적용되는 binary 설정에 `<CheckBox>` → `<Switch>` 권고
+- form field 안에 비슷한 모양 컴포넌트 혼용 (RadioGroup + ToggleGroup 등)
+
+## 출력 형식
+
+```md
+## NEXUS Audit Report
+
+### 🔴 Critical (즉시 수정)
+- src/pages/Login.tsx:23 — `<button className="bg-blue-500">` → `<Button semantic="primary">`
+  - Reason: raw HTML + 임의 색상
+
+### 🟡 Warning (검토 후 수정)
+- src/components/Settings.tsx:47 — Select with 12 options → Combobox 권고
+
+### 🟢 Info (개선 제안)
+- src/styles/theme.css:8 — `--my-blue: #0066ff` → `--color-accent-primary` 활용
+
+### Summary
+- Critical: 3
+- Warning: 5
+- Info: 2
+```
+
+## 작업 흐름
+
+1. Glob/Grep으로 위 패턴 일괄 검색
+2. 각 위반 건마다 위치·코드 스니펫·수정안 정리
+3. 우선순위 (Critical → Warning → Info) 분류
+4. Summary 출력 후 사용자에게 일괄 수정 여부 확인
+5. 수정 시 `@.claude/nexus/ui-components.md`, `@.claude/nexus/ui-decisions.md`, `@.claude/nexus/tokens.md` 참조

package/claude-rules/nexus/commands/nexus-component-map.md

@@ -0,0 +1,85 @@
+---
+description: Figma 디자인이나 기존 화면을 NEXUS 컴포넌트로 매핑하는 표를 생성합니다. 코드 작성 전 필수 단계.
+---
+
+# /nexus-component-map
+
+UI 작업 시작 전, 디자인의 모든 요소를 NEXUS 컴포넌트로 매핑하는 단계.
+
+## 사용 시점
+
+- Figma 링크/스크린샷을 받았을 때
+- 기존 화면을 NEXUS로 마이그레이션할 때
+- 새 페이지/모달 설계 시작 시
+
+## 워크플로우
+
+### Step 1. 디자인 입력 받기
+사용자에게 다음 중 하나를 요청:
+- Figma URL (Figma MCP로 `get_design_context` 호출)
+- 스크린샷 첨부
+- 기존 코드 파일 경로
+
+### Step 2. 모든 인터랙티브·시각 요소 식별
+
+다음 카테고리로 분류:
+- **Form fields**: input, select, checkbox, radio, switch, textarea
+- **Actions**: button, dropdown menu, link
+- **Display**: badge, chip, avatar, divider, image
+- **Feedback**: alert, toast, spinner, skeleton, progress, empty state
+- **Overlay**: modal, drawer, popover, tooltip
+- **Navigation**: tab, breadcrumb, pagination, stepper
+- **Layout**: card, list, grid, accordion, carousel
+
+### Step 3. 매핑 표 작성
+
+각 요소마다 다음 표 출력:
+
+```md
+## NEXUS Component Mapping
+
+| # | Detected Element | NEXUS Component | Variants/Props | Note |
+|---|---|---|---|---|
+| 1 | 큰 파란 버튼 "회원가입" | `<Button>` | `semantic="primary" size="lg"` | - |
+| 2 | 회색 작은 버튼 "취소" | `<Button>` | `semantic="normal" variant="ghost"` | - |
+| 3 | 이메일 입력 (라벨 위) | `<TextInput>` | `label="이메일" type="email" clearable` | - |
+| 4 | "정렬" 드롭다운 (4개 옵션) | `<Select>` | `placeholder="정렬"` | 옵션 ≤7 → Select 적합 |
+| 5 | "카테고리" 드롭다운 (24개) | `<Combobox>` | `placeholder="검색하여 선택"` | 옵션 >7 → Combobox |
+| 6 | 알림 받기 토글 | `<Switch>` | `label="알림 받기"` | 즉시 적용 → Switch |
+| 7 | 도움말 ? 아이콘 | `<Tooltip>` | `content="..."` | hover 시 짧은 설명 |
+| 8 | "삭제" 확인 팝업 | `modal.confirm()` | `danger: true` | 파괴적 액션 |
+| 9 | 카드 6개 그리드 | `<DataList>` | - | 단순 그리드 |
+| 10 | 알림 배지 (n) | `<Badge>` | `size="sm"` | - |
+```
+
+### Step 4. 토큰 매핑 (색상·간격)
+
+```md
+## Token Mapping
+
+| Figma 색상 | NEXUS 토큰 |
+|---|---|
+| Background #FAFBFC | `bg-bg-default` |
+| Card #FFFFFF | `bg-surface-elevated` |
+| Primary CTA #0066FF | `bg-accent-primary` |
+| Body text #1E232E | `text-text-primary` |
+| Border #E5E7EB | `border-border-default` |
+```
+
+### Step 5. 사용자 확인 후 코드 생성
+
+매핑 표를 보여주고 사용자 OK 받은 후 코드 작성 시작.
+
+## 모호한 케이스 처리
+
+매핑 시 결정이 어려우면 `@.claude/nexus/ui-decisions.md` 참조:
+- "Select vs Combobox" — 옵션 개수와 검색 필요성으로 판단
+- "Modal vs Drawer" — 결정 강제 vs 보조 작업
+- "Tab vs ToggleGroup" — 영역 전환 vs 즉시 옵션
+
+## 참조 문서
+
+- 컴포넌트 매핑 규칙: `@.claude/nexus/ui-components.md`
+- 컴포넌트 props: `@.claude/nexus/ui-api.md`
+- 결정 가이드: `@.claude/nexus/ui-decisions.md`
+- 토큰 전체: `@.claude/nexus/tokens.md`

package/claude-rules/nexus/commands/nexus-token-check.md

@@ -0,0 +1,68 @@
+---
+description: NEXUS 디자인 토큰 위반(hex, rgb, 기본 Tailwind 색상)을 빠르게 검출하고 토큰으로 교체할 매핑을 제시합니다.
+---
+
+# /nexus-token-check
+
+토큰 사용 위반만 빠르게 검사하는 가벼운 명령어. 색상에 집중.
+
+## 검사 패턴
+
+`src/`, `app/`, `pages/`, `components/`, `styles/` 하위에서 검색:
+
+| 위반 패턴 | 정규식 |
+|---|---|
+| hex 색상 | `#([0-9a-fA-F]{3,4}\|[0-9a-fA-F]{6}\|[0-9a-fA-F]{8})\b` |
+| rgb/rgba | `rgba?\(\s*\d+` |
+| hsl/hsla | `hsla?\(` |
+| 기본 Tailwind 컬러 | `\b(bg\|text\|border\|ring\|from\|to\|via)-(red\|blue\|green\|yellow\|orange\|amber\|lime\|emerald\|teal\|cyan\|sky\|indigo\|violet\|purple\|fuchsia\|pink\|rose\|gray\|slate\|zinc\|neutral\|stone)-\d+` |
+| 임의값 색상 | `\b(bg\|text\|border)-\[#` |
+
+## 토큰 매핑 가이드 (자주 쓰이는 변환)
+
+| 원본 | NEXUS 토큰 | 용도 |
+|---|---|---|
+| `bg-white` `bg-gray-50` | `bg-bg-default` | 페이지 배경 |
+| `bg-gray-100` | `bg-surface-elevated` | 카드 배경 |
+| `bg-gray-200` | `bg-surface-sunken` | 비활성 영역 |
+| `text-gray-900` `text-black` | `text-text-primary` | 본문 |
+| `text-gray-600` | `text-text-secondary` | 보조 텍스트 |
+| `text-gray-400` | `text-text-muted` | 비활성 텍스트 |
+| `border-gray-200` | `border-border-default` | 일반 테두리 |
+| `border-gray-300` | `border-border-strong` | 강조 테두리 |
+| `bg-blue-500` `bg-blue-600` | `bg-accent-primary` | 주요 액션 |
+| `bg-red-500` | `bg-status-danger` | 위험 |
+| `bg-yellow-500` | `bg-status-warning` | 경고 |
+| `bg-green-500` | `bg-status-success` | 성공 |
+| `text-blue-500` | `text-accent-primary` | 강조 텍스트 |
+| `text-red-500` | `text-status-danger` | 에러 텍스트 |
+
+전체 매핑은 `@.claude/nexus/tokens.md` 참조.
+
+## 출력 형식
+
+```md
+## Token Check Report
+
+### 위반 8건 발견
+
+src/pages/Login.tsx
+  L23  `<button className="bg-blue-500 text-white">` → `bg-accent-primary text-text-on-accent`
+  L45  `style={{ borderColor: '#e5e7eb' }}` → `border-border-default`
+
+src/components/Card.tsx
+  L12  `bg-gray-50` → `bg-surface-elevated`
+
+### Summary
+- hex: 1
+- rgb/hsl: 0
+- Tailwind 기본 컬러: 6
+- 임의값: 1
+```
+
+## 작업 흐름
+
+1. Grep으로 위 패턴 검색
+2. 각 위반에 권고 토큰 명시
+3. 사용자에게 일괄 자동 수정 여부 확인
+4. 수정 시 `@.claude/nexus/tokens.md`로 정확한 토큰 검증

package/claude-rules/nexus/skills/nexus-design-system/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: nexus-design-system
+description: Use whenever the user asks to build UI, implement a Figma design, create/edit components, pages, forms, layouts, or change colors/spacing/styling in this codebase. Maps native HTML and Tailwind primitives to @nexus-cross/design-system components and NEXUS design tokens. Triggers on natural-language requests like "버튼 만들어줘", "이 페이지 구현해줘", "색상 바꿔줘", "Figma 보고 만들어줘", "input 추가", "modal 띄워줘". Required reading before generating any UI code in this project.
+---
+
+# NEXUS Design System Skill
+
+이 프로젝트는 `@nexus-cross/design-system`을 사용합니다. UI 코드를 작성하기 전에 반드시 이 룰을 따르세요.
+
+## 핵심 워크플로우 (모든 UI 작업)
+
+### Step 1. 컴포넌트 매핑
+디자인의 모든 UI 요소를 NEXUS 컴포넌트로 매핑하세요. **native `<button>`, `<input>`, `<select>` 등을 직접 쓰기 전에 반드시 매핑 표를 확인.**
+
+| 발견된 요소 | NEXUS 컴포넌트 |
+|---|---|
+| `<button>` | `<Button>` |
+| `<input type="text">` | `<TextInput>` |
+| `<input type="number">` | `<NumberInput>` |
+| `<textarea>` | `<TextArea>` |
+| `<select>` (옵션 ≤7) | `<Select>` |
+| 검색·필터링 select (옵션 >7) | `<Combobox>` |
+| `<input type="checkbox">` | `<CheckBox>` |
+| `<input type="radio">` | `<RadioGroup>` + `<RadioItem>` |
+| 토글 스위치 | `<Switch>` |
+| 칩/태그 | `<Chip>` |
+| 탭 | `<Tab>` |
+| 모달 | `modal()` (imperative) 또는 `<ModalTemplate>` |
+| 측면 패널 | `<Drawer>` |
+| 툴팁 | `<Tooltip>` |
+| 팝오버 | `<Popover>` |
+| 아바타 | `<Avatar>` |
+| 알림 (토스트) | `toast()` |
+| 배지 | `<Badge>` |
+| 알림 박스 | `<Alert>` |
+| 진행률 | `<Progress>` |
+| 빈 상태 | `<EmptyState>` |
+| 로더 | `<Spinner>` 또는 `<Skeleton>` |
+
+상세 가이드: `@.claude/nexus/ui-components.md`
+
+### Step 2. 토큰 사용
+
+색상·간격·라디우스·타이포그래피는 NEXUS 토큰만 사용:
+
+| 카테고리 | Tailwind 프리픽스 | 예시 |
+|---|---|---|
+| 배경 | `bg-bg-*`, `bg-surface-*` | `bg-bg-default`, `bg-surface-elevated` |
+| 텍스트 | `text-text-*` | `text-text-primary`, `text-text-muted` |
+| 아이콘 | `text-icon-*` | `text-icon-default` |
+| 테두리 | `border-border-*` | `border-border-default` |
+| 액센트 | `bg-accent-*` `text-accent-*` | `bg-accent-primary` |
+| 상태 | `bg-status-*` `text-status-*` | `text-status-danger` |
+
+❌ 금지: `bg-blue-500`, `style={{ color: '#1e232e' }}`, `border: 1px solid #ddd`
+
+상세 토큰 목록: `@.claude/nexus/tokens.md`
+
+### Step 3. props 정확히 사용
+
+각 컴포넌트의 props는 `@.claude/nexus/ui-api.md`에서 확인. 특히 자주 틀리는 항목:
+- `Button`: `semantic` × `variant` 2축 (`primary/secondary/normal/danger` × `contained/outlined/subtle/ghost`)
+- `TextInput`: `error` (boolean), `label`, `description`, `clearable`, `showCount` + `maxLength`
+- `Combobox`: 옵션 7개 이상 또는 검색 필요할 때. async 옵션은 `loading` prop 활용
+- `RadioGroup`: 새 `variant="ring"` 옵션 (체크 시 두꺼운 테두리)
+- `ToggleGroup`: 새 `outline` variant + `fullWidth` prop (버튼 형식)
+- `modal()`: imperative API. `<Dialog>` 직접 구현 금지
+
+## Figma → 코드 변환 규칙
+
+1. Figma MCP 출력 (특히 `get_design_context`)은 **디자인 의도 파악용**.
+2. 절대 그대로 붙여넣지 말고, 다음 단계 거치기:
+   - 모든 색상값 → NEXUS 토큰
+   - 모든 native 요소 → NEXUS 컴포넌트
+   - inline style → Tailwind 클래스
+   - 직접 정의된 폰트 스택 → 토큰 클래스
+3. 매핑 결과를 사용자에게 표로 보여주고 진행.
+
+## 절대 금지
+
+- ❌ `!important`로 NEXUS 컴포넌트 스타일 강제 오버라이드 (`cn()` 사용)
+- ❌ Radix UI / Headless UI 직접 import (NEXUS가 내부적으로 사용 중)
+- ❌ NEXUS에 동일 기능이 있는데 raw HTML로 재구현
+- ❌ hex/rgb/HSL/기본 Tailwind 색상
+
+## 더 알아야 할 것
+
+- 컴포넌트 매핑 상세: `@.claude/nexus/ui-components.md`
+- 컴포넌트 props API: `@.claude/nexus/ui-api.md`
+- 디자인 토큰 전체: `@.claude/nexus/tokens.md`
+- 도메인 토큰: `@.claude/nexus/domains.md`
+- 핵심 룰 모음: `@.claude/nexus/CLAUDE.md`