@nextlevel_korea/design-system 1.1.5 → 2.0.0

package/README.md

@@ -1,627 +1,199 @@
-# @nextlevel/design-system
+# NextLevel Design System
 
-TypeScript와 Tailwind CSS로 구축된 현대적인 React 디자인 시스템으로, 포괄적인 Storybook 문서화를 제공합니다.
+A modern React design system built with TypeScript and Tailwind CSS, now powered by Next.js.
 
-## 🚀 빠른 시작
+## 🚀 Features
 
-### 설치
+- **Next.js 15**: Latest Next.js with App Router
+- **TypeScript**: Full type safety
+- **Tailwind CSS**: Utility-first CSS framework
+- **Responsive Design**: Mobile-first approach
+- **Customizable Components**: Full color and styling customization
+- **Storybook**: Component documentation and testing
+
+## 📦 Installation
 
 ```bash
 npm install @nextlevel_korea/design-system
 ```
 
-### 기본 사용법
-
-```tsx
-import { Header } from '@nextlevel_korea/design-system';
-import '@nextlevel_korea/design-system/styles';
-
-function App() {
-  return (
-    <div>
-      <Header logo="https://your-logo-url.com/logo.png" />
-    </div>
-  );
-}
-```
-
-## ⚠️ 중요: 스타일 적용 방법
-
-이 라이브러리를 사용할 때 **반드시 스타일을 import**해야 합니다:
-
-### 방법 1: CSS 파일 직접 import (권장)
-
-```tsx
-import { Header } from '@nextlevel_korea/design-system';
-import '@nextlevel_korea/design-system/styles'; // 이 줄이 필수입니다!
-
-function App() {
-  return <Header logo="https://example.com/logo.png" />;
-}
-```
-
-### 방법 2: 전역 CSS 파일에서 import
-
-```css
-/* styles.css */
-@import '@nextlevel_korea/design-system/styles';
-```
-
-### 방법 3: Next.js에서 사용
-
-```tsx
-// pages/_app.tsx 또는 app/layout.tsx
-import '@nextlevel_korea/design-system/styles';
-
-export default function App({ Component, pageProps }) {
-  return <Component {...pageProps} />;
-}
-```
-
-### 방법 4: Vite에서 사용
-
-```tsx
-// main.tsx
-import '@nextlevel_korea/design-system/styles';
-import { Header } from '@nextlevel_korea/design-system';
-```
-
-## 🔧 문제 해결
+## 🛠️ Development
 
-### 스타일이 적용되지 않는 경우
+### Prerequisites
 
-#### 1. 스타일 import 확인
+- Node.js 18+
+- npm or yarn
 
-가장 일반적인 문제는 스타일을 import하지 않는 것입니다:
-
-```tsx
-// ❌ 잘못된 사용법
-import { Header } from '@nextlevel_korea/design-system';
-// 스타일 import가 없음!
-
-// ✅ 올바른 사용법
-import { Header } from '@nextlevel_korea/design-system';
-import '@nextlevel_korea/design-system/styles'; // 필수!
-```
-
-#### 2. Tailwind CSS 충돌 해결
-
-프로젝트에 Tailwind CSS가 이미 설치되어 있는 경우:
-
-```js
-// tailwind.config.js
-module.exports = {
-  content: [
-    './src/**/*.{js,ts,jsx,tsx}',
-    './node_modules/@nextlevel_korea/design-system/dist/**/*.js', // 이 줄 추가
-  ],
-  // 라이브러리의 커스텀 색상을 추가
-  theme: {
-    extend: {
-      colors: {
-        success: '#22c55e',
-        warning: '#eab308',
-        danger: '#ef4444',
-        info: '#0ea5e9',
-        muted: '#6b7280',
-      },
-    },
-  },
-};
-```
+### Setup
 
-#### 3. CSS 우선순위 문제
-
-다른 CSS가 라이브러리 스타일을 덮어쓰는 경우:
-
-```css
-/* styles.css */
-/* 라이브러리 스타일을 먼저 import */
-@import '@nextlevel_korea/design-system/styles';
-
-/* 그 다음에 프로젝트 스타일 */
-@import './your-styles.css';
-```
-
-#### 4. 번들러 설정 확인
-
-**Vite에서 사용 시:**
-
-```ts
-// vite.config.ts
-export default defineConfig({
-  optimizeDeps: {
-    include: ['@nextlevel_korea/design-system'],
-  },
-});
-```
-
-**Webpack에서 사용 시:**
-
-```js
-// webpack.config.js
-module.exports = {
-  resolve: {
-    alias: {
-      '@nextlevel_korea/design-system': require.resolve(
-        '@nextlevel_korea/design-system'
-      ),
-    },
-  },
-};
-```
-
-#### 5. TypeScript 설정 확인
-
-```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "moduleResolution": "node",
-    "esModuleInterop": true,
-    "allowSyntheticDefaultImports": true
-  }
-}
-```
-
-### 일반적인 오류와 해결책
-
-#### 오류: "Cannot resolve module '@nextlevel_korea/design-system/styles'"
+1. Clone the repository:
 
 ```bash
-# 패키지 재설치
-npm uninstall @nextlevel_korea/design-system
-npm install @nextlevel_korea/design-system
+git clone https://github.com/NextLevel-KR/design-system.git
+cd design-system
 ```
 
-#### 오류: "Module not found"
+2. Install dependencies:
 
 ```bash
-# node_modules 삭제 후 재설치
-rm -rf node_modules package-lock.json
 npm install
 ```
 
-#### 스타일이 일부만 적용되는 경우
-
-Tailwind CSS의 purge 설정을 확인하세요:
-
-```js
-// tailwind.config.js
-module.exports = {
-  content: [
-    './src/**/*.{js,ts,jsx,tsx}',
-    './node_modules/@nextlevel_korea/design-system/dist/**/*.js',
-  ],
-  // safelist 추가 (필요한 경우)
-  safelist: [
-    'text-success',
-    'text-warning',
-    'text-danger',
-    'text-info',
-    'text-muted',
-  ],
-};
-```
-
-## 📖 Storybook 문서
-
-우리 디자인 시스템을 탐색하고 이해하는 가장 좋은 방법은 인터랙티브 Storybook 문서를 통하는 것입니다.
-
-### 로컬에서 Storybook 실행하기
-
-컴포넌트를 탐색하기 위해 로컬에서 Storybook을 실행하려면:
+3. Start development server:
 
 ```bash
-# 저장소 클론
-git clone https://github.com/NextLevel-KR/design-system.git
-cd design-system
-
-# 의존성 설치
-npm install
-
-# Storybook 시작
-npm run storybook
+npm run dev
 ```
 
-그런 다음 브라우저에서 [http://localhost:6006](http://localhost:6006)을 열어보세요.
+4. Open [http://localhost:3000](http://localhost:3000) in your browser.
 
-### Storybook에서 찾을 수 있는 것들
+### Available Scripts
 
-우리 Storybook에는 다음이 포함됩니다:
+- `npm run dev` - Start development server
+- `npm run build` - Build for production
+- `npm run start` - Start production server
+- `npm run lint` - Run ESLint
+- `npm run storybook` - Start Storybook
+- `npm run build-storybook` - Build Storybook
 
-- **📚 인터랙티브 문서** - 모든 컴포넌트의 실시간 예제
-- **🎛️ 컨트롤 패널** - 실시간으로 컴포넌트 props 수정
-- **📱 반응형 테스트** - 다양한 화면 크기에서 컴포넌트 테스트
-- **🌙 다크/라이트 모드** - 테마 간 전환
-- **♿ 접근성 테스트** - 내장된 a11y 검사
-- **📋 코드 예제** - 복사-붙여넣기 가능한 코드 스니펫
+## 🎨 Components
 
-## 🧩 컴포넌트
+### Header Component
 
-### Header
-
-커스터마이징 가능한 로고가 있는 유연한 헤더 컴포넌트입니다. 모든 화면 크기에서 최적화된 반응형 디자인을 제공합니다.
+A responsive navigation header with dropdown menus and mobile sidebar.
 
 ```tsx
-import { Header } from '@nextlevel_korea/design-system';
-import '@nextlevel_korea/design-system/styles'; // 필수!
-
-// 기본 사용법
-<Header logo="https://example.com/logo.png" title="My App" />
+import Header from '@nextlevel_korea/design-system/components/Header/Header'
 
-// 로고만 있는 헤더
-<Header logo="https://example.com/logo.png" />
+const navList = [
+  {
+    idx: 1,
+    name: 'Home',
+    path: '/',
+  },
+  {
+    idx: 2,
+    name: 'Products',
+    path: '/products',
+    sub: [
+      { idx: 1, name: 'Category 1', path: '/products/category1' },
+      { idx: 2, name: 'Category 2', path: '/products/category2' },
+    ],
+  },
+]
 
-// 제목만 있는 헤더
-<Header title="My Application" />
+<Header
+  logo="/logo.png"
+  navList={navList}
+  eventButton={{
+    text: 'Get Started',
+    onClick: () => console.log('Button clicked!'),
+    className: 'bg-blue-500 text-white hover:bg-blue-600',
+  }}
+  colors={{
+    headerBg: 'bg-white',
+    navText: 'text-gray-600',
+    navTextHover: 'hover:text-blue-500',
+  }}
+/>
 ```
 
-**Props:**
-
-- `logo` (string, optional) - 로고 이미지 URL
-- `title` (string, optional) - 헤더 제목
-
-**반응형 스타일 클래스:**
-
-- **레이아웃**: `flex items-center justify-between`
-- **패딩**: `px-4 py-3 sm:px-6 lg:px-8` (화면 크기에 따라 패딩 증가)
-- **로고**: `h-6 sm:h-8 md:h-10 lg:h-12` (화면 크기에 따라 높이 증가)
-- **제목**: `text-lg sm:text-xl md:text-2xl lg:text-3xl` (화면 크기에 따라 폰트 크기 증가)
-- **제목 색상**: `text-success font-bold`
-
-**반응형 동작:**
-
-- **모바일 (320px-639px)**: 컴팩트한 레이아웃, 작은 로고와 텍스트
-- **태블릿 (640px-1023px)**: 중간 크기 로고와 텍스트, 우측 텍스트 표시
-- **데스크톱 (1024px+)**: 큰 로고와 텍스트, 넓은 패딩
-
-**Storybook 예제:**
-
-- 플레이스홀더 로고가 있는 기본 헤더
-- 커스텀 브랜드 헤더
-- 작은 컴팩트 헤더
-- 반응형 테스트 (다양한 화면 크기)
-
-## 🛠️ 개발
-
-### 사전 요구사항
-
-- Node.js 22+
-- npm 또는 yarn
+### Footer Component
 
-### 설정
+A flexible footer with sections, social links, and custom styling.
 
-```bash
-# 의존성 설치
-npm install
-
-# 개발 서버 시작
-npm run dev
-
-# Storybook 시작
-npm run storybook
-
-# 라이브러리 빌드
-npm run build:lib
-
-# Storybook 빌드
-npm run build-storybook
-```
-
-### 프로젝트 구조
+```tsx
+import Footer from '@nextlevel_korea/design-system/components/Footer/Footer';
 
-```
-src/
-├── components/          # React 컴포넌트
-│   ├── Header.tsx      # Header 컴포넌트
-│   └── Header.stories.tsx  # Header Storybook 스토리
-├── utils/              # 유틸리티 함수
-├── index.ts           # 메인 export 파일
-└── index.css          # 전역 스타일
+<Footer
+  logo="/logo.png"
+  companyInfo={{
+    name: 'NextLevel',
+    ceo: 'John Doe',
+    businessNumber: '123-45-67890',
+    phone: '010-1234-5678',
+    email: 'contact@nextlevel.com',
+    address: '123 Main St, City, Country',
+  }}
+/>;
 ```
 
-### 새 컴포넌트 추가하기
+## 🎨 Customization
 
-1. **컴포넌트 생성** `src/components/`에
-2. **Storybook 스토리 추가** 같은 이름 + `.stories.tsx`
-3. **컴포넌트 export** `src/index.ts`에서
-4. **Storybook에서 문서화** 예제와 컨트롤 포함
+All components support extensive customization through props:
 
-예제:
+### Color Customization
 
 ```tsx
-// src/components/Button.tsx
-export interface ButtonProps {
-  variant?: 'primary' | 'secondary';
-  children: React.ReactNode;
-}
-
-export const Button = ({ variant = 'primary', children }: ButtonProps) => {
-  return <button className={`btn btn-${variant}`}>{children}</button>;
-};
-```
+const customColors = {
+  // Background colors
+  headerBg: 'bg-white',
+  sidebarBg: 'bg-gray-50',
 
-```tsx
-// src/components/Button.stories.tsx
-import type { Meta, StoryObj } from '@storybook/react';
-import { Button } from './Button';
-
-const meta: Meta<typeof Button> = {
-  title: 'Components/Button',
-  component: Button,
-  argTypes: {
-    variant: {
-      control: 'select',
-      options: ['primary', 'secondary'],
-    },
-  },
-};
+  // Text colors
+  navText: 'text-gray-600',
+  navTextHover: 'hover:text-blue-500',
 
-export default meta;
-type Story = StoryObj<typeof meta>;
+  // Accent colors
+  primary: 'bg-blue-500',
+  primaryDark: 'bg-blue-600',
 
-export const Primary: Story = {
-  args: {
-    variant: 'primary',
-    children: 'Primary Button',
-  },
+  // Border colors
+  border: 'border-gray-200',
+
+  // Shadow
+  shadow: 'shadow-lg',
 };
 ```
 
-## 🎨 디자인 시스템 특징
-
-- **TypeScript 우선** - 완전한 타입 안전성과 IntelliSense 지원
-- **Tailwind CSS** - 유틸리티 우선 CSS 프레임워크
-- **반응형 디자인** - 모바일 우선 접근법
-- **접근성** - WCAG 2.1 준수 컴포넌트
-- **커스터마이징 가능** - 쉬운 테마링과 커스터마이징
-
-## 📱 반응형 브레이크포인트
-
-이 디자인 시스템은 다음과 같은 반응형 브레이크포인트를 지원합니다:
-
-### 기본 브레이크포인트
-
-- `xs`: 475px (초소형 모바일)
-- `sm`: 640px (소형 모바일)
-- `md`: 768px (태블릿)
-- `lg`: 1024px (노트북)
-- `xl`: 1280px (데스크톱)
-- `2xl`: 1536px (대형 데스크톱)
-- `3xl`: 1920px (초대형 화면)
-- `4xl`: 2560px (울트라 와이드)
-- `5xl`: 3840px (4K 이상)
-
-### 의미적 브레이크포인트
-
-- `mobile`: 320px (모바일)
-- `tablet`: 768px (태블릿)
-- `laptop`: 1024px (노트북)
-- `desktop`: 1280px (데스크톱)
-- `wide`: 1536px (와이드 스크린)
-- `ultra-wide`: 1920px (울트라 와이드)
-
-### 사용 예제
+### Sidebar Position
 
 ```tsx
-// 반응형 헤더 컴포넌트
-<header
-  className="
-  px-4 py-3           // 기본 패딩
-  sm:px-6             // 640px 이상에서 패딩 증가
-  lg:px-8             // 1024px 이상에서 패딩 더 증가
-"
->
-  <img
-    className="
-      h-6              // 기본 높이
-      sm:h-8           // 640px 이상에서 높이 증가
-      md:h-10          // 768px 이상에서 높이 증가
-      lg:h-12          // 1024px 이상에서 높이 증가
-    "
-    src="/logo.png"
-    alt="Logo"
-  />
-  <h1
-    className="
-    text-lg            // 기본 폰트 크기
-    sm:text-xl         // 640px 이상에서 폰트 크기 증가
-    md:text-2xl        // 768px 이상에서 폰트 크기 증가
-    lg:text-3xl        // 1024px 이상에서 폰트 크기 증가
-  "
-  >
-    제목
-  </h1>
-</header>
+<Header
+  sidebarPosition="right" // 'left' | 'right'
+  // ... other props
+/>
 ```
 
-### 반응형 유틸리티 클래스
+## 📚 Storybook
 
-```tsx
-// 숨김/표시
-<div className="hidden sm:block">태블릿 이상에서만 표시</div>
-<div className="block sm:hidden">모바일에서만 표시</div>
-
-// 그리드 시스템
-<div className="
-  grid
-  grid-cols-1         // 모바일: 1열
-  sm:grid-cols-2      // 태블릿: 2열
-  md:grid-cols-3      // 노트북: 3열
-  lg:grid-cols-4      // 데스크톱: 4열
-  xl:grid-cols-5      // 대형 화면: 5열
-  gap-4
-">
-  {/* 그리드 아이템들 */}
-</div>
-
-// 텍스트 크기
-<p className="
-  text-sm             // 기본: 작은 텍스트
-  sm:text-base        // 태블릿: 기본 텍스트
-  md:text-lg          // 노트북: 큰 텍스트
-  lg:text-xl          // 데스크톱: 더 큰 텍스트
-">
-  반응형 텍스트
-</p>
-
-// 최대 너비 (Max Width)
-<div className="
-  w-full              // 전체 너비
-  max-w-xs            // 320px
-  max-w-sm            // 384px
-  max-w-md            // 448px
-  max-w-lg            // 512px
-  max-w-xl            // 576px
-  max-w-2xl           // 672px
-  max-w-3xl           // 768px
-  max-w-4xl           // 896px
-  max-w-5xl           // 1024px
-  max-w-6xl           // 1152px
-  max-w-7xl           // 1280px
-  max-w-full          // 100%
-  max-w-screen-sm     // 640px
-  max-w-screen-md     // 768px
-  max-w-screen-lg     // 1024px
-  max-w-screen-xl     // 1280px
-  max-w-screen-2xl    // 1536px
-">
-  컨테이너
-</div>
-
-// 반응형 최대 너비
-<div className="
-  w-full
-  max-w-xs            // 모바일: 320px
-  sm:max-w-md         // 태블릿: 448px
-  md:max-w-lg         // 노트북: 512px
-  lg:max-w-xl         // 데스크톱: 576px
-  xl:max-w-2xl        // 대형 화면: 672px
-  mx-auto             // 중앙 정렬
-">
-  반응형 컨테이너
-</div>
+View all components and their variations in Storybook:
+
+```bash
+npm run storybook
 ```
 
-## 📚 Storybook 애드온
+Then open [http://localhost:6006](http://localhost:6006)
 
-우리 Storybook은 다음으로 구성되어 있습니다:
+## 🔧 Migration from Vite
 
-- **@storybook/addon-docs** - 자동 문서 생성
-- **@storybook/addon-controls** - 인터랙티브 prop 컨트롤
-- **@storybook/addon-backgrounds** - 배경 전환
-- **@storybook/addon-viewport** - 반응형 테스트
+This project has been migrated from Vite to Next.js for better compatibility and performance. Key changes:
 
-## 🤝 기여하기
+- **App Router**: Using Next.js 13+ App Router
+- **Server Components**: Support for React Server Components
+- **Built-in Optimization**: Automatic code splitting and optimization
+- **Better TypeScript Support**: Enhanced TypeScript integration
+- **Improved Development Experience**: Faster refresh and better error handling
 
-1. 저장소를 포크하세요
-2. 기능 브랜치를 만드세요
-3. Storybook 스토리와 함께 컴포넌트를 추가하세요
-4. Storybook에서 테스트하세요
-5. 풀 리퀘스트를 제출하세요
+## 📄 License
 
-### Storybook 가이드라인
+MIT License - see [LICENSE](LICENSE) file for details.
 
-- 각 컴포넌트는 포괄적인 스토리를 가져야 합니다
-- 여러 변형과 상태를 포함하세요
-- 모든 props에 적절한 argTypes를 추가하세요
-- 접근성 테스트를 포함하세요
-- 명확한 문서를 제공하세요
+## 🤝 Contributing
 
-## 📄 라이선스
+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
 
-MIT 라이선스 - 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.
+## 📞 Support
 
-## 🔗 링크
+For support and questions, please contact:
 
-- [Storybook 문서](https://storybook.js.org/)
-- [Tailwind CSS](https://tailwindcss.com/)
-- [React](https://reactjs.org/)
-- [TypeScript](https://www.typescriptlang.org/)
+- Email: support@nextlevel.com
+- Website: https://nextlevel.com
 
 ---
 
-NextLevel 팀이 ❤️로 만들었습니다
-
-## 📝 완전한 사용 예제
-
-### React + Vite 프로젝트
-
-```tsx
-// src/App.tsx
-import { Header } from '@nextlevel_korea/design-system';
-import '@nextlevel_korea/design-system/styles';
-
-function App() {
-  return (
-    <div className="min-h-screen bg-gray-50">
-      <Header
-        logo="https://via.placeholder.com/150x50/2563eb/ffffff?text=LOGO"
-        title="My Awesome App"
-      />
-      <main className="container mx-auto px-4 py-8">
-        <h1 className="text-3xl font-bold text-gray-900">Welcome to My App</h1>
-      </main>
-    </div>
-  );
-}
-
-export default App;
-```
-
-### Next.js 프로젝트
-
-```tsx
-// app/layout.tsx
-import '@nextlevel_korea/design-system/styles';
-
-export default function RootLayout({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
-  return (
-    <html lang="en">
-      <body>{children}</body>
-    </html>
-  );
-}
-```
-
-```tsx
-// app/page.tsx
-import { Header } from '@nextlevel_korea/design-system';
-
-export default function Home() {
-  return (
-    <div>
-      <Header logo="/logo.png" title="Next.js App" />
-      <main>
-        <h1>Welcome to Next.js!</h1>
-      </main>
-    </div>
-  );
-}
-```
-
-### Create React App
-
-```tsx
-// src/App.js
-import { Header } from '@nextlevel_korea/design-system';
-import '@nextlevel_korea/design-system/styles';
-
-function App() {
-  return (
-    <div className="App">
-      <Header logo="https://example.com/logo.png" title="React App" />
-      <header className="App-header">
-        <p>Edit src/App.js and save to reload.</p>
-      </header>
-    </div>
-  );
-}
-
-export default App;
-```
+Built with ❤️ by NextLevel Team