@samkwang/ui-kit

Samkwang Design System UI Components for React / Next.js

React 및 Next.js 프로젝트에서 일관된 UI를 구현하기 위한 디자인 시스템 컴포넌트 라이브러리입니다.

목적

• 프로젝트 간 일관된 디자인 유지
• 검증된 컴포넌트를 재사용하여 개발 생산성 향상
• Storybook을 통한 컴포넌트 문서화 및 시각적 테스트
• npm 배포를 통한 버전 관리 및 배포 자동화

컴포넌트 목록

| 분류 | 컴포넌트 | |------|----------| | Form | Button, Input, Label, Textarea, Select, Checkbox, Switch, Search, DatePicker | | Data Display | Badge, Table, DataTable, Tabs, TreeView, List, Accordion | | Overlay | Dialog, Modal, DropdownMenu, Popover, Tooltip | | Feedback | Notification, Skeleton, Spinner | | Layout | Separator, ScrollArea |

설치

npm install @samkwang/ui-kit

사용법

1. 스타일 import

앱의 최상위 레이아웃에서 CSS를 1회 import합니다.

// Next.js: app/layout.tsx
// React: src/main.tsx 또는 src/App.tsx
import "@samkwang/ui-kit/styles";

2. 컴포넌트 사용

import { Button, Input, Dialog } from "@samkwang/ui-kit";

export default function MyPage() {
  return (
    <div>
      <Input label="이름" placeholder="이름을 입력하세요" />
      <Button variant="primary">저장</Button>
    </div>
  );
}

3. Tailwind 프리셋 (선택)

프로젝트에서 Tailwind CSS를 사용하고 디자인 시스템의 색상 토큰을 활용하려면:

// tailwind.config.ts
import { samkwangPreset } from "@samkwang/ui-kit/tailwind-preset";

export default {
  presets: [samkwangPreset],
  // ...
};

호환성

| 환경 | 지원 버전 | |------|-----------| | React | ^18.0.0 || ^19.0.0 | | Next.js | 13+ (App Router / Pages Router) | | TypeScript | 지원 (타입 정의 포함) |

모든 컴포넌트에 "use client" 지시문이 포함되어 Next.js App Router에서 바로 사용할 수 있습니다.

개발 가이드

환경 설정

git clone [email protected]:tom783/samkwang-ui-kit.git
cd samkwang-ui-kit
npm install

Storybook 실행

npm run dev

http://localhost:6006 에서 모든 컴포넌트를 확인할 수 있습니다.

Storybook 정적 빌드

웹 서버에 배포할 정적 파일을 생성합니다.

npm run build-storybook

storybook-static/ 디렉토리에 정적 파일이 생성되며, 이를 웹 서버(Vercel, Netlify, GitHub Pages 등)에 배포하면 팀원들이 브라우저에서 컴포넌트 문서를 확인할 수 있습니다.

라이브러리 빌드

npm run build

dist/ 디렉토리에 ESM, CJS, 타입 정의, CSS 파일이 생성됩니다.

타입 체크

npm run lint

npm 배포

사전 준비

1. npmjs.com에서 samkwang 조직이 존재하는지 확인합니다.
2. 프로젝트 루트에 .env 파일을 생성하고 npm 토큰을 설정합니다.

# .env
NPM_TOKEN=your_npm_token_here

.env 파일은 .gitignore에 포함되어 Git에 커밋되지 않습니다. npm 토큰은 npmjs.com → Access Tokens에서 발급할 수 있습니다.

배포

npm run publish:npm

이 스크립트는 .env에서 NPM_TOKEN을 읽어 자동으로 인증 후 공개 배포합니다. 빌드(tsup)도 자동 실행됩니다.

버전 업데이트

# 패치 (버그 수정): 0.1.0 → 0.1.1
npm version patch

# 마이너 (기능 추가): 0.1.0 → 0.2.0
npm version minor

# 메이저 (Breaking Change): 0.1.0 → 1.0.0
npm version major

기술 스택

• React + TypeScript
• Tailwind CSS v4 + CSS Variables (디자인 토큰)
• Radix UI (접근성 기반 헤드리스 프리미티브)
• Class Variance Authority (컴포넌트 variant 관리)
• tsup (ESM/CJS 번들링)
• Storybook (컴포넌트 문서화)

라이센스

NO LICENCE