@x-plat/design-system 0.5.47 → 0.5.49

package/guidelines/AGENT_PROMPT.md

@@ -38,6 +38,26 @@ import { Button, Modal, ToastProvider, useToast, ... } from "@x-plat/design-syst
 import { Layout, Header, SideBar, FullGrid, FullScreen, GapGrid, GridItem } from "@x-plat/design-system/layout";
 ```
 
+### 브랜드 전환 (default 외 다른 브랜드 적용)
+
+design-system 은 빌드 시점에 tokens-default 를 임베드한다. 다른 브랜드를 쓰려면 **design-system 의 style.css 를 import 한 뒤** 브랜드 tokens.css 를 추가 import 한다 (CSS 카스케이드: 나중 선언이 이김).
+
+```tsx
+// ✅ 햇빛길 브랜드
+import "@x-plat/design-system/style.css";          // 1) 컴포넌트 스타일 + default 토큰
+import "@x-plat/tokens-haetbitgil/tokens.css";     // 2) 색상/타이포 override
+
+// ✅ CBIO 브랜드
+import "@x-plat/design-system/style.css";
+import "@x-plat/tokens-cbio/tokens.css";
+
+// ❌ 순서 반대 — design-system 이 default 로 다시 덮어버린다
+import "@x-plat/tokens-haetbitgil/tokens.css";
+import "@x-plat/design-system/style.css";  // 이게 마지막에 로드되어 default 적용
+```
+
+> 브랜드 토큰 단독 import 만으로는 작동 X — 컴포넌트 스타일이 빠진다. 반드시 design-system style.css 를 먼저 로드.
+
 ---
 
 ## 앱 최상단 레이아웃 (필수 구조)
@@ -423,6 +443,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/guidelines/setup.md

@@ -8,6 +8,34 @@
 import "@x-plat/design-system/style.css";
 ```
 
+> `style.css` 는 **컴포넌트 스타일 + tokens-default 의 토큰 값** 을 함께 포함한다. 다른 브랜드를 적용하려면 아래 "브랜드 전환" 섹션 참고.
+
+## 브랜드 전환 (cbio / haetbitgil / daibee-ir 등)
+
+design-system 은 tokens-default 를 기본으로 사용한다. 다른 브랜드 토큰을 적용하려면 **design-system 의 style.css 를 import 한 뒤** 해당 브랜드 토큰을 import 한다 (CSS 카스케이드: 나중 선언이 이김).
+
+```tsx
+// ✅ 햇빛길 브랜드 적용
+import "@x-plat/design-system/style.css";          // 1) 컴포넌트 스타일 + default 토큰
+import "@x-plat/tokens-haetbitgil/tokens.css";     // 2) 햇빛길 색상/타이포로 override
+```
+
+```tsx
+// ✅ CBIO 브랜드 적용
+import "@x-plat/design-system/style.css";
+import "@x-plat/tokens-cbio/tokens.css";
+```
+
+```tsx
+// ❌ 순서 반대 — design-system 이 다시 default 로 덮음
+import "@x-plat/tokens-haetbitgil/tokens.css";
+import "@x-plat/design-system/style.css";
+```
+
+**기본(default) 브랜드** 만 쓸 거면 design-system style.css 만 import 하면 된다.
+
+**브랜드 토큰만** import 하면 컴포넌트 스타일이 빠져서 동작하지 않는다 — 반드시 design-system 의 style.css 를 함께 로드.
+
 ## 컴포넌트 Import
 
 ```tsx

package/package.json

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