@x-plat/design-system 0.5.0 → 0.5.2

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.5.0",
+  "version": "0.5.2",
   "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",