@nexus-cross/design-system 2.0.0 → 2.0.2

package/README.md

@@ -0,0 +1,375 @@
+# @nexus-cross/design-system
+
+NEXUS Design System — UI 컴포넌트 + 디자인 토큰을 한 패키지에 담은 통합 라이브러리.
+
+[![npm](https://img.shields.io/npm/v/@nexus-cross/design-system)](https://www.npmjs.com/package/@nexus-cross/design-system)
+[![license](https://img.shields.io/npm/l/@nexus-cross/design-system)](#-라이선스)
+
+- **45+ React 컴포넌트** — Button부터 DataGrid, DatePicker까지 프로덕션-레디
+- **160+ 디자인 토큰** — `@nexus-cross/tokens`를 sub-path(`/tokens`)로 자동 노출
+- **도메인 토큰** — `@nexus-cross/tokens-domains`도 sub-path(`/tokens-domains`)로 옵트인
+- **Tailwind v4 / v3 / Pure CSS** — 모든 환경에서 검증 완료 (`test-apps/`)
+- **AI 규칙 자동 셋업** — `nexus-ds-setup` CLI로 Cursor / Claude Code가 자동 인식
+- **Sub-path 개별 임포트** — `@nexus-cross/design-system/button` 처럼 컴포넌트별 트리쉐이킹
+
+> v2.0부터 `@nexus-cross/tokens`와 `@nexus-cross/tokens-domains`를 transitive dependency로 흡수했습니다. **이 패키지 1개만 install 하면 토큰까지 모두 사용할 수 있습니다.**
+
+---
+
+## 🚀 Quick Start
+
+### 1. 설치
+
+```bash
+npm install @nexus-cross/design-system
+# 또는: pnpm add / yarn add
+```
+
+postinstall에서 `nexus-ds-setup`이 자동 실행되어 Cursor/Claude Code 규칙 파일도 함께 셋업합니다.
+
+### 2. CSS 한 줄 셋업 (Tailwind v4 기준)
+
+```css
+/* app/globals.css (Next.js) 또는 src/globals.css (Vite) */
+@import 'tailwindcss';
+@import '@nexus-cross/design-system/tailwind-v4.css';
+```
+
+이 한 줄 안에 다음이 모두 들어 있습니다:
+- 회사 공통 디자인 토큰 (`/tokens/company.css`) 자동 로드
+- 컴포넌트 CSS를 Tailwind `components` 레이어에 주입
+- Cascade: `base < components(Nexus) < utilities` → `className="bg-red-500"` 같은 utility 오버라이드가 항상 우선
+
+### 3. 컴포넌트 사용
+
+```tsx
+import { Button, TextInput } from '@nexus-cross/design-system'
+
+export default function Hello() {
+  return (
+    <form className="flex flex-col gap-3 p-6">
+      <TextInput placeholder="이메일" />
+      <Button semantic="primary" variant="contained">시작하기</Button>
+    </form>
+  )
+}
+```
+
+> Button API: `semantic` ∈ `primary | secondary | tertiary | danger | success | warning | info`,
+> `variant` ∈ `contained | outlined | ghost | text | subtle`.
+
+---
+
+## 📦 환경별 셋업
+
+> 모든 환경은 `test-apps/{tw4, vite-tw4, tw3, pure-css}`에서 Playwright + CDP로 검증됨.
+
+### Next.js + Tailwind v4 (Turbopack / Webpack)
+
+```css
+/* app/globals.css */
+@import 'tailwindcss';
+@import '@nexus-cross/design-system/tailwind-v4.css';
+```
+
+```js
+// next.config.mjs
+const nextConfig = {
+  transpilePackages: ['@nexus-cross/design-system'],
+}
+export default nextConfig
+```
+
+> **레이어 순서를 직접 선언하지 마세요.** Tailwind v4의 CSS 프로세서는 사용자 영역에서 선언한 `@layer base, nexus, components, utilities;` 같은 statement를 자동 정리/제거합니다. `tailwind-v4.css` 프리셋이 Tailwind 빌트인 `components` 레이어를 활용하므로 별도 layer 선언이 필요 없습니다.
+
+### Vite + Tailwind v4
+
+```css
+/* src/globals.css */
+@import 'tailwindcss';
+@import '@nexus-cross/design-system/tailwind-v4.css';
+```
+
+### Tailwind v3
+
+```js
+// tailwind.config.js
+module.exports = {
+  presets: [require('@nexus-cross/design-system/tokens/tailwind')],
+  // 도메인 토큰 사용 시:
+  // presets: [require('@nexus-cross/design-system/tokens-domains/tailwind')],
+  content: ['./src/**/*.{js,ts,jsx,tsx}'],
+}
+```
+
+```css
+/* globals.css */
+@import '@nexus-cross/design-system/tokens/css';
+@import '@nexus-cross/design-system/styles.css';
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+### 순수 CSS / CSS Modules (Tailwind 미사용)
+
+```css
+@import '@nexus-cross/design-system/tokens/css';
+/* 도메인 토큰까지: */
+/* @import '@nexus-cross/design-system/tokens-domains/prediction-vars.css'; */
+```
+
+```tsx
+// 앱 entry (main.tsx / _app.tsx)
+import '@nexus-cross/design-system/styles'
+```
+
+### 도메인 토큰 추가
+
+도메인(예: Prediction) 색을 함께 쓰고 싶다면 한 줄 추가:
+
+```css
+@import 'tailwindcss';
+@import '@nexus-cross/design-system/tailwind-v4.css';
+@import '@nexus-cross/design-system/tokens-domains/prediction.css';
+```
+
+---
+
+## 🔔 전역 셋업: `<Toaster />` · `<ModalContainer />`
+
+`Toaster` / `ModalContainer`는 내부적으로 `useState`를 쓰는 **클라이언트 컴포넌트**입니다. 환경에 맞춰 둘 중 한 패턴을 선택하세요.
+
+### Pattern A — Next.js App Router (권장)
+
+server `layout.tsx`에서 직접 import 하면 `useState only works in Client Components` 에러가 납니다. `"use client"` wrapper로 분리하세요.
+
+```tsx
+// app/providers.tsx
+'use client'
+
+import { Toaster } from '@nexus-cross/design-system'
+import { ModalContainer } from '@nexus-cross/design-system/modal'
+
+export function NexusProviders() {
+  return (
+    <>
+      <ModalContainer />
+      <Toaster position="top-right" />
+    </>
+  )
+}
+```
+
+```tsx
+// app/layout.tsx (server component — "use client" 추가 금지)
+import { NexusProviders } from './providers'
+import './globals.css'
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="ko">
+      <body>
+        {children}
+        <NexusProviders />
+      </body>
+    </html>
+  )
+}
+```
+
+### Pattern B — Vite / CRA / 이미 client인 root
+
+```tsx
+// App.tsx
+import { Toaster } from '@nexus-cross/design-system'
+import { ModalContainer } from '@nexus-cross/design-system/modal'
+
+export default function App() {
+  return (
+    <>
+      {/* routes / pages */}
+      <ModalContainer />
+      <Toaster position="top-right" />
+    </>
+  )
+}
+```
+
+> ⚠️ `Toaster` / `ModalContainer`는 앱 전체에 1개씩만 마운트하세요. 페이지 단위로 다시 마운트하면 toast/modal이 두 번 뜨는 현상이 생길 수 있습니다.
+
+---
+
+## 🎨 디자인 토큰 사용
+
+토큰은 세 가지 방식으로 노출됩니다 — CSS 변수 / Tailwind 유틸리티 / JS API.
+
+### CSS 변수
+
+```css
+.card {
+  background: var(--color-surface-default);
+  color: var(--color-text-primary);
+  padding: var(--space-4);
+  border: 1px solid var(--color-border-default);
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-sm);
+}
+```
+
+### Tailwind 유틸리티
+
+```tsx
+<div className="bg-surface-default text-text-primary p-4 rounded-lg shadow-sm">
+  <h2 className="text-text-primary font-semibold">Hello</h2>
+  <p className="text-text-secondary mt-2">디자인 토큰으로 만든 카드</p>
+</div>
+```
+
+semantic 토큰(`bg-bg-default`, `text-text-primary` 등)은 light/dark 모드별 값을 갖고 있어, 별도 분기 없이 자동 전환됩니다.
+
+### JS API (sub-path)
+
+```tsx
+import { getTheme } from '@nexus-cross/design-system/tokens'
+import { getPredictionTheme } from '@nexus-cross/design-system/tokens-domains'
+
+const { semantic } = getTheme('dark')
+// semantic.bg.default.base → "#1E232E"
+
+const { domain } = getPredictionTheme('dark')
+// domain['domain-market'].bullish.base
+
+<MyChart
+  bg={semantic.bg.default.base}
+  series={[
+    domain['domain-market'].bullish.base,
+    domain['domain-market'].bearish.base,
+  ]}
+/>
+```
+
+---
+
+## 🤖 AI 규칙 자동 셋업 — `nexus-ds-setup`
+
+postinstall에서 자동 실행되며, 수동으로 다시 돌릴 수도 있습니다. 이미 같은 내용이 있으면 skip 합니다. 사용자의 `CLAUDE.md`는 절대 덮어쓰지 않고 마커 블록만 추가/갱신합니다.
+
+```bash
+npx nexus-ds-setup
+```
+
+| 위치 | 내용 |
+|---|---|
+| `.cursor/rules/nexus-project-setup.mdc` | 셋업 / 컴포넌트 매핑 / Figma 변환 룰 |
+| `.cursor/rules/nexus-ui-components.mdc` | 컴포넌트 매핑 가이드 |
+| `.cursor/rules/nexus-ui-api.mdc` | 컴포넌트 props 자동 생성 (44개) |
+| `.cursor/rules/nexus-ui-decisions.mdc` | UI 결정 트리 |
+| `.cursor/rules/nexus-tokens.mdc` | Company 토큰 레퍼런스 |
+| `.cursor/rules/nexus-domains.mdc` | Domain 토큰 레퍼런스 (Prediction 등) |
+| `.claude/nexus/CLAUDE.md` | Claude Code용 인덱스 (`@import` 모음) |
+| `.claude/nexus/skills/nexus-design-system/SKILL.md` | 자연어 트리거 |
+| `.claude/nexus/{ui-components,ui-api,ui-decisions,tokens,domains}.md` | mdc → md 변환본 |
+| `.claude/commands/nexus-{audit,token-check,component-map}.md` | 슬래시 커맨드 |
+| 루트 `DESIGN.md` | 디자인 시스템 핵심 결정 사항 |
+| 루트 `CLAUDE.md` | nexus 마커 블록만 삽입/갱신 (사용자 내용 보존) |
+
+설치 후엔 자연어로:
+
+```text
+"Nexus로 로그인 폼 만들어줘"
+"이 hex(#FF6B6B)를 가장 가까운 Nexus 토큰으로 바꿔줘"
+"이 Figma URL을 Nexus 컴포넌트로 변환해줘"
+
+# 슬래시 커맨드
+/nexus-audit        # 토큰/컴포넌트 사용 감사
+/nexus-token-check  # 하드코딩된 색/스페이스 찾기
+```
+
+---
+
+## 🧩 컴포넌트 카탈로그 (45+)
+
+| 카테고리 | 컴포넌트 |
+|---|---|
+| **Form** | `Button` · `TextInput` · `TextArea` · `NumberInput` · `PriceInput` · `Select` · `Combobox` · `Switch` · `CheckBox` · `RadioGroup` · `Slider` · `ToggleGroup` · `TagInput` · `DatePicker` · `ImageUpload` |
+| **Overlay / Container** | `Modal` · `Drawer` · `Tooltip` · `Popover` · `DropdownMenu` · `Accordion` · `Tab` · `Carousel` |
+| **Feedback** | `Toast` · `Alert` · `Progress` · `Spinner` · `Skeleton` · `Countdown` · `Counter` · `Badge` · `Chip` |
+| **Layout / Navigation** | `Divider` · `EmptyState` · `Stepper` · `Breadcrumb` · `Pagination` |
+| **Data** | `Table` · `DataList` · `DataGrid` · `VirtualScroll` · `InfiniteScroll` · `Marquee` · `Ellipsis` |
+| **Media / Utility** | `Avatar` · `NxImage` · `ClientOnly` · `ErrorBoundary` |
+
+### Hooks
+
+`useCheckDevice` · `useClickOutside` · `useModal` · `useInView`
+
+### Utils
+
+`cn` (class merger)
+
+---
+
+## 📁 Sub-path Imports (트리쉐이킹)
+
+배포 사이즈에 민감한 환경에서는 컴포넌트별 sub-path로 직접 import 하세요. 의존하지 않는 컴포넌트는 번들에 포함되지 않습니다.
+
+```tsx
+import { Button } from '@nexus-cross/design-system/button'
+import { TextInput } from '@nexus-cross/design-system/text-input'
+import { useModal } from '@nexus-cross/design-system/hooks/useModal'
+import { cn } from '@nexus-cross/design-system/utils/cn'
+```
+
+전체 export 경로:
+
+| 카테고리 | 경로 |
+|---|---|
+| **Root API** | `@nexus-cross/design-system` |
+| **Styles** | `/styles` · `/styles.css` · `/styles.layered.css` · `/tailwind-v4.css` · `/styles/layer` |
+| **Tokens (sub-path)** | `/tokens` · `/tokens/data` · `/tokens/tailwind` · `/tokens/company.css` · `/tokens/css` |
+| **Domain Tokens** | `/tokens-domains` · `/tokens-domains/data` · `/tokens-domains/tailwind` · `/tokens-domains/prediction.css` · `/tokens-domains/prediction-vars.css` |
+| **Modal / Toast / Table** | `/modal` · `/toast` · `/table` |
+| **Components** | `/button` · `/text-input` · `/text-area` · `/number-input` · `/price-input` · `/select` · `/combobox` · `/switch` · `/checkbox` · `/radio-group` · `/slider` · `/toggle-group` · `/tag-input` · `/date-picker` · `/avatar` · `/badge` · `/chip` · `/progress` · `/alert` · `/spinner` · `/skeleton` · `/countdown` · `/counter` · `/divider` · `/drawer` · `/tooltip` · `/popover` · `/dropdown-menu` · `/accordion` · `/tab` · `/carousel` · `/breadcrumb` · `/pagination` · `/stepper` · `/empty-state` · `/data-list` · `/data-grid` · `/virtual-scroll` · `/infinite-scroll` · `/marquee` · `/ellipsis` · `/nx-image` · `/client-only` · `/error-boundary` |
+| **Hooks** | `/hooks/useCheckDevice` · `/hooks/useClickOutside` · `/hooks/useModal` · `/hooks/useInView` |
+| **Utils / Schemas** | `/utils/cn` · `/schemas` |
+
+---
+
+## ⚙️ 컴포넌트 오버라이드
+
+Nexus 컴포넌트 CSS는 Tailwind `components` 레이어에 들어가 있고, utility class는 그 다음 레이어에 위치합니다. 따라서 utility 오버라이드가 항상 우선합니다.
+
+```tsx
+<Button semantic="primary" className="rounded-full px-6">
+  알림 받기
+</Button>
+```
+
+---
+
+## 🔌 호환성
+
+- **React** — `^18` / `^19`
+- **TypeScript** — `^5` 권장
+- **Node** — `>=18` (권장 `>=20`)
+- **Tailwind** — v3 / v4 모두 지원, 없어도 사용 가능
+
+> `react`와 `react-dom`은 peerDependency 입니다. 호스트 앱이 제공해야 합니다.
+
+---
+
+## 📚 더 알아보기
+
+- [통합 사용 가이드](https://github.com/nexus-cross/nexus-design-system/blob/main/guides/GUIDE.md) — 환경별 가장 상세한 셋업
+- [Designer 가이드](https://github.com/nexus-cross/nexus-design-system/blob/main/guides/DESIGNER.md) — 토큰 시각 편집 도구
+- [파이프라인](https://github.com/nexus-cross/nexus-design-system/blob/main/guides/PIPELINE.md) — 디자이너 → PR → 빌드 → 배포
+- [@nexus-cross/tokens](https://www.npmjs.com/package/@nexus-cross/tokens) — 토큰만 단독 사용
+- [@nexus-cross/tokens-domains](https://www.npmjs.com/package/@nexus-cross/tokens-domains) — 도메인 토큰만 단독 사용
+- [CHANGELOG](./CHANGELOG.md) — 버전 변경 이력
+
+---
+
+## 📝 라이선스
+
+ISC