@x-plat/design-system 0.5.46 → 0.5.47

package/guidelines/AGENT_PROMPT.md

@@ -300,6 +300,91 @@ DS 컴포넌트는 자체 외부 margin 없음. 부모가 gap 안 주면 모두
 </div>
 ```
 
+### 폼 요소 구조 — 중첩 금지
+
+**Input / TextArea / Select 안에 다른 컴포넌트를 넣지 않는다.** 레이아웃이 깨진다. 폼 요소는 항상 **형제(sibling)** 로 배치한다.
+
+#### ❌ 금지 — 폼 요소 중첩
+
+```tsx
+// Input 안에 Button → 잘못
+<Input>
+  <Button>검색</Button>
+</Input>
+
+// TextArea 안에 Button → 잘못
+<TextArea>
+  <Button>전송</Button>
+</TextArea>
+
+// Select 안에 Input → 잘못
+<Select>
+  <Input placeholder="검색" />
+</Select>
+
+// form 안에 form → 절대 금지
+<form>
+  <form>...</form>
+</form>
+```
+
+#### ✅ 올바른 패턴
+
+**Pattern 1: "입력 + 전송 버튼" 합성** → `ChatInput` 컴포넌트 사용
+```tsx
+import { ChatInput } from "@x-plat/design-system/components";
+
+<ChatInput
+  placeholder="메시지 입력"
+  onSubmit={(value) => handleSend(value)}
+/>
+```
+
+**Pattern 2: Input 우측 아이콘/소형 액션** → Input 의 `suffix` 슬롯 사용
+```tsx
+<Input
+  placeholder="검색"
+  suffix={<Icon name="search" />}
+/>
+```
+> `suffix` 는 작은 아이콘/버튼 1개용. 일반 `<Button>` 컴포넌트 넣지 말 것 (사이즈 충돌).
+
+**Pattern 3: 폼 요소 + 액션 버튼** → 형제 배치, wrapper 에서 gap
+```tsx
+<div style={{ display: "flex", gap: "var(--spacing-space-2)" }}>
+  <Input placeholder="이메일" />
+  <Button type="primary">확인</Button>
+</div>
+```
+
+**Pattern 4: 폼 요소들 묶음** → 모두 형제, 부모에서 gap
+```tsx
+<form style={{
+  display: "flex",
+  flexDirection: "column",
+  gap: "var(--spacing-space-4)",
+}}>
+  <Input label="이름" />
+  <TextArea label="자기소개" />
+  <Select label="국가" options={...} />
+  <Button type="primary">제출</Button>
+</form>
+```
+
+#### 폼 요소별 children/슬롯 정책
+
+| 컴포넌트 | children 받음? | 슬롯 |
+|---|---|---|
+| `Input` | ❌ | `suffix` (아이콘 1개) |
+| `TextArea` | ❌ | 없음 |
+| `Select` | ❌ | `options` prop 사용 (children 아님) |
+| `CheckBox` / `Radio` / `Switch` | ❌ | `label` prop |
+| `DatePicker` / `Calendar` | ❌ | controlled value/onChange |
+| `Button` | ✅ | 텍스트/아이콘만 |
+| `ChatInput` | ❌ | 입력+버튼 합성 컴포넌트 |
+
+> "입력 안에 무언가를 넣고 싶다" 는 욕구가 들면 → **다른 형태의 합성 컴포넌트가 있는지 먼저 확인**. 없으면 **wrapper + 형제** 패턴 사용.
+
 ### 케이스별 권장 spacing 값
 
 | 케이스 | 권장 값 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x-plat/design-system",
-  "version": "0.5.46",
+  "version": "0.5.47",
   "description": "XPLAT UI Design System",
   "author": "XPLAT WOONG",
   "main": "dist/index.cjs",