@x-plat/design-system 0.5.47 → 0.5.48

package/guidelines/AGENT_PROMPT.md

@@ -423,6 +423,88 @@ import { ChatInput } from "@x-plat/design-system/components";
 
 ---
 
+## 안전 가이드 — 자주 누락되는 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.47",
+  "version": "0.5.48",
   "description": "XPLAT UI Design System",
   "author": "XPLAT WOONG",
   "main": "dist/index.cjs",