@bigtablet/design-system 1.10.0 → 1.11.1

package/README.md

@@ -1,331 +1,786 @@
 # Bigtablet Design System
 
-Bigtablet의 공통 UI 컴포넌트 및 디자인 시스템입니다.  
-Foundation(디자인 토큰)과 Components(UI 컴포넌트)를 분리하여 관리하며,  
-Storybook 기반 문서화와 Chromatic을 통한 시각적 테스트를 제공합니다.
+[![npm version](https://img.shields.io/npm/v/@bigtablet/design-system.svg)](https://www.npmjs.com/package/@bigtablet/design-system)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
----
+Bigtablet의 공식 디자인 시스템으로, Foundation(디자인 토큰)과 Components(UI 컴포넌트)로 구성된 통합 UI 라이브러리입니다.
 
-## Features
+> **현재 버전**: v1.10.0 | **최근 업데이트**: 2025년 1월 7일
 
-- Foundation / Components 구조 분리
-- Storybook 8 기반 문서화
-- Chromatic 시각적 회귀 테스트
-- Pure React / Next.js 분리 번들
-- SCSS 기반 Design Token 관리
-- pnpm + GitHub Actions 자동 배포
+[깃허브 링크](https://github.com/Bigtablet/bigtablet-design-system) | [📦 NPM 패키지](https://www.npmjs.com/package/@bigtablet/design-system)
 
 ---
 
-## Tech Stack
+## 목차
 
-| Category | Technology |
-|--------|-----------|
-| Framework | React 19 |
-| Styling | SCSS |
-| Documentation | Storybook 8 |
-| Visual Test | Chromatic |
-| Build | tsup |
-| Package Manager | pnpm |
-| CI / CD | GitHub Actions |
+- [주요 특징](#주요-특징)
+- [설치](#설치)
+- [빠른 시작](#빠른-시작)
+- [프로젝트 구조](#프로젝트-구조)
+- [Foundation (디자인 토큰)](#foundation-디자인-토큰)
+- [Components (UI 컴포넌트)](#components-ui-컴포넌트)
+- [개발 가이드](#개발-가이드)
+- [기여하기](#기여하기)
+- [라이센스](#라이센스)
 
 ---
 
-## Project Structure
+## 주요 특징
 
-```bash
-src/
-├── styles/
-│   ├── ts/                 # Foundation Tokens (TypeScript)
-│   │   ├── colors.ts
-│   │   ├── spacing.ts
-│   │   ├── typography.ts
-│   │   ├── radius.ts
-│   │   ├── shadows.ts
-│   │   ├── motion.ts
-│   │   ├── z-index.ts
-│   │   ├── breakpoints.ts
-│   │   └── a11y.ts
-│   └── scss/               # SCSS Token & Mixins
-│
-├── ui/
-│   ├── form/               # TextField, Checkbox, Radio, Switch, FileInput
-│   ├── feedback/           # Alert, Toast, Loading
-│   ├── navigation/         # Pagination, Sidebar
-│   ├── overlay/            # Modal
-│   ├── display/            # Card
-│   ├── general/            # Button, Select
-│   ├── skeleton/           # SkeletonCard, SkeletonList
-│   └── styles/             # Shared component styles
-│
-├── index.ts                # Pure React exports
-└── next.ts                 # Next.js specific exports
-```
-
-## Design System Structure
-
-Bigtablet Design System은 **Foundation**과 **Components** 두 레이어로 구성됩니다.  
-Foundation은 디자인의 기준과 규칙을 정의하고,  
-Components는 이 기준을 사용해 실제 UI를 구성합니다.
+**체계적인 구조**
+- Foundation과 Components의 명확한 분리
+- TypeScript 기반 타입 안정성
+- SCSS 기반 스타일 토큰 관리
+
+**개발자 경험**
+- Storybook 8 기반 인터랙티브 문서화
+- Chromatic 시각적 회귀 테스트
+- Pure React / Next.js 전용 번들 제공
+
+**최신 기술 스택**
+- React 19 지원
+- pnpm 워크스페이스
+- GitHub Actions 자동 배포
+- Changesets 기반 버전 관리
+
+**디자인 시스템**
+- 일관된 디자인 토큰 (색상, 타이포그래피, 간격 등)
+- 접근성(a11y) 기본 지원
+- 다크모드 준비중
 
 ---
 
-## Foundation
+## 설치
 
-Storybook 경로:
+### npm
 ```bash
-src/styles/ts/colors.ts
+npm install @bigtablet/design-system
 ```
-Foundation은 **모든 컴포넌트에서 공통으로 사용하는 디자인 기준**입니다.  
-컴포넌트 구현 시, 임의의 값 사용을 금지하고 반드시 Foundation 토큰을 사용해야 합니다.
-
-### Colors
-- 브랜드, 배경, 텍스트, 상태(success / error / warning) 색상
-- 직접 색상 값 사용 금지
 
-파일:
+### yarn
 ```bash
-src/styles/ts/colors.ts
+yarn add @bigtablet/design-system
 ```
----
-
-### Spacing
-- margin, padding, gap 기준 스케일
-- 레이아웃 일관성 유지 목적
 
-파일:
+### pnpm
 ```bash
-src/styles/ts/spacing.ts
+pnpm add @bigtablet/design-system
 ```
 
 ---
 
-### Typography
-- 폰트 패밀리
-- 폰트 크기, 굵기, 줄 간격
-- Heading / Body / Caption 기준
+## 빠른 시작
+
+### Pure React 프로젝트
+
+```tsx
+import { Button, TextField } from '@bigtablet/design-system';
+import '@bigtablet/design-system/styles';
+
+function App() {
+  return (
+    <div>
+      <TextField 
+        label="이메일" 
+        type="email" 
+        placeholder="email@example.com"
+      />
+      <Button variant="primary" size="md">
+        제출하기
+      </Button>
+    </div>
+  );
+}
+```
 
-파일:
-```bash
-src/styles/ts/typography.ts
+### Next.js 프로젝트
+
+```tsx
+import { Sidebar, Button } from '@bigtablet/design-system/next';
+import '@bigtablet/design-system/styles';
+
+export default function Layout({ children }) {
+  return (
+    <div>
+      <Sidebar 
+        items={[
+          { label: '홈', href: '/' },
+          { label: '대시보드', href: '/dashboard' }
+        ]}
+      />
+      <main>{children}</main>
+    </div>
+  );
+}
 ```
 
----
+### Foundation 토큰 사용
 
-### Radius
-- 컴포넌트 모서리 둥글기 기준
-- 카드, 버튼, 입력 필드 등 공통 사용
+```tsx
+import { colors, spacing, typography } from '@bigtablet/design-system/foundation';
 
-파일:
-```bash
-src/styles/ts/radius.ts
+const StyledComponent = styled.div`
+  color: ${colors.brand.primary};
+  padding: ${spacing.md};
+  font-size: ${typography.body.fontSize};
+`;
 ```
 
 ---
 
-### Shadows
-- elevation 레벨 정의
-- 카드, 모달, 드롭다운 등 깊이 표현
+## 프로젝트 구조
 
-파일:
-```bash
-src/styles/ts/shadows.ts
+```
+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
 ```
 
 ---
 
-### Motion
-- transition duration
-- easing curve 기준
+## Foundation (디자인 토큰)
+
+Foundation은 **모든 컴포넌트의 기반이 되는 디자인 규칙**입니다. 컴포넌트 구현 시 임의의 값을 사용하지 않고 반드시 Foundation 토큰을 사용해야 합니다.
+
+### 1. Colors (색상)
+
+브랜드 색상, 배경색, 텍스트 색상, 상태 색상을 정의합니다.
+
+```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',
+  }
+};
+```
 
-파일:
-```bash
-src/styles/ts/motion.ts
+**사용 예시:**
+```tsx
+<Button style={{ backgroundColor: colors.brand.primary }}>
+  클릭
+</Button>
 ```
 
----
+### 2. Spacing (간격)
 
-### Z-Index
-- 레이어 우선순위 정의
-- modal, toast, dropdown 등
+일관된 레이아웃을 위한 margin, padding, gap 기준을 정의합니다.
 
-파일:
-```bash
-src/styles/ts/z-index.ts
+```typescript
+// src/styles/ts/spacing.ts
+export const spacing = {
+  xs: '4px',
+  sm: '8px',
+  md: '16px',
+  lg: '24px',
+  xl: '32px',
+  xxl: '48px',
+};
 ```
 
----
+### 3. Typography (타이포그래피)
+
+폰트 패밀리, 크기, 굵기, 줄 간격을 정의합니다.
+
+```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 },
+  }
+};
+```
 
-### Breakpoints
-- 반응형 기준 해상도
+### 4. Radius (둥근 모서리)
 
-권장 구분:
-- mobile
-- tablet
-- laptop
-- desktop
+컴포넌트의 모서리 둥글기 기준을 정의합니다.
 
-파일:
-```bash
-src/styles/ts/breakpoints.ts
+```typescript
+// src/styles/ts/radius.ts
+export const radius = {
+  none: '0',
+  sm: '4px',
+  md: '8px',
+  lg: '12px',
+  full: '9999px',
+};
 ```
----
 
-### Accessibility (A11y)
-- 포커스 링 스타일
-- 최소 터치 영역 크기
-- 접근성 기준 토큰
+### 5. Shadows (그림자)
 
-파일:
-```bash
-src/styles/ts/a11y.ts
+elevation 레벨에 따른 그림자를 정의합니다.
+
+```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)',
+};
 ```
-예시:
-```ts
-focusRing
-focusRingError
-tapMinSize
+
+### 6. Motion (애니메이션)
+
+transition duration과 easing curve를 정의합니다.
+
+```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',
+  }
+};
 ```
----
 
-## Components
+### 7. Z-Index (레이어 우선순위)
 
-Storybook 경로 규칙:
-```bash
-src/stories/components/name.stoires.tsx
+컴포넌트 레이어의 우선순위를 정의합니다.
+
+```typescript
+// src/styles/ts/z-index.ts
+export const zIndex = {
+  base: 0,
+  dropdown: 1000,
+  sticky: 1100,
+  modal: 1300,
+  toast: 1400,
+  tooltip: 1500,
+};
 ```
-Components는 Foundation 토큰을 기반으로 구현된 **실제 UI 컴포넌트 레이어**입니다.  
-모든 컴포넌트는 다음 원칙을 따릅니다.
 
-- Foundation 토큰(colors, spacing, typography 등)만 사용
-- 상태(hover, active, disabled, error 등) 명확히 정의
-- 접근성(a11y) 기본 고려
-- Storybook 문서 필수 제공
+### 8. Breakpoints (반응형 기준)
+
+반응형 디자인을 위한 화면 크기 기준을 정의합니다.
+
+```typescript
+// src/styles/ts/breakpoints.ts
+export const breakpoints = {
+  mobile: '320px',
+  tablet: '768px',
+  laptop: '1024px',
+  desktop: '1440px',
+};
+```
+
+### 9. Accessibility (접근성)
+
+접근성을 위한 기준을 정의합니다.
+
+```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', // 최소 터치 영역
+};
+```
 
 ---
 
-### Form
+## Components (UI 컴포넌트)
+
+Components는 Foundation 토큰을 기반으로 구현된 실제 UI 요소입니다.
 
-사용자 입력을 담당하는 컴포넌트들입니다.
+### Form (입력 컴포넌트)
 
 #### Button
-- 기본 액션 버튼
-- variant: primary / secondary / ghost / danger
-- size: sm / md / lg
+
+```tsx
+<Button variant="primary" size="md" onClick={() => alert('클릭!')}>
+  기본 버튼
+</Button>
+```
+
+**Props:**
+- `variant`: `primary` | `secondary` | `ghost` | `danger`
+- `size`: `sm` | `md` | `lg`
+- `disabled`: `boolean`
+- `loading`: `boolean`
 
 #### TextField
-- 텍스트 입력 필드
-- label, helperText 지원
-- error / success 상태 지원
-- leftIcon / rightIcon 지원
+
+```tsx
+<TextField
+  label="이메일"
+  type="email"
+  placeholder="email@example.com"
+  helperText="이메일을 입력해주세요"
+  error={false}
+  leftIcon={<EmailIcon />}
+/>
+```
+
+**Props:**
+- `label`: `string`
+- `type`: `text` | `email` | `password` | `number`
+- `error`: `boolean`
+- `helperText`: `string`
+- `leftIcon` / `rightIcon`: `ReactNode`
 
 #### Checkbox
-- 다중 선택 입력
-- indeterminate 상태 지원
+
+```tsx
+<Checkbox
+  checked={isChecked}
+  onChange={(e) => setIsChecked(e.target.checked)}
+  label="동의합니다"
+  indeterminate={false}
+/>
+```
 
 #### Radio
-- 단일 선택 입력
-- 동일한 name으로 그룹 구성
+
+```tsx
+<Radio
+  name="option"
+  value="1"
+  checked={selected === '1'}
+  onChange={(e) => setSelected(e.target.value)}
+  label="옵션 1"
+/>
+```
 
 #### Switch
-- ON / OFF 토글 입력
-- controlled / uncontrolled 모두 지원
+
+```tsx
+<Switch
+  checked={isOn}
+  onChange={(checked) => setIsOn(checked)}
+  label="알림 받기"
+/>
+```
 
 #### Select
-- 드롭다운 선택 컴포넌트
-- 키보드 및 마우스 인터랙션 지원
-- controlled / uncontrolled 모두 지원
+
+```tsx
+<Select
+  options={[
+    { value: '1', label: '옵션 1' },
+    { value: '2', label: '옵션 2' },
+  ]}
+  value={selected}
+  onChange={(value) => setSelected(value)}
+  placeholder="선택하세요"
+/>
+```
 
 #### FileInput
-- 파일 선택 입력
-- 커스텀 UI 제공
 
----
+```tsx
+<FileInput
+  accept="image/*"
+  onChange={(file) => console.log(file)}
+  label="파일 선택"
+/>
+```
 
-### Feedback
+---
 
-사용자에게 상태 및 피드백을 전달하는 컴포넌트들입니다.
+### Feedback (피드백 컴포넌트)
 
 #### Alert
-- 모달 형태의 알림
-- info / success / warning / error variant
-- confirm / cancel 액션 지원
-- useAlert 훅 기반
+
+```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('취소'),
+    });
+  };
+}
+```
+
+**Variants:** `info` | `success` | `warning` | `error`
+
+#### Toast
+
+```tsx
+import { ToastProvider, useToast } from '@bigtablet/design-system';
+
+function App() {
+  return (
+    <ToastProvider>
+      <YourComponent />
+    </ToastProvider>
+  );
+}
+
+function YourComponent() {
+  const toast = useToast();
+  
+  return (
+    <button onClick={() => toast.success('저장되었습니다')}>
+      저장
+    </button>
+  );
+}
+```
+
+**메서드:**
+- `toast.success(message)`
+- `toast.error(message)`
+- `toast.warning(message)`
+- `toast.info(message)`
+- `toast.message(message)`
 
 #### Loading
-- 인라인 로딩 스피너
-- 크기 조절 가능
 
-#### ToastProvider / useToast
-- 전역 토스트 메시지
-- success / error / warning / info / message 타입 제공
-- 내부적으로 react-toastify 사용
+```tsx
+<Loading size="md" />
+```
 
----
+**Props:**
+- `size`: `sm` | `md` | `lg`
 
-### Navigation
+---
 
-페이지 이동 및 흐름 제어 컴포넌트입니다.
+### Navigation (네비게이션 컴포넌트)
 
 #### Pagination
-- Prev / Next 기반 페이지네이션
-- controlled 방식으로 상태 관리
 
-#### Sidebar
-- 좌측 네비게이션 메뉴
-- 활성 경로 표시
-- match 모드 지원 (startsWith / exact)
-- Next.js 전용 컴포넌트
+```tsx
+<Pagination
+  currentPage={page}
+  totalPages={10}
+  onPageChange={(newPage) => setPage(newPage)}
+/>
+```
 
----
+#### Sidebar (Next.js 전용)
 
-### Overlay
+```tsx
+import { Sidebar } from '@bigtablet/design-system/next';
 
-콘텐츠 위에 표시되는 레이어 컴포넌트입니다.
+<Sidebar
+  items={[
+    { label: '홈', href: '/', icon: <HomeIcon /> },
+    { label: '대시보드', href: '/dashboard', icon: <DashboardIcon /> },
+  ]}
+  matchMode="startsWith" // 'startsWith' | 'exact'
+/>
+```
+
+---
+
+### Overlay (오버레이 컴포넌트)
 
 #### Modal
-- 중앙 정렬 오버레이
-- ESC / 오버레이 클릭 닫기 지원
-- 제목 영역 optional
 
----
+```tsx
+<Modal
+  isOpen={isOpen}
+  onClose={() => setIsOpen(false)}
+  title="모달 제목"
+>
+  <p>모달 내용</p>
+</Modal>
+```
 
-### Display
+**Props:**
+- `isOpen`: `boolean`
+- `onClose`: `() => void`
+- `title`: `string` (optional)
+- `closeOnOverlayClick`: `boolean` (default: `true`)
+- `closeOnEsc`: `boolean` (default: `true`)
 
-정보를 시각적으로 표현하는 컴포넌트입니다.
+---
+
+### Display (표시 컴포넌트)
 
 #### Card
-- 콘텐츠 그룹화용 컨테이너
-- elevation 및 padding 포함
 
----
+```tsx
+<Card elevation="md" padding="lg">
+  <h3>카드 제목</h3>
+  <p>카드 내용</p>
+</Card>
+```
 
-### Skeleton
+**Props:**
+- `elevation`: `sm` | `md` | `lg` | `xl`
+- `padding`: `sm` | `md` | `lg` | `xl`
 
-로딩 중 UI를 표현하는 컴포넌트입니다.
+---
+
+### Skeleton (로딩 상태 컴포넌트)
 
 #### SkeletonCard
-- 카드 형태 스켈레톤
+
+```tsx
+<SkeletonCard />
+```
 
 #### SkeletonList
-- 리스트 형태 스켈레톤
+
+```tsx
+<SkeletonList count={5} />
+```
+
+---
+
+## 개발 가이드
+
+### 로컬 개발 환경 설정
+
+```bash
+# 저장소 클론
+git clone https://github.com/Bigtablet/bigtablet-design-system.git
+cd bigtablet-design-system
+
+# 의존성 설치
+pnpm install
+
+# Storybook 실행
+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 타입 적절히 활용
 
 ---
 
-## Storybook Guidelines
+## 기여하기
+
+기여는 언제나 환영합니다! 다음 절차를 따라주세요:
+
+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
+
+### Commit Convention
+
+```
+feat: 새로운 기능 추가
+fix: 버그 수정
+docs: 문서 수정
+style: 코드 포맷팅, 세미콜론 누락 등
+refactor: 코드 리팩토링
+test: 테스트 코드
+chore: 빌드 업무, 패키지 매니저 설정 등
+```
+
+---
+
+## 버전 관리
+
+이 프로젝트는 [Changesets](https://github.com/changesets/changesets)를 사용하여 버전을 관리합니다.
+
+### 변경사항 추가
 
-### Title 규칙
 ```bash
-foundation/
-components/
+pnpm changeset
 ```
 
 ---
 
-### Story 작성 원칙
+## 기술 스택
+
+| 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개 버전)
+
+---
+
+## 라이센스
+
+[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)
+
+---
+
+## 팀
+
+이 프로젝트는 5명의 기여자들에 의해 관리되고 있습니다.
+
+---
+
+<div align="center">
+
+Made with by Bigtablet, Icn.
 
-- 기본 상태(Default) 반드시 포함
-- size / variant / state 예제 포함
-- 디자이너가 봐도 이해 가능한 설명 작성
-- 실제 사용 예제 위주 구성
-- 불필요한 control 노출 지양
+</div>

package/dist/index.css

@@ -964,7 +964,7 @@
   align-items: center;
   justify-content: center;
   gap: 0.5rem;
-  margin-top: 2rem;
+  margin-top: 1.75rem;
 }
 .pagination_item {
   border: 1px solid #e5e5e5;

package/dist/styles/scss/_colors.scss

@@ -1,25 +1,34 @@
+/* Primary */
 $color_primary: #000000;
 $color_primary_hover: #333333;
 
+/* Background */
 $color_background: #ffffff;
 $color_background_secondary: #fafafa;
+$color_background_neutral: #F3F3F3;
+$color_background_muted: #f0f0f0;
+$color_background_primary: #47555E;
 
+/* Text */
 $color_text_primary: #1a1a1a;
 $color_text_secondary: #666666;
 $color_text_tertiary: #999999;
 
+$text_strong: #1f2937;
+$text_normal: #3b3b3b;
+$text_subtle: #6b7280;
+$text_disabled: #9ca3af;
+$text_inverse: #ffffff;
+
+/* Border */
 $color_border: #e5e5e5;
 $color_border_light: rgba(0, 0, 0, 0.08);
 
+/* Status */
 $color_success: #10b981;
 $color_error: #ef4444;
 $color_warning: #f59e0b;
 $color_info: #3b82f6;
 
-$color_overlay: rgba(0, 0, 0, 0.5);
-
-$text_strong: #1f2937;
-$text_normal: #3b3b3b;
-$text_subtle: #6b7280;
-$text_disabled: #9ca3af;
-$text_inverse: #ffffff;
+/* Overlay */
+$color_overlay: rgba(0, 0, 0, 0.5);

package/dist/styles/scss/_spacing.scss

@@ -1,9 +1,12 @@
-$spacing_xs: 0.25rem;
-$spacing_sm: 0.5rem;
-$spacing_md: 0.75rem;
-$spacing_lg: 1rem;
-$spacing_xl: 1.25rem;
-$spacing_2xl: 1.5rem;
-$spacing_3xl: 2rem;
-$spacing-4xl: 2.5rem;
-$spacing-5xl: 3rem;
+$spacing_xs: 0.25rem; // 4px
+$spacing_sm: 0.5rem; // 8px
+$spacing_md: 0.75rem; // 12px
+$spacing_lg: 1rem; // 16px
+$spacing_xl: 1.25rem; // 20px
+$spacing_2xl: 1.5rem; // 24px
+$spacing_3xl: 1.75rem; // 28px
+$spacing_4xl: 2rem; // 32px
+$spacing_5xl: 2.25rem; // 36px
+$spacing_6xl: 2.5rem; // 40px
+$spacing_7xl: 2.75rem; // 44px
+$spacing_8xl: 3rem; // 48px

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bigtablet/design-system",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "description": "Bigtablet Design System UI Components",
   "type": "module",
   "types": "dist/index.d.ts",

package/src/styles/scss/_colors.scss

@@ -1,25 +1,34 @@
+/* Primary */
 $color_primary: #000000;
 $color_primary_hover: #333333;
 
+/* Background */
 $color_background: #ffffff;
 $color_background_secondary: #fafafa;
+$color_background_neutral: #F3F3F3;
+$color_background_muted: #f0f0f0;
+$color_background_primary: #47555E;
 
+/* Text */
 $color_text_primary: #1a1a1a;
 $color_text_secondary: #666666;
 $color_text_tertiary: #999999;
 
+$text_strong: #1f2937;
+$text_normal: #3b3b3b;
+$text_subtle: #6b7280;
+$text_disabled: #9ca3af;
+$text_inverse: #ffffff;
+
+/* Border */
 $color_border: #e5e5e5;
 $color_border_light: rgba(0, 0, 0, 0.08);
 
+/* Status */
 $color_success: #10b981;
 $color_error: #ef4444;
 $color_warning: #f59e0b;
 $color_info: #3b82f6;
 
-$color_overlay: rgba(0, 0, 0, 0.5);
-
-$text_strong: #1f2937;
-$text_normal: #3b3b3b;
-$text_subtle: #6b7280;
-$text_disabled: #9ca3af;
-$text_inverse: #ffffff;
+/* Overlay */
+$color_overlay: rgba(0, 0, 0, 0.5);

package/src/styles/scss/_spacing.scss

@@ -1,9 +1,12 @@
-$spacing_xs: 0.25rem;
-$spacing_sm: 0.5rem;
-$spacing_md: 0.75rem;
-$spacing_lg: 1rem;
-$spacing_xl: 1.25rem;
-$spacing_2xl: 1.5rem;
-$spacing_3xl: 2rem;
-$spacing-4xl: 2.5rem;
-$spacing-5xl: 3rem;
+$spacing_xs: 0.25rem; // 4px
+$spacing_sm: 0.5rem; // 8px
+$spacing_md: 0.75rem; // 12px
+$spacing_lg: 1rem; // 16px
+$spacing_xl: 1.25rem; // 20px
+$spacing_2xl: 1.5rem; // 24px
+$spacing_3xl: 1.75rem; // 28px
+$spacing_4xl: 2rem; // 32px
+$spacing_5xl: 2.25rem; // 36px
+$spacing_6xl: 2.5rem; // 40px
+$spacing_7xl: 2.75rem; // 44px
+$spacing_8xl: 3rem; // 48px