# 디자인 시스템 빠른 참조 가이드

## 📍 접근 경로
```
로그인 (SystemAdmin) → 기준정보 관리 → 디자인시스템
```

## 🎯 컴포넌트 빠른 찾기

### Atoms (6개) - `/components/ui/`
| 컴포넌트 | 용도 | Import |
|---------|------|--------|
| Button | 버튼 | `import { Button } from "./components/ui/button"` |
| Input | 입력 필드 | `import { Input } from "./components/ui/input"` |
| Label | 레이블 | `import { Label } from "./components/ui/label"` |
| Badge | 배지 | `import { Badge } from "./components/ui/badge"` |
| Switch | 스위치 | `import { Switch } from "./components/ui/switch"` |
| Checkbox | 체크박스 | `import { Checkbox } from "./components/ui/checkbox"` |

### Molecules (6개) - `/components/molecules/`
| 컴포넌트 | 용도 | Import |
|---------|------|--------|
| FormField | 레이블+입력 | `import { FormField } from "./components/molecules/FormField"` |
| SearchBar | 검색바 | `import { SearchBar } from "./components/molecules/SearchBar"` |
| StatCard | 통계 카드 | `import { StatCard } from "./components/molecules/StatCard"` |
| StatusBadge | 상태 배지 | `import { StatusBadge } from "./components/molecules/StatusBadge"` |
| TableActions | 테이블 액션 | `import { TableActions } from "./components/molecules/TableActions"` |
| IconWithBadge | 아이콘+배지 | `import { IconWithBadge } from "./components/molecules/IconWithBadge"` |

### Organisms (8개) - `/components/organisms/`
| 컴포넌트 | 용도 | Import |
|---------|------|--------|
| PageHeader | 페이지 헤더 ⭐ | `import { PageHeader } from "./components/organisms/PageHeader"` |
| StatCards | 통계 그리드 ⭐ | `import { StatCards } from "./components/organisms/StatCards"` |
| SearchFilter | 검색+필터 ⭐ | `import { SearchFilter } from "./components/organisms/SearchFilter"` |
| DataTable | 데이터 테이블 ⭐ | `import { DataTable } from "./components/organisms/DataTable"` |
| PageLayout | 페이지 레이아웃 | `import { PageLayout } from "./components/organisms/PageLayout"` |
| EmptyState | 빈 상태 | `import { EmptyState } from "./components/organisms/EmptyState"` |
| FormSection | 폼 섹션 | `import { FormSection } from "./components/organisms/FormSection"` |
| MobileCard | 모바일 카드 | `import { MobileCard } from "./components/organisms/MobileCard"` |

⭐ = 모든 페이지에서 필수 사용

### Templates (4개) - `/components/templates/`
| 컴포넌트 | 용도 | Import |
|---------|------|--------|
| ListPageTemplate | 목록 페이지 🔥 | `import { ListPageTemplate } from "./components/templates/ListPageTemplate"` |
| FormPageTemplate | 폼 페이지 | `import { FormPageTemplate } from "./components/templates/FormPageTemplate"` |
| DashboardTemplate | 대시보드 | `import { DashboardTemplate } from "./components/templates/DashboardTemplate"` |
| TabbedPageTemplate | 탭 페이지 | `import { TabbedPageTemplate } from "./components/templates/TabbedPageTemplate"` |

🔥 = 가장 많이 사용

## 📐 표준 페이지 구조

```tsx
<PageLayout>                        {/* 1. 전체 레이아웃 */}
  <PageHeader                       {/* 2. 헤더 (필수) */}
    icon={Archive}
    title="페이지 제목"
    subtitle="페이지 설명"
  />
  
  <div className="p-6">
    <StatCards stats={[...]} />     {/* 3. 통계 (선택) */}
    
    <SearchFilter                   {/* 4. 검색/필터 (선택) */}
      searchValue={search}
      onSearchChange={setSearch}
    />
    
    <DataTable                      {/* 5. 컨텐츠 (필수) */}
      columns={columns}
      data={data}
    />
  </div>
</PageLayout>
```

## 🚀 3분 안에 새 페이지 만들기

### Step 1: 템플릿 선택 (30초)
```tsx
import { ListPageTemplate } from "./templates/ListPageTemplate";
```

### Step 2: 데이터 정의 (1분)
```tsx
const stats = [
  { label: "항목1", value: "100", icon: Box },
  { label: "항목2", value: "200", icon: Package },
  { label: "항목3", value: "300", icon: Archive },
  { label: "항목4", value: "400", icon: Layers },
];

const columns = [
  { key: "id", label: "ID" },
  { key: "name", label: "이름" },
  { key: "status", label: "상태" },
];
```

### Step 3: 렌더링 (1분 30초)
```tsx
return (
  <ListPageTemplate
    title="새 페이지"
    icon={Database}
    stats={stats}
    columns={columns}
    data={data}
    searchValue={search}
    onSearchChange={setSearch}
  />
);
```

## 🎨 디자인 토큰 (globals.css)

### 색상 변경
```css
:root {
  --primary: #3B82F6;      /* 주요 색상 */
  --secondary: #F1F5F9;    /* 보조 색상 */
  --background: #FAFAFA;   /* 배경 */
  --destructive: #EF4444;  /* 삭제/경고 */
  --border: #E2E8F0;       /* 테두리 */
}
```

### 간격 변경
```css
:root {
  --radius: 0.75rem;       /* 모서리 둥글기 */
  --font-size: 16px;       /* 기본 폰트 크기 */
}
```

## 💡 자주 사용하는 코드 스니펫

### 페이지 헤더
```tsx
<PageHeader
  icon={Archive}
  title="페이지 제목"
  subtitle="페이지 설명"
  actions={<Button>액션</Button>}
/>
```

### 통계 카드
```tsx
<StatCards stats={[
  { label: "총 개수", value: "100", icon: Box, iconColor: "text-blue-600" },
  { label: "진행중", value: "50", icon: Clock, iconColor: "text-green-600" },
]} />
```

### 검색 필터
```tsx
<SearchFilter
  searchValue={search}
  onSearchChange={setSearch}
  searchPlaceholder="검색어 입력..."
  filters={[
    { type: "select", label: "필터", value: filter, onChange: setFilter }
  ]}
  actions={[
    { label: "+ 추가", onClick: handleAdd }
  ]}
/>
```

### 데이터 테이블
```tsx
<DataTable
  columns={[
    { key: "id", label: "ID" },
    { key: "name", label: "이름" },
    { key: "status", label: "상태", render: (v) => <StatusBadge status={v} /> },
  ]}
  data={data}
  onView={handleView}
  onEdit={handleEdit}
  onDelete={handleDelete}
/>
```

### 상태 배지
```tsx
<StatusBadge status="완료" />   {/* 초록색 */}
<StatusBadge status="진행중" /> {/* 파란색 */}
<StatusBadge status="대기" />   {/* 노란색 */}
<StatusBadge status="취소" />   {/* 빨간색 */}
```

### 폼 필드
```tsx
<FormField
  label="이름"
  value={name}
  onChange={setName}
  required
  error={errors.name}
/>

<FormField
  label="유형"
  type="select"
  value={type}
  onChange={setType}
  options={[
    { value: "type1", label: "유형1" },
    { value: "type2", label: "유형2" },
  ]}
/>
```

## 🔧 컴포넌트 Props 치트시트

### PageHeader
```tsx
interface PageHeaderProps {
  title: string;           // 필수
  description?: string;    // 부제목
  icon?: LucideIcon;       // 아이콘
  actions?: ReactNode;     // 액션 버튼
}
```

### StatCard
```tsx
interface StatCardProps {
  label: string;           // 레이블
  value: string | number;  // 값
  icon: LucideIcon;        // 아이콘
  iconColor?: string;      // 아이콘 색상
  trend?: {                // 추세 (선택)
    value: string;
    isPositive: boolean;
  };
}
```

### DataTable
```tsx
interface DataTableProps<T> {
  columns: Column<T>[];    // 컬럼 정의
  data: T[];              // 데이터
  onView?: (item: T) => void;
  onEdit?: (item: T) => void;
  onDelete?: (item: T) => void;
  pagination?: {           // 페이지네이션
    page: number;
    pageSize: number;
    total: number;
  };
}
```

### FormField
```tsx
interface FormFieldProps {
  label: string;           // 레이블
  value: string | number;  // 값
  onChange: (value: string) => void;
  type?: "text" | "number" | "email" | "select" | "textarea";
  required?: boolean;      // 필수 여부
  error?: string;          // 에러 메시지
  placeholder?: string;    // 플레이스홀더
  disabled?: boolean;      // 비활성화
  options?: Array<{        // select 옵션
    value: string;
    label: string;
  }>;
}
```

## ⚠️ 주의사항

### 수정 영향 범위
| 레벨 | 수정 시 영향 범위 | 테스트 필요 페이지 |
|------|------------------|-------------------|
| Atoms | 전체 시스템 | 5개 이상 |
| Molecules | 사용하는 페이지들 | 3개 이상 |
| Organisms | 사용하는 페이지들 | 2개 이상 |
| Templates | 해당 템플릿 페이지들 | 모든 사용 페이지 |

### 안전한 수정 방법
✅ 새 Variant 추가 (기존 유지)
✅ Optional Props 추가
✅ 하위 호환성 유지

❌ 기존 Variant 변경
❌ Required Props 추가
❌ Props 이름 변경

## 🔍 문제 해결

### Q: 컴포넌트가 안 보여요
```tsx
// ❌ 잘못된 import
import { PageHeader } from "./PageHeader";

// ✅ 올바른 import
import { PageHeader } from "./components/organisms/PageHeader";
```

### Q: 스타일이 안 먹혀요
```tsx
// ❌ inline style 사용
<Button style={{ color: 'red' }}>버튼</Button>

// ✅ variant 사용
<Button variant="destructive">버튼</Button>
```

### Q: 디자인 토큰을 어디서 바꾸나요?
```
/styles/globals.css 파일에서 변경
:root 섹션의 CSS 변수 값 수정
```

## 📚 더 알아보기

- 상세 가이드: `/DESIGN_SYSTEM_MANAGEMENT_GUIDE.md`
- 실전 예제: `/DESIGN_SYSTEM_EXAMPLE.md`
- 컴포넌트 계층: `/COMPONENT_HIERARCHY_REFERENCE.md`
- 아토믹 디자인: `/ATOMIC_DESIGN_SYSTEM.md`

## 💬 지원

- 디자인시스템 페이지에서 코드 예제 확인
- 복사 버튼으로 코드 빠르게 복사
- 팀에 문의하기

---

**마지막 업데이트**: 2025-10-31
**버전**: 1.0.0
