@x-plat/design-system 0.5.46 → 0.5.48

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 값
 
 | 케이스 | 권장 값 |
@@ -338,6 +423,88 @@ DS 컴포넌트는 자체 외부 margin 없음. 부모가 gap 안 주면 모두
 
 ---
 
+## 안전 가이드 — 자주 누락되는 5가지
+
+UI 디자인 결정(레이아웃 폭, 색상 조합, 위계 등)은 **사용자 의도를 존중** 한다. 다만 아래 5가지는 빠지면 **레이아웃이 깨지거나 DS 가 오용되는 영역**이라 반드시 적용.
+
+### 1. 반응형 GridItem 누락 방지
+
+`GridItem` 의 `column` 은 default(laptop) 만 주면 **모바일에서 깨진다**. tablet(≤8) / mobile(≤4) 한계를 반드시 확인.
+
+```tsx
+// ❌ default 만 → mobile 에서 6/4 = 1.5 칸이 되어 잘림
+<GridItem column={{ default: 6 }}>...</GridItem>
+
+// ✅ 브레이크별 명시
+<GridItem column={{ default: 6, tablet: 4, mobile: 4 }}>...</GridItem>
+
+// ✅ 전체 폭이면 명시적으로 12/8/4
+<GridItem column={{ default: 12, tablet: 8, mobile: 4 }}>...</GridItem>
+```
+
+### 2. 컴포넌트 오용 방지 — 상황별 매칭
+
+비슷해 보이는 컴포넌트가 여러 개일 때 잘못 고르면 UX 가 망가진다.
+
+| 상황 | 사용할 컴포넌트 | 쓰지 말 것 |
+|---|---|---|
+| 짧은 알림(3-5초 후 사라짐) | `Toast` | Modal, Alert |
+| 인라인 경고/상태 메시지 | `Alert` | Modal |
+| 추가 설명 1-2줄 (hover) | `Tooltip` | PopOver |
+| 풍부한 부가 정보 + 액션 | `PopOver` | Modal, Tooltip |
+| 전용 작업 흐름 (작성/확인) | `Modal` | Drawer (전화면 시) |
+| 사이드 패널 (긴 흐름) | `Drawer` | Modal |
+| 단일 선택 (2-7개) | `Radio` | Select |
+| 단일 선택 (8개 이상) | `Select` | Radio |
+| 다중 선택 | `CheckBox` 리스트 또는 multi-`Select` | Radio |
+| boolean on/off | `Switch` | CheckBox |
+
+### 3. 상태 처리 3종 — Loading / Empty / Error
+
+데이터를 가져오는 곳(API/비동기)에는 반드시 3개 상태를 모두 처리.
+
+```tsx
+// ✅ 3개 상태 모두 처리
+if (loading) return <Skeleton />;        // 또는 <Spinner />
+if (error) return <Alert type="error">오류: {error.message}</Alert>;
+if (data.length === 0) return <EmptyState title="데이터가 없습니다" />;
+
+return <Table data={data} />;
+```
+
+데이터 무관 정적 화면이면 이 패턴 생략 가능.
+
+### 4. 접근성 기본 4개
+
+빠지면 시각/키보드 사용자가 못 씀.
+
+| 요소 | 필수 처리 |
+|---|---|
+| 이미지 (`<img>`) | `alt` 속성 (장식이면 `alt=""`) |
+| 아이콘 only 버튼 | `aria-label` (예: `<Button aria-label="삭제"><TrashIcon /></Button>`) |
+| Input / TextArea / Select 등 폼 | `label` prop |
+| Modal / Drawer 등 오버레이 | DS 가 처리하지만 닫기 버튼이 키보드로 접근 가능한지 확인 |
+
+### 5. 콘텐츠 안전
+
+```tsx
+// ❌ 자리 채우기 lorem ipsum
+<p>Lorem ipsum dolor sit amet...</p>
+
+// ❌ 한국어 컨텍스트에 영어 placeholder
+<Input placeholder="Enter your name" />
+
+// ✅ 의미 있는 / 한국어 placeholder
+<Input placeholder="이름을 입력하세요" />
+
+// ✅ 데이터가 없을 때 명시적 처리
+<EmptyState title="등록된 게시글이 없습니다" />
+```
+
+언어 일관성: 사용자가 한국어로 요청했으면 모든 UI 텍스트(label / placeholder / button / message)도 한국어.
+
+---
+
 ## 컴포넌트 사용 패턴
 
 ### ✅ 올바른 사용

package/package.json

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