@nexus-cross/design-system

v2.0.6

Published

9 days ago

NEXUS Design System UI Components

0High
0Medium
0Low

hans-nexus

design-system ui components nexus-cross

@nexus-cross/design-system

NEXUS Design System — UI 컴포넌트 + 디자인 토큰을 한 패키지에 담은 통합 라이브러리.

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. 설치

npm install @nexus-cross/design-system
# 또는: pnpm add / yarn add

postinstall에서 nexus-ds-setup이 자동 실행되어 Cursor/Claude Code 규칙 파일도 함께 셋업합니다.

2. CSS 한 줄 셋업 (Tailwind v4 기준)

/* 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. 컴포넌트 사용

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)

/* app/globals.css */
@import 'tailwindcss';
@import '@nexus-cross/design-system/tailwind-v4.css';

// 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

/* src/globals.css */
@import 'tailwindcss';
@import '@nexus-cross/design-system/tailwind-v4.css';

Tailwind v3

// 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}'],
}

/* 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 미사용)

@import '@nexus-cross/design-system/tokens/css';
/* 도메인 토큰까지: */
/* @import '@nexus-cross/design-system/tokens-domains/prediction-vars.css'; */

// 앱 entry (main.tsx / _app.tsx)
import '@nexus-cross/design-system/styles'

도메인 토큰 추가

도메인(예: Prediction) 색을 함께 쓰고 싶다면 한 줄 추가:

@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로 분리하세요.

// 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" />
    </>
  )
}

// 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

// 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 변수

.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 유틸리티

<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)

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는 절대 덮어쓰지 않고 마커 블록만 추가/갱신합니다.

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 마커 블록만 삽입/갱신 (사용자 내용 보존) |

설치 후엔 자연어로:

"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 하세요. 의존하지 않는 컴포넌트는 번들에 포함되지 않습니다.

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 오버라이드가 항상 우선합니다.

<Button semantic="primary" className="rounded-full px-6">
  알림 받기
</Button>

🔌 호환성

React — ^18 / ^19
TypeScript — ^5 권장
Node — >=18 (권장 >=20)
Tailwind — v3 / v4 모두 지원, 없어도 사용 가능

react와 react-dom은 peerDependency 입니다. 호스트 앱이 제공해야 합니다.

📚 더 알아보기

통합 사용 가이드 — 환경별 가장 상세한 셋업
Designer 가이드 — 토큰 시각 편집 도구
파이프라인 — 디자이너 → PR → 빌드 → 배포
@nexus-cross/tokens — 토큰만 단독 사용
@nexus-cross/tokens-domains — 도메인 토큰만 단독 사용
CHANGELOG — 버전 변경 이력

📝 라이선스

ISC

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@nexus-cross/design-system

🚀 Quick Start

1. 설치

2. CSS 한 줄 셋업 (Tailwind v4 기준)

3. 컴포넌트 사용

📦 환경별 셋업

Next.js + Tailwind v4 (Turbopack / Webpack)

Vite + Tailwind v4

Tailwind v3

순수 CSS / CSS Modules (Tailwind 미사용)

도메인 토큰 추가

🔔 전역 셋업: <Toaster /> · <ModalContainer />

Pattern A — Next.js App Router (권장)

Pattern B — Vite / CRA / 이미 client인 root

🎨 디자인 토큰 사용

CSS 변수

Tailwind 유틸리티

JS API (sub-path)

🤖 AI 규칙 자동 셋업 — nexus-ds-setup

🧩 컴포넌트 카탈로그 (45+)

Hooks

Utils

📁 Sub-path Imports (트리쉐이킹)

⚙️ 컴포넌트 오버라이드

🔌 호환성

📚 더 알아보기

📝 라이선스

🔔 전역 셋업: `<Toaster />` · `<ModalContainer />`

🤖 AI 규칙 자동 셋업 — `nexus-ds-setup`