@samkwang/ui-kit
v2.3.0
Published
Samkwang Design System UI Components for React / Next.js
Maintainers
leehyungjunReadme
@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],
// ...
};4. 디자인 선택
data-theme는 light/dark 명암 테마, data-design은 디자인 언어 선택입니다.
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html data-design="v3" data-theme="light" data-density="comfortable">
<body>{children}</body>
</html>
);
}| 속성 | 값 | 설명 |
|------|----|------|
| data-design | v2, v3 | 기존 디자인 / 신규 운영 시스템형 디자인 |
| data-theme | light, dark | 라이트 / 다크 명암 테마 |
| data-density | compact, comfortable, spacious | 화면 정보 밀도 |
반응형 breakpoint 정책
@samkwang/ui-kit 은 두 종류의 breakpoint 를 노출하고, 둘은 서로 충돌하지 않게 격리되어 있습니다.
| 종류 | variant | 분기 | 용도 |
|------|---------|-----|------|
| 표준 Tailwind | sm: md: lg: xl: 2xl: | 640 / 768 / 1024 / 1280 / 1536px | consumer 페이지 레이아웃 — 자유롭게 사용 / override |
| UI Kit (M3 adaptive) | sk-compact: sk-medium: sk-expanded: sk-large: | 600 / 840 / 1200 / 1600px | UI Kit 내부 컴포넌트 의 반응형 분기 |
→ consumer 의 globals.css 에서 --breakpoint-md: 800px 같이 표준 값을 바꿔도 UI Kit 컴포넌트는 깨지지 않습니다. UI Kit 의 반응형 분기는 sk-* 로 별도 노출됩니다.
// 페이지 레이아웃 - 표준 사용
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3">...</div>
// M3 adaptive 분기가 필요하면 sk-* 도 그대로 쓸 수 있음
<aside className="hidden sk-large:block">사이드바</aside>AI / Consumer 사용 가이드
npm 패키지에는 AI와 consumer 프로젝트가 참고할 문서가 함께 포함됩니다.
| 문서 | 용도 |
|------|------|
| docs/ai/AI_USAGE.md | AI가 화면 구현 전 읽어야 할 기본 규칙 |
| docs/ai/components.md | 주요 컴포넌트 import, props, 예제 |
| docs/ai/patterns.md | 사내 운영 시스템 화면을 만들 때 사용할 공용 조합 패턴 |
| docs/ai/components.manifest.json | AI/도구가 읽기 쉬운 컴포넌트 manifest |
consumer 프로젝트의 AGENTS.md에는 다음 지시를 추가하는 것을 권장합니다.
UI 구현 시 @samkwang/ui-kit을 우선 사용한다.
작업 전 node_modules/@samkwang/ui-kit/docs/ai/AI_USAGE.md를 읽는다.
Button, Input, Select, DataTable, Badge, Card, Dialog, Sheet, Tabs, Stepper, Progress 등은 직접 구현하지 말고 UI Kit 컴포넌트를 사용한다.호환성
| 환경 | 지원 버전 | |------|-----------| | Node.js | >= 18 | | npm | >= 9 (또는 pnpm >= 8 / yarn >= 4) | | React | ^18.0.0 || ^19.0.0 | | Next.js | 13+ (App Router / Pages Router) | | TypeScript | 지원 (타입 정의 포함) |
모든 컴포넌트에 "use client" 지시문이 포함되어 Next.js App Router에서 바로 사용할 수 있습니다.
설치 문제 해결 (Troubleshooting)
npm i @samkwang/ui-kit 시 workspace: 관련 에러가 나는 경우
라이브러리 자체에는 workspace: protocol이 포함돼 있지 않습니다 (npm view @samkwang/ui-kit dependencies 로 확인 가능). 거의 항상 consumer 환경의 문제입니다. 다음 순서대로 점검하세요.
1. monorepo 안에서 install 하는 경우
자기 앱 root 디렉토리에서 npm i 를 실행해야 합니다. 모노레포 root의 package.json 에 "workspaces": [...] 필드가 있다면, 앱 디렉토리(예: apps/web/)에서 직접 실행하세요.
# ❌ 잘못 — monorepo root 에서
cd ~/my-monorepo
npm i @samkwang/ui-kit
# ✅ 올바름 — 앱 디렉토리에서
cd ~/my-monorepo/apps/web
npm i @samkwang/ui-kit2. 기존 lockfile 혼용
이전에 pnpm으로 설치돼 pnpm-lock.yaml 이 남아있는 디렉토리에서 npm을 그대로 쓰면 workspace: 표현 충돌이 납니다.
# 둘 중 하나로 통일
rm pnpm-lock.yaml node_modules -rf
npm install
# 또는 pnpm 사용
rm package-lock.json node_modules -rf
pnpm install3. npm 버전 확인
node --version # >= 18
npm --version # >= 9 (8 이하는 workspaces protocol 처리 미흡)낮으면 업그레이드:
npm install -g npm@latest4. 모두 해도 안 되면
정확한 에러 메시지와 함께 사내 슬랙 #frontend-kit 채널에 공유하세요. npm install --verbose @samkwang/ui-kit 2>&1 | tee npm-error.log 출력 같이 부탁드립니다.
React 버전 충돌 (ERESOLVE)
npm install @samkwang/ui-kit --legacy-peer-deps임시 해결책. 근본 원인은 consumer 앱에 React 18과 19가 동시에 hoist된 경우. npm ls react 로 중복 확인 후 정리하세요.
개발 가이드
환경 설정
git clone [email protected]:tom783/samkwang-ui-kit.git
cd samkwang-ui-kit
npm installStorybook 실행
npm run devhttp://localhost:6006 에서 모든 컴포넌트를 확인할 수 있습니다.
Storybook 정적 빌드
웹 서버에 배포할 정적 파일을 생성합니다.
npm run build-storybookstorybook-static/ 디렉토리에 정적 파일이 생성되며, 이를 웹 서버(Vercel, Netlify, GitHub Pages 등)에 배포하면 팀원들이 브라우저에서 컴포넌트 문서를 확인할 수 있습니다.
라이브러리 빌드
npm run builddist/ 디렉토리에 ESM, CJS, 타입 정의, CSS 파일이 생성됩니다.
타입 체크
npm run lintnpm 배포
사전 준비
- npmjs.com에서
samkwang조직이 존재하는지 확인합니다. - 프로젝트 루트에
.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