@x-plat/design-system 0.5.42 → 0.5.44

package/guidelines/AGENT_PROMPT.md

@@ -0,0 +1,248 @@
+# @x-plat/design-system — AI 에이전트 셋업 프롬프트
+
+## 사용법
+
+이 문서 **전체를 복사** 해서 Figma Make / Claude / Cursor 등 AI 코딩 에이전트의 컨텍스트(시스템 프롬프트 / 첫 메시지)에 **붙여넣어** 사용한다. 새 프로젝트 시작 시 1회만 셋업하면 된다.
+
+- 최신본 URL: `https://unpkg.com/@x-plat/design-system/guidelines/AGENT_PROMPT.md`
+- 라이브러리 버전 업데이트 후에는 위 URL 에서 다시 받아 갱신 권장.
+
+---
+
+## 에이전트가 따라야 할 지침
+
+프로젝트는 `@x-plat/design-system` 의 컴포넌트·레이아웃·토큰만으로 구성한다. 아래 규칙을 절대 어기지 않는다.
+
+---
+
+## 절대 규칙
+
+1. 컴포넌트에 `color` / `className` / `style` prop **없음**. 색상·스타일은 내부 semantic 토큰으로 고정됨.
+2. 컴포넌트는 `width: 100%` 로 부모를 채우므로 **반드시 GridItem 또는 wrapper 로 감싸서 너비를 제어**.
+3. **CSS 로 DS 컴포넌트를 오버라이드하지 않는다**.
+4. 색상·간격·타이포는 **semantic 토큰만** 사용. primitive / brand 직접 참조 금지.
+
+---
+
+## Import
+
+```tsx
+// 스타일 (앱 진입점에서 1회)
+import "@x-plat/design-system/style.css";
+
+// 컴포넌트
+import { Button, Modal, ToastProvider, useToast, ... } from "@x-plat/design-system/components";
+
+// 레이아웃
+import { Layout, Header, SideBar, FullGrid, FullScreen, GapGrid, GridItem } from "@x-plat/design-system/layout";
+```
+
+---
+
+## 앱 최상단 레이아웃 (필수 구조)
+
+컴포넌트가 이 구조에 맞게 설계되어 있어 **반드시 이 골격을 따른다**.
+
+### 중첩 순서
+
+```
+ToastProvider                  ← 가장 바깥 (useToast 컨텍스트 범위 확보)
+  └─ Layout                    ← 전체 레이아웃 래퍼
+       ├─ header (prop)        ← <Header /> 인스턴스를 prop 으로
+       ├─ sideBar (prop)       ← <SideBar /> 인스턴스를 prop 으로
+       └─ children             ← 메인 콘텐츠 (라우터 / 페이지)
+```
+
+### 코드 골격
+
+```tsx
+import { ToastProvider } from "@x-plat/design-system/components";
+import { Layout, Header, SideBar } from "@x-plat/design-system/layout";
+
+function App() {
+  return (
+    <ToastProvider position="top-right">
+      <Layout
+        header={
+          <Header
+            logo={<img src="/logo.svg" />}
+            centerContent={<NavTabs />}
+            rightContent={<UserMenu />}
+          />
+        }
+        sideBar={
+          <SideBar>
+            {/* 메뉴 children */}
+          </SideBar>
+        }
+      >
+        {/* 페이지 콘텐츠 — children */}
+        <Router />
+      </Layout>
+    </ToastProvider>
+  );
+}
+```
+
+### Layout 컴포넌트 API
+
+| Prop | 타입 | 설명 |
+|---|---|---|
+| `header` | `React.ReactElement<typeof Header>` (optional) | 상단 영역. `<Header/>` 인스턴스 |
+| `sideBar` | `React.ReactElement` (optional) | 좌측 사이드. `<SideBar/>` 인스턴스 |
+| `children` | `React.ReactNode` | 메인 콘텐츠 영역 |
+
+### Header 컴포넌트 API
+
+| Prop | 타입 |
+|---|---|
+| `logo` | `React.ReactNode` (좌측) |
+| `centerContent` | `React.ReactElement` (가운데) |
+| `rightContent` | `React.ReactElement` (우측) |
+
+❌ `<Header title="..." />` 같은 형태 **없음** — 위 3개 prop 만 받는다.
+
+### SideBar 컴포넌트 API
+
+| Prop | 타입 |
+|---|---|
+| `children` | 메뉴 항목들 |
+| `className` | (optional) wrapper className |
+
+내부에 `useState` 로 open/close 토글 상태 보유. 자식이 `useContext(SideBarContext)` 로 `isSidebarOpen`, `handleSwitchSideBar` 접근 가능.
+
+---
+
+## Grid 시스템
+
+페이지 콘텐츠는 Grid 위에서 배치한다.
+
+```tsx
+import { FullGrid, FullScreen, GapGrid, GridItem } from "@x-plat/design-system/layout";
+```
+
+### 컴포넌트
+
+| 컴포넌트 | 용도 |
+|---|---|
+| `FullGrid` | 12 컬럼 반응형 그리드 컨테이너 |
+| `FullScreen` | 전체 화면 그리드 |
+| `GapGrid` | gap 만 적용하는 그리드 |
+| `GridItem` | 그리드 아이템 (컬럼 span 지정) |
+
+### 브레이크포인트 (laptop / tablet / mobile)
+
+| 브레이크포인트 | min-width | 최대 컬럼 수 |
+|---|---|---|
+| `default` (laptop) | 1024px | 12 |
+| `tablet` | 768px | 8 |
+| `mobile` | 0px | 4 |
+
+### GridItem 사용
+
+```tsx
+<FullGrid gap={16}>
+  <GridItem column={{ default: 6, tablet: 4, mobile: 4 }}>
+    <Button type="primary">버튼</Button>
+  </GridItem>
+  <GridItem column={{ default: 6, tablet: 4, mobile: 4 }}>
+    <Input />
+  </GridItem>
+</FullGrid>
+```
+
+- `default`: laptop 이상에서 (1-12)
+- `tablet`: tablet 폭에서 (1-8)
+- `mobile`: mobile 폭에서 (1-4)
+- 상위만 지정해도 하위 자동 적용 (예: `{ default: 6 }` → 모든 브레이크 6 칸)
+
+---
+
+## 컴포넌트 사용 패턴
+
+### ✅ 올바른 사용
+
+```tsx
+<FullGrid>
+  <GridItem column={{ default: 6 }}>
+    <Button type="primary">저장</Button>
+  </GridItem>
+</FullGrid>
+```
+
+또는 단순 wrapper:
+
+```tsx
+<div style={{ width: 240 }}>
+  <Button type="primary">저장</Button>
+</div>
+```
+
+### ❌ 금지
+
+```tsx
+<Button color="blue" style={{ width: 200 }} className="my-btn">저장</Button>
+```
+
+이유: 컴포넌트가 `color/style/className` 을 받지 않고, 너비는 wrapper 에서 제어.
+
+---
+
+## 토큰 사용 (semantic 만)
+
+### 색상
+
+CSS 변수 `--semantic-{category}-{role}` 사용.
+
+| 카테고리 | 키 |
+|---|---|
+| `text` | strong / subtle / muted / brand / disabled / inverse / success / error / warning / info / link / sunday / saturday |
+| `surface` | neutral.{default/subtle/strong/overlay/disabled} / brand.{subtle/default/strong} / success/error/warning/info.{subtle/default/strong} |
+| `border` | default / subtle / strong / disabled / brand / success / error / warning / info |
+| `icon` | strong / subtle / inverse / brand / success / error / warning / info / disabled |
+| `emphasis` | brand / success / error / warning / info |
+| `interaction` | overlay-10 / overlay-25 / focus-ring |
+| `categorical` | 1-8 × {bg / area / fill / text} |
+
+예: `color: var(--semantic-text-strong)`, `background: var(--semantic-surface-brand-default)`
+
+### 스페이싱
+
+| 카테고리 | 키 |
+|---|---|
+| `space` | none / 1 ~ 16 |
+| `control-height` | xs / sm / md / lg |
+| `radius` | none / sm / md / lg / xl / full |
+| `stroke` | none / xs / sm / md / lg / xl / 2xl |
+
+예: `padding: var(--spacing-space-4)`, `border-radius: var(--spacing-radius-md)`
+
+### 타이포그래피 (Text Style 적용 권장)
+
+23 개 semantic 스타일: `display-1-b/sb`, `display-2-b/sb`, `title-1/2-sb/m`, `heading-1/2-sb/m`, `body-1/2-sb/m/r`, `label-1/2-sb/m`, `caption-1/2-sb/r`
+
+---
+
+## 컴포넌트 카탈로그
+
+| 카테고리 | 컴포넌트 |
+|---|---|
+| 입력 | `Button`, `Input`, `PasswordInput`, `TextArea`, `Select`, `CheckBox`, `Radio`, `Switch`, `DatePicker`, `Calendar` |
+| 표시 | `Table`, `Card`, `Tag`, `Chip`, `Avatar`, `Badge`, `Skeleton`, `Spinner`, `Divider`, `EmptyState`, `Progress` |
+| 오버레이 | `Modal`, `Drawer`, `PopOver`, `Tooltip`, `Alert`, `Toast` (`ToastProvider` 필요) |
+| 네비 | `Tab`, `CardTab`, `Breadcrumb`, `Pagination`, `Steps`, `Dropdown` |
+| 미디어 | `Video`, `FileUpload`, `ImageSelector`, `Swiper` |
+| 기타 | `Accordion`, `Chart`, `HtmlTypeWriter` |
+
+---
+
+## 추가 참조 (필요 시 fetch)
+
+unpkg 로 항상 최신 가이드 접근 가능:
+
+- 전체 가이드라인: `https://unpkg.com/@x-plat/design-system/guidelines/Guidelines.md`
+- 설치/설정: `https://unpkg.com/@x-plat/design-system/guidelines/setup.md`
+- 색상 토큰: `https://unpkg.com/@x-plat/design-system/guidelines/foundations/color.md`
+- 컴포넌트별 가이드: `https://unpkg.com/@x-plat/design-system/guidelines/components/{name}.md`
+- Layout 상세: `https://unpkg.com/@x-plat/design-system/guidelines/composition/layout.md`
+- Grid 상세: `https://unpkg.com/@x-plat/design-system/guidelines/composition/grid.md`

package/guidelines/Guidelines.md

@@ -4,6 +4,14 @@ React 기반 디자인 시스템 라이브러리이다. Figma Make Kit과 1:1
 
 ---
 
+## AI 에이전트로 작업할 때 (Figma Make / Claude / Cursor)
+
+새 프로젝트를 AI 에이전트로 시작할 때는 [AGENT_PROMPT.md](./AGENT_PROMPT.md) 전체를 복사해서 에이전트의 시스템 프롬프트 / 첫 메시지에 붙여넣는다. 에이전트가 본 가이드라인 규칙을 따르도록 만든다.
+
+- 최신본: `https://unpkg.com/@x-plat/design-system/guidelines/AGENT_PROMPT.md`
+
+---
+
 ## 핵심 규칙
 
 1. **컴포넌트에 `color`, `className`, `style` prop이 없다.** 색상과 스타일은 내부 semantic 토큰으로 고정한다.

package/guidelines/composition/layout.md

@@ -1,30 +1,101 @@
 # Layout / Header / SideBar
 
-## 페이지 레이아웃 구조
+페이지 전체 골격을 잡는 컴포넌트.
 
 ```tsx
 import { Layout, Header, SideBar } from "@x-plat/design-system/layout";
 ```
 
-Layout은 Header와 SideBar를 포함하는 페이지 전체 구조를 제공한다.
+---
+
+## API 요약
+
+### Layout
+
+| Prop | 타입 | 설명 |
+|---|---|---|
+| `header` | `React.ReactElement<typeof Header>` (optional) | 상단 헤더 영역. `<Header/>` 인스턴스 |
+| `sideBar` | `React.ReactElement` (optional) | 좌측 사이드바 영역. `<SideBar/>` 인스턴스 |
+| `children` | `React.ReactNode` | 메인 콘텐츠 영역 |
+
+> 주의: `Layout.Content` 같은 서브 컴포넌트는 **없다**. 메인 콘텐츠는 그냥 `children` 으로 직접 전달.
+
+### Header
+
+| Prop | 타입 |
+|---|---|
+| `logo` | `React.ReactNode` — 좌측 영역 |
+| `centerContent` | `React.ReactElement` — 가운데 영역 |
+| `rightContent` | `React.ReactElement` — 우측 영역 |
+
+> `title` prop 은 없다. 텍스트가 필요하면 `logo` 또는 `centerContent` 안에 직접 배치.
+
+### SideBar
+
+| Prop | 타입 |
+|---|---|
+| `children` | 메뉴 항목들 |
+| `className` | (optional) wrapper className |
+
+자체적으로 open/close 토글 상태를 관리. 자식이 `SideBarContext` 로 `isSidebarOpen`, `handleSwitchSideBar` 에 접근 가능.
 
 ---
 
-## 예시
+## 기본 골격
 
 ```tsx
-<Layout>
-  <Header title="대시보드" />
-  <SideBar>
-    <SideBar.Item>메뉴 1</SideBar.Item>
-    <SideBar.Item>메뉴 2</SideBar.Item>
-  </SideBar>
-  <Layout.Content>
-    <FullGrid>
-      <GridItem column={12}>
-        <p>페이지 내용</p>
-      </GridItem>
-    </FullGrid>
-  </Layout.Content>
+import { ToastProvider } from "@x-plat/design-system/components";
+import { Layout, Header, SideBar } from "@x-plat/design-system/layout";
+
+function App() {
+  return (
+    <ToastProvider position="top-right">
+      <Layout
+        header={
+          <Header
+            logo={<img src="/logo.svg" alt="logo" />}
+            centerContent={<NavTabs />}
+            rightContent={<UserMenu />}
+          />
+        }
+        sideBar={
+          <SideBar>
+            <Menu />
+          </SideBar>
+        }
+      >
+        {/* 페이지 콘텐츠 (라우터 등) */}
+        <Router />
+      </Layout>
+    </ToastProvider>
+  );
+}
+```
+
+권장 중첩 순서: `ToastProvider > Layout > (header / sideBar / children)`.
+
+자세한 ToastProvider 배치 이유는 [../setup.md](../setup.md#toastprovider-설정) 참고.
+
+---
+
+## 페이지 콘텐츠 구성
+
+`Layout` 의 `children` 안에서는 Grid 시스템으로 배치한다.
+
+```tsx
+<Layout header={...} sideBar={...}>
+  <FullGrid gap={16}>
+    <GridItem column={{ default: 12 }}>
+      <h1>대시보드</h1>
+    </GridItem>
+    <GridItem column={{ default: 8, tablet: 8, mobile: 4 }}>
+      <Card>본문</Card>
+    </GridItem>
+    <GridItem column={{ default: 4, tablet: 8, mobile: 4 }}>
+      <Card>사이드</Card>
+    </GridItem>
+  </FullGrid>
 </Layout>
 ```
+
+Grid 상세는 [./grid.md](./grid.md) 참고.

package/guidelines/setup.md

@@ -25,18 +25,27 @@ import { Layout, Header, SideBar } from "@x-plat/design-system/layout";
 import { FullGrid, GridItem } from "@x-plat/design-system/layout";
 ```
 
+> 페이지 최상단에 Layout/Header/SideBar/Layout.Content 를 배치하는 구조와 예시는 [composition/layout.md](./composition/layout.md) 참고.
+
 ## ToastProvider 설정
 
-앱 최상위에 ToastProvider를 배치한다.
+앱 최상위에 ToastProvider를 배치한다. **Layout 보다 바깥** 에 두어야 Header / SideBar / Layout.Content 안 어디서든 `useToast()` 훅을 호출할 수 있다.
 
 ```tsx
 import { ToastProvider } from "@x-plat/design-system/components";
+import { Layout, Header, SideBar } from "@x-plat/design-system/layout";
 
 function App() {
   return (
     <ToastProvider position="top-right">
-      <MyApp />
+      <Layout>
+        <Header title="..." />
+        <SideBar>...</SideBar>
+        <Layout.Content>{/* 라우터 */}</Layout.Content>
+      </Layout>
     </ToastProvider>
   );
 }
 ```
+
+권장 중첩 순서: `ToastProvider > Layout > (Header / SideBar / Layout.Content)`. ToastProvider 는 `createPortal` 로 `document.body` 에 렌더하므로 시각적 z-index 는 관계없지만, `useToast()` 의 컨텍스트 범위를 확보하려면 Layout 을 감싸야 한다.

package/package.json

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