# 흔한 실수 (Common Mistakes)

AI 에이전트와 개발자가 PDS 사용 시 자주 하는 실수 패턴입니다. 코드 생성 전 이 문서를 확인하세요.

---

## 1. Deprecated 컴포넌트 사용

### VStack, HStack 사용 금지

VStack과 HStack은 deprecated입니다. Stack 컴포넌트의 `direction` prop을 사용하세요.

-   **문제**: `<VStack>`, `<HStack>` 사용
-   **해결**: `<Stack direction="column">`, `<Stack direction="row">` 사용
-   **참조**: Component/Stack/Stack 문서

### CheckboxGroup, RadioGroup의 gap prop

CheckboxGroup과 RadioGroup은 `gap` 대신 `spacing` prop을 사용합니다.

-   **문제**: `<CheckboxGroup gap={16}>`, `<RadioGroup gap={8}>`
-   **해결**: `<CheckboxGroup spacing={16}>`, `<RadioGroup spacing={8}>`
-   **참조**: Component/Control/CheckboxGroup, Component/Control/RadioGroup 문서

### Divider의 gap prop

Divider는 `gap` 대신 `spacing` prop을 사용합니다.

-   **문제**: `<Divider gap={40} />`
-   **해결**: `<Divider spacing={40} />`
-   **참조**: Component/Divider 문서

---

## 2. Props 네이밍 혼동

### Modal 열림 상태

다른 라이브러리의 패턴을 사용하지 마세요.

-   **잘못된 props**: `open`, `visible`, `isOpen`
-   **올바른 prop**: `opened`
-   **참조**: Component/Modal/BasicModal 문서

### Modal 닫기 이벤트

Modal은 `onCancel`을 사용합니다. `onClose`가 아닙니다.

-   **잘못된 props**: `onClose`
-   **올바른 prop**: `onCancel` (reason 파라미터 받음)
-   **주의**: Banner, Drawer는 `onClose` 사용 - 컴포넌트마다 다름!
-   **참조**: Component/Modal/BasicModal, Component/Banner 문서

### Button 스타일

Button은 `kind`를 사용합니다.

-   **잘못된 props**: `variant`, `type`, `color`
-   **올바른 prop**: `kind` ('primary', 'secondary', 'black', 'negative', 'outlined_*')
-   **참조**: Component/Button/Button 문서

### DataTable 데이터

DataTable은 `rows`를 사용합니다.

-   **잘못된 props**: `data`, `dataSource`
-   **올바른 prop**: `rows`
-   **참조**: Component/Table/DataTable 문서

### Stack 간격

Stack은 `gap`을 사용합니다.

-   **잘못된 props**: `spacing`, `gutter`
-   **올바른 prop**: `gap`
-   **주의**: VStack/HStack은 `spacing` 사용하지만 deprecated
-   **참조**: Component/Stack/Stack 문서

### Pagination props

Pagination은 고유한 prop 이름을 사용합니다.

-   **잘못된 props**: `page`, `current`, `total`, `count`, `onChange`
-   **올바른 props**: `currentPage`, `totalPages`, `onChangePage`
-   **참조**: Component/Pagination/Pagination 문서

### LineTabs 활성 탭

LineTabs는 `activeTabId`를 사용합니다.

-   **잘못된 props**: `value`, `activeKey`, `index`
-   **올바른 prop**: `activeTabId`
-   **참조**: Component/LineTabs 문서

---

## 3. Foundation 토큰 미사용

### 색상 하드코딩

색상값을 직접 사용하지 마세요. `semantic_colors` 토큰을 사용하세요.

-   **잘못된 패턴**: `color="#333333"`, `color="rgb(51, 51, 51)"`, `backgroundColor="#f5f5f5"`
-   **올바른 패턴**: `color={semantic_colors.content.primary}`, `backgroundColor={semantic_colors.background.secondary}`
-   **참조**: Foundation/SemanticColors 문서

### 간격 하드코딩

간격값을 직접 사용하지 마세요. `spacing` 토큰 또는 숫자를 사용하세요.

-   **잘못된 패턴**: `padding="24px"`, `margin="16px"`, `gap="8px"`
-   **올바른 패턴**: `p={24}`, `m={16}`, `gap={8}` 또는 `padding={spacing.spacing_6}`
-   **참조**: Foundation/Spacing 문서

### gap에 단위 없는 문자열 사용

`gap`에 단위 없는 문자열을 사용하면 CSS 오류가 발생합니다.

-   **잘못된 패턴**: `gap="16"` (단위 없는 문자열)
-   **올바른 패턴**: `gap={16}` (숫자) 또는 `gap="1rem"` (단위 포함 문자열)

---

## 4. 타 라이브러리 패턴 추측

### Material-UI 패턴

MUI 패턴을 PDS에 적용하지 마세요.

| Material-UI | PDS | |-------------|-----| | `<Modal open>` | `<Modal opened>` | | `<Button variant="contained">` | `<Button kind="primary">` | | `<Stack spacing={2}>` | `<Stack gap={16}>` | | `<Table data>` | `<DataTable rows>` |

### Ant Design 패턴

Ant Design 패턴을 PDS에 적용하지 마세요.

| Ant Design | PDS | |------------|-----| | `<Modal visible>` | `<Modal opened>` | | `<Button type="primary">` | `<Button kind="primary">` | | `<Table dataSource>` | `<DataTable rows>` | | `<Pagination current>` | `<Pagination currentPage>` |

### Chakra UI 패턴

Chakra UI 패턴을 PDS에 적용하지 마세요.

| Chakra UI | PDS | |-----------|-----| | `<Modal isOpen>` | `<Modal opened>` | | `<Button variant>` | `<Button kind>` | | `<Stack spacing>` | `<Stack gap>` | | `toast()` | `toast.show()` |

---

## 5. 컴포넌트 조합 실수

### FormField status 전파

FormField의 `status` prop은 일부 컴포넌트에만 자동 공유됩니다.

-   **자동 공유되는 컴포넌트**: Input, Dropdown
-   **자동 공유 안 되는 컴포넌트**: DatePicker, Textarea, NumericInput 등
-   **해결**: 지원되지 않는 컴포넌트는 `status` prop을 직접 전달
-   **참조**: Component/Form/FormField 문서

### DataTable 메모이제이션 누락

DataTable의 `columns`와 `rows`는 반드시 `useMemo`로 메모이제이션해야 합니다.

-   **문제**: 매 렌더링마다 새 객체 생성으로 인한 성능 저하
-   **해결**: `useMemo(() => [...], [dependencies])` 사용
-   **참조**: Component/Table/DataTable 문서

### Toast 직접 렌더링 시도

Toast는 컴포넌트로 직접 렌더링하지 않습니다.

-   **잘못된 패턴**: `<Toast message="..." />`
-   **올바른 패턴**: `const toast = useToast(); toast.show({ message: "..." });`
-   **참조**: Component/Toast 문서

---

## 6. 타입 정의 확인 누락

### 항상 타입 정의를 먼저 확인하세요

PDS 컴포넌트 사용 전 반드시 TypeScript 타입 정의를 확인하세요.

-   **확인 경로**: `node_modules/@croquiscom/pds/dist/components/{component}/*.d.ts`
-   **또는**: IDE의 타입 자동완성 기능 활용
-   **원칙**: 추측하지 말고 확인하세요

---

## 요약 체크리스트

코드 생성 전 다음을 확인하세요:

-   [ ] VStack/HStack 대신 Stack 사용
-   [ ] Modal은 `opened`, `onCancel` 사용
-   [ ] Button은 `kind` 사용
-   [ ] DataTable은 `rows` 사용, useMemo 적용
-   [ ] Stack은 `gap` 사용 (숫자 또는 단위 포함 문자열)
-   [ ] CheckboxGroup, RadioGroup, Divider는 `spacing` 사용
-   [ ] 색상은 `semantic_colors` 사용
-   [ ] 간격은 숫자 또는 `spacing` 토큰 사용
-   [ ] 타 라이브러리 패턴 적용 금지