@x-plat/design-system 0.4.6 → 0.5.1

package/guidelines/components/select.md

@@ -0,0 +1,44 @@
+# Select
+
+**Select.Item만 children으로 허용한다.**
+
+```tsx
+<Select placeholder="선택하세요" onChange={(value, label) => console.log(value)}>
+  <Select.Item value="apple">사과</Select.Item>
+  <Select.Item value="banana">바나나</Select.Item>
+</Select>
+```
+
+## onChange
+
+`onChange(value: string, label: string)` 형태로 선택된 값과 라벨을 전달한다.
+
+## Controlled / Uncontrolled
+
+```tsx
+// controlled
+<Select value={selected} onChange={(v) => setSelected(v)}>
+  <Select.Item value="a">A</Select.Item>
+</Select>
+
+// uncontrolled
+<Select defaultValue="a">
+  <Select.Item value="a">A</Select.Item>
+</Select>
+```
+
+## 상태
+
+| 상태 | 설명 |
+|------|------|
+| error | 에러 표시 |
+| disabled | 비활성화 |
+
+---
+
+## 유사 컴포넌트 구분
+
+| 목적 | 사용할 것 |
+|------|----------|
+| 값 선택 (onChange) | Select |
+| 액션 메뉴 (onClick per item) | Dropdown |

package/guidelines/components/swiper.md

@@ -0,0 +1,84 @@
+# Swiper
+
+슬라이더/캐러셀을 표시한다. 드래그, 자동 재생, 루프를 지원하며 controlled/uncontrolled 모두 가능하다.
+
+```tsx
+import { Swiper } from "@xplat/design-system";
+import type { SwiperHandle } from "@xplat/design-system";
+```
+
+## Props
+
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| renderItems | `ReactNode[]` | `[]` | 슬라이드 아이템 배열 |
+| viewItemCount | `number` | `1` | 한 번에 보이는 아이템 수 |
+| maxItems | `number` | — | 최대 아이템 수 (초과 시 잘림) |
+| spaceBetween | `number` | `16` | 슬라이드 간격 (px) |
+| speed | `number` | `300` | 전환 속도 (ms) |
+| slideBy | `number` | `1` | 한 번에 이동할 슬라이드 수 |
+| auto | `boolean` | `false` | 자동 슬라이딩 |
+| autoplayDelay | `number` | `3000` | 오토플레이 간격 (ms) |
+| loop | `boolean` | `false` | 무한 루프 |
+| showProgress | `boolean` | `false` | 진행바 표시 |
+| index | `number` | — | 현재 인덱스 (controlled) |
+| onChange | `(index: number) => void` | — | 슬라이드 변경 콜백 |
+| swiperRef | `RefObject<SwiperHandle>` | — | 명령형 제어 ref |
+
+### SwiperHandle
+
+| 메서드 | 설명 |
+|--------|------|
+| `slidePrev()` | 이전 슬라이드로 이동 |
+| `slideNext()` | 다음 슬라이드로 이동 |
+| `slideTo(index)` | 특정 인덱스로 이동 |
+
+---
+
+## 사용 예시
+
+### 기본
+
+```tsx
+<Swiper
+  renderItems={[
+    <img src="/img1.jpg" />,
+    <img src="/img2.jpg" />,
+    <img src="/img3.jpg" />,
+  ]}
+/>
+```
+
+### 자동 재생 + 루프 + 진행바
+
+```tsx
+<Swiper
+  renderItems={slides}
+  auto
+  loop
+  showProgress
+  autoplayDelay={5000}
+/>
+```
+
+### 명령형 제어
+
+```tsx
+const ref = useRef<SwiperHandle>(null);
+
+<Swiper swiperRef={ref} renderItems={slides} />
+
+<button onClick={() => ref.current?.slidePrev()}>이전</button>
+<button onClick={() => ref.current?.slideNext()}>다음</button>
+```
+
+### 다중 아이템 뷰
+
+```tsx
+<Swiper
+  renderItems={cards}
+  viewItemCount={3}
+  spaceBetween={24}
+  slideBy={3}
+/>
+```

package/guidelines/components/table.md

@@ -0,0 +1,62 @@
+# Table
+
+**반드시 `Table > TableHead/TableBody > TableRow > TableCell` 구조를 따른다.**
+
+```tsx
+<Table>
+  <TableHead>
+    <TableRow>
+      <TableCell>이름</TableCell>
+      <TableCell>나이</TableCell>
+    </TableRow>
+  </TableHead>
+  <TableBody>
+    <TableRow>
+      <TableCell>홍길동</TableCell>
+      <TableCell>30</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+## Props
+
+| Prop | 설명 |
+|------|------|
+| headerSticky | 헤더 고정 |
+| isSticky | 특정 셀 고정 |
+
+## TableRow type
+
+| type | 용도 |
+|------|------|
+| primary | 기본 행 |
+| secondary | 보조 행 (배경색 구분) |
+
+---
+
+## 올바른 예시
+
+```tsx
+<Table headerSticky>
+  <TableHead>
+    <TableRow>
+      <TableCell isSticky>이름</TableCell>
+      <TableCell>부서</TableCell>
+      <TableCell>직급</TableCell>
+    </TableRow>
+  </TableHead>
+  <TableBody>
+    <TableRow type="primary">
+      <TableCell isSticky>홍길동</TableCell>
+      <TableCell>개발팀</TableCell>
+      <TableCell>선임</TableCell>
+    </TableRow>
+    <TableRow type="secondary">
+      <TableCell isSticky>김철수</TableCell>
+      <TableCell>디자인팀</TableCell>
+      <TableCell>책임</TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```

package/guidelines/composition/grid.md

@@ -0,0 +1,95 @@
+# Grid 시스템
+
+페이지 레이아웃과 컴포넌트 내부 배치 모두 Grid를 사용한다.
+
+```tsx
+import { FullGrid, FullScreen, GridItem } from "@x-plat/design-system/layout";
+```
+
+## 컴포넌트
+
+| 컴포넌트 | 용도 |
+|---------|------|
+| FullGrid | 12컬럼 그리드 컨테이너 |
+| FullScreen | 전체 화면 그리드 |
+| GridItem | 그리드 아이템 |
+
+## gap
+
+```tsx
+<FullGrid gap={16}>
+  <GridItem column={6}>왼쪽</GridItem>
+  <GridItem column={6}>오른쪽</GridItem>
+</FullGrid>
+```
+
+---
+
+## 반응형 브레이크포인트
+
+| 브레이크포인트 | 범위 | 최대 컬럼 |
+|---------------|------|-----------|
+| laptop (default) | 1024px ~ | 12 |
+| tablet | 768px ~ 1024px | 8 |
+| mobile | ~ 768px | 4 |
+
+## Column 상속 규칙
+
+하위 브레이크포인트를 지정하지 않으면 상위 값을 상속한다.
+
+```tsx
+<GridItem column={{ default: 6, tablet: 4, mobile: 4 }}>
+  내용
+</GridItem>
+```
+
+---
+
+## 위젯 패턴
+
+### 대시보드
+
+```tsx
+<FullGrid>
+  <GridItem column={{ default: 4, tablet: 4, mobile: 4 }}>
+    <Card>위젯 A</Card>
+  </GridItem>
+  <GridItem column={{ default: 4, tablet: 4, mobile: 4 }}>
+    <Card>위젯 B</Card>
+  </GridItem>
+  <GridItem column={{ default: 4, tablet: 8, mobile: 4 }}>
+    <Card>위젯 C</Card>
+  </GridItem>
+</FullGrid>
+```
+
+### 폼
+
+```tsx
+<FullGrid>
+  <GridItem column={{ default: 6, tablet: 4, mobile: 4 }}>
+    <Input placeholder="이름" />
+  </GridItem>
+  <GridItem column={{ default: 6, tablet: 4, mobile: 4 }}>
+    <Input placeholder="이메일" type="email" />
+  </GridItem>
+  <GridItem column={{ default: 12, tablet: 8, mobile: 4 }}>
+    <Button type="primary">저장</Button>
+  </GridItem>
+</FullGrid>
+```
+
+### 중첩 Grid
+
+```tsx
+<Card title="사용자 정보">
+  <FullGrid>
+    <GridItem column={{ default: 3, tablet: 2, mobile: 4 }}>
+      <Avatar name="홍길동" size="lg" />
+    </GridItem>
+    <GridItem column={{ default: 9, tablet: 6, mobile: 4 }}>
+      <Input placeholder="이름" />
+    </GridItem>
+  </FullGrid>
+</Card>
+```

package/guidelines/composition/layout.md

@@ -0,0 +1,30 @@
+# Layout / Header / SideBar
+
+## 페이지 레이아웃 구조
+
+```tsx
+import { Layout, Header, SideBar } from "@x-plat/design-system/layout";
+```
+
+Layout은 Header와 SideBar를 포함하는 페이지 전체 구조를 제공한다.
+
+---
+
+## 예시
+
+```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>
+</Layout>
+```

package/guidelines/foundations/color.md

@@ -0,0 +1,81 @@
+# 컬러 토큰 시스템
+
+## 4레이어 구조
+
+| 레이어 | 접두사 | 역할 |
+|--------|--------|------|
+| Primitive | `--primitive-*` | 기초 팔레트 (hex) |
+| Brand | `--brand-*` | 브랜드 색상 |
+| System | `--system-*` | 상태 색상 (success/error/warning/info) |
+| Semantic | `--semantic-*` | 용도 기반 최종 토큰 (brand+system 참조) |
+
+컴포넌트는 **semantic 토큰만** 소비한다. primitive/brand/system을 직접 참조하지 않는다.
+
+---
+
+## Tailwind 클래스 사용 (소비 프로젝트)
+
+소비 프로젝트에서 직접 만드는 UI에만 사용한다.
+
+```tsx
+// 텍스트
+<p className="text-semantic-text-strong">강조 텍스트</p>
+<p className="text-semantic-text-subtle">보조 텍스트</p>
+<p className="text-semantic-text-error">에러 메시지</p>
+
+// 배경
+<div className="bg-semantic-surface-neutral-default">기본 배경</div>
+<div className="bg-semantic-surface-brand-subtle">브랜드 배경</div>
+
+// 테두리
+<div className="border border-semantic-border-default">기본 테두리</div>
+```
+
+---
+
+## Semantic 토큰 목록
+
+### Text
+
+`--semantic-text-{strong, subtle, muted, brand, disabled, inverse, success, error, warning, info, link, sunday, saturday}`
+
+### Surface
+
+- Neutral: `--semantic-surface-neutral-{subtle, default, strong}`
+- Brand: `--semantic-surface-brand-{subtle, default, strong}`
+- Success: `--semantic-surface-success-{subtle, default, strong}`
+- Error: `--semantic-surface-error-{subtle, default, strong}`
+- Warning: `--semantic-surface-warning-{subtle, default, strong}`
+- Info: `--semantic-surface-info-{subtle, default, strong}`
+
+### Border
+
+`--semantic-border-{default, strong, subtle, disabled, focus, error, success}`
+
+### Icon
+
+`--semantic-icon-{default, subtle, disabled, inverse, brand, success, warning, error, info}`
+
+### Emphasis
+
+`--semantic-emphasis-{brand, success, error, warning, info}`
+
+### Interaction
+
+`--semantic-interaction-{primary, primary-hover, primary-active, primary-disabled, secondary, secondary-hover, secondary-active, danger, danger-hover, danger-active}`
+
+### Categorical
+
+`--semantic-categorical-{1, 2, 3, 4, 5, 6, 7, 8}`
+
+---
+
+## 잘못된 사용
+
+```css
+/* 금지: primitive 토큰 직접 사용 */
+color: var(--primitive-blue-500);
+
+/* 올바른 방법: semantic 토큰 사용 */
+color: var(--semantic-text-brand);
+```

package/guidelines/foundations/icons.md

@@ -0,0 +1,55 @@
+# 아이콘 시스템
+
+## Import
+
+```tsx
+import { DeleteIcon, ChevronDownIcon, BellIcon } from "@x-plat/design-system";
+```
+
+## 크기/색상 제어
+
+부모의 `font-size`로 크기, `color`로 색상을 제어한다.
+
+```tsx
+<span style={{ fontSize: "1.5rem", color: "var(--semantic-icon-error)" }}>
+  <ErrorIcon />
+</span>
+```
+
+---
+
+## 카테고리별 용도
+
+| 카테고리 | 용도 | 예시 |
+|---------|------|------|
+| action | CRUD 액션 | DeleteIcon, SaveIcon, EditIcon, SearchIcon |
+| arrow | 방향/화살표 | ChevronDownIcon, ArrowLeftIcon |
+| status | 상태/검증 | CheckCircleIcon, ErrorIcon, XIcon, PlusIcon |
+| form | 폼 UI | EyeIcon, SettingsIcon, ToggleLeftIcon |
+| communication | 알림/메시지 | BellIcon, MessageCircleIcon |
+| commerce | 결제/배송 | ShoppingCartIcon, CreditCardIcon |
+| chart | 차트/통계 | BarChartIcon, TrendingUpIcon |
+| file | 파일/문서 | FileIcon, FolderIcon |
+| media | 미디어 | PlayIcon, CameraIcon, ImageIcon |
+| user | 사용자/인증 | UserIcon, LogOutIcon, LockIcon |
+| layout | 레이아웃/메뉴 | MenuIcon, GridIcon |
+| social | 소셜 | GithubIcon, FacebookIcon |
+| dev | 개발 | CodeIcon, TerminalIcon |
+| edit | 편집 | CopyIcon, ClipboardIcon |
+| date | 날짜 | CalendarIcon, ClockIcon |
+| call | 통화 | PhoneIcon, PhoneOffIcon |
+| device | 디바이스 | MonitorIcon, SmartphoneIcon |
+| weather | 날씨 | SunIcon, CloudIcon |
+| shape | 도형 | CircleIcon, SquareIcon |
+| misc | 기타 | HashIcon, LinkIcon |
+
+---
+
+## 아이콘 선택 의사결정
+
+| 상황 | 카테고리 |
+|------|---------|
+| CRUD 동작 (생성/조회/수정/삭제) | action |
+| 방향 표시, 펼침/접힘 | arrow |
+| 상태 피드백 (성공/에러/경고) | status |
+| 폼 입력 보조 | form |

package/guidelines/foundations/spacing.md

@@ -0,0 +1,51 @@
+# 스페이싱 토큰 시스템
+
+## 3레이어 구조
+
+| 레이어 | 역할 |
+|--------|------|
+| Primitive | 기초 수치 (4px 단위) |
+| Brand | 브랜드별 커스텀 |
+| Semantic | 컴포넌트가 소비하는 최종 토큰 |
+
+컴포넌트는 **semantic spacing만** 사용한다.
+
+---
+
+## Space
+
+| 토큰 | 값 |
+|------|-----|
+| `--spacing-space-none` | 0 |
+| `--spacing-space-1` ~ `--spacing-space-16` | 4px ~ 64px (4px 단위) |
+
+## Control Height
+
+| 토큰 | 용도 |
+|------|------|
+| `--spacing-control-height-xs` | 초소형 컨트롤 |
+| `--spacing-control-height-sm` | 소형 컨트롤 |
+| `--spacing-control-height-md` | 기본 컨트롤 |
+| `--spacing-control-height-lg` | 대형 컨트롤 |
+
+## Radius
+
+`--spacing-radius-{none, xs, sm, md, lg, xl, 2xl, full}`
+
+## Stroke
+
+`--spacing-stroke-{none, xs, sm, md, lg, xl, 2xl}`
+
+---
+
+## 잘못된 사용
+
+```css
+/* 금지: 하드코딩 */
+padding: 16px;
+gap: 8px;
+
+/* 올바른 방법: semantic 토큰 사용 */
+padding: var(--spacing-space-4);
+gap: var(--spacing-space-2);
+```

package/guidelines/foundations/typography.md

@@ -0,0 +1,63 @@
+# 타이포그래피 토큰 시스템
+
+## 3레이어 구조
+
+| 레이어 | 역할 |
+|--------|------|
+| Primitive | 기초 폰트 수치 |
+| Brand | 브랜드별 커스텀 |
+| Semantic | 컴포넌트가 소비하는 최종 토큰 |
+
+---
+
+## Font Family
+
+| 토큰 | 용도 |
+|------|------|
+| `--font-family-sans` | 기본 산세리프 |
+| `--font-family-serif` | 세리프 |
+| `--font-family-suit` | SUIT 폰트 |
+
+## Font Size
+
+`--font-size-{xs, sm, md, lg, xl, 2xl, 3xl, 4xl}`
+
+## Line Height (Density)
+
+3단계 밀도를 지원한다.
+
+| 밀도 | 용도 |
+|------|------|
+| compact | 정보 밀집 UI |
+| default | 기본 |
+| airy | 여유 있는 UI |
+
+## Font Weight
+
+| 토큰 | 값 |
+|------|-----|
+| `--font-weight-regular` | 400 |
+| `--font-weight-medium` | 500 |
+| `--font-weight-semibold` | 600 |
+| `--font-weight-bold` | 700 |
+
+## Letter Spacing
+
+| 토큰 | 용도 |
+|------|------|
+| `--letter-spacing-tight` | 좁은 자간 |
+| `--letter-spacing-normal` | 기본 자간 |
+| `--letter-spacing-wide` | 넓은 자간 |
+
+---
+
+## Semantic Text Styles
+
+| 스타일 | 용도 |
+|--------|------|
+| display | 대형 타이틀, 히어로 |
+| title | 페이지 타이틀 |
+| heading | 섹션 타이틀 |
+| body | 본문 텍스트 |
+| label | 폼 라벨, 버튼 텍스트 |
+| caption | 부가 설명, 힌트 |

package/guidelines/setup.md

@@ -0,0 +1,42 @@
+# 설치 및 설정
+
+## CSS Import
+
+앱 진입점에서 1회 import한다.
+
+```tsx
+import "@x-plat/design-system/style.css";
+```
+
+## 컴포넌트 Import
+
+```tsx
+// barrel import
+import { Button, Select, Modal } from "@x-plat/design-system/components";
+
+// deep import
+import { Button } from "@x-plat/design-system/components/Button";
+```
+
+## 레이아웃 Import
+
+```tsx
+import { Layout, Header, SideBar } from "@x-plat/design-system/layout";
+import { FullGrid, GridItem } from "@x-plat/design-system/layout";
+```
+
+## ToastProvider 설정
+
+앱 최상위에 ToastProvider를 배치한다.
+
+```tsx
+import { ToastProvider } from "@x-plat/design-system/components";
+
+function App() {
+  return (
+    <ToastProvider position="top-right">
+      <MyApp />
+    </ToastProvider>
+  );
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x-plat/design-system",
-  "version": "0.4.6",
+  "version": "0.5.1",
   "description": "XPLAT UI Design System",
   "author": "XPLAT WOONG",
   "main": "dist/index.cjs",
@@ -47,7 +47,9 @@
   },
   "files": [
     "dist",
-    "global.d.ts"
+    "global.d.ts",
+    ".npmrc",
+    "guidelines"
   ],
   "scripts": {
     "generate-grid": "tsx generate_grid.ts",
@@ -62,13 +64,11 @@
     "react-dom": ">=18"
   },
   "dependencies": {
+    "@x-plat/tokens-core": "*",
     "@x-plat/tokens-default": "*"
   },
   "devDependencies": {
-    "chart.js": "^4.5.1",
-    "chartjs-plugin-datalabels": "^2.2.0",
     "framer-motion": "^12.23.19",
-    "react-chartjs-2": "^5.3.1",
     "@types/node": "^24.10.1",
     "@types/react": "^19.1.13",
     "@types/react-dom": "^19.1.9",