# 흔한 실수 (Common Mistakes)

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

## 먼저 — 새 이름을 쓰세요

네이밍 전환 중이라 `@croquiscom/pds` 가 옛 이름과 새 이름을 둘 다 받습니다. **이 문서는 새 이름 기준**입니다. 옛 이름은 deprecated 이고 개발 모드에서 `[PDS deprecated]` 경고가 납니다. 아래 일부 항목의 「옛 이름」 줄은 헷갈리기 쉬운 것만 적은 예시이고, 전체 목록이 아닙니다. 기존 코드를 고칠 때는 지금 고치는 prop 만 새 이름으로 바꿔도 됩니다.

---

## 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**: `visible`, `isOpen`
-   **올바른 prop**: `open`
-   **옛 이름(deprecated)**: `opened`
-   **참조**: Component/Modal/BasicModal 문서

### Modal 닫기 이벤트

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

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

### Button 스타일

Button은 `variant`와 `color` 두 축을 사용합니다. 옛 `kind` 한 축이 둘로 갈라졌습니다.

-   **잘못된 패턴**: `type="primary"` (Ant Design 식) — `type` 은 `'button' | 'submit' | 'reset'` 만 받는 HTML 속성입니다
-   **올바른 prop**: `variant` ('filled', 'outlined') + `color` ('primary', 'secondary', 'emphasis', 'destructive')
-   **옛 이름(deprecated)**: `kind` 한 축입니다. 값이 둘로 갈라지므로 이름만 바꾸면 안 됩니다.

| 옛 `kind` | 새 `variant` | 새 `color` | | -------------------- | ------------ | ----------- | | `primary` | `filled` | `primary` | | `secondary` | `filled` | `secondary` | | `black` | `filled` | `emphasis` | | `negative` | `filled` | `destructive` | | `outlined_primary` | `outlined` | `primary` | | `outlined_secondary` | `outlined` | `secondary` | | `outlined_black` | `outlined` | `emphasis` | | `outlined_negative` | `outlined` | `destructive` |

-   **참조**: Component/Button/Button 문서

### DataTable 데이터

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

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

### Stack 간격

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

-   **잘못된 props**: `spacing`, `gutter`
-   **올바른 prop**: `gap`
-   **참조**: Component/Stack/Stack 문서

### Pagination props

Pagination은 표준 prop 이름을 사용합니다.

-   **잘못된 props**: `current`, `total`, `count`
-   **올바른 props**: `page`, `totalPages`, `onChange`
-   **옛 이름(deprecated)**: `currentPage`, `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 open>` (같습니다) | | `<Button variant="contained">` | `<Button variant="filled" color="primary">` | | `<Stack spacing={2}>` | `<Stack gap={16}>` | | `<Table data>` | `<DataTable rows>` |

### Ant Design 패턴

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

| Ant Design | PDS | |------------|-----| | `<Modal visible>` | `<Modal open>` | | `<Button type="primary">` | `<Button variant="filled" color="primary">` | | `<Table dataSource>` | `<DataTable rows>` | | `<Pagination current>` | `<Pagination page>` |

### Chakra UI 패턴

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

| Chakra UI | PDS | |-----------|-----| | `<Modal isOpen>` | `<Modal open>` | | `<Button variant>` | `<Button variant>` + `color` (값 체계가 다릅니다) | | `<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 content="..." />`
-   **올바른 패턴**: `const toast = useToast(); toast.show({ content: "..." });`
-   **참조**: Component/Toast 문서

---

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

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

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

-   **확인 경로**: `node_modules/@croquiscom/pds/dist/components/{component}/*.d.ts`
-   **또는**: IDE의 타입 자동완성 기능 활용
-   **원칙**: 추측하지 말고 확인하세요
-   **주의**: 위 경로는 **읽어서 확인하는 용도**입니다. `@croquiscom/pds/dist/...`를 import하지 마세요. 공개 진입점이 아니라 파일 배치가 바뀌면 깨지고, `moduleResolution`이 `bundler`·`node16`인 환경에서는 해석되지 않습니다. 타입도 공개 진입점에서 import합니다 — 전환 전이면 `@croquiscom/pds`, 전환한 경로면 `@croquiscom/pds/unstable-next`입니다. 두 진입점 다 각 컴포넌트의 타입을 그대로 내보냅니다.

---

## 요약 체크리스트

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

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