@x-plat/design-system

XPLAT UI 디자인 시스템. React 컴포넌트, 레이아웃, 토큰 시스템 제공.

@x-plat/tokens-default 를 기본 브랜드로 사용하며, 다른 브랜드 토큰 패키지(cbio / daibee-ir / haetbitgil 등) 와 조합 가능.

요구 사항

| 항목 | 버전 | |------|------| | Node.js | 18+ | | React | 18+ |

설치

npm install @x-plat/design-system

사용법

1. 스타일 로드 (필수)

import "@x-plat/design-system/style.css";

style.css 는 컴포넌트 스타일 + tokens-default 의 토큰 값 을 함께 포함한다.

2. 컴포넌트 사용

import { Button, Modal, ToastProvider } from "@x-plat/design-system/components";

<ToastProvider position="top-right">
  <Layout
    header={<Header logo={<img src="/logo.svg" />} />}
    sideBar={<SideBar>...</SideBar>}
  >
    <FullGrid>
      <GridItem column={{ default: 6, tablet: 4, mobile: 4 }}>
        <Button type="primary">저장</Button>
      </GridItem>
    </FullGrid>
  </Layout>
</ToastProvider>

3. 다른 브랜드 적용 (cbio / haetbitgil / daibee-ir)

import "@x-plat/design-system/style.css";          // 1) 컴포넌트 + default 토큰
import "@x-plat/tokens-haetbitgil/tokens.css";     // 2) 햇빛길 토큰으로 override (CSS 카스케이드)

순서가 중요. design-system 을 먼저, 브랜드 토큰을 뒤에 import.

Import 패턴

| 방식 | 예시 | |------|------| | 루트 barrel | import { Button } from "@x-plat/design-system"; | | 서브패스 barrel | import { Button } from "@x-plat/design-system/components"; | | Deep import | import Button from "@x-plat/design-system/components/Button"; |

컴포넌트 목록

| 카테고리 | 컴포넌트 | |---|---| | 입력 | Button, Input, PasswordInput, TextArea, Select, CheckBox, Radio, Switch, DatePicker, Calendar, Editor | | 표시 | 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 | | Layout | Layout, Header, SideBar, FullGrid, FullScreen, GapGrid, GridItem |

AI 에이전트로 작업하기 (Figma Make / Claude / Cursor)

AI 에이전트 셋업용 종합 가이드:

https://unpkg.com/@x-plat/design-system/guidelines/AGENT_PROMPT.md

위 내용 전체를 복사해서 에이전트 컨텍스트에 붙여넣으면, 절대 규칙 / 레이아웃 / 컴포넌트 카탈로그 / 토큰 사용법 / 흔히 누락되는 케이스 등이 함께 적용된다.

핵심 규칙

1. 컴포넌트에 color / className / style prop 없음
2. 컴포넌트는 width: 100% → 반드시 GridItem 또는 wrapper 로 너비 제어
3. CSS 로 DS 컴포넌트 오버라이드 금지
4. 색상·간격·타이포는 semantic 토큰만 사용

가이드라인 문서

• guidelines/Guidelines.md — 전체 진입 + 읽기 순서
• guidelines/setup.md — 설치 + Layout / Toast / 브랜드 전환
• guidelines/AGENT_PROMPT.md — AI 에이전트 셋업 프롬프트
• guidelines/foundations/{color,spacing,typography,icons}.md
• guidelines/components/{name}.md — 컴포넌트별 가이드
• guidelines/composition/{grid,layout}.md

unpkg 로 접근:

https://unpkg.com/@x-plat/design-system/guidelines/{경로}

라이선스

Private. XPLAT WOONG.