@bigtablet/design-system 1.14.0 → 1.14.2

package/README.md

@@ -2,8 +2,6 @@
 
 <img width="1800" height="300" alt="Image" src="https://github.com/user-attachments/assets/420a15cc-5be3-447f-9c64-068e946cb118" /> <br>
 
-</div>
-
 # Bigtablet Design System
 
 [![npm version](https://img.shields.io/npm/v/@bigtablet/design-system.svg)](https://www.npmjs.com/package/@bigtablet/design-system)
@@ -11,9 +9,9 @@
 
 Bigtablet의 공식 디자인 시스템으로, Foundation(디자인 토큰)과 Components(UI 컴포넌트)로 구성된 통합 UI 라이브러리입니다.
 
-> **현재 버전**: v1.12.0 | **최근 업데이트**: 2025년 1월 15일
+[GitHub](https://github.com/Bigtablet/bigtablet-design-system) · [NPM](https://www.npmjs.com/package/@bigtablet/design-system) · [Storybook](https://bigtablet.github.io/bigtablet-design-system)
 
-[깃허브 링크](https://github.com/Bigtablet/bigtablet-design-system) | [📦 NPM 패키지](https://www.npmjs.com/package/@bigtablet/design-system)
+</div>
 
 ---
 
@@ -22,93 +20,73 @@ Bigtablet의 공식 디자인 시스템으로, Foundation(디자인 토큰)과 C
 - [주요 특징](#주요-특징)
 - [설치](#설치)
 - [빠른 시작](#빠른-시작)
-- [프로젝트 구조](#프로젝트-구조)
+- [컴포넌트](#컴포넌트)
 - [Foundation (디자인 토큰)](#foundation-디자인-토큰)
-- [Components (UI 컴포넌트)](#components-ui-컴포넌트)
 - [개발 가이드](#개발-가이드)
 - [기여하기](#기여하기)
-- [라이센스](#라이센스)
 
 ---
 
 ## 주요 특징
 
-**체계적인 구조**
-- Foundation과 Components의 명확한 분리
-- TypeScript 기반 타입 안정성
-- SCSS 기반 스타일 토큰 관리
-
-**개발자 경험**
-- Storybook 8 기반 인터랙티브 문서화
-- Chromatic 시각적 회귀 테스트
-- Pure React / Next.js 전용 번들 제공
-
-**최신 기술 스택**
-- React 19 지원
-- pnpm 워크스페이스
-- GitHub Actions 자동 배포
-- Changesets 기반 버전 관리
-
-**디자인 시스템**
-- 일관된 디자인 토큰 (색상, 타이포그래피, 간격 등)
-- 접근성(a11y) 기본 지원
-- 다크모드 준비중
+- **React 19 지원** - 최신 React 버전 완벽 지원
+- **TypeScript** - 완전한 타입 안정성
+- **Pure React / Next.js** - 프레임워크별 최적화된 번들 제공
+- **디자인 토큰** - 일관된 색상, 타이포그래피, 간격 시스템
+- **접근성(a11y)** - 키보드 네비게이션, 스크린 리더 호환
+- **Storybook** - 인터랙티브 문서화
 
 ---
 
 ## 설치
 
-### npm
 ```bash
+# npm
 npm install @bigtablet/design-system
-```
 
-### yarn
-```bash
+# yarn
 yarn add @bigtablet/design-system
+
+# pnpm
+pnpm add @bigtablet/design-system
 ```
 
-### pnpm
+### Peer Dependencies
+
 ```bash
-pnpm add @bigtablet/design-system
+npm install react react-dom lucide-react react-toastify
 ```
 
 ---
 
 ## 빠른 시작
 
-### Pure React 프로젝트
+### Pure React
 
 ```tsx
 import { Button, TextField } from '@bigtablet/design-system';
-import '@bigtablet/design-system/styles';
+import '@bigtablet/design-system/style.css';
 
 function App() {
   return (
     <div>
-      <TextField 
-        label="이메일" 
-        type="email" 
-        placeholder="email@example.com"
-      />
-      <Button variant="primary" size="md">
-        제출하기
-      </Button>
+      <TextField label="이메일" placeholder="email@example.com" />
+      <Button variant="primary">제출</Button>
     </div>
   );
 }
 ```
 
-### Next.js 프로젝트
+### Next.js
 
 ```tsx
 import { Sidebar, Button } from '@bigtablet/design-system/next';
-import '@bigtablet/design-system/styles';
+import '@bigtablet/design-system/style.css';
 
 export default function Layout({ children }) {
   return (
     <div>
-      <Sidebar 
+      <Sidebar
         items={[
           { label: '홈', href: '/' },
           { label: '대시보드', href: '/dashboard' }
@@ -120,502 +98,582 @@ export default function Layout({ children }) {
 }
 ```
 
-### Foundation 토큰 사용
-
-```tsx
-import { colors, spacing, typography } from '@bigtablet/design-system/foundation';
-
-const StyledComponent = styled.div`
-  color: ${colors.brand.primary};
-  padding: ${spacing.md};
-  font-size: ${typography.body.fontSize};
-`;
-```
-
 ---
 
-## 프로젝트 구조
+## 컴포넌트
 
-```
-bigtablet-design-system/
-├── .changeset/              # 버전 관리 설정
-├── .github/
-│   └── workflows/           # CI/CD 파이프라인
-├── .storybook/              # Storybook 설정
-├── public/                  # 정적 리소스
-├── scripts/                 # 빌드 및 배포 스크립트
-├── src/
-│   ├── styles/
-│   │   ├── ts/             # TypeScript 디자인 토큰
-│   │   │   ├── colors.ts
-│   │   │   ├── spacing.ts
-│   │   │   ├── typography.ts
-│   │   │   ├── radius.ts
-│   │   │   ├── shadows.ts
-│   │   │   ├── motion.ts
-│   │   │   ├── z-index.ts
-│   │   │   ├── breakpoints.ts
-│   │   │   └── a11y.ts
-│   │   └── scss/           # SCSS 믹스인 및 변수
-│   ├── ui/
-│   │   ├── form/           # 입력 컴포넌트
-│   │   │   ├── Button/
-│   │   │   ├── TextField/
-│   │   │   ├── Checkbox/
-│   │   │   ├── Radio/
-│   │   │   ├── Switch/
-│   │   │   ├── Select/
-│   │   │   └── FileInput/
-│   │   ├── feedback/       # 피드백 컴포넌트
-│   │   │   ├── Alert/
-│   │   │   ├── Toast/
-│   │   │   └── Loading/
-│   │   ├── navigation/     # 네비게이션 컴포넌트
-│   │   │   ├── Pagination/
-│   │   │   └── Sidebar/
-│   │   ├── overlay/        # 오버레이 컴포넌트
-│   │   │   └── Modal/
-│   │   ├── display/        # 표시 컴포넌트
-│   │   │   └── Card/
-│   │   └── skeleton/       # 스켈레톤 컴포넌트
-│   │       ├── SkeletonCard/
-│   │       └── SkeletonList/
-│   ├── index.ts            # Pure React 진입점
-│   └── next.ts             # Next.js 진입점
-├── package.json
-├── tsconfig.json
-├── tsup.config.ts
-└── README.md
-```
+### General
 
----
+#### Button
 
-## Foundation (디자인 토큰)
+```tsx
+import { Button } from '@bigtablet/design-system';
 
-Foundation은 **모든 컴포넌트의 기반이 되는 디자인 규칙**입니다. 컴포넌트 구현 시 임의의 값을 사용하지 않고 반드시 Foundation 토큰을 사용해야 합니다.
+// 기본 사용
+<Button>클릭</Button>
 
-### 1. Colors (색상)
+// Variants
+<Button variant="primary">Primary</Button>
+<Button variant="secondary">Secondary</Button>
+<Button variant="ghost">Ghost</Button>
+<Button variant="danger">Danger</Button>
 
-브랜드 색상, 배경색, 텍스트 색상, 상태 색상을 정의합니다.
+// Sizes
+<Button size="sm">Small</Button>
+<Button size="md">Medium</Button>
+<Button size="lg">Large</Button>
 
-```typescript
-// src/styles/ts/colors.ts
-export const colors = {
-  brand: {
-    primary: '#0066FF',
-    secondary: '#00C896',
-  },
-  background: {
-    primary: '#FFFFFF',
-    secondary: '#F5F5F5',
-  },
-  text: {
-    primary: '#1A1A1A',
-    secondary: '#666666',
-  },
-  status: {
-    success: '#22C55E',
-    error: '#EF4444',
-    warning: '#F59E0B',
-  }
-};
+// 너비 조절
+<Button width="200px">고정 너비</Button>
+<Button width="100%">전체 너비</Button>
 ```
 
-**사용 예시:**
-```tsx
-<Button style={{ backgroundColor: colors.brand.primary }}>
-  클릭
-</Button>
-```
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'danger'` | `'primary'` | 버튼 스타일 |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 버튼 크기 |
+| `width` | `string` | `'100%'` | 버튼 너비 |
+| `disabled` | `boolean` | `false` | 비활성화 |
 
-### 2. Spacing (간격)
+#### Select
 
-일관된 레이아웃을 위한 margin, padding, gap 기준을 정의합니다.
+```tsx
+import { Select } from '@bigtablet/design-system';
 
-```typescript
-// src/styles/ts/spacing.ts
-export const spacing = {
-  xs: '4px',
-  sm: '8px',
-  md: '16px',
-  lg: '24px',
-  xl: '32px',
-  xxl: '48px',
-};
-```
+const options = [
+  { value: 'apple', label: '사과' },
+  { value: 'banana', label: '바나나' },
+  { value: 'orange', label: '오렌지', disabled: true },
+];
 
-### 3. Typography (타이포그래피)
+// 기본 사용
+<Select
+  label="과일 선택"
+  options={options}
+  placeholder="선택하세요"
+  onChange={(value, option) => console.log(value, option)}
+/>
 
-폰트 패밀리, 크기, 굵기, 줄 간격을 정의합니다.
+// Controlled
+const [fruit, setFruit] = useState<string | null>(null);
+<Select
+  options={options}
+  value={fruit}
+  onChange={(value) => setFruit(value)}
+/>
 
-```typescript
-// src/styles/ts/typography.ts
-export const typography = {
-  fontFamily: {
-    base: 'Pretendard, -apple-system, sans-serif',
-    mono: 'Fira Code, monospace',
-  },
-  heading: {
-    h1: { fontSize: '32px', lineHeight: '40px', fontWeight: 700 },
-    h2: { fontSize: '24px', lineHeight: '32px', fontWeight: 700 },
-    h3: { fontSize: '20px', lineHeight: '28px', fontWeight: 600 },
-  },
-  body: {
-    large: { fontSize: '16px', lineHeight: '24px', fontWeight: 400 },
-    medium: { fontSize: '14px', lineHeight: '20px', fontWeight: 400 },
-    small: { fontSize: '12px', lineHeight: '16px', fontWeight: 400 },
-  }
-};
+// Variants & Sizes
+<Select options={options} variant="outline" size="md" />
+<Select options={options} variant="filled" size="lg" />
+<Select options={options} variant="ghost" size="sm" />
 ```
 
-### 4. Radius (둥근 모서리)
-
-컴포넌트의 모서리 둥글기 기준을 정의합니다.
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options` | `SelectOption[]` | required | 옵션 목록 |
+| `value` | `string \| null` | - | 선택된 값 (controlled) |
+| `defaultValue` | `string \| null` | `null` | 기본 선택값 |
+| `onChange` | `(value, option) => void` | - | 변경 핸들러 |
+| `placeholder` | `string` | `'Select…'` | 플레이스홀더 |
+| `variant` | `'outline' \| 'filled' \| 'ghost'` | `'outline'` | 스타일 |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 크기 |
+| `fullWidth` | `boolean` | `false` | 전체 너비 |
+| `disabled` | `boolean` | `false` | 비활성화 |
 
-```typescript
-// src/styles/ts/radius.ts
-export const radius = {
-  none: '0',
-  sm: '4px',
-  md: '8px',
-  lg: '12px',
-  full: '9999px',
-};
-```
-
-### 5. Shadows (그림자)
+---
 
-elevation 레벨에 따른 그림자를 정의합니다.
+### Form
 
-```typescript
-// src/styles/ts/shadows.ts
-export const shadows = {
-  sm: '0 1px 2px rgba(0, 0, 0, 0.05)',
-  md: '0 4px 6px rgba(0, 0, 0, 0.1)',
-  lg: '0 10px 15px rgba(0, 0, 0, 0.1)',
-  xl: '0 20px 25px rgba(0, 0, 0, 0.15)',
-};
-```
+#### TextField
 
-### 6. Motion (애니메이션)
+```tsx
+import { TextField } from '@bigtablet/design-system';
 
-transition duration과 easing curve를 정의합니다.
+// 기본 사용
+<TextField label="이름" placeholder="이름을 입력하세요" />
 
-```typescript
-// src/styles/ts/motion.ts
-export const motion = {
-  duration: {
-    fast: '150ms',
-    normal: '300ms',
-    slow: '500ms',
-  },
-  easing: {
-    ease: 'ease',
-    easeIn: 'ease-in',
-    easeOut: 'ease-out',
-    easeInOut: 'ease-in-out',
-  }
-};
-```
+// 상태 표시
+<TextField label="이메일" error helperText="유효하지 않은 이메일입니다" />
+<TextField label="이메일" success helperText="사용 가능한 이메일입니다" />
 
-### 7. Z-Index (레이어 우선순위)
+// 아이콘
+import { Search, Eye } from 'lucide-react';
+<TextField leftIcon={<Search size={16} />} placeholder="검색..." />
+<TextField rightIcon={<Eye size={16} />} type="password" />
 
-컴포넌트 레이어의 우선순위를 정의합니다.
+// Variants
+<TextField variant="outline" label="Outline" />
+<TextField variant="filled" label="Filled" />
+<TextField variant="ghost" label="Ghost" />
 
-```typescript
-// src/styles/ts/z-index.ts
-export const zIndex = {
-  base: 0,
-  dropdown: 1000,
-  sticky: 1100,
-  modal: 1300,
-  toast: 1400,
-  tooltip: 1500,
-};
+// 값 변환 (자동 포맷팅)
+<TextField
+  label="전화번호"
+  transformValue={(v) => v.replace(/\D/g, '').slice(0, 11)}
+  onChangeAction={(value) => console.log(value)}
+/>
 ```
 
-### 8. Breakpoints (반응형 기준)
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | - | 라벨 |
+| `helperText` | `string` | - | 도움말 텍스트 |
+| `error` | `boolean` | `false` | 에러 상태 |
+| `success` | `boolean` | `false` | 성공 상태 |
+| `variant` | `'outline' \| 'filled' \| 'ghost'` | `'outline'` | 스타일 |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 크기 |
+| `leftIcon` | `ReactNode` | - | 왼쪽 아이콘 |
+| `rightIcon` | `ReactNode` | - | 오른쪽 아이콘 |
+| `fullWidth` | `boolean` | `false` | 전체 너비 |
+| `onChangeAction` | `(value: string) => void` | - | 값 변경 콜백 |
+| `transformValue` | `(value: string) => string` | - | 값 변환 함수 |
 
-반응형 디자인을 위한 화면 크기 기준을 정의합니다.
+#### DatePicker
 
-```typescript
-// src/styles/ts/breakpoints.ts
-export const breakpoints = {
-  mobile: '320px',
-  tablet: '768px',
-  laptop: '1024px',
-  desktop: '1440px',
-};
-```
+```tsx
+import { DatePicker } from '@bigtablet/design-system';
+
+// 기본 사용 (연-월-일)
+const [date, setDate] = useState('');
+<DatePicker
+  label="생년월일"
+  value={date}
+  onChange={setDate}
+/>
 
-### 9. Accessibility (접근성)
+// 연-월 모드
+<DatePicker
+  label="시작 월"
+  mode="year-month"
+  value={date}
+  onChange={setDate}
+/>
 
-접근성을 위한 기준을 정의합니다.
+// 범위 제한
+<DatePicker
+  label="예약일"
+  startYear={2020}
+  endYear={2030}
+  selectableRange="until-today"  // 오늘까지만 선택 가능
+  value={date}
+  onChange={setDate}
+/>
 
-```typescript
-// src/styles/ts/a11y.ts
-export const a11y = {
-  focusRing: '0 0 0 3px rgba(0, 102, 255, 0.3)',
-  focusRingError: '0 0 0 3px rgba(239, 68, 68, 0.3)',
-  tapMinSize: '44px', // 최소 터치 영역
-};
+// 너비 조절
+<DatePicker label="날짜" width={300} onChange={setDate} />
+<DatePicker label="날짜" width="50%" onChange={setDate} />
 ```
 
----
-
-## Components (UI 컴포넌트)
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | - | 라벨 |
+| `value` | `string` | - | 선택된 날짜 (`'YYYY-MM-DD'` 또는 `'YYYY-MM'`) |
+| `onChange` | `(value: string) => void` | required | 변경 핸들러 |
+| `mode` | `'year-month' \| 'year-month-day'` | `'year-month-day'` | 날짜 선택 모드 |
+| `startYear` | `number` | `1950` | 시작 연도 |
+| `endYear` | `number` | `현재년도 + 10` | 종료 연도 |
+| `selectableRange` | `'all' \| 'until-today'` | `'all'` | 선택 가능 범위 |
+| `minDate` | `string` | - | 최소 날짜 |
+| `width` | `number \| string` | `'100%'` | 너비 |
+| `disabled` | `boolean` | `false` | 비활성화 |
 
-Components는 Foundation 토큰을 기반으로 구현된 실제 UI 요소입니다.
-
-### Form (입력 컴포넌트)
-
-#### Button
+#### Checkbox
 
 ```tsx
-<Button variant="primary" size="md" onClick={() => alert('클릭!')}>
-  기본 버튼
-</Button>
-```
+import { Checkbox } from '@bigtablet/design-system';
 
-**Props:**
-- `variant`: `primary` | `secondary` | `ghost` | `danger`
-- `size`: `sm` | `md` | `lg`
-- `disabled`: `boolean`
-- `loading`: `boolean`
+// 기본 사용
+<Checkbox label="동의합니다" />
 
-#### TextField
-
-```tsx
-<TextField
-  label="이메일"
-  type="email"
-  placeholder="email@example.com"
-  helperText="이메일을 입력해주세요"
-  error={false}
-  leftIcon={<EmailIcon />}
+// Controlled
+const [checked, setChecked] = useState(false);
+<Checkbox
+  label="알림 받기"
+  checked={checked}
+  onChange={(e) => setChecked(e.target.checked)}
 />
-```
-
-**Props:**
-- `label`: `string`
-- `type`: `text` | `email` | `password` | `number`
-- `error`: `boolean`
-- `helperText`: `string`
-- `leftIcon` / `rightIcon`: `ReactNode`
 
-#### Checkbox
+// Indeterminate (부분 선택)
+<Checkbox label="전체 선택" indeterminate />
 
-```tsx
-<Checkbox
-  checked={isChecked}
-  onChange={(e) => setIsChecked(e.target.checked)}
-  label="동의합니다"
-  indeterminate={false}
-/>
+// Sizes
+<Checkbox size="sm" label="Small" />
+<Checkbox size="md" label="Medium" />
+<Checkbox size="lg" label="Large" />
 ```
 
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `ReactNode` | - | 라벨 |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 크기 |
+| `indeterminate` | `boolean` | `false` | 부분 선택 상태 |
+| `checked` | `boolean` | - | 체크 상태 |
+| `disabled` | `boolean` | `false` | 비활성화 |
+
 #### Radio
 
 ```tsx
+import { Radio } from '@bigtablet/design-system';
+
+const [selected, setSelected] = useState('option1');
+
 <Radio
-  name="option"
-  value="1"
-  checked={selected === '1'}
-  onChange={(e) => setSelected(e.target.value)}
+  name="options"
+  value="option1"
   label="옵션 1"
+  checked={selected === 'option1'}
+  onChange={(e) => setSelected(e.target.value)}
+/>
+<Radio
+  name="options"
+  value="option2"
+  label="옵션 2"
+  checked={selected === 'option2'}
+  onChange={(e) => setSelected(e.target.value)}
 />
 ```
 
 #### Switch
 
 ```tsx
-<Switch
-  checked={isOn}
-  onChange={(checked) => setIsOn(checked)}
-  label="알림 받기"
-/>
-```
+import { Switch } from '@bigtablet/design-system';
 
-#### Select
+// 기본 사용
+<Switch onChange={(checked) => console.log(checked)} />
 
-```tsx
-<Select
-  options={[
-    { value: '1', label: '옵션 1' },
-    { value: '2', label: '옵션 2' },
-  ]}
-  value={selected}
-  onChange={(value) => setSelected(value)}
-  placeholder="선택하세요"
-/>
+// Controlled
+const [isOn, setIsOn] = useState(false);
+<Switch checked={isOn} onChange={setIsOn} />
+
+// Sizes
+<Switch size="sm" />
+<Switch size="md" />
+<Switch size="lg" />
 ```
 
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `checked` | `boolean` | - | 켜짐 상태 (controlled) |
+| `defaultChecked` | `boolean` | `false` | 기본 상태 |
+| `onChange` | `(checked: boolean) => void` | - | 변경 핸들러 |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 크기 |
+| `disabled` | `boolean` | `false` | 비활성화 |
+
 #### FileInput
 
 ```tsx
+import { FileInput } from '@bigtablet/design-system';
+
 <FileInput
-  accept="image/*"
-  onChange={(file) => console.log(file)}
   label="파일 선택"
+  accept="image/*"
+  onFiles={(files) => console.log(files)}
+/>
+
+// 여러 파일
+<FileInput
+  label="이미지 업로드"
+  accept="image/*"
+  multiple
+  onFiles={(files) => console.log(files)}
 />
 ```
 
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | `'파일 선택'` | 버튼 라벨 |
+| `accept` | `string` | - | 허용 파일 타입 |
+| `onFiles` | `(files: FileList \| null) => void` | - | 파일 선택 핸들러 |
+| `multiple` | `boolean` | `false` | 다중 선택 |
+| `disabled` | `boolean` | `false` | 비활성화 |
+
 ---
 
-### Feedback (피드백 컴포넌트)
+### Feedback
 
 #### Alert
 
 ```tsx
-import { useAlert } from '@bigtablet/design-system';
-
-function Component() {
-  const alert = useAlert();
-  
-  const handleClick = () => {
-    alert.show({
-      title: '알림',
-      message: '작업이 완료되었습니다.',
-      variant: 'success',
-      onConfirm: () => console.log('확인'),
-      onCancel: () => console.log('취소'),
+import { AlertProvider, useAlert } from '@bigtablet/design-system';
+
+// App에 Provider 추가
+function App() {
+  return (
+    <AlertProvider>
+      <YourComponent />
+    </AlertProvider>
+  );
+}
+
+// 사용
+function YourComponent() {
+  const { showAlert } = useAlert();
+
+  const handleDelete = () => {
+    showAlert({
+      variant: 'warning',
+      title: '삭제 확인',
+      message: '정말 삭제하시겠습니까?',
+      showCancel: true,
+      confirmText: '삭제',
+      cancelText: '취소',
+      onConfirm: () => console.log('삭제됨'),
+      onCancel: () => console.log('취소됨'),
     });
   };
+
+  return <button onClick={handleDelete}>삭제</button>;
 }
 ```
 
-**Variants:** `info` | `success` | `warning` | `error`
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `variant` | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` | 알림 타입 |
+| `title` | `ReactNode` | - | 제목 |
+| `message` | `ReactNode` | - | 메시지 |
+| `confirmText` | `string` | `'확인'` | 확인 버튼 텍스트 |
+| `cancelText` | `string` | `'취소'` | 취소 버튼 텍스트 |
+| `showCancel` | `boolean` | `false` | 취소 버튼 표시 |
+| `actionsAlign` | `'left' \| 'center' \| 'right'` | `'right'` | 버튼 정렬 |
+| `onConfirm` | `() => void` | - | 확인 핸들러 |
+| `onCancel` | `() => void` | - | 취소 핸들러 |
 
 #### Toast
 
 ```tsx
 import { ToastProvider, useToast } from '@bigtablet/design-system';
 
+// App에 Provider 추가
 function App() {
   return (
-    <ToastProvider>
+    <>
+      <ToastProvider />
       <YourComponent />
-    </ToastProvider>
+    </>
   );
 }
 
+// 사용
 function YourComponent() {
   const toast = useToast();
-  
+
   return (
-    <button onClick={() => toast.success('저장되었습니다')}>
-      저장
-    </button>
+    <div>
+      <button onClick={() => toast.success('저장되었습니다')}>성공</button>
+      <button onClick={() => toast.error('오류가 발생했습니다')}>에러</button>
+      <button onClick={() => toast.warning('주의가 필요합니다')}>경고</button>
+      <button onClick={() => toast.info('참고 정보입니다')}>정보</button>
+      <button onClick={() => toast.message('일반 메시지')}>메시지</button>
+    </div>
   );
 }
 ```
 
-**메서드:**
-- `toast.success(message)`
-- `toast.error(message)`
-- `toast.warning(message)`
-- `toast.info(message)`
-- `toast.message(message)`
+#### Spinner
 
-#### Loading
+```tsx
+import { Spinner } from '@bigtablet/design-system';
+
+<Spinner />           // 기본 (24px)
+<Spinner size={16} /> // 작은 크기
+<Spinner size={48} /> // 큰 크기
+```
+
+#### TopLoading
 
 ```tsx
-<Loading size="md" />
+import { TopLoading } from '@bigtablet/design-system';
+
+// Indeterminate (무한 로딩)
+<TopLoading isLoading />
+
+// Progress (진행률 표시)
+<TopLoading isLoading progress={65} />
+
+// 커스텀 스타일
+<TopLoading isLoading color="#ff0000" height={5} />
+
+// 숨기기
+<TopLoading isLoading={false} />
 ```
 
-**Props:**
-- `size`: `sm` | `md` | `lg`
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `isLoading` | `boolean` | `true` | 표시 여부 |
+| `progress` | `number` | - | 진행률 (0-100), 없으면 indeterminate |
+| `color` | `string` | primary | 로딩바 색상 |
+| `height` | `number` | `3` | 로딩바 높이 (px) |
 
 ---
 
-### Navigation (네비게이션 컴포넌트)
+### Navigation
 
 #### Pagination
 
 ```tsx
+import { Pagination } from '@bigtablet/design-system';
+
+const [page, setPage] = useState(1);
+
 <Pagination
-  currentPage={page}
-  totalPages={10}
-  onPageChange={(newPage) => setPage(newPage)}
+  page={page}
+  totalPages={20}
+  onChange={setPage}
 />
 ```
 
-#### Sidebar (Next.js 전용)
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `page` | `number` | required | 현재 페이지 |
+| `totalPages` | `number` | required | 전체 페이지 수 |
+| `onChange` | `(page: number) => void` | required | 페이지 변경 핸들러 |
+
+#### Sidebar (Next.js)
 
 ```tsx
 import { Sidebar } from '@bigtablet/design-system/next';
+import { Home, Settings, Users } from 'lucide-react';
+
+const items = [
+  { href: '/', label: '홈', icon: Home },
+  { href: '/users', label: '사용자', icon: Users },
+  {
+    type: 'group',
+    id: 'settings',
+    label: '설정',
+    icon: Settings,
+    children: [
+      { href: '/settings/profile', label: '프로필' },
+      { href: '/settings/security', label: '보안' },
+    ],
+  },
+];
 
 <Sidebar
-  items={[
-    { label: '홈', href: '/', icon: <HomeIcon /> },
-    { label: '대시보드', href: '/dashboard', icon: <DashboardIcon /> },
-  ]}
-  matchMode="startsWith" // 'startsWith' | 'exact'
+  items={items}
+  activePath={pathname}
+  match="startsWith"
+  brandHref="/main"
 />
 ```
 
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `items` | `SidebarItem[]` | `[]` | 메뉴 아이템 |
+| `activePath` | `string` | - | 현재 활성 경로 |
+| `match` | `'startsWith' \| 'exact'` | `'startsWith'` | 경로 매칭 방식 |
+| `brandHref` | `string` | `'/main'` | 로고 클릭 시 이동 경로 |
+| `onItemSelect` | `(href: string) => void` | - | 아이템 선택 핸들러 |
+
 ---
 
-### Overlay (오버레이 컴포넌트)
+### Overlay
 
 #### Modal
 
 ```tsx
+import { Modal } from '@bigtablet/design-system';
+
+const [isOpen, setIsOpen] = useState(false);
+
+<button onClick={() => setIsOpen(true)}>모달 열기</button>
+
 <Modal
-  isOpen={isOpen}
+  open={isOpen}
   onClose={() => setIsOpen(false)}
   title="모달 제목"
+  width={600}
 >
-  <p>모달 내용</p>
+  <p>모달 내용입니다.</p>
 </Modal>
 ```
 
-**Props:**
-- `isOpen`: `boolean`
-- `onClose`: `() => void`
-- `title`: `string` (optional)
-- `closeOnOverlayClick`: `boolean` (default: `true`)
-- `closeOnEsc`: `boolean` (default: `true`)
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `open` | `boolean` | required | 열림 상태 |
+| `onClose` | `() => void` | - | 닫기 핸들러 |
+| `title` | `ReactNode` | - | 제목 |
+| `width` | `number \| string` | `520` | 모달 너비 |
+| `closeOnOverlay` | `boolean` | `true` | 오버레이 클릭 시 닫기 |
 
 ---
 
-### Display (표시 컴포넌트)
+### Display
 
 #### Card
 
 ```tsx
-<Card elevation="md" padding="lg">
-  <h3>카드 제목</h3>
-  <p>카드 내용</p>
+import { Card } from '@bigtablet/design-system';
+
+<Card heading="카드 제목">
+  <p>카드 내용입니다.</p>
+</Card>
+
+// 스타일 옵션
+<Card heading="제목" shadow="lg" padding="lg" bordered>
+  내용
 </Card>
 ```
 
-**Props:**
-- `elevation`: `sm` | `md` | `lg` | `xl`
-- `padding`: `sm` | `md` | `lg` | `xl`
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `heading` | `ReactNode` | - | 카드 제목 |
+| `shadow` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'sm'` | 그림자 |
+| `padding` | `'none' \| 'sm' \| 'md' \| 'lg'` | `'md'` | 내부 여백 |
+| `bordered` | `boolean` | `false` | 테두리 표시 |
 
 ---
 
-### Skeleton (로딩 상태 컴포넌트)
+## Foundation (디자인 토큰)
 
-#### SkeletonCard
+### SCSS 토큰 사용
 
-```tsx
-<SkeletonCard />
+```scss
+@use "@bigtablet/design-system/scss/token" as token;
+
+.my-component {
+  color: token.$color_primary;
+  padding: token.$spacing_md;
+  border-radius: token.$radius_sm;
+  font-size: token.$font_size_base;
+}
 ```
 
-#### SkeletonList
+### 주요 토큰
+
+| Category | Examples |
+|----------|----------|
+| **Colors** | `$color_primary`, `$color_error`, `$color_text_primary` |
+| **Spacing** | `$spacing_xs` (4px), `$spacing_sm` (8px), `$spacing_md` (16px) |
+| **Typography** | `$font_size_sm`, `$font_size_base`, `$font_weight_medium` |
+| **Radius** | `$radius_sm` (4px), `$radius_md` (8px), `$radius_lg` (12px) |
+| **Shadows** | `$shadow_sm`, `$shadow_md`, `$shadow_lg` |
+| **Z-Index** | `$z_dropdown`, `$z_modal`, `$z_toast` |
+
+---
+
+## 프로젝트 구조
 
-```tsx
-<SkeletonList count={5} />
+```
+src/
+├── styles/
+│   ├── ts/              # TypeScript 디자인 토큰
+│   └── scss/            # SCSS 토큰 및 믹스인
+├── ui/
+│   ├── general/         # Button, Select
+│   ├── form/            # TextField, Checkbox, Radio, Switch, DatePicker, FileInput
+│   ├── feedback/        # Alert, Toast, Spinner, TopLoading
+│   ├── navigation/      # Pagination, Sidebar
+│   ├── overlay/         # Modal
+│   └── display/         # Card
+├── index.ts             # Pure React 진입점
+└── next.ts              # Next.js 진입점
 ```
 
 ---
 
 ## 개발 가이드
 
-### 로컬 개발 환경 설정
-
 ```bash
 # 저장소 클론
 git clone https://github.com/Bigtablet/bigtablet-design-system.git
@@ -629,151 +687,39 @@ pnpm storybook
 
 # 빌드
 pnpm build
-
-# 테스트
-pnpm test
 ```
 
-### Storybook 가이드라인
-
-1. **Title 규칙**
-    - Foundation: `foundation/Colors`, `foundation/Typography`
-    - Components: `components/Button`, `components/TextField`
-
-2. **Story 작성 원칙**
-    - 기본 상태(Default) 필수 포함
-    - 모든 variant와 size 예시 제공
-    - 실제 사용 사례 중심으로 작성
-    - 명확한 설명과 문서화
-
-3. **예시**
-
-```tsx
-// Button.stories.tsx
-import type { Meta, StoryObj } from '@storybook/react';
-import { Button } from './Button';
-
-const meta: Meta<typeof Button> = {
-  title: 'components/Button',
-  component: Button,
-  tags: ['autodocs'],
-};
-
-export default meta;
-type Story = StoryObj<typeof Button>;
-
-export const Default: Story = {
-  args: {
-    children: '기본 버튼',
-    variant: 'primary',
-    size: 'md',
-  },
-};
-
-export const Variants: Story = {
-  render: () => (
-    <>
-      <Button variant="primary">Primary</Button>
-      <Button variant="secondary">Secondary</Button>
-      <Button variant="ghost">Ghost</Button>
-      <Button variant="danger">Danger</Button>
-    </>
-  ),
-};
-```
-
-### 컴포넌트 개발 원칙
-
-1. **Foundation 토큰 사용 필수**
-    - 직접적인 색상/크기 값 사용 금지
-    - 모든 스타일은 토큰을 통해 정의
-
-2. **접근성(a11y) 고려**
-    - 키보드 네비게이션 지원
-    - 스크린 리더 호환
-    - 적절한 ARIA 속성 사용
-
-3. **상태 관리**
-    - hover, active, disabled, error 등 명확히 정의
-    - loading 상태 제공
-
-4. **TypeScript 타입**
-    - Props 타입 명확히 정의
-    - Generic 타입 적절히 활용
-
 ---
 
 ## 기여하기
 
-기여는 언제나 환영합니다! 다음 절차를 따라주세요:
-
 1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+2. Create your feature branch (`git checkout -b feat/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
+4. Push to the branch (`git push origin feat/amazing-feature`)
+5. Open a Pull Request to `develop` branch
 
 ### Commit Convention
 
-```
-feat: 새로운 기능 추가
-fix: 버그 수정
-docs: 문서 수정
-style: 코드 포맷팅, 세미콜론 누락 등
-refactor: 코드 리팩토링
-test: 테스트 코드
-chore: 빌드 업무, 패키지 매니저 설정 등
-```
-
----
-
-## 버전 관리
-
-이 프로젝트는 [Changesets](https://github.com/changesets/changesets)를 사용하여 버전을 관리합니다.
-
-### 변경사항 추가
-
-```bash
-pnpm changeset
-```
-
----
-
-## 기술 스택
-
-| Category | Technology |
-|----------|------------|
-| **Framework** | React 19 |
-| **Language** | TypeScript |
-| **Styling** | SCSS |
-| **Documentation** | Storybook 8 |
-| **Visual Test** | Chromatic |
-| **Build** | tsup |
-| **Package Manager** | pnpm |
-| **CI/CD** | GitHub Actions |
-| **Version Management** | Changesets |
-
----
-
-## 브라우저 지원
-
-- Chrome (최신 2개 버전)
-- Firefox (최신 2개 버전)
-- Safari (최신 2개 버전)
-- Edge (최신 2개 버전)
+| Label | Description |
+|-------|-------------|
+| `feat` | 새로운 기능 |
+| `fix` | 버그/코드 수정 |
+| `docs` | 문서 수정 |
+| `style` | 코드 스타일 변경 |
+| `config` | 설정 파일 수정 |
 
 ---
 
 ## 라이센스
 
-[Bigtablet License](https://github.com/Bigtablet/.github/blob/main/BIGTABLET_LICENSE.md) 를 참고해주세요
+[Bigtablet License](https://github.com/Bigtablet/.github/blob/main/BIGTABLET_LICENSE.md)
 
 ---
 
 ## 링크
 
-- [Github Link](https://bigtablet.github.io/bigtablet-design-system)
-- [NPM 패키지](https://www.npmjs.com/package/@bigtablet/design-system)
-- [이슈 트래커](https://github.com/Bigtablet/bigtablet-design-system/issues)
-- [토론](https://github.com/Bigtablet/bigtablet-design-system/discussions)
-
+- [GitHub](https://github.com/Bigtablet/bigtablet-design-system)
+- [NPM](https://www.npmjs.com/package/@bigtablet/design-system)
+- [Storybook](https://bigtablet.github.io/bigtablet-design-system)
+- [Issues](https://github.com/Bigtablet/bigtablet-design-system/issues)